@poncho-ai/harness 0.59.15 → 0.59.17

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.17 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            570.16 KB
-ESM ⚡️ Build success in 242ms
+ESM dist/index.js            571.82 KB
+ESM ⚡️ Build success in 264ms
 DTS Build start
-DTS ⚡️ Build success in 6639ms
-DTS dist/index.d.ts 103.12 KB
+DTS ⚡️ Build success in 7586ms
+DTS dist/index.d.ts 104.01 KB

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @poncho-ai/harness
 
+## 0.59.17
+
+### Patch Changes
+
+- [`963a0e3`](https://github.com/cesr/poncho-ai/commit/963a0e34b9f362ab21b7b8d94835f37713d4e5da) Thanks [@cesr](https://github.com/cesr)! - Browser config: support embedding apps that own per-tenant browser sessions
+  and the live viewport.
+  - `browser.sessionName` now overrides the browser session id (previously
+    always `poncho-${agentId}`). Lets a multi-tenant host isolate sessions
+    per user even when every user shares one agent definition.
+  - `browser.storagePersistence` lets the host supply its own
+    `{ save(json), load() }` for the browser storage state (cookies +
+    localStorage). When provided, the harness skips its built-in file-based
+    persistence — so state can live in an encrypted/DB-backed per-tenant store.
+  - `browser.hostManagedStreaming` makes the harness skip wiring
+    `onFrame`/`onStatus` during `run()`, so no `browser:frame` / `browser:status`
+    events are emitted into the agent event stream. The host subscribes to the
+    `BrowserSession` listeners directly and streams frames out-of-band (and can
+    keep the viewport interactive while the agent is idle).
+
+## 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.d.ts

@@ -820,6 +820,21 @@ interface PonchoConfig extends McpConfig {
         /** Connect to an existing browser via CDP URL or port.
          *  Mutually exclusive with `provider`. */
         cdpUrl?: string;
+        /** Host-supplied persistence for the browser's storage state
+         *  (cookies + localStorage as a Playwright storageState JSON). When
+         *  provided, the harness uses this instead of its built-in file-based
+         *  persistence — letting an embedding app store session state in its
+         *  own (e.g. encrypted, per-tenant) backend. */
+        storagePersistence?: {
+            save(json: string): Promise<void>;
+            load(): Promise<string | undefined>;
+        };
+        /** When true, the host owns the live viewport: the harness will NOT
+         *  wire frame/status listeners during run() (so no `browser:frame` /
+         *  `browser:status` events are emitted into the agent event stream).
+         *  The host is expected to subscribe to the BrowserSession's
+         *  `onFrame`/`onStatus` directly and stream frames out-of-band. */
+        hostManagedStreaming?: boolean;
     };
 }
 declare const resolveStateConfig: (config: PonchoConfig | undefined) => StateConfig | undefined;

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 {
       }
     }
