browse 0.8.4 → 0.8.5

package/dist/lib/driver/session-manager.js

@@ -1,14 +1,41 @@
 import { Stagehand } from "@browserbasehq/stagehand";
 import { emptyRefMaps, resolveSelector as resolveCachedSelector, } from "./commands/selectors.js";
 import { executeDriverCommand } from "./commands/registry.js";
+import { DriverError } from "./errors.js";
 import { discoverLocalCdp } from "./local-cdp-discovery.js";
 import { NetworkCapture } from "./network-capture.js";
 import { getRemote } from "./remote-binding.js";
 const INIT_FAILURE_RETRY_MS = 5_000;
+const INIT_FAILURE_RETRY_MAX_MS = 60_000;
+// chrome-launcher reports "no Chrome on this machine" with these codes (its
+// LaunchErrorCodes const enum, which can't be imported directly: const enums
+// are erased at build time and isolatedModules forbids cross-module access).
+const CHROME_NOT_FOUND_ERROR_CODES = new Set([
+    "ERR_LAUNCHER_NOT_INSTALLED",
+    "ERR_LAUNCHER_PATH_NOT_SET",
+]);
+/**
+ * Exponential backoff for cached init failures: 5s, 10s, 20s, ... capped at
+ * 1 minute. Prevents agents stuck in retry loops from hammering init while
+ * still allowing a quick retry after the first failure.
+ */
+export function initFailureBackoffMs(consecutiveFailures) {
+    const attempt = Math.max(1, consecutiveFailures);
+    return Math.min(INIT_FAILURE_RETRY_MS * 2 ** (attempt - 1), INIT_FAILURE_RETRY_MAX_MS);
+}
+export function isChromeNotFoundError(error) {
+    const code = error?.code;
+    if (typeof code === "string" && CHROME_NOT_FOUND_ERROR_CODES.has(code)) {
+        return true;
+    }
+    return (error instanceof Error &&
+        error.message.includes("No Chrome installations found"));
+}
 export class DriverSessionManager {
     session;
     target;
     network;
+    consecutiveInitFailures = 0;
     context = null;
     initFailure = null;
     initPromise = null;
@@ -79,6 +106,7 @@ export class DriverSessionManager {
         this.stagehand = null;
         this.context = null;
         this.initFailure = null;
+        this.consecutiveInitFailures = 0;
         await this.network.disable().catch(() => undefined);
         if (stagehand) {
             await stagehand.close().catch(() => undefined);
@@ -128,23 +156,23 @@ export class DriverSessionManager {
             if (!page) {
                 throw new Error(`Target ${target.targetId} was not found in the attached browser.`);
             }
-            this.context.setActivePage(page);
+            this.activateIfNeeded(page);
             this.selectedTargetId = page.targetId();
             return page;
         }
         const existingPage = this.activePageIfPresent() ?? this.context.pages()[0];
         if (existingPage) {
-            this.context.setActivePage(existingPage);
+            this.activateIfNeeded(existingPage);
             this.selectedTargetId = existingPage.targetId();
             return existingPage;
         }
         if (options.createIfMissing) {
             const page = await this.context.newPage();
-            this.context.setActivePage(page);
+            this.activateIfNeeded(page);
             this.selectedTargetId = page.targetId();
             return page;
         }
-        throw new Error(`No active page in session "${this.session}". Run browse open <url> --session ${this.session} or browse tab new <url> --session ${this.session}.`);
+        throw new DriverError(`No active page in session "${this.session}". Run browse open <url> --session ${this.session} or browse tab new <url> --session ${this.session}.`, { code: "no_active_page" });
     }
     activePageIfPresent() {
         try {
@@ -154,6 +182,21 @@ export class DriverSessionManager {
             return undefined;
         }
     }
+    /**
+     * Mark `page` active only when it isn't already the active page.
+     *
+     * `setActivePage` ends in a CDP `Target.activateTarget`, which on macOS
+     * raises the whole Chrome app to the OS foreground and steals keyboard focus.
+     * The daemon resolves the active page on every subcommand, so calling this
+     * unconditionally yanks focus away from the user's editor/terminal on each
+     * command in headed local mode. Skipping the redundant re-activation keeps a
+     * headed session usable alongside a coding agent.
+     */
+    activateIfNeeded(page) {
+        if (page !== this.activePageIfPresent()) {
+            this.context?.setActivePage(page);
+        }
+    }
     async ensureInitialized() {
         if (this.stagehand && this.context)
             return;
@@ -168,19 +211,32 @@ export class DriverSessionManager {
         this.initPromise = this.initialize()
             .then(() => {
             this.initFailure = null;
+            this.consecutiveInitFailures = 0;
         })
-            .catch((error) => {
+            .catch(async (error) => {
+            this.consecutiveInitFailures += 1;
+            const failure = await this.markRepeatedInitFailure(error);
             this.initFailure = {
-                error,
-                retryAt: Date.now() + INIT_FAILURE_RETRY_MS,
+                error: failure,
+                retryAt: Date.now() + initFailureBackoffMs(this.consecutiveInitFailures),
             };
-            throw error;
+            throw failure;
         })
             .finally(() => {
             this.initPromise = null;
         });
         return this.initPromise;
     }
+    async markRepeatedInitFailure(error) {
+        if (this.consecutiveInitFailures < 3 || !(error instanceof Error)) {
+            return error;
+        }
+        const hint = (await getRemote()).driverInitHints().repeatedInitFailure;
+        if (!error.message.includes(hint)) {
+            error.message += hint;
+        }
+        return error;
+    }
     async initialize() {
         const resolvedTarget = await this.resolveTarget();
         const options = await this.stagehandOptions(resolvedTarget);
@@ -190,7 +246,7 @@ export class DriverSessionManager {
         }
         catch (error) {
             await stagehand.close().catch(() => undefined);
-            throw error;
+            throw await describeInitError(error, resolvedTarget);
         }
         this.stagehand = stagehand;
         this.context = stagehand.context;
@@ -213,6 +269,10 @@ export class DriverSessionManager {
                 disablePino: true,
                 env: "LOCAL",
                 localBrowserLaunchOptions: {
+                    ...(target.chromeArgs?.length ? { args: target.chromeArgs } : {}),
+                    ...(target.ignoreDefaultArgs !== undefined
+                        ? { ignoreDefaultArgs: target.ignoreDefaultArgs }
+                        : {}),
                     headless: target.headless,
                 },
                 verbose: 0,
@@ -239,3 +299,24 @@ async function safeTitle(page) {
         return "";
     }
 }
+/**
+ * Turn raw `stagehand.init()` failures into typed, actionable errors. Remote
+ * failures are classified by the remote capability (401/403/etc.); a missing
+ * local Chrome gets install/escape-hatch guidance. Anything else is rethrown
+ * unchanged.
+ */
+async function describeInitError(error, target) {
+    if (error instanceof DriverError)
+        return error;
+    if (target.kind === "remote") {
+        const { code, httpStatus, message } = (await getRemote()).classifyRemoteInitError(error);
+        return new DriverError(message, { cause: error, code, httpStatus });
+    }
+    if (target.kind === "managed-local" && isChromeNotFoundError(error)) {
+        return new DriverError((await getRemote()).driverInitHints().chromeNotFound, {
+            cause: error,
+            code: "no_chrome_found",
+        });
+    }
+    return error;
+}

package/dist/lib/skills/install.js

@@ -5,6 +5,7 @@ import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { fail } from "../errors.js";
+import { setRunTelemetryCompletion } from "../run-telemetry.js";
 import { defaultSkillsApiBaseUrl, isRecord, responseDetail } from "./shared.js";
 const defaultBlobBaseUrl = "https://gh0lfhlmyzhg6tww.public.blob.vercel-storage.com";
 const generatedSkillSuffixPattern = /-[A-Za-z0-9]{6}$/;
@@ -46,14 +47,18 @@ export function isBlobSkillId(skillId) {
     return generatedSkillSuffixPattern.test(skillId.task);
 }
 export async function installSkill(rawSkillId) {
-    const skillId = parseSkillId(rawSkillId);
+    const skill = parseSkillId(rawSkillId);
+    // Attach only the validated, catalog-public id to telemetry — never the raw
+    // argument, which can contain arbitrary user input. Setting it right after
+    // parsing covers success and every downstream failure path.
+    setRunTelemetryCompletion({ skillId: skill.id });
     const npxPath = await findExecutable("npx");
     if (!npxPath) {
         fail("`npx` is not installed. Install Node.js from https://nodejs.org, then rerun `browse skills add`.", 1, { resultCode: "npx_missing" });
     }
-    const files = await fetchSkillFiles(skillId);
+    const files = await fetchSkillFiles(skill);
     if (files.status === "found") {
-        const result = await downloadBlobSkill(skillId, files.files);
+        const result = await downloadBlobSkill(skill, files.files);
         process.stdout.write(`Downloaded ${result.fileCount} skill file${result.fileCount === 1 ? "" : "s"} to ${result.installPath}\n`);
         await runSkillsInstall(npxPath, [
             "--yes",
@@ -64,7 +69,7 @@ export async function installSkill(rawSkillId) {
         return;
     }
     if (files.status === "not_found") {
-        fail(`Skill "${skillId.id}" not found in the catalog. Run \`browse skills find ${skillId.domain}\` to discover available skills, or \`browse skills list\` to browse them.`, 1, { resultCode: "skill_not_found" });
+        fail(`Skill "${skill.id}" not found in the catalog. Run \`browse skills find ${skill.domain}\` to discover available skills, or \`browse skills list\` to browse them.`, 1, { resultCode: "skill_not_found" });
     }
     // Suffix-shaped (generated) ids, or a temporarily unavailable catalog, may
     // still resolve through the browse.sh GitHub repo.
@@ -74,10 +79,11 @@ export async function installSkill(rawSkillId) {
         "add",
         "browserbase/browse.sh",
         "--skill",
-        skillId.id,
+        skill.id,
     ]);
 }
 export async function installBundledCliSkill() {
+    setRunTelemetryCompletion({ skillId: "bundled/browse" });
     const npxPath = await findExecutable("npx");
     if (!npxPath) {
         fail("`npx` is not installed. Install Node.js from https://nodejs.org, then rerun `browse skills install`.", 1, { resultCode: "npx_missing" });

package/dist/lib/telemetry.js

@@ -52,6 +52,25 @@ export async function captureCommandCompleted(cliVersion, error) {
         completionCapture,
     ]);
 }
+/**
+ * Captures a `cli.command_not_found` event. Privacy: only the sanitized
+ * attempted command id and the computed suggestion are sent — never raw argv,
+ * which can contain URLs, selectors, or secrets.
+ */
+export async function captureCommandNotFound(cliVersion, attemptedCommand, suggestedCommand) {
+    await getCliTelemetry(cliVersion)
+        .capture("cli.command_not_found", {
+        attempted_command: attemptedCommand
+            ? resolveCommandPath(attemptedCommand)
+            : null,
+        suggested_command: suggestedCommand
+            ? resolveCommandPath(suggestedCommand)
+            : null,
+    })
+        .catch(() => {
+        // Best-effort telemetry should never affect CLI behavior.
+    });
+}
 function createCliTelemetry(options) {
     const env = options.env ?? process.env;
     const transport = resolveTransportConfig(env);
@@ -147,6 +166,7 @@ function commandCompletedProperties(invocation, completion) {
         request_had_http_response: failureTelemetry?.requestHadHttpResponse ??
             runTelemetry.requestHadHttpResponse ??
             null,
+        skill_id: runTelemetry.skillId ?? null,
     };
 }
 function fallbackResultCode(success, errorType) {