@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/responses/parser.ts

@@ -22,9 +22,9 @@ import { extractHostedWebSearch, WEB_SEARCH_TOOL_NAME } from "../web-search/synt
 import { buildImageTool, extractHostedImageGeneration, IMAGE_GEN_TOOL_NAME } from "../images/synthetic-tool";
 import { toolSearchDescription, toolSearchParameters } from "./tool-search-compat";
 
-function isObj(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
+import { isObj, inputContentParts, outputTextOf, outputToToolResultContent, toolOutputContainsEncryptedContent } from "./parser-content";
+import { mapToolChoice, buildTools, customToolNamespaces } from "./parser-tools";
+import { parseTextFormat } from "./parser-text-format";
 
 /**
  * Wrap a remembered proxy-side signature as provider metadata for a replayed tool call.
@@ -41,241 +41,7 @@ function replayThoughtSignatureMetadata(
   return signature ? { google: { thoughtSignature: signature } } : undefined;
 }
 
-type InputBlock =
-  | { type: "input_text"; text: string }
-  | { type: "text"; text: string }
-  | { type: "input_image"; image_url?: string; file_id?: string; detail?: string }
-  | { type: "input_video"; video_url?: string }
-  | { type: "input_file"; file_id?: string; filename?: string; file_data?: string };
-
-/** A usable reference string, or undefined. Empty strings and non-strings are not references. */
-function nonEmptyString(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-
-function inputContentParts(blocks: unknown): string | OcxContentPart[] {
-  if (typeof blocks === "string") return blocks;
-  // The catch-all can also hand back a non-array `content` (an object, a number), which would
-  // throw at the loop below before any per-block guard runs.
-  if (!Array.isArray(blocks)) return [];
-  const parts: OcxContentPart[] = [];
-  for (const raw of blocks) {
-    // A malformed message item fails its strict schema and falls through to inputItemSchema's
-    // permissive catch-all, so blocks reaching here are NOT guaranteed to match the declared
-    // shape. Validate each field before use, as outputToToolResultContent already does.
-    if (!isObj(raw)) continue;
-    const block = raw as InputBlock;
-    if (block.type === "input_text" || block.type === "text") {
-      if (typeof raw.text === "string") parts.push({ type: "text", text: raw.text });
-    } else if (block.type === "input_image") {
-      const b = block as { image_url?: string; file_id?: string; detail?: string };
-      const imageUrl = nonEmptyString(b.image_url);
-      const fileId = nonEmptyString(b.file_id);
-      const detail = nonEmptyString(b.detail);
-      if (imageUrl) {
-        // Preserve the image as a structured part — adapters send it as a native image block.
-        // NEVER inline the (often base64 data-URL) image_url as text: that explodes the token count.
-        parts.push({ type: "image", imageUrl, ...(detail ? { detail: normalizeImageDetail(detail) } : {}) });
-      } else if (fileId) {
-        parts.push({ type: "text", text: `[image: ${fileId}]` }); // file_id ref → no inline data
-      }
-      // No usable reference: omit the block. A "[image: ?]" marker would claim an attachment
-      // the request never carried, which is worse than dropping malformed input.
-    } else if (block.type === "input_video") {
-      const videoUrl = nonEmptyString(block.video_url);
-      if (videoUrl) parts.push({ type: "video", videoUrl });
-    } else if (block.type === "input_file") {
-      const b = block as { file_id?: string; filename?: string; file_data?: string };
-      const fileId = nonEmptyString(b.file_id);
-      const fileData = nonEmptyString(b.file_data);
-      const filename = nonEmptyString(b.filename);
-      if (fileId) {
-        parts.push({ type: "text", text: `[file: ${fileId}]` });
-      } else if (fileData) {
-        // Inline file_data is often large base64. Preserve only its presence and name, never bytes.
-        parts.push({ type: "text", text: filename ? `[file: ${filename}]` : "[file: inline data]" });
-      }
-      // A bare filename is not a file resource in the Responses schema, so omit it rather than
-      // fabricating a "[file: ...]" marker for an attachment that was never sent.
-    }
-  }
-  // Collapse to a plain string only for a single TEXT part; images must stay structured.
-  if (parts.length === 1 && parts[0].type === "text") return parts[0].text;
-  return parts;
-}
-
-type OutputBlock = { type: "output_text"; text: string } | { type: "text"; text: string } | { type: "refusal"; refusal: string };
-
-function outputTextOf(blocks: unknown): OcxTextContent[] {
-  if (typeof blocks === "string") return blocks.length > 0 ? [{ type: "text", text: blocks }] : [];
-  if (!Array.isArray(blocks)) return [];
-  const out: OcxTextContent[] = [];
-  for (const raw of blocks) {
-    // Same catch-all caveat as inputContentParts: validate before use.
-    if (!isObj(raw)) continue;
-    const b = raw as OutputBlock;
-    if (b.type === "output_text" || b.type === "text") {
-      if (typeof raw.text === "string") out.push({ type: "text", text: raw.text });
-    } else if (b.type === "refusal") {
-      if (typeof raw.refusal === "string") out.push({ type: "text", text: `[refusal: ${raw.refusal}]` });
-    }
-  }
-  return out;
-}
-
-function mapToolChoice(value: unknown): OcxRequestOptions["toolChoice"] {
-  if (value === undefined || value === null) return undefined;
-  if (value === "auto" || value === "none" || value === "required") return value;
-  if (isObj(value) && "type" in value) {
-    const t = (value as { type: string }).type;
-    if ((t === "function" || t === "custom") && "name" in value) {
-      return { name: (value as { name: string }).name };
-    }
-    // Hosted image tool types (with or without a name) map to the synthetic image_gen wire name.
-    if (t === "image_generation" || t === "image_gen") {
-      return { name: IMAGE_GEN_TOOL_NAME };
-    }
-    if (t === "allowed_tools" && Array.isArray(value.tools)) {
-      const names = value.tools
-        .map(allowedToolName)
-        .filter((name): name is string => Boolean(name));
-      return names.length > 0
-        ? { allowedTools: [...new Set(names)], mode: value.mode === "required" ? "required" : "auto" }
-        : "none";
-    }
-    return "auto";
-  }
-  return undefined;
-}
 
-function allowedToolName(tool: unknown): string | undefined {
-  if (!isObj(tool)) return undefined;
-  if (typeof tool.name === "string" && tool.name.length > 0) return tool.name;
-  if (tool.type === "web_search" || tool.type === "web_search_preview") return WEB_SEARCH_TOOL_NAME;
-  if (tool.type === "image_generation" || tool.type === "image_gen") return IMAGE_GEN_TOOL_NAME;
-  if (tool.type === "tool_search") return "tool_search";
-  return undefined;
-}
-
-function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
-  if (!tools) return undefined;
-  const out: OcxTool[] = [];
-  const normalizeParameters = (raw: unknown): Record<string, unknown> => {
-    if (isObj(raw) && raw.type === "object") return raw;
-    return { ...(isObj(raw) ? raw : {}), type: "object" };
-  };
-  const pushFn = (t: Record<string, unknown>, namespace?: string) => {
-    // Hosted image_generation already installed the synthetic root tool. A later
-    // ordinary root `image_gen` must not create a second un-namespaced identity.
-    if (
-      !namespace
-      && t.name === IMAGE_GEN_TOOL_NAME
-      && out.some(tool => tool.name === IMAGE_GEN_TOOL_NAME && !tool.namespace && tool.imageGeneration)
-    ) {
-      return;
-    }
-    const tool: OcxTool = {
-      name: t.name as string,
-      description: (t.description as string) ?? "",
-      parameters: normalizeParameters(t.parameters),
-    };
-    if (t.strict !== undefined) tool.strict = t.strict as boolean;
-    if (namespace) tool.namespace = namespace;
-    out.push(tool);
-  };
-  const pushCustom = (t: Record<string, unknown>, namespace?: string) => {
-    // Hosted image_generation already installed the synthetic root tool. A later
-    // root custom `image_gen` would collide on the same wire name with a different
-    // `freeform` flag and throw `ambiguous tool catalog`.
-    if (
-      !namespace
-      && t.name === IMAGE_GEN_TOOL_NAME
-      && out.some(tool => tool.name === IMAGE_GEN_TOOL_NAME && !tool.namespace && tool.imageGeneration)
-    ) {
-      return;
-    }
-    // Freeform custom tools are lowered to a single string `input` because chat models cannot
-    // emit Responses grammar payloads directly. Keep tool-specific input guidance scoped to the
-    // tool that owns it: leaking apply_patch syntax into `exec` or another freeform tool teaches
-    // routed models that the nested helper name is itself a callable top-level tool.
-    const inputDescription = t.name === "apply_patch"
-      ? "Raw tool input. For apply_patch, begin exactly with `*** Begin Patch` (no trailing `***`), then use its standard patch envelope."
-      : "Raw freeform input for this tool.";
-    const tool: OcxTool = {
-      name: t.name as string,
-      description: (t.description as string) ?? "",
-      parameters: { type: "object", properties: { input: { type: "string", description: inputDescription } }, required: ["input"] },
-      freeform: true,
-    };
-    if (namespace) tool.namespace = namespace;
-    out.push(tool);
-  };
-  for (const t of tools) {
-    if (!isObj(t)) continue;
-    if (t.type === "function" && isObj(t.function) && typeof t.function.name === "string" && t.function.name.length > 0) {
-      pushFn(t.function as Record<string, unknown>);
-      continue;
-    }
-    if (t.type === "function" && typeof t.name === "string") {
-      pushFn(t);
-    } else if (t.type === "namespace" && Array.isArray(t.tools)) {
-      // Codex 0.147 groups its ordinary client tools under the reserved `functions` namespace,
-      // including freeform custom tools such as code-mode `exec`. Those children are still
-      // top-level Responses tools, so flatten them without a namespace. Other namespace groups
-      // are MCP-style and keep their namespace for round-trip routing.
-      const builtinFunctions = t.name === "functions";
-      const ns = typeof t.name === "string" && !builtinFunctions ? t.name : undefined;
-      for (const inner of t.tools as unknown[]) {
-        if (isObj(inner) && inner.type === "function" && typeof inner.name === "string") pushFn(inner, ns);
-        else if (isObj(inner) && inner.type === "custom" && typeof inner.name === "string") pushCustom(inner, ns);
-      }
-    }
-    else if (t.type === "custom" && typeof t.name === "string") {
-      pushCustom(t);
-    }
-    else if (t.type === "tool_search") {
-      // Client-executed tool discovery — the gateway to deferred tools (subagents, extra MCP tools).
-      // Expose as a function so chat models can call it; the bridge relays it as a tool_search_call.
-      out.push({
-        name: "tool_search",
-        description: toolSearchDescription(t),
-        parameters: normalizeParameters(toolSearchParameters(t)),
-        toolSearch: true,
-      });
-    }
-    else if (t.type === "image_generation" || t.type === "image_gen") {
-      // Keep Codex's image_gen visible to routed chat models. The hosted OpenAI tool
-      // cannot execute on Grok; the model still has to see a callable image_gen so
-      // Codex's client-side /v1/images request can fire and be relayed to xAI.
-      // Identity is the un-namespaced synthetic root (`imageGeneration: true`), not
-      // the bare name: a namespaced ordinary `image_gen` must not suppress it.
-      const synthetic = buildImageTool();
-      // Every un-namespaced `image_gen` collides on one wire name, so removing only
-      // the first leaves a second root behind and the catalog stays ambiguous.
-      // Drop all root collisions, keep namespaced entries, then insert exactly one
-      // synthetic root — at the earliest colliding position so declaration order is
-      // preserved for models that read the catalog positionally.
-      let insertAt = -1;
-      for (let i = out.length - 1; i >= 0; i -= 1) {
-        const tool = out[i]!;
-        if (tool.name !== IMAGE_GEN_TOOL_NAME || tool.namespace) continue;
-        out.splice(i, 1);
-        insertAt = i;
-      }
-      if (insertAt >= 0) out.splice(insertAt, 0, synthetic);
-      else out.push(synthetic);
-    }
-    else if (typeof t.name === "string" && t.type !== "web_search" && t.type !== "image_generation") {
-      // Any OTHER named tool (e.g. a native/computer-use tool type opencodex doesn't explicitly
-      // model) is client-executed — pass it through as a function so the routed model can read and
-      // call it naturally; the bridge relays its call as a function_call. Previously such tools were
-      // silently dropped, so the model never saw them.
-      pushFn(t);
-    }
-    // Hosted web_search is still dropped here — the web-search sidecar re-injects it.
-  }
-  return out.length > 0 ? out : undefined;
-}
 
 function ensureAssistantPlaceholder(messages: OcxMessage[], modelId: string, now: number): OcxAssistantMessage {
   const last = messages[messages.length - 1];
@@ -285,45 +51,6 @@ function ensureAssistantPlaceholder(messages: OcxMessage[], modelId: string, now
   return placeholder;
 }
 
-/**
- * Tool-call output content. Preserves images (e.g. Codex `view_image` returns
- * `input_image` items): returns content parts when any image is present, else a plain joined string.
- * Never inlines an image_url as text (that would explode the token count).
- */
-function outputToToolResultContent(output: string | unknown[] | undefined): string | OcxContentPart[] {
-  if (typeof output === "string") return output;
-  if (!Array.isArray(output)) return "";
-  const parts: OcxContentPart[] = [];
-  let hasImage = false;
-  for (const raw of output) {
-    if (!isObj(raw)) continue;
-    if (raw.type === "output_text" || raw.type === "text" || raw.type === "input_text") {
-      if (typeof raw.text === "string") parts.push({ type: "text", text: raw.text });
-    } else if (raw.type === "refusal" && typeof raw.refusal === "string") {
-      parts.push({ type: "text", text: `[refusal: ${raw.refusal}]` });
-    } else if (raw.type === "input_image" && typeof raw.image_url === "string") {
-      parts.push({ type: "image", imageUrl: raw.image_url, ...(typeof raw.detail === "string" ? { detail: normalizeImageDetail(raw.detail) } : {}) });
-      hasImage = true;
-    } else if (raw.type === "encrypted_content") {
-      // codex-rs FunctionCallOutputContentItem::EncryptedContent — opaque to routed models.
-      parts.push({ type: "text", text: "[encrypted content omitted]" });
-    }
-  }
-  if (!hasImage) return parts.map(p => (p.type === "text" ? p.text : "")).join("");
-  return parts;
-}
-
-function toolOutputContainsEncryptedContent(output: string | unknown[] | undefined): boolean {
-  return Array.isArray(output) && output.some(raw => isObj(raw) && raw.type === "encrypted_content");
-}
-
-/**
- * codex-rs ImageDetail allows "original", but chat-completions providers only accept
- * auto|low|high on image_url.detail — degrade "original" to "high" (the codex default).
- */
-function normalizeImageDetail(detail: string): string {
-  return detail === "original" ? "high" : detail;
-}
 
 function findToolById(messages: OcxMessage[], callId: string): { name: string; namespace?: string } {
   for (let i = messages.length - 1; i >= 0; i--) {
@@ -366,34 +93,6 @@ function attachPendingReasoningToCallOwner(
 
 const REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max"]);
 
-/**
- * Namespace a custom tool was declared under, by its bare name.
- *
- * A `custom_tool_call` echoed back by the client carries only the bare name — the bridge
- * emits `{"type":"custom_tool_call","name":"exec"}` even when the tool was declared as
- * `mcp__functions__exec`. Without this lookup the namespace is lost on the return trip,
- * and the adapters replay history through `namespacedToolName(namespace, name)`, which
- * then produces a bare `exec` the provider may not have. Ordinary `function_call` items
- * do not need this: they carry `namespace` on the wire.
- */
-function customToolNamespaces(tools: unknown): Map<string, string> {
-  const out = new Map<string, string>();
-  if (!Array.isArray(tools)) return out;
-  for (const spec of tools) {
-    if (!isObj(spec) || spec.type !== "namespace" || !Array.isArray(spec.tools)) continue;
-    const namespace = typeof spec.name === "string" ? spec.name : undefined;
-    // Codex 0.147 groups ordinary client tools under the reserved `functions` namespace and
-    // buildTools deliberately flattens those without a namespace. Mirror that here, or the
-    // reconstruction would invent a namespace the request never advertised.
-    if (!namespace || namespace === "functions") continue;
-    for (const inner of spec.tools) {
-      if (!isObj(inner) || inner.type !== "custom" || typeof inner.name !== "string") continue;
-      // Ambiguous bare names are already rejected upstream, so first declaration wins.
-      if (!out.has(inner.name)) out.set(inner.name, namespace);
-    }
-  }
-  return out;
-}
 
 export function parseRequest(
   body: unknown,
@@ -859,25 +558,3 @@ export function parseRequest(
     ...(contextCompactionBoundary ? { _contextCompactionBoundary: true } : {}),
   };
 }
-
-/**
- * The Responses `text.format` object when it requests structured output (json_schema or
- * json_object), undefined otherwise. Acceptance is identical to the boolean detector this
- * replaces; unknown or malformed formats are ignored, never rejected, so the native
- * passthrough keeps forwarding whatever the caller sent via `_rawBody`.
- */
-function parseTextFormat(text: unknown): OcxRequestOptions["textFormat"] {
-  if (!isObj(text)) return undefined;
-  const format = (text as { format?: unknown }).format;
-  if (!isObj(format)) return undefined;
-  const f = format as { type?: unknown; name?: unknown; description?: unknown; schema?: unknown; strict?: unknown };
-  if (f.type === "json_object") return { type: "json_object" };
-  if (f.type !== "json_schema") return undefined;
-  return {
-    type: "json_schema",
-    ...(typeof f.name === "string" ? { name: f.name } : {}),
-    ...(typeof f.description === "string" ? { description: f.description } : {}),
-    ...(isObj(f.schema) ? { schema: f.schema as Record<string, unknown> } : {}),
-    ...(typeof f.strict === "boolean" ? { strict: f.strict } : {}),
-  };
-}

package/src/responses/state.ts

@@ -170,6 +170,77 @@ async function snapshotOnDiskMatches(path: string, payload: string, payloadBytes
   }
 }
 const spillCounters = { writes: 0, writeFailures: 0, readFailures: 0 };
+
+export type ResponseSpillWriteFailureCode =
+  | "EACLRETRYEXHAUSTED"
+  | "ETIMEDOUT"
+  | "EACCES"
+  | "ENOSPC"
+  | "EFBIG"
+  | "EIO"
+  | "ECAPACITY"
+  | "ELOOP"
+  | "EUNKNOWN";
+
+export type ResponseSpillWriteStatus = "initial" | "healthy" | "degraded";
+
+interface ResponseSpillWriteHealth {
+  consecutiveFailures: number;
+  lastFailureCode: ResponseSpillWriteFailureCode | null;
+  lastFailureAt: number | null;
+  lastSuccessAt: number | null;
+}
+
+const spillWriteHealth: ResponseSpillWriteHealth = {
+  consecutiveFailures: 0,
+  lastFailureCode: null,
+  lastFailureAt: null,
+  lastSuccessAt: null,
+};
+
+/**
+ * Collapse filesystem/runtime errors into a fixed privacy-safe diagnostic union.
+ * Messages and paths are deliberately ignored: this projection is returned by the
+ * authenticated memory endpoint, and a nested `cause` can contain a username or
+ * workspace path even when the public wrapper does not.
+ */
+function classifySpillWriteFailure(error: unknown): ResponseSpillWriteFailureCode {
+  let cursor = error;
+  for (let depth = 0; depth < 4 && cursor && typeof cursor === "object"; depth += 1) {
+    const record = cursor as { code?: unknown; cause?: unknown };
+    const code = typeof record.code === "string" ? record.code.toUpperCase() : "";
+    switch (code) {
+      case "EACLRETRYEXHAUSTED": return "EACLRETRYEXHAUSTED";
+      case "ETIMEDOUT": return "ETIMEDOUT";
+      case "EACCES":
+      case "EPERM": return "EACCES";
+      case "ENOSPC":
+      case "EDQUOT": return "ENOSPC";
+      case "EFBIG": return "EFBIG";
+      case "EIO": return "EIO";
+      case "ECAPACITY": return "ECAPACITY";
+      case "ELOOP": return "ELOOP";
+    }
+    cursor = record.cause;
+  }
+  return "EUNKNOWN";
+}
+
+function noteSpillWriteSuccess(): void {
+  spillCounters.writes += 1;
+  spillWriteHealth.consecutiveFailures = 0;
+  spillWriteHealth.lastSuccessAt = now();
+}
+
+function noteSpillWriteFailure(
+  error: unknown,
+  override?: ResponseSpillWriteFailureCode,
+): void {
+  spillCounters.writeFailures += 1;
+  spillWriteHealth.consecutiveFailures += 1;
+  spillWriteHealth.lastFailureCode = override ?? classifySpillWriteFailure(error);
+  spillWriteHealth.lastFailureAt = now();
+}
 /**
  * Admission-boundary observability (test-visible). directSpills: oversized
  * candidates routed straight to durable spill without a resident stay or
@@ -346,6 +417,7 @@ async function runPendingResponseSpill(job: PendingResponseSpill): Promise<void>
   job.running = true;
   const candidate = job.candidate;
   let ref: ResponseSpillRef | null = null;
+  let exhaustedAclRetry = false;
   try {
     const state = spillPayloadForResident(candidate);
     try {
@@ -357,11 +429,16 @@ async function runPendingResponseSpill(job: PendingResponseSpill): Promise<void>
       if (!isAclTimeout(error)) throw error;
       // The ACL helper permits exactly one caller-owned recovery budget. The resident generation
       // remains replayable during both attempts, so a transient timeout never becomes a tombstone.
-      ref = await writeResponseSpillDurablyAsync(job.id, state, {
-        aclBudgetMs: responseSpillAsyncAclAttemptBudgetMs(),
-        retryTimedOutOnce: true,
-        publicationControl: job.publicationControl,
-      });
+      try {
+        ref = await writeResponseSpillDurablyAsync(job.id, state, {
+          aclBudgetMs: responseSpillAsyncAclAttemptBudgetMs(),
+          retryTimedOutOnce: true,
+          publicationControl: job.publicationControl,
+        });
+      } catch (retryError) {
+        exhaustedAclRetry = isAclTimeout(retryError);
+        throw retryError;
+      }
     }
     if (ref.payloadBytes > responseSpillPayloadCap()) {
       deleteResponseSpill(ref);
@@ -376,14 +453,14 @@ async function runPendingResponseSpill(job: PendingResponseSpill): Promise<void>
     }
     if (swapResidentForSpill(job.id, candidate, ref)) {
       ref = null;
-      spillCounters.writes += 1;
+      noteSpillWriteSuccess();
       if (job.directAdmission) admissionCounters.directSpills += 1;
       deferSupersededSpill(job.supersededSpill);
     }
-  } catch {
+  } catch (error) {
     if (ref) deleteResponseSpill(ref);
     if (states.get(job.id) === candidate && !job.cancelled) {
-      spillCounters.writeFailures += 1;
+      noteSpillWriteFailure(error, exhaustedAclRetry ? "EACLRETRYEXHAUSTED" : undefined);
       replaceWithSpillFailure(job.id, candidate);
       deferSupersededSpill(job.supersededSpill);
     }
@@ -406,7 +483,7 @@ function queuePendingResponseSpill(
 ): void {
   const inheritedSpill = cancelPendingResponseSpill(id) ?? options.supersededSpill;
   if (pendingResponseSpillBytes + candidate.sizeBytes > MAX_PENDING_RESPONSE_SPILL_BYTES) {
-    spillCounters.writeFailures += 1;
+    noteSpillWriteFailure(null, "ECAPACITY");
     replaceWithSpillFailure(id, candidate);
     deferSupersededSpill(inheritedSpill);
     return;
@@ -424,7 +501,7 @@ function queuePendingResponseSpill(
   if (accountedResponseSpillBytes() + footprint + inheritedBytes > spillByteCap()) {
     enforceSpilledResponseBudget();
     if (accountedResponseSpillBytes() + footprint + inheritedBytes > spillByteCap()) {
-      spillCounters.writeFailures += 1;
+      noteSpillWriteFailure(null, "ECAPACITY");
       replaceWithSpillFailure(id, candidate);
       deferSupersededSpill(inheritedSpill);
       return;
@@ -560,7 +637,7 @@ function installShutdownFallbackSpill(
       enforceSpilledResponseBudget();
       if (accountedResponseSpillBytes() + supersededBytes > spillByteCap()) {
         if (states.get(job.id) === candidate) {
-          spillCounters.writeFailures += 1;
+          noteSpillWriteFailure(null, "ECAPACITY");
           replaceWithSpillFailure(job.id, candidate);
           deferSupersededSpill(job.supersededSpill);
         }
@@ -581,14 +658,14 @@ function installShutdownFallbackSpill(
     }
     if (swapResidentForSpill(job.id, candidate, ref)) {
       ref = null;
-      spillCounters.writes += 1;
+      noteSpillWriteSuccess();
       if (job.directAdmission) admissionCounters.directSpills += 1;
       deferSupersededSpill(job.supersededSpill);
     }
   } catch (error) {
     if (ref) deleteResponseSpill(ref);
     if (states.get(job.id) === candidate) {
-      spillCounters.writeFailures += 1;
+      noteSpillWriteFailure(error);
       replaceWithSpillFailure(job.id, candidate);
       deferSupersededSpill(job.supersededSpill);
     }
@@ -601,9 +678,10 @@ function installShutdownFallbackSpill(
 function terminalizeShutdownFallbackCandidate(
   job: PendingResponseSpill,
   candidate: ResidentResponseState,
+  failureCode: ResponseSpillWriteFailureCode = "ETIMEDOUT",
 ): void {
   if (states.get(job.id) !== candidate) return;
-  spillCounters.writeFailures += 1;
+  noteSpillWriteFailure(null, failureCode);
   replaceWithSpillFailure(job.id, candidate);
   deferSupersededSpill(job.supersededSpill);
 }
@@ -652,11 +730,11 @@ function stopAtShutdownTerminalizationPassLimit(
   failures.push(Object.assign(new Error("Response spill shutdown terminalization pass limit exceeded"), { code: "ELOOP" }));
   supersedeShutdownFallbackBatch(pending, failures);
   for (const { job, candidate } of pending) {
-    terminalizeShutdownFallbackCandidate(job, candidate);
+    terminalizeShutdownFallbackCandidate(job, candidate, "ELOOP");
   }
   for (const [id, state] of [...states]) {
     if (state.kind !== "resident") continue;
-    spillCounters.writeFailures += 1;
+    noteSpillWriteFailure(null, "ELOOP");
     replaceWithSpillFailure(id, state);
   }
   recomputeOldestResident();
@@ -986,7 +1064,7 @@ function replaceSpillEntryAtomically(
       deleteResponseSpill(ref);
       return;
     }
-    spillCounters.writes += 1;
+    noteSpillWriteSuccess();
     noteStubSwapForTest();
     // The old generation is NOT unlinked here (review C1-1): the new stub is
     // only durable once the debounced snapshot flushes — a crash before that
@@ -996,8 +1074,8 @@ function replaceSpillEntryAtomically(
     while (pendingSpillUnlinks.length > PENDING_SPILL_UNLINKS_MAX) {
       deleteResponseSpill(pendingSpillUnlinks.shift()!);
     }
-  } catch {
-    spillCounters.writeFailures += 1;
+  } catch (error) {
+    noteSpillWriteFailure(error);
     // deferSpillUnlink: the durable snapshot may still reference the old
     // generation; deleting it now would strand the old stub after a crash.
     replaceWithSpillFailure(id, expected, { deferSpillUnlink: true });
@@ -1087,7 +1165,7 @@ function admitOversizedCandidate(
       deleteResponseSpill(ref);
       return;
     }
-    spillCounters.writes += 1;
+    noteSpillWriteSuccess();
     admissionCounters.directSpills += 1;
     noteStubSwapForTest();
     if (expected?.kind === "spill") {
@@ -1099,8 +1177,8 @@ function admitOversizedCandidate(
         deleteResponseSpill(pendingSpillUnlinks.shift()!);
       }
     }
-  } catch {
-    spillCounters.writeFailures += 1;
+  } catch (error) {
+    noteSpillWriteFailure(error);
     replaceWithSpillFailure(id, expected, { deferSpillUnlink: true });
   }
 }
@@ -1812,9 +1890,9 @@ function pruneResponses(at = now()): void {
         ...(entry.providerOutputStart !== undefined ? { providerOutputStart: entry.providerOutputStart } : {}),
         ...(entry.providers ? { providers: entry.providers } : {}),
       });
-      if (swapResidentForSpill(oldestId, entry, ref)) spillCounters.writes += 1;
-    } catch {
-      spillCounters.writeFailures += 1;
+      if (swapResidentForSpill(oldestId, entry, ref)) noteSpillWriteSuccess();
+    } catch (error) {
+      noteSpillWriteFailure(error);
       replaceWithSpillFailure(oldestId, entry);
     }
   }
@@ -1929,9 +2007,9 @@ export function evictOldestResponseContinuationForBudget(): number {
       ...(entry.providerOutputStart !== undefined ? { providerOutputStart: entry.providerOutputStart } : {}),
       ...(entry.providers ? { providers: entry.providers } : {}),
     });
-    if (swapResidentForSpill(id, entry, ref)) spillCounters.writes += 1;
-  } catch {
-    spillCounters.writeFailures += 1;
+    if (swapResidentForSpill(id, entry, ref)) noteSpillWriteSuccess();
+  } catch (error) {
+    noteSpillWriteFailure(error);
     replaceWithSpillFailure(id, entry);
   }
   schedulePersist();
@@ -2107,6 +2185,11 @@ export interface ResponseStateMetrics {
   oldestAgeMs: number;
   spillWrites: number;
   spillWriteFailures: number;
+  spillWriteStatus: ResponseSpillWriteStatus;
+  spillWriteConsecutiveFailures: number;
+  spillLastWriteFailureCode: ResponseSpillWriteFailureCode | null;
+  spillLastWriteFailureAt: number | null;
+  spillLastWriteSuccessAt: number | null;
   spillReadFailures: number;
   replayScopeMismatchDrops: number;
 }
@@ -2150,6 +2233,15 @@ export function responseStateMetrics(): ResponseStateMetrics {
     oldestAgeMs: states.size > 0 ? at - oldestCreatedAt : 0,
     spillWrites: spillCounters.writes,
     spillWriteFailures: spillCounters.writeFailures,
+    spillWriteStatus: spillWriteHealth.consecutiveFailures > 0
+      ? "degraded"
+      : spillWriteHealth.lastSuccessAt !== null
+        ? "healthy"
+        : "initial",
+    spillWriteConsecutiveFailures: spillWriteHealth.consecutiveFailures,
+    spillLastWriteFailureCode: spillWriteHealth.lastFailureCode,
+    spillLastWriteFailureAt: spillWriteHealth.lastFailureAt,
+    spillLastWriteSuccessAt: spillWriteHealth.lastSuccessAt,
     spillReadFailures: spillCounters.readFailures,
     replayScopeMismatchDrops,
   };
@@ -2268,6 +2360,10 @@ export function clearResponseStateMemoryForTests(): void {
   spillCounters.writes = 0;
   spillCounters.writeFailures = 0;
   spillCounters.readFailures = 0;
+  spillWriteHealth.consecutiveFailures = 0;
+  spillWriteHealth.lastFailureCode = null;
+  spillWriteHealth.lastFailureAt = null;
+  spillWriteHealth.lastSuccessAt = null;
   replayScopeMismatchDrops = 0;
   replayOverlapSkips = 0;
   persistAttemptHookForTests = null;