@askalf/dario 6.17.1 → 6.18.0

package/dist/analytics.d.ts

@@ -55,6 +55,23 @@ export interface RequestRecord {
      * reached an upstream.
      */
     timing?: RequestTiming;
+    /**
+     * What a Codex request shared with the previous one on its cache key
+     * (src/cache-trace.ts): the gap, whether the input extends the previous
+     * one, and whether the seat or the prefix changed. Absent off that path.
+     */
+    cache?: RequestCacheTrace;
+}
+export interface RequestCacheTrace {
+    /** The `prompt_cache_key` the request went out under: dario's derived key as is, a caller's own key as a digest. */
+    key: string;
+    items: number;
+    sinceMs: number | null;
+    prevItems: number | null;
+    extends: boolean | null;
+    divergedAt: number | null;
+    seatChanged: boolean | null;
+    prefixChanged: boolean | null;
 }
 export interface RequestContinuation {
     /** See midstream.ts ContinuationOutcome. */

package/dist/cache-trace.d.ts

@@ -0,0 +1,106 @@
+/** One input item, as a short digest of its JSON form. */
+export declare function itemHash(item: unknown): string;
+/**
+ * The key as the trace records it. A key dario derived itself
+ * (codexPromptCacheKey) is already a digest and is kept as it went out, so a
+ * trace matches the request; a caller-supplied key can be anything (a session
+ * id, an email, a secret that happens to look like a derived key) and is
+ * recorded only as a digest, stable per key so a run of traces still groups
+ * by conversation. Only the caller knows which it is, so the shape of the key
+ * decides nothing.
+ */
+export declare function traceKey(key: string, derived: boolean): string;
+/**
+ * The stable front of a request: model, instructions and tool names, as a
+ * short digest. The same material the derived cache key hashes, kept
+ * separately so a changed system prompt between two turns of one
+ * conversation shows up as such.
+ */
+export declare function prefixHash(body: {
+    model?: unknown;
+    instructions?: unknown;
+    tools?: unknown;
+}): string;
+export interface CacheTraceInput {
+    /** The `prompt_cache_key` the request goes out with. */
+    key: string;
+    /** The seat that serves it. */
+    alias: string;
+    /** `prefixHash()` of the outgoing body. */
+    prefix: string;
+    /** `itemHash()` of every input item, in order. */
+    items: readonly string[];
+    /** When it goes out, ms since the epoch. */
+    at: number;
+    /**
+     * Dispatch order, stamped by `peek()` when absent, so two requests that
+     * went out in the same ms still order by which went out first.
+     */
+    seq?: number;
+}
+export interface CacheTraceResult {
+    /** Input items in this request. */
+    items: number;
+    /** ms since the previous request on this key; null on the first. */
+    sinceMs: number | null;
+    /** Input items in the previous request on this key; null on the first. */
+    prevItems: number | null;
+    /**
+     * The previous request's input is a strict prefix of this one: every item
+     * equal, this one longer. The shape a cache hit needs. null on the first,
+     * and when this one is longer but the previous input ran past
+     * CACHE_TRACE_MAX_ITEMS, so its tail was not kept to compare.
+     */
+    extends: boolean | null;
+    /**
+     * Index of the first input item that differs from the previous request,
+     * when one does. null when the inputs agree as far as both go (the new one
+     * extends, equals or shortens the old one) and on the first request.
+     */
+    divergedAt: number | null;
+    /** The seat differs from the previous request's; null on the first. */
+    seatChanged: boolean | null;
+    /** Model, instructions or tool names differ from the previous request's; null on the first. */
+    prefixChanged: boolean | null;
+}
+export declare const CACHE_TRACE_MAX_KEYS = 1000;
+/** Longer than the backend keeps a prefix, so a stale entry cannot look like a live conversation. */
+export declare const CACHE_TRACE_TTL_MS: number;
+/** Items remembered per key. A longer input is compared on its first this many items and its length. */
+export declare const CACHE_TRACE_MAX_ITEMS = 2000;
+export declare class CacheTrace {
+    private readonly seen;
+    private readonly maxKeys;
+    private readonly ttlMs;
+    private readonly now;
+    private dispatched;
+    constructor(opts?: {
+        maxKeys?: number;
+        ttlMs?: number;
+        now?: () => number;
+    });
+    /** Compare a request with the previous one on its key, then remember it. */
+    note(input: CacheTraceInput): CacheTraceResult;
+    /** Compare a request with the previous one on its key, remembering nothing but its dispatch order. */
+    peek(input: CacheTraceInput): CacheTraceResult;
+    /**
+     * Make a request the one the next request on its key compares with, unless
+     * one that went out after it is already remembered: concurrent requests are
+     * accepted in whatever order their upstream headers arrive, and the next
+     * request compares with the latest to go out.
+     */
+    remember(input: CacheTraceInput): void;
+    /** Keys remembered right now. */
+    size(): number;
+    /**
+     * Drop every expired entry, then, while over the cap, the entry that went
+     * out earliest. By `at` rather than Map order: a request accepted late can
+     * be older than entries inserted before it.
+     */
+    private sweep;
+}
+/** The one-line trace for stdout: `key=... since=3.2s items=23 extends=yes read=0/44120 (0%)`. `key` is the `traceKey()` form. */
+export declare function formatCacheTraceLine(requestCount: number, key: string, t: CacheTraceResult, usage: {
+    inputTokens: number;
+    cacheReadTokens: number;
+}, alias?: string): string;

package/dist/cache-trace.js

@@ -0,0 +1,176 @@
+/**
+ * Cache trace: what a Codex request shares with the previous request on the
+ * same `prompt_cache_key`.
+ *
+ * The backend caches prompt prefixes and reports what it read back as
+ * `cached_tokens`, and dario already records that number. What the number
+ * cannot say is WHY a turn missed. The trace records three things that bear
+ * on a hit and are visible to dario before the request goes out. They narrow
+ * the cause down; they do not prove it:
+ *
+ *   1. time: a cache write is not readable at once, so a turn that follows
+ *      the previous one closely may read nothing it wrote. The gap is
+ *      measured here; when the backend's write became readable is not;
+ *   2. shape: a hit needs the previous input to be a strict prefix of this
+ *      one, item for item, with the same front in place. `extends` compares
+ *      the input items only; the model, instructions and tool names are
+ *      compared apart as `prefixChanged`, and tool schemas not at all;
+ *   3. seat: the cache is scoped to the serving account, so a conversation
+ *      that moved seats starts over.
+ *
+ * `note()` answers all three for a request and remembers it for the next one.
+ * `peek()` and `remember()` are its two halves, for a caller that only knows
+ * after the comparison whether the request was served. It keeps hashes only:
+ * no content, no token counts. Pure except for the map it keeps, with an
+ * injectable clock so the tests need no sleeping.
+ */
+import { createHash } from 'node:crypto';
+/** One input item, as a short digest of its JSON form. */
+export function itemHash(item) {
+    return createHash('sha256').update(JSON.stringify(item) ?? 'undefined').digest('hex').slice(0, 12);
+}
+/**
+ * The key as the trace records it. A key dario derived itself
+ * (codexPromptCacheKey) is already a digest and is kept as it went out, so a
+ * trace matches the request; a caller-supplied key can be anything (a session
+ * id, an email, a secret that happens to look like a derived key) and is
+ * recorded only as a digest, stable per key so a run of traces still groups
+ * by conversation. Only the caller knows which it is, so the shape of the key
+ * decides nothing.
+ */
+export function traceKey(key, derived) {
+    if (derived)
+        return key;
+    return `key-${createHash('sha256').update('trace\0').update(key).digest('hex').slice(0, 16)}`;
+}
+/**
+ * The stable front of a request: model, instructions and tool names, as a
+ * short digest. The same material the derived cache key hashes, kept
+ * separately so a changed system prompt between two turns of one
+ * conversation shows up as such.
+ */
+export function prefixHash(body) {
+    const h = createHash('sha256');
+    h.update(String(body.model ?? '')).update('\0');
+    h.update(typeof body.instructions === 'string' ? body.instructions : '').update('\0');
+    const tools = Array.isArray(body.tools) ? body.tools : [];
+    for (const t of tools)
+        h.update(typeof t?.name === 'string' ? t.name : String(t?.type ?? '')).update('\0');
+    return h.digest('hex').slice(0, 12);
+}
+export const CACHE_TRACE_MAX_KEYS = 1000;
+/** Longer than the backend keeps a prefix, so a stale entry cannot look like a live conversation. */
+export const CACHE_TRACE_TTL_MS = 60 * 60 * 1000;
+/** Items remembered per key. A longer input is compared on its first this many items and its length. */
+export const CACHE_TRACE_MAX_ITEMS = 2000;
+export class CacheTrace {
+    seen = new Map();
+    maxKeys;
+    ttlMs;
+    now;
+    dispatched = 0;
+    constructor(opts = {}) {
+        this.maxKeys = opts.maxKeys ?? CACHE_TRACE_MAX_KEYS;
+        this.ttlMs = opts.ttlMs ?? CACHE_TRACE_TTL_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Compare a request with the previous one on its key, then remember it. */
+    note(input) {
+        const result = this.peek(input);
+        this.remember(input);
+        return result;
+    }
+    /** Compare a request with the previous one on its key, remembering nothing but its dispatch order. */
+    peek(input) {
+        if (input.seq === undefined)
+            input.seq = ++this.dispatched;
+        const prev = this.seen.get(input.key);
+        const live = prev !== undefined && input.at - prev.at <= this.ttlMs;
+        return live
+            ? {
+                items: input.items.length,
+                sinceMs: Math.max(0, input.at - prev.at),
+                prevItems: prev.count,
+                ...compare(prev, kept(input.items), input.items.length),
+                seatChanged: prev.alias !== input.alias,
+                prefixChanged: prev.prefix !== input.prefix,
+            }
+            : { items: input.items.length, sinceMs: null, prevItems: null, extends: null, divergedAt: null, seatChanged: null, prefixChanged: null };
+    }
+    /**
+     * Make a request the one the next request on its key compares with, unless
+     * one that went out after it is already remembered: concurrent requests are
+     * accepted in whatever order their upstream headers arrive, and the next
+     * request compares with the latest to go out.
+     */
+    remember(input) {
+        const seq = input.seq ?? 0;
+        const prev = this.seen.get(input.key);
+        if (prev !== undefined && (prev.at > input.at || (prev.at === input.at && prev.seq > seq)))
+            return;
+        this.seen.delete(input.key);
+        this.seen.set(input.key, { alias: input.alias, prefix: input.prefix, items: kept(input.items), count: input.items.length, at: input.at, seq });
+        this.sweep(input.at);
+    }
+    /** Keys remembered right now. */
+    size() {
+        return this.seen.size;
+    }
+    /**
+     * Drop every expired entry, then, while over the cap, the entry that went
+     * out earliest. By `at` rather than Map order: a request accepted late can
+     * be older than entries inserted before it.
+     */
+    sweep(at) {
+        for (const [key, r] of this.seen) {
+            if (at - r.at > this.ttlMs)
+                this.seen.delete(key);
+        }
+        while (this.seen.size > this.maxKeys) {
+            let oldest;
+            let oldestAt = Infinity;
+            for (const [key, r] of this.seen)
+                if (r.at < oldestAt) {
+                    oldest = key;
+                    oldestAt = r.at;
+                }
+            if (oldest === undefined)
+                break;
+            this.seen.delete(oldest);
+        }
+    }
+}
+function kept(items) {
+    return items.length > CACHE_TRACE_MAX_ITEMS ? items.slice(0, CACHE_TRACE_MAX_ITEMS) : items;
+}
+function compare(prev, cur, curCount) {
+    const shared = Math.min(prev.items.length, cur.length);
+    for (let i = 0; i < shared; i++) {
+        if (prev.items[i] !== cur[i])
+            return { extends: false, divergedAt: i };
+    }
+    if (curCount <= prev.count)
+        return { extends: false, divergedAt: null };
+    // Longer than the previous input and equal as far as it was kept; past
+    // that, nothing was kept to say whether it still agrees.
+    return { extends: prev.items.length < prev.count ? null : true, divergedAt: null };
+}
+/** The one-line trace for stdout: `key=... since=3.2s items=23 extends=yes read=0/44120 (0%)`. `key` is the `traceKey()` form. */
+export function formatCacheTraceLine(requestCount, key, t, usage, alias) {
+    const prompt = usage.inputTokens + usage.cacheReadTokens;
+    const pct = prompt > 0 ? Math.round((usage.cacheReadTokens / prompt) * 100) : 0;
+    const yesNo = (v) => (v === null ? '-' : v ? 'yes' : 'no');
+    const since = t.sinceMs === null ? 'first' : `${(t.sinceMs / 1000).toFixed(1)}s`;
+    const parts = [
+        `key=${key.slice(0, 16)}`,
+        alias ? `seat=${alias}` : '',
+        `since=${since}`,
+        `items=${t.items}${t.prevItems === null ? '' : `/${t.prevItems}`}`,
+        `extends=${yesNo(t.extends)}`,
+        t.divergedAt === null ? '' : `diverged_at=${t.divergedAt}`,
+        t.seatChanged ? 'seat_changed' : '',
+        t.prefixChanged ? 'prefix_changed' : '',
+        `read=${usage.cacheReadTokens}/${prompt} (${pct}%)`,
+    ].filter(Boolean);
+    return `[dario] #${requestCount} cache: ${parts.join(' ')}`;
+}

package/dist/cc-template-data.json

@@ -1,6 +1,6 @@
 {
   "_version": "2.1.311",
-  "_captured": "2026-10-23T12:28:22.488Z",
+  "_captured": "2026-10-26T22:30:54.888Z",
   "_source": "bundled",
   "_schemaVersion": 3,
   "agent_identity": "You are a Claude agent, built on Anthropic's Claude Agent SDK.",
@@ -188,7 +188,7 @@
     },
     {
       "name": "Bash",
-      "description": "Executes a bash command and returns its output.\n\n- Working directory persists between calls, but prefer absolute paths — `cd` in a compound command can trigger a permission prompt. Shell state (env vars, functions) does not persist; the shell is initialized from the user's profile.\n- IMPORTANT: Avoid using this tool to run `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user.\n- Command output is displayed to you, not reliably to the user.\n- `timeout` is in milliseconds: default 120000, max 600000 for a foreground command.\n- `run_in_background` runs the command detached: it keeps running across turns and re-invokes you when it exits. With it, `timeout` is how long the command may run in the background (default 600000, max 7200000); at that limit it is stopped and you are re-invoked. No `&` needed. Foreground `sleep` is blocked; use Monitor with an until-loop to wait on a condition.\n\n# Git\n- Interactive flags (`-i`, e.g. `git rebase -i`, `git add -i`) are not supported in this environment.\n- Use the `gh` CLI for GitHub operations (PRs, issues, API).\n- GitHub notifies the owner of any `@name` written in a PR, issue, or comment. Write a bare `@name` only for a real login you mean to notify. Put roles, placeholders, and code (`@human`, `@reviewer`, `@types/node`) in backticks or drop the `@`, even when copied from project files.\n- Commit or push only when the user asks. If on the default branch, branch first.\n- End git commit messages and PR bodies with the attribution lines given in the conversation's system-reminder, when one is present.",
+      "description": "Executes a bash command and returns its output.\n\n- `cd` carries to the next call only in the main session, if the command succeeds and ends inside the working directories. Outside them the shell returns to the start folder; otherwise it stays where it was. Prefer absolute paths — `cd` in a compound command can trigger a permission prompt. Shell state (env vars, functions) does not persist; the shell is initialized from the user's profile.\n- IMPORTANT: Avoid using this tool to run `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user.\n- Command output is displayed to you, not reliably to the user.\n- `timeout` is in milliseconds: default 120000, max 600000 for a foreground command.\n- `run_in_background` runs the command detached: it keeps running across turns and re-invokes you when it exits. With it, `timeout` is how long the command may run in the background (default 600000, max 7200000); at that limit it is stopped and you are re-invoked. No `&` needed. Foreground `sleep` is blocked; use Monitor with an until-loop to wait on a condition.\n\n# Git\n- Interactive flags (`-i`, e.g. `git rebase -i`, `git add -i`) are not supported in this environment.\n- Use the `gh` CLI for GitHub operations (PRs, issues, API).\n- GitHub notifies the owner of any `@name` written in a PR, issue, or comment. Write a bare `@name` only for a real login you mean to notify. Put roles, placeholders, and code (`@human`, `@reviewer`, `@types/node`) in backticks or drop the `@`, even when copied from project files.\n- Commit or push only when the user asks. If on the default branch, branch first.\n- End git commit messages and PR bodies with the attribution lines given in the conversation's system-reminder, when one is present.",
       "input_schema": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "type": "object",
@@ -1525,7 +1525,7 @@
     "accept-encoding",
     "content-length"
   ],
-  "anthropic_beta": "claude-code-20250219,interleaved-thinking-2025-05-14,thinking-token-count-2026-05-13,context-management-2025-06-27,mid-conversation-tool-changes-2026-07-01,inline-tools-2026-09-15,advisor-tool-2026-03-01,advanced-tool-use-2025-11-20,effort-2025-11-24",
+  "anthropic_beta": "claude-code-20250219,interleaved-thinking-2025-05-14,context-management-2025-06-27,mid-conversation-tool-changes-2026-07-01,inline-tools-2026-09-15,advisor-tool-2026-03-01,thinking-token-count-2026-05-13,advanced-tool-use-2025-11-20,effort-2025-11-24",
   "header_values": {
     "accept": "application/json",
     "user-agent": "claude-cli/2.1.311 (external, sdk-cli)",
@@ -1533,7 +1533,7 @@
     "x-stainless-package-version": "0.128.0",
     "x-stainless-retry-count": "0",
     "x-stainless-runtime": "node",
-    "x-stainless-runtime-version": "v26.3.0",
+    "x-stainless-runtime-version": "v26.12.1",
     "x-stainless-timeout": "600",
     "anthropic-dangerous-direct-browser-access": "true",
     "anthropic-version": "2023-06-01",

package/dist/cli.js

@@ -393,6 +393,9 @@ async function proxy() {
         || args.includes('--verbose=2')
         || process.env.DARIO_LOG_BODIES === '1';
     const verbose = verboseBodies || args.includes('--verbose') || args.includes('-v');
+    // --cache-trace / DARIO_CACHE_TRACE=1: one line per Codex request on what it
+    // shared with the previous request on its cache key (src/cache-trace.ts).
+    const cacheTrace = args.includes('--cache-trace') || process.env.DARIO_CACHE_TRACE === '1';
     const passthrough = args.includes('--passthrough') || args.includes('--thin');
     const preserveTools = args.includes('--preserve-tools') || args.includes('--keep-tools');
     const hybridTools = args.includes('--hybrid-tools') || args.includes('--context-inject');
@@ -792,7 +795,7 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, analyticsToken, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, shutdownGraceMs, upstreamTimeoutMs, poolStrategy, poolHeadroomFloor, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, familyFallback, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath, keySockets: keySockets.length > 0 ? keySockets : undefined });
+    await startProxy({ port, host, verbose, verboseBodies, cacheTrace, model, fastModel, noClaudeAuth, analyticsToken, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, shutdownGraceMs, upstreamTimeoutMs, poolStrategy, poolHeadroomFloor, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, familyFallback, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath, keySockets: keySockets.length > 0 ? keySockets : undefined });
 }
 /**
  * `dario keys` — named keys for a shared dario (v6.8, dario#1318). One
@@ -2387,6 +2390,10 @@ async function help() {
     --verbose, -v            Log all requests
     --verbose=2, -vv         Also dump redacted request bodies
                              (env: DARIO_LOG_BODIES=1)
+    --cache-trace            One line per ChatGPT (codex) request on what it
+                             shared with the previous request on its cache
+                             key: the gap, whether the input extends it, a
+                             seat or prompt change (env: DARIO_CACHE_TRACE=1)
     --log-file=PATH          Append one JSON-ND record per completed
                              request to PATH. Useful for backgrounded
                              proxies where stdout is unobserved (where

package/dist/codex-backend.d.ts

@@ -4,6 +4,7 @@ import { type ResponsesReasoningConfig, type ResponsesUsage } from './anthropic-
 import { type ModelResolver, type ClaudeTarget } from './claude-model.js';
 import { type EffortValue } from './effort.js';
 import type { MidstreamGuard } from './midstream.js';
+import { type CacheTraceResult } from './cache-trace.js';
 export declare const CODEX_BACKEND_BASE_URL: string;
 /** The usage endpoint the Codex CLI's /status reads, beside the Responses base. */
 export declare const CODEX_USAGE_URL: string;
@@ -52,7 +53,14 @@ export interface CodexForwardOutcome {
     stream: boolean;
     model: string;
     alias: string;
+    /** What the request shared with the previous one on its cache key (src/cache-trace.ts). Absent when no key went out. */
+    cache?: CodexCacheTrace;
 }
+/** The cache trace of one request, with the key it went out under (`traceKey()`: a caller's own key only as a digest). */
+export interface CodexCacheTrace extends CacheTraceResult {
+    key: string;
+}
+export declare function _resetCacheTraceForTest(): void;
 /** Why a forward DECLINED, for the caller's cool-down bookkeeping. `status` is
  *  the upstream status, or 0 when the request never got one (transport). */
 export interface CodexDecline {

package/dist/codex-backend.js

@@ -31,6 +31,7 @@ import { BAKED_BASE_MODELS } from './model-catalog.js';
 import { parseRetryAfterMs } from './provider-cooldown.js';
 import { upstreamDeadline } from './upstream-deadline.js';
 import { noteCodexUsageHeaders, parseCodexUsageEndpoint, recordCodexUsage, codexUsageFor } from './codex-usage.js';
+import { CacheTrace, itemHash, prefixHash, traceKey } from './cache-trace.js';
 export const CODEX_BACKEND_BASE_URL = process.env.DARIO_CODEX_BASE_URL || 'https://chatgpt.com/backend-api/codex';
 /** The usage endpoint the Codex CLI's /status reads, beside the Responses base. */
 export const CODEX_USAGE_URL = process.env.DARIO_CODEX_USAGE_URL || `${CODEX_BACKEND_BASE_URL.replace(/\/+$/, '').replace(/\/codex$/, '')}/wham/usage`;
@@ -130,6 +131,25 @@ export async function fetchCodexModels(creds, fetchImpl = fetch) {
     }
     return slugs;
 }
+// One trace per process: the comparison is between consecutive requests on a
+// key, whichever seat or client path they came through.
+let cacheTrace = new CacheTrace();
+export function _resetCacheTraceForTest() {
+    cacheTrace = new CacheTrace();
+}
+/**
+ * Make a request the one the next request on its key compares with. Called
+ * once a seat has accepted it: a declined attempt retried on a peer is the
+ * same request, and must not become its own predecessor.
+ */
+function rememberTrace(traced) {
+    if (!traced)
+        return;
+    try {
+        cacheTrace.remember(traced);
+    }
+    catch { /* the trace is a reading, not a step of the request */ }
+}
 /** The cached slug list for an alias WITHOUT fetching. For the admin surface:
  *  a status read must never cost an upstream call or a token refresh. */
 export function peekCodexModelSlugs(alias) {
@@ -884,13 +904,15 @@ timing) {
     });
     const model = String(body.model ?? '');
     let reported = false;
