@poncho-ai/harness 0.59.16 → 0.59.18

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.59.16 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.59.18 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/index.js            572.34 KB
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM ⚡️ Build success in 239ms
+ESM ⚡️ Build success in 214ms
 DTS Build start
-DTS ⚡️ Build success in 6987ms
-DTS dist/index.d.ts 103.12 KB
+DTS ⚡️ Build success in 7534ms
+DTS dist/index.d.ts 104.01 KB

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @poncho-ai/harness
 
+## 0.59.18
+
+### Patch Changes
+
+- [#184](https://github.com/cesr/poncho-ai/pull/184) [`12ce2be`](https://github.com/cesr/poncho-ai/commit/12ce2be01c9d98b1d9aa634d4d8051c4c0094a44) Thanks [@cesr](https://github.com/cesr)! - Add `browser_download` so the agent can save files from the browser into the
+  VFS. The tool fetches a file using the page's logged-in session (so it works
+  for files behind a login) and writes the bytes straight to the tenant's VFS via
+  `ToolContext.vfs` — never through the model. `url` defaults to the current page,
+  or pass a same-origin link's href. The fetch runs inside the page (`evaluate`),
+  so it works identically for local and remote/cloud browsers (bytes return over
+  CDP). Capped at 25 MB. The harness browser system prompt now documents it under
+  a "Saving files" section.
+
+## 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

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

@@ -10651,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;
@@ -10852,6 +10855,9 @@ Browser sessions (cookies, localStorage, login state) are automatically saved an
 - Use \`browser_screenshot\` only when you need to see visual layout or images. Screenshots consume significantly more tokens.
 - The accessibility tree may be sparse on some pages. If \`browser_snapshot\` returns little or no content, fall back to \`browser_content\` or \`browser_screenshot\`.
 
+### Saving files
+To keep a file the page offers (a PDF, CSV, image, export, etc.), use \`browser_download\` to save it into the user's filesystem. It fetches with the browser's logged-in session, so it works for files behind a login. For a download link, get its href from a snapshot and pass it as \`url\`; for a file that opens in the browser, navigate to it and call \`browser_download\` with no \`url\`. The bytes go straight to the filesystem (not through the chat), so prefer this over screenshotting or copy-pasting file contents.
+
 ### Tabs and resources
 Each conversation gets its own browser tab sharing a single browser instance. Call \`browser_close\` when done to free the tab. If you don't close it, the tab stays open and the user can continue interacting with it.` : "";
     const mainMemory = await memoryPromise;
@@ -10982,7 +10988,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.16",
+  "version": "0.59.18",
   "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

@@ -2123,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);
@@ -2369,6 +2376,9 @@ Browser sessions (cookies, localStorage, login state) are automatically saved an
 - Use \`browser_screenshot\` only when you need to see visual layout or images. Screenshots consume significantly more tokens.
 - The accessibility tree may be sparse on some pages. If \`browser_snapshot\` returns little or no content, fall back to \`browser_content\` or \`browser_screenshot\`.
 
+### Saving files
+To keep a file the page offers (a PDF, CSV, image, export, etc.), use \`browser_download\` to save it into the user's filesystem. It fetches with the browser's logged-in session, so it works for files behind a login. For a download link, get its href from a snapshot and pass it as \`url\`; for a file that opens in the browser, navigate to it and call \`browser_download\` with no \`url\`. The bytes go straight to the filesystem (not through the chat), so prefer this over screenshotting or copy-pasting file contents.
+
 ### Tabs and resources
 Each conversation gets its own browser tab sharing a single browser instance. Call \`browser_close\` when done to free the tab. If you don't close it, the tab stays open and the user can continue interacting with it.`
       : "";
@@ -2577,7 +2587,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)),