@poncho-ai/harness 0.59.14 → 0.59.16

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.16 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
@@ -8,9 +8,9 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
+ESM dist/index.js            571.49 KB
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM dist/index.js            564.58 KB
-ESM ⚡️ Build success in 217ms
+ESM ⚡️ Build success in 239ms
 DTS Build start
-DTS ⚡️ Build success in 8055ms
-DTS dist/index.d.ts 102.50 KB
+DTS ⚡️ Build success in 6987ms
+DTS dist/index.d.ts 103.12 KB

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @poncho-ai/harness
 
+## 0.59.16
+
+### Patch Changes
+
+- [`96bbf55`](https://github.com/cesr/poncho-ai/commit/96bbf5532d85de1ae0957f770758bf26b9c1e50b) Thanks [@cesr](https://github.com/cesr)! - Tighten the oversized-tool-result spill read-back path (follow-up to the
+  spill guard):
+  - The spill handle now exposes `toolResultId` / `toolCallId` explicitly, so
+    the model passes the right id to `get_tool_result_by_id` instead of guessing
+    from the path stem.
+  - `get_tool_result_by_id` now redirects when it hits a spill envelope: it
+    returns `{ spilled: true, path, totalChars }` pointing at the VFS file rather
+    than silently paging the ~6k-char envelope (which read as "I've got
+    everything"). The file is the source of truth; read it with bash.
+  - The handle's `note` is now format-aware: JSONL spills keep the line tools
+    (`sed`/`grep`/`jq` per line), but pretty-JSON spills steer to byte-offset
+    reads and `jq -r` to unescape — `wc -l`/`grep` mislead on JSON whose string
+    fields carry escaped newlines on one line.
+
+## 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,66 @@ 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, toolCallId, path, format, serialized, records } = opts;
+  const approxTokens = Math.ceil(serialized.length / 4);
+  const bytesHint = `\`wc -c ${path}\` (size), \`head -c 4000 ${path}\`, \`tail -c +<N> ${path} | head -c 4000\` (read from byte N)`;
+  const note = format === "jsonl" ? `Result too large to return inline (~${approxTokens.toLocaleString()} tokens, ${records} records, one JSON object per line). Read it with bash: ${bytesHint}, \`sed -n '1,5p' ${path}\`, \`grep -i <term> ${path}\`, or \`jq -c 'select(...)' ${path}\` per line. Do NOT cat/read_file the whole file (it re-overflows). Or re-run the tool with a narrower request.` : `Result too large to return inline (~${approxTokens.toLocaleString()} tokens, JSON). Its string fields are escaped onto single lines, so \`wc -l\`/\`grep\` MISLEAD \u2014 read by byte offset (${bytesHint}) or unescape first with \`jq -r '.stdout // .' ${path}\` (then pipe to wc -l / grep). Do NOT cat/read_file the whole file (it re-overflows). Or re-run the tool with a narrower request.`;
+  return {
+    __toolResultSpilled: true,
+    tool: toolName,
+    // Expose the id explicitly so the model passes the right value if it
+    // reaches for get_tool_result_by_id (the path stem is NOT the id).
+    toolResultId: toolCallId,
+    toolCallId,
+    path,
+    format,
+    ...records !== void 0 ? { records } : {},
+    totalChars: serialized.length,
+    approxTokens,
+    preview: serialized.slice(0, SPILLED_PREVIEW_CHARS),
+    note
+  };
+};
+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({
@@ -9718,6 +9778,21 @@ var AgentHarness = class _AgentHarness {
             error: `No archived tool result found for id "${toolResultId}" in this conversation.`
           };
         }
+        try {
+          const env = JSON.parse(record.payload);
+          if (env && env.__toolResultSpilled === true && typeof env.path === "string") {
+            return {
+              toolResultId: record.toolResultId,
+              toolName: record.toolName,
+              toolCallId: record.toolCallId,
+              spilled: true,
+              path: env.path,
+              totalChars: typeof env.totalChars === "number" ? env.totalChars : void 0,
+              note: `This result was spilled to ${env.path} \u2014 the archive only holds a preview. Read the full payload there with bash (head -c / tail -c +<N> | head -c, or jq), NOT via get_tool_result_by_id.`
+            };
+          }
+        } catch {
+        }
         const offset = Math.max(0, Number(input.offset) || 0);
         const limit = Math.min(Math.max(Number(input.limit) || 6e3, 1), 2e4);
         const end = Math.min(record.payload.length, offset + limit);
@@ -9825,6 +9900,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, toolCallId, 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 +10804,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 +11946,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 +11999,7 @@ ${textContent}` };
                   output: {
                     type: "content",
                     value: [
-                      { type: "text", text: JSON.stringify(strippedOutput ?? null) },
+                      { type: "text", text: effectiveSerialized },
                       ...mediaItems
                     ]
                   }
@@ -11870,7 +12009,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.16",
   "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";
@@ -1060,6 +1068,30 @@ export class AgentHarness {
             error: `No archived tool result found for id "${toolResultId}" in this conversation.`,
           };
         }
+        // Spill envelopes: the archived payload is the small handle, not the
+        // data — the real payload lives in a VFS file. Paging the envelope here
+        // would silently return ~6k chars and `hasMore:false`, reading as "I've
+        // got everything". Redirect to the file (read it with bash) instead of
+        // building a second read path the agent already has via bash/jq.
+        try {
+          const env = JSON.parse(record.payload) as Record<string, unknown>;
+          if (env && env.__toolResultSpilled === true && typeof env.path === "string") {
+            return {
+              toolResultId: record.toolResultId,
+              toolName: record.toolName,
+              toolCallId: record.toolCallId,
+              spilled: true,
+              path: env.path,
+              totalChars: typeof env.totalChars === "number" ? env.totalChars : undefined,
+              note:
+                `This result was spilled to ${env.path} — the archive only holds a preview. ` +
+                `Read the full payload there with bash (head -c / tail -c +<N> | head -c, or ` +
+                `jq), NOT via get_tool_result_by_id.`,
+            };
+          }
+        } catch {
+          // Not JSON / not an envelope — fall through to normal paging.
+        }
         const offset = Math.max(0, Number(input.offset) || 0);
         const limit = Math.min(Math.max(Number(input.limit) || 6000, 1), 20_000);
         const end = Math.min(record.payload.length, offset + limit);
@@ -1181,6 +1213,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, toolCallId, 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 +2315,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 +3796,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 +3860,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 +3870,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,150 @@
+// 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;
+  toolCallId: string;
+  path: string;
+  format: "jsonl" | "json";
+  serialized: string;
+  records?: number;
+}): Record<string, unknown> => {
+  const { toolName, toolCallId, path, format, serialized, records } = opts;
+  const approxTokens = Math.ceil(serialized.length / 4);
+  // Byte-offset reads are correct for BOTH formats; line tools (`wc -l`,
+  // `grep`, `sed -n`) only behave for JSONL (one record per line). For pretty
+  // JSON the payload is a JSON document whose string fields (e.g. a command's
+  // stdout) carry escaped `\n` on a single line, so `wc -l`/`grep` mislead —
+  // unescape with `jq -r` first. Tailor the hint to the format so the model
+  // doesn't act on wrong line/match counts.
+  const bytesHint =
+    `\`wc -c ${path}\` (size), \`head -c 4000 ${path}\`, ` +
+    `\`tail -c +<N> ${path} | head -c 4000\` (read from byte N)`;
+  const note =
+    format === "jsonl"
+      ? `Result too large to return inline (~${approxTokens.toLocaleString()} tokens, ` +
+        `${records} records, one JSON object per line). Read it with bash: ${bytesHint}, ` +
+        `\`sed -n '1,5p' ${path}\`, \`grep -i <term> ${path}\`, or \`jq -c 'select(...)' ${path}\` ` +
+        `per line. Do NOT cat/read_file the whole file (it re-overflows). Or re-run the tool ` +
+        `with a narrower request.`
+      : `Result too large to return inline (~${approxTokens.toLocaleString()} tokens, JSON). ` +
+        `Its string fields are escaped onto single lines, so \`wc -l\`/\`grep\` MISLEAD — ` +
+        `read by byte offset (${bytesHint}) or unescape first with ` +
+        `\`jq -r '.stdout // .' ${path}\` (then pipe to wc -l / grep). Do NOT cat/read_file the ` +
+        `whole file (it re-overflows). Or re-run the tool with a narrower request.`;
+  return {
+    __toolResultSpilled: true,
+    tool: toolName,
+    // Expose the id explicitly so the model passes the right value if it
+    // reaches for get_tool_result_by_id (the path stem is NOT the id).
+    toolResultId: toolCallId,
+    toolCallId,
+    path,
+    format,
+    ...(records !== undefined ? { records } : {}),
+    totalChars: serialized.length,
+    approxTokens,
+    preview: serialized.slice(0, SPILLED_PREVIEW_CHARS),
+    note,
+  };
+};
+
+/** 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,135 @@
+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, the call id, and bash instructions", () => {
+    const serialized = "x".repeat(SPILLED_PREVIEW_CHARS + 50_000);
+    const h = buildSpillHandle({
+      toolName: "mcp_gmail_GMAIL_FETCH_EMAILS",
+      toolCallId: "toolu_01Ctij",
+      path: "/tmp/tool-results/mcp_gmail_GMAIL_FETCH_EMAILS_toolu_01Ctij.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);
+    // Issue 1: the call id is exposed explicitly (not just embedded in the path).
+    expect(h.toolCallId).toBe("toolu_01Ctij");
+    expect(h.toolResultId).toBe("toolu_01Ctij");
+    expect(String(h.note)).toContain("/tmp/tool-results/");
+    expect(String(h.note)).toContain("Do NOT cat");
+    // JSONL: line tools are valid (one record per line).
+    expect(String(h.note)).toContain("sed -n");
+  });
+
+  it("json format steers AWAY from line tools and toward byte-offset / jq (Issue 3)", () => {
+    const h = buildSpillHandle({
+      toolName: "run_code",
+      toolCallId: "toolu_2",
+      path: "/tmp/tool-results/run_code_toolu_2.json",
+      format: "json",
+      serialized: "y".repeat(10),
+    });
+    expect(h.records).toBeUndefined();
+    const note = String(h.note);
+    // It must warn that wc -l / grep mislead, and point at byte-offset + jq -r.
+    expect(note).toContain("MISLEAD");
+    expect(note).toContain("tail -c +");
+    expect(note).toContain("jq -r");
+    // It must NOT suggest sed-by-line for escaped-JSON.
+    expect(note).not.toContain("sed -n");
+  });
+});
+
+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");
+  });
+});