@askalf/dario 6.0.29 → 6.0.31

package/README.md

@@ -18,7 +18,7 @@
 
 <p><strong>One local endpoint. Every AI tool you own. The subscriptions you already pay for.</strong></p>
 
-<sub><code>npm i -g @askalf/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~30k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
+<sub><code>npm i -g @askalf/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~31k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
 
 <sub>Part of <a href="#own-your-stack"><strong>Own Your Stack</strong></a> — 11 open tools for owning your AI infra: <a href="https://github.com/askalf/redstamp">redstamp</a> · <a href="https://github.com/askalf/truecopy">truecopy</a> · <a href="https://github.com/askalf/fieldpass">fieldpass</a> · <a href="https://github.com/askalf/plumbline">plumbline</a> · <a href="#own-your-stack">full family ↓</a></sub>
 
@@ -167,6 +167,8 @@ Streaming, tool calls, and tool-result round trips work on both shapes: dario tr
 
 **Chat/completions fidelity:** text and `image_url` user-content parts (HTTPS URLs and data URIs, including the `detail` fidelity setting) carry through to Responses input items. The Codex subscription backend does not accept every chat field, so `response_format`, `stop`, `n`, `logprobs`, `stream_options` and other unmapped chat-only fields are intentionally lossy — and so are the sampling parameters `temperature`, `top_p`, `max_tokens` and `max_completion_tokens`, which translate cleanly but are then rejected by the backend and stripped before the request goes out. With `--verbose`, dario reports each field that does not reach Codex once per process.
 
+**Prompt caching:** the backend caches prompt prefixes of 1,024 tokens and up on its own; what dario adds is the `prompt_cache_key` that routes same-prefix requests to the cache that holds them, the way the Codex CLI does with its session id. A chat/completions client that sets its own key keeps it; an Anthropic-shape request gets one per Claude Code session (a hash of `metadata.user_id`, never the raw ids); anything else is keyed on its model, instructions and tool names, so repeated system prompts from any caller land together. Cached tokens come back as `prompt_tokens_details.cached_tokens` on chat/completions and as `cache_read_input_tokens` on `/v1/messages`, and show up in `/analytics` and the `-v` usage line like a Claude request's do.
+
 Codex accounts live in `~/.dario/codex-accounts/`, entirely separate from the Claude pool. Nothing about `dario login`, `dario accounts`, or Claude routing changes.
 
 ---
@@ -309,7 +311,7 @@ The split isn't live, but it was announced once on short notice and could return
 
 | Signal | Status |
 |---|---|
