pi-freeflow 1.40.0 → 1.41.0

package/src/stream-pipe.ts

@@ -16,9 +16,16 @@ import {
  WATCHDOG_SSE_MIN_SAMPLES,
  WATCHDOG_SSE_WINDOW,
 } from "./config.ts";
-import { cloakMessagesContent, looksLikeSse, type CaseRestoreMap, type FindGlobRestore } from "./opencode-fingerprint.ts";
+import {
+	accumulateToolCallName,
+	cloakMessagesContent,
+	looksLikeSse,
+	type CaseRestoreMap,
+	type FindGlobRestore,
+} from "./opencode-fingerprint.ts";
 import { restoreToolNameForCaller } from "./tool-translation.ts";
 import { repairToolArguments } from "./tool-args.ts";
+import type { ToolcallRepairSink, ToolcallStreamAudit } from "./toolcall-audit.ts";
 
 /**
  * A premature stream end counts as "substantial" only when BOTH thresholds
@@ -27,6 +34,17 @@ import { repairToolArguments } from "./tool-args.ts";
  */
 export const SUBSTANTIAL_MIN_CHUNKS = 50;
 export const SUBSTANTIAL_MIN_BYTES = 100 * 1024;
+// Body-stall cut for streamed upstream bodies (see pipeUpstreamStream).
+// Generous: every healthy stream observed on this proxy re-arms it within a
+// few hundred ms; a 120s byte-silence on an open socket is a wedged relay
+// leg, not a building model.
+let bodyStallCutMs = 120_000;
+/** Test-only: override the body-stall cut; returns a restore function. */
+export function _setBodyStallCutForTest(ms: number): () => void {
+ const prev = bodyStallCutMs;
+ bodyStallCutMs = ms;
+ return () => { bodyStallCutMs = prev; };
+}
 // Bounded lookahead for a streaming response whose upstream omitted the
 // content-type: the pipe holds at most this many bytes while it waits for SSE
 // evidence, then classifies the body itself (raw passthrough on overflow —
@@ -49,6 +67,29 @@ const TOOL_CALL_MARKERS = [
  "custom_tool_call_input",
  '"tool_calls"',
 ];
