openzoo 0.49.9 → 0.49.10

package/lib/launch.js

@@ -1,15 +1,13 @@
 /**
- * `npx openzoo claude [args...]` — install and/or launch `openzoo-claude`
- * (the staccDOTsol fork of open-claude-code) already pointed at the local zoo.
+ * `npx openzoo claude [args...]` — launch Claude Code (or any Anthropic-shaped
+ * harness) already pointed at the local zoo, so its inference is paid per turn
+ * over x402 instead of hitting Anthropic directly.
  *
- * This is the supported front door. We exec that package's binary
- * (`openzoo-claude` / `occ` / its `claude` bin), never Anthropic's bun
- * `~/.local/bin/claude`. First run prefers `npx -y openzoo-claude` so there
- * is no global-install dance and no official Anthropic installer.
- *
- * ANTHROPIC_BASE_URL is the env the harness reads at startup. The proxy
- * serves POST /v1/messages (see lib/anthropic.js). We boot :8402 first if
- * needed, then spawn with the same zoo env pair — no second key/url pair.
+ * This is the supported front door: ANTHROPIC_BASE_URL is an official env var
+ * Claude Code reads at startup. No DNS games, no TLS interception — the proxy
+ * serves POST /v1/messages (see lib/anthropic.js) and this just spawns the
+ * harness with the two env vars set. The proxy must already be running
+ * (`npx openzoo` in another terminal); we check first and say so if not.
  */
 import { spawn, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
@@ -60,9 +58,8 @@ function resolveClaudeDesktop() {
   return null;
 }
 
-/** Extra bin dirs (Homebrew, ~/.local/bin, npm-global-ish). Finder-launched
- *  grokui has no ~/.zshrc PATH, so PATH-only lookup misses user bins. We
- *  still scan these for `openzoo-claude` / `occ` — not for Anthropic bun. */
+/** Dirs Claude's install.sh uses, plus Homebrew. Finder-launched grokui
+ *  has no ~/.zshrc PATH, so PATH-only lookup misses `~/.local/bin/claude`. */
 export function claudeCodeBinDirs(home = os.homedir()) {
   return [
     path.join(home, '.local', 'bin'),
@@ -71,141 +68,19 @@ export function claudeCodeBinDirs(home = os.homedir()) {
   ];
 }
 
-export const OPENZOO_CLAUDE_PACKAGE = 'openzoo-claude';
-
-function exeName(name) {
-  return name + (process.platform === 'win32' ? '.cmd' : '');
-}
-
-function isExecutable(file) {
-  try { fs.accessSync(file, fs.constants.X_OK); return true; } catch { return false; }
-}
-
-function readHeadBytes(file, n = 8192) {
-  const fd = fs.openSync(file, 'r');
-  try {
-    const buf = Buffer.alloc(n);
-    const got = fs.readSync(fd, buf, 0, n, 0);
-    return buf.subarray(0, got);
-  } finally {
-    fs.closeSync(fd);
-  }
-}
-
-function isNativeBinary(buf) {
-  if (!buf || buf.length < 2) return false;
-  if (buf[0] === 0x7f && buf[1] === 0x45 && buf[2] === 0x4c && buf[3] === 0x46) return true; // ELF
-  if (buf[0] === 0x4d && buf[1] === 0x5a) return true; // PE
-  if (buf.length >= 4) {
-    const mag = buf.readUInt32BE(0);
-    // Mach-O 32/64 + fat (incl. byte-swapped).
-    if (mag === 0xfeedface || mag === 0xfeedfacf || mag === 0xcafebabe
-      || mag === 0xcffaedfe || mag === 0xcefaedfe) return true;
-  }
-  return false;
-}
-
-/** True for Anthropic's bun `claude` (install.sh standalone or bun shebang). */
-export function isAnthropicBunClaude(filePath) {
-  try {
-    const buf = readHeadBytes(filePath, 512);
-    if (isNativeBinary(buf)) return true;
-    const shebang = buf.toString('utf8').split(/\r?\n/, 1)[0] || '';
-    return shebang.startsWith('#!') && /\bbun\b/i.test(shebang);
-  } catch {
-    return false;
-  }
-}
-
-/** True when this file is the openzoo-claude package (name, realpath, or shim). */
-export function isOpenzooClaudeBin(filePath) {
-  try {
-    const real = fs.realpathSync(filePath);
-    if (/(?:^|[\\/])openzoo-claude(?:[\\/]|$)/i.test(real)) return true;
-    if (isAnthropicBunClaude(real)) return false;
-    const buf = readHeadBytes(real, 8192);
-    if (isNativeBinary(buf)) return false;
-    return buf.toString('utf8').includes('openzoo-claude');
-  } catch {
-    return false;
-  }
-}
-
-function pathSearchDirs(env = process.env) {
-  const extras = env.OPENZOO_CLAUDE_PATH_ONLY === '1'
-    ? []
-    : claudeCodeBinDirs(env.HOME || os.homedir());
+/** Resolve the Claude Code TERMINAL CLI. */
+export function resolveClaudeCli(env = process.env) {
+  const name = 'claude' + (process.platform === 'win32' ? '.cmd' : '');
+  const extras = env.OPENZOO_CLAUDE_PATH_ONLY === '1' ? [] : claudeCodeBinDirs();
   const pathDirs = String(env.PATH || '').split(path.delimiter).filter(Boolean);
-  return [...new Set([...extras, ...pathDirs])].filter(Boolean);
-}
-
-function findNamedBin(name, env, { requireOpenzoo = false } = {}) {
-  const bin = exeName(name);
-  for (const dir of pathSearchDirs(env)) {
-    const f = path.join(dir, bin);
-    if (!isExecutable(f)) continue;
-    if (requireOpenzoo && !isOpenzooClaudeBin(f)) continue;
-    return f;
+  for (const dir of [...new Set([...extras, ...pathDirs])]) {
+    if (!dir) continue;
+    const f = path.join(dir, name);
+    try { fs.accessSync(f, fs.constants.X_OK); return f; } catch { /* next */ }
   }
   return null;
 }
 
-export function resolveNpx(env = process.env) {
-  return findNamedBin('npx', env);
-}
-
-/**
- * Resolve the openzoo-claude TERMINAL CLI.
- * Prefers `openzoo-claude`, then package `occ`, then that package's `claude`
- * bin. Never returns Anthropic bun `~/.local/bin/claude`.
- */
-export function resolveClaudeCli(env = process.env) {
-  const named = findNamedBin('openzoo-claude', env);
-  if (named) return named;
-  const occ = findNamedBin('occ', env, { requireOpenzoo: true });
-  if (occ) return occ;
-  const pkgClaude = findNamedBin('claude', env, { requireOpenzoo: true });
-  if (pkgClaude) return pkgClaude;
-  return null;
-}
-
-/**
- * Path hit or `npx -y openzoo-claude` fallback. Null only when neither the
- * package nor npx is available.
- */
-export function resolveOpenzooClaude(env = process.env) {
-  const cli = resolveClaudeCli(env);
-  if (cli) return { command: cli, prefixArgs: [], via: 'path' };
-  const npx = resolveNpx(env);
-  if (npx) return { command: npx, prefixArgs: ['-y', OPENZOO_CLAUDE_PACKAGE], via: 'npx' };
-  return null;
-}
-
-/** Spawn argv for `openzoo claude [args]` — `--help` execs openzoo-claude. */
-export function claudeSpawnSpec(argv = [], env = process.env) {
-  const rest = argv.filter((a) => !['--terminal', '-t', '--desktop'].includes(a));
-  const resolved = resolveOpenzooClaude(env);
-  if (!resolved) return null;
-  return {
-    command: resolved.command,
-    args: [...resolved.prefixArgs, ...rest],
-    via: resolved.via,
-  };
-}
-
-function zooAuthToken(baseEnv) {
-  if (baseEnv.ANTHROPIC_AUTH_TOKEN) return baseEnv.ANTHROPIC_AUTH_TOKEN;
-  const envKey = String(baseEnv.OPENZOO_SUBSCRIPTION_KEY || '').trim();
-  if (envKey) return envKey;
-  const file = baseEnv.OPENZOO_SUBSCRIPTION_PATH
-    || path.join(baseEnv.HOME || os.homedir(), '.openzoo', 'subscription.json');
-  try {
-    const key = String(JSON.parse(fs.readFileSync(file, 'utf8'))?.key || '').trim();
-    if (key) return key;
-  } catch { /* no subscription file */ }
-  return 'sk-openzoo';
-}
-
 /**
  * The same env `openzoo claude` writes: gateway auth at the local proxy,
  * Anthropic API key UNSET (it would bill api.anthropic.com), catalog
@@ -218,8 +93,8 @@ export function claudeZooEnv(baseEnv = process.env, { base, port } = {}) {
   const env = { ...baseEnv };
   delete env.ANTHROPIC_API_KEY;
   env.ANTHROPIC_BASE_URL = url;
-  env.ANTHROPIC_AUTH_TOKEN = zooAuthToken(baseEnv);
-  const extras = claudeCodeBinDirs(baseEnv.HOME || os.homedir()).filter((d) => {
+  env.ANTHROPIC_AUTH_TOKEN = baseEnv.ANTHROPIC_AUTH_TOKEN || 'sk-openzoo';
+  const extras = claudeCodeBinDirs().filter((d) => {
     try { return fs.existsSync(d); } catch { return false; }
   });
   const pathDirs = String(env.PATH || '').split(path.delimiter).filter(Boolean);
@@ -258,9 +133,9 @@ export function claudeZooEnv(baseEnv = process.env, { base, port } = {}) {
 }
 
 /**
- * `npx openzoo claude [args]` — launch openzoo-claude on the zoo.
- * Terminal (openzoo-claude) is the default; `--desktop` opens the Anthropic app.
- * Both get the same zoo env pair so inference pays x402 / subscription.
+ * `npx openzoo claude [dir] [--terminal]` — launch Claude on the zoo.
+ * DEFAULT is the desktop app; `--terminal` (or `-t`) runs the Claude Code CLI.
+ * Both get ANTHROPIC_BASE_URL so inference pays x402.
  */
 export async function launchClaude(argv) {
   // let, not const: startProxy can heal onto a different port and every URL
@@ -356,13 +231,8 @@ export async function launchClaude(argv) {
   const env = claudeZooEnv(process.env, { base });
 
   if (terminal) {
-    const spec = claudeSpawnSpec(argv, env);
-    if (!spec) {
-      console.error('openzoo: openzoo-claude not found and npx is unavailable.');
-      console.error('  install:  npx -y openzoo-claude');
-      console.error('  or:       npm i -g openzoo-claude');
-      process.exit(1);
-    }
+    const cli = resolveClaudeCli();
+    if (!cli) { console.error('openzoo: `claude` CLI not found on PATH — install Claude Code, or drop --terminal for the desktop app'); process.exit(1); }
     // ALWAYS-ON HUD via Claude Code's NATIVE status line (the title bar is owned
     // by Claude Code and gets overwritten, so OSC there is useless). We write a
     // tiny status script that reads the proxy's /v1/info, and merge a statusLine
@@ -472,17 +342,17 @@ export async function launchClaude(argv) {
     let wallet = '';
     try { const { PayClient } = await import('./pay.js'); wallet = new PayClient().address; } catch { /* optional */ }
     console.error('');
-    console.error('  \x1b[38;5;208m●\x1b[0m openzoo — this openzoo-claude session routes through the zoo');
+    console.error('  \x1b[38;5;208m●\x1b[0m openzoo — this Claude Code session routes through the zoo');
     console.error(`     endpoint : ${base}`);
-    console.error('     models   : GET /v1/models (quoteable catalog — Claude /model includes OpenRouter ids + Auto)');
+    console.error('     models   : GET /v1/models (quoteable ids only — Claude /model is a short picker + Auto)');
     console.error('     auth     : gateway token (ANTHROPIC_API_KEY unset — no api.anthropic.com billing)');
     if (wallet) console.error(`     wallet   : ${wallet}`);
     console.error('     spend    : live in the status line below (bottom of screen); receipts in ~/.openzoo/proxy.log');
     console.error('     every turn pays x402.');
     console.error('');
-    const child = spawn(spec.command, spec.args, { stdio: 'inherit', env });
+    const child = spawn(cli, rest, { stdio: 'inherit', env });
     child.on('exit', (c) => { try { restoreStatus?.(); } catch { /* ignore */ } process.exit(c ?? 0); });
-    child.on('error', (e) => { console.error(`openzoo: could not launch openzoo-claude: ${e.message}`); process.exit(1); });
+    child.on('error', (e) => { console.error(`openzoo: could not launch claude: ${e.message}`); process.exit(1); });
     return;
   }
 

package/lib/models.js

@@ -366,6 +366,59 @@ export function publishModelList(payload, opts) {
   };
 }
 
+function modelVersionKey(id) {
+  const m = String(id || '').match(/(\d+(?:\.\d+)*)/g);
+  if (!m) return [0];
+  return m[0].split('.').map((n) => Number(n) || 0);
+}
+
+function cmpModelVersion(a, b) {
+  const ka = modelVersionKey(a);
+  const kb = modelVersionKey(b);
+  for (let i = 0; i < Math.max(ka.length, kb.length); i++) {
+    const d = (kb[i] || 0) - (ka[i] || 0);
+    if (d) return d;
+  }
+  return String(a).localeCompare(String(b));
+}
+
+function newestMatching(ids, pred) {
+  const hits = ids.filter((id) => pred(id) && !String(id).includes(':') && !/-fast(?:$|:)/i.test(id));
+  hits.sort(cmpModelVersion);
+  return hits[0] || null;
+}
+
+/** Preferred gateway flagships for the Claude Code picker, if quoteable. */
+export const CLAUDE_PICKER_GATEWAY = [
+  { prefer: 'x-ai/grok-4.6', re: /^x-ai\/grok-/ },
+  { prefer: 'google/gemini-3.7-flash', re: /^google\/gemini-/ },
+  { prefer: 'deepseek/deepseek-v4-pro-0813', re: /^deepseek\// },
+  { prefer: 'qwen/qwen3.8-2.4t-a95b', re: /^qwen\// },
+];
+
+/**
+ * Short honest Claude Code /model list: current Opus/Sonnet/Haiku/Fable
+ * plus a few real gateway models plus Auto. Only ids already in `rows`.
+ */
+export function pickClaudePickerRows(rows) {
+  const list = Array.isArray(rows) ? rows : [];
+  const byId = new Map(list.map((m) => [m.id, m]));
+  const ids = list.map((m) => m.id);
+  const picked = [];
+  const add = (id) => {
+    if (id && byId.has(id) && !picked.includes(id)) picked.push(id);
+  };
+  add(newestMatching(ids, (id) => /^anthropic\/claude-opus/.test(id)));
+  add(newestMatching(ids, (id) => /^anthropic\/claude-sonnet/.test(id)));
+  add(newestMatching(ids, (id) => /claude-(?:3-)?haiku/.test(id)));
+  add(newestMatching(ids, (id) => /^anthropic\/claude-fable/.test(id)));
+  for (const { prefer, re } of CLAUDE_PICKER_GATEWAY) {
+    add(ids.includes(prefer) ? prefer : newestMatching(ids, (id) => re.test(id)));
+  }
+  add(AUTO_MODEL_ID);
+  return picked.map((id) => byId.get(id)).filter(Boolean);
+}
+
 function anthropicRows(rows) {
   return rows.map((m) => ({
     type: 'model',
@@ -376,27 +429,14 @@ function anthropicRows(rows) {
   }));
 }
 
-/** openzoo/auto first so Claude Code's picker default is the router, not opus. */
-function withAutoFirst(rows) {
-  const list = Array.isArray(rows) ? rows.slice() : [];
-  const i = list.findIndex((m) => isAutoModel(m?.id));
-  if (i > 0) {
-    const [auto] = list.splice(i, 1);
-    list.unshift(auto);
-  }
-  return list;
-}
-
 /**
  * Anthropic GET /v1/models shape (id + display_name + type).
  * Claude Code gateway discovery reads `data[].id` and optional `display_name`.
- * Full quoteable catalog — every priced published id, including OpenRouter
- * grok/gemini/gpt rows. Not a 4-id Anthropic cap, not openzoo-* clones.
- * Picker ≠ classifier: rewriteChatModel still pins 16-token classify off opus-5.
+ * Short picker — not the 300+ OpenRouter dump and not openzoo-* clones.
  */
 export function anthropicModelList(payload) {
   const published = publishModelList(payload, { aliases: false });
-  const data = anthropicRows(withAutoFirst(published.data || []));
+  const data = anthropicRows(pickClaudePickerRows(published.data || []));
   return {
     data,
     has_more: false,
@@ -416,10 +456,8 @@ export function wantsAnthropicModelList(headers = {}) {
 
 /**
  * Body for GET /v1/models. Quoteable catalog only (never opus-5-only, never
- * unpriced / :batch / openzoo-* clones). Anthropic-shaped clients get the
- * same quoteable ids in Anthropic shape (type / id / display_name) so Claude
- * Code can select grok, gemini, gpt, etc. OpenAI clients keep object:list
- * of every quoteable id + harness aliases.
+ * the raw OpenRouter dump). Anthropic-shaped clients get the short picker;
+ * OpenAI clients keep object:list of every quoteable id + harness aliases.
  */
 export function modelsListForRequest(payload, headers) {
   return wantsAnthropicModelList(headers) ? anthropicModelList(payload) : publishModelList(payload);

package/lib/proxy.js

@@ -30,6 +30,7 @@ import { injectBrief } from './brief.js';
 import { withNamespace } from './namespace.js';
 import { anthropicToOpenAI, openAIToAnthropic, streamOpenAIToAnthropic, writeAnthropicSse } from './anthropic.js';
 import { responsesToChat, chatToResponses, writeResponsesSse } from './responses.js';
+import { streamOpenAIToResponses } from './responses-stream.js';
 import { loadSessionSpend, saveSessionSpend } from './session.js';
 import { creditBalance, quotedPrices } from './info.js';
 import { subscriptionPublicView } from './subscription.js';
@@ -37,7 +38,6 @@ import { priceHoldings } from './livestatus.js';
 import { receiptUsedCogs, receiptDirectUsd, pairActualBilled } from './racesettle.js';
 import { rewriteWrapClientError } from './wrap.js';
 import { fetchHeaders } from './fetch.js';
-import { relay } from './relay.js';
 
 const HOP_BY_HOP = new Set([
   'host', 'connection', 'keep-alive', 'transfer-encoding', 'upgrade',
@@ -87,6 +87,46 @@ async function readBody(req) {
   return Buffer.concat(chunks);
 }
 
+/** Pipe an upstream fetch Response to the client, unbuffered (SSE-safe).
+ *
+ *  `onReceipt` is called with the gateway's x402 block when it arrives. On a
+ *  STREAMED call there is no JSON body to carry that block, so the gateway
+ *  emits it as an SSE COMMENT (`: x402 {...}`) after the last frame — comments
+ *  are discarded by every compliant client, so nothing downstream sees it, but
+ *  without reading it here every spend and savings figure on the status line
+ *  would silently read zero the moment real streaming was switched on.
+ *
+ *  Sniffing NEVER delays a byte: each chunk is written to the client first and
+ *  only then scanned. */
+function relay(res, upstream, onReceipt) {
+  const headers = {};
+  upstream.headers.forEach((v, k) => {
+    if (!['transfer-encoding', 'connection', 'content-encoding', 'content-length'].includes(k)) headers[k] = v;
+  });
+  res.writeHead(upstream.status, headers);
+  if (!upstream.body) { res.end(); return Promise.resolve(); }
+  const sse = (upstream.headers.get('content-type') || '').includes('text/event-stream');
+  return new Promise((resolve) => {
+    const body = Readable.fromWeb(upstream.body);
+    body.on('error', () => res.destroy());
+    res.on('close', () => body.destroy());
+    body.on('end', resolve);
+    if (!sse || typeof onReceipt !== 'function') { body.pipe(res); return; }
+    let pending = '';
+    body.on('data', (c) => {
+      res.write(c);
+      pending += c.toString('utf8');
+      const lines = pending.split('\n');
+      pending = lines.pop() ?? '';   // a comment can straddle two chunks
+      for (const line of lines) {
+        if (!line.startsWith(': x402 ')) continue;
+        try { onReceipt(JSON.parse(line.slice(7))); } catch { /* not our frame */ }
+      }
+    });
+    body.on('end', () => res.end());
+  });
+}
+
 function jsonErr(res, status, message, extraFields = {}) {
   res.writeHead(status, { 'content-type': 'application/json' });
   res.end(JSON.stringify({ error: { message }, ...extraFields }));
@@ -779,9 +819,6 @@ async function maybeCacheCorpus(req, bodyBuf, log, stats, extra = {}) {
  * default, so localhost behaviour is unchanged.
  */
 export async function startProxy({ silent = false, requireToken = null, sessionMaxUsd = null, autoTunnel = false } = {}) {
-  // grokui's packed sidecar spawn sets OPENZOO_SILENT=1 so 400s land in
-  // ~/.openzoo/proxy.log instead of Electron's inherited /dev/null.
-  if (process.env.OPENZOO_SILENT === '1') silent = true;
   const client = new PayClient();
   const log = silent ? () => {} : (...a) => console.log(...a);
   // ALWAYS-ON. `silent: true` is used by the editor path to keep startup tidy,
@@ -1241,7 +1278,11 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         }
         responsesModel = inbound.model;
         const meta = {};
-        bodyBuf = Buffer.from(JSON.stringify(responsesToChat(inbound, meta)));
+        const translated = responsesToChat(inbound, meta);
+        // Codex's watchdog is ~10s to first SSE byte. Force stream so we can
+        // emit response.created immediately instead of buffering Opus.
+        translated.stream = true;
+        bodyBuf = Buffer.from(JSON.stringify(translated));
         responsesCustom = meta.custom;
         responsesMode = true;
         req.url = '/v1/chat/completions';
@@ -1816,6 +1857,39 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         say(`credit -> $${x.billedUsd.toFixed(6)}  ·  session $${sessionSpent.toFixed(6)}`);
       };
 
+      // RESPONSES CLIENTS (Codex Security) GET THE SAME STREAM, IN THEIR GRAMMAR.
+      // Without this, relay() pipes OpenAI SSE frames at a client waiting for
+      // response.created, and the 10s watchdog fires ("connection interrupted").
+      if (responsesMode && wantsStream
+          && (response.headers.get('content-type') || '').includes('text/event-stream')
+          && response.ok && response.body) {
+        const tr = streamOpenAIToResponses(res, response, responsesModel, responsesCustom);
+        let pending = '';
+        const body = Readable.fromWeb(response.body);
+        res.on('close', () => body.destroy());
+        try {
+          for await (const c of body) {
+            pending += c.toString('utf8');
+            const lines = pending.split('\n');
+            pending = lines.pop() ?? '';
+            for (const line of lines) {
+              if (line.startsWith(': x402 ')) {
+                try { meterStreamed(JSON.parse(line.slice(7))); } catch { /* not ours */ }
+                continue;
+              }
+              if (!line.startsWith('data:')) continue;
+              const payload = line.slice(5).trim();
+              if (!payload || payload === '[DONE]') continue;
+              try { tr.onChunk(JSON.parse(payload)); } catch { /* frame split */ }
+            }
+          }
+        } catch (e) {
+          log(`responses stream aborted: ${e.message}`);
+        }
+        tr.finish();
+        return;
+      }
+
       // ANTHROPIC CLIENTS GET THE SAME STREAM, IN THEIR OWN GRAMMAR.
       // Translated frame by frame rather than buffered, so Claude Code sees
       // tokens as they are produced instead of nothing until the turn ends.

package/lib/racesettle.js

@@ -255,7 +255,16 @@ export function isQuoteReserveBilled(billed, cost, x = {}) {
  * savings). Never return the reserve when we learned the real upstream cost.
  */
 export function receiptSettledBilled(x, usage) {
-  const cost = money(usage?.cost) ?? money(x?.actualUsd) ?? money(usage?.actualUsd);
+  // The gateway now sets `usage.billedUsd` explicitly, and it is exactly the
+  // settled figure this function spends the rest of its body reconstructing
+  // from tokens and prices. Take it when it is there; the reconstruction below
+  // stays for older gateways and for the race path, which has no single
+  // billed number of its own.
+  const direct = money(usage?.billedUsd);
+  if (direct != null) return direct;
+  // See pairActualBilled: `usage.cost` is our price now, not upstream's.
+  const cost = money(usage?.cost_details?.upstream_inference_cost)
+    ?? money(usage?.cost) ?? money(x?.actualUsd) ?? money(usage?.actualUsd);
   const explicit = explicitSettledBilled(x, usage);
   if (explicit != null) return explicit;
 
@@ -295,7 +304,19 @@ function settledSavedUsd(x, cost) {
  * twin. Null when this call did not report a real cost — do not mix populations.
  */
 export function pairActualBilled(x402, usage) {
-  const fromUsage = money(usage?.cost);
+  // `usage.cost` IS NO LONGER THE UPSTREAM FIGURE. The gateway now reports OUR
+  // price there, because that is the field every generic OpenAI-compatible
+  // client reads and they were all showing what OpenRouter charged us instead
+  // of what the caller was charged. The upstream number moved to
+  // `cost_details.upstream_inference_cost`, which is where OpenRouter itself
+  // publishes it.
+  //
+  // This is the HUD's DENOMINATOR, so reading the new `usage.cost` here would
+  // divide billed by billed and print 1× on every call regardless of markup.
+  // Prefer the explicit upstream field; fall back to `usage.cost` only for
+  // responses from a gateway old enough to predate the move.
+  const fromUpstream = money(usage?.cost_details?.upstream_inference_cost);
+  const fromUsage = fromUpstream ?? money(usage?.cost);
   const fromX = money(x402?.actualUsd) ?? money(x402?.usage?.cost);
   const upstreamUsd = fromUsage ?? fromX;
   if (upstreamUsd == null) return null;