@poncho-ai/browser 0.6.26 → 0.7.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/browser@0.6.26 build /home/runner/work/poncho-ai/poncho-ai/packages/browser
+> @poncho-ai/browser@0.7.0 build /home/runner/work/poncho-ai/poncho-ai/packages/browser
 > tsup src/index.ts --format esm --dts
 
 CLI Building entry: src/index.ts
@@ -7,8 +7,8 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js 47.98 KB
-ESM ⚡️ Build success in 60ms
+ESM dist/index.js 53.08 KB
+ESM ⚡️ Build success in 63ms
 DTS Build start
-DTS ⚡️ Build success in 4894ms
-DTS dist/index.d.ts 13.77 KB
+DTS ⚡️ Build success in 5156ms
+DTS dist/index.d.ts 14.54 KB

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @poncho-ai/browser
 
+## 0.7.0
+
+### Minor 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.6.26
 
 ### Patch Changes

package/dist/index.d.ts

@@ -144,6 +144,21 @@ declare class BrowserSession {
         url: string;
         title: string;
     }>;
+    /**
+     * Fetch a file using the page's own (logged-in) session and return its
+     * bytes, so the host can persist it (e.g. to a VFS). `url` defaults to the
+     * current page. The fetch runs INSIDE the page via `evaluate`, so it carries
+     * the site's cookies and works the same whether the browser is local or a
+     * remote/cloud provider (the bytes come back over CDP). Because it's a page
+     * `fetch`, same-origin and CORS-permissive URLs work; a cross-origin URL the
+     * site doesn't allow CORS for will fail — navigate to the file first (so it's
+     * same-origin) or pass its direct URL while on that site.
+     */
+    download(conversationId: string, url?: string): Promise<{
+        data: Buffer;
+        contentType: string;
+        filename: string;
+    }>;
     scroll(conversationId: string, direction: "up" | "down", amount?: number): Promise<void>;
     clickText(conversationId: string, text: string, exact?: boolean): Promise<void>;
     executeJs(conversationId: string, script: string): Promise<unknown>;

package/dist/index.js

@@ -244,6 +244,28 @@ var SAME_TAB_INIT_SCRIPT = `
   } catch {}
 })();
 `;
