@poncho-ai/browser 0.5.0 → 0.6.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/browser@0.4.0 build /Users/cesar/Dev/latitude/poncho-ai/packages/browser
+> @poncho-ai/browser@0.6.1 build /Users/cesar/Dev/latitude/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 34.91 KB
-ESM ⚡️ Build success in 218ms
+ESM dist/index.js 41.37 KB
+ESM ⚡️ Build success in 83ms
 DTS Build start
-DTS ⚡️ Build success in 5616ms
-DTS dist/index.d.ts 12.44 KB
+DTS ⚡️ Build success in 1112ms
+DTS dist/index.d.ts 13.59 KB

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @poncho-ai/browser
 
+## 0.6.1
+
+### Patch Changes
+
+- Pass `@sparticuz/chromium` recommended args (--no-sandbox, --disable-gpu, etc.) when launching on serverless platforms. Fixes Chromium sandbox crash on Vercel/Lambda.
+
+## 0.6.0
+
+### Minor Changes
+
+- [`76294e9`](https://github.com/cesr/poncho-ai/commit/76294e95035bf3abbb19c28871a33f82351c49ec) Thanks [@cesr](https://github.com/cesr)! - Support remote and serverless browser deployments.
+
+  **@poncho-ai/browser**: Add `provider` and `cdpUrl` config options for cloud browser services (Browserbase, Browser Use, Kernel) and direct CDP connections. Auto-detect `@sparticuz/chromium` on serverless platforms (Vercel, Lambda) and default the profile directory to `/tmp`.
+
+  **@poncho-ai/cli**: Generate @vercel/nft trace hints for `@poncho-ai/browser` and `@sparticuz/chromium` in the Vercel entry point so dynamically-loaded browser packages are bundled into the serverless function.
+
 ## 0.5.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -64,6 +64,13 @@ interface BrowserConfig {
      *  user-agent, and passes anti-automation Chrome flags. */
     stealth?: boolean;
     storagePersistence?: BrowserStoragePersistence;
+    /** Cloud browser provider. Requires the provider's API key env var to be set
+     *  (e.g. `BROWSERBASE_API_KEY` + `BROWSERBASE_PROJECT_ID` for Browserbase).
+     *  When set, the browser runs remotely instead of launching a local Chromium. */
+    provider?: "browserbase" | "browseruse" | "kernel";
+    /** Connect to an existing browser via Chrome DevTools Protocol URL or port.
+     *  Mutually exclusive with `provider`. */
+    cdpUrl?: string;
 }
 
 type FrameListener = (frame: BrowserFrame) => void;
@@ -101,6 +108,14 @@ declare class BrowserSession {
      * CDP Network.setUserAgentOverride is per-target, so call per-tab.
      */
     private overrideUserAgentOnPage;
+    private get isRemote();
+    private get isServerless();
+    /**
+     * Resolve executablePath and launch args for serverless platforms.
+     * When `@sparticuz/chromium` is installed, uses its executable and
+     * recommended args (--no-sandbox, --disable-gpu, etc.).
+     */
+    private resolveServerlessChromium;
     private launchFreshManager;
     private ensureManager;
     private evictOldestTab;

package/dist/index.js

@@ -338,26 +338,76 @@ var BrowserSession = class {
       console.warn("[poncho][browser] Failed to override UA via CDP:", err?.message ?? err);
     }
   }
+  get isRemote() {
+    return !!(this.config.provider || this.config.cdpUrl);
+  }
+  get isServerless() {
+    return !!(process.env.VERCEL || process.env.AWS_LAMBDA_FUNCTION_NAME || process.env.AWS_EXECUTION_ENV || process.env.SERVERLESS);
+  }
+  /**
+   * Resolve executablePath and launch args for serverless platforms.
+   * When `@sparticuz/chromium` is installed, uses its executable and
+   * recommended args (--no-sandbox, --disable-gpu, etc.).
+   */
+  async resolveServerlessChromium() {
+    if (this.config.executablePath) return { executablePath: this.config.executablePath };
+    if (!this.isServerless) return {};
+    try {
+      const spec = ["@sparticuz", "chromium"].join("/");
+      const mod = await import(
+        /* webpackIgnore: true */
+        spec
+      );
+      const chromium = mod.default ?? mod;
+      const executablePath = await chromium.executablePath();
+      const args = Array.isArray(chromium.args) ? chromium.args : [];
+      console.log(`[poncho][browser] Auto-detected @sparticuz/chromium: ${executablePath} (${args.length} args)`);
+      return { executablePath, args };
+    } catch {
+      return {};
+    }
+  }
   async launchFreshManager() {
     const Ctor = await getBrowserManagerCtor();
     const mgr = new Ctor();
     const viewport = this.config.viewport ?? { width: 1280, height: 720 };
-    await mkdir(this.profileDir, { recursive: true });
+    const serverless = await this.resolveServerlessChromium();
     const launchOpts = {
       action: "launch",
       headless: this.config.headless ?? true,
       viewport: { width: viewport.width ?? 1280, height: viewport.height ?? 720 },
-      executablePath: this.config.executablePath,
-      profile: this.profileDir
+      executablePath: serverless.executablePath
     };
+    if (this.config.cdpUrl) {
+      launchOpts.cdpUrl = this.config.cdpUrl;
+      console.log(`[poncho][browser] Connecting via CDP: ${this.config.cdpUrl}`);
+    } else if (this.config.provider) {
+      launchOpts.provider = this.config.provider;
+      console.log(`[poncho][browser] Using cloud provider: ${this.config.provider}`);
+    } else {
+      const profileDir = this.isServerless && !this.config.profileDir ? join(tmpdir(), "poncho-browser", this.sessionId) : this.profileDir;
+      await mkdir(profileDir, { recursive: true });
+      launchOpts.profile = profileDir;
+    }
+    const baseArgs = serverless.args ?? [];
     if (this.stealthEnabled) {
       const ua = this.stealthUserAgent;
       launchOpts.userAgent = ua;
-      launchOpts.args = buildStealthArgs(ua);
+      if (!this.isRemote) {
+        const stealthArgs = buildStealthArgs(ua);
+        const merged = [...baseArgs];
+        for (const arg of stealthArgs) {
+          if (!merged.includes(arg)) merged.push(arg);
+        }
+        launchOpts.args = merged;
+      }
       console.log("[poncho][browser] Launching with stealth mode enabled (UA: " + ua + ")");
     } else if (this.config.userAgent) {
       launchOpts.userAgent = this.config.userAgent;
     }
+    if (!launchOpts.args && baseArgs.length > 0) {
+      launchOpts.args = baseArgs;
+    }
     await mgr.launch(launchOpts);
     this._contextStealthInstalled = false;
     this._uaOverrideApplied.clear();

package/package.json

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

package/src/session.ts

@@ -244,30 +244,94 @@ export class BrowserSession {
     }
   }
 
