Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

14.2 KB
Raw Blame

Managed CPA patch

source.json pins the upstream revision, artifact version and patch digest. local-management-stdin.patch includes the parent-pipe management credential bootstrap and Codex account model discovery. Build with scripts/build-cpa.py.

Browser sign-in callbacks

The pinned browser flow receives Codex and Claude callbacks directly on temporary loopback listeners at their existing registered addresses. It binds available IPv4 and IPv6 loopback interfaces; an occupied address releases any partial bind and keeps the same session for protected manual input. The private auth-URL response projects only hiroute_callback_mode=automatic|manual. An old artifact lacking this handshake must not be used with the current daemon.

Reception checks the method, path, host and exact pending state. Browser callbacks and the management callback POST share atomic one-use admission, including after the waiting OAuth worker removes the callback file. CPA reception may retry failed file publication; HiRoute's manual-input owner does not resend an admitted code after a failed or uncertain submission. Observe status or cancel and start again. An accepted authorization code cannot be replaced. The browser response contains no code, state, provider error or management redirect and acknowledges reception only. The existing token exchange and credential persistence establish actual login. Completion, cancellation, timeout and owned-process exit release the listeners. There is one pending login per provider; saved accounts do not retain these ports.

The patch carries TestHiRouteBrowserCallbackValidationAndOneUse, atomic admission, dual-loopback cleanup, occupied-port fallback, main-route error and actual Codex browser-to-file-store regressions. Run these on the exact prepared source with:

go test ./internal/api/handlers/management ./internal/api -run '^TestHiRoute' -count=1

The Codex exchange regression supplies synthetic tokens through the pinned OAuth service test seam. It proves callback reception and persistence, not fresh real-account authorization. No native credential store or paid model call is used.

Codex OAuth registration queries https://chatgpt.com/backend-api/codex/models using the account's access token and account ID over CPA's existing proxy/TLS transport. For native access-only leases, client_version comes from the auth metadata hiroute_client_version, populated by HiRoute's bounded native engine --version probe. A new access lease re-probes the selected engine. Prerelease suffixes are removed, matching Codex's models-manager. Missing native version evidence still fails closed.

For independent OAuth credentials containing their own refresh token, discovery extracts the version from CPA's upstream codexUserAgent constant. This is the same client identity the pinned executor sends, rather than a second version number maintained by HiRoute. It works on initial OAuth registration before any HiRoute account-controls PATCH, and requires no native Codex installation or login. Neither mode reads a local models cache or substitutes bundled membership.

Remote membership replaces the bundled membership for access-token accounts. Existing bundled metadata can enrich matching IDs. Registration still applies normal exclusions, OAuth aliases and account prefixes. Discovery has a five second deadline and a 16 MiB response bound; redirects are rejected. Failure leaves the existing registered catalog unchanged, without logging tokens or upstream response bodies. An initial failure does not create model entries. This does not add polling or a new catalog cache. Inference does not discover models. Successful listing is not proof that inference succeeds.

An enabled newer generation of the same registration can supersede an in-flight lookup. The stale result is discarded and the registration owner can discover once for the latest access-bearing generation, sharing the original five-second deadline. Removal, disable, lost access and a different registration epoch cannot request this handoff. Transport failure alone does not retry. Continued churn remains bounded and observable; an old account cannot populate a replacement.

HiRoute's ordinary routing compilation and Codex preview read and verify the registered catalog without repeating an already-correct auth control PATCH. An explicit subscription check refreshes it; credential/version changes use the existing auth update path. This keeps remote directory availability out of unchanged preview/publication reads while retaining all account pin checks. When the directory is empty and the whole registration is quiescent with a consistent terminal observation, a pin read fails immediately instead of polling that empty result for 20 seconds. The existing response's registration_pending flag covers the whole registration, including the gap before a bounded handoff. Queued auth updates and reconciliation passes share that same scope. Two observations bracket the local catalog read; any intervening transition makes that response pending. No registry lock spans discovery or management I/O. Pending work still gets its existing convergence wait. Missing/malformed observations, unknown registration state and an older retained failure cannot shorten the wait. A nonempty retained directory still undergoes every normal pin check. For native borrowing, the fields PATCH carries the validated lease's current hiroute_client_version alongside its controls. CPA persists and synchronously discovers that version even when its watcher still holds the preceding metadata. No access or refresh token is included in this control request.

