Repository navigation
Introduce a typed RoutePlan seam for Gateway routing and mutation policy #61
Description
Problem
Gateway behavior is represented partly by RouteDecision, but request execution still recomputes policy from overlapping booleans and string comparisons such as transparent metering, Codex App external adaptation, official passthrough, same-format transparency, lightweight fallback, semantic repair, vision, usage, retry, and transport choices.
This makes it difficult to prove what a route exposes or mutates, and risky to add #58 without another cross-product of conditions.
#5 owns upstream opening/error mapping. #25 owns protocol conversion. This issue owns the higher-level route-plan interface and must compose those seams.
Scope
Introduce one typed, immutable RoutePlan produced at a pure/testable seam before request mutation or network I/O.
The plan should explicitly contain or reference:
- upstream/provider/model and alias mapping;
- authentication strategy;
- inbound/upstream wire formats and conversion mode;
- semantic adapter mode;
- request and response/SSE mutation policies;
- retry policy and request kind;
- usage/telemetry mode;
- Vision Proxy policy;
- Codex compatibility policy;
- tool exposure policy and evidence state;
- upstream transport policy including official keepalive.
Tool exposure must be represented without assuming unresolved #57 results. The type should be able to distinguish at least:
- current compatibility behavior;
- native deferred search candidate;
- native no-search candidate with an explicit proven tool subset;
- unsupported/unknown.
In this behavior-preserving issue, all existing third-party Codex App routes continue to resolve to current compatibility behavior. Candidate/unknown states must not enable passthrough or remove repair logic until #57/#58 authorize them.
The executor should consume the plan instead of re-deriving policy. Add a mutation summary suitable for tests/telemetry, such as model alias, namespace flattening, wire conversion, semantic repair, hard-coded schema injection, official tool-search preservation, or synthetic terminal failure. Do not record secrets or request content.
Spike boundary
This architecture extraction does not answer whether native search/no-search routes work. If implementation exposes an unresolved Codex behavior not already covered by #57, record it on #57 or create a narrower spike; do not choose production behavior inside this refactor.
Acceptance criteria
- One planning interface determines all major route policies before mutation/network I/O.
-
_proxy_post_requestno longer re-derives route mode through overlapping conditions. - Tool exposure policy distinguishes compatibility, candidate native modes, and unknown.
- Unknown/candidate modes cannot accidentally enable passthrough in this behavior-preserving issue.
- Official passthrough, Codex App external compatibility, provider-scoped transparent Responses, and Responses/Chat conversion have table-driven plan fixtures.
- Fixtures include current
supports_search_tool = falseplus explicit Gateway injection as compatibility behavior, without claiming all Deferred tools are visible. - Transport selection composes with Continue Gateway request pipeline extraction: upstream opener and error mapper #5/Scope official TCP keepalive to official requests without a global urllib opener #60.
- Tests assert route mode and mutation summary.
- Existing routing, retry, usage, vision, tool exposure, and response behavior remains unchanged.
- 0.1.8 Beta2: Implement runtime-derived tool compatibility for custom Responses endpoints #58/Retire Gateway-owned Codex tool schemas and scheduling where the spike proves native behavior #59 can later add evidence-backed policies without further branching in the request handler.
Required verification
python -m pytest tests/test_routing.py tests/test_chat_completions_gateway.py tests/test_proxy_event_logging.py
python -m pytest
python scripts/report_quality_gates.pyRelated
- Continue Gateway request pipeline extraction: upstream opener and error mapper #5
- Extract protocol_translation.py seam for Responses and Chat conversion #25
- Spike complete Codex model capability exposure on third-party providers #57
- 0.1.8 Beta2: Implement runtime-derived tool compatibility for custom Responses endpoints #58
- Retire Gateway-owned Codex tool schemas and scheduling where the spike proves native behavior #59
- Scope official TCP keepalive to official requests without a global urllib opener #60
src-python/codex_proxy.py::route_decision_for_requestsrc-python/codex_proxy.py::_proxy_post_request
Activity
NOirBRight commentedon Jul 11, 2026
Planning update (2026-07-11): this behavior-preserving RoutePlan seam is on the Issue #57 decision gate milestone and can proceed in parallel with #62 during Jul 13–17. Candidate/unknown capability states must continue to resolve to existing compatibility behavior; this issue does not wait for the final #57 route decision.
12 remaining items
NOirBRight commentedon Jul 30, 2026
Third independent-review repair is frozen and pushed to PR #262 at
76b02adf43efcdee8dcccd502338c63d96c0f77d(76b02ad).What changed:
RouteAttemptPlannow owns endpoint URL plus typed auth/stream/usage/transport/mutation choices and a frozen retry execution contract (eligibility, timeout, attempt counts, failure expansion, elapsed/open/pre-response budgets, retry notices, and lifecycle eligibility).autoroutes now record and execute the real body chain: Chat→Responses first, then Chat→Responses→Chat after an eligible 404 fallback. Planned-union telemetry is explicitly separate from selected/executed-attempt telemetry.caller_tool_strippingmutation.Supportedstate reports supported.Verification:
PATHpy_compile: passedgit diff --check: passedThe earlier core attempt whose nested replay process resolved Python 3.11 produced only two issue-108 syntax-parser failures; the authoritative Python 3.13 rerun is green and both results are recorded in
docs/evidence/issue-61/README.md. GitHub Actions is now running on the frozen SHA; this update does not merge or close the issue.NOirBRight commentedon Jul 30, 2026
Fourth independent-review repair is pushed at exact SHA
013e1daa72e7b7a53878dbef9ff64267044daed4(013e1daa).Actionable findings repaired:
provider-capabilities.v3schema with a valid version/hash pair; future/unknown versions fail closed;HTTPError, and official-control response paths require a typedRelayExecutionPlan; the relay profile/optional-policy re-derivation entry was removed;Verification:
py_compile: passedgit diff --check: passedExact red/green and environment notes are recorded in
docs/evidence/issue-61/README.md. This update does not merge or close #61; exact-SHA CI and renewed independent Standards/Spec review remain required.NOirBRight commentedon Jul 30, 2026
Phase 1 ownership clarification: protocol-switch restart contract
No end-to-end requirement is removed. The overlapping protocol-switch sentence is split at the existing issue boundary:
RoutePlanconsumes the configured provider protocol plus one route-qualified capability binding. A stale/mismatched old-protocol binding is typedUnqualified, observable, and fail-closed before credential refresh, request mutation, or upstream I/O. Introduce a typed RoutePlan seam for Gateway routing and mutation policy #61 must not invent a hot-switch success or a restart-clearing signal.A process restart is the clearing boundary because the new Codex process reloads the regenerated binding; Gateway restart or another save is not a truthful substitute. Beta1 requires both #61 and #250, and merging #61 alone does not claim the #250 end-to-end disclosure is complete.
feat(gateway): add immutable route planning seam (#61)
Introduce immutable RoutePlan seam for Gateway routing (#262)
NOirBRight commentedon Aug 1, 2026
Resolved by merged PR #262 (3c73a7a). Exact head passed two-axis review and Hosted CI / gate.