Repository navigation
0.1.8 Beta2: Implement runtime-derived tool compatibility for custom Responses endpoints #58
Description
Parent
Outcome
Implement one runtime-derived tool compatibility layer for user-selected custom Responses endpoints.
The Provider/model is already chosen by the user and resolved to an exact immutable route. This issue decides only how the installed Codex runtime's tool declarations and wire lifecycle are represented on that same route.
Required behavior
- Build a request-scoped immutable compatibility plan from:
- the runtime-provided tool plan;
- the selected upstream protocol's representational capabilities;
- request requirements such as
tool_choice.
- Classify every declaration as
native,adapt,omit, orrequired-but-unavailableaccording to 0.1.8 Beta2: Define tool-type compatibility rules for custom Responses endpoints #65. - Preserve native-compatible declarations and items unchanged.
- Add only the reversible Adapters required by incompatible shapes, including where applicable:
- collision-free request-scoped namespace aliases;
- reversible custom/freeform envelopes;
- client-executed tool-discovery encoding;
- response added/delta/done assembly before final validation;
- inverse call/result/history mapping with exact IDs and order.
- Apply 0.1.8 Beta2: Isolate V1 repair from V2 namespace adaptation #198 so V1 repair cannot touch V2.
- Expose hosted tools only when the selected Provider natively supports them. Otherwise omit optional hosted tools or fail visibly when required.
- Keep the exact selected Provider/model for the entire request. No alias, fallback, retry, or compatibility branch may select Terra, Luna, OpenAI, or another Provider/model.
- Emit only bounded classification/count diagnostics; never log prompts, reasoning, tool arguments/results, credentials, call IDs, or task paths.
Architecture constraints
- No production Adapter selection by GLM/K2.7/model name.
- Existing Provider entries may describe endpoint, auth, protocol, and real hosted capability facts, but must not choose a model-specific tool codec.
- CodexHub adapts protocol structures; it does not execute tools, create agents, schedule subagents, or fabricate results.
- Tool execution behavior follows the declaration type and the selected Provider's real capabilities.
- Unknown custom endpoints use the same conservative rules and are not blocked by absence from a model matrix.
- Beta2 adds no alternate-codec retry and no model-output format-repair attempt.
- Explicit and implicit cross-Provider tool proxying are prohibited.
Acceptance criteria
- Tests cover all four dispositions for each relevant 0.1.8 Beta2: Inventory Codex CLI 0.146 tool types and representative Responses lifecycles #62 structural family.
- Already compatible function/namespace/custom items remain semantically unchanged.
- Every Adapter is injective and reversible across declaration, call, result, streaming, and replay history.
- Alias collisions, length limits, unknown aliases, malformed deltas, missing/duplicate IDs, and ambiguous inverse mapping fail safely.
- Optional unsupported hosted tools are absent from the model-visible plan with a bounded diagnostic.
- A required unavailable hosted or non-representable tool fails before upstream sampling.
- Network assertions prove no tool request reaches a second Provider.
- Exact provider/model identity survives Direct -> Gateway -> Direct, reconnect, and permitted retry boundaries.
- Official transparent behavior and all Beta1 regressions remain unchanged.
- Production routing/codec tests prove that changing only a model slug does not select a different compatibility algorithm.
Verification
Verification class: strict.
- Focused Python routing, protocol translation, semantic adapter, Collaboration isolation, SSE, and history tests.
- Full affected Python suite.
- Real Codex CLI smoke against a configured custom endpoint after exact-SHA review.
- local verification gate only after review and CLI/manual verification are accepted.
Blocked by
- 0.1.8 Beta2: Isolate V1 repair from V2 namespace adaptation #198
- 0.1.8 Beta2: Approve the custom-endpoint tool compatibility contract #249
#61, #273, #274, and #327 are closed foundations whose invariants remain mandatory.
Activity
NOirBRight commentedon Jul 11, 2026
Planning update (2026-07-11): GitHub now records #57 as a native blocking dependency. This issue is on the Capability-driven routing rollout milestone. Target implementation window is Aug 3–7, after #67 records the scoped #57 maintainer decision. Only approved provider/model/protocol/capability scopes may enter the native fast path.
39 remaining items
NOirBRight commentedon Aug 4, 2026
Orchestrator dispatch status (2026-08-04)
Campaign:
campaign:0.1.8-beta2.Dispatch is held by #198 and #249. One Luna Max worker will implement the runtime-derived generic compatibility path only after both inputs are accepted. The selected Provider/model identity remains immutable; native tools stay native, adapters are reversible and request-local, optional unavailable tools are omitted, and required unavailable tools fail before sampling.
NOirBRight commentedon Aug 5, 2026
{ "contract": { "acceptance": [ "Every Issue 62 structural family resolves deterministically to one of native, adapt, omit, or required-but-unavailable according to the merged Issue 65 table.", "Native-compatible function, namespace, custom/freeform, tool_search, hosted, call/result, SSE, and history shapes remain semantically unchanged with exact identities and order.", "Namespace and custom/freeform Adapters are request-scoped, collision-free, injective, and reversible across declaration, call, result, streaming, and replay history; malformed or ambiguous inverses fail visibly and safely.", "Optional unsupported hosted, client-executed, namespace, custom/freeform, plain-function, and unknown declarations are absent from the model-visible plan with bounded sanitized classification diagnostics.", "A required unavailable hosted or non-representable declaration fails before any upstream sampling with a stable bounded error and without fallback, proxying, retrying another codec, or output repair.", "Collaboration V1/V2 is selected before compatibility planning; V2 never receives V1 injection, repair, state, scheduler, close/resume, or result parsing, and neither lifecycle is downgraded or reinterpreted.", "The exact user-selected Provider/model and protocol remain immutable across request planning, Direct to Gateway to Direct, reconnect, and permitted same-route transport retries; changing only a model slug never changes the compatibility algorithm.", "Network-level deterministic tests prove no tool request reaches a second Provider and the Gateway never executes tools, creates agents, schedules work, or fabricates tool results.", "Official transparent behavior, existing V1 behavior, Issue 198 isolation, and Beta1 routing, identity, catalog, continuation, and context-window regressions remain unchanged.", "Diagnostics contain only bounded counts/classifications and contain none of the prohibited request, tool, credential, identity, alias, continuation, or task-path values.", "The Worker publishes one Draft PR at an exact candidate SHA; exact-head strict review is required before any CLI/manual or local candidate verification, and no merge or Beta2 tag/release is performed." ], "change_claims": { "paths": [ "src-python", "tests" ], "resources": [ "runtime-tool-compatibility-plan", "responses-tool-wire-lifecycle", "request-scoped-tool-alias-registry", "collaboration-v1-v2-boundary", "selected-route-identity", "bounded-compatibility-diagnostics" ] }, "dependencies": { "dispatch_after": [ 65, 198, 249 ], "merge_after": [ 65, 198, 249 ] }, "design": [ "Use exact dev lineage a9440e648be4cd6713d50e182ebd5fb1affbc4b1, accepted ADR-0002, merged Issue 65 candidate c92441e770cebaa06019d2cf56ef3cddc926f69b, Issue 198 isolation, and maintainer GO comment 5189685427 as the complete product contract.", "Implement an immutable request-scoped ToolCompatibilityPlan after exact Provider/model route resolution and before upstream request encoding; inputs are runtime declaration structure, selected protocol representational capabilities, selected Provider hosted capability facts, and whether the request requires each declaration.", "Classify plain function, namespace including pre-classified Collaboration V1/V2, custom/freeform, client-executed tool_search, Provider-hosted, and unknown/future declaration families to exactly native, adapt, omit, or required-but-unavailable using the Issue 65 table; leave no implicit fallback outcome.", "Pass native-compatible declarations, tool choice, calls, results, IDs, streaming events, and replay/history through semantically unchanged; do not wrap or normalize a native lifecycle.", "Adapt only a proven structural mismatch: use one collision-free request-local namespace alias registry for namespace children when the selected protocol has a complete function lifecycle, and the exact __codexhub_custom_input/__codexhub_custom_output envelope for custom/freeform when its complete inverse is representable; reverse lookups use the registry, never alias parsing.", "Keep every Adapter injective and reversible across declarations, calls, client results, added/delta/done streaming assembly, and replay/history while preserving original names, namespace/version, continuation fields, exact call/item IDs, result links, and order; classify an unprovable optional mapping as omit and a required one as required-but-unavailable before sampling.", "Treat tool_search as client-executed and native only with its exact client marker and complete lifecycle; otherwise omit it when optional or fail required-but-unavailable. Treat hosted tools as native only on the already-selected Provider with a complete selected-protocol lifecycle; never adapt, execute, fabricate, or proxy them. Preserve unknown/future kinds only with an explicit exact lifecycle contract.", "Fail a required unavailable declaration before upstream sampling with a stable bounded sanitized error. Fail unknown aliases, collisions or length exhaustion, malformed or incomplete envelopes/deltas, missing or duplicate identities, duplicate terminals, mixed V1/V2 fields, and ambiguous inverse mappings visibly at the request/stream/history boundary without partial forwarding.", "Integrate planning and inverse mapping only at the existing resolved-route Responses request, response, SSE, and history seams. Preserve Issue 198 so V1 repair cannot run for V2, and keep exact Provider/model identity through Direct to Gateway to Direct, reconnect, and permitted same-route transport retry.", "Emit only bounded family/disposition counts and stable failure classifications; never log prompts, reasoning, tool arguments or results, credentials, call IDs, aliases, continuation IDs, task paths, or raw declaration payloads.", "Add focused deterministic unit and routing/protocol tests for every table family and disposition, native identity, reversible namespace/custom round trips, tool_choice required handling, alias and envelope limits, streaming/history ambiguity failures, V1/V2 isolation, unknown endpoints, model-slug invariance, and proof that no second Provider receives a tool request.", "Create exactly one Draft PR to dev from the managed Worker branch with only Issue 58 production implementation and tests, an exact-head orchestrator delivery record, focused verification evidence, deviations and risks; do not run GitHub Actions, CLI/manual evidence, the post-review local full suite, integration, tagging, or release." ], "difficulty": "heavy", "done_when": [ "Focused deterministic compatibility, protocol, routing, SSE/history, and Issue 198 isolation tests covering the changed contract pass in the Worker worktree.", "git diff --check passes and git status --porcelain is empty after the Worker commits the exact candidate.", "One Draft PR to dev contains only Issue 58 production implementation/tests and a valid orchestrator:delivery:v1 record bound to its exact head SHA and this contract hash.", "The Worker explicitly records that GitHub CI, CLI/manual evidence, the post-review local full Python suite, integration, tagging, and release were not run." ], "priority": "P1", "risk": "strict", "sha256": "774c19703aa4d98340e91f4b075f6ac0a08717c4d218bf370f84a99b01212f8f", "unresolved_decisions": [] }, "dispatch": { "attempt": 1, "base_sha": "a9440e648be4cd6713d50e182ebd5fb1affbc4b1", "branch": "work/issue-58", "claimed_at": "2026-08-05T09:07:15.858662Z", "contract_sha256": "774c19703aa4d98340e91f4b075f6ac0a08717c4d218bf370f84a99b01212f8f", "creator_agent_id": "470f6d8f-78e6-4afb-b625-257f00f09983", "generation": 1, "id": "dispatch-issue-58-a1", "recovery_prompt_sent": true, "status": "running", "worker_agent_id": "0edb51bb-332b-4137-b3b9-dd99958b6ba9", "workspace_id": "wks_ff467dde6e322efc" } }NOirBRight commentedon Aug 5, 2026
Worker dispatched
dispatch-issue-58-a1gpt-5.6-luna, Max, full-access0edb51bb-332b-4137-b3b9-dd99958b6ba9wks_ff467dde6e322efcwork/issue-58a9440e648be4cd6713d50e182ebd5fb1affbc4b1774c19703aa4d98340e91f4b075f6ac0a08717c4d218bf370f84a99b01212f8fThis isolated Worker owns only Issue #58 production implementation/tests and one Draft PR. The contract preserves native declarations and permits only structural, request-scoped reversible adapters with
native,adapt,omit, orrequired-but-unavailableoutcomes.Model-name branches, fallback, cross-Provider proxying, Gateway tool execution/scheduling, alternate-codec retry, output repair, advanced Beta3/Beta4 qualification, GitHub CI, integration, tagging, and release are excluded. Exact-head strict review is required before CLI/manual or local candidate verification. Merge and Beta2 release authority remain with the coordinator/maintainer.
NOirBRight commentedon Aug 5, 2026
Implementation candidate is now in Draft PR #363 at exact SHA f0e21e5. Focused development verification: 673 passed + 223 subtests; diff/compile checks passed. Publication gates remain intentionally open: exact-SHA review, CLI/manual smoke, post-review affected full local gate, merge, and #318 release work.
feat(gateway): add runtime-derived tool compatibility (#58)
NOirBRight commentedon Aug 5, 2026
Implemented and squash-merged via PR #363 at
4962400c369502ac49b504e142656bc9a61e0571(source candidate521be91524d1a40fffc5464e3e7c7c04d312d357).Acceptance evidence recorded on PR #363:
827 passed, 223 subtests;2109 passed, 1 skipped, 467 subtests, with three baseline failures outside this diff;missing_stream_identity, reconnect storm, or fallback.The fix allows ordinary assistant
messageresponse.output_item.doneevents through adapted streams; tool-shaped unowned lifecycles remain fail-closed. No formal Beta2 tag/release is implied by closing this implementation issue.