@@ -10631,10 +10651,13 @@ var AgentHarness = class _AgentHarness {
     this._browserMod = browserMod;
     const browserCfg = typeof config.browser === "object" ? { ...config.browser } : {};
     const agentId = this.parsedAgent?.frontmatter.id ?? this.parsedAgent?.frontmatter.name ?? "default";
-    const sessionId = `poncho-${agentId}`;
-    const storagePersistence = await this.buildBrowserStoragePersistence(config, sessionId);
-    if (storagePersistence) {
-      browserCfg.storagePersistence = storagePersistence;
+    const sessionName = typeof config.browser === "object" ? config.browser.sessionName : void 0;
+    const sessionId = sessionName ?? `poncho-${agentId}`;
+    if (!browserCfg.storagePersistence) {
+      const storagePersistence = await this.buildBrowserStoragePersistence(config, sessionId);
+      if (storagePersistence) {
+        browserCfg.storagePersistence = storagePersistence;
+      }
     }
     const session = new browserMod.BrowserSession(sessionId, browserCfg);
     this._browserSession = session;
@@ -10962,7 +10985,8 @@ ${this.skillFingerprint}`;
     const browserEventQueue = [];
     const browserCleanups = [];
     const browserSession = this._browserSession;
-    if (browserSession) {
+    const hostManagedStreaming = typeof this.loadedConfig?.browser === "object" && this.loadedConfig.browser.hostManagedStreaming === true;
+    if (browserSession && !hostManagedStreaming) {
       browserCleanups.push(
         browserSession.onFrame(conversationId, makeBrowserFrameListener(browserEventQueue)),
         browserSession.onStatus(conversationId, makeBrowserStatusListener(browserEventQueue))

package/package.json

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

package/src/config.ts

@@ -294,6 +294,21 @@ export interface PonchoConfig extends McpConfig {
         /** Connect to an existing browser via CDP URL or port.
          *  Mutually exclusive with `provider`. */
         cdpUrl?: string;
+        /** Host-supplied persistence for the browser's storage state
+         *  (cookies + localStorage as a Playwright storageState JSON). When
+         *  provided, the harness uses this instead of its built-in file-based
+         *  persistence — letting an embedding app store session state in its
+         *  own (e.g. encrypted, per-tenant) backend. */
+        storagePersistence?: {
+          save(json: string): Promise<void>;
+          load(): Promise<string | undefined>;
+        };
+        /** When true, the host owns the live viewport: the harness will NOT
+         *  wire frame/status listeners during run() (so no `browser:frame` /
+         *  `browser:status` events are emitted into the agent event stream).
+         *  The host is expected to subscribe to the BrowserSession's
+         *  `onFrame`/`onStatus` directly and stream frames out-of-band. */
+        hostManagedStreaming?: boolean;
       };
 }
 

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.
       }
@@ -2099,11 +2123,18 @@ export class AgentHarness {
     this._browserMod = browserMod;
     const browserCfg: Record<string, unknown> = typeof config.browser === "object" ? { ...config.browser } : {};
     const agentId = this.parsedAgent?.frontmatter.id ?? this.parsedAgent?.frontmatter.name ?? "default";
-    const sessionId = `poncho-${agentId}`;
-
-    const storagePersistence = await this.buildBrowserStoragePersistence(config, sessionId);
-    if (storagePersistence) {
-      browserCfg.storagePersistence = storagePersistence;
+    // Let an embedding app override the session id (e.g. to make it per-tenant
+    // when many users share one agent definition). Falls back to the agent id.
+    const sessionName = typeof config.browser === "object" ? config.browser.sessionName : undefined;
+    const sessionId = sessionName ?? `poncho-${agentId}`;
+
+    // Only build the built-in file persistence when the host didn't supply its
+    // own. A host-provided `storagePersistence` (e.g. encrypted/DB-backed) wins.
+    if (!browserCfg.storagePersistence) {
+      const storagePersistence = await this.buildBrowserStoragePersistence(config, sessionId);
+      if (storagePersistence) {
+        browserCfg.storagePersistence = storagePersistence;
+      }
     }
 
     const session = new browserMod.BrowserSession(sessionId, browserCfg);
@@ -2553,7 +2584,14 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
           profileDir: string;
           isLaunched: boolean }
       | undefined;
-    if (browserSession) {
+    // When the host owns the live viewport (`browser.hostManagedStreaming`),
+    // it subscribes to onFrame/onStatus directly and streams frames out-of-band.
+    // Skip the during-run wiring so frames don't double-emit into the agent
+    // event stream (and don't flood any host-side event buffer).
+    const hostManagedStreaming =
+      typeof this.loadedConfig?.browser === "object" &&
+      this.loadedConfig.browser.hostManagedStreaming === true;
+    if (browserSession && !hostManagedStreaming) {
       browserCleanups.push(
         browserSession.onFrame(conversationId, makeBrowserFrameListener(browserEventQueue)),
         browserSession.onStatus(conversationId, makeBrowserStatusListener(browserEventQueue)),

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");
   });
 });