browse 0.11.0 → 0.11.1

package/dist/lib/driver/local-cdp-discovery.js

@@ -59,24 +59,6 @@ export async function readDevToolsActivePort(userDataDir) {
         return null;
     }
 }
-function isPortReachable(port, timeoutMs = 500) {
-    return new Promise((resolve) => {
-        const socket = net.createConnection({ host: "127.0.0.1", port });
-        const timer = setTimeout(() => {
-            socket.destroy();
-            resolve(false);
-        }, timeoutMs);
-        socket.on("connect", () => {
-            clearTimeout(timer);
-            socket.destroy();
-            resolve(true);
-        });
-        socket.on("error", () => {
-            clearTimeout(timer);
-            resolve(false);
-        });
-    });
-}
 async function probeJsonVersion(port) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), 2000);
@@ -97,6 +79,46 @@ async function probeJsonVersion(port) {
         clearTimeout(timer);
     }
 }
+/**
+ * Multiple candidates (several profile dirs, or a profile dir and a fallback
+ * port) can reference the same port within one discovery call. Memoize the
+ * live /json/version probe per port so that port is only actually hit once.
+ */
+function createJsonVersionProbe() {
+    const cache = new Map();
+    return (port) => {
+        let pending = cache.get(port);
+        if (!pending) {
+            pending = probeJsonVersion(port);
+            cache.set(port, pending);
+        }
+        return pending;
+    };
+}
+function wsPathname(wsUrl) {
+    try {
+        return new URL(wsUrl).pathname;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A DevToolsActivePort file only reflects the browser instance that wrote it.
+ * If a different process later binds the same port (a very likely collision,
+ * since 9222 is the near-universal default debugging port), the cached
+ * port+wsPath pair points at a target that no longer exists. Confirm the
+ * port's live /json/version still reports this exact target before trusting
+ * it. Compare pathnames only (not the full URL) since Chrome can report the
+ * host as "127.0.0.1" or "localhost" depending on version/platform.
+ */
+async function isDevToolsActivePortFresh(info, probe = probeJsonVersion) {
+    const liveWsUrl = await probe(info.port);
+    if (!liveWsUrl)
+        return false;
+    const expectedPathname = wsPathname(buildDevToolsWsUrl(info.port, info.wsPath));
+    return (expectedPathname !== null && wsPathname(liveWsUrl) === expectedPathname);
+}
 async function verifyCdpWebSocket(wsUrl) {
     return new Promise((resolve) => {
         const url = new URL(wsUrl);
@@ -135,12 +157,12 @@ async function verifyCdpWebSocket(wsUrl) {
         });
     });
 }
-async function resolveDevToolsActivePortUrl(port, userDataDirs) {
+async function resolveDevToolsActivePortUrl(port, userDataDirs, probe) {
     for (const dir of userDataDirs) {
         const info = await readDevToolsActivePort(dir);
         if (!info || info.port !== port)
             continue;
-        if (!(await isPortReachable(info.port)))
+        if (!(await isDevToolsActivePortFresh(info, probe)))
             continue;
         return buildDevToolsWsUrl(info.port, info.wsPath);
     }
@@ -148,10 +170,11 @@ async function resolveDevToolsActivePortUrl(port, userDataDirs) {
 }
 export async function resolveWsTargetFromPort(port, options = {}) {
     const userDataDirs = options.userDataDirs ?? getChromeUserDataDirs();
-    const devToolsUrl = await resolveDevToolsActivePortUrl(port, userDataDirs);
+    const probe = createJsonVersionProbe();
+    const devToolsUrl = await resolveDevToolsActivePortUrl(port, userDataDirs, probe);
     if (devToolsUrl)
         return devToolsUrl;
-    const jsonVersionUrl = await probeJsonVersion(port);
+    const jsonVersionUrl = await probe(port);
     if (jsonVersionUrl)
         return jsonVersionUrl;
     const fallback = buildDevToolsWsUrl(port, "/devtools/browser");
@@ -162,9 +185,10 @@ export async function resolveWsTargetFromPort(port, options = {}) {
 export async function discoverLocalCdp(options = {}) {
     const candidates = [];
     const userDataDirs = options.userDataDirs ?? getChromeUserDataDirs();
+    const probe = createJsonVersionProbe();
     for (const dir of userDataDirs) {
         const info = await readDevToolsActivePort(dir);
-        if (!info || !(await isPortReachable(info.port)))
+        if (!info || !(await isDevToolsActivePortFresh(info, probe)))
             continue;
         candidates.push({
             source: `DevToolsActivePort:${dir}`,
@@ -172,7 +196,7 @@ export async function discoverLocalCdp(options = {}) {
         });
     }
     for (const port of options.fallbackPorts ?? DEFAULT_FALLBACK_PORTS) {
-        const wsUrl = await probeJsonVersion(port);
+        const wsUrl = await probe(port);
         if (!wsUrl)
             continue;
         if (!candidates.some((candidate) => candidate.wsUrl === wsUrl)) {

package/dist/lib/functions/dev.js

@@ -377,7 +377,9 @@ async function routeRequest(request, response, bridge, manifestStore, sessionMan
             ? body.params || {}
             : {};
         const session = await sessionManager.createSession(manifest.config?.sessionConfig);
-        const accepted = bridge.triggerInvocation(functionName, params, { session }, corsHeaders, response);
+        const accepted = bridge.triggerInvocation(functionName, params, 
+        // Match production, which always sends secrets.
+        { session, secrets: {} }, corsHeaders, response);
         if (!accepted) {
             await sessionManager.closeSession(session.id);
             sendJson(response, 503, { error: "No runtime is connected yet." }, corsHeaders);

package/dist/lib/functions/init.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { fail } from "../errors.js";
@@ -17,24 +17,49 @@ dist/
 .DS_Store
 `;
 const starterFunctionTemplate = `import { defineFn } from "@browserbasehq/sdk-functions";
-import { chromium } from "playwright-core";
+import { browserbase, Stagehand } from "@browserbasehq/stagehand";
+import { z } from "zod/v4";
 
-defineFn("my-function", async (context) => {
-  const browser = await chromium.connectOverCDP(context.session.connectUrl);
-  const page = browser.contexts()[0]!.pages()[0]!;
-
-  await page.goto("https://news.ycombinator.com");
-  await page.waitForSelector(".athing", { timeout: 30_000 });
+defineFn(
+  "my-function",
+  async (context) => {
+    const browser = await browserbase.connect({
+      // The local dev server has no secrets, so fall back to .env.
+      apiKey:
+        context.secrets.BROWSERBASE_API_KEY ?? process.env.BROWSERBASE_API_KEY!,
+      sessionId: context.session.id,
+    });
+    // In this example, Stagehand uses the Model Gateway where Browserbase charges for the tokens
+    const stagehand = await Stagehand.create({ browser });
+    const page = (await browser.context.activePage())!;
 
-  const titles = await page.$$eval(".athing .titleline > a", (elements) =>
-    elements.slice(0, 3).map((element) => element.textContent),
-  );
+    await page.goto("https://news.ycombinator.com");
+    const { data } = await stagehand.extract(
+      "Extract the top 3 stories with their rank, title, and link URL.",
+      z.object({
+        stories: z
+          .array(z.object({ rank: z.number(), title: z.string(), url: z.string() }))
+          .max(3),
+      }),
+    );
 
-  return {
-    message: "Fetched top Hacker News titles",
-    titles,
-  };
-});
+    await stagehand.close();
+    return {
+      message: "Successfully fetched top Hacker News stories",
+      timestamp: new Date().toISOString(),
+      results: data.stories,
+    };
+  },
+  {
+    // Upload the Stagehand extension once, then paste its ID here:
+    //   browse cloud extensions upload node_modules/@browserbasehq/stagehand/dist/assets/stagehand-extension.zip
+    sessionConfig: { extensionId: "your-extension-id" },
+  },
+);
+`;
+// pnpm 11 and later fail installs when esbuild's build script is not approved.
+const pnpmWorkspaceTemplate = `allowBuilds:
+  esbuild: true
 `;
 const tsconfigTemplate = `{
   "compilerOptions": {
@@ -71,9 +96,15 @@ export async function initFunctionsProject({ packageManager, projectName, }) {
     await writeFile(join(projectRoot, ".gitignore"), gitignoreTemplate);
     await writeFile(join(projectRoot, "index.ts"), starterFunctionTemplate);
     await writeFile(join(projectRoot, "tsconfig.json"), tsconfigTemplate);
+    if (packageManager === "pnpm") {
+        await writeFile(join(projectRoot, "pnpm-workspace.yaml"), pnpmWorkspaceTemplate);
+    }
     const install = packageManager === "pnpm" ? ["add"] : ["install"];
     const installDev = packageManager === "pnpm" ? ["add", "-D"] : ["install", "--save-dev"];
-    runPackageManager(packageManager, [...install, "@browserbasehq/sdk-functions", "playwright-core"], projectRoot);
+    runPackageManager(packageManager, [...install, "@browserbasehq/sdk-functions", "@browserbasehq/stagehand"], projectRoot);
+    // Match Stagehand's version of zod in order to pass type checks.
+    const zodVersion = readStagehandZodVersion(projectRoot);
+    runPackageManager(packageManager, [...install, zodVersion ? `zod@${zodVersion}` : "zod"], projectRoot);
     runPackageManager(packageManager, [...installDev, "typescript", "@types/node"], projectRoot);
     if (!existsSync(join(projectRoot, ".git"))) {
         spawnSync("git", ["init"], {
@@ -88,8 +119,11 @@ export async function initFunctionsProject({ packageManager, projectName, }) {
         nextSteps: [
             `cd ${projectName}`,
             "Edit .env with your Browserbase API key",
-            packageManager === "pnpm" ? "pnpm dev" : "npm run dev",
-            packageManager === "pnpm" ? "pnpm run deploy" : "npm run deploy",
+            "browse cloud extensions upload node_modules/@browserbasehq/stagehand/dist/assets/stagehand-extension.zip",
+            "Paste the uploaded extension ID into index.ts",
+            "browse functions dev index.ts",
+            "browse functions publish index.ts",
+            "Create a BROWSERBASE_API_KEY secret with browse cloud secrets create, then attach it with browse functions secrets attach",
         ],
     }, null, 2));
 }
@@ -99,6 +133,15 @@ function ensureCommand(command) {
         fail(`${command} is required but was not found on PATH.`);
     }
 }
+function readStagehandZodVersion(projectRoot) {
+    try {
+        const stagehandPackageJson = JSON.parse(readFileSync(join(projectRoot, "node_modules", "@browserbasehq", "stagehand", "package.json"), "utf8"));
+        return stagehandPackageJson.dependencies?.zod;
+    }
+    catch {
+        return undefined;
+    }
+}
 function runPackageManager(packageManager, args, cwd) {
     const result = spawnSync(packageManager, args, {
         cwd,

package/dist/lib/functions/publish.js

@@ -122,14 +122,23 @@ function ensureArchiveLockfile(root, entries) {
     }
     const tempDir = join(tmpdir(), `bb-functions-lockgen-${randomUUID()}`);
     mkdirSync(tempDir, { recursive: true });
-    copyFileSync(join(root, "package.json"), join(tempDir, "package.json"));
-    const result = spawnSync("npm", ["install", "--package-lock-only"], {
+    // Copy the files that publish uploads, so npm resolves local dependencies the same way the build does.
+    for (const entry of entries) {
+        const target = join(tempDir, entry);
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(join(root, entry), target);
+    }
+    // Omit resolved URLs so the builder installs from its own registry rather than the one on your machine.
+    const result = spawnSync("npm", ["install", "--package-lock-only", "--omit-lockfile-registry-resolved"], {
         cwd: tempDir,
         stdio: "pipe",
     });
     if (result.status !== 0) {
         rmSync(tempDir, { recursive: true, force: true });
-        fail("Failed to generate package-lock.json for the Functions build archive.");
+        const npmOutput = result.error
+            ? result.error.message
+            : result.stderr.toString().trim();
+        fail(`Failed to generate package-lock.json for the Functions build archive.${npmOutput ? `\n${npmOutput}` : ""}`);
     }
     return {
         entries: [...entries, "package-lock.json"].sort(),

package/oclif.manifest.json

@@ -5502,18 +5502,18 @@
         "update.js"
       ]
     },
-    "cloud:projects:get": {
+    "cloud:extensions:delete": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Project ID.",
+          "description": "Extension ID.",
           "name": "id",
           "required": true
         }
       },
-      "description": "Get a project by ID.",
+      "description": "Delete a Chrome extension.",
       "examples": [
-        "browse cloud projects get <project-id>"
+        "browse cloud extensions delete <extension-id>"
       ],
       "flags": {
         "api-key": {
@@ -5535,7 +5535,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "cloud:projects:get",
+      "id": "cloud:extensions:delete",
       "pluginAlias": "browse",
       "pluginName": "browse",
       "pluginType": "core",
@@ -5545,17 +5545,22 @@
         "dist",
         "commands",
         "cloud",
-        "projects",
-        "get.js"
+        "extensions",
+        "delete.js"
       ]
     },
-    "cloud:projects:list": {
+    "cloud:extensions:get": {
       "aliases": [],
-      "args": {},
-      "description": "List projects visible to the current API key.",
+      "args": {
+        "id": {
+          "description": "Extension ID.",
+          "name": "id",
+          "required": true
+        }
+      },
+      "description": "Get a Chrome extension by ID.",
       "examples": [
-        "browse cloud projects list",
-        "browse cloud projects list --json"
+        "browse cloud extensions get <extension-id>"
       ],
       "flags": {
         "api-key": {
@@ -5573,35 +5578,11 @@
           "helpValue": "<baseUrl>",
           "multiple": false,
           "type": "option"
-        },
-        "format": {
-          "description": "Output format. Defaults to table in a terminal and JSON when piped.",
-          "name": "format",
-          "hasDynamicHelp": false,
-          "helpValue": "<format>",
-          "multiple": false,
-          "options": [
-            "table",
-            "json"
-          ],
-          "type": "option"
-        },
-        "json": {
-          "description": "Print raw JSON output.",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "wide": {
-          "description": "Show full table values without truncation.",
-          "name": "wide",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "cloud:projects:list",
+      "id": "cloud:extensions:get",
       "pluginAlias": "browse",
       "pluginName": "browse",
       "pluginType": "core",
@@ -5611,22 +5592,22 @@
         "dist",
         "commands",
         "cloud",
-        "projects",
-        "list.js"
+        "extensions",
+        "get.js"
       ]
     },
-    "cloud:projects:usage": {
+    "cloud:extensions:upload": {
       "aliases": [],
       "args": {
-        "id": {
-          "description": "Project ID.",
-          "name": "id",
+        "file": {
+          "description": "Path to extension ZIP file.",
+          "name": "file",
           "required": true
         }
       },
-      "description": "Get project usage.",
+      "description": "Upload a Chrome extension ZIP file.",
       "examples": [
-        "browse cloud projects usage <project-id>"
+        "browse cloud extensions upload ./extension.zip"
       ],
       "flags": {
         "api-key": {
@@ -5648,7 +5629,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "cloud:projects:usage",
+      "id": "cloud:extensions:upload",
       "pluginAlias": "browse",
       "pluginName": "browse",
       "pluginType": "core",
@@ -5658,22 +5639,22 @@
         "dist",
         "commands",
         "cloud",
-        "projects",
-        "usage.js"
+        "extensions",
+        "upload.js"
       ]
     },
-    "cloud:extensions:delete": {
+    "cloud:projects:get": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Extension ID.",
+          "description": "Project ID.",
           "name": "id",
           "required": true
         }
       },
-      "description": "Delete a Chrome extension.",
+      "description": "Get a project by ID.",
       "examples": [
-        "browse cloud extensions delete <extension-id>"
+        "browse cloud projects get <project-id>"
       ],
       "flags": {
         "api-key": {
@@ -5695,7 +5676,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "cloud:extensions:delete",
+      "id": "cloud:projects:get",
       "pluginAlias": "browse",
       "pluginName": "browse",
       "pluginType": "core",
@@ -5705,22 +5686,17 @@
         "dist",
         "commands",
         "cloud",
-        "extensions",
-        "delete.js"
+        "projects",
+        "get.js"
       ]
     },
-    "cloud:extensions:get": {
+    "cloud:projects:list": {
       "aliases": [],
-      "args": {
-        "id": {
-          "description": "Extension ID.",
-          "name": "id",
-          "required": true
-        }
-      },
-      "description": "Get a Chrome extension by ID.",
+      "args": {},
+      "description": "List projects visible to the current API key.",
       "examples": [
-        "browse cloud extensions get <extension-id>"
+        "browse cloud projects list",
+        "browse cloud projects list --json"
       ],
       "flags": {
         "api-key": {
@@ -5738,11 +5714,35 @@
           "helpValue": "<baseUrl>",
           "multiple": false,
           "type": "option"
+        },
+        "format": {
+          "description": "Output format. Defaults to table in a terminal and JSON when piped.",
+          "name": "format",
+          "hasDynamicHelp": false,
+          "helpValue": "<format>",
+          "multiple": false,
+          "options": [
+            "table",
+            "json"
+          ],
+          "type": "option"
+        },
+        "json": {
+          "description": "Print raw JSON output.",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "wide": {
+          "description": "Show full table values without truncation.",
+          "name": "wide",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "cloud:extensions:get",
+      "id": "cloud:projects:list",
       "pluginAlias": "browse",
       "pluginName": "browse",
       "pluginType": "core",
@@ -5752,22 +5752,22 @@
         "dist",
         "commands",
         "cloud",
-        "extensions",
-        "get.js"
+        "projects",
+        "list.js"
       ]
     },
-    "cloud:extensions:upload": {
+    "cloud:projects:usage": {
       "aliases": [],
       "args": {
-        "file": {
-          "description": "Path to extension ZIP file.",
-          "name": "file",
+        "id": {
+          "description": "Project ID.",
+          "name": "id",
           "required": true
         }
       },
-      "description": "Upload a Chrome extension ZIP file.",
+      "description": "Get project usage.",
       "examples": [
-        "browse cloud extensions upload ./extension.zip"
+        "browse cloud projects usage <project-id>"
       ],
       "flags": {
         "api-key": {
@@ -5789,7 +5789,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "cloud:extensions:upload",
+      "id": "cloud:projects:usage",
       "pluginAlias": "browse",
       "pluginName": "browse",
       "pluginType": "core",
@@ -5799,8 +5799,8 @@
         "dist",
         "commands",
         "cloud",
-        "extensions",
-        "upload.js"
+        "projects",
+        "usage.js"
       ]
     },
     "cloud:secrets:create": {
@@ -6903,5 +6903,5 @@
       ]
     }
   },
-  "version": "0.11.0"
+  "version": "0.11.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browse",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Unified Browserbase CLI for browser automation and cloud APIs.",
   "type": "module",
   "private": false,