Repository navigation
0.1.8 Beta2: Record the runtime-derived tool compatibility architecture (ADR-0002) #350
Description
Parent
Outcome
Add docs/adr/0002-runtime-derived-tool-compatibility.md and record the architecture already approved for 0.1.8 Beta2.
Decisions to record
- The user selects the Provider and model. CodexHub resolves that choice to one immutable route binding containing endpoint, auth reference, upstream protocol, and exact model ID; compatibility handling never selects or changes the model.
- After route resolution, a request-scoped tool compatibility plan classifies each runtime declaration as
native,adapt,omit, orrequired-but-unavailable. - Native-compatible declarations and wire items pass through unchanged.
- An Adapter is used only for a reversible structural mismatch. Namespace aliases and custom/freeform envelopes must be injective, request-scoped, and invertible across calls, results, streaming, and history.
- Tool behavior is derived from the runtime declaration type and selected upstream protocol, not from a model-name allowlist.
- A hosted tool is exposed only when the selected Provider natively supports it. Otherwise it is omitted, or the request fails visibly when
tool_choicerequires it. - Explicit and implicit cross-Provider tool proxying are prohibited. CodexHub must not ask an OpenAI model or any second Provider to execute search, compaction, or another tool for the selected model.
- CodexHub adapts protocol shapes but does not execute tools, create agents, or become a second Collaboration scheduler. Collaboration V2 namespace adaptation may make declarations representable; the Codex client remains the agent owner and executor.
- Unknown custom endpoints use the same conservative type/protocol rules. Maintained Provider regressions are release evidence, not runtime eligibility or dispatch policy.
- Beta2 does not add alternate-codec retry or model-output format repair.
Acceptance criteria
- ADR-0002 uses the terms
ResolvedRoute(or the existing equivalent) andToolCompatibilityPlanwith non-overlapping responsibilities. - The four dispositions and their required/optional behavior are defined.
- The no-model-fallback and no-cross-Provider-proxy invariants are explicit.
- Native passthrough, necessary reversible adaptation, hosted omission, V1/V2 isolation, and side-effect boundaries are explicit.
- The ADR states that there is no runtime model qualification gate and no GLM/K2.7-specific production branch.
- Superseded alternatives and the Beta2 non-goals are recorded.
Scope guard
Documentation and architecture contract only. Product implementation remains #58; runtime inventory and the compatibility table remain #62 and #65.
Activity
NOirBRight commentedon Aug 4, 2026
{ "contract": { "acceptance": [ "ADR-0002 exists and uses ResolvedRoute (or the current equivalent) and ToolCompatibilityPlan with non-overlapping responsibilities.", "All four dispositions have deterministic optional/required behavior and precise inverse/stream/history boundaries.", "The ADR explicitly forbids model/provider fallback, cross-Provider tool execution, Gateway-owned execution/scheduling, model-name dispatch, and Beta2 format-repair retries.", "The ADR records superseded alternatives and the boundary to #62, #64, #65, #198, and #58 without adding product implementation." ], "change_claims": { "paths": [ "docs/adr/0002-runtime-derived-tool-compatibility.md" ], "resources": [ "adr:0002-runtime-derived-tool-compatibility" ] }, "dependencies": { "dispatch_after": [], "merge_after": [] }, "design": [ "Create docs/adr/0002-runtime-derived-tool-compatibility.md as the Beta2 architecture contract using the already-approved product decisions; keep this ticket documentation-only.", "Define the non-overlapping ResolvedRoute and ToolCompatibilityPlan seams, and classify runtime declarations as native, adapt, omit, or required-but-unavailable.", "Document exact-model identity, no fallback, no cross-Provider proxy, native passthrough, only reversible request-scoped adapters, hosted-tool omission/failure, V1/V2 isolation, and Gateway side-effect boundaries.", "Record unknown-endpoint behavior, no model-name allowlist/qualification gate, no GLM/K2.7 production branch, and the rejected Beta2 alternatives (alternate-codec retry and output repair)." ], "difficulty": "light", "done_when": [ "git diff --check", "The ADR acceptance checklist is self-reviewed against Issue #350 and the resulting commit is pushed in a PR referencing #350." ], "priority": "P1", "risk": "low", "sha256": "38fe19ddf6c9de3cd78e1ae20ed7b2aa3ab1869130bef347a11c81907ddbb727", "unresolved_decisions": [] }, "dispatch": null }docs: record runtime-derived tool compatibility ADR
NOirBRight commentedon Aug 4, 2026
Beta2 campaign update: PR #353 was squash-merged into
devas7c792a057961d7e1fd6de61919be6eafb4e1967fafter final headbbbe4a9bff322e05a2db8e999c0730408814fcb6received Spec + Standards/Quality PASS and post-review HostedCI / gatePASS (run30889655050). #350 is complete; runtime implementation remains owned by #58.