@poncho-ai/harness 0.59.14 → 0.59.15

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.59.14 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.59.15 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -9,8 +9,8 @@
 CLI Target: es2022
 ESM Build start
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM dist/index.js            564.58 KB
-ESM ⚡️ Build success in 217ms
+ESM dist/index.js            570.16 KB
+ESM ⚡️ Build success in 242ms
 DTS Build start
-DTS ⚡️ Build success in 8055ms
-DTS dist/index.d.ts 102.50 KB
+DTS ⚡️ Build success in 6639ms
+DTS dist/index.d.ts 103.12 KB

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @poncho-ai/harness
 
+## 0.59.15
+
+### Patch Changes
+
+- [`c5f6d7f`](https://github.com/cesr/poncho-ai/commit/c5f6d7f999bc3d4699295c376b23fc3894302e3a) Thanks [@cesr](https://github.com/cesr)! - Guard a single oversized FRESH tool result from overflowing the context
+  window. `truncateHistoricalToolResults` only shrinks results from prior runs
+  (it deliberately preserves the latest run's results so the model can read what
+  it just fetched), so a tool that returns a payload larger than the window in
+  one shot — e.g. an MCP email-fetch returning 1.6M–3.3M tokens of full bodies —
+  was never truncated and failed the very next step with "prompt is too long".
+
+  The result is now guarded at the moment it's produced, before the
+  `tool:completed` event is emitted (so the WS stream never carries the megabytes
+  either) and before it reaches the model:
+  - **Spill mode** (opt-in via the `__toolResultSpill` run parameter
+    `{ enabled, dir?, thresholdChars?, keepLast? }`): the full payload is written
+    to a VFS file (JSONL for arrays, pretty JSON otherwise) and the model gets a
+    small handle + preview pointing at it, to read back in bounded chunks with
+    bash/jq. Durable and lossless; the spill dir is pruned to `keepLast` files.
+  - **Inline-truncate mode** (default when spill isn't enabled, and the fallback
+    if a spill write fails): the payload is replaced with a preview + "re-run
+    narrower" notice.
+
+  Both modes apply to every tool uniformly (MCP, bash, run_code, subagent
+  results) and only trigger above `thresholdChars` (default 500k ≈ 125k tokens),
+  so normal-sized results are untouched. Inline media (images/PDFs) is separated
+  out first and unaffected.
+
 ## 0.59.14
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1494,6 +1494,17 @@ declare class AgentHarness {
     get frontmatter(): AgentFrontmatter | undefined;
     getToolResultArchive(conversationId: string): Record<string, ArchivedToolResult>;
     private seedToolResultArchive;
+    /**
+     * Guard a single FRESH tool result against overflowing the context window.
+     * `serialized` is the JSON-serialized (media-stripped) output. Returns a
+     * replacement value to put in front of the model (a handle or a truncated
+     * preview) when the result is oversized, or `null` to leave it untouched.
+     * Spilling writes the full payload to a VFS file; on any write failure it
+     * falls back to inline truncation, so this never throws into the run loop.
+     */
+    private guardOversizedToolResult;
+    /** Best-effort: keep only the newest `keepLast` files in the spill dir. */
+    private pruneSpillDir;
     private truncateHistoricalToolResults;
     private shouldPreserveSkillToolResult;
     getTodos(conversationId: string): Promise<TodoItem[]>;

package/dist/index.js

@@ -5649,6 +5649,61 @@ var BashEnvironmentManager = class {
   }
 };
 
+// src/tool-result-guard.ts
+var SPILL_POLICY_PARAM = "__toolResultSpill";
+var DEFAULT_OVERSIZED_TOOL_RESULT_CHARS = 5e5;
+var SPILLED_PREVIEW_CHARS = 6e3;
+var INLINE_TRUNCATE_PREVIEW_CHARS = 6e4;
+var DEFAULT_SPILL_DIR = "/tmp/tool-results";
+var DEFAULT_SPILL_KEEP_LAST = 20;
+var readSpillPolicy = (parameters) => {
+  const raw = parameters?.[SPILL_POLICY_PARAM];
+  const obj = typeof raw === "object" && raw !== null ? raw : {};
+  const thresholdChars = typeof obj.thresholdChars === "number" && obj.thresholdChars > 0 ? obj.thresholdChars : DEFAULT_OVERSIZED_TOOL_RESULT_CHARS;
+  const dir = typeof obj.dir === "string" && obj.dir.startsWith("/") ? obj.dir : DEFAULT_SPILL_DIR;
+  const keepLast = typeof obj.keepLast === "number" && obj.keepLast > 0 ? Math.floor(obj.keepLast) : DEFAULT_SPILL_KEEP_LAST;
+  return { enabled: obj.enabled === true, dir, thresholdChars, keepLast };
+};
+var isOversizedToolResult = (serialized, policy) => serialized.length > policy.thresholdChars;
+var formatSpillPayload = (output) => {
+  if (Array.isArray(output)) {
+    return {
+      content: output.map((row) => JSON.stringify(row)).join("\n"),
+      format: "jsonl",
+      records: output.length
+    };
+  }
+  return { content: JSON.stringify(output ?? null, null, 2), format: "json" };
+};
+var buildSpillHandle = (opts) => {
+  const { toolName, path, format, serialized, records } = opts;
+  const approxTokens = Math.ceil(serialized.length / 4);
+  const isArray = format === "jsonl";
+  return {
+    __toolResultSpilled: true,
+    tool: toolName,
+    path,
+    format,
+    ...records !== void 0 ? { records } : {},
+    totalChars: serialized.length,
+    approxTokens,
+    preview: serialized.slice(0, SPILLED_PREVIEW_CHARS),
+    note: `This result was too large to return inline (~${approxTokens.toLocaleString()} tokens) and was saved to ${path}. Inspect it with bash \u2014 e.g. \`wc -l ${path}\`, \`head -c 4000 ${path}\`, ` + (isArray ? `\`sed -n '1,5p' ${path}\`, \`grep -i <term> ${path}\`, or \`jq\` per line` : `\`grep -i <term> ${path}\``) + `. Do NOT cat or read_file the whole file (it re-overflows). Or re-run the tool with a narrower request (fewer items / a filter / metadata only).`
+  };
+};
+var buildInlineTruncation = (toolName, serialized) => {
+  const approxTokens = Math.ceil(serialized.length / 4);
+  const omittedChars = Math.max(0, serialized.length - INLINE_TRUNCATE_PREVIEW_CHARS);
+  return {
+    __toolResultTruncated: true,
+    tool: toolName,
+    approxTokens,
+    omittedChars,
+    preview: serialized.slice(0, INLINE_TRUNCATE_PREVIEW_CHARS),
+    note: `This result was too large (~${approxTokens.toLocaleString()} tokens) and was truncated to fit the context window \u2014 only the first ${INLINE_TRUNCATE_PREVIEW_CHARS.toLocaleString()} characters are shown. Re-run with a narrower request (fewer items / a filter / metadata only). Do NOT retry the same call unchanged \u2014 it will overflow again.`
+  };
+};
+
 // src/vfs/bash-tool.ts
 import { defineTool as defineTool2 } from "@poncho-ai/sdk";
 var createBashTool = (bashManager) => defineTool2({
@@ -9825,6 +9880,59 @@ var AgentHarness = class _AgentHarness {
     this.archivedToolResultsByConversation.set(conversationId, merged);
     return merged;
   }
+  /**
+   * Guard a single FRESH tool result against overflowing the context window.
+   * `serialized` is the JSON-serialized (media-stripped) output. Returns a
+   * replacement value to put in front of the model (a handle or a truncated
+   * preview) when the result is oversized, or `null` to leave it untouched.
+   * Spilling writes the full payload to a VFS file; on any write failure it
+   * falls back to inline truncation, so this never throws into the run loop.
+   */
+  async guardOversizedToolResult(opts) {
+    const { tenantId, toolName, toolCallId, output, serialized, policy } = opts;
+    if (!isOversizedToolResult(serialized, policy)) return null;
+    if (policy.enabled && this.bashManager) {
+      try {
+        const vfs = this.createVfsAccess(tenantId);
+        const { content, format, records } = formatSpillPayload(output);
+        const safeTool = toolName.replace(/[^A-Za-z0-9_-]/g, "_");
+        const path = `${policy.dir}/${safeTool}_${toolCallId}.${format}`;
+        await vfs.mkdir(policy.dir, { recursive: true });
+        await vfs.writeText(path, content);
+        await this.pruneSpillDir(vfs, policy.dir, policy.keepLast);
+        return buildSpillHandle({ toolName, path, format, serialized, records });
+      } catch {
+      }
+    }
+    return buildInlineTruncation(toolName, serialized);
+  }
+  /** Best-effort: keep only the newest `keepLast` files in the spill dir. */
+  async pruneSpillDir(vfs, dir, keepLast) {
+    try {
+      const entries = await vfs.readdir(dir);
+      const names = (Array.isArray(entries) ? entries : []).map((e) => typeof e === "string" ? e : e.name).filter((n) => typeof n === "string");
+      if (names.length <= keepLast) return;
+      const stated = await Promise.all(
+        names.map(async (name) => {
+          try {
+            const s = await vfs.stat(`${dir}/${name}`);
+            return { name, mtime: s.updatedAt ?? 0 };
+          } catch {
+            return { name, mtime: 0 };
+          }
+        })
+      );
+      stated.sort((a, b) => a.mtime - b.mtime);
+      const doomed = stated.slice(0, stated.length - keepLast);
+      for (const d of doomed) {
+        try {
+          await vfs.rm(`${dir}/${d.name}`);
+        } catch {
+        }
+      }
+    } catch {
+    }
+  }
   truncateHistoricalToolResults(messages, conversationId) {
     let latestRunId;
     let latestToolMessageIndex = -1;
@@ -10676,6 +10784,7 @@ var AgentHarness = class _AgentHarness {
     const messages = [...input.messages ?? []];
     const conversationId = input.conversationId ?? "__default__";
     this.seedToolResultArchive(conversationId, input.parameters);
+    const spillPolicy = readSpillPolicy(input.parameters);
     const truncationSummary = this.truncateHistoricalToolResults(messages, conversationId);
     if (truncationSummary.changed) {
       costLog.debug(
@@ -11817,29 +11926,39 @@ ${textContent}` };
                 span.setStatus({ code: SpanStatusCode.OK });
                 span.end();
               }
-              const serialized = JSON.stringify(result2.output ?? null);
-              const outputTokenEstimate = Math.ceil(serialized.length / 4);
+              const { mediaItems, strippedOutput } = extractMediaFromToolOutput(result2.output);
+              const strippedSerialized = JSON.stringify(strippedOutput ?? null);
+              const guarded = await this.guardOversizedToolResult({
+                tenantId: input.tenantId ?? "__default__",
+                toolName: result2.tool,
+                toolCallId: result2.callId,
+                output: strippedOutput,
+                serialized: strippedSerialized,
+                policy: spillPolicy
+              });
+              const effectiveOutput = guarded ?? strippedOutput ?? null;
+              const effectiveSerialized = guarded ? JSON.stringify(guarded) : strippedSerialized;
+              const outputTokenEstimate = Math.ceil(effectiveSerialized.length / 4);
               toolOutputEstimateSinceModel += outputTokenEstimate;
               yield pushEvent({
                 type: "tool:completed",
                 tool: result2.tool,
                 toolCallId: result2.callId,
                 input: callInputMap.get(result2.callId),
-                output: result2.output,
+                output: effectiveOutput,
                 duration: now() - batchStart,
                 outputTokenEstimate
               });
-              const { mediaItems, strippedOutput } = extractMediaFromToolOutput(result2.output);
               toolResultsForModel.push({
                 type: "tool_result",
                 tool_use_id: result2.callId,
                 tool_name: result2.tool,
-                content: JSON.stringify(strippedOutput ?? null)
+                content: effectiveSerialized
               });
               {
                 const archive = this.archivedToolResultsByConversation.get(conversationId);
                 if (archive && !NON_ARCHIVABLE_TOOL_NAMES.has(result2.tool)) {
-                  const payload = JSON.stringify(result2.output ?? null);
+                  const payload = effectiveSerialized;
                   archive[result2.callId] = {
                     toolResultId: result2.callId,
                     conversationId,
@@ -11860,7 +11979,7 @@ ${textContent}` };
                   output: {
                     type: "content",
                     value: [
-                      { type: "text", text: JSON.stringify(strippedOutput ?? null) },
+                      { type: "text", text: effectiveSerialized },
                       ...mediaItems
                     ]
                   }
@@ -11870,7 +11989,7 @@ ${textContent}` };
                   type: "tool-result",
                   toolCallId: result2.callId,
                   toolName: result2.tool,
-                  output: { type: "json", value: result2.output ?? null }
+                  output: { type: "json", value: effectiveOutput }
                 });
               }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.59.14",
+  "version": "0.59.15",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/harness.ts

@@ -30,6 +30,14 @@ import {
   createReminderStoreFromEngine,
 } from "./storage/store-adapters.js";
 import { BashEnvironmentManager } from "./vfs/bash-manager.js";
+import {
+  type ToolResultSpillPolicy,
+  readSpillPolicy,
+  isOversizedToolResult,
+  formatSpillPayload,
+  buildSpillHandle,
+  buildInlineTruncation,
+} from "./tool-result-guard.js";
 import type { VirtualMount } from "./vfs/poncho-fs-adapter.js";
 export type { VirtualMount } from "./vfs/poncho-fs-adapter.js";
 import { createBashTool } from "./vfs/bash-tool.js";
@@ -1181,6 +1189,77 @@ export class AgentHarness {
     return merged;
   }
 
+  /**
+   * Guard a single FRESH tool result against overflowing the context window.
+   * `serialized` is the JSON-serialized (media-stripped) output. Returns a
+   * replacement value to put in front of the model (a handle or a truncated
+   * preview) when the result is oversized, or `null` to leave it untouched.
+   * Spilling writes the full payload to a VFS file; on any write failure it
+   * falls back to inline truncation, so this never throws into the run loop.
+   */
+  private async guardOversizedToolResult(opts: {
+    tenantId: string;
+    toolName: string;
+    toolCallId: string;
+    output: unknown;
+    serialized: string;
+    policy: ToolResultSpillPolicy;
+  }): Promise<Record<string, unknown> | null> {
+    const { tenantId, toolName, toolCallId, output, serialized, policy } = opts;
+    if (!isOversizedToolResult(serialized, policy)) return null;
+
+    if (policy.enabled && this.bashManager) {
+      try {
+        const vfs = this.createVfsAccess(tenantId);
+        const { content, format, records } = formatSpillPayload(output);
+        // toolCallId is unique per call and stable across a checkpoint→resume,
+        // so the path is idempotent (a resumed run rewrites the same file).
+        const safeTool = toolName.replace(/[^A-Za-z0-9_-]/g, "_");
+        const path = `${policy.dir}/${safeTool}_${toolCallId}.${format}`;
+        await vfs.mkdir(policy.dir, { recursive: true });
+        await vfs.writeText(path, content);
+        await this.pruneSpillDir(vfs, policy.dir, policy.keepLast);
+        return buildSpillHandle({ toolName, path, format, serialized, records });
+      } catch {
+        // Fall through to inline truncation below.
+      }
+    }
+
+    return buildInlineTruncation(toolName, serialized);
+  }
+
+  /** Best-effort: keep only the newest `keepLast` files in the spill dir. */
+  private async pruneSpillDir(
+    vfs: NonNullable<ToolContext["vfs"]>,
+    dir: string,
+    keepLast: number,
+  ): Promise<void> {
+    try {
+      const entries = await vfs.readdir(dir);
+      const names = (Array.isArray(entries) ? entries : [])
+        .map((e) => (typeof e === "string" ? e : (e as { name?: string }).name))
+        .filter((n): n is string => typeof n === "string");
+      if (names.length <= keepLast) return;
+      const stated = await Promise.all(
+        names.map(async (name) => {
+          try {
+            const s = await vfs.stat(`${dir}/${name}`);
+            return { name, mtime: s.updatedAt ?? 0 };
+          } catch {
+            return { name, mtime: 0 };
+          }
+        }),
+      );
+      stated.sort((a, b) => a.mtime - b.mtime); // oldest first
+      const doomed = stated.slice(0, stated.length - keepLast);
+      for (const d of doomed) {
+        try { await vfs.rm(`${dir}/${d.name}`); } catch { /* best-effort */ }
+      }
+    } catch {
+      // Dir unreadable — nothing to prune.
+    }
+  }
+
   private truncateHistoricalToolResults(
     messages: Message[],
     conversationId: string,
@@ -2212,6 +2291,7 @@ export class AgentHarness {
     const messages: Message[] = [...(input.messages ?? [])];
     const conversationId = input.conversationId ?? "__default__";
     this.seedToolResultArchive(conversationId, input.parameters);
+    const spillPolicy = readSpillPolicy(input.parameters);
     const truncationSummary = this.truncateHistoricalToolResults(messages, conversationId);
     if (truncationSummary.changed) {
       costLog.debug(
@@ -3692,30 +3772,49 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
             span.setStatus({ code: SpanStatusCode.OK });
             span.end();
           }
-          const serialized = JSON.stringify(result.output ?? null);
-          const outputTokenEstimate = Math.ceil(serialized.length / 4);
+          // Separate inline media (images/PDFs) from the textual output, then
+          // guard the textual part against overflowing the window. A single
+          // oversized fresh result is replaced with a handle (spill) or a
+          // preview (inline) BEFORE we emit the event or feed the model — so
+          // neither the WS stream nor the next step ever carries the full
+          // multi-MB payload.
+          const { mediaItems, strippedOutput } = extractMediaFromToolOutput(result.output);
+          const strippedSerialized = JSON.stringify(strippedOutput ?? null);
+          const guarded = await this.guardOversizedToolResult({
+            tenantId: input.tenantId ?? "__default__",
+            toolName: result.tool,
+            toolCallId: result.callId,
+            output: strippedOutput,
+            serialized: strippedSerialized,
+            policy: spillPolicy,
+          });
+          const effectiveOutput: unknown = guarded ?? strippedOutput ?? null;
+          const effectiveSerialized = guarded ? JSON.stringify(guarded) : strippedSerialized;
+          const outputTokenEstimate = Math.ceil(effectiveSerialized.length / 4);
           toolOutputEstimateSinceModel += outputTokenEstimate;
           yield pushEvent({
             type: "tool:completed",
             tool: result.tool,
             toolCallId: result.callId,
             input: callInputMap.get(result.callId),
-            output: result.output,
+            output: effectiveOutput,
             duration: now() - batchStart,
             outputTokenEstimate,
           });
 
-          const { mediaItems, strippedOutput } = extractMediaFromToolOutput(result.output);
           toolResultsForModel.push({
             type: "tool_result",
             tool_use_id: result.callId,
             tool_name: result.tool,
-            content: JSON.stringify(strippedOutput ?? null),
+            content: effectiveSerialized,
           });
           {
             const archive = this.archivedToolResultsByConversation.get(conversationId);
             if (archive && !NON_ARCHIVABLE_TOOL_NAMES.has(result.tool)) {
-              const payload = JSON.stringify(result.output ?? null);
+              // Archive the model-visible payload (handle/preview when guarded).
+              // When spilled, the VFS file is the durable full copy; keeping the
+              // in-memory archive small avoids re-introducing the same bloat.
+              const payload = effectiveSerialized;
               archive[result.callId] = {
                 toolResultId: result.callId,
                 conversationId,
@@ -3737,7 +3836,7 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
               output: {
                 type: "content",
                 value: [
-                  { type: "text", text: JSON.stringify(strippedOutput ?? null) },
+                  { type: "text", text: effectiveSerialized },
                   ...mediaItems,
                 ],
               },
@@ -3747,7 +3846,7 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
               type: "tool-result",
               toolCallId: result.callId,
               toolName: result.tool,
-              output: { type: "json", value: result.output ?? null },
+              output: { type: "json", value: effectiveOutput },
             });
           }
         }

package/src/tool-result-guard.ts

@@ -0,0 +1,133 @@
+// Oversized FRESH tool-result guard — pure logic.
+//
+// `truncateHistoricalToolResults` (in harness.ts) only shrinks results from
+// PRIOR runs — it deliberately preserves the latest run's results so the model
+// can read what it just fetched. So a single fresh result that is itself larger
+// than the context window is never truncated, and the next step fails with
+// "prompt is too long" (seen with MCP email-fetch tools returning 1.6M–3.3M
+// token payloads). This module decides what to put in front of the model when
+// that happens; the I/O (the VFS write + prune) lives on the Harness class,
+// which has the per-tenant filesystem. Splitting the pure decision out keeps it
+// unit-testable without a Harness instance.
+
+/** Run parameter key carrying the spill policy (a freeform-params bag entry,
+ *  same mechanism as `__toolResultArchive`). */
+export const SPILL_POLICY_PARAM = "__toolResultSpill";
+
+/** Results whose serialized form exceeds this many chars are guarded. ~125k
+ *  tokens — well under any current window, well above any normal result, so
+ *  normal-sized results are never touched. */
+export const DEFAULT_OVERSIZED_TOOL_RESULT_CHARS = 500_000;
+/** Preview kept inline when SPILLING — small, because the full payload is in
+ *  the file. */
+export const SPILLED_PREVIEW_CHARS = 6_000;
+/** Preview kept inline when TRUNCATING — larger, because there's no file to
+ *  fall back to. */
+export const INLINE_TRUNCATE_PREVIEW_CHARS = 60_000;
+export const DEFAULT_SPILL_DIR = "/tmp/tool-results";
+export const DEFAULT_SPILL_KEEP_LAST = 20;
+
+export interface ToolResultSpillPolicy {
+  enabled: boolean;
+  dir: string;
+  thresholdChars: number;
+  keepLast: number;
+}
+
+/** Parse the spill policy out of the run parameters, applying defaults. A
+ *  missing/malformed bag yields a disabled policy with safe defaults. */
+export const readSpillPolicy = (
+  parameters: Record<string, unknown> | undefined,
+): ToolResultSpillPolicy => {
+  const raw = parameters?.[SPILL_POLICY_PARAM];
+  const obj = (typeof raw === "object" && raw !== null ? raw : {}) as Record<string, unknown>;
+  const thresholdChars =
+    typeof obj.thresholdChars === "number" && obj.thresholdChars > 0
+      ? obj.thresholdChars
+      : DEFAULT_OVERSIZED_TOOL_RESULT_CHARS;
+  const dir =
+    typeof obj.dir === "string" && obj.dir.startsWith("/") ? obj.dir : DEFAULT_SPILL_DIR;
+  const keepLast =
+    typeof obj.keepLast === "number" && obj.keepLast > 0
+      ? Math.floor(obj.keepLast)
+      : DEFAULT_SPILL_KEEP_LAST;
+  return { enabled: obj.enabled === true, dir, thresholdChars, keepLast };
+};
+
+/** True when this serialized result is large enough to need guarding. */
+export const isOversizedToolResult = (
+  serialized: string,
+  policy: ToolResultSpillPolicy,
+): boolean => serialized.length > policy.thresholdChars;
+
+/** Serialize an oversized payload for the spill file. Arrays become JSONL (one
+ *  record per line — bash/jq/sed friendly, line ranges map to records); other
+ *  shapes become pretty JSON. */
+export const formatSpillPayload = (
+  output: unknown,
+): { content: string; format: "jsonl" | "json"; records?: number } => {
+  if (Array.isArray(output)) {
+    return {
+      content: output.map((row) => JSON.stringify(row)).join("\n"),
+      format: "jsonl",
+      records: output.length,
+    };
+  }
+  return { content: JSON.stringify(output ?? null, null, 2), format: "json" };
+};
+
+/** The handle object placed in front of the model when a result is spilled to
+ *  a file: a small preview plus the path and bash-readback instructions. */
+export const buildSpillHandle = (opts: {
+  toolName: string;
+  path: string;
+  format: "jsonl" | "json";
+  serialized: string;
+  records?: number;
+}): Record<string, unknown> => {
+  const { toolName, path, format, serialized, records } = opts;
+  const approxTokens = Math.ceil(serialized.length / 4);
+  const isArray = format === "jsonl";
+  return {
+    __toolResultSpilled: true,
+    tool: toolName,
+    path,
+    format,
+    ...(records !== undefined ? { records } : {}),
+    totalChars: serialized.length,
+    approxTokens,
+    preview: serialized.slice(0, SPILLED_PREVIEW_CHARS),
+    note:
+      `This result was too large to return inline (~${approxTokens.toLocaleString()} ` +
+      `tokens) and was saved to ${path}. Inspect it with bash — e.g. ` +
+      `\`wc -l ${path}\`, \`head -c 4000 ${path}\`, ` +
+      (isArray
+        ? `\`sed -n '1,5p' ${path}\`, \`grep -i <term> ${path}\`, or \`jq\` per line`
+        : `\`grep -i <term> ${path}\``) +
+      `. Do NOT cat or read_file the whole file (it re-overflows). Or re-run the ` +
+      `tool with a narrower request (fewer items / a filter / metadata only).`,
+  };
+};
+
+/** The replacement placed in front of the model when a result is too large and
+ *  spill is unavailable: a preview plus a "re-run narrower" instruction. */
+export const buildInlineTruncation = (
+  toolName: string,
+  serialized: string,
+): Record<string, unknown> => {
+  const approxTokens = Math.ceil(serialized.length / 4);
+  const omittedChars = Math.max(0, serialized.length - INLINE_TRUNCATE_PREVIEW_CHARS);
+  return {
+    __toolResultTruncated: true,
+    tool: toolName,
+    approxTokens,
+    omittedChars,
+    preview: serialized.slice(0, INLINE_TRUNCATE_PREVIEW_CHARS),
+    note:
+      `This result was too large (~${approxTokens.toLocaleString()} tokens) and was ` +
+      `truncated to fit the context window — only the first ` +
+      `${INLINE_TRUNCATE_PREVIEW_CHARS.toLocaleString()} characters are shown. Re-run ` +
+      `with a narrower request (fewer items / a filter / metadata only). Do NOT retry ` +
+      `the same call unchanged — it will overflow again.`,
+  };
+};

package/test/tool-result-guard.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_OVERSIZED_TOOL_RESULT_CHARS,
+  DEFAULT_SPILL_DIR,
+  DEFAULT_SPILL_KEEP_LAST,
+  INLINE_TRUNCATE_PREVIEW_CHARS,
+  SPILLED_PREVIEW_CHARS,
+  buildInlineTruncation,
+  buildSpillHandle,
+  formatSpillPayload,
+  isOversizedToolResult,
+  readSpillPolicy,
+} from "../src/tool-result-guard.js";
+
+describe("readSpillPolicy", () => {
+  it("defaults to disabled with safe defaults when the param is absent", () => {
+    expect(readSpillPolicy(undefined)).toEqual({
+      enabled: false,
+      dir: DEFAULT_SPILL_DIR,
+      thresholdChars: DEFAULT_OVERSIZED_TOOL_RESULT_CHARS,
+      keepLast: DEFAULT_SPILL_KEEP_LAST,
+    });
+  });
+
+  it("defaults when the param is malformed", () => {
+    expect(readSpillPolicy({ __toolResultSpill: "nope" }).enabled).toBe(false);
+    expect(readSpillPolicy({ __toolResultSpill: 42 }).dir).toBe(DEFAULT_SPILL_DIR);
+  });
+
+  it("reads enabled + dir + threshold + keepLast", () => {
+    const p = readSpillPolicy({
+      __toolResultSpill: { enabled: true, dir: "/tmp/x", thresholdChars: 1000, keepLast: 5 },
+    });
+    expect(p).toEqual({ enabled: true, dir: "/tmp/x", thresholdChars: 1000, keepLast: 5 });
+  });
+
+  it("rejects a non-absolute dir, a non-positive threshold, and a bad keepLast", () => {
+    const p = readSpillPolicy({
+      __toolResultSpill: { enabled: true, dir: "relative", thresholdChars: 0, keepLast: -3 },
+    });
+    expect(p.dir).toBe(DEFAULT_SPILL_DIR);
+    expect(p.thresholdChars).toBe(DEFAULT_OVERSIZED_TOOL_RESULT_CHARS);
+    expect(p.keepLast).toBe(DEFAULT_SPILL_KEEP_LAST);
+  });
+
+  it("only treats enabled === true as enabled (not truthy strings)", () => {
+    expect(readSpillPolicy({ __toolResultSpill: { enabled: "yes" } }).enabled).toBe(false);
+    expect(readSpillPolicy({ __toolResultSpill: { enabled: 1 } }).enabled).toBe(false);
+  });
+});
+
+describe("isOversizedToolResult", () => {
+  const policy = readSpillPolicy({ __toolResultSpill: { enabled: true, thresholdChars: 100 } });
+  it("is false at or below the threshold (boundary)", () => {
+    expect(isOversizedToolResult("a".repeat(100), policy)).toBe(false);
+    expect(isOversizedToolResult("a".repeat(99), policy)).toBe(false);
+  });
+  it("is true above the threshold", () => {
+    expect(isOversizedToolResult("a".repeat(101), policy)).toBe(true);
+  });
+});
+
+describe("formatSpillPayload", () => {
+  it("formats an array as JSONL with a record count", () => {
+    const r = formatSpillPayload([{ a: 1 }, { b: 2 }, { c: 3 }]);
+    expect(r.format).toBe("jsonl");
+    expect(r.records).toBe(3);
+    expect(r.content.split("\n")).toEqual(['{"a":1}', '{"b":2}', '{"c":3}']);
+  });
+
+  it("formats a non-array as pretty JSON with no record count", () => {
+    const r = formatSpillPayload({ hello: "world" });
+    expect(r.format).toBe("json");
+    expect(r.records).toBeUndefined();
+    expect(r.content).toBe('{\n  "hello": "world"\n}');
+  });
+
+  it("handles null", () => {
+    expect(formatSpillPayload(null)).toEqual({ content: "null", format: "json" });
+  });
+});
+
+describe("buildSpillHandle", () => {
+  it("returns a handle with path, format, records, preview, and bash instructions", () => {
+    const serialized = "x".repeat(SPILLED_PREVIEW_CHARS + 50_000);
+    const h = buildSpillHandle({
+      toolName: "mcp_gmail_GMAIL_FETCH_EMAILS",
+      path: "/tmp/tool-results/mcp_gmail_GMAIL_FETCH_EMAILS_tool_1.jsonl",
+      format: "jsonl",
+      serialized,
+      records: 312,
+    });
+    expect(h.__toolResultSpilled).toBe(true);
+    expect(h.records).toBe(312);
+    expect(h.totalChars).toBe(serialized.length);
+    expect((h.preview as string).length).toBe(SPILLED_PREVIEW_CHARS);
+    expect(String(h.note)).toContain("/tmp/tool-results/");
+    expect(String(h.note)).toContain("jq"); // array → jsonl hint
+    expect(String(h.note)).toContain("Do NOT cat");
+  });
+
+  it("omits the array-only jq hint and records for json format", () => {
+    const h = buildSpillHandle({
+      toolName: "t",
+      path: "/tmp/tool-results/t_x.json",
+      format: "json",
+      serialized: "y".repeat(10),
+    });
+    expect(h.records).toBeUndefined();
+    expect(String(h.note)).not.toContain("jq");
+  });
+});
+
+describe("buildInlineTruncation", () => {
+  it("returns a truncation marker with a capped preview and omitted-char count", () => {
+    const serialized = "z".repeat(INLINE_TRUNCATE_PREVIEW_CHARS + 1234);
+    const t = buildInlineTruncation("some_tool", serialized);
+    expect(t.__toolResultTruncated).toBe(true);
+    expect((t.preview as string).length).toBe(INLINE_TRUNCATE_PREVIEW_CHARS);
+    expect(t.omittedChars).toBe(1234);
+    expect(String(t.note)).toContain("Do NOT retry");
+  });
+});