+    let cache;
+    let traced;
     const report = (status, usage) => {
         if (reported || !onDone)
             return;
         reported = true;
         try {
             onDone({ status, latencyMs: Date.now() - startedAt, upstreamTtfbMs: ttfbMs(), upstreamMs: upstreamMsNow(), inputTokens: usage?.input ?? 0, outputTokens: usage?.output ?? 0,
-                cacheReadTokens: usage?.cacheRead ?? 0, cacheCreateTokens: usage?.cacheCreate ?? 0, stream: true, model, alias: creds.alias });
+                cacheReadTokens: usage?.cacheRead ?? 0, cacheCreateTokens: usage?.cacheCreate ?? 0, stream: true, model, alias: creds.alias, cache });
         }
         catch { /* never break a served request */ }
     };
@@ -905,6 +927,20 @@ timing) {
     // default to make its next turn's previous_response_id resolvable, and
     // Codex CLI sends false itself.
     const upstreamBody = { ...body, stream: true };
+    // The same trace as forwardToCodex, under the key the client sent (Codex CLI
+    // sends its session id on every request); none when it sent no key.
+    // Compared here, remembered only once the seat accepts the request.
+    try {
+        const key = typeof body.prompt_cache_key === 'string' ? body.prompt_cache_key : '';
+        if (key) {
+            // The Responses API also takes a bare string input: one item, so a
+            // changed string diverges like a changed message would.
+            const input = Array.isArray(body.input) ? body.input : typeof body.input === 'string' ? [body.input] : [];
+            traced = { key, alias: creds.alias, prefix: prefixHash(body), items: input.map(itemHash), at: Date.now() };
+            cache = { key: traceKey(key, false), ...cacheTrace.peek(traced) };
+        }
+    }
+    catch { /* the trace is a reading, not a step of the request */ }
     const target = `${CODEX_BACKEND_BASE_URL.replace(/\/$/, '')}/responses`;
     const abort = new AbortController();
     let clientGone = false;
@@ -963,6 +999,7 @@ timing) {
             report(clientGone ? 499 : upstream.status, null);
             return true;
         }
