@poncho-ai/browser 0.7.0 → 0.7.1

package/.turbo/turbo-build.log

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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @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

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>;

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 : "";
@@ -290,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;
@@ -442,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}`);
@@ -470,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);
@@ -609,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 ?? "";
@@ -638,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);
@@ -1189,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"]
@@ -1205,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);
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/browser",
-  "version": "0.7.0",
+  "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"];
 
 /**
@@ -200,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;
@@ -379,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}`);
@@ -414,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
@@ -565,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 ?? "";
@@ -588,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);

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

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