@poncho-ai/harness 0.59.15 → 0.59.16

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.59.15 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            570.16 KB
-ESM ⚡️ Build success in 242ms
+ESM ⚡️ Build success in 239ms
 DTS Build start
-DTS ⚡️ Build success in 6639ms
+DTS ⚡️ Build success in 6987ms
 DTS dist/index.d.ts 103.12 KB

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @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

package/dist/index.js

@@ -5676,19 +5676,24 @@ var formatSpillPayload = (output) => {
   return { content: JSON.stringify(output ?? null, null, 2), format: "json" };
 };
 var buildSpillHandle = (opts) => {
-  const { toolName, path, format, serialized, records } = opts;
+  const { toolName, toolCallId, path, format, serialized, records } = opts;
   const approxTokens = Math.ceil(serialized.length / 4);
-  const isArray = format === "jsonl";
+  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: `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).`
+    note
   };
 };
 var buildInlineTruncation = (toolName, serialized) => {
@@ -9773,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);
@@ -9900,7 +9920,7 @@ var AgentHarness = class _AgentHarness {
         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 });
+        return buildSpillHandle({ toolName, toolCallId, path, format, serialized, records });
       } catch {
       }
     }

package/package.json

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

package/src/harness.ts

@@ -1068,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);
@@ -1219,7 +1243,7 @@ export class AgentHarness {
         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 });
+        return buildSpillHandle({ toolName, toolCallId, path, format, serialized, records });
       } catch {
         // Fall through to inline truncation below.
       }

package/src/tool-result-guard.ts

@@ -80,32 +80,49 @@ export const formatSpillPayload = (
  *  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, path, format, serialized, records } = opts;
+  const { toolName, toolCallId, path, format, serialized, records } = opts;
   const approxTokens = Math.ceil(serialized.length / 4);
-  const isArray = format === "jsonl";
+  // 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:
-      `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).`,
+    note,
   };
 };
 

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

@@ -81,11 +81,12 @@ describe("formatSpillPayload", () => {
 });
 
 describe("buildSpillHandle", () => {
-  it("returns a handle with path, format, records, preview, and bash instructions", () => {
+  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",
-      path: "/tmp/tool-results/mcp_gmail_GMAIL_FETCH_EMAILS_tool_1.jsonl",
+      toolCallId: "toolu_01Ctij",
+      path: "/tmp/tool-results/mcp_gmail_GMAIL_FETCH_EMAILS_toolu_01Ctij.jsonl",
       format: "jsonl",
       serialized,
       records: 312,
@@ -94,20 +95,31 @@ describe("buildSpillHandle", () => {
     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("jq"); // array → jsonl hint
     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("omits the array-only jq hint and records for json format", () => {
+  it("json format steers AWAY from line tools and toward byte-offset / jq (Issue 3)", () => {
     const h = buildSpillHandle({
-      toolName: "t",
-      path: "/tmp/tool-results/t_x.json",
+      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();
-    expect(String(h.note)).not.toContain("jq");
+    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");
   });
 });