browse 0.8.4-alpha-4ee8d99 → 0.8.4-alpha-cffcc91

package/dist/lib/driver/commands/selectors.js

@@ -1,3 +1,4 @@
+import { DriverError } from "../errors.js";
 export function emptyRefMaps() {
     return { urlMap: {}, xpathMap: {} };
 }
@@ -24,7 +25,7 @@ export function resolveSelector(selector, refMaps) {
         return selector;
     const xpath = refMaps.xpathMap[ref];
     if (!xpath) {
-        throw new Error(`Unknown ref "${ref}" - run browse snapshot first to populate refs (have ${Object.keys(refMaps.xpathMap).length} refs).`);
+        throw new DriverError(`Unknown ref "${ref}" - run browse snapshot first to populate refs (have ${Object.keys(refMaps.xpathMap).length} refs).`, { code: "stale_ref" });
     }
     return xpath;
 }

package/dist/lib/driver/daemon/client.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { promises as fs } from "node:fs";
 import net from "node:net";
-import { fail } from "../../errors.js";
+import { CommandFailure, fail } from "../../errors.js";
 import { targetsCompatible } from "../mode.js";
 import { cleanupDaemonFiles, ensureRuntimeDir, getLockPath, getPidPath, getSocketPath, PRIVATE_FILE_MODE, } from "./paths.js";
 import { isProcessAlive } from "./process.js";