+        rememberTrace(traced);
         res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', 'Access-Control-Allow-Origin': corsOrigin, ...securityHeaders, ...splitHeaders() });
         timeout.streaming();
         const reader = upstream.body.getReader();
@@ -1118,6 +1155,8 @@ timing) {
         fetchStartedAt: fetchStartedAt || Date.now(), upstreamTtfbMs: ttfbMs(),
     });
     let reported = false;
+    let cache;
+    let traced;
     const report = (status, usage, stream, model) => {
         if (reported || !onDone)
             return;
@@ -1127,7 +1166,7 @@ timing) {
                 status, latencyMs: Date.now() - startedAt, upstreamTtfbMs: ttfbMs(), upstreamMs: upstreamMsNow(),
                 inputTokens: usage?.input ?? 0, outputTokens: usage?.output ?? 0,
                 cacheReadTokens: usage?.cacheRead ?? 0, cacheCreateTokens: usage?.cacheCreate ?? 0,
-                stream, model, alias: creds.alias,
+                stream, model, alias: creds.alias, cache,
             });
         }
         catch { /* a reporting failure must never break a served request */ }
@@ -1155,10 +1194,27 @@ timing) {
     const upstreamBody = isAnthropic
         ? { ...anthropicToResponsesRequest(parsed, model, effort ? { effort } : {}), stream: true }
         : chatCompletionsToResponses(parsed);
+    const ownCacheKey = upstreamBody.prompt_cache_key;
     const scrubbed = toCodexSupportedBody({
         ...upstreamBody,
         prompt_cache_key: codexPromptCacheKey(shape, parsed, upstreamBody),
     });
+    // What this request shares with the previous one on its key, for the
+    // analytics row and the log line (src/cache-trace.ts). Hashes only, and a
+    // failure here never costs the request. Compared here, remembered only once
+    // the seat accepts the request.
+    try {
+        const key = String(scrubbed.prompt_cache_key ?? '');
+        if (key) {
+            const input = Array.isArray(scrubbed.input) ? scrubbed.input : [];
+            // Kept as is only when dario derived it; a client's own key is digested
+            // whatever it looks like.
+            const derived = !(typeof ownCacheKey === 'string' && ownCacheKey.length > 0);
+            traced = { key, alias: creds.alias, prefix: prefixHash(scrubbed), items: input.map(itemHash), at: Date.now() };
+            cache = { key: traceKey(key, derived), ...cacheTrace.peek(traced) };
+        }
+    }
+    catch { /* the trace is a reading, not a step of the request */ }
     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
@@ -1277,6 +1333,7 @@ timing) {
             report(upstream.status, null, clientWantsStream, model);
             return true;
         }
