@poncho-ai/browser 0.5.0 → 0.6.0

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.0 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 40.85 KB
+ESM ⚡️ Build success in 76ms
 DTS Build start
-DTS ⚡️ Build success in 5616ms
-DTS dist/index.d.ts 12.44 KB
+DTS ⚡️ Build success in 1346ms
+DTS dist/index.d.ts 13.55 KB

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @poncho-ai/browser
 
+## 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,13 @@ declare class BrowserSession {
      * CDP Network.setUserAgentOverride is per-target, so call per-tab.
      */
     private overrideUserAgentOnPage;
+    private get isRemote();
+    private get isServerless();
+    /**
+     * Resolve executablePath for local launches. When no explicit path is set
+     * and we're on a serverless platform, try `@sparticuz/chromium` automatically.
+     */
+    private resolveExecutablePath;
     private launchFreshManager;
     private ensureManager;
     private evictOldestTab;

package/dist/index.js

@@ -338,22 +338,61 @@ 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 for local launches. When no explicit path is set
+   * and we're on a serverless platform, try `@sparticuz/chromium` automatically.
+   */
+  async resolveExecutablePath() {
+    if (this.config.executablePath) return this.config.executablePath;
+    if (!this.isServerless) return void 0;
+    try {
+      const spec = ["@sparticuz", "chromium"].join("/");
+      const mod = await import(
+        /* webpackIgnore: true */
+        spec
+      );
+      const chromium = mod.default ?? mod;
+      const path = await chromium.executablePath();
+      console.log(`[poncho][browser] Auto-detected @sparticuz/chromium: ${path}`);
+      return path;
+    } catch {
+      return void 0;
+    }
+  }
   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 executablePath = await this.resolveExecutablePath();
     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
     };
+    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;
+    }
     if (this.stealthEnabled) {
       const ua = this.stealthUserAgent;
       launchOpts.userAgent = ua;
-      launchOpts.args = buildStealthArgs(ua);
+      if (!this.isRemote) {
+        launchOpts.args = buildStealthArgs(ua);
+      }
       console.log("[poncho][browser] Launching with stealth mode enabled (UA: " + ua + ")");
     } else if (this.config.userAgent) {
       launchOpts.userAgent = this.config.userAgent;

package/package.json

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

package/src/session.ts

@@ -244,25 +244,74 @@ 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 for local launches. When no explicit path is set
+   * and we're on a serverless platform, try `@sparticuz/chromium` automatically.
+   */
+  private async resolveExecutablePath(): Promise<string | undefined> {
+    if (this.config.executablePath) return this.config.executablePath;
+    if (!this.isServerless) return undefined;
+    try {
+      // Dynamic require — @sparticuz/chromium is an optional peer dependency
+      // that the user installs in their agent project for serverless runtimes.
+      const spec = ["@sparticuz", "chromium"].join("/");
+      const mod = await import(/* webpackIgnore: true */ spec);
+      const chromium = mod.default ?? mod;
+      const path = await chromium.executablePath();
+      console.log(`[poncho][browser] Auto-detected @sparticuz/chromium: ${path}`);
+      return path;
+    } catch {
+      return undefined;
+    }
+  }
+
   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 executablePath = await this.resolveExecutablePath();
 
     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,
     };
 
+    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;
+    }
+
     if (this.stealthEnabled) {
       const ua = this.stealthUserAgent!;
       launchOpts.userAgent = ua;
-      launchOpts.args = buildStealthArgs(ua);
+      if (!this.isRemote) {
+        launchOpts.args = buildStealthArgs(ua);
+      }
       console.log("[poncho][browser] Launching with stealth mode enabled (UA: " + ua + ")");
     } else if (this.config.userAgent) {
       launchOpts.userAgent = this.config.userAgent;

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