t3mp3st/.aiwg/architecture/adr-002.md

ADR-002 — Keep the Reasoning Backbone Provider-Neutral

Metadata

• ADR ID: ADR-002
• Status: Accepted (retrospective baseline)
• Decision date: 2026-07-20
• Authors: Architecture baseline process
• Reviewers: Maintainer, integration, and safety-review roles; named human approval is not recorded
• Supersedes: None
• Current level: L3 — Accepted; multiple adapter paths are implemented

Context

Problem

Operators may use hosted model APIs, local OpenAI-compatible servers, or already-authenticated coding-agent CLIs. These providers differ in authentication, model names, base URLs, timeouts, tool-calling formats, and failure behavior. Binding mission orchestration to one provider would weaken local/keyless operation and make provider output an accidental trust boundary.

Constraints

• No single provider exposes a stable universal capability contract.
• Local agent and local inference paths must remain viable without new cloud credentials.
• Provider responses are nondeterministic and may include unsafe tool proposals.
• Provider-specific behavior must remain observable rather than erased by a lowest-common-denominator abstraction.
• Secrets must not cross provider/base-URL boundaries or appear in diagnostics.

Stakeholders

• Operators need provider choice and fallback clarity.
• Integrators need a stable common interface with explicit capability differences.
• Safety reviewers need deterministic controls below model output.
• Maintainers need provider-specific tests without duplicating mission logic.

Source Verification and Claim Tracking

Claim	Source	Verification
Hosted, local OpenAI-compatible, and connected-agent paths exist	Configuration, LLM, and local-agent modules	Direct code and provider test inspection
Provider/model compatibility is registry-driven	Provider/model registry	Registry tests
Local-agent tool proposals use shared runtime controls	Local-agent and arsenal integration	Tool-calling and approval/scope tests

Decision

Resolve provider/model differences behind shared configuration and LLM/agent adapter contracts. Preserve provider capability metadata and explicit routing/fallback behavior. Treat all provider output as untrusted proposals: target authorization, scope, dangerous-action approval, argument validation, evidence, and reporting policy remain in T3MP3ST.

Provider-specific adapters may expose additional capability only through declared contract extensions and tests. A fallback must be configured, bounded, and recorded; silent provider switching is not acceptable for evidence-bearing work.

Alternatives Considered

Standardize on one hosted provider

• Pros: Smaller adapter/test matrix and simpler support.
• Cons: Vendor dependency, credential requirement, weaker local operation, and provider outage concentration.
• Why not chosen: Conflicts with the existing product promise and implemented local-agent/provider diversity.

Let each workflow call providers directly

• Pros: Maximum provider-specific freedom.
• Cons: Duplicated authentication, retry, timeout, secret, and response logic; safety behavior drifts by workflow.
• Why not chosen: Makes provider behavior inseparable from domain and safety logic.

Normalize every provider to the lowest common feature set

• Pros: Superficially uniform orchestration.
• Cons: Hides meaningful capability and error differences and can misroute tool behavior.
• Why not chosen: The common contract must normalize transport, not erase capabilities.

Consequences

Positive

• Users retain hosted, local, and connected-agent choices.
• Mission/orchestration code depends on stable internal contracts.
• Safety controls remain provider-independent.

Negative

• Compatibility, fallback, timeout, and secret-routing test matrices grow with every provider.
• Provider-specific capabilities require explicit extension and documentation.
• Similar-looking model names or base URLs can still create configuration hazards.

Risks and Mitigations

Risk	Likelihood / impact	Mitigation
Credential sent to wrong endpoint	Low / Critical	Explicit provider/base-URL routing, environment/static tests, redaction
Silent fallback changes evidence identity	Medium / High	Record primary/fallback outcomes and model/provider identity
Adapter reports malformed output as success	Medium / High	Schema/response validation and explicit error feedback
Lowest-common-denominator abstraction hides capability	Medium / Medium	Capability registry and provider-specific contract tests

Implementation and Verification

• Configuration: src/config/ resolves provider, model, base URL, secret source, and defaults.
• Hosted/local interface: src/llm/index.ts normalizes reasoning requests and responses.
• Connected agents: src/agent/local-agents.ts discovers and invokes supported authenticated agent CLIs.
• Concurrency/state: Requests are bounded tasks; no provider response becomes shared durable state until mission/evidence code records it.
• Testing: Provider-model registry, provider-specific adapters, base-URL routing, local-agent selection/path/tool-calling, timeout/fallback, and redaction.
• Regression guard: A new provider is incomplete until configuration, capability metadata, error/timeout, secret, and tool-proposal behavior are tested.

Definition of Done

• Provider-neutral contract and trust boundary documented.
• Hosted, local inference, and connected-agent implementations identified.
• Alternatives and security risks recorded.
• Named maintainer/integration approval is recorded.
• Evidence receipts consistently capture provider/model/fallback identity across all benchmark paths.

References

• @.aiwg/requirements/UC-002.md — Provider and local-agent use case.
• @.aiwg/requirements/nfr-register.md — Secret, portability, compatibility, testability, and timeout constraints.
• @.aiwg/architecture/software-architecture-doc.md — Provider adapter and trust-boundary views.
• @src/config/index.ts — Runtime configuration.
• @src/config/provider-models.ts — Provider/model capability registry.
• @src/llm/index.ts — LLM adapter interface.
• @src/agent/local-agents.ts — Connected-agent adapter.
• @src/tests/provider-models.test.ts — Compatibility registry evidence.
• @src/tests/provider-base-url-routing-static.test.ts — Endpoint-routing evidence.
• @src/tests/local-agent-tool-calling.test.ts — Tool-proposal integration evidence.
• @scripts/test-model-fallback.mjs — Fallback behavior evidence.

Review and Approval

This is a retrospective description of implemented adapter policy. “Accepted” means it governs the current baseline; it does not fabricate historical approval. Future provider additions or contract changes require maintainer/integration review and an updated evidence matrix.