browse 0.8.4-alpha-75df86a → 0.8.4-alpha-cffcc91

package/dist/hooks/command-not-found.js

@@ -0,0 +1,45 @@
+import { Errors } from "@oclif/core";
+import { suggestCommand } from "../lib/command-suggestions.js";
+import { captureCommandNotFound } from "../lib/telemetry.js";
+function toSpaced(commandId) {
+    return commandId.replaceAll(":", " ");
+}
+const hook = async function ({ config, id }) {
+    let attempted = "";
+    let suggestion = null;
+    try {
+        const commandIds = config.commands
+            .filter((command) => !command.hidden)
+            .map((command) => command.id);
+        const result = suggestCommand(id, commandIds);
+        attempted = result.attempted;
+        suggestion = result.suggestion;
+        if (suggestion &&
+            !config.findCommand(suggestion) &&
+            !config.findTopic(suggestion)) {
+            // Guards against alias targets drifting out of the command tree.
+            suggestion = null;
+        }
+        const displayAttempted = toSpaced(attempted || (id.split(":")[0] ?? id));
+        const didYouMean = suggestion
+            ? ` Did you mean "${config.bin} ${toSpaced(suggestion)}"?`
+            : "";
+        process.stderr.write(`"${config.bin} ${displayAttempted}" is not a ${config.bin} command.${didYouMean} Run ${config.bin} --help for all commands.\n`);
+    }
+    catch {
+        // Suggestions are best-effort and must never mask the not-found error.
+    }
+    try {
+        // Awaited so the event is delivered before the process exits; the
+        // transport aborts after a short timeout, so this cannot hang the CLI.
+        await captureCommandNotFound(config.version, attempted || null, suggestion);
+    }
+    catch {
+        // Best-effort telemetry should never affect CLI behavior.
+    }
+    // Re-throw oclif's standard not-found error. Returning normally from a
+    // command_not_found hook makes oclif treat the invocation as handled
+    // (exit 0), so this throw preserves the default error and exit code 2.
+    throw new Errors.CLIError(`command ${id} not found`);
+};
+export default hook;

package/dist/lib/command-suggestions.js

@@ -0,0 +1,112 @@
+/**
+ * Suggestion engine for unknown commands.
+ *
+ * oclif's spaced-topic parsing glues unknown leading argv tokens into the
+ * attempted command id (e.g. `browse opne https://example.com` arrives as
+ * `opne:https://example.com`), so the id may contain user-provided values.
+ * Everything here works on a sanitized token prefix and never returns raw
+ * argv content beyond the tokens that matched a known command shape.
+ */
+import { distance } from "fastest-levenshtein";
+/**
+ * Old Commander-era syntax (and common agent guesses) mapped to the current
+ * command tree. Keys and values are colon-separated oclif ids; values may
+ * also be topics (e.g. `cloud:contexts`, which prints topic help).
+ */
+export const aliasSuggestions = new Map([
+    ["sessions", "cloud:sessions:list"],
+    ["sessions:list", "cloud:sessions:list"],
+    ["sessions:create", "cloud:sessions:create"],
+    ["sessions:get", "cloud:sessions:get"],
+    ["projects", "cloud:projects:list"],
+    ["projects:list", "cloud:projects:list"],
+    ["contexts", "cloud:contexts"],
+    ["extensions", "cloud:extensions"],
+    ["search", "cloud:search"],
+    ["fetch", "cloud:fetch"],
+    ["goto", "open"],
+    ["navigate", "open"],
+]);
+const safeTokenPattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const maxCommandTokens = 4;
+const maxSuggestionDistance = 5;
+/**
+ * Extracts the leading command-shaped tokens from an attempted id, stopping
+ * at the first token that does not look like a command word (URLs, selectors,
+ * flags, and other argument-like values).
+ */
+export function extractCommandTokens(id) {
+    const tokens = [];
+    for (const token of id.split(":")) {
+        if (tokens.length >= maxCommandTokens || !safeTokenPattern.test(token)) {
+            break;
+        }
+        tokens.push(token.toLowerCase());
+    }
+    return tokens;
+}
+function tokenThreshold(token) {
+    return Math.max(2, Math.floor(token.length / 3));
+}
+/**
+ * Segment-aligned fuzzy distance between a token prefix and a command id.
+ * Only command ids with the same number of segments are considered, and every
+ * token must be within its own edit-distance threshold of the corresponding
+ * segment. This means a trailing token can only ever be retained in the
+ * attempted command when it itself looks like a typo of a real command
+ * segment — free-form user values can never ride along.
+ */
+function prefixDistance(tokens, commandId) {
+    const segments = commandId.split(":");
+    if (segments.length !== tokens.length) {
+        return null;
+    }
+    let total = 0;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i] ?? "";
+        const segmentDistance = distance(token, segments[i] ?? "");
+        if (segmentDistance > tokenThreshold(token)) {
+            return null;
+        }
+        total += segmentDistance;
+    }
+    return total > maxSuggestionDistance ? null : total;
+}
+/**
+ * Computes a suggestion for an unknown command id. Explicit aliases win over
+ * fuzzy matches, and longer token prefixes win over shorter ones so that
+ * `auth status` resolves before `auth`. Returns only the matched prefix as
+ * `attempted` (or the first token when nothing matches) so user-provided
+ * values never escape into messaging or telemetry.
+ */
+export function suggestCommand(id, commandIds) {
+    const tokens = extractCommandTokens(id);
+    if (tokens.length === 0) {
+        return { attempted: "", suggestion: null };
+    }
+    for (let length = tokens.length; length >= 1; length--) {
+        const attempted = tokens.slice(0, length).join(":");
+        const alias = aliasSuggestions.get(attempted);
+        if (alias) {
+            return { attempted, suggestion: alias };
+        }
+    }
+    let best;
+    for (let length = tokens.length; length >= 1; length--) {
+        const prefix = tokens.slice(0, length);
+        for (const commandId of commandIds) {
+            const prefixDist = prefixDistance(prefix, commandId);
+            if (prefixDist !== null && (!best || prefixDist < best.distance)) {
+                best = {
+                    attempted: prefix.join(":"),
+                    suggestion: commandId,
+                    distance: prefixDist,
+                };
+            }
+        }
+    }
+    if (best) {
+        return { attempted: best.attempted, suggestion: best.suggestion };
+    }
+    return { attempted: tokens[0] ?? "", suggestion: null };
+}

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/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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browse",
-  "version": "0.8.4-alpha-75df86a",
+  "version": "0.8.4-alpha-cffcc91",
   "description": "Unified Browserbase CLI for browser automation and cloud APIs.",
   "type": "module",
   "private": false,
@@ -27,7 +27,8 @@
     "hooks": {
       "init": "./dist/hooks/init.js",
       "prerun": "./dist/hooks/prerun.js",
-      "finally": "./dist/hooks/finally.js"
+      "finally": "./dist/hooks/finally.js",
+      "command_not_found": "./dist/hooks/command-not-found.js"
     },
     "topicSeparator": " ",
     "topics": {
@@ -91,6 +92,8 @@
     "archiver": "^7.0.1",
     "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",