The existing authenticated account-model response also carries the private hiroute.cpa-model-discovery/v1 observation. CPA retains the first failed or discarded attempt and the latest attempt per account, including phase, closed reason, total/phase durations, HTTP or proxy status, model counts and up to six phase timings. Credentials, native version, account/model IDs, URLs and raw errors are excluded. The in-memory store holds at most 128 accounts and reports evictions; process exit loses it. Retention starts when this artifact starts, so it cannot recover historical failures from an older process. Older concurrent attempts cannot overwrite the latest attempt. No new endpoint or maintenance channel is introduced. Transport retry settings are unchanged; generation handoff shares the original five-second discovery deadline. In-flight registration counts are separate from the retained history, survive history eviction and are deleted when the last overlapping registration exits.

HiRoute validates this metadata independently of model membership, emits bounded cpa_model_discovery transitions on its existing diagnostic context and explicitly marks missing, invalid or truncated observations. Repeated polling does not emit the same transition again. Proxy CONNECT rejection has its own status; it must not be interpreted as an upstream HTTP response. An empty successful upstream list, filtering to zero models and discarding a stale authorization are distinct observations. These facts diagnose listing and registration, not inference. Registration also records generation and registration-epoch equality as separate booleans, so a stale result identifies the actual failed guard without exposing authorization identifiers or generation values.

On Windows, native Codex and Claude file borrowing uses borrowed_native_windows.rs. The reader holds the inspected parent and regular file, rejects reparses and hardlinks, and checks native identity, timestamps and permission facts before publishing an access lease. Readable external ACLs and read-only attributes stay unchanged; only the managed access-only copy receives HiRoute's private ACL. These local admission checks do not establish official account authorization, model discovery or inference. Native adversarial cases live in borrowed_native_windows_tests.rs.

Focused upstream tests are shipped in the patch:

For the stale-manager/current-file regression, copy vendor/cpa/tests/managed_version_sync_test.go into the prepared pinned source's internal/api/handlers/management/ directory, then run go test ./internal/api/handlers/management -run '^TestHiRouteManagedVersionSyncBeforeWatcher$' -count=1. It uses the real fields handler, file store and patched discovery executor with a synthetic transport. Legacy requests reproduce rollback; current requests verify synchronous version consumption and access-only ownership.

go test ./sdk/cliproxy ./internal/runtime/executor ./cmd/server ./internal/api/handlers/management \
  -run 'TestCodexDiscovery|TestCodexModelDiscovery|TestRegisterModelsForAuth|TestLocalManagementPasswordPipeBounds|TestLocalMachinePasswordPreservesRemotePolicy'

Managed children allowlist HTTP(S)_PROXY and NO_PROXY (both cases). The local patch applies Go's standard per-destination environment proxy selection to protected-host TLS transports when no explicit proxy/injected transport exists. It preserves NO_PROXY and does not retry direct after proxy failure. ALL_PROXY is not part of this contract; configure HTTPS_PROXY for subscription endpoints.

Current macOS development artifacts

The checked-in development-cpa-artifacts.v1.json identifies a historical .1 binary; its hash is retained as measured, not relabeled as the current .3 build. Do not stage that old binary with the current daemon.

On macOS, python3 scripts/package-desktop.py build --cpa-source-repo /absolute/CPA-checkout generates the current patched CPA and a measured cpa-artifacts.json in its candidate output directory. For a Debug Desktop build, set HIROUTE_CPA_MANIFEST=/absolute/candidate-output/cpa-artifacts.json and use that same output's HiRoute.app/Contents/MacOS/cliproxyapi beside the Debug hirouted:

