@timo972/cc-router 0.9.0 → 0.10.0-rc.1

package/CHANGELOG.md

@@ -12,6 +12,131 @@ Nothing yet.
 
 ---
 
+## [0.10.0] — 2026-08-18
+
+### Added
+
+- OpenAI/Codex sticky session routing: sessions pin to one account for prompt-cache
+  locality (`session_id` → `x-claude-code-session-id` → `prompt_cache_key`), with
+  load- and headroom-aware selection for new sessions.
+- Codex usage tracking from `x-codex-*` response headers: default 5h/weekly windows
+  plus dynamically discovered model-scoped metered buckets, credits, and plan.
+- Scoped cooldowns on upstream failures: bucket-scoped via `x-codex-active-limit`,
+  account-global otherwise; local 429/503 responses when no account is eligible.
+- Dashboard: OpenAI accounts now show 5h/weekly bars, per-bucket rows, credits,
+  plan, request/error/in-flight/session counts, and cooldown state.
+- Unprefixed `gpt-*` models route to OpenAI. The Codex CLI writes the bare slug
+  from its own registry — `model = "gpt-5.6-sol"` in `config.toml`, or whatever
+  its `/model` picker selects — and an unprefixed name went to the Claude path,
+  where `/v1/responses` answers `501 Not Implemented`. No configuration could
+  redirect it, because `openAIAliases` is only consulted for names that are
+  already prefixed; those aliases now apply to the bare form as well. Every
+  other unprefixed model still routes to Claude.
+
+### Changed
+
+- OpenAI account records persist `scopes`, `sessionLimitPercent`, and
+  `weeklyLimitPercent`.
+- The stateless OpenAI round-robin picker was removed in favor of
+  `OpenAITokenPool`.
+
+### Fixed
+
+- A refresh token the OAuth server rejects as terminally expired
+  (`400 invalid_grant`) is no longer retried forever. Every rejection was
+  treated as transient, so the five-minute refresh loop kept re-POSTing a token
+  that could never succeed — one account issued roughly 2000 futile requests
+  over three weeks on the shared Claude Code `client_id`, and nothing marked it
+  as needing re-authentication. Such an account is now flagged, dropped from the
+  refresh loop, and reported once to the operator; the flag is persisted, so a
+  restart neither resumes the futile traffic nor returns the dead account to the
+  routing pool, where it would have answered every request with a `401`. Any
+  other rejection — a different 400, 401, 429, 5xx, a network error — is still
+  retried. Thanks to @ethanhawkes-gif.
+- `accounts list` no longer prints a count that contradicts the rows beneath it.
+  The proxy reads `accounts.json` once at startup and holds that snapshot, so
+  the two sources diverge the moment anything rewrites the file underneath it;
+  the count came from disk while the rows came from the live pool, and a real
+  drift surfaced only as "Accounts (4 configured)" above six rows. An account
+  could be routing live while its refresh token existed nowhere on disk — one
+  restart from needing re-authentication — with nothing to indicate it. The
+  count now describes the rows it sits above, and both directions of drift are
+  named: accounts missing from disk (a credential-loss risk, with the recovery)
+  and accounts on disk the proxy has not loaded (merely stale).
+- `accounts remove` accepts an account that exists only in the running proxy.
+  The guard validated the id against disk while the removal it guards prefers
+  the live pool — the same pool `list` displays — so an account you could see
+  and the code could remove was rejected as "not found". The inventory is now
+  the union of both sources.
+- An unexpected failure partway through an OpenAI request — an upstream
+  connection error, a rejected token refresh, a mid-stream abort — no longer
+  takes down the proxy. Both `/v1/responses` and the `/v1/messages` OpenAI
+  branch awaited the upstream call without catching a rejection, so a single
+  network blip could kill the daemon and lose every account's routing state.
+- `/v1/messages` no longer reports an upstream OpenAI failure as a success. A
+  stream ending in `response.failed`, an `error` event, a JSON error body, or
+  no completion event at all — a stream that stopped mid-flight, or an
+  event-stream response with no body — was translated into an empty Anthropic
+  message with HTTP 200; each now surfaces as an error response, so a rate
+  limit reads as a rate limit instead of an empty assistant turn. A non-2xx
+  upstream response (401, 429, 5xx) is now relayed with its real status, error
+  message, and safe headers — `Retry-After` included, so a client can honor the
+  backoff the server asked for — instead of being parsed as an event stream and
+  reported as a success or a generic failure; non-2xx Codex responses also keep
+  their real content type instead of being rewritten to `text/event-stream`.
+- A terminal event that carries no response object is no longer treated as a
+  successful result. `{"type":"response.completed","response":null}` — or any
+  other non-object payload — satisfied the completion check, so a
+  non-streaming request got HTTP 200 with a `null` body, and `/v1/messages` got
+  a fabricated empty assistant turn; a streamed `/v1/messages` turn was closed
+  with `message_stop` and `end_turn`, telling the client a truncated answer had
+  finished normally. The collected paths now report the `502` that a stream
+  ending without a terminal event already did, and the streamed path ends
+  without `message_stop`, which is what clients already surface as a
+  truncation.
+- A client that disconnects mid-response no longer leaves the upstream Codex
+  request running. Nothing propagated the disconnect, so the relay drained the
+  whole upstream body into a closed socket and held that connection open for a
+  response nobody would receive; the request is now cancelled as soon as the
+  client goes away.
+- A single malformed SSE frame no longer truncates a `/v1/messages` stream.
+  Parsing a chunk was all-or-nothing, so one bad frame discarded the valid
+  events beside it and ended the response as a clean `200` the client could
+  not tell apart from a complete answer.
+- OpenAI credentials are written back to the accounts file the proxy was
+  started with. Under `--accounts <path>` accounts were read from that file
+  but every refresh, add, delete, and update wrote the default
+  `accounts.json` — discarding the change and copying OAuth tokens into an
+  unrelated file.
+- OpenAI token refresh survives a malformed token response. A payload missing
+  `expires_in` produced a `NaN` expiry that read as "never needs refreshing",
+  so the account kept presenting a stale token indefinitely — as did a lifetime
+  large enough to overflow into an infinite expiry, while a zero or negative
+  one reported success on a token that was already due for another refresh.
+  Each is now treated as the failed refresh it is; a failure to
+  persist rotated credentials no longer fails the request that triggered the
+  refresh, and the write is now retried on subsequent requests (and the
+  background refresh loop) until it succeeds, so a rotated refresh token
+  still reaches disk.
+- `PATCH /cc-router/accounts/:id` works for OpenAI accounts instead of
+  returning `404`, so a single OpenAI account can be enabled, disabled, or
+  capped without toggling the whole provider. `POST /cc-router/accounts` now
+  rejects an out-of-range percentage cap the same way `PATCH` does, rather
+  than silently coercing it.
+- A Codex response that ends as `response.incomplete` — e.g. hitting the
+  output-token ceiling — is now delivered with its partial content and token
+  usage instead of being discarded. `/v1/responses` treated only
+  `response.completed` as a terminal event, so `response.incomplete` looked
+  identical to a stream that stopped mid-flight and turned a usable partial
+  answer into a `502 upstream_error`. A streamed `/v1/messages` turn that ends
+  incomplete now closes properly too — the Anthropic translation emitted no
+  `message_stop` for it, leaving the client waiting on a turn that was already
+  over. Both `/v1/messages` paths, streamed or collected, now report
+  `max_tokens` as the stop reason when the output-token ceiling was the cause,
+  instead of an `end_turn` that made a truncated answer look deliberate.
+
+---
+
 ## [0.9.0] — 2026-08-04
 
 ### Added

