chainlesschain 0.162.95 → 0.162.96

package/src/runtime/agent-core.js

@@ -43,6 +43,11 @@ import {
 import { createToolContext } from "../tools/tool-context.js";
 import { createToolTelemetryRecord } from "../tools/tool-telemetry.js";
 import { isAbortError, throwIfAborted } from "../lib/abort-utils.js";
+import {
+  isRetryableStreamError,
+  STREAM_RETRY_MAX,
+  STREAM_RETRY_BASE_MS,
+} from "../lib/stream-retry.js";
 import {
   annotateLines,
   replaceByHash,
@@ -154,9 +159,20 @@ function _killTask(task) {
   try {
     if (process.platform === "win32") {
       if (child.pid) {
-        spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+        const tk = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
           windowsHide: true,
         });
+        // A spawn that fails to launch emits an async 'error' event — with no
+        // listener Node rethrows it as an UNCAUGHT exception (the try/catch
+        // here can't catch the async emit), crashing the CLI. Handle it and
+        // fall back to a direct kill.
+        tk.on("error", () => {
+          try {
+            child.kill();
+          } catch {
+            /* already dead */
+          }
+        });
       } else {
         child.kill();
       }
@@ -684,7 +700,7 @@ export function computeProposedEdit(name, args = {}, cwd = process.cwd()) {
       }
       return {
         filePath,
-        newContent: content.replace(args.old_string, args.new_string),
+        newContent: content.replace(args.old_string, () => args.new_string),
         originalText: content,
       };
     }
@@ -953,7 +969,9 @@ export async function executeTool(name, args, context = {}) {
   // An explicit settings `allow` rule is the only bypass (exact user
   // pre-authorization); headless without a confirmer fails closed.
   if (
-    (name === "write_file" || name === "edit_file") &&
+    (name === "write_file" ||
+      name === "edit_file" ||
+      name === "notebook_edit") &&
     settingsVerdict.decision !== "allow" &&
     args?.path
   ) {
@@ -1212,7 +1230,8 @@ export async function executeTool(name, args, context = {}) {
   if (
     (name === "write_file" ||
       name === "edit_file" ||
-      name === "edit_file_hashed") &&
+      name === "edit_file_hashed" ||
+      name === "notebook_edit") &&
     toolResult &&
     typeof toolResult === "object" &&
     !toolResult.error &&
@@ -1271,6 +1290,173 @@ export function writeFileVerified(filePath, content, fsImpl = fs) {
   return { size: actual };
 }
 
+// Short, stable-ish id for a freshly inserted notebook cell (nbformat 4.5+).
+function _newNotebookCellId() {
+  return Math.random().toString(36).slice(2, 10);
+}
+
+/**
+ * Apply a single cell edit to a Jupyter notebook (.ipynb) given its raw text.
+ * Pure (no fs) + exported for tests. Returns `{ text, summary, cellId }` on
+ * success or `{ error }` on any validation failure — the caller writes `text`.
+ *
+ * edit_mode:
+ *   - "replace" (default): overwrite the target cell's source; a code cell also
+ *     gets outputs=[] + execution_count=null (stale output would be misleading).
+ *   - "insert": add a new cell of `cell_type` after the target (or at the top
+ *     when no target is given).
+ *   - "delete": remove the target cell.
+ * Target = cell_id (preferred) or 0-based cell_index.
+ */
+export function editNotebookCell(notebookText, args = {}) {
+  let nb;
+  try {
+    nb = JSON.parse(notebookText);
+  } catch {
+    return { error: "Notebook is not valid JSON (.ipynb)" };
+  }
+  if (!nb || !Array.isArray(nb.cells)) {
+    return { error: "Not a valid notebook: missing cells[] (need nbformat 4)" };
+  }
+  const mode = args.edit_mode || "replace";
+  if (!["replace", "insert", "delete"].includes(mode)) {
+    return { error: `Unknown edit_mode "${mode}" (replace|insert|delete)` };
+  }
+  // .ipynb stores source as an array of lines that each KEEP their trailing \n.
+  const toLines = (s) => {
+    const t = String(s ?? "");
+    return t === "" ? [] : t.split(/(?<=\n)/);
+  };
+  // Re-serialize with Jupyter's 1-space indent + trailing newline.
+  const out = (summary, cellId) => ({
+    text: JSON.stringify(nb, null, 1) + "\n",
+    summary,
+    cellId,
+  });
+  const locate = () => {
+    if (args.cell_id != null) {
+      return nb.cells.findIndex((c) => c && c.id === args.cell_id);
+    }
+    if (Number.isInteger(args.cell_index)) {
+      return args.cell_index >= 0 && args.cell_index < nb.cells.length
+        ? args.cell_index
+        : -1;
+    }
+    return -2; // no locator supplied
+  };
+
+  if (mode === "insert") {
+    if (typeof args.new_source !== "string") {
+      return { error: "new_source is required for edit_mode 'insert'" };
+    }
+    const ct = args.cell_type;
+    if (ct !== "code" && ct !== "markdown") {
+      return {
+        error:
+          "cell_type ('code'|'markdown') is required for edit_mode 'insert'",
+      };
+    }
+    const id = _newNotebookCellId();
+    const cell =
+      ct === "code"
+        ? {
+            cell_type: "code",
+            id,
+            metadata: {},
+            source: toLines(args.new_source),
+            outputs: [],
+            execution_count: null,
+          }
+        : {
+            cell_type: "markdown",
+            id,
+            metadata: {},
+            source: toLines(args.new_source),
+          };
+    let at = 0;
+    if (args.cell_id != null || Number.isInteger(args.cell_index)) {
+      const idx = locate();
+      if (idx < 0) return { error: "Target cell not found for insert" };
+      at = idx + 1; // insert AFTER the target
+    }
+    nb.cells.splice(at, 0, cell);
+    return out(`inserted ${ct} cell at index ${at}`, id);
+  }
+
+  // replace / delete both need an existing target
+  const idx = locate();
+  if (idx === -2) {
+    return {
+      error: "Provide cell_id or cell_index to identify the target cell",
+    };
+  }
+  if (idx < 0) {
+    return {
+      error: `Target cell not found (${
+        args.cell_id != null
+          ? "cell_id " + args.cell_id
+          : "cell_index " + args.cell_index
+      })`,
+    };
+  }
+
+  if (mode === "delete") {
+    const [removed] = nb.cells.splice(idx, 1);
+    return out(`deleted cell at index ${idx}`, removed?.id);
+  }
+
+  // replace
+  if (typeof args.new_source !== "string") {
+    return { error: "new_source is required for edit_mode 'replace'" };
+  }
+  const cell = nb.cells[idx];
+  cell.source = toLines(args.new_source);
+  if (cell.cell_type === "code") {
+    cell.outputs = [];
+    cell.execution_count = null;
+  }
+  return out(`replaced ${cell.cell_type} cell at index ${idx}`, cell.id);
+}
+
+/**
+ * Render a Jupyter notebook (.ipynb) as a compact, token-cheap cell listing so
+ * the model can locate cells (index + id + type + source) to edit with
+ * notebook_edit — instead of drowning in raw JSON / base64 output blobs. Cell
+ * OUTPUTS are summarized, not dumped. Pure + exported for tests; returns null
+ * when the text is not a parseable nbformat-4 notebook (caller falls back to raw).
+ */
+export function renderNotebook(text) {
+  let nb;
+  try {
+    nb = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!nb || !Array.isArray(nb.cells)) return null;
+  const srcOf = (c) =>
+    Array.isArray(c.source) ? c.source.join("") : String(c.source ?? "");
+  const lines = [
+    `Jupyter notebook — ${nb.cells.length} cell(s), nbformat ${nb.nbformat ?? "?"}. Edit cells with the notebook_edit tool (target by the id shown below). Pass raw:true to read_file for the underlying JSON.`,
+    "",
+  ];
+  nb.cells.forEach((c, i) => {
+    const id = c && c.id != null ? ` id=${c.id}` : "";
+    lines.push(`── Cell ${i} [${(c && c.cell_type) || "?"}${id}] ──`);
+    const src = srcOf(c || {});
+    lines.push(src.length ? src.replace(/\n$/, "") : "(empty)");
+    if (
+      c &&
+      c.cell_type === "code" &&
+      Array.isArray(c.outputs) &&
+      c.outputs.length
+    ) {
+      lines.push(`  ⟨${c.outputs.length} output(s) hidden⟩`);
+    }
+    lines.push("");
+  });
+  return lines.join("\n");
+}
+
 /**
  * Inner tool execution — no hooks, no plan-mode checks.
  */
@@ -1340,6 +1526,24 @@ async function executeToolInner(
         return attachDescriptor({ error: `File not found: ${filePath}` });
       }
       const content = fs.readFileSync(filePath, "utf8");
+      // Jupyter notebooks: render a compact cell listing (index/id/type/source,
+      // outputs summarized) so the model can find cells for notebook_edit
+      // without ingesting raw JSON / base64 output blobs. `raw:true` returns the
+      // underlying JSON. Non-.ipynb reads are unchanged.
+      if (args.raw !== true && /\.ipynb$/i.test(filePath)) {
+        const nbView = renderNotebook(content);
+        if (nbView) {
+          return attachDescriptor(
+            nbView.length > 50000
+              ? {
+                  content: nbView.substring(0, 50000) + "\n...(truncated)",
+                  size: nbView.length,
+                  notebook: true,
+                }
+              : { content: nbView, notebook: true },
+          );
+        }
+      }
       // Hashline mode: prefix each line with a 6-char content hash tag
       // so downstream edit_file_hashed calls can anchor by hash.
       const rendered = args.hashed === true ? annotateLines(content) : content;
@@ -1371,6 +1575,25 @@ async function executeToolInner(
       });
     }
 
+    case "notebook_edit": {
+      const filePath = path.resolve(cwd, args.path);
+      if (!fs.existsSync(filePath)) {
+        return attachDescriptor({ error: `Notebook not found: ${filePath}` });
+      }
+      const original = fs.readFileSync(filePath, "utf8");
+      const res = editNotebookCell(original, args);
+      if (res.error) return attachDescriptor({ error: res.error });
+      const wrote = writeFileVerified(filePath, res.text);
+      if (wrote.error) return attachDescriptor({ error: wrote.error });
+      return attachDescriptor({
+        success: true,
+        path: filePath,
+        size: wrote.size,
+        summary: res.summary,
+        cellId: res.cellId,
+      });
+    }
+
     case "edit_file": {
       const filePath = path.resolve(cwd, args.path);
       if (!fs.existsSync(filePath)) {
@@ -1380,7 +1603,10 @@ async function executeToolInner(
       if (!content.includes(args.old_string)) {
         return attachDescriptor({ error: "old_string not found in file" });
       }
-      const newContent = content.replace(args.old_string, args.new_string);
+      const newContent = content.replace(
+        args.old_string,
+        () => args.new_string,
+      );
       const wrote = writeFileVerified(filePath, newContent);
       if (wrote.error) return attachDescriptor({ error: wrote.error });
       return attachDescriptor({
@@ -2679,6 +2905,9 @@ export async function chatWithTools(rawMessages, options) {
             { model, messages: ollamaMessages, tools },
             options.onToken,
             signal,
+            options.onStall,
+            options.streamStallMs,
+            options.streamStallTimeoutMs,
           ),
         { signal, onRetry: options.onStreamRetry },
       );
@@ -2720,10 +2949,30 @@ export async function chatWithTools(rawMessages, options) {
       input_schema: t.function.parameters,
     }));
 
+    // Prompt caching (Claude-Code parity, default-on): the system prompt + the
+    // ~18 tool schemas are a large, stable prefix re-sent on every agent-loop
+    // iteration. Marking the LAST tool and the system block as cache
+    // breakpoints lets Anthropic serve that prefix from cache (~10% the input
+    // cost, lower latency) across iterations and turns. Anthropic ignores a
+    // breakpoint when the prefix is under the model's minimum cacheable size,
+    // so it is always safe. Opt out (e.g. a custom gateway that rejects the
+    // field) with CC_PROMPT_CACHE=0 or options.promptCaching:false.
+    const cacheEnabled =
+      options.promptCaching !== false && process.env.CC_PROMPT_CACHE !== "0";
+    if (cacheEnabled && anthropicTools.length > 0) {
+      const last = anthropicTools.length - 1;
+      anthropicTools[last] = {
+        ...anthropicTools[last],
+        cache_control: { type: "ephemeral" },
+      };
+    }
+
     // Model-aware max_tokens (Opus → 16384, Haiku → 4096, else 8192) via
     // provider-options. We read ONLY maxTokens: the module's `temperature`
     // default is never forwarded (400s on Opus 4.7/4.8).
-    const effModel = model || "claude-sonnet-4-20250514";
+    // Fallback to the CURRENT Sonnet, not a retired snapshot:
+    // claude-sonnet-4-20250514 was retired 2026-06-15 and would 404 here.
+    const effModel = model || "claude-sonnet-4-6";
     const { maxTokens: anthropicMaxTokens } = mergeProviderOptions(
       "anthropic",
       effModel,
@@ -2750,7 +2999,18 @@ export async function chatWithTools(rawMessages, options) {
     );
     if (thinkingParams) Object.assign(body, thinkingParams);
     if (systemMsgs.length > 0) {
-      body.system = systemMsgs.map((m) => m.content).join("\n");
+      const systemText = systemMsgs.map((m) => m.content).join("\n");
+      // Array-form system with a cache breakpoint when caching is on; plain
+      // string otherwise (byte-identical to the prior request shape).
+      body.system = cacheEnabled
+        ? [
+            {
+              type: "text",
+              text: systemText,
+              cache_control: { type: "ephemeral" },
+            },
+          ]
+        : systemText;
     }
 
     const url =
@@ -2771,6 +3031,9 @@ export async function chatWithTools(rawMessages, options) {
             options.onToken,
             signal,
             options.onThinking,
+            options.onStall,
+            options.streamStallMs,
+            options.streamStallTimeoutMs,
           ),
         { signal, onRetry: options.onStreamRetry },
       );
@@ -2795,8 +3058,15 @@ export async function chatWithTools(rawMessages, options) {
     const normalized = _normalizeAnthropicResponse(data);
     if (data.usage) {
       normalized.usage = {
+        // With prompt caching, Anthropic splits input into uncached
+        // `input_tokens` + cache read/write — capture all three so cost
+        // accounting prices the cached prefix correctly (read ≈ 0.1×,
+        // write ≈ 1.25× input). Absent (caching off) → 0, byte-identical.
         input_tokens: data.usage.input_tokens || 0,
         output_tokens: data.usage.output_tokens || 0,
+        cache_read_input_tokens: data.usage.cache_read_input_tokens || 0,
+        cache_creation_input_tokens:
+          data.usage.cache_creation_input_tokens || 0,
       };
     }
     return normalized;
@@ -2865,6 +3135,9 @@ export async function chatWithTools(rawMessages, options) {
           options.onToken,
           signal,
           provider,
+          options.onStall,
+          options.streamStallMs,
+          options.streamStallTimeoutMs,
         ),
       { signal, onRetry: options.onStreamRetry },
     );
@@ -2895,9 +3168,14 @@ export async function chatWithTools(rawMessages, options) {
   const choice = data.choices[0];
   const out = { message: choice.message };
   if (data.usage) {
+    // OpenAI/DeepSeek/volcengine report cached prompt tokens AS PART of
+    // prompt_tokens — split them out so cost prices the cached prefix at the
+    // provider's cache rate, not full input. 0 (or absent) → input unchanged.
+    const cached = _openaiCachedTokens(data.usage);
     out.usage = {
-      input_tokens: data.usage.prompt_tokens || 0,
+      input_tokens: Math.max(0, (data.usage.prompt_tokens || 0) - cached),
       output_tokens: data.usage.completion_tokens || 0,
+      cache_read_input_tokens: cached,
     };
   }
   return out;
@@ -3033,34 +3311,27 @@ export function formatProviderHttpError(provider, status) {
  * streamed (partial-output drops are preserved internally and never throw) — so
  * a retry can never duplicate visible text. Pure + exported for tests.
  */
-export function _isRetryableStreamError(err, signal) {
-  if (isAbortError(err)) return false;
-  if (signal && signal.aborted) return false;
-  if (!err) return false;
-  const code = String(err.code || err.cause?.code || "").toUpperCase();
-  if (
-    [
-      "ECONNRESET",
-      "ETIMEDOUT",
-      "ECONNREFUSED",
-      "EAI_AGAIN",
-      "EPIPE",
-      "ENETUNREACH",
-      "ENOTFOUND",
-      "UND_ERR_SOCKET",
-    ].includes(code)
-  ) {
-    return true;
-  }
-  const msg = String(err.message || err).toLowerCase();
-  return /econnreset|etimedout|econnrefused|eai_again|socket hang ?up|terminated|fetch failed|network error|timed?\s*out|premature close/.test(
-    msg,
-  );
-}
-
-/** Bounded auto-retry for streaming connection drops (Claude-Code 2.1.181). */
-const STREAM_RETRY_MAX = 2;
-const STREAM_RETRY_BASE_MS = 400;
+// Re-exported from the shared classifier (src/lib/stream-retry.js) so agent-core
+// internals and existing test imports keep resolving it from this module, while
+// the agent and chat streaming paths share ONE definition (no drift). The retry
+// budget constants (STREAM_RETRY_MAX / STREAM_RETRY_BASE_MS) come from there too.
+export const _isRetryableStreamError = isRetryableStreamError;
+// 2.1.185 parity: when a streaming response goes silent mid-flight (the TCP
+// connection is alive but no bytes arrive — a slow/overloaded API), surface a
+// "waiting for API response" hint after this many ms instead of leaving the
+// user staring at a frozen spinner. Upstream raised this from 10s to 20s.
+const STREAM_STALL_MS = 20000;
+// Hard inactivity timeout: a stream silent for this long is treated as a dead
+// connection — the watchdog cancels the reader and throws a RETRYABLE error so
+// `_retryStreamingChat` re-issues the request instead of hanging forever.
+// Default 180s mirrors the long-standing `cc chat`/`cc ask` stall guard
+// (chat-core.js STREAM_STALL_MS / CC_CHAT_STALL_MS) — generous enough that even
+// a slow local model's first token arrives in time, while still recovering from
+// a genuinely dead connection by default. Set llm.streamStallTimeoutMs (or pass
+// streamStallTimeoutMs: 0) to tune or disable. The 20s hint above still fires
+// first. Must exceed STREAM_STALL_MS.
+const STREAM_STALL_TIMEOUT_MS = 180000;
+const _STREAM_STALL = Symbol("stream-stall");
 
 /**
  * Run a streaming chat attempt with bounded auto-retry on transient API
@@ -3114,7 +3385,99 @@ function _finalizeTruncatedStream(finalize, state) {
   return out;
 }
 
-async function _chatOllamaStreaming(apiUrl, body, onToken, signal) {
+// Wrap a ReadableStream reader so the read loop yields chunk values while a
+// watchdog (a) fires `onStall(elapsedMs)` at most once per silent gap longer
+// than `stallMs` (2.1.185 stream-stall hint) and (b) — when `stallTimeoutMs` is
+// set — cancels the reader and throws a RETRYABLE ETIMEDOUT after that long a
+// silence, so a permanently dead-but-open connection recovers via the retry
+// layer instead of hanging forever. The SAME in-flight read() promise is
+// re-raced against a fresh timer each tick, so no chunk is ever dropped or
+// double-read; `done`, errors, and aborts propagate unchanged. With neither a
+// hook nor a timeout this degrades to a plain read loop (zero extra timers).
+export async function* _iterateStreamWithStall(reader, opts = {}) {
+  const onStall = typeof opts.onStall === "function" ? opts.onStall : null;
+  const stallMs = opts.stallMs ?? STREAM_STALL_MS;
+  const timeoutMs =
+    opts.stallTimeoutMs == null ? STREAM_STALL_TIMEOUT_MS : opts.stallTimeoutMs;
+  for (;;) {
+    const readP = reader.read();
+    // Fast path: nothing to watch for — await the chunk directly.
+    if (!onStall && !timeoutMs) {
+      const { done, value } = await readP;
+      if (done) return;
+      yield value;
+      continue;
+    }
+    const start = Date.now();
+    let notified = false;
+    let result;
+    for (;;) {
+      const elapsed = Date.now() - start;
+      // Hard inactivity timeout reached: cancel the dead stream (release the
+      // socket) and throw a retryable error the dispatch seam re-issues.
+      if (timeoutMs && elapsed >= timeoutMs) {
+        try {
+          await reader.cancel();
+        } catch {
+          /* best-effort release — the throw below is what matters */
+        }
+        const err = new Error(
+          `stream stalled: no data from API for ${Math.round(elapsed / 1000)}s`,
+        );
+        err.code = "ETIMEDOUT";
+        throw err;
+      }
+      // Wake at whichever fires first: the one-shot stall hint or the timeout.
+      const waits = [];
+      if (onStall && !notified) waits.push(stallMs - elapsed);
+      if (timeoutMs) waits.push(timeoutMs - elapsed);
+      const nextWait = waits.length ? Math.max(0, Math.min(...waits)) : null;
+      if (nextWait == null) {
+        // Hint already fired and no timeout — just wait for the chunk.
+        result = await readP;
+        break;
+      }
+      let timer;
+      const wakeP = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(_STREAM_STALL), nextWait);
+        if (timer && typeof timer.unref === "function") timer.unref();
+      });
+      let r;
+      try {
+        r = await Promise.race([readP, wakeP]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (r === _STREAM_STALL) {
+        // A timer woke us. Fire the one-shot hint if we've crossed stallMs; the
+        // loop re-evaluates `elapsed` to decide hint-vs-hard-timeout next tick.
+        if (onStall && !notified && Date.now() - start >= stallMs) {
+          notified = true;
+          try {
+            onStall(Date.now() - start);
+          } catch {
+            /* stall hint is best-effort — never break the stream over it */
+          }
+        }
+        continue; // keep awaiting the SAME read() against a fresh timer
+      }
+      result = r;
+      break;
+    }
+    if (result.done) return;
+    yield result.value;
+  }
+}
+
+async function _chatOllamaStreaming(
+  apiUrl,
+  body,
+  onToken,
+  signal,
+  onStall,
+  stallMs,
+  stallTimeoutMs,
+) {
   const response = await fetch(apiUrl, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -3129,9 +3492,11 @@ async function _chatOllamaStreaming(apiUrl, body, onToken, signal) {
   const decoder = new TextDecoder();
   let buf = "";
   try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
+    for await (const value of _iterateStreamWithStall(reader, {
+      onStall,
+      stallMs,
+      stallTimeoutMs,
+    })) {
       buf += decoder.decode(value, { stream: true });
       let idx;
       while ((idx = buf.indexOf("\n")) >= 0) {
@@ -3157,7 +3522,14 @@ async function _chatOllamaStreaming(apiUrl, body, onToken, signal) {
 // the same shape chatWithTools returns non-streamed.
 
 function _anthropicInitState() {
-  return { text: "", blocks: {}, inputTokens: 0, outputTokens: 0 };
+  return {
+    text: "",
+    blocks: {},
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheCreationTokens: 0,
+  };
 }
 
 function _anthropicReduceLine(state, raw, onToken, onThinking) {
@@ -3172,8 +3544,13 @@ function _anthropicReduceLine(state, raw, onToken, onThinking) {
     return state;
   }
   if (obj.type === "message_start") {
-    state.inputTokens =
-      Number(obj.message?.usage?.input_tokens) || state.inputTokens;
+    const u = obj.message?.usage || {};
+    state.inputTokens = Number(u.input_tokens) || state.inputTokens;
+    // Prompt-cache token counts ride message_start.usage (Anthropic caching).
+    state.cacheReadTokens =
+      Number(u.cache_read_input_tokens) || state.cacheReadTokens;
+    state.cacheCreationTokens =
+      Number(u.cache_creation_input_tokens) || state.cacheCreationTokens;
   } else if (obj.type === "content_block_start") {
     const cb = obj.content_block || {};
     state.blocks[obj.index] =
@@ -3252,10 +3629,17 @@ function _anthropicFinalize(state) {
   // tool turn — required by the API when extended thinking is on.
   if (thinkingBlocks.length) message._thinkingBlocks = thinkingBlocks;
   const out = { message };
-  if (state.inputTokens || state.outputTokens) {
+  if (
+    state.inputTokens ||
+    state.outputTokens ||
+    state.cacheReadTokens ||
+    state.cacheCreationTokens
+  ) {
     out.usage = {
       input_tokens: state.inputTokens,
       output_tokens: state.outputTokens,
+      cache_read_input_tokens: state.cacheReadTokens,
+      cache_creation_input_tokens: state.cacheCreationTokens,
     };
   }
   return out;
@@ -3276,6 +3660,9 @@ async function _chatAnthropicStreaming(
   onToken,
   signal,
   onThinking,
+  onStall,
+  stallMs,
+  stallTimeoutMs,
 ) {
   const response = await fetch(apiUrl, {
     method: "POST",
@@ -3291,9 +3678,11 @@ async function _chatAnthropicStreaming(
   const decoder = new TextDecoder();
   let buf = "";
   try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
+    for await (const value of _iterateStreamWithStall(reader, {
+      onStall,
+      stallMs,
+      stallTimeoutMs,
+    })) {
       buf += decoder.decode(value, { stream: true });
       const lines = buf.split("\n");
       buf = lines.pop() || "";
@@ -3316,8 +3705,30 @@ async function _chatAnthropicStreaming(
 // concatenated across chunks). usage rides the terminal chunk when
 // stream_options.include_usage was requested. Terminator: `data: [DONE]`.
 
+// OpenAI-compatible cached-prompt-token count. OpenAI / volcengine report it as
+// usage.prompt_tokens_details.cached_tokens; DeepSeek as
+// usage.prompt_cache_hit_tokens. In BOTH, prompt_tokens already INCLUDES the
+// cached count (unlike Anthropic, where input_tokens is the uncached remainder)
+// — so callers subtract it to recover the uncached input and avoid pricing the
+// cached prefix twice. Verified live against volcengine (field present, 0 when
+// the provider does not auto-cache).
+function _openaiCachedTokens(usage) {
+  if (!usage || typeof usage !== "object") return 0;
+  const detailed = Number(usage.prompt_tokens_details?.cached_tokens);
+  if (Number.isFinite(detailed) && detailed > 0) return detailed;
+  const deepseek = Number(usage.prompt_cache_hit_tokens);
+  if (Number.isFinite(deepseek) && deepseek > 0) return deepseek;
+  return 0;
+}
+
 function _openaiInitState() {
-  return { text: "", tools: [], inputTokens: 0, outputTokens: 0 };
+  return {
+    text: "",
+    tools: [],
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+  };
 }
 
 function _openaiReduceLine(state, raw, onToken) {
@@ -3354,7 +3765,11 @@ function _openaiReduceLine(state, raw, onToken) {
     }
   }
   if (obj.usage) {
-    state.inputTokens = Number(obj.usage.prompt_tokens) || state.inputTokens;
+    const cached = _openaiCachedTokens(obj.usage);
+    const prompt = Number(obj.usage.prompt_tokens);
+    if (Number.isFinite(prompt))
+      state.inputTokens = Math.max(0, prompt - cached);
+    if (cached) state.cacheReadTokens = cached;
     state.outputTokens =
       Number(obj.usage.completion_tokens) || state.outputTokens;
   }
@@ -3370,10 +3785,11 @@ function _openaiFinalize(state) {
   const message = { role: "assistant", content: state.text };
   if (toolCalls.length) message.tool_calls = toolCalls;
   const out = { message };
-  if (state.inputTokens || state.outputTokens) {
+  if (state.inputTokens || state.outputTokens || state.cacheReadTokens) {
     out.usage = {
       input_tokens: state.inputTokens,
       output_tokens: state.outputTokens,
+      cache_read_input_tokens: state.cacheReadTokens || 0,
     };
   }
   return out;
@@ -3393,6 +3809,9 @@ async function _chatOpenAIStreaming(
   onToken,
   signal,
   provider,
+  onStall,
+  stallMs,
+  stallTimeoutMs,
 ) {
   const response = await fetch(apiUrl, {
     method: "POST",
@@ -3411,9 +3830,11 @@ async function _chatOpenAIStreaming(
   const decoder = new TextDecoder();
   let buf = "";
   try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
+    for await (const value of _iterateStreamWithStall(reader, {
+      onStall,
+      stallMs,
+      stallTimeoutMs,
+    })) {
       buf += decoder.decode(value, { stream: true });
       const lines = buf.split("\n");
       buf = lines.pop() || "";