python3 scripts/stage-desktop-cpa.py \
  --manifest /absolute/candidate-output/cpa-artifacts.json \
  --cpa /absolute/candidate-output/HiRoute.app/Contents/MacOS/cliproxyapi \
  --hirouted /absolute/checkout/target/debug/hirouted

Use the default ad-hoc package identity for this development staging path. The staging tool rejects stale versions before copying; it still verifies the exact digest, architecture, signature, dependencies and version of the binary. A Linux backend test does not validate this native macOS build/install path.

Managed OAuth authentication recovery and execution evidence

The pinned auth manager owns proactive refresh and its bounded same-account, same-model 401 recovery. HiRoute keeps request-retry=0, max-retry-credentials=1, and streaming.bootstrap-retries=0; it does not add a second OAuth retry loop. Access-only native leases still lack refresh credentials and cannot enter this recovery path. Existing executor protocol repairs can make additional inference sends, so one logical HiRoute attempt is not a promise of at most two wire sends. Cross-account/model fallback remains disabled.

The local patch attaches one request-scoped trace to the API handler context. The common usage HTTP transport records each inference RoundTrip invocation and HTTP 401 response; it does not count OAuth exchanges or account discovery. These are transport attempts, not proof that bytes reached the remote server. It deliberately does not count MarkUpstreamAttempt, whose outer Claude send marker and inner transport marker can refer to the same request. Auth recovery attempts/successes are counted separately in the existing auth manager; a success includes reusing a newer token that another request already refreshed. No token-usage records are created from these counters or failed 401 responses. Codex uses this HTTP transport for non-WebSocket downstream calls; the HiRoute bridge uses that path. WebSocket inference is outside this metadata contract.

Before the first downstream header/body/flush commit, a response-writer wrapper sets the reserved X-HiRoute-CPA-Execution header to v1;<inference_attempts>;<http_401_responses>;<auth_recovery_attempts>;<auth_recovery_successes>. Each count is at most 32; overflow is v1;unknown. The trace carries no account identifier, token, prompt, provider error body or usage. The upstream header filter excludes this reserved name, and the local writer overwrites any supplied value at commit. The same rule covers success and error replies. The existing stream bootstrap recovery finishes before downstream commit; forwarded stream failures do not trigger this auth recovery.

Gateway trusts these facts only for a validated CPA connector whose current credential lease resolved to loopback. Other upstreams' identically named headers are ignored. Missing, malformed, duplicate, unsupported-version or overflow metadata is explicitly unknown, not zero or one. The typed upstream_wire diagnostic carries the counters under cpa_execution; the ordinary logical attempt/usage producer remains unchanged. Gateway reconstructs public response headers and does not forward the private bridge header.

Gateway's existing deadline/cancellation closes the downstream call; CPA forwards request cancellation into the existing refresh and retry context. A canceled waiter now checks its context immediately after acquiring the account refresh mutex, before reading/updating credentials or invoking a refresher. The stock mutex wait itself remains non-interruptible; it can retain a canceled goroutine until the active refresher exits, but must not cause another refresh/send.

The additive diagnostic field defaults to absent for historical records. No persisted business-data migration or public response-contract change is needed; the private CPA handshake is delivered by the matching managed artifact version.

Focused patch checks (run by the assigned validation owner, not implementation):

go test ./sdk/cliproxy/executor ./internal/runtime/executor/helps ./sdk/api/handlers ./sdk/cliproxy/auth -run '^TestHiRoute' -count=1

These cover the HTTP counter against a controlled upstream ledger, OAuth exclusion, spoofed/error response headers, metadata commit, pinned same-account 401 recovery, no-refresh-token rejection, no recovery loop, canceled refresh waiters, and stream payload followed by 401 without replay. Controlled tests do not replace independent real-account expiry/refresh and restart acceptance.