package/README.md

@@ -18,7 +18,7 @@ Distribute Claude Code requests across Claude subscriptions, and expose an OpenA
 ### Features
 
 - **Cache-aware session routing** — keep each Claude Code session on one account while distributing new sessions across 2-20 Claude Max accounts
-- **Multi-provider routing** — route `openai/*` models to OpenAI ChatGPT/Codex subscription accounts and Claude models to Claude subscriptions
+- **Multi-provider routing** — route `openai/*` and unprefixed `gpt-*` models to OpenAI ChatGPT/Codex subscription accounts and Claude models to Claude subscriptions
 - **Transparent Claude proxy** — Claude Code works normally; streaming, thinking, tool use, prompt caching all pass through
 - **Codex CLI support** — configure Codex to use CC-Router as a Responses-compatible provider
 - **Automatic token refresh** — OAuth tokens are refreshed before they expire, saved atomically to disk
@@ -273,6 +273,8 @@ See [docs/litellm-setup.md](docs/litellm-setup.md) for details.
 
 CC-Router exposes an OpenAI Responses-compatible endpoint for Codex CLI at `/v1/responses`. This lets Codex use OpenAI ChatGPT/Codex subscription accounts through the same local router that Claude Code uses for Claude subscriptions.
 
+**Features:** Sticky sessions pin each Codex conversation to one account for prompt-cache locality. Load- and headroom-aware account selection spreads new sessions across available capacity. Usage tracking from response headers reports account-level 5-hour and 7-day windows, dynamically discovered model-scoped metered buckets, credits, and plan. User caps (`sessionLimitPercent`/`weeklyLimitPercent`) apply to the default Codex bucket. The dashboard shows per-bucket rows, usage bars, credits, plan, and cooldown state for OpenAI accounts.
+
 Configure Codex:
 
 ```bash
@@ -318,11 +320,20 @@ CC_ROUTER_TOKEN=cc-rtr-your-secret codex -m openai/gpt-5.5
 
 Model prefixes:
 
-| Prefix | Upstream |
+| Model | Upstream |
 |--------|----------|
 | `openai/*` | OpenAI ChatGPT/Codex subscription route |
+| `gpt-*` (no prefix) | OpenAI ChatGPT/Codex subscription route |
 | `claude/*` | Claude subscription route |
 | `anthropic/*` | Claude subscription route |
+| anything else with no prefix | Claude subscription route |
+
+The unprefixed `gpt-*` rule exists for clients that do not speak this
+convention. The Codex CLI writes the bare slug from its own registry — either
+`model = "gpt-5.6-sol"` in `~/.codex/config.toml` or whatever its `/model`
+picker selects — so those names arrive without a prefix and would otherwise be
+routed to Claude, where `/v1/responses` answers `501`. Configured
+`openAIAliases` apply to the bare form too.
 
 Examples after the configuration above:
 

package/dist/cli/cmd-accounts.js

@@ -31,7 +31,12 @@ export function registerAccounts(program) {
             console.log(JSON.stringify(liveStats ?? buildStoredAccountsJson(stored, openAIStored), null, 2));
             return;
         }
-        console.log(chalk.bold(`\n  Accounts (${stored.length + openAIStored.length} configured)\n`));
+        // The count has to describe the rows printed below it. Taking it from
+        // disk while listing the proxy's live pool made drift invisible — the
+        // header claimed four accounts above six rows.
+        console.log(chalk.bold(liveStats
+            ? `\n  Accounts (${liveStats.length} in the running proxy)\n`
+            : `\n  Accounts (${stored.length + openAIStored.length} configured)\n`));
         if (liveStats) {
             console.log(chalk.green("  ● Proxy is running — showing live stats\n"));
             for (const s of liveStats) {
@@ -52,6 +57,22 @@ export function registerAccounts(program) {
                     `  errors: ${chalk.red(String(s.errorCount).padStart(3))}` +
                     `  expires: ${exp}`);
             }
+            // The proxy reads accounts.json once at startup, so anything that
+            // rewrites the file afterwards leaves the two out of step. Silence
+            // here is how an account can be routing live while its refresh token
+            // exists nowhere on disk — one restart from having to authenticate it
+            // again.
+            const { unpersisted, unloaded } = accountDrift(liveStats.map(s => s.id), [...stored.map(a => a.id), ...openAIStored.map(a => a.id)]);
+            if (unpersisted.length > 0) {
+                console.log(chalk.red(`\n  ⚠ Not in accounts.json: ${unpersisted.join(", ")}`));
+                console.log(chalk.gray("    These live only in the running proxy. Restarting it loses their\n"
+                    + "    credentials — re-add them, or update any one account to make the\n"
+                    + "    proxy write its pool back to disk."));
+            }
+            if (unloaded.length > 0) {
+                console.log(chalk.yellow(`\n  ⚠ In accounts.json but not loaded: ${unloaded.join(", ")}`));
+                console.log(chalk.gray("    Restart the proxy to pick them up: cc-router start"));
+            }
         }
         else {
             console.log(chalk.gray("  (Proxy not running — showing stored configuration)\n"));
@@ -181,10 +202,7 @@ export function registerAccounts(program) {
         }
         const anthropicAccounts = loadAccounts();
         const openAIAccounts = loadOpenAIAccounts();
-        const existingIds = [
-            ...anthropicAccounts.map(a => a.id),
-            ...openAIAccounts.map(a => a.id),
-        ];
+        const { ids: existingIds, openAIIds } = mergeAccountInventory(anthropicAccounts.map(a => a.id), openAIAccounts.map(a => a.id), await fetchLiveStats());
         if (!existingIds.includes(id)) {
             console.log(chalk.red(`✗ Account "${id}" not found.`));
             console.log(chalk.gray(`  Available: ${existingIds.join(", ")}`));
@@ -199,7 +217,7 @@ export function registerAccounts(program) {
             console.log(chalk.gray("Cancelled."));
             return;
         }
-        const isOpenAI = openAIAccounts.some(account => account.id === id);
+        const isOpenAI = openAIIds.has(id);
         try {
             await removeAccountRuntimeAware(id);
         }
@@ -223,6 +241,46 @@ function printAddOutcome(mode) {
         ? chalk.gray("  Loaded into the running proxy — available now, no restart needed.\n")
         : chalk.gray("  Restart the proxy to load the new account: cc-router start\n"));
 }
+/**
+ * Every account this CLI could act on, from both places one can live.
+ *
+ * The proxy loads accounts.json once at startup and holds that snapshot, so
+ * the two sources drift the moment the file changes underneath a running
+ * proxy — and they answer different questions. Removal prefers the live pool
+ * (see `removeAccountRuntimeAware`), so validating an id against disk alone
+ * rejected accounts that existed and were perfectly removable.
+ */
+export function mergeAccountInventory(storedAnthropicIds, storedOpenAIIds, live) {
+    const openAIIds = new Set(storedOpenAIIds);
+    for (const account of live ?? []) {
+        if (account.provider === "openai_subscription")
+            openAIIds.add(account.id);
+    }
+    return {
+        ids: [...new Set([
+                ...storedAnthropicIds,
+                ...storedOpenAIIds,
+                ...(live ?? []).map(account => account.id),
+            ])],
+        openAIIds,
+    };
+}
+/**
+ * Where the running proxy and accounts.json disagree.
+ *
+ * `unpersisted` is the dangerous direction: those accounts exist only in the
+ * proxy's memory, so a restart loses their refresh tokens and they have to be
+ * authenticated again. `unloaded` is merely stale — the records are safe on
+ * disk, the proxy just has not read them.
+ */
+export function accountDrift(liveIds, storedIds) {
+    const live = new Set(liveIds);
+    const stored = new Set(storedIds);
+    return {
+        unpersisted: liveIds.filter(id => !stored.has(id)),
+        unloaded: storedIds.filter(id => !live.has(id)),
+    };
+}
 export function buildStoredAccountsJson(anthropicAccounts, openAIAccounts) {
     return [
         ...anthropicAccounts.map(a => ({

package/dist/config/manager.js

@@ -137,11 +137,17 @@ export function loadOpenAIAccounts(path) {
         refreshToken: a.refreshToken,
         expiresAt: a.expiresAt,
         enabled: a.enabled !== false,
+        ...(Array.isArray(a.scopes) ? { scopes: a.scopes } : {}),
+        ...(a.sessionLimitPercent !== undefined ? { sessionLimitPercent: a.sessionLimitPercent } : {}),
+        ...(a.weeklyLimitPercent !== undefined ? { weeklyLimitPercent: a.weeklyLimitPercent } : {}),
     }));
 }
-export function saveOpenAIAccounts(accounts) {
+/** Persist OpenAI subscription accounts to an explicit accounts file, preserving
+ *  every other provider's records already in that file. Shared by `saveOpenAIAccounts`
+ *  (default path) and any caller bound to a custom `--accounts <path>`. */
+export function saveOpenAIAccountsToPath(accounts, path) {
     ensureConfigDir();
-    const existing = readAccountsRaw();
+    const existing = readRawFromPath(path);
     const nonOpenAI = existing.filter(a => a.provider !== "openai_subscription");
     const records = accounts.map(a => ({
         id: a.id,
@@ -149,10 +155,15 @@ export function saveOpenAIAccounts(accounts) {
         accessToken: a.accessToken,
         refreshToken: a.refreshToken,
         expiresAt: a.expiresAt,
-        scopes: ["openid", "profile", "email", "offline_access"],
+        scopes: a.scopes ?? ["openid", "profile", "email", "offline_access"],
         enabled: a.enabled,
+        ...(a.sessionLimitPercent !== undefined ? { sessionLimitPercent: a.sessionLimitPercent } : {}),
+        ...(a.weeklyLimitPercent !== undefined ? { weeklyLimitPercent: a.weeklyLimitPercent } : {}),
     }));
-    writeAccountsAtomicToPath(ACCOUNTS_PATH, [...nonOpenAI, ...records]);
+    writeAccountsAtomicToPath(path, [...nonOpenAI, ...records]);
+}
+export function saveOpenAIAccounts(accounts) {
+    saveOpenAIAccountsToPath(accounts, ACCOUNTS_PATH);
 }
 function parseProxyConfig(raw) {
     const parsed = JSON.parse(raw);
@@ -229,13 +240,18 @@ function deserialize(records) {
             expiresAt: a.expiresAt,
             scopes: a.scopes ?? ["user:inference", "user:profile"],
         },
-        healthy: true,
+        // An authExpired account must come back unhealthy. `needsRefresh()` skips
+        // it, so the startup refresh that would otherwise fail and clear `healthy`
+        // never runs — and TokenPool.hardBlock() gates only on `enabled && healthy`,
+        // so defaulting to true here would route live traffic to a dead token.
+        healthy: a.authExpired !== true,
         busy: false,
         requestCount: 0,
         errorCount: 0,
         lastUsed: 0,
         lastRefresh: 0,
         consecutiveErrors: 0,
+        authExpired: a.authExpired === true,
         rateLimits: { ...DEFAULT_RATE_LIMITS },
         enabled: a.enabled !== false, // default true
         sessionLimitPercent: a.sessionLimitPercent !== undefined
@@ -258,5 +274,6 @@ export function serialize(accounts) {
         enabled: a.enabled,
         sessionLimitPercent: a.sessionLimitPercent,
         weeklyLimitPercent: a.weeklyLimitPercent,
+        ...(a.authExpired ? { authExpired: true } : {}),
     }));
 }

package/dist/protocol/model-ref.js

@@ -6,10 +6,29 @@ function cleanModel(model) {
     const trimmed = model?.trim();
     return trimmed ? trimmed : undefined;
 }
+/**
+ * Unprefixed models that belong to OpenAI anyway.
+ *
+ * Clients do not all speak this router's `provider/model` convention. The
+ * Codex CLI writes the bare slug from its own registry — `model =
+ * "gpt-5.6-sol"` in config.toml, or whatever its `/model` picker selects — and
+ * an unprefixed name used to fall through to Anthropic, where the Responses
+ * ingress answers `501`. No configuration could redirect it either, since
+ * `openAIAliases` is only consulted once a name is already prefixed.
+ *
+ * `gpt-` is unambiguous: no Claude model is named that way, so claiming it
+ * costs the Anthropic path nothing. Everything else unprefixed still goes to
+ * Anthropic, which is what existing setups rely on.
+ */
+function isBareOpenAIModel(publicModel) {
+    return publicModel.toLowerCase().startsWith("gpt-");
+}
 export function parseModelRef(model, config = {}) {
     const publicModel = cleanModel(model) ?? cleanModel(config.anthropicDefaultModel) ?? "claude/sonnet";
-    if (publicModel.startsWith("openai/")) {
-        const openAIModel = publicModel.slice("openai/".length);
+    if (publicModel.startsWith("openai/") || isBareOpenAIModel(publicModel)) {
+        const openAIModel = publicModel.startsWith("openai/")
+            ? publicModel.slice("openai/".length)
+            : publicModel;
         const defaultOpenAIModel = cleanModel(config.openAIDefaultModel);
         return {
             provider: "openai_subscription",

package/dist/protocol/openai-response-to-anthropic.js

@@ -1,3 +1,18 @@
+/**
+ * Anthropic stop reason for a terminal Responses payload. Shared by both
+ * translation paths — this module for a collected response, and the streaming
+ * normalizer for a terminal SSE event — so a turn that ends the same way is
+ * reported the same way whether or not the client asked for a stream.
+ *
+ * Keys off `incomplete_details` rather than the event type or `status`: a
+ * completed response carries none, so the same call is correct for both, and
+ * the output-token ceiling is the one reason that maps onto an Anthropic stop
+ * reason of its own. Any other incomplete reason still delivered content, so
+ * `end_turn` stays the honest default.
+ */
+export function anthropicStopReasonForResponse(response) {
+    return response?.incomplete_details?.reason === "max_output_tokens" ? "max_tokens" : "end_turn";
+}
 export function openAIResponseToAnthropicMessage(response) {
     const content = (response.output ?? [])
         .filter(item => item.type === "message")
@@ -10,7 +25,7 @@ export function openAIResponseToAnthropicMessage(response) {
         role: "assistant",
         model: response.model ?? "",
         content,
-        stop_reason: "end_turn",
+        stop_reason: anthropicStopReasonForResponse(response),
         stop_sequence: null,
         usage: {
             input_tokens: response.usage?.input_tokens ?? 0,

package/dist/protocol/openai-responses-collect.js

@@ -2,14 +2,81 @@ import { parseSseLines } from "./sse.js";
 function upstreamError(message) {
     return { kind: "json", status: 502, body: { error: { type: "upstream_error", message } } };
 }
+/**
+ * SSE event types that represent a Responses stream reaching a terminal
+ * *result*, as opposed to a transport/backend failure.
+ *
+ * `response.completed` is the ordinary success terminal event.
+ * `response.incomplete` is also terminal: Codex/OpenAI emit it when
+ * generation stops without completing — most commonly hitting
+ * `max_output_tokens`, or a content filter — but the event still carries a
+ * full response object with `usage` and `incomplete_details.reason`. It is a
+ * *result* to relay, not an error, so it belongs here rather than alongside
+ * `response.failed`.
+ *
+ * `response.failed` and the bare `error` event are failures, not results:
+ * they carry no usable response body and are handled separately by every
+ * caller below.
+ */
+const TERMINAL_RESPONSE_EVENT_TYPES = new Set([
+    "response.completed",
+    "response.incomplete",
+]);
+/**
+ * Returns the `.response` payload carried by a terminal Responses SSE event
+ * (`response.completed` or `response.incomplete`), or `undefined` for any
+ * other event — including `response.failed`/`error`, which are failures and
+ * carry no usable response to return. Shared by every ingress that needs to
+ * recognize "the stream produced a result", so that notion cannot drift
+ * apart between the `/v1/responses` and `/v1/messages` paths.
+ *
+ * The event type alone does not make a result: it has to carry an actual
+ * response object. Upstream can emit `{"type":"response.incomplete",
+ * "response":null}` — or a string, a number, an array — and every consumer
+ * here asks whether the payload is `undefined`, so anything else would count
+ * as a terminal success. That would hand a `200` with a `null` body to a
+ * non-streaming caller and mark an observed stream complete, which is exactly
+ * what the terminal-event checks exist to prevent. A payload nothing can be
+ * read out of is not a result.
+ *
+ * `{}` is the same problem wearing an object's clothes: it satisfies a bare
+ * typeof check and then produces a `200` whose body is `{}`, or an empty
+ * assistant turn on the Messages path. `id` is the field that separates a
+ * Responses object from an empty husk — upstream stamps it from
+ * `response.created` onward — so requiring it is what makes "is this an
+ * object" mean "is this a response".
+ */
+export function terminalResponsePayload(event) {
+    if (typeof event !== "object" || event === null)
+        return undefined;
+    const typed = event;
+    if (typeof typed.type !== "string" || !TERMINAL_RESPONSE_EVENT_TYPES.has(typed.type)) {
+        return undefined;
+    }
+    const payload = typed.response;
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+        return undefined;
+    const { id } = payload;
+    if (typeof id !== "string" || id.length === 0)
+        return undefined;
+    return payload;
+}
 /**
  * Collapse the Codex backend's forced SSE stream into a single Responses
  * object for callers that did not ask to stream. The backend's terminal
- * `response.completed` payload is returned verbatim, preserving tool calls,
- * reasoning, and usage.
+ * `response.completed` or `response.incomplete` payload is returned
+ * verbatim, preserving tool calls, reasoning, and usage — including for a
+ * response that stopped early (e.g. hitting the output-token ceiling), which
+ * is a usable partial answer, not a transport failure.
  */
-export async function collectCodexResponseStream(upstream) {
+export async function collectCodexResponseStream(upstream, 
+/** Invoked the moment upstream announces a failure, so the caller keeps that
+ *  verdict even when the read is later cut short — the catch below turns any
+ *  such interruption into a generic "malformed stream" and would otherwise
+ *  bury it. */
+onUpstreamFailure) {
     if (!upstream.ok) {
+        onUpstreamFailure?.();
         const contentType = upstream.headers.get("content-type") ?? undefined;
         return { kind: "text", status: upstream.status, contentType, body: await upstream.text() };
     }
@@ -27,21 +94,25 @@ export async function collectCodexResponseStream(upstream) {
         return upstreamError("Empty upstream body");
     const decoder = new TextDecoder();
     let remainder = "";
-    let completed;
+    let terminalResponse;
     let failure;
     const applyEvent = (event) => {
+        const payload = terminalResponsePayload(event);
+        if (payload !== undefined) {
+            terminalResponse = payload;
+            return;
+        }
         if (typeof event !== "object" || event === null)
             return;
         const e = event;
-        if (e.type === "response.completed") {
-            completed = e.response;
-        }
-        else if (e.type === "response.failed") {
+        if (e.type === "response.failed") {
             const err = e.response?.error;
             failure = err?.message ?? "Response failed";
+            onUpstreamFailure?.();
         }
         else if (e.type === "error") {
             failure = e.error?.message ?? "Upstream error event";
+            onUpstreamFailure?.();
         }
     };
     try {
@@ -65,7 +136,115 @@ export async function collectCodexResponseStream(upstream) {
     }
     if (failure !== undefined)
         return upstreamError(failure);
-    if (completed === undefined)
-        return upstreamError("Stream ended before response.completed");
-    return { kind: "json", status: upstream.status, body: completed };
+    if (terminalResponse === undefined)
+        return upstreamError("Stream ended before any terminal response event");
+    return { kind: "json", status: upstream.status, body: terminalResponse };
+}
+function usageNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+ * Extract usage totals from a response-shaped object (i.e. something with a
+ * `.usage` field directly — the Responses `response.completed`/
+ * `response.incomplete` payload, or an object wrapping one). Shared by every
+ * ingress that needs to report Codex token usage from a fully-materialized
+ * body.
+ */
+export function usageFromResponseBody(body) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const usage = body.usage;
+    if (usage === undefined || usage === null || typeof usage !== "object")
+        return undefined;
+    return {
+        inputTokens: usageNumber(usage.input_tokens),
+        cachedInputTokens: usageNumber(usage.input_tokens_details?.cached_tokens),
+        outputTokens: usageNumber(usage.output_tokens),
+    };
+}
+/**
+ * Extract usage totals from a terminal Responses SSE event —
+ * `response.completed` or `response.incomplete`, see
+ * `TERMINAL_RESPONSE_EVENT_TYPES` above — or `undefined` for any other
+ * event. Single definition shared by every streaming ingress so
+ * `/v1/responses` and `/v1/messages` can never report different token totals
+ * for the same stream.
+ */
+export function usageFromTerminalEvent(event) {
+    return usageFromResponseBody(terminalResponsePayload(event));
+}
+/**
+ * Passive usage reader for the byte-transparent streaming path: it only
+ * observes chunks that are already being piped downstream unchanged. It also
+ * watches for a `response.failed`/`error` event — the same terminal-failure
+ * signal `collectCodexResponseStream` above already detects for the
+ * non-streaming path — so a stream that upstream answered with `200` but
+ * ended in failure can still be reported (for stats/activity only) as the
+ * failure it was, without altering a single byte written to the client.
+ */
+export function createCodexUsageObserver() {
+    const decoder = new TextDecoder();
+    let remainder = "";
+    let totals;
+    let failure;
+    let completed = false;
+    const applyEvent = (event) => {
+        totals = usageFromTerminalEvent(event) ?? totals;
+        if (typeof event !== "object" || event === null)
+            return;
+        const e = event;
+        if (e.type === "response.failed") {
+            const err = e.response?.error;
+            failure = err?.message ?? "Response failed";
+        }
+        else if (e.type === "error") {
+            failure = e.error?.message ?? "Upstream error event";
+        }
+        else if (terminalResponsePayload(event) !== undefined) {
+            completed = true;
+        }
+    };
+    return {
+        push(chunk) {
+            // Best-effort: a malformed SSE frame from upstream must never throw
+            // here. This observer only watches bytes that are already being
+            // relayed to the client verbatim — a parse failure just means that one
+            // frame goes uncaptured, never that the response breaks. Tolerant
+            // parsing keeps the rest of the chunk's valid events.
+            try {
+                const parsed = parseSseLines(remainder + decoder.decode(chunk, { stream: true }), { tolerant: true });
+                remainder = parsed.remainder;
+                parsed.events.forEach(applyEvent);
+            }
+            catch {
+                // swallow — passive observer, see comment above
+            }
+        },
+        finish() {
+            try {
+                const tail = decoder.decode();
+                if (tail || remainder) {
+                    parseSseLines(remainder + tail + "\n", { tolerant: true }).events.forEach(applyEvent);
+                }
+            }
+            catch {
+                // swallow — passive observer, see comment above
+            }
+            remainder = "";
+            return totals;
+        },
+        failure() {
+            // Tolerant parsing drops a malformed frame instead of aborting, which
+            // also means a malformed *terminal* response event (`response.completed`
+            // or `response.incomplete`) frame vanishes silently. Without an
+            // observed terminal event the stream never actually produced a result,
+            // so — mirroring collectCodexResponseStream's non-streaming check —
+            // that is reported as a failure too, unless an explicit
+            // response.failed/error already said more about what went wrong.
+            return failure ?? (completed ? undefined : "Upstream stream ended before any terminal response event");
+        },
+        explicitFailure() {
+            return failure;
+        },
+    };
 }