Joseph Magly
afc9dad1b2
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
4.2 KiB
4.2 KiB
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
- The user selects a provider family and model or a connected agent.
- Configuration resolves the provider, base URL, credential source, and capability metadata.
- The adapter validates required settings without exposing secret values.
- The orchestration layer submits a bounded reasoning request through the shared interface.
- The adapter translates the request and returns normalized content and tool proposals.
- The runtime treats the response as untrusted input and applies shared tool, target, and evidence controls.
- 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.