@rikcodes/teamclaude 1.1.20-rik.13 → 1.1.20-rik.15

package/README.md

@@ -107,10 +107,12 @@ A Claude Code session can use OpenAI models alongside the Claude accounts. They
 **1. Install the sidecar and log it into your ChatGPT account** (one time):
 
 ```bash
-brew install raine/claude-code-proxy/claude-code-proxy
+curl -fsSL https://raw.githubusercontent.com/rikbrown/claude-code-proxy/rik/main/scripts/install.sh | bash
 claude-code-proxy codex auth login
 ```
 
+This installs [rikbrown/claude-code-proxy](https://github.com/rikbrown/claude-code-proxy), a fork of the reference sidecar. Take the fork rather than upstream's Homebrew build: it forwards Codex's quota headers, without which every bar on the account reads `unknown`, and it lets you raise the 60-second header timeout that otherwise kills a long reasoning turn. See [Timeouts](docs/openai.md#timeouts).
+
 **2. Connect it** — add four pieces to `~/.config/teamclaude.json`:
 
 ```json
@@ -161,11 +163,11 @@ Each request is routed by the model name in its body, so one session can freely
 
 1. Check that your sidecar build lists it: `curl -s http://127.0.0.1:18765/v1/models`. The sidecar has its own allow-list and rejects any id that it does not know, regardless of the TeamClaude configuration. Upgrade the sidecar if the id is missing.
 2. Add a `customModels` row. Codex publishes the window for each model as `context_window` in `~/.codex/models_cache.json`; copy it to `contextTokens`.
-3. Start a new `teamclaude run` session. The rows are read at launch, so you do not need to restart the server. If you upgraded the sidecar binary, restart the server — or send `SIGTERM` to the sidecar process and let the supervisor restart it with the new binary.
+3. Start a new `teamclaude run` session. The rows are read at launch, so you do not need to restart the server. If you upgraded the sidecar binary, restart the server — or send `SIGTERM` to the sidecar process and let the supervisor restart it with the new binary. The first `SIGTERM` only starts a graceful shutdown, which a request in flight holds open; send it a second time to force the exit.
 
-Claude Code prints one `[claude-code:unrecognized_model]` line to stderr for each custom model. This is expected; suppressing it would lose the correct context window. The quota bars for the sidecar account show `unknown` unless the sidecar forwards Codex's rate-limit headers — see [Quota](docs/openai.md#quota). Keep the sidecar on loopback.
+Claude Code prints one `[claude-code:unrecognized_model]` line to stderr for each custom model. This is expected; suppressing it would lose the correct context window. The quota bars for the sidecar account show `unknown` unless the sidecar forwards Codex's rate-limit headers, which the fork build in step 1 does and upstream's does not — see [Quota](docs/openai.md#quota). Keep the sidecar on loopback.
 
-The sidecar appears under the account table as a `⚙` line rather than a row because it holds no subscription, is the only account its route can use, and never rotates. The line also shows its supervised process state (`up pid 98018`, or `down (code 1) 3 restarts`).
+The sidecar appears under the account table as a `⚙` line rather than a row because it holds no subscription, is the only account its route can use, and never rotates. The line also shows its supervised process state (`up pid 98018`, or `down (code 1) 3 restarts`), followed by what the sidecar reports about itself while it is up (`2 active 3 errors`, read from its own `/monitor` endpoint; each is omitted at zero, and both are omitted if that endpoint does not answer).
 
 #### Several ChatGPT accounts
 
@@ -221,7 +223,7 @@ Three details matter:
 - **`CCP_CODEX_TRANSPORT=http` is required.** A WebSocket upgrade is relayed with the caller's own headers and draws no account, so the WebSocket transport cannot be pooled.
 - **Do not reuse a name across providers.** Routes address accounts by name, so a shared name admits both — including the Claude account that cannot serve `gpt-*`, which outranks the sidecar on priority and wins. TeamClaude warns at startup when it sees one.
 
-Two things differ from the single-account setup: each turn appears **twice** in the activity list, once per hop, and tokens are booked against the sidecar account, so a ChatGPT account reads `N req · 0 tok`. Its quota bars are unaffected because they come from the `x-codex-*` headers on the second hop, where the subscription is.
+One thing differs from the single-account setup: each turn appears **twice** in the activity list, once per hop. Tokens and quota bars both come from the second hop, where the subscription is, so they are booked against the ChatGPT account that served. The sidecar account holds a stub login and spends nothing of its own, so it reads `N req · 0 tok` — booking it as well would double every figure.
 
 Full details, including what happens to quota on each hop: [Several ChatGPT accounts behind one sidecar](docs/openai.md#several-chatgpt-accounts-behind-one-sidecar).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rikcodes/teamclaude",
-  "version": "1.1.20-rik.13",
+  "version": "1.1.20-rik.15",
   "description": "Multi-account proxy for Claude Code and Codex: pools Claude Max, ChatGPT/Codex, API-key and third-party backend accounts, and rotates on quota",
   "type": "module",
   "main": "src/index.js",

package/src/account-manager.js

@@ -214,6 +214,13 @@ function makeAccount(acct, index) {
     hasClaudeMax: acct.hasClaudeMax ?? null,
     hasClaudePro: acct.hasClaudePro ?? null,
     priority: acct.priority || 0,
+    // Where this account sits in the list the TUI draws, arranged by the
+    // operator from the settings screen. Presentation only: nothing but
+    // _displayOrder in tui.js reads it, and it is emphatically NOT `priority`
+    // above — that one decides which account rotation spends next, and the two
+    // answer different questions about the same fleet. `null` means never
+    // placed, which sorts after every account that has been.
+    displayOrder: Number.isFinite(acct.displayOrder) ? acct.displayOrder : null,
     disabled: acct.disabled || false,
     maxUsage: acct.maxUsage ?? null,
     upstream: acct.upstream || null,
@@ -3485,7 +3492,9 @@ export class AccountManager {
     // threshold and every request fails, while a sibling sits at 0%.
     // A standalone sidecar (no Codex accounts here) is NOT a conduit: it holds
     // its own login, the forwarded numbers are its own, and they still apply.
-    if (!(isLocalUpstream(account) && this.accounts.some(a => providerOf(a) === 'codex'))) {
+    // Shares its definition with the token counters, which drop a conduit hop
+    // for the same reason: what it reports belongs to whoever served.
+    if (!this._isCodexConduit(account)) {
       for (const window of ['primary', 'secondary']) {
         const used = parseFloat(headers[`x-codex-${window}-used-percent`]);
         const minutes = parseInt(headers[`x-codex-${window}-window-minutes`], 10);
@@ -3556,12 +3565,49 @@ export class AccountManager {
     }
   }
 
+  /**
+   * Whether `account` merely RELAYS to this fleet's own Codex pool instead of
+   * holding a subscription of its own: a translating sidecar whose back leg is
+   * pointed back at this proxy, so each turn crosses this process twice — once
+   * inbound on `/v1/messages` and once outbound on `/backend-api/codex/*`
+   * (docs/openai.md, "Several ChatGPT accounts behind one sidecar").
+   *
+   * Keyed on three things, all of which the documented setup has and no other
+   * account does:
+   *
+   *   a loopback upstream   the sidecar runs on this machine.
+   *   the Anthropic wire    a conduit is reached on `/v1/messages`, so it
+   *                         carries no `provider` field — docs/openai.md warns
+   *                         that giving one `"provider": "codex"` puts it in the
+   *                         foreign-subscription partition and every `gpt-*`
+   *                         request then fails to find an account. A pooled
+   *                         ChatGPT account is therefore never a conduit,
+   *                         whatever its upstream says; it IS the pool.
+   *   a pool to relay to    a standalone sidecar holding its own ChatGPT login
+   *                         is NOT a conduit: everything it reports is its own,
+   *                         and it is the only hop there is.
+   *
+   * Still imprecise in one direction, deliberately: a fleet running BOTH a
+   * self-hosting local Anthropic backend and Codex accounts reads the former as
+   * a conduit. Narrowing that would mean correlating the two hops of one turn,
+   * which nothing here can do — they are separate requests sharing no id — and
+   * the cost of the false positive is a row that under-reports rather than one
+   * that misroutes.
+   *
+   * @param {any} account
+   */
+  _isCodexConduit(account) {
+    return isLocalUpstream(account)
+      && providerOf(account) === DEFAULT_PROVIDER
+      && this.accounts.some(a => providerOf(a) === 'codex');
+  }
+
   /**
    * Update cumulative token usage from response body data.
    */
   updateUsage(accountIndex, inputTokens, outputTokens) {
     const account = this.accounts[accountIndex];
-    if (!account) return;
+    if (!account || this._isCodexConduit(account)) return;
     if (inputTokens) account.usage.totalInputTokens += inputTokens;
     if (outputTokens) account.usage.totalOutputTokens += outputTokens;
   }
@@ -3581,6 +3627,22 @@ export class AccountManager {
    */
   recordTokenUsage(accountIndex, sessionId, model, usage) {
     if (!usage) return;
+    // A conduit hop is the SAME tokens, translated: the sidecar rebuilt this
+    // report out of the Responses usage the pool sent it, and the pool's own hop
+    // records the original a moment later. Both scopes would double — the two
+    // account rows are distinct, but a session is one row and carries the same
+    // id on both hops, so its context and spend would read twice the truth.
+    //
+    // Dropped rather than deduplicated because there is nothing to deduplicate
+    // against: the two hops are separate requests that share no id, and the
+    // conduit spends nothing of its own anyway (its login is a stub). Booking at
+    // the hop that really spent is what keeps one turn one record.
+    //
+    // Only the ACCOUNT-scoped and SESSION-scoped counters stop here. Per-client
+    // attribution still runs on the inbound hop, in the caller, because that is
+    // the only hop that can see who asked: the outbound one comes from the
+    // sidecar on loopback and carries no client identity at all.
+    if (this._isCodexConduit(this.accounts[accountIndex])) return;
     // The same resolver routing uses, so a token total and a routing decision
     // agree about which family a request belonged to. Resolved here rather than
     // at the call sites: they parse a wire format and have no business knowing

package/src/claude-env.js

@@ -76,6 +76,66 @@ export function mergeNoProxy(...inherited) {
   return out.join(',');
 }
 
+/** The two ways a launched client can reach the proxy. */
+export const CLIENT_MODES = ['mitm', 'base-url'];
+
+/**
+ * Which mode `run` and `env` use: a `--mitm` or `--no-mitm` flag decides, else
+ * the config's `defaultClientMode`, else MITM.
+ *
+ * MITM routes every request of the launched client through the proxy, so the
+ * hard-coded api.anthropic.com endpoints and the Codex CLI (which honours only
+ * proxy variables) are covered. It is also the whole point of the setting: with
+ * `eval "$(teamclaude env)"` the proxy variables are shell-wide, and every other
+ * tool in that shell — gh, git, a package manager — follows them to a listener
+ * that only speaks to two hosts (#382). An operator who lives in such a shell
+ * sets `defaultClientMode: "base-url"` once and opts back in per launch.
+ *
+ * @param {{ defaultClientMode?: string }|null|undefined} config
+ * @param {string[]} flags  the invocation's own arguments
+ * @returns {'mitm'|'base-url'}
+ */
+export function resolveClientMode(config, flags) {
+  const mitm = flags.includes('--mitm');
+  const noMitm = flags.includes('--no-mitm');
+  if (mitm && noMitm) throw new Error('choose either --mitm or --no-mitm');
+  if (mitm) return 'mitm';
+  if (noMitm) return 'base-url';
+  return config?.defaultClientMode === 'base-url' ? 'base-url' : 'mitm';
+}
+
+const SHELL_PROXY_VARS = ['HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'http_proxy', 'https_proxy', 'all_proxy'];
+
+/**
+ * @param {unknown} value
+ * @param {number} port
+ */
+function pointsAtLoopback(value, port) {
+  if (!value) return false;
+  try {
+    const url = new URL(String(value));
+    const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    return ['127.0.0.1', 'localhost', '::1'].includes(host) && Number(url.port || 80) === port;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `unset` lines for proxy variables a previous MITM-mode eval left in the
+ * shell, so re-evaluating in base-URL mode takes the proxy back out of it. Only
+ * a value naming THIS proxy's loopback port is touched: a real corporate proxy
+ * in the same variables is the operator's and stays.
+ *
+ * @param {unknown} port
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+export function clearSelfProxyEnvLines(port, env = process.env) {
+  const checkedPort = validPort(port);
+  return SHELL_PROXY_VARS.filter(name => pointsAtLoopback(env[name], checkedPort)).map(name => `unset ${name}`);
+}
+
 // Build the shell `export` lines that point Claude Code — or any tool that
 // spawns it, e.g. an agent multiplexer — at the proxy. This is the same
 // environment `teamclaude run` sets up, but emitted for `eval "$(teamclaude

package/src/config.js

@@ -101,6 +101,7 @@ export function createDefaultConfig() {
     sessionTitles: { enabled: false, width: 18 },
     projection: { enabled: true, windowMinutes: 90, wasteFloor: 0.1 },
     eventLogging: 'hide',
+    defaultClientMode: 'mitm',
     activityLog: null,
     autoRestart: false,
     blockedModels: [],

package/src/index.js

@@ -31,7 +31,7 @@ import { ensureCerts, mitmHosts } from './mitm.js';
 import { Prober } from './prober.js';
 import { Warmer } from './warmer.js';
 import { createRollingWarmupSchedule, formatWarmupScheduleConfirmation, resolveWarmupConfig, resolveWarmupSchedule } from './warmup-schedule.js';
-import { Sidecar } from './sidecar.js';
+import { Sidecar, SIDECAR_DRAIN_GRACE_MS, SIDECAR_SHUTDOWN_GRACE_MS } from './sidecar.js';
 import { TUI } from './tui.js';
 import { SessionTitles } from './session-titles.js';
 import { RemoteControl, createAttachSession } from './tui-remote.js';
@@ -42,7 +42,7 @@ import { createVersionSource, UpdateWatcher } from './update-watch.js';
 import { renderStatus, formatPercent } from './status-renderer.js';
 import { sanitizeText } from './safe-text.js';
 import { ClientUsageTracker, UsageDimensionTracker } from './client-usage.js';
-import { buildClaudeEnvLines, buildCustomModelAgents, buildCustomModelSettings, buildCustomModelVars, bypassesAllHosts, encodePinComponent, mergeNoProxy } from './claude-env.js';
+import { buildClaudeEnvLines, buildCustomModelAgents, buildCustomModelSettings, buildCustomModelVars, bypassesAllHosts, clearSelfProxyEnvLines, encodePinComponent, mergeNoProxy, resolveClientMode } from './claude-env.js';
 import { serviceKind, installService, uninstallService, serviceStatus, renderService, logPath } from './service.js';
 import { formatTerminalTitle, titleSequence, TITLE_STACK_PUSH, TITLE_STACK_POP } from './terminal-title.js';
 import { getUpstreamProxy, describeProxy, describeSelfProxy } from './upstream-proxy.js';
@@ -474,6 +474,8 @@ async function serverCommand() {
     // Both are read per request off this object (server.js) and the TUI already
     // persists them; without this a hand edit or another writer waited for a restart.
     config.eventLogging = diskConfig.eventLogging || 'hide';
+    // Read by `run`/`env` from disk, but the TUI settings screen shows it live.
+    config.defaultClientMode = diskConfig.defaultClientMode === 'base-url' ? 'base-url' : 'mitm';
     config.blockedModels = Array.isArray(diskConfig.blockedModels) ? diskConfig.blockedModels : [];
     config.projection = diskConfig.projection;
     accountManager.setProjection(config.projection);
@@ -537,6 +539,7 @@ async function serverCommand() {
         // screen too; the server reads them live from `config`, but without this
         // the edit never reached disk and was silently undone by the next start.
         if (config.eventLogging != null) diskConfig.eventLogging = config.eventLogging;
+        if (config.defaultClientMode != null) diskConfig.defaultClientMode = config.defaultClientMode;
         if (config.blockedModels != null) diskConfig.blockedModels = config.blockedModels;
         if (config.sessionTitles != null) diskConfig.sessionTitles = config.sessionTitles;
         // Persist the route table (edited from the TUI routes screen).
@@ -800,7 +803,20 @@ async function serverCommand() {
     prober?.stop();
     warmer?.stop();
     eventLoopMonitor.stop();
-    sidecar?.stop();
+    // Started here, awaited at the end, so the sidecar's grace runs BESIDE the
+    // rest of this teardown instead of after it.
+    //
+    // Forcing, because this path already made that choice for everything else:
+    // it destroys live streaming connections a few lines down and hard-exits on
+    // a timer. The sidecar's first SIGTERM only BEGINS its shutdown, which an
+    // in-flight request holds open, so asking politely and leaving is how a
+    // copy of it outlived the server and kept its port — the exact orphan
+    // Sidecar._reapOrphan then had to clean up on the next start.
+    //
+    // Never rejects by construction; caught anyway, because an unhandled one
+    // between here and the await below would be this process's last word.
+    const sidecarStopped = Promise.resolve(
+      sidecar?.stop({ graceMs: SIDECAR_SHUTDOWN_GRACE_MS, force: true })).catch(() => {});
     if (quotaSaveInterval) clearInterval(quotaSaveInterval);
     await persistQuotaState();
     // Don't linger waiting on keep-alive / streaming connections: actively
@@ -808,7 +824,12 @@ async function serverCommand() {
     // short grace period in case anything still hangs.
     setTimeout(() => process.exit(0), 2000).unref?.();
     server.closeAllConnections?.();
-    server.close(() => process.exit(0));
+    const closed = new Promise(resolve => server.close(() => resolve(undefined)));
+    // Both, not the first of the two. Exiting the moment the listener closed is
+    // what walked out on the sidecar mid-kill; the timer above is still what
+    // guarantees this ends.
+    await Promise.all([closed, sidecarStopped]);
+    process.exit(0);
   }
   process.on('SIGINT', shutdown);
   process.on('SIGTERM', shutdown);
@@ -865,7 +886,13 @@ async function serverCommand() {
       console.log(drained
         ? `[TeamClaude] Drained in ${(waitedMs / 1000).toFixed(1)}s. Restarting on the new build.`
         : `[TeamClaude] ${inFlight} request(s) still in flight after ${(waitedMs / 1000).toFixed(0)}s — restarting anyway.`);
-      sidecar?.stop();
+      // Patient, and awaited: the drain above already proved nothing is in
+      // flight, so one SIGTERM is all this takes and the wait is only there to
+      // bound it. Awaited because the relaunch wants the port a moment later
+      // and this is the only place that can hand it over cleanly. No forcing
+      // signal — the whole point of this path is to cost the fleet nothing, and
+      // a sidecar that somehow outlasts the grace is what _reapOrphan is for.
+      await sidecar?.stop({ graceMs: SIDECAR_DRAIN_GRACE_MS });
       if (quotaSaveInterval) clearInterval(quotaSaveInterval);
       await persistQuotaState();
     } catch (err) {
@@ -1147,7 +1174,13 @@ async function envCommand() {
     process.exit(1);
   }
   const port = config.proxy.port;
-  const useMitm = !args.slice(1).includes('--no-mitm');
+  let useMitm;
+  try {
+    useMitm = resolveClientMode(config, args.slice(1)) === 'mitm';
+  } catch (/** @type {any} */ err) {
+    process.stderr.write(`teamclaude env: ${err.message}\n`);
+    process.exit(1);
+  }
 
   let caPath = null;
   // The leaf has to name every host MITM will intercept, or the CONNECT for
@@ -1166,6 +1199,9 @@ async function envCommand() {
       inheritedNoProxy: [process.env.NO_PROXY, process.env.no_proxy].filter(Boolean).join(','),
       customModels: config.customModels,
     });
+    // Base-URL mode takes the proxy back OUT of a shell an earlier MITM eval
+    // put it into; only this proxy's own loopback address is unset.
+    if (!useMitm) lines.push(...clearSelfProxyEnvLines(port));
   } catch (err) {
     // A bad proxy.port. Nothing reaches stdout: the shell is eval'ing it.
     process.stderr.write(`teamclaude env: ${err.message} (in ${getConfigPath()})\n`);
@@ -1183,7 +1219,9 @@ async function envCommand() {
       process.stderr.write(`# warning: no account named "${account}" in the config — the proxy will refuse this pin\n`);
     }
   }
-  process.stderr.write(`# apply to this shell:  eval "$(teamclaude env${useMitm ? '' : ' --no-mitm'})"\n`);
+  // The flag that reproduces this mode whatever the config's default says.
+  process.stderr.write(`# apply to this shell:  eval "$(teamclaude env${useMitm ? ' --mitm' : ' --no-mitm'})"\n`);
+  process.stderr.write(`# default mode is ${config.defaultClientMode === 'base-url' ? 'base-URL' : 'MITM'} (config defaultClientMode; the TUI settings screen toggles it)\n`);
   if (!(await isProxyUp(port))) {
     process.stderr.write(`# note: proxy not running on port ${port} — start it with: teamclaude server\n`);
   }
@@ -1200,12 +1238,18 @@ async function runCommand() {
   // Args after 'run'. teamclaude flags (e.g. --no-mitm) are recognized only
   // before an optional `--` separator; everything after `--` goes verbatim to
   // claude. MITM forward-proxy mode is the default so hardcoded api.anthropic.com
-  // endpoints are intercepted too; --no-mitm opts back into base-URL-only routing.
-  // --mitm is still accepted (now a no-op) for backward compatibility.
+  // endpoints are intercepted too; the config's `defaultClientMode` can make
+  // base-URL the default instead, and --mitm / --no-mitm decide per launch.
   const rest = args.slice(1);
   const sep = rest.indexOf('--');
   const tcFlags = sep >= 0 ? rest.slice(0, sep) : rest;
-  const useMitm = !tcFlags.includes('--no-mitm');
+  let useMitm;
+  try {
+    useMitm = resolveClientMode(config, tcFlags) === 'mitm';
+  } catch (/** @type {any} */ err) {
+    console.error(`[TeamClaude] ${err.message}`);
+    process.exit(1);
+  }
   const autoFallback = tcFlags.includes('--auto-fallback');
   const claudeArgs = sep >= 0
     ? rest.slice(sep + 1)
@@ -2283,10 +2327,12 @@ Commands:
   login               OAuth login via browser
   login --token       OAuth login via copy/paste (no local callback; for headless/remote)
   login --api         Add an API key account
-  env [--no-mitm]     Print export lines to point Claude Code at the proxy, for
-                      'eval "$(teamclaude env)"' (MITM forward-proxy by default;
-                      --no-mitm for base-URL only). Handy for agent multiplexers
-                      that spawn claude themselves instead of via 'teamclaude run'
+  env [--mitm|--no-mitm]
+                      Print export lines to point Claude Code at the proxy, for
+                      'eval "$(teamclaude env)"'. MITM forward-proxy unless the
+                      config's defaultClientMode is "base-url"; a flag decides
+                      per call. Handy for agent multiplexers that spawn claude
+                      themselves instead of via 'teamclaude run'
   run [--no-mitm] [--auto-fallback] [-- args...]
                       Run Claude Code through the proxy (errors if it's down,
                       unless --auto-fallback launches claude directly instead).

package/src/responses-usage.js

@@ -0,0 +1,131 @@
+// Token usage as OpenAI's Responses API reports it, rewritten into the shape
+// the rest of this proxy books.
+//
+// Every counter here — the account totals, the per-session ones, the per-client
+// ones — speaks Anthropic's usage vocabulary, because that is the only shape
+// this proxy had to read for its first year. Codex traffic is a passthrough, so
+// it arrives in OpenAI's vocabulary instead, and the two disagree in a way that
+// is easy to miss because they share field NAMES:
+//
+//   Anthropic   `input_tokens` is the UNCACHED input. The cached part is
+//               reported separately (`cache_read_input_tokens`,
+//               `cache_creation_input_tokens`) and the three are disjoint — the
+//               readers here add them up to get a context size or a total.
+//
+//   Responses   `input_tokens` is the WHOLE prompt, with the cached part named
+//               again underneath it as `input_tokens_details.cached_tokens`.
+//               Booking it as Anthropic's would count the cached prefix twice
+//               once the cache field is also read, and on Codex traffic that
+//               prefix is most of the prompt.
+//
+// So the subtraction below is the entire point of this file: the cached tokens
+// move out of `input_tokens` and into `cache_read_input_tokens`, leaving three
+// disjoint figures that every existing reader already knows how to add.
+//
+// `output_tokens_details.reasoning_tokens` is NOT added to the output side —
+// it is a breakdown of `output_tokens`, not a second quantity beside it (a real
+// turn: input 54904, output 132 of which 18 reasoning, total_tokens 55036 =
+// 54904 + 132). `input_tokens_details.cache_write_tokens` is likewise left
+// folded into the uncached remainder rather than mapped onto Anthropic's
+// `cache_creation_input_tokens`: a cache write IS fresh input being processed,
+// OpenAI does not bill it at a premium the way Anthropic does, and inventing a
+// fourth disjoint bucket out of a field whose subset relationship is not stated
+// anywhere would risk a total that no longer adds up.
+//
+// Shape confirmed against OpenAI's generated SDK types (`ResponseUsage`), the
+// Codex CLI's own per-turn records, and the sidecar binary that translates this
+// same body for the hop before us.
+
+/** Terminal stream events, the only ones that carry a settled usage object.
+ *
+ *  Named rather than inferred from "the event has a usage object": EVERY
+ *  `response.*` event carries the whole response envelope, so `response.created`
+ *  and `response.in_progress` have a `usage` key too — null today. Reading the
+ *  key would make this proxy's accounting depend on that staying null, and an
+ *  upstream that started reporting progress figures would be counted twice. A
+ *  fixed set of terminal names makes a second report unrepresentable instead.
+ *
+ *  `response.failed` is in the set because a failure that got far enough to
+ *  report figures still spent them; when it carries none — the usual case — the
+ *  normaliser below returns null and nothing is recorded.
+ */
+const TERMINAL_EVENTS = new Set(['response.completed', 'response.incomplete', 'response.failed']);
+
+/**
+ * A wire figure as a non-negative integer. Everything here is untrusted JSON:
+ * a string, a null, a NaN or a negative count must read as "nothing reported"
+ * rather than poison a cumulative total that is never recomputed.
+ *
+ * @param {unknown} v
+ * @returns {number}
+ */
+function count(v) {
+  return typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.trunc(v) : 0;
+}
+
+/**
+ * A Responses `usage` object in Anthropic's disjoint shape, or null when there
+ * is nothing to record.
+ *
+ * Null for an absent, non-object or all-zero usage, because the recorders
+ * downstream treat a written record as an observation that happened: an
+ * all-zero one would claim a report arrived and count against `reports`, which
+ * is the one thing that distinguishes "upstream told us nothing" from "upstream
+ * told us zero".
+ *
+ * @param {any} usage
+ * @returns {{input_tokens: number, output_tokens: number, cache_read_input_tokens: number}|null}
+ */
+export function normalizeResponsesUsage(usage) {
+  if (!usage || typeof usage !== 'object') return null;
+  const prompt = count(usage.input_tokens);
+  const output = count(usage.output_tokens);
+  // Clamped to the prompt it is a part of. Upstream cannot report more cached
+  // tokens than input tokens, but the uncached remainder is a subtraction, and
+  // an unclamped one would go negative and silently shrink a lifetime total.
+  const cached = Math.min(count(usage.input_tokens_details?.cached_tokens), prompt);
+  if (!prompt && !output) return null;
+  return {
+    input_tokens: prompt - cached,
+    output_tokens: output,
+    cache_read_input_tokens: cached,
+  };
+}
+
+/**
+ * Usage from one parsed SSE event of a Responses stream, or null when this
+ * event is not a terminal one (the common case — a stream is mostly deltas).
+ *
+ * @param {any} event
+ */
+export function responsesEventUsage(event) {
+  if (!event || !TERMINAL_EVENTS.has(event.type)) return null;
+  return normalizeResponsesUsage(event.response?.usage);
+}
+
+/**
+ * Usage from a NON-streaming Responses body, or null when the body is not one.
+ *
+ * Two independent tells, either of which is enough, and neither of which an
+ * Anthropic message body can produce:
+ *
+ *   `object: "response"`     what the Responses envelope calls itself.
+ *   `input_tokens_details`   present exactly when a prompt-cache breakdown is
+ *                            reported, which is the case that actually needs
+ *                            rewriting.
+ *
+ * Both, rather than either alone, because the first is the honest discriminator
+ * while the second is the one that matters: a Responses body that reports no
+ * cache breakdown at all needs no rewriting — its `input_tokens` is already
+ * uncached input — so a body that somehow shows neither tell is read as
+ * Anthropic's and lands on exactly the same numbers it would have anyway.
+ *
+ * @param {any} json
+ */
+export function responsesBodyUsage(json) {
+  if (!json || typeof json !== 'object') return null;
+  const usage = json.usage;
+  const tagged = json.object === 'response'
+    || (usage != null && typeof usage === 'object' && usage.input_tokens_details != null);
+  return tagged ? normalizeResponsesUsage(usage) : null;
+}

package/src/server.js

@@ -19,6 +19,7 @@ import { safeLine } from './safe-text.js';
 import { forwardRefusal, guardedLookup, FORBIDDEN_FORWARD } from './forward-target.js';
 import { renderDashboardHtml, dashboardCsp } from './dashboard.js';
 import { createUsageRecorder, resolveUsageDimensions, usageDimensionHeaderNames } from './client-usage.js';
+import { responsesEventUsage, responsesBodyUsage } from './responses-usage.js';
 import { classificationPath } from './classification-path.js';
 /** @typedef {import('./types.js').CodedError} CodedError */
 
@@ -3041,8 +3042,24 @@ export function createSseLineScanner(onLine, maxChars = SSE_MAX_LINE_CHARS) {
 // over. One record per message is what makes double counting unrepresentable
 // rather than merely avoided.
 //
-// Reads one `data:` line. Anthropic's events carry exactly one, so a line is an
-// event for this purpose, and the scanner above never has to hold more.
+// A Responses stream (the Codex path) instead reports once, at the end, and in
+// OpenAI's own vocabulary — so it is rewritten into Anthropic's disjoint shape
+// before it reaches either counter (src/responses-usage.js explains why the two
+// disagree). It rides this function rather than a parser of its own because the
+// line is ALREADY parsed here: the branch costs a Set lookup on a string, not a
+// second pass over the stream. Nothing else would be cheap — a Responses stream
+// is mostly text deltas, and the settled figures arrive on one event near the end
+// with no header or marker to find it by.
+//
+// Reads one `data:` line. Both dialects carry exactly one per event, so a line
+// is an event for this purpose, and the scanner above never has to hold more.
+/**
+ * @param {string} line
+ * @param {number} accountIndex
+ * @param {any} accountManager
+ * @param {((inputTokens: number, outputTokens: number) => void)|null} [onUsage]
+ * @param {Record<string, any>|null} [merged]
+ */
 function parseSSEDataLine(line, accountIndex, accountManager, onUsage = null, merged = null) {
   if (!line.startsWith('data: ')) return;
 
@@ -3056,6 +3073,15 @@ function parseSSEDataLine(line, accountIndex, accountManager, onUsage = null, me
       accountManager.updateUsage(accountIndex, 0, data.usage.output_tokens);
       onUsage?.(0, data.usage.output_tokens || 0);
       if (merged) Object.assign(merged, data.usage);
+    } else {
+      // Both sides settle at once here, so unlike the Anthropic branches above
+      // this is a single incremental update rather than one per side.
+      const usage = responsesEventUsage(data);
+      if (usage) {
+        accountManager.updateUsage(accountIndex, usage.input_tokens, usage.output_tokens);
+        onUsage?.(usage.input_tokens, usage.output_tokens);
+        if (merged) Object.assign(merged, usage);
+      }
     }
   } catch {
     // not valid JSON, skip
@@ -3066,9 +3092,16 @@ function extractUsageFromBody(buffer, accountIndex, accountManager, onUsage = nu
   try {
     const json = JSON.parse(buffer.toString());
     if (json.usage) {
-      accountManager.updateUsage(accountIndex, json.usage.input_tokens, json.usage.output_tokens);
-      onUsage?.(json.usage.input_tokens || 0, json.usage.output_tokens || 0);
-      accountManager.recordTokenUsage(accountIndex, sessionId, model, json.usage);
+      // A buffered Responses body reports under the same two field NAMES with a
+      // different meaning, so reading it as Anthropic's would book the cached
+      // prefix as fresh input and never book it as a cache read at all. Only a
+      // body that says it is one is rewritten; anything else — including a
+      // Responses body carrying no figures to rewrite — falls through to the
+      // reading this had before, unchanged.
+      const usage = responsesBodyUsage(json) || json.usage;
+      accountManager.updateUsage(accountIndex, usage.input_tokens, usage.output_tokens);
+      onUsage?.(usage.input_tokens || 0, usage.output_tokens || 0);
+      accountManager.recordTokenUsage(accountIndex, sessionId, model, usage);
     }
   } catch {
     // not JSON or no usage