+function sanitizeName(name) {
+  const cleaned = name.trim().replace(/[/\\]/g, "_").replace(/\0/g, "");
+  return cleaned || "download";
+}
+function filenameFromDownload(disposition, url) {
+  const star = /filename\*=(?:UTF-8'')?["']?([^"';]+)/i.exec(disposition);
+  if (star?.[1]) {
+    try {
+      return sanitizeName(decodeURIComponent(star[1]));
+    } catch {
+      return sanitizeName(star[1]);
+    }
+  }
+  const plain = /filename=["']?([^"';]+)/i.exec(disposition);
+  if (plain?.[1]) return sanitizeName(plain[1]);
+  try {
+    const base = new URL(url).pathname.split("/").filter(Boolean).pop();
+    if (base) return sanitizeName(decodeURIComponent(base));
+  } catch {
+  }
+  return "download";
+}
 var BrowserSession = class {
   config;
   sessionId;
@@ -693,6 +715,55 @@ var BrowserSession = class {
       this.unlock();
     }
   }
+  /**
+   * Fetch a file using the page's own (logged-in) session and return its
+   * bytes, so the host can persist it (e.g. to a VFS). `url` defaults to the
+   * current page. The fetch runs INSIDE the page via `evaluate`, so it carries
+   * the site's cookies and works the same whether the browser is local or a
+   * remote/cloud provider (the bytes come back over CDP). Because it's a page
+   * `fetch`, same-origin and CORS-permissive URLs work; a cross-origin URL the
+   * site doesn't allow CORS for will fail — navigate to the file first (so it's
+   * same-origin) or pass its direct URL while on that site.
+   */
+  async download(conversationId, url) {
+    await this.lock();
+    try {
+      const mgr = await this.ensureManager();
+      await this.switchToConversation(mgr, conversationId);
+      const page = mgr.getPage();
+      const target = url && url.trim() ? url.trim() : page.url();
+      if (!target || target === "about:blank") {
+        throw new Error("no URL to download (open the file's page first, or pass a url)");
+      }
+      const MAX_BYTES = 25 * 1024 * 1024;
+      const expr = `(async () => {
+        const res = await fetch(${JSON.stringify(target)}, { credentials: "include" });
+        if (!res.ok) throw new Error("HTTP " + res.status + " " + res.statusText);
+        const buf = new Uint8Array(await res.arrayBuffer());
+        if (buf.length > ${MAX_BYTES}) throw new Error("file too large: " + buf.length + " bytes (max ${MAX_BYTES})");
+        let bin = "";
+        const CH = 0x8000;
+        for (let i = 0; i < buf.length; i += CH) {
+          bin += String.fromCharCode.apply(null, buf.subarray(i, i + CH));
+        }
+        return {
+          base64: btoa(bin),
+          contentType: res.headers.get("content-type") || "",
+          disposition: res.headers.get("content-disposition") || "",
+          finalUrl: res.url || ${JSON.stringify(target)},
+        };
+      })()`;
+      const r = await page.evaluate(expr);
+      const data = Buffer.from(r.base64, "base64");
+      return {
+        data,
+        contentType: r.contentType,
+        filename: filenameFromDownload(r.disposition, r.finalUrl)
+      };
+    } finally {
+      this.unlock();
+    }
+  }
   async scroll(conversationId, direction, amount) {
     await this.lock();
     try {
@@ -1261,6 +1332,47 @@ function createBrowserTools(getSession) {
         return { url: result.url, title: result.title, text: result.text };
       }
     },
+    {
+      name: "browser_download",
+      description: "Download a file from the browser and save it into the user's virtual filesystem (VFS). Fetches the file using the browser's logged-in session, so it works for files behind a login \u2014 use it to keep a PDF, CSV, image, or other file the page offers. It fetches `url` (or the current page if you omit it), so for a download link on the page, grab its href from a snapshot first; for a file that opens in the browser, navigate to it and call this with no url. The fetch runs in the page, so the url should be same-origin with the current page (navigate to the file's site first if needed). Returns the saved VFS path and byte size \u2014 the bytes go straight to the VFS, not through the chat.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: {
+            type: "string",
+            description: "Destination in the VFS. Include a filename (e.g. /downloads/report.pdf); parent folders are created as needed. End with '/' (e.g. /downloads/) to keep the file's own name."
+          },
+          url: {
+            type: "string",
+            description: "URL of the file to download. Optional \u2014 defaults to the current page's URL."
+          }
+        },
+        required: ["path"]
+      },
+      handler: async (input, context) => {
+        const session = getSession();
+        const vfs = context.vfs;
+        if (!vfs) throw new Error("VFS is not available in this environment");
+        const dest0 = String(input.path ?? "").trim();
+        if (!dest0) throw new Error("path is required");
+        const url = input.url != null ? String(input.url) : void 0;
+        const { data, contentType, filename } = await session.download(
+          context.conversationId ?? "__default__",
+          url
+        );
+        let dest = dest0.startsWith("/") ? dest0 : `/${dest0}`;
+        if (dest.endsWith("/")) dest = `${dest}${filename}`;
+        const slash = dest.lastIndexOf("/");
+        if (slash > 0) {
+          try {
+            await vfs.mkdir(dest.slice(0, slash), { recursive: true });
+          } catch {
+          }
+        }
+        await vfs.writeFile(dest, new Uint8Array(data), contentType || void 0);
+        return { path: dest, bytes: data.length, ...contentType ? { contentType } : {} };
+      }
+    },
     {
       name: "browser_screenshot",
       description: "Take a screenshot of the current page. Returns the image so you can see exactly what the page looks like. Use this when you need to see visual layout, verify actions, or read content that isn't in the accessibility tree.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/browser",
-  "version": "0.6.26",
+  "version": "0.7.0",
   "description": "Browser automation for Poncho agents, powered by agent-browser",
   "repository": {
     "type": "git",

package/src/session.ts

@@ -146,6 +146,29 @@ interface ConversationTab {
   lastUsed: number;
 }
 
+/** Strip path separators / nulls so a derived name can't escape its folder. */
+function sanitizeName(name: string): string {
+  const cleaned = name.trim().replace(/[/\\]/g, "_").replace(/\0/g, "");
+  return cleaned || "download";
+}
+
+/** Derive a filename from a Content-Disposition header, falling back to the
+ *  URL's last path segment, then a generic "download". */
+function filenameFromDownload(disposition: string, url: string): string {
+  const star = /filename\*=(?:UTF-8'')?["']?([^"';]+)/i.exec(disposition);
+  if (star?.[1]) {
+    try { return sanitizeName(decodeURIComponent(star[1])); }
+    catch { return sanitizeName(star[1]); }
+  }
+  const plain = /filename=["']?([^"';]+)/i.exec(disposition);
+  if (plain?.[1]) return sanitizeName(plain[1]);
+  try {
+    const base = new URL(url).pathname.split("/").filter(Boolean).pop();
+    if (base) return sanitizeName(decodeURIComponent(base));
+  } catch { /* not a parseable URL */ }
+  return "download";
+}
+
 export class BrowserSession {
   private readonly config: BrowserConfig;
   private readonly sessionId: string;
@@ -655,6 +678,66 @@ export class BrowserSession {
     }
   }
 
+  /**
+   * Fetch a file using the page's own (logged-in) session and return its
+   * bytes, so the host can persist it (e.g. to a VFS). `url` defaults to the
+   * current page. The fetch runs INSIDE the page via `evaluate`, so it carries
+   * the site's cookies and works the same whether the browser is local or a
+   * remote/cloud provider (the bytes come back over CDP). Because it's a page
+   * `fetch`, same-origin and CORS-permissive URLs work; a cross-origin URL the
+   * site doesn't allow CORS for will fail — navigate to the file first (so it's
+   * same-origin) or pass its direct URL while on that site.
+   */
+  async download(
+    conversationId: string,
+    url?: string,
+  ): Promise<{ data: Buffer; contentType: string; filename: string }> {
+    await this.lock();
+    try {
+      const mgr = await this.ensureManager();
+      await this.switchToConversation(mgr, conversationId);
+      const page = mgr.getPage();
+      const target = url && url.trim() ? url.trim() : page.url();
+      if (!target || target === "about:blank") {
+        throw new Error("no URL to download (open the file's page first, or pass a url)");
+      }
+      const MAX_BYTES = 25 * 1024 * 1024;
+      // Build the in-page fetch. JSON.stringify safely escapes the URL into the
+      // evaluated source. Base64 in-page so the bytes survive the JSON channel.
+      const expr = `(async () => {
+        const res = await fetch(${JSON.stringify(target)}, { credentials: "include" });
+        if (!res.ok) throw new Error("HTTP " + res.status + " " + res.statusText);
+        const buf = new Uint8Array(await res.arrayBuffer());
+        if (buf.length > ${MAX_BYTES}) throw new Error("file too large: " + buf.length + " bytes (max ${MAX_BYTES})");
+        let bin = "";
+        const CH = 0x8000;
+        for (let i = 0; i < buf.length; i += CH) {
+          bin += String.fromCharCode.apply(null, buf.subarray(i, i + CH));
+        }
+        return {
+          base64: btoa(bin),
+          contentType: res.headers.get("content-type") || "",
+          disposition: res.headers.get("content-disposition") || "",
+          finalUrl: res.url || ${JSON.stringify(target)},
+        };
+      })()`;
+      const r = (await page.evaluate(expr)) as {
+        base64: string;
+        contentType: string;
+        disposition: string;
+        finalUrl: string;
+      };
+      const data = Buffer.from(r.base64, "base64");
+      return {
+        data,
+        contentType: r.contentType,
+        filename: filenameFromDownload(r.disposition, r.finalUrl),
+      };
+    } finally {
+      this.unlock();
+    }
+  }
+
   async scroll(conversationId: string, direction: "up" | "down", amount?: number): Promise<void> {
     await this.lock();
     try {

package/src/tools.ts

@@ -176,6 +176,55 @@ export function createBrowserTools(
         return { url: result.url, title: result.title, text: result.text };
       },
     },
+    {
+      name: "browser_download",
+      description:
+        "Download a file from the browser and save it into the user's virtual filesystem (VFS). " +
+        "Fetches the file using the browser's logged-in session, so it works for files behind a login — " +
+        "use it to keep a PDF, CSV, image, or other file the page offers. " +
+        "It fetches `url` (or the current page if you omit it), so for a download link on the page, grab its href from a snapshot first; " +
+        "for a file that opens in the browser, navigate to it and call this with no url. " +
+        "The fetch runs in the page, so the url should be same-origin with the current page (navigate to the file's site first if needed). " +
+        "Returns the saved VFS path and byte size — the bytes go straight to the VFS, not through the chat.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: {
+            type: "string",
+            description:
+              "Destination in the VFS. Include a filename (e.g. /downloads/report.pdf); parent folders are created as needed. " +
+              "End with '/' (e.g. /downloads/) to keep the file's own name.",
+          },
+          url: {
+            type: "string",
+            description:
+              "URL of the file to download. Optional — defaults to the current page's URL.",
+          },
+        },
+        required: ["path"],
+      },
+      handler: async (input: BrowserToolInput, context: ToolContext) => {
+        const session = getSession();
+        const vfs = context.vfs;
+        if (!vfs) throw new Error("VFS is not available in this environment");
+        const dest0 = String(input.path ?? "").trim();
+        if (!dest0) throw new Error("path is required");
+        const url = input.url != null ? String(input.url) : undefined;
+        const { data, contentType, filename } = await session.download(
+          context.conversationId ?? "__default__",
+          url,
+        );
+        // A trailing slash (or bare folder) means "use the file's own name".
+        let dest = dest0.startsWith("/") ? dest0 : `/${dest0}`;
+        if (dest.endsWith("/")) dest = `${dest}${filename}`;
+        const slash = dest.lastIndexOf("/");
+        if (slash > 0) {
+          try { await vfs.mkdir(dest.slice(0, slash), { recursive: true }); } catch { /* exists */ }
+        }
+        await vfs.writeFile(dest, new Uint8Array(data), contentType || undefined);
+        return { path: dest, bytes: data.length, ...(contentType ? { contentType } : {}) };
+      },
+    },
     {
       name: "browser_screenshot",
       description: