@poncho-ai/browser 0.6.25 → 0.7.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/browser@0.6.25 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.44 KB
+ESM dist/index.js 53.08 KB
 ESM ⚡️ Build success in 63ms
 DTS Build start
-DTS ⚡️ Build success in 5080ms
-DTS dist/index.d.ts 13.69 KB
+DTS ⚡️ Build success in 5156ms
+DTS dist/index.d.ts 14.54 KB

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @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
+
+- [#182](https://github.com/cesr/poncho-ai/pull/182) [`5ca3615`](https://github.com/cesr/poncho-ai/commit/5ca361576cbe1a97e6315f550a58a302b4e70aca) Thanks [@cesr](https://github.com/cesr)! - Keep host viewport listeners alive across browser sessions. `onFrame` /
+  `onStatus` listeners were stored inside the per-conversation `ConversationTab`
+  object, so `closeTab` (and LRU eviction) deleted them along with the tab. When
+  an agent closed one browser and opened another in the same conversation, the
+  new tab had empty listener sets — the host's live-viewport subscription was
+  silently orphaned, so the second session's `browser:status` / frames never
+  reached the client until it reconnected (the "pill/sheet doesn't appear, or is
+  left over after close, until I navigate away and back" bug). Listeners now live
+  in session-level maps keyed by conversationId, independent of any tab's
+  lifetime; they persist until the host unsubscribes, and `emitStatus` delivers
+  the final `active:false` on close before the tab is removed.
+
 ## 0.6.25
 
 ### Patch Changes

package/dist/index.d.ts

@@ -80,6 +80,8 @@ declare class BrowserSession {
     private readonly sessionId;
     private manager;
     private readonly tabs;
+    private readonly frameListeners;
+    private readonly statusListeners;
     private _contextStealthInstalled;
     private readonly _uaOverrideApplied;
     private _lockQueue;
@@ -142,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,12 +244,43 @@ 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;
   manager;
   // Tab management: conversationId → tab state
   tabs = /* @__PURE__ */ new Map();
+  // Viewport listeners, keyed by conversationId and kept SEPARATE from the
+  // tab. A host (e.g. a live iOS viewport) subscribes once; its listeners must
+  // outlive any individual tab so that closing one browser and opening another
+  // in the same conversation — or an LRU tab eviction — doesn't silently
+  // orphan the subscription (the symptom: the second session's status/frames
+  // never reach the client until it reconnects). Tabs come and go; listeners
+  // persist until the host unsubscribes.
+  frameListeners = /* @__PURE__ */ new Map();
+  statusListeners = /* @__PURE__ */ new Map();
   // Whether context-level stealth init script has been installed
   _contextStealthInstalled = false;
   // Track which tabs have had per-page CDP UA override applied
@@ -549,13 +580,10 @@ var BrowserSession = class {
       if (realTabs > 0) {
         await mgr.newTab();
       }
-      const existing = tab;
       tab = {
         tabIndex: mgr.getActiveIndex(),
         active: true,
-        lastUsed: Date.now(),
-        frameListeners: existing?.frameListeners ?? /* @__PURE__ */ new Set(),
-        statusListeners: existing?.statusListeners ?? /* @__PURE__ */ new Set()
+        lastUsed: Date.now()
       };
       this.tabs.set(conversationId, tab);
     } else {
@@ -687,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 {
@@ -829,15 +906,15 @@ var BrowserSession = class {
         (frame) => {
           const cid = this._screencastConversation;
           if (!cid) return;
-          const t = this.tabs.get(cid);
-          if (!t) return;
+          const listeners = this.frameListeners.get(cid);
+          if (!listeners || listeners.size === 0) return;
           const browserFrame = {
             data: frame.data,
             width: frame.metadata.deviceWidth,
             height: frame.metadata.deviceHeight,
             timestamp: Date.now()
           };
-          for (const listener of t.frameListeners) {
+          for (const listener of listeners) {
             try {
               listener(browserFrame);
             } catch {
@@ -865,29 +942,37 @@ var BrowserSession = class {
   // Per-conversation event listeners
   // -----------------------------------------------------------------------
   onFrame(conversationId, listener) {
-    let tab = this.tabs.get(conversationId);
-    if (!tab) {
-      tab = { tabIndex: -1, active: false, lastUsed: Date.now(), frameListeners: /* @__PURE__ */ new Set(), statusListeners: /* @__PURE__ */ new Set() };
-      this.tabs.set(conversationId, tab);
+    let set = this.frameListeners.get(conversationId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.frameListeners.set(conversationId, set);
     }
-    tab.frameListeners.add(listener);
+    set.add(listener);
     return () => {
-      tab.frameListeners.delete(listener);
-      if (tab.frameListeners.size === 0 && this._screencastConversation === conversationId) {
-        this.stopScreencast().catch(() => {
-        });
+      const s = this.frameListeners.get(conversationId);
+      if (!s) return;
+      s.delete(listener);
+      if (s.size === 0) {
+        this.frameListeners.delete(conversationId);
+        if (this._screencastConversation === conversationId) {
+          this.stopScreencast().catch(() => {
+          });
+        }
       }
     };
   }
   onStatus(conversationId, listener) {
-    let tab = this.tabs.get(conversationId);
-    if (!tab) {
-      tab = { tabIndex: -1, active: false, lastUsed: Date.now(), frameListeners: /* @__PURE__ */ new Set(), statusListeners: /* @__PURE__ */ new Set() };
-      this.tabs.set(conversationId, tab);
+    let set = this.statusListeners.get(conversationId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.statusListeners.set(conversationId, set);
     }
-    tab.statusListeners.add(listener);
+    set.add(listener);
     return () => {
-      tab.statusListeners.delete(listener);
+      const s = this.statusListeners.get(conversationId);
+      if (!s) return;
+      s.delete(listener);
+      if (s.size === 0) this.statusListeners.delete(conversationId);
     };
   }
   // -----------------------------------------------------------------------
@@ -1087,8 +1172,9 @@ var BrowserSession = class {
       url: tab?.url,
       interactionAllowed: tab?.active ?? false
     };
-    if (tab) {
-      for (const listener of tab.statusListeners) {
+    const listeners = this.statusListeners.get(conversationId);
+    if (listeners) {
+      for (const listener of listeners) {
         try {
           listener(status);
         } catch {
@@ -1246,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.25",
+  "version": "0.7.0",
   "description": "Browser automation for Poncho agents, powered by agent-browser",
   "repository": {
     "type": "git",

package/src/session.ts

@@ -144,8 +144,29 @@ interface ConversationTab {
   url?: string;
   active: boolean;
   lastUsed: number;
-  frameListeners: Set<FrameListener>;
-  statusListeners: Set<StatusListener>;
+}
+
+/** 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 {
@@ -156,6 +177,16 @@ export class BrowserSession {
   // Tab management: conversationId → tab state
   private readonly tabs = new Map<string, ConversationTab>();
 
+  // Viewport listeners, keyed by conversationId and kept SEPARATE from the
+  // tab. A host (e.g. a live iOS viewport) subscribes once; its listeners must
+  // outlive any individual tab so that closing one browser and opening another
+  // in the same conversation — or an LRU tab eviction — doesn't silently
+  // orphan the subscription (the symptom: the second session's status/frames
+  // never reach the client until it reconnects). Tabs come and go; listeners
+  // persist until the host unsubscribes.
+  private readonly frameListeners = new Map<string, Set<FrameListener>>();
+  private readonly statusListeners = new Map<string, Set<StatusListener>>();
+
   // Whether context-level stealth init script has been installed
   private _contextStealthInstalled = false;
 
@@ -500,13 +531,10 @@ export class BrowserSession {
       if (realTabs > 0) {
         await mgr.newTab();
       }
-      const existing = tab;
       tab = {
         tabIndex: mgr.getActiveIndex(),
         active: true,
         lastUsed: Date.now(),
-        frameListeners: existing?.frameListeners ?? new Set(),
-        statusListeners: existing?.statusListeners ?? new Set(),
       };
       this.tabs.set(conversationId, tab);
     } else {
@@ -650,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 {
@@ -799,15 +887,15 @@ export class BrowserSession {
         (frame) => {
           const cid = this._screencastConversation;
           if (!cid) return;
-          const t = this.tabs.get(cid);
-          if (!t) return;
+          const listeners = this.frameListeners.get(cid);
+          if (!listeners || listeners.size === 0) return;
           const browserFrame: BrowserFrame = {
             data: frame.data,
             width: frame.metadata.deviceWidth,
             height: frame.metadata.deviceHeight,
             timestamp: Date.now(),
           };
-          for (const listener of t.frameListeners) {
+          for (const listener of listeners) {
             try { listener(browserFrame); } catch { /* */ }
           }
         },
@@ -835,28 +923,38 @@ export class BrowserSession {
   // -----------------------------------------------------------------------
 
   onFrame(conversationId: string, listener: FrameListener): () => void {
-    let tab = this.tabs.get(conversationId);
-    if (!tab) {
-      tab = { tabIndex: -1, active: false, lastUsed: Date.now(), frameListeners: new Set(), statusListeners: new Set() };
-      this.tabs.set(conversationId, tab);
+    let set = this.frameListeners.get(conversationId);
+    if (!set) {
+      set = new Set();
+      this.frameListeners.set(conversationId, set);
     }
-    tab.frameListeners.add(listener);
+    set.add(listener);
     return () => {
-      tab!.frameListeners.delete(listener);
-      if (tab!.frameListeners.size === 0 && this._screencastConversation === conversationId) {
-        this.stopScreencast().catch(() => {});
+      const s = this.frameListeners.get(conversationId);
+      if (!s) return;
+      s.delete(listener);
+      if (s.size === 0) {
+        this.frameListeners.delete(conversationId);
+        if (this._screencastConversation === conversationId) {
+          this.stopScreencast().catch(() => {});
+        }
       }
     };
   }
 
   onStatus(conversationId: string, listener: StatusListener): () => void {
-    let tab = this.tabs.get(conversationId);
-    if (!tab) {
-      tab = { tabIndex: -1, active: false, lastUsed: Date.now(), frameListeners: new Set(), statusListeners: new Set() };
-      this.tabs.set(conversationId, tab);
+    let set = this.statusListeners.get(conversationId);
+    if (!set) {
+      set = new Set();
+      this.statusListeners.set(conversationId, set);
     }
-    tab.statusListeners.add(listener);
-    return () => { tab!.statusListeners.delete(listener); };
+    set.add(listener);
+    return () => {
+      const s = this.statusListeners.get(conversationId);
+      if (!s) return;
+      s.delete(listener);
+      if (s.size === 0) this.statusListeners.delete(conversationId);
+    };
   }
 
   // -----------------------------------------------------------------------
@@ -1068,8 +1166,12 @@ export class BrowserSession {
       url: tab?.url,
       interactionAllowed: tab?.active ?? false,
     };
-    if (tab) {
-      for (const listener of tab.statusListeners) {
+    // Listeners live at the session level, so a close (which deletes the tab)
+    // still delivers the final active:false to the host before the tab is
+    // gone — and a later reopen reuses the same subscription.
+    const listeners = this.statusListeners.get(conversationId);
+    if (listeners) {
+      for (const listener of listeners) {
         try { listener(status); } catch { /* */ }
       }
     }

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: