browse 0.8.4 → 0.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -57,10 +57,14 @@ Every driver command accepts the same flags to pick where the browser runs. Mix
57
57
  | `--auto-connect` | Auto-discover and attach to a local Chrome with remote debugging enabled |
58
58
  | `--cdp <url\|port>` | Attach directly to a CDP endpoint (port, `http(s)://`, or `ws(s)://`) |
59
59
  | `--target-id <id>` | Select a specific CDP target when attaching to an existing browser |
60
+ | `--chrome-arg <flag>` | Append a Chrome launch arg on top of the defaults (repeatable, managed-local only) |
61
+ | `--ignore-default-chrome-arg <flag>` | Drop a specific Chrome default launch arg (repeatable, managed-local only) |
62
+ | `--no-default-chrome-args` | Launch without any of Chrome's default args (managed-local only) |
60
63
 
61
64
  ```bash
62
65
  browse open https://example.com # default target
63
66
  browse open https://example.com --local --headed
67
+ browse open https://example.com --local --headed --chrome-arg=--no-focus-on-navigate
64
68
  browse open https://example.com --remote
65
69
  browse open https://example.com --auto-connect
66
70
  browse open https://example.com --cdp 9222
@@ -0,0 +1,45 @@
1
+ import { Errors } from "@oclif/core";
2
+ import { suggestCommand } from "../lib/command-suggestions.js";
3
+ import { captureCommandNotFound } from "../lib/telemetry.js";
4
+ function toSpaced(commandId) {
5
+ return commandId.replaceAll(":", " ");
6
+ }
7
+ const hook = async function ({ config, id }) {
8
+ let attempted = "";
9
+ let suggestion = null;
10
+ try {
11
+ const commandIds = config.commands
12
+ .filter((command) => !command.hidden)
13
+ .map((command) => command.id);
14
+ const result = suggestCommand(id, commandIds);
15
+ attempted = result.attempted;
16
+ suggestion = result.suggestion;
17
+ if (suggestion &&
18
+ !config.findCommand(suggestion) &&
19
+ !config.findTopic(suggestion)) {
20
+ // Guards against alias targets drifting out of the command tree.
21
+ suggestion = null;
22
+ }
23
+ const displayAttempted = toSpaced(attempted || (id.split(":")[0] ?? id));
24
+ const didYouMean = suggestion
25
+ ? ` Did you mean "${config.bin} ${toSpaced(suggestion)}"?`
26
+ : "";
27
+ process.stderr.write(`"${config.bin} ${displayAttempted}" is not a ${config.bin} command.${didYouMean} Run ${config.bin} --help for all commands.\n`);
28
+ }
29
+ catch {
30
+ // Suggestions are best-effort and must never mask the not-found error.
31
+ }
32
+ try {
33
+ // Awaited so the event is delivered before the process exits; the
34
+ // transport aborts after a short timeout, so this cannot hang the CLI.
35
+ await captureCommandNotFound(config.version, attempted || null, suggestion);
36
+ }
37
+ catch {
38
+ // Best-effort telemetry should never affect CLI behavior.
39
+ }
40
+ // Re-throw oclif's standard not-found error. Returning normally from a
41
+ // command_not_found hook makes oclif treat the invocation as handled
42
+ // (exit 0), so this throw preserves the default error and exit code 2.
43
+ throw new Errors.CLIError(`command ${id} not found`);
44
+ };
45
+ export default hook;
@@ -0,0 +1,112 @@
1
+ /**
2
+ * Suggestion engine for unknown commands.
3
+ *
4
+ * oclif's spaced-topic parsing glues unknown leading argv tokens into the
5
+ * attempted command id (e.g. `browse opne https://example.com` arrives as
6
+ * `opne:https://example.com`), so the id may contain user-provided values.
7
+ * Everything here works on a sanitized token prefix and never returns raw
8
+ * argv content beyond the tokens that matched a known command shape.
9
+ */
10
+ import { distance } from "fastest-levenshtein";
11
+ /**
12
+ * Old Commander-era syntax (and common agent guesses) mapped to the current
13
+ * command tree. Keys and values are colon-separated oclif ids; values may
14
+ * also be topics (e.g. `cloud:contexts`, which prints topic help).
15
+ */
16
+ export const aliasSuggestions = new Map([
17
+ ["sessions", "cloud:sessions:list"],
18
+ ["sessions:list", "cloud:sessions:list"],
19
+ ["sessions:create", "cloud:sessions:create"],
20
+ ["sessions:get", "cloud:sessions:get"],
21
+ ["projects", "cloud:projects:list"],
22
+ ["projects:list", "cloud:projects:list"],
23
+ ["contexts", "cloud:contexts"],
24
+ ["extensions", "cloud:extensions"],
25
+ ["search", "cloud:search"],
26
+ ["fetch", "cloud:fetch"],
27
+ ["goto", "open"],
28
+ ["navigate", "open"],
29
+ ]);
30
+ const safeTokenPattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
31
+ const maxCommandTokens = 4;
32
+ const maxSuggestionDistance = 5;
33
+ /**
34
+ * Extracts the leading command-shaped tokens from an attempted id, stopping
35
+ * at the first token that does not look like a command word (URLs, selectors,
36
+ * flags, and other argument-like values).
37
+ */
38
+ export function extractCommandTokens(id) {
39
+ const tokens = [];
40
+ for (const token of id.split(":")) {
41
+ if (tokens.length >= maxCommandTokens || !safeTokenPattern.test(token)) {
42
+ break;
43
+ }
44
+ tokens.push(token.toLowerCase());
45
+ }
46
+ return tokens;
47
+ }
48
+ function tokenThreshold(token) {
49
+ return Math.max(2, Math.floor(token.length / 3));
50
+ }
51
+ /**
52
+ * Segment-aligned fuzzy distance between a token prefix and a command id.
53
+ * Only command ids with the same number of segments are considered, and every
54
+ * token must be within its own edit-distance threshold of the corresponding
55
+ * segment. This means a trailing token can only ever be retained in the
56
+ * attempted command when it itself looks like a typo of a real command
57
+ * segment — free-form user values can never ride along.
58
+ */
59
+ function prefixDistance(tokens, commandId) {
60
+ const segments = commandId.split(":");
61
+ if (segments.length !== tokens.length) {
62
+ return null;
63
+ }
64
+ let total = 0;
65
+ for (let i = 0; i < tokens.length; i++) {
66
+ const token = tokens[i] ?? "";
67
+ const segmentDistance = distance(token, segments[i] ?? "");
68
+ if (segmentDistance > tokenThreshold(token)) {
69
+ return null;
70
+ }
71
+ total += segmentDistance;
72
+ }
73
+ return total > maxSuggestionDistance ? null : total;
74
+ }
75
+ /**
76
+ * Computes a suggestion for an unknown command id. Explicit aliases win over
77
+ * fuzzy matches, and longer token prefixes win over shorter ones so that
78
+ * `auth status` resolves before `auth`. Returns only the matched prefix as
79
+ * `attempted` (or the first token when nothing matches) so user-provided
80
+ * values never escape into messaging or telemetry.
81
+ */
82
+ export function suggestCommand(id, commandIds) {
83
+ const tokens = extractCommandTokens(id);
84
+ if (tokens.length === 0) {
85
+ return { attempted: "", suggestion: null };
86
+ }
87
+ for (let length = tokens.length; length >= 1; length--) {
88
+ const attempted = tokens.slice(0, length).join(":");
89
+ const alias = aliasSuggestions.get(attempted);
90
+ if (alias) {
91
+ return { attempted, suggestion: alias };
92
+ }
93
+ }
94
+ let best;
95
+ for (let length = tokens.length; length >= 1; length--) {
96
+ const prefix = tokens.slice(0, length);
97
+ for (const commandId of commandIds) {
98
+ const prefixDist = prefixDistance(prefix, commandId);
99
+ if (prefixDist !== null && (!best || prefixDist < best.distance)) {
100
+ best = {
101
+ attempted: prefix.join(":"),
102
+ suggestion: commandId,
103
+ distance: prefixDist,
104
+ };
105
+ }
106
+ }
107
+ }
108
+ if (best) {
109
+ return { attempted: best.attempted, suggestion: best.suggestion };
110
+ }
111
+ return { attempted: tokens[0] ?? "", suggestion: null };
112
+ }
@@ -1,15 +1,18 @@
1
1
  import { Flags } from "@oclif/core";
2
- import { autoConnectFlag, cdpFlag, headedFlag, headlessFlag, localFlag, remoteFlag, sessionFlag, sessionName, targetIdFlag, } from "./flags.js";
2
+ import { autoConnectFlag, cdpFlag, chromeArgFlag, headedFlag, headlessFlag, ignoreDefaultChromeArgFlag, localFlag, noDefaultChromeArgsFlag, remoteFlag, sessionFlag, sessionName, targetIdFlag, } from "./flags.js";
3
3
  import { getDriverStatus } from "./daemon/client.js";
4
- import { resolveConnectionTarget } from "./mode.js";
4
+ import { hasChromeArgFlags, resolveConnectionTarget, } from "./mode.js";
5
5
  import { outputJson } from "../output.js";
6
6
  import { runDriverCommandWithTarget } from "./runtime.js";
7
7
  export const driverCommandFlags = {
8
8
  "auto-connect": autoConnectFlag,
9
9
  cdp: cdpFlag,
10
+ "chrome-arg": chromeArgFlag,
10
11
  headed: headedFlag,
11
12
  headless: headlessFlag,
13
+ "ignore-default-chrome-arg": ignoreDefaultChromeArgFlag,
12
14
  local: localFlag,
15
+ "no-default-chrome-args": noDefaultChromeArgsFlag,
13
16
  remote: remoteFlag,
14
17
  session: sessionFlag,
15
18
  "target-id": targetIdFlag,
@@ -52,6 +55,7 @@ export function hasExplicitDriverTarget(flags) {
52
55
  flags.remote ||
53
56
  flags["auto-connect"] ||
54
57
  flags.cdp ||
58
+ hasChromeArgFlags(flags) ||
55
59
  flags["target-id"] ||
56
60
  flags.headed ||
57
61
  flags.headless);
@@ -60,6 +64,7 @@ function hasModeOnlyFlag(flags) {
60
64
  return Boolean((flags.local || flags.remote) &&
61
65
  !flags["auto-connect"] &&
62
66
  !flags.cdp &&
67
+ !hasChromeArgFlags(flags) &&
63
68
  !flags["target-id"] &&
64
69
  !flags.headed &&
65
70
  !flags.headless &&
@@ -1,3 +1,4 @@
1
+ import { DriverError } from "../errors.js";
1
2
  export function emptyRefMaps() {
2
3
  return { urlMap: {}, xpathMap: {} };
3
4
  }
@@ -24,7 +25,7 @@ export function resolveSelector(selector, refMaps) {
24
25
  return selector;
25
26
  const xpath = refMaps.xpathMap[ref];
26
27
  if (!xpath) {
27
- throw new Error(`Unknown ref "${ref}" - run browse snapshot first to populate refs (have ${Object.keys(refMaps.xpathMap).length} refs).`);
28
+ throw new DriverError(`Unknown ref "${ref}" - run browse snapshot first to populate refs (have ${Object.keys(refMaps.xpathMap).length} refs).`, { code: "stale_ref" });
28
29
  }
29
30
  return xpath;
30
31
  }
@@ -1,7 +1,7 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import { promises as fs } from "node:fs";
3
3
  import net from "node:net";
4
- import { fail } from "../../errors.js";
4
+ import { CommandFailure, fail } from "../../errors.js";
5
5
  import { targetsCompatible } from "../mode.js";
6
6
  import { cleanupDaemonFiles, ensureRuntimeDir, getLockPath, getPidPath, getSocketPath, PRIVATE_FILE_MODE, } from "./paths.js";
7
7
  import { isProcessAlive } from "./process.js";
@@ -15,7 +15,7 @@ export async function ensureDriverDaemon({ session, target, }) {
15
15
  }
16
16
  const locked = await acquireLock(session);
17
17
  if (!locked) {
18
- fail(`Timed out waiting for driver daemon lock for session "${session}".`);
18
+ fail(`Timed out waiting for driver daemon lock for session "${session}".`, 1, { resultCode: "daemon_lock_timeout" });
19
19
  }
20
20
  try {
21
21
  const afterLock = await tryDriverStatus(session);
@@ -24,7 +24,7 @@ export async function ensureDriverDaemon({ session, target, }) {
24
24
  return;
25
25
  }
26
26
  if (await isDaemonPidAlive(session)) {
27
- fail(`Driver daemon session "${session}" is running but not responding. Run browse stop --session ${session} --force to clean it up.`);
27
+ fail(`Driver daemon session "${session}" is running but not responding. Run browse stop --session ${session} --force to clean it up.`, 1, { resultCode: "daemon_unresponsive" });
28
28
  }
29
29
  spawnDaemon(session, target);
30
30
  await waitForSocketReady(getSocketPath(session), 30_000);
@@ -123,7 +123,7 @@ async function sendDriverRequest(session, request) {
123
123
  return new Error(`Driver daemon session "${session}" closed ${detail}.`);
124
124
  };
125
125
  const timeout = setTimeout(() => {
126
- failRequest(new Error(`Timed out waiting for driver daemon session "${session}".`));
126
+ failRequest(new CommandFailure(`Timed out waiting for driver daemon session "${session}".`, 1, { resultCode: "daemon_socket_timeout" }));
127
127
  }, 35_000);
128
128
  socket.on("connect", () => {
129
129
  socket.write(`${JSON.stringify(request)}\n`);
@@ -136,7 +136,12 @@ async function sendDriverRequest(session, request) {
136
136
  try {
137
137
  const response = ResponseSchema.parse(JSON.parse(buffer.slice(0, newline)));
138
138
  if (response.type === "error") {
139
- failRequest(new Error(response.error));
139
+ failRequest(new CommandFailure(response.error, 1, {
140
+ ...(response.code ? { resultCode: response.code } : {}),
141
+ ...(response.httpStatus !== undefined
142
+ ? { httpStatus: response.httpStatus }
143
+ : {}),
144
+ }));
140
145
  return;
141
146
  }
142
147
  completeRequest(response.data);
@@ -161,7 +166,9 @@ async function sendDriverRequest(session, request) {
161
166
  function spawnDaemon(session, target) {
162
167
  const entrypoint = process.argv[1];
163
168
  if (!entrypoint) {
164
- fail("Unable to locate browse CLI entrypoint for daemon startup.");
169
+ fail("Unable to locate browse CLI entrypoint for daemon startup.", 1, {
170
+ resultCode: "daemon_spawn_failed",
171
+ });
165
172
  }
166
173
  const child = spawn(process.execPath, [
167
174
  entrypoint,
@@ -32,7 +32,9 @@ export const SuccessResponseSchema = z.object({
32
32
  type: z.literal("success"),
33
33
  });
34
34
  export const ErrorResponseSchema = z.object({
35
+ code: z.string().optional(),
35
36
  error: z.string(),
37
+ httpStatus: z.number().optional(),
36
38
  id: z.string().optional(),
37
39
  type: z.literal("error"),
38
40
  });
@@ -1,5 +1,6 @@
1
1
  import net from "node:net";
2
2
  import readline from "node:readline";
3
+ import { DriverError } from "../errors.js";
3
4
  import { DriverSessionManager } from "../session-manager.js";
4
5
  import { cleanupDaemonFiles, ensureRuntimeDir, getPidPath, getSocketPath, writePrivateFile, } from "./paths.js";
5
6
  import { parseRequest, serializeResponse, } from "./protocol.js";
@@ -83,7 +84,7 @@ async function handleLine(line, socket, manager) {
83
84
  request = parseRequest(line);
84
85
  }
85
86
  catch (error) {
86
- await writeResponse(socket, { error: formatError(error), type: "error" });
87
+ await writeResponse(socket, { ...formatError(error), type: "error" });
87
88
  return false;
88
89
  }
89
90
  try {
@@ -124,7 +125,7 @@ async function handleLine(line, socket, manager) {
124
125
  }
125
126
  catch (error) {
126
127
  await writeResponse(socket, {
127
- error: formatError(error),
128
+ ...formatError(error),
128
129
  id: request.id,
129
130
  type: "error",
130
131
  });
@@ -161,5 +162,15 @@ function endSocket(socket) {
161
162
  });
162
163
  }
163
164
  function formatError(error) {
164
- return error instanceof Error ? error.message : String(error);
165
+ const message = error instanceof Error ? error.message : String(error);
166
+ if (error instanceof DriverError) {
167
+ return {
168
+ code: error.code,
169
+ error: message,
170
+ ...(error.httpStatus !== undefined
171
+ ? { httpStatus: error.httpStatus }
172
+ : {}),
173
+ };
174
+ }
175
+ return { error: message };
165
176
  }
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Typed driver error. The daemon serializes `code`/`httpStatus` into error
3
+ * responses so the client can record a telemetry result code and agents get
4
+ * a stable, machine-readable failure reason alongside the human message.
5
+ */
6
+ export class DriverError extends Error {
7
+ code;
8
+ httpStatus;
9
+ constructor(message, options) {
10
+ super(message, options.cause === undefined ? {} : { cause: options.cause });
11
+ this.name = "DriverError";
12
+ this.code = options.code;
13
+ if (options.httpStatus !== undefined)
14
+ this.httpStatus = options.httpStatus;
15
+ }
16
+ }
@@ -27,6 +27,19 @@ export const targetIdFlag = Flags.string({
27
27
  description: "Select a specific CDP target when attaching to an existing browser.",
28
28
  helpValue: "<target-id>",
29
29
  });
30
+ export const chromeArgFlag = Flags.string({
31
+ description: "Add a Chrome launch arg for managed local sessions. Repeatable.",
32
+ helpValue: "<flag>",
33
+ multiple: true,
34
+ });
35
+ export const ignoreDefaultChromeArgFlag = Flags.string({
36
+ description: "Drop one of Chrome's default launch args for managed local sessions. Repeatable.",
37
+ helpValue: "<flag>",
38
+ multiple: true,
39
+ });
40
+ export const noDefaultChromeArgsFlag = Flags.boolean({
41
+ description: "Launch managed local Chrome without any of its default launch args.",
42
+ });
30
43
  export function sessionName(value) {
31
44
  return value ?? process.env.BROWSE_SESSION ?? "default";
32
45
  }
@@ -1,3 +1,4 @@
1
+ import { isDeepStrictEqual } from "node:util";
1
2
  import { fail } from "../errors.js";
2
3
  import { getRemote } from "./remote-binding.js";
3
4
  import { resolveWsTarget } from "./resolve-ws.js";
@@ -11,10 +12,25 @@ function resolveHeadless(flags) {
11
12
  return true;
12
13
  return true;
13
14
  }
15
+ export function hasChromeArgFlags(flags) {
16
+ return chromeArgFlagsInUse(flags).length > 0;
17
+ }
18
+ function chromeArgFlagsInUse(flags) {
19
+ const names = [];
20
+ if (flags["chrome-arg"]?.length)
21
+ names.push("--chrome-arg");
22
+ if (flags["ignore-default-chrome-arg"]?.length)
23
+ names.push("--ignore-default-chrome-arg");
24
+ if (flags["no-default-chrome-args"])
25
+ names.push("--no-default-chrome-args");
26
+ return names;
27
+ }
14
28
  export async function resolveConnectionTarget(flags) {
29
+ const chromeArgFlags = chromeArgFlagsInUse(flags);
15
30
  if (flags.cdp) {
16
31
  failOnConflictingFlags("--cdp", [
17
32
  flags["auto-connect"] ? "--auto-connect" : null,
33
+ ...chromeArgFlags,
18
34
  flags.local ? "--local" : null,
19
35
  flags.remote ? "--remote" : null,
20
36
  flags.headed ? "--headed" : null,
@@ -31,6 +47,7 @@ export async function resolveConnectionTarget(flags) {
31
47
  }
32
48
  if (flags["auto-connect"]) {
33
49
  failOnConflictingFlags("--auto-connect", [
50
+ ...chromeArgFlags,
34
51
  flags.local ? "--local" : null,
35
52
  flags.remote ? "--remote" : null,
36
53
  flags.headed ? "--headed" : null,
@@ -43,36 +60,76 @@ export async function resolveConnectionTarget(flags) {
43
60
  }
44
61
  if (flags.remote) {
45
62
  failOnConflictingFlags("--remote", [
63
+ ...chromeArgFlags,
46
64
  flags.headed ? "--headed" : null,
47
65
  flags.headless ? "--headless" : null,
48
66
  ]);
49
67
  return (await getRemote()).resolveExplicitRemoteTarget(flags);
50
68
  }
51
69
  if (flags.local) {
52
- return { kind: "managed-local", headless: resolveHeadless(flags) };
70
+ return managedLocalTarget(resolveHeadless(flags), resolveChromeArgs(flags));
53
71
  }
54
72
  const autoRemote = (await getRemote()).autoSelectRemoteTarget();
55
73
  if (autoRemote) {
56
74
  failOnConflictingFlags("remote mode", [
75
+ ...chromeArgFlags,
57
76
  flags.headed ? "--headed" : null,
58
77
  flags.headless ? "--headless" : null,
59
78
  ]);
60
79
  return autoRemote;
61
80
  }
62
- return { kind: "managed-local", headless: resolveHeadless(flags) };
81
+ return managedLocalTarget(resolveHeadless(flags), resolveChromeArgs(flags));
82
+ }
83
+ function managedLocalTarget(headless, chromeArgs) {
84
+ return {
85
+ ...(chromeArgs.args?.length ? { chromeArgs: chromeArgs.args } : {}),
86
+ ...(chromeArgs.ignoreDefaultArgs !== undefined
87
+ ? { ignoreDefaultArgs: chromeArgs.ignoreDefaultArgs }
88
+ : {}),
89
+ kind: "managed-local",
90
+ headless,
91
+ };
63
92
  }
64
93
  function failOnConflictingFlags(flag, candidates) {
65
94
  const conflicts = candidates.filter((candidate) => Boolean(candidate));
66
95
  if (conflicts.length > 0)
67
96
  fail(`${flag} cannot be combined with ${conflicts.join(", ")}.`);
68
97
  }
98
+ function resolveChromeArgs(flags) {
99
+ const args = flags["chrome-arg"]?.filter((arg) => arg.length > 0);
100
+ const ignoreDefaults = flags["ignore-default-chrome-arg"]?.filter((arg) => arg.length > 0);
101
+ const noDefaults = flags["no-default-chrome-args"] === true;
102
+ if (noDefaults && ignoreDefaults?.length) {
103
+ fail("--no-default-chrome-args cannot be combined with --ignore-default-chrome-arg.");
104
+ }
105
+ const resolved = {};
106
+ if (args?.length)
107
+ resolved.args = args;
108
+ if (noDefaults) {
109
+ resolved.ignoreDefaultArgs = true;
110
+ }
111
+ else if (ignoreDefaults?.length) {
112
+ resolved.ignoreDefaultArgs = ignoreDefaults;
113
+ }
114
+ return resolved;
115
+ }
69
116
  export function targetsCompatible(left, right) {
70
117
  if (left.kind !== right.kind)
71
118
  return false;
72
119
  if (left.kind === "managed-local" && right.kind === "managed-local")
73
- return left.headless === right.headless;
120
+ return (left.headless === right.headless &&
121
+ chromeArgsEqual(left.chromeArgs, right.chromeArgs) &&
122
+ ignoreDefaultArgsEqual(left.ignoreDefaultArgs, right.ignoreDefaultArgs));
74
123
  if (left.kind === "cdp" && right.kind === "cdp") {
75
124
  return left.endpoint === right.endpoint && left.targetId === right.targetId;
76
125
  }
77
126
  return true;
78
127
  }
128
+ function chromeArgsEqual(left, right) {
129
+ return isDeepStrictEqual(left ?? [], right ?? []);
130
+ }
131
+ function ignoreDefaultArgsEqual(left, right) {
132
+ if (left === true || right === true)
133
+ return left === right;
134
+ return chromeArgsEqual(Array.isArray(left) ? left : undefined, Array.isArray(right) ? right : undefined);
135
+ }
@@ -13,6 +13,21 @@ export function autoSelectRemoteTarget() {
13
13
  export function remoteStagehandOptions() {
14
14
  throw new Error(DISABLED_MESSAGE);
15
15
  }
16
+ export function classifyRemoteInitError(error) {
17
+ // Remote targets cannot be selected in a local-only build, so this is only
18
+ // reachable if a remote error somehow surfaces anyway; preserve it as-is.
19
+ return {
20
+ code: "remote_session_create_failed",
21
+ message: error instanceof Error ? error.message : String(error),
22
+ };
23
+ }
24
+ export function driverInitHints() {
25
+ // Key-free variants: a local-only artifact must not mention the API key.
26
+ return {
27
+ 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>.",
28
+ repeatedInitFailure: " (failing repeatedly — check your browser setup or run browse doctor)",
29
+ };
30
+ }
16
31
  export function remoteDoctorCheck() {
17
32
  return { ok: true, message: "remote disabled (local-only build)" };
18
33
  }
@@ -1,3 +1,4 @@
1
+ import { StatusCodes } from "http-status-codes";
1
2
  /**
2
3
  * Real Browserbase capability. This is the ONLY module that reads
3
4
  * `BROWSERBASE_API_KEY`; it is excluded from `build:local-only` so that
@@ -25,6 +26,40 @@ export function remoteStagehandOptions() {
25
26
  verbose: 0,
26
27
  };
27
28
  }
29
+ /**
30
+ * Map a failed remote `stagehand.init()` to an actionable message and a
31
+ * stable result code. Browserbase SDK errors carry an HTTP `status`.
32
+ */
33
+ export function classifyRemoteInitError(error) {
34
+ const status = error?.status;
35
+ const httpStatus = typeof status === "number" ? status : undefined;
36
+ const original = error instanceof Error ? error.message : String(error);
37
+ if (httpStatus === StatusCodes.UNAUTHORIZED) {
38
+ return {
39
+ code: "remote_auth_401",
40
+ httpStatus,
41
+ 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.",
42
+ };
43
+ }
44
+ if (httpStatus === StatusCodes.FORBIDDEN) {
45
+ return {
46
+ code: "remote_auth_403",
47
+ httpStatus,
48
+ 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.",
49
+ };
50
+ }
51
+ return {
52
+ code: "remote_session_create_failed",
53
+ ...(httpStatus !== undefined ? { httpStatus } : {}),
54
+ message: `Failed to start a remote (Browserbase) session: ${original}\nRun browse doctor to diagnose remote connectivity.`,
55
+ };
56
+ }
57
+ export function driverInitHints() {
58
+ return {
59
+ 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.",
60
+ repeatedInitFailure: " (failing repeatedly — fix BROWSERBASE_API_KEY, use --local, or run browse doctor)",
61
+ };
62
+ }
28
63
  export function remoteDoctorCheck(env) {
29
64
  if (env.BROWSERBASE_API_KEY) {
30
65
  return { ok: true, message: "BROWSERBASE_API_KEY is set" };