+  private get isRemote(): boolean {
+    return !!(this.config.provider || this.config.cdpUrl);
+  }
+
+  private get isServerless(): boolean {
+    return !!(
+      process.env.VERCEL ||
+      process.env.AWS_LAMBDA_FUNCTION_NAME ||
+      process.env.AWS_EXECUTION_ENV ||
+      process.env.SERVERLESS
+    );
+  }
+
+  /**
+   * Resolve executablePath and launch args for serverless platforms.
+   * When `@sparticuz/chromium` is installed, uses its executable and
+   * recommended args (--no-sandbox, --disable-gpu, etc.).
+   */
+  private async resolveServerlessChromium(): Promise<{
+    executablePath?: string;
+    args?: string[];
+  }> {
+    if (this.config.executablePath) return { executablePath: this.config.executablePath };
+    if (!this.isServerless) return {};
+    try {
+      const spec = ["@sparticuz", "chromium"].join("/");
+      const mod = await import(/* webpackIgnore: true */ spec);
+      const chromium = mod.default ?? mod;
+      const executablePath = await chromium.executablePath();
+      const args: string[] = Array.isArray(chromium.args) ? chromium.args : [];
+      console.log(`[poncho][browser] Auto-detected @sparticuz/chromium: ${executablePath} (${args.length} args)`);
+      return { executablePath, args };
+    } catch {
+      return {};
+    }
+  }
+
   private async launchFreshManager(): Promise<BrowserManagerInstance> {
     const Ctor = await getBrowserManagerCtor();
     const mgr = new Ctor();
 
     const viewport = this.config.viewport ?? { width: 1280, height: 720 };
-    await mkdir(this.profileDir, { recursive: true });
+    const serverless = await this.resolveServerlessChromium();
 
     const launchOpts: Record<string, unknown> = {
       action: "launch",
       headless: this.config.headless ?? true,
       viewport: { width: viewport.width ?? 1280, height: viewport.height ?? 720 },
-      executablePath: this.config.executablePath,
-      profile: this.profileDir,
+      executablePath: serverless.executablePath,
     };
 
+    if (this.config.cdpUrl) {
+      launchOpts.cdpUrl = this.config.cdpUrl;
+      console.log(`[poncho][browser] Connecting via CDP: ${this.config.cdpUrl}`);
+    } else if (this.config.provider) {
+      launchOpts.provider = this.config.provider;
+      console.log(`[poncho][browser] Using cloud provider: ${this.config.provider}`);
+    } else {
+      const profileDir = this.isServerless && !this.config.profileDir
+        ? join(tmpdir(), "poncho-browser", this.sessionId)
+        : this.profileDir;
+      await mkdir(profileDir, { recursive: true });
+      launchOpts.profile = profileDir;
+    }
+
+    // Merge args: serverless chromium args (--no-sandbox etc.) + stealth args
+    const baseArgs: string[] = serverless.args ?? [];
+
     if (this.stealthEnabled) {
       const ua = this.stealthUserAgent!;
       launchOpts.userAgent = ua;
-      launchOpts.args = buildStealthArgs(ua);
+      if (!this.isRemote) {
+        const stealthArgs = buildStealthArgs(ua);
+        const merged = [...baseArgs];
+        for (const arg of stealthArgs) {
+          if (!merged.includes(arg)) merged.push(arg);
+        }
+        launchOpts.args = merged;
+      }
       console.log("[poncho][browser] Launching with stealth mode enabled (UA: " + ua + ")");
     } else if (this.config.userAgent) {
       launchOpts.userAgent = this.config.userAgent;
     }
 
+    if (!launchOpts.args && baseArgs.length > 0) {
+      launchOpts.args = baseArgs;
+    }
+
     await mgr.launch(launchOpts as Parameters<BrowserManagerInstance["launch"]>[0]);
 
     // Reset stealth tracking for fresh browser

package/src/types.ts

@@ -70,4 +70,11 @@ export interface BrowserConfig {
    *  user-agent, and passes anti-automation Chrome flags. */
   stealth?: boolean;
   storagePersistence?: BrowserStoragePersistence;
+  /** Cloud browser provider. Requires the provider's API key env var to be set
+   *  (e.g. `BROWSERBASE_API_KEY` + `BROWSERBASE_PROJECT_ID` for Browserbase).
+   *  When set, the browser runs remotely instead of launching a local Chromium. */
+  provider?: "browserbase" | "browseruse" | "kernel";
+  /** Connect to an existing browser via Chrome DevTools Protocol URL or port.
+   *  Mutually exclusive with `provider`. */
+  cdpUrl?: string;
 }