@askalf/dario 6.0.30 → 6.0.32

package/dist/analytics.d.ts

@@ -83,6 +83,13 @@ export declare const CODEX_CLAIM = "chatgpt_subscription";
  * cache-TTL discussion turns on. Output tokens are excluded from the ratio
  * (they are never cacheable). Pure + total-zero-safe for unit testing.
  */
+/**
+ * Share of PROMPT tokens served from cache: cache_read / (input + cache_read +
+ * cache_create), as a percentage with two decimals (the same rounding as
+ * subscriptionPercent). Output tokens are excluded; they are never cacheable.
+ * Zero-safe. The single definition behind the summary's cache fields.
+ */
+export declare function cachedPromptPercent(inputTokens: number, cacheReadTokens: number, cacheCreateTokens: number): number;
 export declare function formatUsageLogLine(requestCount: number, u: {
     inputTokens?: number;
     outputTokens?: number;
@@ -200,6 +207,10 @@ interface PerAccountStat {
     requests: number;
     inputTokens: number;
     outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreateTokens: number;
+    /** Share of this account's prompt tokens served from cache (see cachedPromptPercent). */
+    cachedPromptPercent: number;
     estimatedCost: number;
     currentUtil5h: number;
     currentUtil7d: number;
@@ -210,12 +221,25 @@ interface PerModelStat {
     avgInputTokens: number;
     avgOutputTokens: number;
     avgThinkingTokens: number;
+    avgCacheReadTokens: number;
+    avgCacheCreateTokens: number;
+    /** Share of this model's prompt tokens served from cache (see cachedPromptPercent). */
+    cachedPromptPercent: number;
     estimatedCost: number;
 }
 interface WindowStats {
     totalInputTokens: number;
     totalOutputTokens: number;
     totalThinkingTokens: number;
+    totalCacheReadTokens: number;
+    totalCacheCreateTokens: number;
+    /**
+     * Share of prompt tokens served from cache across the window. The number
+     * that says whether a long-running session is being re-billed its prefix
+     * every turn (dario#678). Until now readable only off a -v console, one
+     * request at a time, and never for the codex engine at all.
+     */
+    cachedPromptPercent: number;
     estimatedCost: number;
     avgLatencyMs: number;
     errorRate: number;

package/dist/analytics.js

@@ -89,6 +89,16 @@ export const CODEX_CLAIM = 'chatgpt_subscription';
  * cache-TTL discussion turns on. Output tokens are excluded from the ratio
  * (they are never cacheable). Pure + total-zero-safe for unit testing.
  */
+/**
+ * Share of PROMPT tokens served from cache: cache_read / (input + cache_read +
+ * cache_create), as a percentage with two decimals (the same rounding as
+ * subscriptionPercent). Output tokens are excluded; they are never cacheable.
+ * Zero-safe. The single definition behind the summary's cache fields.
+ */
+export function cachedPromptPercent(inputTokens, cacheReadTokens, cacheCreateTokens) {
+    const promptTotal = inputTokens + cacheReadTokens + cacheCreateTokens;
+    return promptTotal > 0 ? Math.round((cacheReadTokens / promptTotal) * 10000) / 100 : 0;
+}
 export function formatUsageLogLine(requestCount, u) {
     const inp = u.inputTokens ?? 0;
     const out = u.outputTokens ?? 0;
@@ -275,6 +285,7 @@ export class Analytics extends EventEmitter {
         if (records.length === 0) {
             return {
                 totalInputTokens: 0, totalOutputTokens: 0, totalThinkingTokens: 0,
+                totalCacheReadTokens: 0, totalCacheCreateTokens: 0, cachedPromptPercent: 0,
                 estimatedCost: 0, avgLatencyMs: 0, errorRate: 0,
                 claimBreakdown: {},
                 billingBucketBreakdown: {
@@ -290,6 +301,8 @@ export class Analytics extends EventEmitter {
         const totalInput = records.reduce((s, r) => s + r.inputTokens, 0);
         const totalOutput = records.reduce((s, r) => s + r.outputTokens, 0);
         const totalThinking = records.reduce((s, r) => s + r.thinkingTokens, 0);
+        const totalCacheRead = records.reduce((s, r) => s + r.cacheReadTokens, 0);
+        const totalCacheCreate = records.reduce((s, r) => s + r.cacheCreateTokens, 0);
         const cost = records.reduce((s, r) => s + estimateCost(r), 0);
         const avgLatency = records.reduce((s, r) => s + r.latencyMs, 0) / records.length;
         const errors = records.filter(r => r.status >= 400).length;
@@ -314,6 +327,9 @@ export class Analytics extends EventEmitter {
             totalInputTokens: totalInput,
             totalOutputTokens: totalOutput,
             totalThinkingTokens: totalThinking,
+            totalCacheReadTokens: totalCacheRead,
+            totalCacheCreateTokens: totalCacheCreate,
+            cachedPromptPercent: cachedPromptPercent(totalInput, totalCacheRead, totalCacheCreate),
             estimatedCost: Math.round(cost * 10000) / 10000,
             avgLatencyMs: Math.round(avgLatency),
             errorRate: Math.round((errors / records.length) * 10000) / 10000,
@@ -330,10 +346,16 @@ export class Analytics extends EventEmitter {
         const result = {};
         for (const [account, recs] of Object.entries(grouped)) {
             const last = recs[recs.length - 1];
+            const inputTokens = recs.reduce((s, r) => s + r.inputTokens, 0);
+            const cacheReadTokens = recs.reduce((s, r) => s + r.cacheReadTokens, 0);
+            const cacheCreateTokens = recs.reduce((s, r) => s + r.cacheCreateTokens, 0);
             result[account] = {
                 requests: recs.length,
-                inputTokens: recs.reduce((s, r) => s + r.inputTokens, 0),
+                inputTokens,
                 outputTokens: recs.reduce((s, r) => s + r.outputTokens, 0),
+                cacheReadTokens,
+                cacheCreateTokens,
+                cachedPromptPercent: cachedPromptPercent(inputTokens, cacheReadTokens, cacheCreateTokens),
                 estimatedCost: Math.round(recs.reduce((s, r) => s + estimateCost(r), 0) * 10000) / 10000,
                 currentUtil5h: last.util5h,
                 currentUtil7d: last.util7d,
@@ -349,11 +371,17 @@ export class Analytics extends EventEmitter {
         }
         const result = {};
         for (const [model, recs] of Object.entries(grouped)) {
+            const inputTokens = recs.reduce((s, r) => s + r.inputTokens, 0);
+            const cacheReadTokens = recs.reduce((s, r) => s + r.cacheReadTokens, 0);
+            const cacheCreateTokens = recs.reduce((s, r) => s + r.cacheCreateTokens, 0);
             result[model] = {
                 requests: recs.length,
-                avgInputTokens: Math.round(recs.reduce((s, r) => s + r.inputTokens, 0) / recs.length),
+                avgInputTokens: Math.round(inputTokens / recs.length),
                 avgOutputTokens: Math.round(recs.reduce((s, r) => s + r.outputTokens, 0) / recs.length),
                 avgThinkingTokens: Math.round(recs.reduce((s, r) => s + r.thinkingTokens, 0) / recs.length),
+                avgCacheReadTokens: Math.round(cacheReadTokens / recs.length),
+                avgCacheCreateTokens: Math.round(cacheCreateTokens / recs.length),
+                cachedPromptPercent: cachedPromptPercent(inputTokens, cacheReadTokens, cacheCreateTokens),
                 estimatedCost: Math.round(recs.reduce((s, r) => s + estimateCost(r), 0) * 10000) / 10000,
             };
         }

package/dist/anthropic-responses-translate.d.ts

@@ -139,6 +139,9 @@ export type AnthropicStopReason = 'end_turn' | 'max_tokens' | 'tool_use' | 'stop
 export interface AnthropicUsage {
     input_tokens: number;
     output_tokens: number;
+    /** Present when the Responses usage carried `input_tokens_details`. */
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
 }
 export interface AnthropicResponse {
     id: string;
@@ -234,6 +237,8 @@ export interface ResponsesRequest {
     top_p?: number;
     stream?: boolean;
     store?: boolean;
+    /** Routing hint for the backend's prompt cache; see `codexPromptCacheKey`. */
+    prompt_cache_key?: string;
 }
 export interface ResponsesOutputText {
     type: 'output_text';
@@ -296,6 +301,20 @@ export interface ResponsesUsage {
     };
     total_tokens?: number;
 }
+/**
+ * Responses usage in Anthropic terms.
+ *
+ * The two APIs count cached prompt tokens differently: OpenAI's
+ * `input_tokens` INCLUDES the cached prefix and reports it again under
+ * `input_tokens_details.cached_tokens`; Anthropic's `input_tokens` EXCLUDES
+ * it and reports it beside as `cache_read_input_tokens`. A client summing the
+ * Anthropic fields (Claude Code's context meter does) would count the cached
+ * prefix twice if the number were copied across, so it is netted out here.
+ * `cache_write_tokens` (the 24h-retention write on newer models) maps to
+ * `cache_creation_input_tokens` the same way. Without `input_tokens_details`
+ * the usage stays two-field, exactly as before.
+ */
+export declare function anthropicUsageFromResponses(u: ResponsesUsage | null | undefined): AnthropicUsage;
 export interface ResponsesResponse {
     id?: string;
     object?: string;
@@ -417,6 +436,8 @@ export type ResponsesAnthropicStreamEvent = {
     usage: {
         output_tokens: number;
         input_tokens?: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
     };
 } | {
     type: 'message_stop';

package/dist/anthropic-responses-translate.js

@@ -78,6 +78,34 @@
  */
 export const REASONING_EFFORT_LOW_MAX = 4096;
 export const REASONING_EFFORT_MEDIUM_MAX = 16384;
+/**
+ * Responses usage in Anthropic terms.
+ *
+ * The two APIs count cached prompt tokens differently: OpenAI's
+ * `input_tokens` INCLUDES the cached prefix and reports it again under
+ * `input_tokens_details.cached_tokens`; Anthropic's `input_tokens` EXCLUDES
+ * it and reports it beside as `cache_read_input_tokens`. A client summing the
+ * Anthropic fields (Claude Code's context meter does) would count the cached
+ * prefix twice if the number were copied across, so it is netted out here.
+ * `cache_write_tokens` (the 24h-retention write on newer models) maps to
+ * `cache_creation_input_tokens` the same way. Without `input_tokens_details`
+ * the usage stays two-field, exactly as before.
+ */
+export function anthropicUsageFromResponses(u) {
+    const input = typeof u?.input_tokens === 'number' ? u.input_tokens : 0;
+    const output = typeof u?.output_tokens === 'number' ? u.output_tokens : 0;
+    const d = u?.input_tokens_details;
+    if (!d || typeof d !== 'object')
+        return { input_tokens: input, output_tokens: output };
+    const cached = typeof d.cached_tokens === 'number' && d.cached_tokens > 0 ? d.cached_tokens : 0;
+    const written = typeof d.cache_write_tokens === 'number' && d.cache_write_tokens > 0 ? d.cache_write_tokens : 0;
+    return {
+        input_tokens: Math.max(0, input - cached - written),
+        output_tokens: output,
+        cache_read_input_tokens: cached,
+        cache_creation_input_tokens: written,
+    };
+}
 // ─────────────────────────────────────────────────────────────────────
 // Small local helpers.
 // Thresholds are IMPORTED so the two translators stay in lock-step.
@@ -491,10 +519,7 @@ export function responsesToAnthropicResponse(resp, requestModel) {
         content,
         stop_reason: deriveStopReason(resp, sawToolCall),
         stop_sequence: null,
-        usage: {
-            input_tokens: resp.usage?.input_tokens ?? 0,
-            output_tokens: resp.usage?.output_tokens ?? 0,
-        },
+        usage: anthropicUsageFromResponses(resp.usage),
     };
 }
 const strOr = (v) => (typeof v === 'string' ? v : '');
@@ -626,8 +651,16 @@ export function responsesStreamToAnthropicSSE(options = {}) {
         const usageOut = {
             output_tokens: numOr(r.usage?.output_tokens, 0),
         };
-        if (typeof r.usage?.input_tokens === 'number')
-            usageOut.input_tokens = r.usage.input_tokens;
+        if (typeof r.usage?.input_tokens === 'number') {
+            // Same netting as the non-streaming body (anthropicUsageFromResponses):
+            // the cached prefix is reported beside input_tokens, not inside it.
+            const u = anthropicUsageFromResponses(r.usage);
+            usageOut.input_tokens = u.input_tokens;
+            if (u.cache_read_input_tokens !== undefined)
+                usageOut.cache_read_input_tokens = u.cache_read_input_tokens;
+            if (u.cache_creation_input_tokens !== undefined)
+                usageOut.cache_creation_input_tokens = u.cache_creation_input_tokens;
+        }
         events.push({
             type: 'message_delta',
             delta: { stop_reason: deriveStopReason(r, sawToolCall), stop_sequence: null },
@@ -837,6 +870,10 @@ export function createAnthropicMessageAssembler() {
                             output_tokens: e.usage.output_tokens,
                             input_tokens: e.usage.input_tokens ?? u.input_tokens,
                         };
+                        if (e.usage.cache_read_input_tokens !== undefined)
+                            msg.usage.cache_read_input_tokens = e.usage.cache_read_input_tokens;
+                        if (e.usage.cache_creation_input_tokens !== undefined)
+                            msg.usage.cache_creation_input_tokens = e.usage.cache_creation_input_tokens;
                     }
                 }
             }

package/dist/claude-model.js

@@ -72,7 +72,17 @@ function servableTarget(target, bases) {
         return null;
     const resolved = resolveAliasAgainst(stripped, bases) ?? stripped;
     const base = resolved.endsWith('[1m]') ? resolved.slice(0, -4) : resolved;
-    return bases.some((b) => b.toLowerCase() === base) ? resolved : null;
+    // The catalog keeps ONE spelling per model — the short id when upstream
+    // lists both `claude-opus-4-8` and `claude-opus-4-8-YYYYMMDD` (see
+    // normalizeUpstreamIds) — while a client may send either. Compare with the
+    // date stripped on both sides, and return the name as written: Anthropic
+    // accepts both forms, so the pool forwards whichever the caller chose.
+    const key = undated(base);
+    return bases.some((b) => undated(b.toLowerCase()) === key) ? resolved : null;
+}
+/** `claude-opus-4-8-20260101` → `claude-opus-4-8`; anything else unchanged. */
+function undated(id) {
+    return id.replace(/-\d{8}$/, '');
 }
 /**
  * The id the Claude pool would serve `model` as AND the effort the entry asked

package/dist/codex-backend.d.ts

@@ -1,28 +1,6 @@
-/**
- * Codex backend — request path for the "altman" engine (dario#1009/#1010).
- *
- * The ChatGPT subscription is NOT an api.openai.com API key: it can't be used
- * with `Authorization: Bearer sk-…` against the public API. OpenAI's own `codex`
- * CLI sends the OAuth access_token as a bearer to the ChatGPT Codex backend's
- * Responses endpoint, with the workspace id from the id_token as a header.
- * Mirrored from the CLI source rather than guessed:
- *
- *   base URL   codex-rs/model-provider-info/src/lib.rs
- *              `CHATGPT_CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex"`
- *              (used as the default base_url whenever auth_mode is Chatgpt)
- *   wire api   same file, `WireApi::Responses` — "the Responses API exposed by
- *              OpenAI at /v1/responses", i.e. `${base}/responses`
- *   headers    codex-rs/model-provider/src/bearer_auth_provider.rs
- *              `Authorization: Bearer <access_token>` + `ChatGPT-Account-ID: <id>`
- *   account id codex-rs/login/src/token_data.rs — id_token claim
- *              `https://api.openai.com/auth`.chatgpt_account_id
- *
- * dario's inbound is OpenAI chat/completions — what any OpenAI-compatible
- * client speaks — so this module owns the chat/completions ⇄ Responses
- * translation in both directions, including SSE.
- */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { CodexAccountCredentials } from './codex-accounts.js';
+import { type ResponsesUsage } from './anthropic-responses-translate.js';
 import { type ModelResolver, type ClaudeTarget } from './claude-model.js';
 export declare const CODEX_BACKEND_BASE_URL: string;
 /**
@@ -54,8 +32,11 @@ export declare function fetchCodexModels(creds: CodexAccountCredentials, fetchIm
 export interface CodexForwardOutcome {
     status: number;
     latencyMs: number;
+    /** Net of the cached prefix (Anthropic convention; see splitResponsesUsage). */
     inputTokens: number;
     outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreateTokens: number;
     stream: boolean;
     model: string;
     alias: string;
@@ -161,6 +142,61 @@ export declare function isFailedResponse(resp: unknown): boolean;
 export declare function failedResponseMessage(resp: unknown): string;
 /** The upstream error code on a failed Responses payload, or null when absent. */
 export declare function failedResponseCode(resp: unknown): string | null;
+/** chat/completions `usage`; `prompt_tokens_details` only when upstream reported details. */
+export interface ChatCompletionsUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    prompt_tokens_details?: {
+        cached_tokens: number;
+    };
+}
+/**
+ * Responses usage -> chat/completions usage. Both OpenAI shapes count the
+ * cached prefix INSIDE the prompt total and repeat it under a details object,
+ * so this is a rename, not a subtraction: `input_tokens_details.cached_tokens`
+ * becomes `prompt_tokens_details.cached_tokens`, which is where every OpenAI
+ * SDK and cost dashboard already looks for it.
+ */
+export declare function chatCompletionsUsage(u: ResponsesUsage): ChatCompletionsUsage;
+/** Per-request token accounting for analytics and the request log. */
+export interface CodexTokenUsage {
+    /** Net of the cached prefix: the Anthropic convention every analytics row uses. */
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheCreate: number;
+}
+/**
+ * Terminal Responses usage -> analytics accounting. Delegates the netting to
+ * anthropicUsageFromResponses so the analytics row and the Anthropic-shape
+ * wire body can never disagree about what "input" means. Null when the
+ * stream never delivered usage.
+ */
+export declare function splitResponsesUsage(u: unknown): CodexTokenUsage | null;
+/**
+ * The `prompt_cache_key` sent with every Codex request.
+ *
+ * The backend caches prompt prefixes on its own (1,024 tokens and up, about
+ * 30 minutes), but the key is what routes same-prefix requests to the machine
+ * that holds the cache; OpenAI's own wording is that it "influences routing".
+ * The Codex CLI sends one on every turn (its session id). dario sent none, so
+ * a fleet re-sending the same 20KB system prompt every few minutes was routed
+ * blind. Resolution order:
+ *
+ *   1. the client's own key, when the chat body carried one: it knows its
+ *      conversation better than any derivation here;
+ *   2. an Anthropic-shape `metadata.user_id`: Claude Code stamps one per
+ *      session, so a session shares a key across its turns. Hashed, because
+ *      the value embeds the client's Anthropic account and session ids and
+ *      neither has any business reaching a second vendor in the clear;
+ *   3. the request's own stable prefix: model, instructions and tool names.
+ *      Every caller sending the same system prompt and tool set lands on the
+ *      same key, which is exactly the grouping the cache wants.
+ *
+ * Pure. The key carries no content, only a truncated SHA-256 of it.
+ */
+export declare function codexPromptCacheKey(shape: CodexRequestShape, clientBody: Record<string, unknown>, upstreamBody: Record<string, unknown>): string;
 /**
  * Stateful per-request translator: Responses SSE in, chat/completions out.
  *
@@ -183,11 +219,9 @@ export declare function createResponsesTranslator(model: string): {
     /** Token usage from the terminal event, or null if none arrived. Read by
      *  the proxy to record the request in analytics — before this, codex
      *  requests were invisible to /analytics and the request log entirely. */
-    usage(): {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    } | null;
+    usage(): ChatCompletionsUsage | null;
+    /** The same terminal usage split for analytics (input net of cache). */
+    tokens(): CodexTokenUsage | null;
     /** Everything seen so far, as one non-streaming chat.completion body. */
     complete(): Record<string, unknown>;
 };

package/dist/codex-backend.js

@@ -1,4 +1,28 @@
-import { anthropicToResponsesRequest, createResponsesSSEParser, formatResponsesAnthropicSSE, createAnthropicMessageAssembler, responsesStreamToAnthropicSSE, } from './anthropic-responses-translate.js';
+/**
+ * Codex backend — request path for the "altman" engine (dario#1009/#1010).
+ *
+ * The ChatGPT subscription is NOT an api.openai.com API key: it can't be used
+ * with `Authorization: Bearer sk-…` against the public API. OpenAI's own `codex`
+ * CLI sends the OAuth access_token as a bearer to the ChatGPT Codex backend's
+ * Responses endpoint, with the workspace id from the id_token as a header.
+ * Mirrored from the CLI source rather than guessed:
+ *
+ *   base URL   codex-rs/model-provider-info/src/lib.rs
+ *              `CHATGPT_CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex"`
+ *              (used as the default base_url whenever auth_mode is Chatgpt)
+ *   wire api   same file, `WireApi::Responses` — "the Responses API exposed by
+ *              OpenAI at /v1/responses", i.e. `${base}/responses`
+ *   headers    codex-rs/model-provider/src/bearer_auth_provider.rs
+ *              `Authorization: Bearer <access_token>` + `ChatGPT-Account-ID: <id>`
+ *   account id codex-rs/login/src/token_data.rs — id_token claim
+ *              `https://api.openai.com/auth`.chatgpt_account_id
+ *
+ * dario's inbound is OpenAI chat/completions — what any OpenAI-compatible
+ * client speaks — so this module owns the chat/completions ⇄ Responses
+ * translation in both directions, including SSE.
+ */
+import { createHash } from 'node:crypto';
+import { anthropicToResponsesRequest, anthropicUsageFromResponses, createResponsesSSEParser, formatResponsesAnthropicSSE, createAnthropicMessageAssembler, responsesStreamToAnthropicSSE, } from './anthropic-responses-translate.js';
 import { resolveClaudeTarget } from './claude-model.js';
 import { BAKED_BASE_MODELS } from './model-catalog.js';
 import { parseRetryAfterMs } from './provider-cooldown.js';
@@ -198,6 +222,7 @@ const CHAT_COMPLETIONS_FIELD_TRANSLATIONS = {
     tool_choice: 'tool_choice',
     stream: 'stream',
     reasoning_effort: 'reasoning',
+    prompt_cache_key: 'prompt_cache_key',
     temperature: 'temperature',
     top_p: 'top_p',
     max_tokens: 'max_output_tokens',
@@ -365,6 +390,12 @@ export function chatCompletionsToResponses(body) {
     }
     if (body.reasoning_effort != null)
         out.reasoning = { effort: body.reasoning_effort };
+    // The public chat/completions API takes this field; a client that sets one
+    // (a harness keying on its own conversation id) knows its prefix better
+    // than any derivation here can.
+    if (typeof body.prompt_cache_key === 'string' && body.prompt_cache_key.length > 0) {
+        out.prompt_cache_key = body.prompt_cache_key;
+    }
     return out;
 }
 /**
@@ -398,6 +429,81 @@ export function failedResponseCode(resp) {
     const e = resp?.error;
     return e && typeof e.code === 'string' && e.code ? e.code : null;
 }
+/**
+ * Responses usage -> chat/completions usage. Both OpenAI shapes count the
+ * cached prefix INSIDE the prompt total and repeat it under a details object,
+ * so this is a rename, not a subtraction: `input_tokens_details.cached_tokens`
+ * becomes `prompt_tokens_details.cached_tokens`, which is where every OpenAI
+ * SDK and cost dashboard already looks for it.
+ */
+export function chatCompletionsUsage(u) {
+    const prompt = typeof u.input_tokens === 'number' ? u.input_tokens : 0;
+    const completion = typeof u.output_tokens === 'number' ? u.output_tokens : 0;
+    const out = { prompt_tokens: prompt, completion_tokens: completion, total_tokens: prompt + completion };
+    const d = u.input_tokens_details;
+    if (d && typeof d === 'object') {
+        out.prompt_tokens_details = { cached_tokens: typeof d.cached_tokens === 'number' && d.cached_tokens > 0 ? d.cached_tokens : 0 };
+    }
+    return out;
+}
+/**
+ * Terminal Responses usage -> analytics accounting. Delegates the netting to
+ * anthropicUsageFromResponses so the analytics row and the Anthropic-shape
+ * wire body can never disagree about what "input" means. Null when the
+ * stream never delivered usage.
+ */
+export function splitResponsesUsage(u) {
+    if (!u || typeof u !== 'object')
+        return null;
+    const a = anthropicUsageFromResponses(u);
+    return {
+        input: a.input_tokens,
+        output: a.output_tokens,
+        cacheRead: a.cache_read_input_tokens ?? 0,
+        cacheCreate: a.cache_creation_input_tokens ?? 0,
+    };
+}
+/**
+ * The `prompt_cache_key` sent with every Codex request.
+ *
+ * The backend caches prompt prefixes on its own (1,024 tokens and up, about
+ * 30 minutes), but the key is what routes same-prefix requests to the machine
+ * that holds the cache; OpenAI's own wording is that it "influences routing".
+ * The Codex CLI sends one on every turn (its session id). dario sent none, so
+ * a fleet re-sending the same 20KB system prompt every few minutes was routed
+ * blind. Resolution order:
+ *
+ *   1. the client's own key, when the chat body carried one: it knows its
+ *      conversation better than any derivation here;
+ *   2. an Anthropic-shape `metadata.user_id`: Claude Code stamps one per
+ *      session, so a session shares a key across its turns. Hashed, because
+ *      the value embeds the client's Anthropic account and session ids and
+ *      neither has any business reaching a second vendor in the clear;
+ *   3. the request's own stable prefix: model, instructions and tool names.
+ *      Every caller sending the same system prompt and tool set lands on the
+ *      same key, which is exactly the grouping the cache wants.
+ *
+ * Pure. The key carries no content, only a truncated SHA-256 of it.
+ */
+export function codexPromptCacheKey(shape, clientBody, upstreamBody) {
+    const own = upstreamBody.prompt_cache_key;
+    if (typeof own === 'string' && own.length > 0)
+        return own;
+    const h = createHash('sha256');
+    if (shape === 'anthropic') {
+        const meta = clientBody.metadata;
+        if (meta && typeof meta.user_id === 'string' && meta.user_id.length > 0) {
+            h.update('session\0').update(meta.user_id);
+            return `dario-${h.digest('hex').slice(0, 32)}`;
+        }
+    }
+    h.update('prefix\0').update(String(upstreamBody.model ?? '')).update('\0');
+    h.update(typeof upstreamBody.instructions === 'string' ? upstreamBody.instructions : '').update('\0');
+    const tools = Array.isArray(upstreamBody.tools) ? upstreamBody.tools : [];
+    for (const t of tools)
+        h.update(typeof t?.name === 'string' ? t.name : '').update('\0');
+    return `dario-${h.digest('hex').slice(0, 32)}`;
+}
 /**
  * Stateful per-request translator: Responses SSE in, chat/completions out.
  *
@@ -417,6 +523,7 @@ export function createResponsesTranslator(model) {
     let id = 'chatcmpl-dario';
     let text = '';
     let usage = null;
+    let rawUsage = null;
     const toolCalls = new Map();
     let nextToolIndex = 0;
     let roleSent = false;
@@ -505,11 +612,8 @@ export function createResponsesTranslator(model) {
                 const r = e.response;
                 const u = r?.usage;
                 if (u) {
-                    usage = {
-                        prompt_tokens: u.input_tokens ?? 0,
-                        completion_tokens: u.output_tokens ?? 0,
-                        total_tokens: (u.input_tokens ?? 0) + (u.output_tokens ?? 0),
-                    };
+                    rawUsage = u;
+                    usage = chatCompletionsUsage(u);
                 }
                 if (failed) {
                     // A failed turn must NOT close like a finished one: a
@@ -540,6 +644,10 @@ export function createResponsesTranslator(model) {
         usage() {
             return usage;
         },
+        /** The same terminal usage split for analytics (input net of cache). */
+        tokens() {
+            return splitResponsesUsage(rawUsage);
+        },
         /** Everything seen so far, as one non-streaming chat.completion body. */
         complete() {
             const calls = [...toolCalls.values()].sort((a, b) => a.index - b.index);
@@ -583,6 +691,9 @@ export function createResponsesTranslator(model) {
 export const CODEX_SUPPORTED_FIELDS = [
     'model', 'input', 'stream', 'store', 'instructions',
     'tools', 'tool_choice', 'parallel_tool_calls', 'reasoning',
+    // Sent by the Codex CLI on every request (codex-rs ResponsesApiRequest), so
+    // accepted by construction; see codexPromptCacheKey.
+    'prompt_cache_key',
 ];
 /** Drop every field this backend does not accept. Pure; exported for tests. */
 export function toCodexSupportedBody(body) {
@@ -648,7 +759,12 @@ export async function forwardToCodex(req, res, body, creds, corsOrigin, security
             return;
         reported = true;
         try {
-            onDone({ status, latencyMs: Date.now() - startedAt, inputTokens: usage?.input ?? 0, outputTokens: usage?.output ?? 0, stream, model, alias: creds.alias });
+            onDone({
+                status, latencyMs: Date.now() - startedAt,
+                inputTokens: usage?.input ?? 0, outputTokens: usage?.output ?? 0,
+                cacheReadTokens: usage?.cacheRead ?? 0, cacheCreateTokens: usage?.cacheCreate ?? 0,
+                stream, model, alias: creds.alias,
+            });
         }
         catch { /* a reporting failure must never break a served request */ }
     };
@@ -675,7 +791,10 @@ export async function forwardToCodex(req, res, body, creds, corsOrigin, security
     const upstreamBody = isAnthropic
         ? { ...anthropicToResponsesRequest(parsed, model), stream: true }
         : chatCompletionsToResponses(parsed);
-    const scrubbed = toCodexSupportedBody(upstreamBody);
+    const scrubbed = toCodexSupportedBody({
+        ...upstreamBody,
+        prompt_cache_key: codexPromptCacheKey(shape, parsed, upstreamBody),
+    });
     const target = `${CODEX_BACKEND_BASE_URL.replace(/\/$/, '')}/responses`;
     const abort = new AbortController();
     // Once the client is gone there is nobody left to write to, but the upstream
@@ -763,8 +882,8 @@ export async function forwardToCodex(req, res, body, creds, corsOrigin, security
         // Reported on the abandoned-client exit as well as the normal one, so a
         // stream the client walked away from still shows what it already spent.
         usageSoFar = isAnthropic
-            ? () => { const tr = terminalResponse; return tr?.usage ? { input: Number(tr.usage.input_tokens ?? 0), output: Number(tr.usage.output_tokens ?? 0) } : null; }
-            : () => { const u = translator.usage(); return u ? { input: u.prompt_tokens, output: u.completion_tokens } : null; };
+            ? () => splitResponsesUsage(terminalResponse?.usage)
+            : () => translator.tokens();
         const emitAnthropic = (events) => {
             for (const ev of events) {
                 const t = ev.type ?? '';