-| Source | **~30k** lines of TypeScript across **65** files — auditable in a weekend (v5 removed shim; the pool is the one code path) |
+| Source | **~31k** lines of TypeScript across **67** files — auditable in a weekend (v5 removed shim; the pool is the one code path) |
 | Dependencies | **0 runtime.** Verify: `npm ls --production` |
 | Provenance | Every release [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions + Sigstore |
 | Scanning | [CodeQL](https://github.com/askalf/dario/actions/workflows/codeql.yml) on every push and weekly |

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/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 ?? '';

package/dist/pool.d.ts

@@ -118,6 +118,41 @@ export type AccountIneligibility = 'rate-limited' | 'token-expired' | 'auth-cool
  * need to name the failure, and a boolean forces each of them to re-derive it
  * and drift again.
  */
+/**
+ * Has the window that produced a `rejected` reading rolled over?
+ *
+ * A rejection is a verdict with an expiry date: `anthropic-ratelimit-unified-reset`
+ * names the moment the window that refused the request resets. Past it, the old
+ * reading says nothing about the account any more.
+ *
+ * This matters because a rejected account is filtered out of `select()`, so it
+ * is sent no further requests, so `updateRateLimits` never runs for it and its
+ * snapshot never refreshes. The only routes back into rotation were the
+ * all-exhausted fallback in `select()` and a proxy restart. Observed on the
+ * fleet box (2026-09-06): one seat sat parked on a 106% five-hour reading while
+ * a second subscription carried every request, and it would have stayed parked
+ * past its own reset for as long as the other seat held out.
+ *
+ * `reset` is epoch SECONDS — the header's own unit, the same one `formatReset`
+ * scales — so it is converted here. A snapshot with no reset (0) keeps its
+ * rejection: with no stated rollover there is nothing to expire, and guessing
+ * would push a genuinely throttled account back into rotation.
+ */
+export declare function rateLimitWindowPassed(rl: RateLimitSnapshot, now?: number): boolean;
+/**
+ * The status string the operator-facing surfaces report for one account —
+ * `GET /accounts` and `GET /admin/accounts`, which must agree with each other
+ * and with what routing actually does.
+ *
+ * Auth cool-down outranks the rate-limit reading: a 401 streak is both the more
+ * urgent fact and the one the rate-limit headers cannot describe, since 401
+ * responses carry none. An expired rejection degrades to `unknown` rather than
+ * `allowed` — the window rolled over, but nothing has measured the account
+ * since, and reporting `allowed` would assert a serving capacity no request has
+ * demonstrated. `unknown` is what a never-used account already reports, which is
+ * exactly the state this is: no current observation.
+ */
+export declare function reportedAccountStatus(account: PoolAccount, now?: number): string;
 export declare function accountIneligibility(account: PoolAccount, now?: number): AccountIneligibility | null;
 /** Boolean form of `accountIneligibility` — the router's eligibility filter. */
 export declare function isAccountEligible(account: PoolAccount, now?: number): boolean;

package/dist/pool.js

@@ -100,8 +100,54 @@ export const TOKEN_EXPIRY_MARGIN_MS = 30_000;
  * need to name the failure, and a boolean forces each of them to re-derive it
  * and drift again.
  */
+/**
+ * Has the window that produced a `rejected` reading rolled over?
+ *
+ * A rejection is a verdict with an expiry date: `anthropic-ratelimit-unified-reset`
+ * names the moment the window that refused the request resets. Past it, the old
+ * reading says nothing about the account any more.
+ *
+ * This matters because a rejected account is filtered out of `select()`, so it
+ * is sent no further requests, so `updateRateLimits` never runs for it and its
+ * snapshot never refreshes. The only routes back into rotation were the
+ * all-exhausted fallback in `select()` and a proxy restart. Observed on the
+ * fleet box (2026-09-06): one seat sat parked on a 106% five-hour reading while
+ * a second subscription carried every request, and it would have stayed parked
+ * past its own reset for as long as the other seat held out.
+ *
+ * `reset` is epoch SECONDS — the header's own unit, the same one `formatReset`
+ * scales — so it is converted here. A snapshot with no reset (0) keeps its
+ * rejection: with no stated rollover there is nothing to expire, and guessing
+ * would push a genuinely throttled account back into rotation.
+ */
+export function rateLimitWindowPassed(rl, now = Date.now()) {
+    return rl.reset > 0 && rl.reset * 1000 <= now;
+}
+/**
+ * The status string the operator-facing surfaces report for one account —
+ * `GET /accounts` and `GET /admin/accounts`, which must agree with each other
+ * and with what routing actually does.
+ *
+ * Auth cool-down outranks the rate-limit reading: a 401 streak is both the more
+ * urgent fact and the one the rate-limit headers cannot describe, since 401
+ * responses carry none. An expired rejection degrades to `unknown` rather than
+ * `allowed` — the window rolled over, but nothing has measured the account
+ * since, and reporting `allowed` would assert a serving capacity no request has
+ * demonstrated. `unknown` is what a never-used account already reports, which is
+ * exactly the state this is: no current observation.
+ */
+export function reportedAccountStatus(account, now = Date.now()) {
+    if (isInAuthCooldown(account, now))
+        return 'auth-cooldown';
+    if (account.rateLimit.status === 'rejected' && rateLimitWindowPassed(account.rateLimit, now))
+        return 'unknown';
+    return account.rateLimit.status;
+}
 export function accountIneligibility(account, now = Date.now()) {
-    if (account.rateLimit.status === 'rejected')
+    // A rejection outlives its own window unless it is allowed to expire:
+    // nothing refreshes a parked account's snapshot, because being parked is
+    // what stops it being sent requests.
+    if (account.rateLimit.status === 'rejected' && !rateLimitWindowPassed(account.rateLimit, now))
         return 'rate-limited';
     if (account.expiresAt <= now + TOKEN_EXPIRY_MARGIN_MS)
         return 'token-expired';

package/dist/proxy.js

@@ -12,7 +12,7 @@ import { darioVersion } from './version.js';
 import { buildCCRequest, applyCcPromptCaching, isGenuineCCClient, parseEffortSuffix, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound, overlayTemplateHeaderValues, forwardClientCCIdentityHeaders, isMcpToolName, CC_TEMPLATE, effectiveCacheControl, withForced1hBeta } from './cc-template.js';
 import { stampCch, hasCchSeed } from './cch.js';
 import { describeTemplate, detectDrift, checkCCCompat, probeInstalledCCVersion } from './live-fingerprint.js';
-import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, accountIneligibility, reconcilePoolAccounts, resolvePoolStrategy, utilFreshness } from './pool.js';
+import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, accountIneligibility, reportedAccountStatus, reconcilePoolAccounts, resolvePoolStrategy, utilFreshness } from './pool.js';
 import { Analytics, billingBucketFromClaim, formatUsageLogLine, SUBSCRIPTION_CLAIMS, CODEX_CLAIM } from './analytics.js';
 import { OverageGuard, buildHaltErrorBody } from './overage-guard.js';
 import { notify as osNotify } from './notify.js';
@@ -2101,7 +2101,7 @@ export async function startProxy(opts = {}) {
                             // must not be the one place a stale reading still looks current.
                             ...utilFreshness(a.rateLimit, snapNow),
                             claim: a.rateLimit.claim,
-                            status: isInAuthCooldown(a, snapNow) ? 'auth-cooldown' : a.rateLimit.status,
+                            status: reportedAccountStatus(a, snapNow),
                             requestCount: a.requestCount,
                             // Raw streak, not just the cooldown boolean: a single 401 also
                             // shows `auth-cooldown` for 60s, indistinguishable from a
@@ -2200,7 +2200,7 @@ export async function startProxy(opts = {}) {
                     util7d: a.rateLimit.util7d,
                     ...utilFreshness(a.rateLimit, now),
                     claim: a.rateLimit.claim,
-                    status: inCooldown ? 'auth-cooldown' : a.rateLimit.status,
+                    status: reportedAccountStatus(a, now),
                     requestCount: a.requestCount,
                     expiresInMs: Math.max(0, a.expiresAt - now),
                     // Refresh-token grant age (refresh-grant.ts): the wall a token
@@ -3040,7 +3040,9 @@ export async function startProxy(opts = {}) {
                                 account: o.alias,
                                 model: o.model || rawModel || 'codex',
                                 inputTokens: o.inputTokens, outputTokens: o.outputTokens,
-                                cacheReadTokens: 0, cacheCreateTokens: 0, thinkingTokens: 0,
+                                // Anthropic convention, like every other row: inputTokens is
+                                // net of the cached prefix, which sits in cacheReadTokens.
+                                cacheReadTokens: o.cacheReadTokens, cacheCreateTokens: o.cacheCreateTokens, thinkingTokens: 0,
                                 // No Anthropic rate-limit headers on this path; the claim
                                 // names the engine and is subscription billing, so the
                                 // overage guard (#288) leaves it alone.
@@ -3051,8 +3053,14 @@ export async function startProxy(opts = {}) {
                                 ts: new Date().toISOString(), req: codexReq,
                                 method: req.method ?? '', path: urlPath, model: o.model || rawModel || undefined,
                                 status: o.status, latency_ms: o.latencyMs, in_tokens: o.inputTokens, out_tokens: o.outputTokens,
+                                cache_read: o.cacheReadTokens, cache_create: o.cacheCreateTokens,
                                 claim: CODEX_CLAIM, bucket: 'subscription', account: o.alias, stream: o.stream,
                             });
+                            if (verbose)
+                                console.log(formatUsageLogLine(codexReq, {
+                                    inputTokens: o.inputTokens, outputTokens: o.outputTokens,
+                                    cacheReadTokens: o.cacheReadTokens, cacheCreateTokens: o.cacheCreateTokens,
+                                }));
                         }, 
                         // Cool codex on a rate limit only — a 5xx or an unreachable backend
                         // is an outage, and parking a provider for that would keep it out

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.0.29",
+  "version": "6.0.31",
   "description": "Use your Claude Pro/Max subscription in any tool — Cursor, Cline, Aider, the Agent SDK, your scripts — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint.",
   "type": "module",
   "bin": {