@poncho-ai/browser 0.6.26 → 0.7.1

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.1 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 57.26 KB
+ESM ⚡️ Build success in 77ms
 DTS Build start
-DTS ⚡️ Build success in 4894ms
-DTS dist/index.d.ts 13.77 KB
+DTS ⚡️ Build success in 5467ms
+DTS dist/index.d.ts 15.75 KB

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @poncho-ai/browser
 
+## 0.7.1
+
+### Patch Changes
+
+- [#188](https://github.com/cesr/poncho-ai/pull/188) [`97772cc`](https://github.com/cesr/poncho-ai/commit/97772ccf2c07ec3a3f3350ef3a65596fba91a154) Thanks [@cesr](https://github.com/cesr)! - Add residential-proxy support for Browserbase sessions so IP-reputation walls
+  (Reddit, LinkedIn, Instagram, …) stop returning 403 "blocked by network
+  security". Datacenter IPs are blocked before any fingerprint check, so stealth
+  alone can't get past them.
+  - Known IP-blocking domains are proxied automatically (domain gate).
+  - `browser_open` gains a `proxy` param so the agent can retry any other site
+    that blocked it through a residential IP.
+  - `BrowserConfig.proxies` sets the default mode for every session.
+
+  Because proxies are fixed at Browserbase-session creation (and Vercel's
+  agent-browser hardcodes the create body to `{ projectId }`), we create the
+  Browserbase session ourselves with `proxies: true` and connect agent-browser to
+  it via its `cdpUrl` path. Switching proxy mode mid-conversation recreates the
+  session; cookies/localStorage are persisted and restored across the recreate,
+  so login state survives.
+
+## 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

@@ -71,6 +71,12 @@ interface BrowserConfig {
     /** Connect to an existing browser via Chrome DevTools Protocol URL or port.
      *  Mutually exclusive with `provider`. */
     cdpUrl?: string;
+    /** Default residential-proxy mode for Browserbase sessions. Datacenter IPs are
+     *  hard-blocked (403) by IP-reputation walls (Reddit, LinkedIn, …) before any
+     *  fingerprint check. Known such domains are always proxied automatically, and
+     *  `browser_open` can force it per-navigation; set this `true` to proxy every
+     *  session by default. Billed per GB by Browserbase. Browserbase provider only. */
+    proxies?: boolean;
 }
 
 type FrameListener = (frame: BrowserFrame) => void;
@@ -87,6 +93,8 @@ declare class BrowserSession {
     private _lockQueue;
     private _locked;
     private _screencastConversation;
+    private launchedProxyMode;
+    private proxyEnabled;
     constructor(sessionId: string, config?: BrowserConfig);
     get profileDir(): string;
     private lock;
@@ -131,9 +139,22 @@ declare class BrowserSession {
     getUrl(conversationId: string): string | undefined;
     /** Whether the browser has been launched. */
     get isLaunched(): boolean;
-    open(conversationId: string, url: string): Promise<{
+    open(conversationId: string, url: string, opts?: {
+        proxy?: boolean;
+    }): Promise<{
         title?: string;
     }>;
+    /**
+     * Reconcile the residential-proxy mode before a navigation. The desired mode
+     * is: an explicit `requested` (the agent's `browser_open` proxy param) OR the
+     * URL hitting a known IP-blocking domain OR the config default. Since proxies
+     * are fixed at Browserbase-session creation, a change tears the live session
+     * down so the next ensureManager relaunches proxied. Cookies/localStorage are
+     * persisted first and restored on relaunch, so login state survives; open
+     * tabs in other conversations of the same session are lost (rare, and only
+     * when the mode actually flips). No-op unless the provider is browserbase.
+     */
+    private ensureProxyMode;
     private _doOpen;
     snapshot(conversationId: string): Promise<string>;
     click(conversationId: string, ref: string): Promise<void>;
@@ -144,6 +165,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

@@ -186,6 +186,49 @@ async function getBrowserManagerCtor() {
   return BrowserManagerCtor;
 }
 var MAX_TABS = 8;
+var PROXY_DOMAINS = [
+  "reddit.com",
+  "linkedin.com",
+  "instagram.com",
+  "facebook.com",
+  "x.com",
+  "twitter.com",
+  "tiktok.com",
+  "quora.com",
+  "pinterest.com"
+];
+function shouldProxyFor(url) {
+  let host;
+  try {
+    host = new URL(url).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  return PROXY_DOMAINS.some((d) => host === d || host.endsWith(`.${d}`));
+}
+async function createBrowserbaseProxiedSession() {
+  const apiKey = process.env.BROWSERBASE_API_KEY;
+  const projectId = process.env.BROWSERBASE_PROJECT_ID;
+  if (!apiKey || !projectId) {
+    throw new Error(
+      "BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are required when using browserbase"
+    );
+  }
+  const res = await fetch("https://api.browserbase.com/v1/sessions", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-BB-API-Key": apiKey },
+    body: JSON.stringify({ projectId, proxies: true })
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`Failed to create Browserbase session: ${res.status} ${detail}`);
+  }
+  const session = await res.json();
+  if (!session.connectUrl) {
+    throw new Error("Browserbase session response missing connectUrl");
+  }
+  return session.connectUrl;
+}
 var VALID_SAME_SITE = ["Strict", "Lax", "None"];
 function sanitizeCookieForCDP(c) {
   const name = typeof c.name === "string" ? c.name : "";
@@ -244,6 +287,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;
@@ -268,6 +333,14 @@ var BrowserSession = class {
   _locked = false;
   // Currently screencast conversation (only one at a time due to CDP)
   _screencastConversation;
+  // Residential-proxy mode. `launchedProxyMode` is what the currently-launched
+  // remote session was created with; `proxyEnabled` is the mode the NEXT launch
+  // should use. They diverge when a navigation asks for a different mode (a
+  // hard-domain gate hit, or an explicit `proxy` on browser_open) — proxies are
+  // fixed at Browserbase-session creation, so switching means recreating the
+  // session (see ensureProxyMode). Only meaningful for the browserbase provider.
+  launchedProxyMode = false;
+  proxyEnabled = false;
   constructor(sessionId, config = {}) {
     this.sessionId = sessionId;
     this.config = config;
@@ -420,6 +493,9 @@ var BrowserSession = class {
     if (this.config.cdpUrl) {
       launchOpts.cdpUrl = this.config.cdpUrl;
       console.log(`[poncho][browser] Connecting via CDP: ${this.config.cdpUrl}`);
+    } else if (this.config.provider === "browserbase" && this.proxyEnabled) {
+      launchOpts.cdpUrl = await createBrowserbaseProxiedSession();
+      console.log("[poncho][browser] Using cloud provider: browserbase (residential proxies)");
     } else if (this.config.provider) {
       launchOpts.provider = this.config.provider;
       console.log(`[poncho][browser] Using cloud provider: ${this.config.provider}`);
@@ -448,6 +524,7 @@ var BrowserSession = class {
       launchOpts.args = baseArgs;
     }
     await mgr.launch(launchOpts);
+    this.launchedProxyMode = this.config.provider === "browserbase" && this.proxyEnabled;
     if (this.isRemote) {
       try {
         await mgr.setViewport(viewport.width ?? 1280, viewport.height ?? 720);
@@ -587,9 +664,10 @@ var BrowserSession = class {
   // -----------------------------------------------------------------------
   // Browser operations (all scoped by conversationId)
   // -----------------------------------------------------------------------
-  async open(conversationId, url) {
+  async open(conversationId, url, opts) {
     await this.lock();
     try {
+      await this.ensureProxyMode(url, opts?.proxy);
       return await this._doOpen(conversationId, url);
     } catch (err) {
       const msg = err?.message ?? "";
@@ -616,6 +694,41 @@ var BrowserSession = class {
       this.unlock();
     }
   }
+  /**
+   * Reconcile the residential-proxy mode before a navigation. The desired mode
+   * is: an explicit `requested` (the agent's `browser_open` proxy param) OR the
+   * URL hitting a known IP-blocking domain OR the config default. Since proxies
+   * are fixed at Browserbase-session creation, a change tears the live session
+   * down so the next ensureManager relaunches proxied. Cookies/localStorage are
+   * persisted first and restored on relaunch, so login state survives; open
+   * tabs in other conversations of the same session are lost (rare, and only
+   * when the mode actually flips). No-op unless the provider is browserbase.
+   */
+  async ensureProxyMode(url, requested) {
+    if (this.config.provider !== "browserbase") return;
+    const want = requested === true || shouldProxyFor(url) || (this.config.proxies ?? false);
+    this.proxyEnabled = want;
+    if (!this.manager || want === this.launchedProxyMode) return;
+    console.log(`[poncho][browser] Switching proxy mode -> ${want}; recreating session`);
+    try {
+      await this.persistStorageState();
+    } catch {
+    }
+    try {
+      await this.manager.close();
+    } catch {
+    }
+    this.manager = void 0;
+    this._contextStealthInstalled = false;
+    this._uaOverrideApplied.clear();
+    for (const [, t] of this.tabs) {
+      if (t.tabIndex >= 0) {
+        t.tabIndex = -1;
+        t.active = false;
+        t.url = void 0;
+      }
+    }
+  }
   async _doOpen(conversationId, url) {
     const mgr = await this.ensureManager();
     const tab = await this.switchToConversation(mgr, conversationId);
@@ -693,6 +806,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 {
@@ -1118,13 +1280,17 @@ function createBrowserTools(getSession) {
   return [
     {
       name: "browser_open",
-      description: "Open a URL in a real browser whose live view the user can watch and interact with. Returns the page title. This is a HEAVY, last-resort tool \u2014 prefer cheaper options first: use `web_fetch` to read page content, and use a dedicated API or MCP integration when one exists for the service. Only reach for the browser when those can't do the job: a page `web_fetch` can't render (JS-heavy/SPA), or a task that requires operating a site or web app that has no API and no MCP integration (e.g. logging in and clicking through a UI). When a site needs credentials, navigate to its login page and let the user sign in directly in the live view \u2014 never ask for passwords in chat. To open files from the virtual filesystem, use /api/vfs/{path} (e.g. /api/vfs/downloads/report.pdf).",
+      description: "Open a URL in a real browser whose live view the user can watch and interact with. Returns the page title. This is a HEAVY, last-resort tool \u2014 prefer cheaper options first: use `web_fetch` to read page content, and use a dedicated API or MCP integration when one exists for the service. Only reach for the browser when those can't do the job: a page `web_fetch` can't render (JS-heavy/SPA), or a task that requires operating a site or web app that has no API and no MCP integration (e.g. logging in and clicking through a UI). When a site needs credentials, navigate to its login page and let the user sign in directly in the live view \u2014 never ask for passwords in chat. If a page returns a 403 / 'blocked by network security' / 'access denied' (common on Reddit, LinkedIn, Instagram, and similar), retry with `proxy: true` to route through a residential IP. To open files from the virtual filesystem, use /api/vfs/{path} (e.g. /api/vfs/downloads/report.pdf).",
       inputSchema: {
         type: "object",
         properties: {
           url: {
             type: "string",
             description: "The URL to navigate to (must include protocol, e.g. https://)"
+          },
+          proxy: {
+            type: "boolean",
+            description: "Route this session through a residential proxy instead of a datacenter IP. Known IP-blocking sites (Reddit, LinkedIn, \u2026) use this automatically; set it explicitly to retry a site that blocked you with a 403/'blocked' page. Slower to start (the session is recreated) and costs proxy bandwidth, so only use it when a normal open was blocked."
           }
         },
         required: ["url"]
@@ -1134,7 +1300,8 @@ function createBrowserTools(getSession) {
         const cid = context.conversationId ?? "__default__";
         const url = String(input.url ?? "");
         if (!url) throw new Error("url is required");
-        const result = await session.open(cid, url);
+        const proxy = input.proxy === true;
+        const result = await session.open(cid, url, { proxy });
         session.startScreencast(cid).catch((err) => {
           console.error("[poncho][browser] startScreencast failed:", err?.message ?? err);
         });
@@ -1261,6 +1428,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.1",
   "description": "Browser automation for Poncho agents, powered by agent-browser",
   "repository": {
     "type": "git",

package/src/session.ts

@@ -62,6 +62,64 @@ async function getBrowserManagerCtor(): Promise<new () => BrowserManagerInstance
 
 const MAX_TABS = 8;
 
+/**
+ * Sites that hard-block datacenter IPs (a 403 / "blocked by network security"
+ * before any fingerprint check). Navigating to one auto-enables residential
+ * proxies. Matched on the registrable-ish suffix so subdomains
+ * (old.reddit.com, www.linkedin.com) are covered. The agent can also force
+ * proxies on for anything else via `browser_open`'s `proxy` param.
+ */
+const PROXY_DOMAINS = [
+  "reddit.com",
+  "linkedin.com",
+  "instagram.com",
+  "facebook.com",
+  "x.com",
+  "twitter.com",
+  "tiktok.com",
+  "quora.com",
+  "pinterest.com",
+];
+
+/** Whether a URL's host is (a subdomain of) a known IP-blocking domain. */
+function shouldProxyFor(url: string): boolean {
+  let host: string;
+  try { host = new URL(url).hostname.toLowerCase(); }
+  catch { return false; }
+  return PROXY_DOMAINS.some((d) => host === d || host.endsWith(`.${d}`));
+}
+
+/**
+ * Create a Browserbase session with residential proxies enabled and return its
+ * CDP `connectUrl`. Used instead of agent-browser's built-in browserbase path,
+ * which hardcodes the create body to `{ projectId }` and so can't turn proxies
+ * on. Reads the same `BROWSERBASE_API_KEY` / `BROWSERBASE_PROJECT_ID` env vars
+ * agent-browser does.
+ */
+async function createBrowserbaseProxiedSession(): Promise<string> {
+  const apiKey = process.env.BROWSERBASE_API_KEY;
+  const projectId = process.env.BROWSERBASE_PROJECT_ID;
+  if (!apiKey || !projectId) {
+    throw new Error(
+      "BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are required when using browserbase",
+    );
+  }
+  const res = await fetch("https://api.browserbase.com/v1/sessions", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-BB-API-Key": apiKey },
+    body: JSON.stringify({ projectId, proxies: true }),
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`Failed to create Browserbase session: ${res.status} ${detail}`);
+  }
+  const session = (await res.json()) as { connectUrl?: string };
+  if (!session.connectUrl) {
+    throw new Error("Browserbase session response missing connectUrl");
+  }
+  return session.connectUrl;
+}
+
 const VALID_SAME_SITE = ["Strict", "Lax", "None"];
 
 /**
@@ -146,6 +204,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;
@@ -177,6 +258,15 @@ export class BrowserSession {
   // Currently screencast conversation (only one at a time due to CDP)
   private _screencastConversation: string | undefined;
 
+  // Residential-proxy mode. `launchedProxyMode` is what the currently-launched
+  // remote session was created with; `proxyEnabled` is the mode the NEXT launch
+  // should use. They diverge when a navigation asks for a different mode (a
+  // hard-domain gate hit, or an explicit `proxy` on browser_open) — proxies are
+  // fixed at Browserbase-session creation, so switching means recreating the
+  // session (see ensureProxyMode). Only meaningful for the browserbase provider.
+  private launchedProxyMode = false;
+  private proxyEnabled = false;
+
   constructor(sessionId: string, config: BrowserConfig = {}) {
     this.sessionId = sessionId;
     this.config = config;
@@ -356,6 +446,16 @@ export class BrowserSession {
     if (this.config.cdpUrl) {
       launchOpts.cdpUrl = this.config.cdpUrl;
       console.log(`[poncho][browser] Connecting via CDP: ${this.config.cdpUrl}`);
+    } else if (this.config.provider === "browserbase" && this.proxyEnabled) {
+      // agent-browser's browserbase path creates the session with only
+      // { projectId } — no proxy option — so it always lands on a datacenter IP
+      // that sites like Reddit block with a 403 before any fingerprint check.
+      // Create the session ourselves with residential proxies enabled and hand
+      // agent-browser the connectUrl via its cdpUrl path, which bypasses
+      // connectToBrowserbase. Stealth, cookie restore, and the screencast are
+      // applied below on the connected context, unchanged.
+      launchOpts.cdpUrl = await createBrowserbaseProxiedSession();
+      console.log("[poncho][browser] Using cloud provider: browserbase (residential proxies)");
     } else if (this.config.provider) {
       launchOpts.provider = this.config.provider;
       console.log(`[poncho][browser] Using cloud provider: ${this.config.provider}`);
@@ -391,6 +491,9 @@ export class BrowserSession {
     }
 
     await mgr.launch(launchOpts as Parameters<BrowserManagerInstance["launch"]>[0]);
+    // Record the proxy mode this session was actually launched with, so
+    // ensureProxyMode knows whether a later navigation needs a recreate.
+    this.launchedProxyMode = this.config.provider === "browserbase" && this.proxyEnabled;
 
     // Remote browsers (cloud provider / cdpUrl) ignore launchOpts.viewport —
     // that's only applied when launching a local context — so the page renders
@@ -542,9 +645,14 @@ export class BrowserSession {
   // Browser operations (all scoped by conversationId)
   // -----------------------------------------------------------------------
 
-  async open(conversationId: string, url: string): Promise<{ title?: string }> {
+  async open(
+    conversationId: string,
+    url: string,
+    opts?: { proxy?: boolean },
+  ): Promise<{ title?: string }> {
     await this.lock();
     try {
+      await this.ensureProxyMode(url, opts?.proxy);
       return await this._doOpen(conversationId, url);
     } catch (err: unknown) {
       const msg = (err as Error)?.message ?? "";
@@ -565,6 +673,33 @@ export class BrowserSession {
     }
   }
 
+  /**
+   * Reconcile the residential-proxy mode before a navigation. The desired mode
+   * is: an explicit `requested` (the agent's `browser_open` proxy param) OR the
+   * URL hitting a known IP-blocking domain OR the config default. Since proxies
+   * are fixed at Browserbase-session creation, a change tears the live session
+   * down so the next ensureManager relaunches proxied. Cookies/localStorage are
+   * persisted first and restored on relaunch, so login state survives; open
+   * tabs in other conversations of the same session are lost (rare, and only
+   * when the mode actually flips). No-op unless the provider is browserbase.
+   */
+  private async ensureProxyMode(url: string, requested?: boolean): Promise<void> {
+    if (this.config.provider !== "browserbase") return;
+    const want =
+      requested === true || shouldProxyFor(url) || (this.config.proxies ?? false);
+    this.proxyEnabled = want;
+    if (!this.manager || want === this.launchedProxyMode) return;
+    console.log(`[poncho][browser] Switching proxy mode -> ${want}; recreating session`);
+    try { await this.persistStorageState(); } catch { /* best-effort */ }
+    try { await this.manager.close(); } catch { /* */ }
+    this.manager = undefined;
+    this._contextStealthInstalled = false;
+    this._uaOverrideApplied.clear();
+    for (const [, t] of this.tabs) {
+      if (t.tabIndex >= 0) { t.tabIndex = -1; t.active = false; t.url = undefined; }
+    }
+  }
+
   private async _doOpen(conversationId: string, url: string): Promise<{ title?: string }> {
     const mgr = await this.ensureManager();
     const tab = await this.switchToConversation(mgr, conversationId);
@@ -655,6 +790,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

@@ -14,6 +14,7 @@ export function createBrowserTools(
         "This is a HEAVY, last-resort tool — prefer cheaper options first: use `web_fetch` to read page content, and use a dedicated API or MCP integration when one exists for the service. " +
         "Only reach for the browser when those can't do the job: a page `web_fetch` can't render (JS-heavy/SPA), or a task that requires operating a site or web app that has no API and no MCP integration (e.g. logging in and clicking through a UI). " +
         "When a site needs credentials, navigate to its login page and let the user sign in directly in the live view — never ask for passwords in chat. " +
+        "If a page returns a 403 / 'blocked by network security' / 'access denied' (common on Reddit, LinkedIn, Instagram, and similar), retry with `proxy: true` to route through a residential IP. " +
         "To open files from the virtual filesystem, use /api/vfs/{path} (e.g. /api/vfs/downloads/report.pdf).",
       inputSchema: {
         type: "object",
@@ -22,6 +23,11 @@ export function createBrowserTools(
             type: "string",
             description: "The URL to navigate to (must include protocol, e.g. https://)",
           },
+          proxy: {
+            type: "boolean",
+            description:
+              "Route this session through a residential proxy instead of a datacenter IP. Known IP-blocking sites (Reddit, LinkedIn, …) use this automatically; set it explicitly to retry a site that blocked you with a 403/'blocked' page. Slower to start (the session is recreated) and costs proxy bandwidth, so only use it when a normal open was blocked.",
+          },
         },
         required: ["url"],
       },
@@ -30,7 +36,8 @@ export function createBrowserTools(
         const cid = context.conversationId ?? "__default__";
         const url = String(input.url ?? "");
         if (!url) throw new Error("url is required");
-        const result = await session.open(cid, url);
+        const proxy = input.proxy === true;
+        const result = await session.open(cid, url, { proxy });
         session.startScreencast(cid).catch((err) => {
           console.error("[poncho][browser] startScreencast failed:", err?.message ?? err);
         });
@@ -176,6 +183,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:

package/src/types.ts

@@ -77,4 +77,10 @@ export interface BrowserConfig {
   /** Connect to an existing browser via Chrome DevTools Protocol URL or port.
    *  Mutually exclusive with `provider`. */
   cdpUrl?: string;
+  /** Default residential-proxy mode for Browserbase sessions. Datacenter IPs are
+   *  hard-blocked (403) by IP-reputation walls (Reddit, LinkedIn, …) before any
+   *  fingerprint check. Known such domains are always proxied automatically, and
+   *  `browser_open` can force it per-navigation; set this `true` to proxy every
+   *  session by default. Billed per GB by Browserbase. Browserbase provider only. */
+  proxies?: boolean;
 }