+// Same wire evidence for the tool-call audit gate, plus the Anthropic
+// argument-fragment event: those deltas carry no tool_use marker of their own
+// (the `content_block_start` did), yet the recorder needs every fragment to
+// classify the call, so they must reach observe() too.
+const AUDIT_TOOL_MARKERS = [...TOOL_CALL_MARKERS, '"type":"input_json_delta"'];
+// Turn-end frames carry the finish reason but no tool marker. They are the
+// only evidence a tool turn ended in plain text, so the audit gate must let
+// them through; matching the populated form (not the ubiquitous
+// `"finish_reason":null` delta) keeps the gate at one extra block per turn.
+const AUDIT_TURN_END_MARKERS = [
+ '"finish_reason":"stop"',
+ '"finish_reason":"tool_calls"',
+ '"finish_reason":"length"',
+ '"finish_reason":"content_filter"',
+ '"stop_reason":"end_turn"',
+ '"stop_reason":"tool_use"',
+ '"stop_reason":"max_tokens"',
+ '"stop_reason":"stop_sequence"',
+ '"response.completed"',
+ '"response.incomplete"',
+ '"response.failed"',
+];
+const AUDIT_MARKERS = [...AUDIT_TOOL_MARKERS, ...AUDIT_TURN_END_MARKERS];
 
 export function isSubstantial(chunks: number, bytes: number): boolean {
  return chunks > SUBSTANTIAL_MIN_CHUNKS && bytes > SUBSTANTIAL_MIN_BYTES;
@@ -279,38 +320,112 @@ export interface StreamCloakOptions {
 export interface SseStreamCloakState {
  responsesDroppedByIndex: Map<number, boolean>;
  responsesDroppedByItemId: Map<string, boolean>;
- chatDroppedByIndex: Map<number, boolean>;
  messagesDroppedByIndex: Map<number, boolean>;
  /** Output index -> tool name, so nameless argument deltas can find their schema. */
  responsesNameByIndex: Map<number, string>;
  /** Anthropic block index -> tool name, same purpose for input_json deltas. */
  messagesNameByIndex: Map<number, string>;
- /** Chat tool-call index -> restored tool name. */
- chatNameByIndex: Map<number, string>;
  /**
- * Argument fragments for tool calls whose schema admits a repair, keyed the
- * same way as the name maps above. Streaming APIs deliver arguments in
- * fragments, so a malformed packet can only be judged once complete: those
- * fragments are held here and re-emitted, repaired, on the call's terminal
- * event. Tools absent from `argSchemas` are never buffered, so their
- * arguments still stream incrementally exactly as before.
+ * Argument fragments for Anthropic tool_use blocks whose schema admits a
+ * repair, keyed the same way as the name map above. Streaming APIs deliver
+ * arguments in fragments, so a malformed packet can only be judged once
+ * complete: those fragments are held here and re-emitted, repaired, on the
+ * block's terminal event. Tools absent from `argSchemas` are never buffered,
+ * so their arguments still stream incrementally exactly as before.
  */
- chatArgsByIndex: Map<number, string>;
  messagesArgsByIndex: Map<number, string>;
+ /**
+ * Chat tool calls tracked PER CALL (defect K1): keyed by the upstream
+ * tool-call id whenever the provider sends one (`id:X`), else by the legacy
+ * index bucket (`idx:N`). Free models label EVERY parallel call `index: 0`
+ * while still sending per-call ids, so index-only keying merged their
+ * fragment streams: one call was silently lost and the other received a
+ * salvage of the merged junk. Drops, names, buffered arguments and the
+ * once-only flush guard are per call; an injected placeholder's drop
+ * verdict is never inherited by a real call that reuses its index.
+ */
+ chatCalls: Map<string, ChatTrackedCall>;
+ /**
+ * Observed delta index -> key of the call its id-less fragments currently
+ * belong to. Resolution mirrors the aggregate cloak exactly
+ * (sseToChatCompletionJson): an id-bearing delta (re)binds the index to its
+ * id-call; id-less deltas follow the current owner, else the legacy
+ * `idx:N` bucket. Never consulted for host-visible indices — that is what
+ * {@link chatIndexClaims} is for.
+ */
+ chatIndexOwner: Map<number, string>;
+ /** Host-index claims: index -> key of the call that FIRST assigned it. Set once, never rebound. */
+ chatIndexClaims: Map<number, string>;
+ /**
+ * Fresh sequential index handed out when a call's upstream index is already
+ * claimed by another tracked call; strictly above every index seen or
+ * assigned so far in this stream.
+ */
+ chatNextIndex: number;
+ /**
+ * Per-turn tool-call audit sink for the rewrites this state performs
+ * (index collisions, dropped name restatements, withheld arguments, repaired
+ * arguments). Absent when the caller did not request an audit.
+ */
+ audit?: ToolcallRepairSink;
 }
 
-export function createSseStreamCloakState(): SseStreamCloakState {
- return {
+/**
+ * Streaming state of ONE chat tool call. Exported only because it hangs off
+ * the exported per-stream state; treat it as pipe-internal.
+ */
+export interface ChatTrackedCall {
+ /** Never emit this call: injected placeholder, or a tool-less caller's call. */
+ dropped: boolean;
+ /**
+  * Restored host-facing name, folded from every name-bearing delta:
+  * fragments append, a delta that also carries arguments restates the whole
+  * name and replaces (see accumulateToolCallName).
+  */
+ name: string | undefined;
+ /**
+ * True once a name-bearing delta decided this tool is repairable and its
+ * fragments must be withheld: the packet is only judgeable once whole, so
+ * the fragments re-emerge whole+repaired on the call's terminal event.
+ */
+ buffered: boolean;
+ /** Buffered argument prefix while {@link buffered} is true ("" until a fragment arrives). */
+ args: string;
+ /**
+ * Host-visible index: the call's FIRST assigned index — its first observed
+ * index — unless that upstream index was claimed by another tracked call,
+ * in which case a fresh sequential index was handed out in arrival order.
+ */
+ hostIndex: number;
+ /** Emitted-once guard: a flush entry already went out for this call (terminal or end-of-stream). */
+ flushed: boolean;
+}
+
+/** Map key of a chat tool call that announced an upstream id. */
+function chatCallIdKey(id: string): string {
+ return `id:${id}`;
+}
+
+/** Legacy map key of the id-less fragment bucket for one observed delta index. */
+function chatIndexKey(idx: number): string {
+ return `idx:${idx}`;
+}
+
+export function createSseStreamCloakState(audit?: ToolcallRepairSink): SseStreamCloakState {
+ const state: SseStreamCloakState = {
   responsesDroppedByIndex: new Map(),
   responsesDroppedByItemId: new Map(),
-  chatDroppedByIndex: new Map(),
   messagesDroppedByIndex: new Map(),
   responsesNameByIndex: new Map(),
   messagesNameByIndex: new Map(),
-  chatNameByIndex: new Map(),
-  chatArgsByIndex: new Map(),
   messagesArgsByIndex: new Map(),
+  chatCalls: new Map(),
+  chatIndexOwner: new Map(),
+  chatIndexClaims: new Map(),
+  chatNextIndex: 0,
  };
+ if (audit !== undefined) state.audit = audit;
+ return state;
 }
 
 /**
@@ -334,11 +449,13 @@ export function flushBufferedToolArgs(
   const blocks: string[] = [];
   for (const [index, args] of state.messagesArgsByIndex) {
    const name = state.messagesNameByIndex.get(index) ?? "";
+   const repaired = repairToolArguments(name, args, cloak.argSchemas);
+   if (repaired !== args) state.audit?.repair("arguments-repaired", name);
    blocks.push(
     `event: content_block_delta\ndata: ${JSON.stringify({
      type: "content_block_delta",
      index,
-     delta: { type: "input_json_delta", partial_json: repairToolArguments(name, args, cloak.argSchemas) },
+     delta: { type: "input_json_delta", partial_json: repaired },
     })}\n\n`,
    );
   }
@@ -346,15 +463,21 @@ export function flushBufferedToolArgs(
   state.messagesNameByIndex.clear();
   return blocks.join("");
  }
- if (state.chatArgsByIndex.size === 0) return null;
  const calls: unknown[] = [];
- for (const [index, args] of state.chatArgsByIndex) {
-  const name = state.chatNameByIndex.get(index);
+ for (const call of state.chatCalls.values()) {
+  // The flushed guard makes this one-shot even when a terminal flush
+  // already emitted the call whole earlier in the stream.
+  if (!call.buffered || call.flushed) continue;
+  const name = call.name;
   if (name === undefined) continue;
-  calls.push({ index, type: "function", function: { name, arguments: repairToolArguments(name, args, cloak.argSchemas) } });
+  const args = call.args;
+  call.flushed = true;
+  call.buffered = false;
+  call.args = "";
+  const repairedArgs = repairToolArguments(name, args, cloak.argSchemas);
+  if (repairedArgs !== args) state.audit?.repair("arguments-repaired", name);
+  calls.push({ index: call.hostIndex, type: "function", function: { name, arguments: repairedArgs } });
  }
- state.chatArgsByIndex.clear();
- state.chatNameByIndex.clear();
  if (calls.length === 0) return null;
  return `data: ${JSON.stringify({ object: "chat.completion.chunk", choices: [{ index: 0, delta: { tool_calls: calls } }] })}\n\n`;
 }
@@ -462,7 +585,10 @@ function rewriteResponsesBlock(
     if (typeof parsed.output_index === "number") state.responsesNameByIndex.set(parsed.output_index, restored);
     if (type === "response.output_item.done") {
      rec.name = restored;
-     rec.arguments = repairToolArguments(restored, typeof rec.arguments === "string" ? rec.arguments : "", cloak.argSchemas);
+     const originalArgs = typeof rec.arguments === "string" ? rec.arguments : "";
+     const repairedArgs = repairToolArguments(restored, originalArgs, cloak.argSchemas);
+     if (repairedArgs !== originalArgs) state.audit?.repair("arguments-repaired", restored);
+     rec.arguments = repairedArgs;
      return emitSseBlock(event, JSON.stringify(parsed), hadEventPrefix);
     }
     if (restored !== rec.name) {
@@ -487,6 +613,7 @@ function rewriteResponsesBlock(
    if (name !== undefined) {
     const repairedArgs = repairToolArguments(name, parsed.arguments, cloak.argSchemas);
     if (repairedArgs !== parsed.arguments) {
+     state.audit?.repair("arguments-repaired", name);
      parsed.arguments = repairedArgs;
      return emitSseBlock(event, JSON.stringify(parsed), hadEventPrefix);
     }
@@ -535,48 +662,140 @@ function cloakStreamResponsesObject(resp: unknown, cloak: StreamCloakOptions): v
  (resp as Record<string, unknown>).output = kept;
 }
 
+/**
+ * Resolve ONE chat tool_calls record to its tracked call, registering the
+ * call on first sight.
+ *
+ * Keying mirrors the aggregate cloak (sseToChatCompletionJson): a record with
+ * a non-empty id is keyed `id:<id>`; an id-less record joins whatever call
+ * currently OWNS its index (`chatIndexOwner`, which id-bearing deltas
+ * rebind), else the legacy `idx:<index>` bucket — so id-less parallel calls
+ * sharing `index: 0` still merge into one fragment stream, exactly as
+ * before. Host index = the call's first observed index unless that upstream
+ * index is ALREADY CLAIMED by another tracked call (`chatIndexClaims`), in
+ * which case the next fresh sequential index is handed out in arrival order.
+ * The claim deliberately counts dropped calls too: the ticket rule is
+ * "claimed by ANOTHER tracked call", and a dropped placeholder has already
+ * moved the claim bookkeeping even though it emits nothing.
+ */
+function chatTrackedCall(
+ state: SseStreamCloakState,
+ rec: Record<string, unknown>,
+): { call: ChatTrackedCall; key: string; idx: number } {
+ const idx = typeof rec.index === "number" ? rec.index : 0;
+ if (idx + 1 > state.chatNextIndex) state.chatNextIndex = idx + 1;
+ const id = typeof rec.id === "string" && rec.id !== "" ? rec.id : undefined;
+ let key: string;
+ if (id !== undefined) {
+  key = chatCallIdKey(id);
+  // Id-bearing deltas (re)bind the index owner; later id-less fragments
+  // follow, and a real call reusing an injected placeholder's index takes
+  // the connection over instead of inheriting its drop verdict.
+  state.chatIndexOwner.set(idx, key);
+ } else {
+  key = state.chatIndexOwner.get(idx) ?? chatIndexKey(idx);
+ }
+ const known = state.chatCalls.get(key);
+ if (known !== undefined) return { call: known, key, idx };
+ // First sight: assign the host-visible index. A claimed upstream index
+ // forces a fresh sequential index above every index seen or assigned so
+ // far; the fresh index is itself claimed so a later real call keeps clear.
+ const claim = state.chatIndexClaims.get(idx);
+ let call: ChatTrackedCall;
+ if (claim === undefined) {
+  state.chatIndexClaims.set(idx, key);
+  call = { dropped: false, name: undefined, buffered: false, args: "", hostIndex: idx, flushed: false };
+ } else {
+  call = { dropped: false, name: undefined, buffered: false, args: "", hostIndex: state.chatNextIndex++, flushed: false };
+  state.chatIndexClaims.set(call.hostIndex, key);
+  // Audit: two tracked calls claimed one upstream index; the host index was
+  // re-homed sequentially so the wire stays well-formed.
+  state.audit?.repair("parallel-index-collision", `idx:${idx}`);
+ }
+ state.chatCalls.set(key, call);
+ return { call, key, idx };
+}
+
+/**
+ * Point one EMITTED chat tool_call delta at its call's host index. The
+ * rewrite must only ever fire in index-collision cases, so byte-identity
+ * holds for every single-call stream: an unchanged index is left untouched,
+ * and a record with NO index field (host-defaulted 0) only gains one when
+ * the host index is not 0.
+ */
+function chatRewriteDeltaIndex(rec: Record<string, unknown>, call: ChatTrackedCall): boolean {
+ if (typeof rec.index === "number") {
+  if (rec.index === call.hostIndex) return false;
+  rec.index = call.hostIndex;
+  return true;
+ }
+ if (call.hostIndex === 0) return false;
+ rec.index = call.hostIndex;
+ return true;
+}
+
 /**
  * Terminal chunk for chat choice: absorb any tool-call argument fragment
- * riding the finish_reason chunk into the buffered prefix, then re-emit every
- * buffered tool call's whole argument packet, repaired.
- * Returns true if delta was mutated.
+ * riding the finish_reason chunk into its call's buffered prefix, then
+ * re-emit every buffered call's whole argument packet, repaired, at ITS host
+ * index. Returns true if delta was mutated.
+ *
+ * Flush-entry id policy: entries keep today's exact shape
+ * {index, type:"function", function:{name,arguments}} WITHOUT the call id.
+ * Hosts assemble streamed tool_calls by index, and every delta of the call —
+ * including the id-bearing name-delta — is emitted at the same rewritten
+ * host index, so the host has already bound the id; the stable shape also
+ * keeps the single-call flush byte-identical.
  */
 function flushChatTerminalToolCalls(
  d: Record<string, unknown>,
  state: SseStreamCloakState,
  cloak: StreamCloakOptions,
- flushedIndices: Set<number>,
+ flushedKeys: Set<string>,
+ flushedEntries: Set<Record<string, unknown>>,
 ): boolean {
- if (state.chatArgsByIndex.size === 0) return false;
+ let rewrote = false;
 
  for (const tc of Array.isArray(d.tool_calls) ? d.tool_calls : []) {
   if (!tc || typeof tc !== "object" || Array.isArray(tc)) continue;
   const rec = tc as Record<string, unknown>;
-  const idx = typeof rec.index === "number" ? rec.index : 0;
+  const { call } = chatTrackedCall(state, rec);
   const fn = rec.function;
   const fnRec = fn && typeof fn === "object" && !Array.isArray(fn) ? (fn as Record<string, unknown>) : null;
-  if (fnRec && state.chatArgsByIndex.has(idx) && typeof fnRec.arguments === "string") {
-   state.chatArgsByIndex.set(idx, (state.chatArgsByIndex.get(idx) ?? "") + fnRec.arguments);
+  if (call.buffered && !call.flushed && fnRec && typeof fnRec.arguments === "string") {
+   call.args += fnRec.arguments;
   }
  }
 
  const flushed: unknown[] = [];
- for (const [idx, args] of state.chatArgsByIndex) {
-  const name = state.chatNameByIndex.get(idx);
+ for (const [key, call] of state.chatCalls) {
+  if (!call.buffered || call.flushed) continue;
+  const name = call.name;
   if (name === undefined) continue;
-  flushedIndices.add(idx);
-  flushed.push({ index: idx, type: "function", function: { name, arguments: repairToolArguments(name, args, cloak.argSchemas) } });
+  call.flushed = true;
+  call.buffered = false;
+  const args = call.args;
+  call.args = "";
+  flushedKeys.add(key);
+  const repairedArgs = repairToolArguments(name, args, cloak.argSchemas);
+  if (repairedArgs !== args) state.audit?.repair("arguments-repaired", name);
+  const entry = { index: call.hostIndex, type: "function", function: { name, arguments: repairedArgs } };
+  flushedEntries.add(entry);
+  flushed.push(entry);
  }
- state.chatArgsByIndex.clear();
- state.chatNameByIndex.clear();
 
- if (flushed.length === 0) return false;
+ if (flushed.length === 0 && !rewrote) return false;
 
+ // Records riding the finish chunk whose call was just flushed are removed
+ // (their fragments were absorbed above); surviving records keep flowing but
+ // are first pointed at their call's host index.
  const remaining = (Array.isArray(d.tool_calls) ? d.tool_calls : []).filter((tc) => {
   if (!tc || typeof tc !== "object" || Array.isArray(tc)) return true;
   const rec = tc as Record<string, unknown>;
-  const idx = typeof rec.index === "number" ? rec.index : 0;
-  return !flushedIndices.has(idx);
+  const { call, key } = chatTrackedCall(state, rec);
+  if (flushedKeys.has(key)) return false;
+  if (chatRewriteDeltaIndex(rec, call)) rewrote = true;
+  return true;
  });
  d.tool_calls = [...remaining, ...flushed];
  return true;
@@ -584,9 +803,12 @@ function flushChatTerminalToolCalls(
 
 /**
  * Rewrite one Chat Completions SSE block: drop injected delta.tool_calls
- * (including nameless argument continuations via per-index tracking), restore
- * surviving names. Tool-less callers lose all tool_calls with arguments
- * folded to content, mirroring the aggregate cloak. Null drops the block.
+ * (including nameless continuations via per-call tracking), restore surviving
+ * names, and keep host-visible indices true: collisions on one upstream
+ * index (free models label every parallel call index 0) are rewritten to
+ * distinct sequential indices while the call stays one call.
+ * Tool-less callers lose all tool_calls with arguments folded to content,
+ * mirroring the aggregate cloak. Null drops the block.
  */
 function rewriteChatBlock(
  block: string,
@@ -623,13 +845,14 @@ function rewriteChatBlock(
   }
   const d = delta as Record<string, unknown>;
   // Terminal chunk for this choice: re-emit every buffered tool call's whole
-  // argument packet, repaired. The fragments never went out, so this is the
-  // first and only time the client sees them. Runs before the tool_calls
-  // branch because the terminal chunk usually carries an empty delta.
-  // Indices flushed on this block: their arguments are final, so the
-  // per-delta loop below must not buffer them a second time.
-  const flushedIndices = new Set<number>();
-  if (c.finish_reason && flushChatTerminalToolCalls(d, state, cloak, flushedIndices)) {
+  // argument packet, repaired, at its host index. The fragments never went
+  // out, so this is the first and only time the client sees them. Runs
+  // before the tool_calls branch because the terminal chunk usually carries
+  // an empty delta. Call keys flushed on this block: their arguments are
+  // final, so the per-delta loop below must not buffer them a second time.
+  const flushedKeys = new Set<string>();
+  const flushedEntries = new Set<Record<string, unknown>>();
+  if (c.finish_reason && flushChatTerminalToolCalls(d, state, cloak, flushedKeys, flushedEntries)) {
    changed = true;
   }
   if (!Array.isArray(d.tool_calls)) {
@@ -640,13 +863,21 @@ function rewriteChatBlock(
   let folded = "";
   for (const tc of d.tool_calls as unknown[]) {
    if (!tc || typeof tc !== "object" || Array.isArray(tc)) continue;
+   // Flush entry rebuilt by the terminal flush above: pure passthrough.
+   // These carry no id, so key resolution would misbind them to whichever
+   // call currently owns the index — today's code skipped them the same way
+   // via the index-keyed flushedIndices set.
+   if (flushedEntries.has(tc as Record<string, unknown>)) {
+    kept.push(tc);
+    continue;
+   }
    const rec = tc as Record<string, unknown>;
-   const idx = typeof rec.index === "number" ? rec.index : 0;
+   const { call, key } = chatTrackedCall(state, rec);
    const fn = rec.function;
    const fnRec = fn && typeof fn === "object" && !Array.isArray(fn) ? (fn as Record<string, unknown>) : null;
    const name = fnRec && typeof fnRec.name === "string" && fnRec.name !== "" ? (fnRec.name as string) : "";
    if (!cloak.callerHadTools) {
-    state.chatDroppedByIndex.set(idx, true);
+    call.dropped = true;
     if (fnRec) {
      folded += (typeof fnRec.arguments === "string" && fnRec.arguments) || name;
     }
@@ -655,44 +886,75 @@ function rewriteChatBlock(
    }
    if (name !== "") {
     if (isInjectedName(name, cloak.injected)) {
-     state.chatDroppedByIndex.set(idx, true);
+     // The verdict is the CALL's, not the index's: a real id-bearing call
+     // reusing this index rebinds the fragment owner (chatIndexOwner) and
+     // inherits nothing.
+     call.dropped = true;
      changed = true;
      continue;
     }
     const restored = restoreStreamName(name, cloak);
-    if (restored !== name && fnRec) {
+    // Fold this delta's name into the call's accumulated name: a name-only
+    // delta is a fragment (append), a delta that ALSO carries arguments
+    // restates the whole name (replace) — same rule as the aggregate cloak,
+    // see accumulateToolCallName. When the restated name is the one the host
+    // already holds, it is dropped from the wire instead of re-sent: the host
+    // concatenates streamed name deltas, so a second copy would hand it
+    // `get_weatherget_weather`.
+    const previousName = call.name;
+    const hasArgs = fnRec !== null && typeof fnRec.arguments === "string" && fnRec.arguments !== "";
+    const toolName = accumulateToolCallName(previousName, restored, hasArgs);
+    const nameRepeated = hasArgs && previousName !== undefined && toolName === previousName;
+    call.name = toolName;
+    if (nameRepeated && fnRec) {
+     delete fnRec.name;
+     changed = true;
+     // Audit: the upstream restated a name the host already holds; the copy
+     // was kept off the wire so the host does not concatenate it.
+     state.audit?.repair("name-restated", toolName);
+    } else if (restored !== name && fnRec) {
      fnRec.name = restored;
      changed = true;
     }
-    state.chatDroppedByIndex.delete(idx);
-    state.chatNameByIndex.set(idx, restored);
-    if (isRepairableTool(restored, cloak.argSchemas) && !flushedIndices.has(idx)) {
+    call.dropped = false;
+    if (isRepairableTool(toolName, cloak.argSchemas) && !call.flushed && !flushedKeys.has(key)) {
      // Hold this call's arguments: the packet is only judgeable once whole,
      // so it is re-emitted repaired on the terminal finish_reason chunk.
-     state.chatArgsByIndex.set(idx, "");
+     // Reset-then-absorb mirrors the old per-index buffer exactly.
+     if (!call.buffered) state.audit?.repair("arguments-buffered", toolName);
+     call.buffered = true;
+     call.args = "";
      if (fnRec && typeof fnRec.arguments === "string" && fnRec.arguments !== "") {
-      state.chatArgsByIndex.set(idx, fnRec.arguments);
+      call.args = fnRec.arguments;
       delete fnRec.arguments;
       changed = true;
      }
+     if (nameRepeated && fnRec && Object.keys(fnRec).length === 0) {
+      // Repeat header whose name and arguments both moved elsewhere: the
+      // delta has nothing left to tell the host.
+      continue;
+     }
      kept.push(tc);
+     if (chatRewriteDeltaIndex(rec, call)) changed = true;
      continue;
     }
     kept.push(tc);
+    if (chatRewriteDeltaIndex(rec, call)) changed = true;
     continue;
    }
-   // Nameless continuation (argument chunk): follows the index verdict.
-   if (state.chatDroppedByIndex.get(idx) === true) {
+   // Nameless continuation (argument chunk): follows the CALL's verdict.
+   if (call.dropped) {
     changed = true;
     continue;
    }
-  if (state.chatArgsByIndex.has(idx) && fnRec && typeof fnRec.arguments === "string") {
-   state.chatArgsByIndex.set(idx, (state.chatArgsByIndex.get(idx) ?? "") + fnRec.arguments);
+  if (call.buffered && fnRec && typeof fnRec.arguments === "string") {
+   call.args += fnRec.arguments;
    delete fnRec.arguments;
    changed = true;
    continue;
   }
   kept.push(tc);
+  if (chatRewriteDeltaIndex(rec, call)) changed = true;
  }
   if (kept.length > 0) {
    d.tool_calls = kept;
@@ -802,6 +1064,7 @@ function rewriteMessagesBlock(
     rec.name = restored;
     state.messagesNameByIndex.set(index, restored);
     if (isRepairableTool(restored, cloak.argSchemas)) {
+     if (!state.messagesArgsByIndex.has(index)) state.audit?.repair("arguments-buffered", restored);
      state.messagesArgsByIndex.set(index, typeof rec.input === "string" ? rec.input : "");
     }
     return emitSseBlock(event, JSON.stringify(parsed), hadEventPrefix);
@@ -831,10 +1094,12 @@ function rewriteMessagesBlock(
   const name = state.messagesNameByIndex.get(index) ?? "";
   state.messagesArgsByIndex.delete(index);
   state.messagesNameByIndex.delete(index);
+  const repaired = repairToolArguments(name, buffered, cloak.argSchemas);
+  if (repaired !== buffered) state.audit?.repair("arguments-repaired", name);
   const flushed: Record<string, unknown> = {
    type: "content_block_delta",
    index,
-   delta: { type: "input_json_delta", partial_json: repairToolArguments(name, buffered, cloak.argSchemas) },
+   delta: { type: "input_json_delta", partial_json: repaired },
   };
   const stopBlock = emitSseBlock(event, JSON.stringify(parsed), hadEventPrefix);
   return `${emitSseBlock("content_block_delta", JSON.stringify(flushed), true)}\n\n${stopBlock}`;
@@ -905,6 +1170,14 @@ export interface StreamPipeOptions {
   * upstream omitted it; the pipe then classifies the buffered start itself.
   */
  upstreamContentType?: string | null;
+ /**
+  * Per-turn tool-call audit recorder (see toolcall-audit.ts). `observe` gets
+  * every forwarded SSE block that carries a tool marker — cloaked and
+  * bypassed streams alike, after any rewrite; `finish` is idempotent and the
+  * pipe calls it exactly once per turn (raw non-SSE bodies finish with
+  * `terminal: false`). Cloak rewrites also report through its `repair`.
+  */
+ audit?: ToolcallStreamAudit;
 }
 /**
  * Pipes an upstream readable stream to a client HTTP response.
@@ -958,7 +1231,17 @@ export function pipeUpstreamStream(
  // `end` already ran; `close` always trails it on a later tick).
  let refirePending = false;
  // Streaming cloak: per-stream rewrite state (null = byte-identical passthrough).
- const cloakState = cloak && !shouldBypassStreamCloak(cloak) ? createSseStreamCloakState() : null;
+ // The repair sink is wrapped because a throwing sink must never drop a chunk.
+ const auditRepairs = opts?.audit
+  ? {
+    repair: (kind: string, detail?: string): void => {
+     try {
+      opts.audit!.repair(kind, detail);
+     } catch { }
+    },
+   }
+  : undefined;
+ const cloakState = cloak && !shouldBypassStreamCloak(cloak) ? createSseStreamCloakState(auditRepairs) : null;
  // Holds the trailing incomplete SSE block across chunks; complete blocks are
  // rewritten and forwarded, so a function_call name split across chunks still
  // matches its injected record.
@@ -992,6 +1275,59 @@ export function pipeUpstreamStream(
  };
  // One-shot resume guard: the refire hook below fires at most once per turn.
  let refireUsed = false;
+ // Tool-call audit completion: exactly one finish per turn. A normal stream
+ // reports from both `end` and `close`, and a rescue hands the turn to a
+ // replacement stream — the guard keeps the report single (the recorder is
+ // idempotent; an external sink need not be).
+ let auditFinished = false;
+ const finishAudit = (terminal: boolean, unclassifiable = false): void => {
+  if (auditFinished) return;
+  auditFinished = true;
+  // An external sink must never change what the client receives.
+  try {
+   opts?.audit?.finish(unclassifiable ? { terminal, unclassifiable: true } : { terminal });
+  } catch { }
+ };
+
+ // Body-stall watchdog: after response headers a streaming body has no fixed
+ // total deadline (See relay.ts: the per-attempt timer is headers-only).
+ // The only failure left is a wedged leg that keeps the socket open
+ // and sends nothing — protected by a per-stream idle cut well above every
+ // observed healthy inter-chunk gap (thinking-heavy streams emit sub-second,
+ // even the slowest logged TTFB is tens of seconds). On expiry the CURRENT
+ // stream is destroyed with a relay-fault error so the truncation path
+ // (health mark + one mid-stream refire) owns the turn. Every forwarded byte
+ // re-arms it; end/close/error disarm it; a rescue re-arms the replacement.
+ let stallCutTimer: NodeJS.Timeout | undefined;
+ let stallCutStream: Readable | null = null;
+ const fireStallCut = (target: Readable): void => {
+  stallCutTimer = undefined;
+  stallCutStream = null;
+  if (target.destroyed || clientAborted || target !== nodeStream) return;
+  const stallErr = new Error(
+   `upstream body idle (no data for ${bodyStallCutMs}ms)`,
+  ) as Error & { code?: string };
+  stallErr.code = "FF_BODY_STALL";
+  stallErr.name = "TimeoutError";
+  target.destroy(stallErr);
+ };
+ const scheduleStallCut = (s: Readable): void => {
+  clearTimeout(stallCutTimer);
+  stallCutStream = s;
+  const timer = setTimeout(() => fireStallCut(s), bodyStallCutMs);
+  timer.unref?.();
+  stallCutTimer = timer;
+ };
+ const breatheStallCut = (): void => {
+  if (stallCutTimer !== undefined && stallCutStream === nodeStream) {
+   scheduleStallCut(nodeStream);
+  }
+ };
+ const disarmStallCut = (): void => {
+  clearTimeout(stallCutTimer);
+  stallCutTimer = undefined;
+  stallCutStream = null;
+ };
 
  const sniffThinking = (chunk: Buffer | string): boolean => {
   const s =
@@ -1033,7 +1369,12 @@ export function pipeUpstreamStream(
   chunk: string | Buffer,
   reason: "model" | "rate_limit",
  ): boolean => {
-  if (refirePending || heldFailureChunk !== null || sawToolCall) return false;
+  if (refirePending || heldFailureChunk !== null || sawToolCall) {
+   // Audit: the only veto worth recording is the tool-turn one — a resume
+   // would regenerate calls the host already received.
+   if (sawToolCall) opts?.audit?.refireSkipped();
+   return false;
+  }
   if (clientAborted || refireUsed || !opts?.refire || res.writableEnded || res.destroyed) return false;
   refireUsed = true;
   refirePending = true;
@@ -1115,6 +1456,10 @@ export function pipeUpstreamStream(
    try {
     if (!res.writableEnded) res.end();
    } catch { }
+   // The cut stream's own end/close may already have passed while this
+   // rescue was in flight, so completion is reported here instead (idempotent
+   // across the later close).
+   finishAudit(hasTerminalEvent);
    return;
   }
   heldFailureChunk = null;
@@ -1202,6 +1547,17 @@ export function pipeUpstreamStream(
    hasTerminalEvent = true;
   }
   terminalScanCarry = Buffer.from(scanBuf.subarray(Math.max(0, scanBuf.length - 32)));
+  // Per-turn tool-call audit: hand over the EXACT forwarded bytes of any block
+  // that carries a tool call (chat deltas, responses items, messages
+  // tool_use + argument fragments) or a populated turn-end marker (so a tool
+  // turn that ended in plain text records its finish reason). The recorder
+  // parses the block itself, so plain text/reasoning blocks are never copied.
+  // Dropped blocks returned before this point and are therefore never observed.
+  if (opts?.audit !== undefined && AUDIT_MARKERS.some((m) => text.includes(m))) {
+   try {
+    opts.audit.observe(text);
+   } catch { }
+  }
   deliver(text);
  };
  const sseBoundary = /\r?\n\r?\n/;
@@ -1262,6 +1618,11 @@ export function pipeUpstreamStream(
  const tryRefire = async (): Promise<boolean> => {
   if (clientAborted || refireUsed || !opts?.refire) return false;
   if (sawToolCall) {
+   // Audit: the resume budget was not spent because the turn already
+   // forwarded tool calls (a regeneration would duplicate them).
+   try {
+    opts?.audit?.refireSkipped();
+   } catch { }
    log("debug", "mid-stream refire skipped: turn already forwarded tool calls", { totalChunks, totalBytes }, rid);
    return false;
   }
@@ -1287,6 +1648,7 @@ export function pipeUpstreamStream(
   sseDecoder = new StringDecoder("utf8");
   terminalScanCarry = Buffer.alloc(0);
   watch(next);
+  scheduleStallCut(next);
   log("debug", "mid-stream refire: continuing turn on replacement stream", { totalChunks, totalBytes }, rid);
   return true;
  };
@@ -1341,6 +1703,7 @@ export function pipeUpstreamStream(
  };
  const onData = (chunk: Buffer | string): void => {
   try {
+   breatheStallCut();
    // While a replacement stream is being fetched the cut stream is stale:
    // its late frames must not interleave with the rescued turn.
    if (refirePending) return;
@@ -1386,6 +1749,7 @@ export function pipeUpstreamStream(
  };
 
  const onError = async (e: unknown): Promise<void> => {
+  disarmStallCut();
   // A rescue is already in flight (its outcome decides the turn): a late
   // error from the cut stream must not inject a terminal mid-rescue.
   if (refirePending) return;
@@ -1433,10 +1797,14 @@ export function pipeUpstreamStream(
    if (!res.writableEnded) {
     res.end();
    }
+   // Audit completion: no terminal SSE event was forwarded on this path (or
+   // one was, before the error); a rescue returned above and owns the report.
+   finishAudit(hasTerminalEvent);
   } catch { }
  };
 
  const onEnd = async (): Promise<void> => {
+  disarmStallCut();
   // A rescue is in flight (its outcome owns the turn): the cut stream's FIN
   // must neither inject a terminal nor end res mid-rescue.
   if (refirePending) return;
@@ -1453,6 +1821,10 @@ export function pipeUpstreamStream(
    try {
     if (!res.writableEnded) res.end();
    } catch { }
+   // Audit: a raw (non-SSE) body carries no event stream to inspect, so the
+   // turn is not classifiable: the summary says `remap: "unknown"` rather
+   // than accusing the model of answering without tools.
+   finishAudit(false, true);
    log(
     "debug",
     `non-SSE upstream body passed through verbatim — ${totalChunks} chunks (${(totalBytes / 1024).toFixed(1)}KB)`,
@@ -1539,9 +1911,12 @@ export function pipeUpstreamStream(
   try {
    if (!res.writableEnded) res.end();
   } catch { }
+  // Audit completion for the turn (idempotent; `close` trails this call).
+  finishAudit(hasTerminalEvent);
  };
 
  const onClose = async (): Promise<void> => {
+  disarmStallCut();
   // A stalled `close` trailing an `end` that is mid-rescue must neither
   // inject a terminal nor end res — the replacement stream owns the turn now.
   if (refirePending) return;
@@ -1592,6 +1967,11 @@ export function pipeUpstreamStream(
     }
    }
    if (!res.writableEnded) res.end();
+   // Audit completion: `end` normally already reported (the guard makes this
+   // a no-op then); a socket death or rescue teardown reports from here. Raw
+   // (non-SSE) bodies carry no event stream, so they are never terminal and
+   // never classifiable (`remap: "unknown"`).
+   finishAudit(bodyGate === "sse" && hasTerminalEvent, bodyGate !== "sse");
   } catch { }
  };
  const watch = (s: Readable): void => {
@@ -1603,6 +1983,7 @@ export function pipeUpstreamStream(
   s.on("close", () => { if (s === nodeStream) void onClose(); });
  };
  watch(nodeStream);
+ scheduleStallCut(nodeStream);
 
  req.on("aborted", () => {
   clientAborted = true;