+        rememberTrace(traced);
         // OpenAI shape: one stateful line-in/line-out translator (unchanged).
         // Anthropic shape: parse the typed Responses event stream, then map events
         // to Anthropic SSE, keeping the terminal `response` for the collapse.

package/dist/proxy.d.ts

@@ -4,6 +4,7 @@ import { getAccessToken, getStatus } from './oauth.js';
 import { type EffortValue } from './cc-template.js';
 import { type KeySocket } from './keys.js';
 import { type BackendCredentials } from './openai-backend.js';
+import { type CodexCacheTrace } from './codex-backend.js';
 /**
  * Assemble the `x-anthropic-billing-header` system-block text, following
  * Claude Code's format:
@@ -358,6 +359,7 @@ interface ProxyOptions {
     host?: string;
     verbose?: boolean;
     verboseBodies?: boolean;
+    cacheTrace?: boolean;
     model?: string;
     fastModel?: string;
     noClaudeAuth?: boolean;
@@ -743,7 +745,18 @@ export interface ProxyLogEntry {
     reject?: string;
     error?: string;
     event?: string;
+    /** The cache trace of a Codex request (src/cache-trace.ts): the key it went out under and what it shared with the previous request on that key. */
+    cache_key?: string;
+    cache_items?: number;
+    cache_since_ms?: number | null;
+    cache_prev_items?: number | null;
+    cache_extends?: boolean | null;
+    cache_diverged_at?: number | null;
+    cache_seat_changed?: boolean | null;
+    cache_prefix_changed?: boolean | null;
 }
