Joseph Magly
afc9dad1b2
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
81 lines
4.2 KiB
Markdown
81 lines
4.2 KiB
Markdown
# UC-002 — Connect a Model or Coding Agent
|
|
|
|
## Metadata
|
|
|
|
- **ID:** UC-002
|
|
- **Status:** Baselined (brownfield)
|
|
- **Level:** User goal
|
|
- **Scope:** Configuration, provider/model registry, LLM adapters, and connected local agents
|
|
- **Primary actor:** Operator or integrator
|
|
- **Goal:** Use a hosted provider, local OpenAI-compatible model, or authenticated coding-agent CLI as the reasoning backbone.
|
|
- **Related story:** US-03
|
|
- **Quality drivers:** NFR-05, NFR-06, NFR-07, NFR-08, NFR-11
|
|
|
|
## Preconditions
|
|
|
|
- At least one supported provider, local inference endpoint, or local agent executable is available.
|
|
- Any required credential is supplied through the supported configuration mechanism.
|
|
- UC-001 remains authoritative for tool execution and target safety.
|
|
|
|
## Trigger
|
|
|
|
The user selects a provider/model or connected local agent during setup or mission execution.
|
|
|
|
## Main Success Scenario
|
|
|
|
1. The user selects a provider family and model or a connected agent.
|
|
2. Configuration resolves the provider, base URL, credential source, and capability metadata.
|
|
3. The adapter validates required settings without exposing secret values.
|
|
4. The orchestration layer submits a bounded reasoning request through the shared interface.
|
|
5. The adapter translates the request and returns normalized content and tool proposals.
|
|
6. The runtime treats the response as untrusted input and applies shared tool, target, and evidence controls.
|
|
7. The mission records the selected reasoning path and its outcome.
|
|
|
|
## Alternate Flows
|
|
|
|
- **A1 — Connected local agent:** Resolve the executable and working environment; no new cloud API key is required.
|
|
- **A2 — Local OpenAI-compatible endpoint:** Route to the configured base URL while applying local-address handling and timeouts.
|
|
- **A3 — Declared fallback:** If the primary path fails in a configured, recoverable manner, use the declared fallback and record both outcomes.
|
|
|
|
## Exception Flows
|
|
|
|
- Missing credentials or executable: fail configuration validation with a redacted, actionable error.
|
|
- Unsupported provider/model combination: reject before a mission request is submitted.
|
|
- Timeout or malformed response: record failure and do not reinterpret incomplete output as a valid tool instruction.
|
|
- Provider attempts a privileged action: route the proposal through the same approval and scope gates as every other provider.
|
|
|
|
## Postconditions
|
|
|
|
- The reasoning path and result are explicit in mission state or diagnostics.
|
|
- Credentials remain isolated to configuration/provider boundaries.
|
|
- Provider choice does not bypass deterministic execution controls.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] A connected local agent can perform mission planning without a newly supplied cloud API key.
|
|
- [ ] Provider selection resolves only supported provider/model combinations.
|
|
- [ ] Local and hosted base URLs route to their intended adapter without credential crossover.
|
|
- [ ] Timeouts produce an explicit error or declared fallback outcome.
|
|
- [ ] Model-generated tool proposals still require UC-001 scope and approval enforcement.
|
|
- [ ] Configuration and error output redact provider secrets.
|
|
|
|
## Design and Test Traceability
|
|
|
|
| Concern | Design / implementation | Verification |
|
|
| --- | --- | --- |
|
|
| Provider/model selection | `src/config/`, `src/config/provider-models.ts` | Provider-model and provider-specific tests |
|
|
| Common reasoning interface | `src/llm/index.ts`, `src/agent/` | Local-agent selection, path, tool-calling, and fallback tests |
|
|
| Bounded execution | Orchestration and configuration timeout controls | Model-fallback and agent-error tests |
|
|
|
|
## References
|
|
|
|
- @.aiwg/architecture/adr-002.md — Provider-neutral reasoning decision.
|
|
- @.aiwg/architecture/software-architecture-doc.md — Provider adapter and trust-boundary design.
|
|
- @src/config/index.ts — Runtime configuration behavior.
|
|
- @src/config/provider-models.ts — Provider/model capability registry.
|
|
- @src/llm/index.ts — Shared hosted/local LLM interface.
|
|
- @src/agent/local-agents.ts — Connected local-agent resolution.
|
|
- @src/__tests__/local-agent-selection.test.ts — Local-agent selection evidence.
|
|
- @src/__tests__/provider-models.test.ts — Registry and compatibility evidence.
|
|
- @scripts/test-model-fallback.mjs — Declared fallback verification.
|