@@ -15,7 +15,7 @@ export async function ensureDriverDaemon({ session, target, }) {
     }
     const locked = await acquireLock(session);
     if (!locked) {
-        fail(`Timed out waiting for driver daemon lock for session "${session}".`);
+        fail(`Timed out waiting for driver daemon lock for session "${session}".`, 1, { resultCode: "daemon_lock_timeout" });
     }
     try {
         const afterLock = await tryDriverStatus(session);
@@ -24,7 +24,7 @@ export async function ensureDriverDaemon({ session, target, }) {
             return;
         }
         if (await isDaemonPidAlive(session)) {
-            fail(`Driver daemon session "${session}" is running but not responding. Run browse stop --session ${session} --force to clean it up.`);
+            fail(`Driver daemon session "${session}" is running but not responding. Run browse stop --session ${session} --force to clean it up.`, 1, { resultCode: "daemon_unresponsive" });
         }
         spawnDaemon(session, target);
         await waitForSocketReady(getSocketPath(session), 30_000);
@@ -123,7 +123,7 @@ async function sendDriverRequest(session, request) {
             return new Error(`Driver daemon session "${session}" closed ${detail}.`);
         };
         const timeout = setTimeout(() => {
-            failRequest(new Error(`Timed out waiting for driver daemon session "${session}".`));
+            failRequest(new CommandFailure(`Timed out waiting for driver daemon session "${session}".`, 1, { resultCode: "daemon_socket_timeout" }));
         }, 35_000);
         socket.on("connect", () => {
             socket.write(`${JSON.stringify(request)}\n`);
@@ -136,7 +136,12 @@ async function sendDriverRequest(session, request) {
             try {
                 const response = ResponseSchema.parse(JSON.parse(buffer.slice(0, newline)));
                 if (response.type === "error") {
-                    failRequest(new Error(response.error));
+                    failRequest(new CommandFailure(response.error, 1, {
+                        ...(response.code ? { resultCode: response.code } : {}),
+                        ...(response.httpStatus !== undefined
+                            ? { httpStatus: response.httpStatus }
+                            : {}),
+                    }));
                     return;
                 }
                 completeRequest(response.data);
@@ -161,7 +166,9 @@ async function sendDriverRequest(session, request) {
 function spawnDaemon(session, target) {
     const entrypoint = process.argv[1];
     if (!entrypoint) {
-        fail("Unable to locate browse CLI entrypoint for daemon startup.");
+        fail("Unable to locate browse CLI entrypoint for daemon startup.", 1, {
+            resultCode: "daemon_spawn_failed",
+        });
     }
     const child = spawn(process.execPath, [
         entrypoint,

package/dist/lib/driver/daemon/protocol.js

@@ -32,7 +32,9 @@ export const SuccessResponseSchema = z.object({
     type: z.literal("success"),
 });
 export const ErrorResponseSchema = z.object({
+    code: z.string().optional(),
     error: z.string(),
+    httpStatus: z.number().optional(),
     id: z.string().optional(),
     type: z.literal("error"),
 });

package/dist/lib/driver/daemon/server.js

@@ -1,5 +1,6 @@
 import net from "node:net";
 import readline from "node:readline";
+import { DriverError } from "../errors.js";
 import { DriverSessionManager } from "../session-manager.js";
 import { cleanupDaemonFiles, ensureRuntimeDir, getPidPath, getSocketPath, writePrivateFile, } from "./paths.js";
 import { parseRequest, serializeResponse, } from "./protocol.js";
@@ -83,7 +84,7 @@ async function handleLine(line, socket, manager) {
         request = parseRequest(line);
     }
     catch (error) {
-        await writeResponse(socket, { error: formatError(error), type: "error" });
+        await writeResponse(socket, { ...formatError(error), type: "error" });
         return false;
     }
     try {
@@ -124,7 +125,7 @@ async function handleLine(line, socket, manager) {
     }
     catch (error) {
         await writeResponse(socket, {
-            error: formatError(error),
+            ...formatError(error),
             id: request.id,
             type: "error",
         });
@@ -161,5 +162,15 @@ function endSocket(socket) {
     });
 }
 function formatError(error) {
-    return error instanceof Error ? error.message : String(error);
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof DriverError) {
+        return {
+            code: error.code,
+            error: message,
+            ...(error.httpStatus !== undefined
+                ? { httpStatus: error.httpStatus }
+                : {}),
+        };
+    }
+    return { error: message };
 }

package/dist/lib/driver/errors.js

@@ -0,0 +1,16 @@
+/**
+ * Typed driver error. The daemon serializes `code`/`httpStatus` into error
+ * responses so the client can record a telemetry result code and agents get
+ * a stable, machine-readable failure reason alongside the human message.
+ */
+export class DriverError extends Error {
+    code;
+    httpStatus;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? {} : { cause: options.cause });
+        this.name = "DriverError";
+        this.code = options.code;
+        if (options.httpStatus !== undefined)
+            this.httpStatus = options.httpStatus;
+    }
+}

package/dist/lib/driver/remote.disabled.js

@@ -13,6 +13,21 @@ export function autoSelectRemoteTarget() {
 export function remoteStagehandOptions() {
     throw new Error(DISABLED_MESSAGE);
 }
+export function classifyRemoteInitError(error) {
+    // Remote targets cannot be selected in a local-only build, so this is only
+    // reachable if a remote error somehow surfaces anyway; preserve it as-is.
+    return {
+        code: "remote_session_create_failed",
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+export function driverInitHints() {
+    // Key-free variants: a local-only artifact must not mention the API key.
+    return {
+        chromeNotFound: "No Chrome or Chromium found on this machine. Install one (Linux: apt install chromium \u00b7 macOS: brew install --cask google-chrome, or Chromium with CHROME_PATH set) or attach to a running browser with --cdp <port>.",
+        repeatedInitFailure: " (failing repeatedly — check your browser setup or run browse doctor)",
+    };
+}
 export function remoteDoctorCheck() {
     return { ok: true, message: "remote disabled (local-only build)" };
 }

package/dist/lib/driver/remote.js

@@ -1,3 +1,4 @@
+import { StatusCodes } from "http-status-codes";
 /**
  * Real Browserbase capability. This is the ONLY module that reads
  * `BROWSERBASE_API_KEY`; it is excluded from `build:local-only` so that
@@ -25,6 +26,40 @@ export function remoteStagehandOptions() {
         verbose: 0,
     };
 }
+/**
+ * Map a failed remote `stagehand.init()` to an actionable message and a
+ * stable result code. Browserbase SDK errors carry an HTTP `status`.
+ */
+export function classifyRemoteInitError(error) {
+    const status = error?.status;
+    const httpStatus = typeof status === "number" ? status : undefined;
+    const original = error instanceof Error ? error.message : String(error);
+    if (httpStatus === StatusCodes.UNAUTHORIZED) {
+        return {
+            code: "remote_auth_401",
+            httpStatus,
+            message: "Browserbase rejected your BROWSERBASE_API_KEY (401 Unauthorized). A set key makes browse default to remote mode. Check the key at https://browserbase.com/settings, run without one using --local (browse open <url> --local), or diagnose with browse doctor.",
+        };
+    }
+    if (httpStatus === StatusCodes.FORBIDDEN) {
+        return {
+            code: "remote_auth_403",
+            httpStatus,
+            message: "Browserbase refused this request (403 Forbidden). Your BROWSERBASE_API_KEY may lack access to this project, or your plan may not allow this session type. Check the key at https://browserbase.com/settings, run without one using --local (browse open <url> --local), or diagnose with browse doctor.",
+        };
+    }
+    return {
+        code: "remote_session_create_failed",
+        ...(httpStatus !== undefined ? { httpStatus } : {}),
+        message: `Failed to start a remote (Browserbase) session: ${original}\nRun browse doctor to diagnose remote connectivity.`,
+    };
+}
+export function driverInitHints() {
+    return {
+        chromeNotFound: "No Chrome or Chromium found on this machine. Install one (Linux: apt install chromium \u00b7 macOS: brew install --cask google-chrome, or Chromium with CHROME_PATH set), attach to a running browser with --cdp <port>, or set BROWSERBASE_API_KEY to use a remote browser.",
+        repeatedInitFailure: " (failing repeatedly — fix BROWSERBASE_API_KEY, use --local, or run browse doctor)",
+    };
+}
 export function remoteDoctorCheck(env) {
     if (env.BROWSERBASE_API_KEY) {
         return { ok: true, message: "BROWSERBASE_API_KEY is set" };

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);
@@ -144,7 +172,7 @@ export class DriverSessionManager {
             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 {
@@ -168,19 +196,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 +231,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;
@@ -243,3 +284,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browse",
-  "version": "0.8.4-alpha-4ee8d99",
+  "version": "0.8.4-alpha-cffcc91",
   "description": "Unified Browserbase CLI for browser automation and cloud APIs.",
   "type": "module",
   "private": false,
@@ -93,6 +93,7 @@
     "deepmerge": "^4.3.1",
     "dotenv": "^16.5.0",
     "fastest-levenshtein": "^1.0.16",
+    "http-status-codes": "^2.3.0",
     "ignore": "^7.0.5",
     "node-html-markdown": "^1.3.0",
     "semver": "^7.7.4",