+/** The log fields of a cache trace; nothing when the request carried none. */
+export declare function cacheLogFields(c: CodexCacheTrace | undefined): Partial<ProxyLogEntry>;
 /**
  * Append a JSON-ND line to the proxy log file. No-op when stream is
  * null (logFile not configured). Errors are swallowed — log writes

package/dist/proxy.js

@@ -33,6 +33,7 @@ import { handleAdminRequest } from './admin-api.js';
 import { createTokenBucket } from './rate-limit.js';
 import { getOpenAIBackend, isOpenAIModel, forwardToOpenAI, isMiniMaxBackend, MINIMAX_MODELS } from './openai-backend.js';
 import { forwardToCodex, forwardResponsesToCodex, getCodexModelSlugs, peekCodexModelSlugs, isCodexModel, pickCodexFallback, pickClaudeTarget, CODEX_BACKEND_BASE_URL } from './codex-backend.js';
+import { formatCacheTraceLine } from './cache-trace.js';
 import { effortForCodex } from './effort.js';
 import { MidstreamGuard, guardFor, loopbackBaseFor, chaosCutFetch, chaosCutState, CONTINUATION_HEADER, CONTINUATION_OF_HEADER, MAX_CONTINUATION_DEPTH, continuationDepth, continuationOfRequest } from './midstream.js';
 /**
@@ -1075,6 +1076,15 @@ export const OPENAI_MODELS_LIST = buildOpenAIModelsList(withLongContextVariants(
 export function requiresClaudeLogin(poolSize, adminEnabled, hasUpstreamApiKey, noClaudeAuth, hasCodexAccount = false) {
     return poolSize === 0 && !adminEnabled && !hasUpstreamApiKey && !noClaudeAuth && !hasCodexAccount;
 }
+/** The log fields of a cache trace; nothing when the request carried none. */
+export function cacheLogFields(c) {
+    if (!c)
+        return {};
+    return {
+        cache_key: c.key, cache_items: c.items, cache_since_ms: c.sinceMs, cache_prev_items: c.prevItems,
+        cache_extends: c.extends, cache_diverged_at: c.divergedAt, cache_seat_changed: c.seatChanged, cache_prefix_changed: c.prefixChanged,
+    };
+}
 /**
  * Append a JSON-ND line to the proxy log file. No-op when stream is
  * null (logFile not configured). Errors are swallowed — log writes
@@ -1418,6 +1428,11 @@ export async function startProxy(opts = {}) {
     // -v stays quiet because bodies can carry file content and tool
     // output. Reported in dario#40 by @ringge.
     const verboseBodies = Boolean(opts.verboseBodies) || process.env.DARIO_LOG_BODIES === '1';
+    // Cache trace line: --cache-trace / DARIO_CACHE_TRACE=1, and under -v. One
+    // line per Codex request saying what it shared with the previous request on
+    // its cache key (src/cache-trace.ts), so a low cache share can be read as
+    // a timing, a shape or a seat problem instead of a number.
+    const cacheTraceLines = Boolean(opts.cacheTrace) || process.env.DARIO_CACHE_TRACE === '1' || verbose;
     // Operator-declared beta passthrough set. Sourced from CLI flag or env;
     // both are CSV strings of beta-flag names. Trimmed, deduped, empty
     // entries dropped. Stays a Set for fast membership checks in the per-
@@ -4394,6 +4409,7 @@ export async function startProxy(opts = {}) {
                                 latencyMs: o.latencyMs, status: o.status, isStream: o.stream, isOpenAI,
                                 continuation: continuationOf(codexGuard, requestDepth),
                                 timing: { queueMs, pacingMs: 0, upstreamTtfbMs: o.upstreamTtfbMs, upstreamMs: o.upstreamMs, totalMs: Math.max(0, Date.now() - arrivedAt) },
+                                cache: o.cache,
                             });
                             writeLogLine(logFileStream, {
                                 ts: new Date().toISOString(), req: codexReq,
@@ -4403,12 +4419,15 @@ export async function startProxy(opts = {}) {
                                 claim: CODEX_CLAIM, bucket: 'subscription', account: o.alias, consumer, stream: o.stream,
                                 ...(codexGuard?.outcome ? { continued: codexGuard.outcome, continued_by: codexGuard.continuedBy ?? undefined, continued_after: codexGuard.partialChars } : {}),
                                 ...continuationLeg,
+                                ...cacheLogFields(o.cache),
                             });
                             if (verbose)
                                 console.log(formatUsageLogLine(codexReq, {
                                     inputTokens: o.inputTokens, outputTokens: o.outputTokens,
                                     cacheReadTokens: o.cacheReadTokens, cacheCreateTokens: o.cacheCreateTokens,
                                 }, consumer));
+                            if (cacheTraceLines && o.cache)
+                                console.log(formatCacheTraceLine(codexReq, o.cache.key, o.cache, o, o.alias));
                         };
                         // Mid-flight seat failover. A 429 lands BEFORE any body is written —
                         // forwardToCodex only returns false on the decline path — so the same

package/docs/analytics.md

@@ -77,6 +77,26 @@ scrape_configs:
     authorization: { credentials: '<DARIO_ANALYTICS_TOKEN>' }
 ```
 
+## The cache trace
+
+A ChatGPT (codex) request reports how much of its prompt the backend read from its cache, and that number alone cannot say why a turn missed. dario records next to it what it can see before the request goes out that bears on a hit (`src/cache-trace.ts`). These narrow a miss down to likely causes; they do not prove one:
+
+| field | says | a miss reads as |
+|---|---|---|
+| `sinceMs` | ms since the previous request on the same `prompt_cache_key`; null on the first | a write is not readable at once, so a turn close behind the last may read nothing it wrote; the gap is measured, the backend's readiness is not |
+| `items`, `prevItems`, `extends` | input items now and before, and whether the previous input is a strict prefix of this one, item for item; `extends` is null when the previous input ran past the first 2000 items, which are all that is kept; input items only, the front of the prompt is `prefixChanged` | a client that rewrites or reorders its history has no prefix to hit |
+| `divergedAt` | the first input item that differs, when one does | which turn the rewrite happened at |
+| `prefixChanged` | the model, system prompt or tool names changed between the two; tool schemas are not compared | the front of the prompt moved, so nothing behind it can match |
+| `seatChanged` | a different account served this one | the cache is per account; a conversation that moved seats starts over |
+
+The trace is hashes and counts only: no content leaves the request. It rides on every `/analytics` row of that path as `cache` (with the `key`: dario's own derived `dario-…` key as it went out, a key the client set itself only as a `key-…` digest of it; a `/v1/responses` request goes through as the client wrote it, so it is traced under its own key, as Codex CLI sends one on every request, and carries no trace when it sent none), on the `--log-file` record as `cache_key`, `cache_items`, `cache_since_ms`, `cache_prev_items`, `cache_extends`, `cache_diverged_at`, `cache_seat_changed`, `cache_prefix_changed`, and with `--cache-trace` / `DARIO_CACHE_TRACE=1` (or `-v`) as one stdout line per request:
+
+```
+[dario] #412 cache: key=dario-3f9a2c7e1b0d44a6 seat=work since=3.1s items=23/21 extends=yes read=0/44120 (0%)
+```
+
+Read a run of them by key. `extends=yes` with `read=0`, a short `since` and no `prefix_changed` or `seat_changed` points at the backend's write delay rather than the shape of the input, but only as the likely explanation: the trace measures the gap, not when the write became readable, and `extends` compares input items only, so a changed tool schema, which the trace does not compare, misses the same way. `extends=no` with a `diverged_at` names the item the client changed; `prefix_changed` is a moved model, system prompt or tool name in front of an input that may still extend; `seat_changed` is the pool moving a conversation. The entry for a key is kept for an hour, longer than the backend keeps a prefix, so a stale key never reads as a live conversation.
+
 ## The rings
 
 `dario usage --donut` and `/analytics/donuts.svg` render the ledger's lifetime spend as three rings: **by model**, **by key** (empty until a named key or `x-dario-consumer` has traffic), and **subscription vs metered**. Each ring keeps the top five and folds the rest into *other*. Shares are of API-equivalent plus metered spend, so a model that only ever ran on an API key still shows.

package/docs/commands.md

@@ -39,9 +39,10 @@ This page is the per-flag reference. For environment variables grouped by task
 | `--host=<addr>` / `DARIO_HOST` | Bind address. Use `0.0.0.0` for LAN, or a specific IP (e.g. a Tailscale interface). When non-loopback, also set `DARIO_API_KEY`. | `127.0.0.1` |
 | `--verbose` / `-v` | Log every request (one line per request — method + path + billing bucket) | off |
 | `--verbose=2` / `-vv` / `DARIO_LOG_BODIES=1` | Also dump the outbound request body (redacted: bearer tokens, `sk-ant-*` keys, JWTs stripped; capped at 8KB). For wire-level client-compat debugging. | off |
+| `--cache-trace` / `DARIO_CACHE_TRACE=1` | One line per ChatGPT (codex) request on what it shared with the previous request on its `prompt_cache_key`: the gap in seconds, the input item counts, whether the input extends the previous one item for item (the shape a cache hit needs) and where it diverged if not, a seat change, a model, system prompt or tool change, and the cached share that came back. Also on under `-v`. The same facts ride on the `--log-file` record (`cache_*`) and the `/analytics` row (`cache`) whether or not the line is on. See [Analytics](./analytics.md#the-cache-trace). | off |
 | `--key-socket=<path>=<key>` / `DARIO_KEY_SOCKETS` | Also listen on a unix socket bound to one named key: every request on it is that key's, with no secret sent or stored by the caller; the socket's directory and group decide who may connect. Repeatable. See [Key sockets](./keys.md#a-key-with-no-secret-key-sockets). | none |
 | `--no-keys` / `DARIO_KEYS=0`; `--keys-path=<file>` / `DARIO_KEYS_PATH` | Ignore named keys (`~/.dario/keys.json`) so only `DARIO_API_KEY` authenticates; or move the file. See [Named keys](./keys.md). (v6.8) | on, `~/.dario/keys.json` |
-| `--log-file=<path>` / `DARIO_LOG_FILE` | Append one JSON-ND record per completed request to PATH. Useful for backgrounded proxies where stdout is unobserved (where `--verbose` can't help). Field set: `ts`, `req`, `method`, `path`, `model`, `status`, `latency_ms`, `in_tokens`, `out_tokens`, `cache_read`, `cache_create`, `claim`, `bucket`, `account`, `client`, `preserve_tools`, `stream`, plus `reject` / `error` on failure paths. Secrets scrubbed via the same redactor that `--verbose-bodies` uses; no request bodies. | off |
+| `--log-file=<path>` / `DARIO_LOG_FILE` | Append one JSON-ND record per completed request to PATH. Useful for backgrounded proxies where stdout is unobserved (where `--verbose` can't help). Field set: `ts`, `req`, `method`, `path`, `model`, `status`, `latency_ms`, `in_tokens`, `out_tokens`, `cache_read`, `cache_create`, `claim`, `bucket`, `account`, `client`, `preserve_tools`, `stream`, plus `reject` / `error` on failure paths, and on a ChatGPT (codex) request the cache trace `cache_key`, `cache_items`, `cache_since_ms`, `cache_prev_items`, `cache_extends`, `cache_diverged_at`, `cache_seat_changed`, `cache_prefix_changed`. Secrets scrubbed via the same redactor that `--verbose-bodies` uses; no request bodies. | off |
 | `--pool-fallback=<models>` / `DARIO_POOL_FALLBACK` / config `poolFallback.model` | Strictly opt-in. When every pool seat is drained or in auth cool-down (at selection, or mid-flight on a 429 with no peer left), serve the request as `<model>` from whichever provider can, instead of surfacing the 429/503. Accepts a **chain** — `gpt-5.6-sol,claude-sonnet-5` — read left to right, each provider taking the first entry it can serve. A Codex/ChatGPT subscription that lists the model is preferred (no per-token cost) and works on **both** wire shapes; otherwise a configured openai-compat backend, which is still OpenAI-path only (no Messages translation on that route). A chain also makes failover **symmetric**: a rate-limited or failing subscription hands the request back to the Claude pool. Only a 429/5xx fails over — a 400 surfaces, since a bad request would just reproduce itself elsewhere. Every substituted response carries `x-dario-pool-fallback: <model>` — never silent. Needs a Codex account (`dario add altman`) or a backend (`dario backend add …`); `dario doctor` reports it as INERT with neither. Empty pool still 503s (setup error, not traffic to re-bill). Empty flag value disables, overriding env + config. See [Pool-exhausted fallback](./multi-account-pool.md#pool-exhausted-fallback). | off |
 | `--family-fallback=<family=model,...>` / `DARIO_FAMILY_FALLBACK` / config `familyFallback` | Strictly opt-in. When a rate limit keeps every pool seat off a model family, serve that family's requests as `<model>` on the Claude pool, while some seat can serve the target's family. Written for Fable: its included credit runs out while the seat still has room for Opus, so `fable=claude-opus-5-5` keeps Fable traffic on the subscription instead of a local 429 until the credit resets. The target must be a `claude-*` model of another family; one step, never chained. Runs before `--pool-fallback`, so a pool with room for the target never leaves the Claude pool. Skipped in upstream API-key mode, under `--model`/`--fast-model` and for a seat-pinned request. A `[1m]` tag on the request carries over. Every switched response carries `x-dario-family-fallback: <requested model>`. Empty flag value disables, overriding env + config. See [Family fallback](./multi-account-pool.md#family-fallback). | off |
 | `--passthrough-betas=<csv>` / `DARIO_PASSTHROUGH_BETAS` | Beta flags ALWAYS forwarded upstream regardless of CC's captured set or the client's `anthropic-beta` header. Bypasses the billable-beta filter (so `extended-cache-ttl-*` survives if you opt in). Per-account rejection cache still applies — a pinned flag the upstream 400's gets dropped on retry rather than re-sent forever. Use when you know a beta works on your account but isn't in the captured template, or when client traffic should be force-augmented. Empty flag value (`--passthrough-betas=`) clears the env-default. | off |

package/docs/docker.md

@@ -109,6 +109,7 @@ All flags have env-var equivalents. The image sets sensible container defaults:
 | `DARIO_CORS_ORIGIN`       | unset            | Override the default `http://localhost:<port>` allow-list |
 | `DARIO_LOG_FILE`          | unset            | Path inside the container (mount a volume)    |
 | `DARIO_LOG_BODIES`        | unset            | `1` to log request/response bodies            |
+| `DARIO_CACHE_TRACE`       | unset            | `1` to log one cache-trace line per ChatGPT (codex) request, see [`docs/analytics.md`](./analytics.md#the-cache-trace) |
 | `DARIO_PASSTHROUGH_BETAS` | unset            | `1` to forward `anthropic-beta` headers as-is |
 | `DARIO_CLAUDE_BIN`        | unset            | Path to a Claude Code binary (optional, for live template capture) |
 | `DARIO_NO_BUN`            | unset            | `1` to skip the Bun auto-relaunch (not recommended) |

package/docs/multi-instance.md

@@ -136,6 +136,10 @@ Anthropic's token endpoint is the one mocked part, and only that — hammering t
 
 ## If you need true HA
 
-There is no shared-state mode today, and building one is a larger change than a lock: rate-limit snapshots and sticky bindings would both have to move out of process memory, which means every routing decision takes a network hop.
+Everything above is as far as dario goes today: shared credentials through the lock, and shared rate-limit readings and sticky bindings through `--pool-shared-state`, both eventually consistent and both failing open. Three things are still per instance:
 
-If you want that, say so on [#993](https://github.com/askalf/dario/issues/993) with your deployment shape. Concrete requirements are considerably more useful than a general "make it HA" — the design depends heavily on whether you need precise accounting or merely approximate.
+- **ChatGPT seats.** The Codex accounts have their own refresh flow and usage windows; neither the lock nor the shared state covers them.
+- **The ledger.** Each instance writes its own file, so `dario usage` and `/analytics` show that instance's share of the spend.
+- **The overage guard's halt**, which each instance tracks on its own.
+
+A design where every routing decision reads Redis on the request path is not planned: it adds a network hop per request and turns the coordination point into a hard dependency, which is exactly what the fail-open rule avoids. Extending the report-and-pull model to the ChatGPT seats is the natural next step. If you need it, say so on [#1733](https://github.com/askalf/dario/issues/1733) with your deployment shape: replica count, Claude only or both plans, and whether accounting has to be exact or may lag a pull interval.

package/docs/two-plans.md

@@ -26,9 +26,9 @@ curl localhost:3456/v1/messages -H 'content-type: application/json' \
 
 **Model names are discovered, not hardcoded.** The set a ChatGPT subscription may use is per-account and moves; dario asks the backend which models this account lists, caches the answer, and advertises them on `GET /v1/models`. Anything not on that list (`gpt-4o` and friends) still routes to a configured API-key backend as before. `codex:<model>` / `chatgpt:<model>` forces the route.
 
-Streaming, tool calls and tool-result round trips work on both shapes, and chat-shape `image_url` parts are carried as Responses `input_image` parts with `detail` preserved: dario translates chat/completions **or** Messages into the Responses API the subscription backend speaks, and translates the stream back into `chat.completion.chunk` or Anthropic message events. There is no `/v1/responses` inbound yet. The Codex backend does not accept every chat field, so `response_format`, `stop`, `n`, `logprobs`, `stream_options` and the sampling parameters `temperature`, `top_p`, `max_tokens`, `max_completion_tokens` are intentionally lossy; with `--verbose`, dario reports each field that does not reach Codex once per process. Codex accounts live in `~/.dario/codex-accounts/`, separate from the Claude pool.
+Streaming, tool calls and tool-result round trips work on both shapes, and chat-shape `image_url` parts are carried as Responses `input_image` parts with `detail` preserved: dario translates chat/completions **or** Messages into the Responses API the subscription backend speaks, and translates the stream back into `chat.completion.chunk` or Anthropic message events. A `/v1/responses` request needs no translation: the backend speaks that shape, so the body goes through as the client wrote it (model resolved) and the stream comes back untouched, on the same seats and failover as the other shapes (see [Codex CLI](./integrations/codex-cli.md)). The Codex backend does not accept every chat field, so `response_format`, `stop`, `n`, `logprobs`, `stream_options` and the sampling parameters `temperature`, `top_p`, `max_tokens`, `max_completion_tokens` are intentionally lossy; with `--verbose`, dario reports each field that does not reach Codex once per process. Codex accounts live in `~/.dario/codex-accounts/`, separate from the Claude pool.
 
-**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.
+**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. When the share is lower than the conversation shape would predict, the [cache trace](./analytics.md#the-cache-trace) shows what may explain it: turns close enough together that the write may not yet have been readable, a rewritten history, a changed system prompt or tool names, or a changed seat.
 
 ## Failover between subscriptions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.17.1",
+  "version": "6.18.0",
   "description": "Use your Claude and ChatGPT subscriptions in Cursor, Cline, Aider, Claude Code and the Agent SDK at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint: either plan answers either wire shape, opt-in failover when one hits its limit, and a ledger of what each plan absorbed.",
   "type": "module",
   "bin": {