browse 0.9.4 → 0.9.5-alpha-04c8ee4

package/README.md

@@ -277,10 +277,19 @@ export BROWSERBASE_API_KEY=bb_live_...
 
 Local driver commands (`--local`) work without an API key.
 
+`browse` also auto-loads a `.env` file from the current directory on startup, and prints a
+one-time deprecation warning to stderr when it actually pulls a variable from `.env` this way.
+This is deprecated because a CLI used across many unrelated projects can silently pick up a
+stale key from the wrong project's `.env`; a future release will disable auto-loading by
+default so `browse` only reads `process.env`. Set `BROWSE_LOAD_DOTENV=0` (or `false`/`no`) to
+opt out of `.env` auto-loading now, ahead of that change, or `BROWSE_LOAD_DOTENV=1` to keep
+auto-loading with no warning.
+
 | Variable | Description |
 |----------|-------------|
 | `BROWSERBASE_API_KEY` | Enables `--remote` sessions and all `browse cloud` / `functions` commands |
 | `BROWSE_SESSION` | Default session name (alternative to `-s, --session`) |
+| `BROWSE_LOAD_DOTENV` | Controls `.env` auto-loading: unset = load + warn once (default, deprecated), `0`/`false`/`no` = skip loading, anything else = load silently |
 
 ## Links
 

package/bin/run.js

@@ -1,5 +1,31 @@
 #!/usr/bin/env node
-import "dotenv/config";
+import { config as loadDotenvConfig } from "dotenv";
+
+// `BROWSE_LOAD_DOTENV` controls whether `browse` auto-loads a `.env` file
+// from the current working directory. This is deprecated: a future release
+// will flip the default to "off" so `browse` only reads `process.env`,
+// matching how most CLIs used across many unrelated projects behave. Until
+// then we keep loading `.env` by default (unset behaves exactly as before)
+// but warn once when we actually pull a value from it, so users relying on
+// the implicit default get a heads-up before the default changes.
+const dotenvToggle = process.env.BROWSE_LOAD_DOTENV;
+const dotenvOptedOut =
+  dotenvToggle !== undefined &&
+  ["0", "false", "no"].includes(dotenvToggle.toLowerCase());
+
+if (!dotenvOptedOut) {
+  const keysBeforeLoad = new Set(Object.keys(process.env));
+  const { parsed } = loadDotenvConfig();
+  const appliedFromDotenv = Object.keys(parsed ?? {}).filter(
+    (key) => !keysBeforeLoad.has(key),
+  );
+
+  if (appliedFromDotenv.length > 0 && dotenvToggle === undefined) {
+    console.error(
+      `[browse] Loaded ${appliedFromDotenv.join(", ")} from .env. Auto-loading .env is deprecated and will be disabled by default in a future release -- export these variables in your shell instead, or set BROWSE_LOAD_DOTENV=1 to keep this behavior explicitly once that happens. Set BROWSE_LOAD_DOTENV=0 to opt out today. Run \`browse doctor\` to check for conflicts with your shell environment.`,
+    );
+  }
+}
 
 globalThis.oclif = {
   ...globalThis.oclif,

package/dist/commands/cloud/sessions/logs.js

@@ -1,19 +1,46 @@
-import { Args } from "@oclif/core";
+import { Args, Flags } from "@oclif/core";
 import { createBrowserbaseClient, outputJson, withBrowserbaseApi, } from "../../../lib/cloud/api.js";
 import { apiCommonFlags, toApiOptions } from "../../../lib/cloud/flags.js";
+import { reduceLogs } from "../../../lib/cloud/reduce-logs.js";
 import { BrowseCommand } from "../../../base.js";
 export default class SessionsLogs extends BrowseCommand {
     static description = "Get Browserbase session logs.";
-    static examples = ["browse cloud sessions logs <session-id>"];
+    static examples = [
+        "browse cloud sessions logs <session-id>",
+        "browse cloud sessions logs <session-id> --only-errors",
+        "browse cloud sessions logs <session-id> --only-errors --failed-requests",
+    ];
     static args = {
         id: Args.string({ required: true, description: "Session ID." }),
     };
-    static flags = { ...apiCommonFlags };
+    static flags = {
+        ...apiCommonFlags,
+        "only-errors": Flags.boolean({
+            description: "Return only the high-signal error records (console errors/exceptions, HTTP 4xx/5xx, network failures) instead of the full CDP firehose.",
+            default: false,
+        }),
+        "failed-requests": Flags.boolean({
+            description: "With --only-errors, narrow to failed / error-status network requests only.",
+            default: false,
+            dependsOn: ["only-errors"],
+        }),
+    };
     async run() {
         const { args, flags } = await this.parse(SessionsLogs);
         await withBrowserbaseApi("sessions", async () => {
             const client = createBrowserbaseClient(toApiOptions(flags));
-            outputJson(await client.sessions.logs.list(args.id));
+            const raw = await client.sessions.logs.list(args.id);
+            if (flags["only-errors"]) {
+                const arr = Array.isArray(raw)
+                    ? raw
+                    : (raw?.data ?? []);
+                outputJson(reduceLogs(arr, {
+                    failedRequests: flags["failed-requests"],
+                }));
+            }
+            else {
+                outputJson(raw);
+            }
         });
     }
 }

package/dist/commands/skills/show.js

@@ -0,0 +1,20 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { BrowseCommand } from "../../base.js";
+import { fail } from "../../lib/errors.js";
+import { bundledCliSkillPath } from "../../lib/skills/install.js";
+export default class SkillsShow extends BrowseCommand {
+    static description = "Print the bundled browse skill (usage patterns, workflows, gotchas) to stdout. Run before using browse in an agent.";
+    static examples = ["browse skills show"];
+    async run() {
+        const skillMdPath = join(bundledCliSkillPath(), "SKILL.md");
+        let contents;
+        try {
+            contents = await readFile(skillMdPath, "utf8");
+        }
+        catch (error) {
+            fail(`Could not read the bundled browse skill (SKILL.md): ${error.message}`, 1, { resultCode: "skill_show_missing" });
+        }
+        this.log(contents);
+    }
+}

package/dist/help.js

@@ -0,0 +1,19 @@
+import { Help } from "@oclif/core";
+// Custom root-help formatter so `browse --help` (and bare `browse`) lead with
+// a short block pointing agents at the bundled skill, ahead of oclif's
+// auto-generated VERSION/USAGE/DESCRIPTION/COMMANDS sections. Only the root
+// help view is customized -- individual `browse <command> --help` views are
+// unaffected.
+const AGENT_HEADER = `Start here (for AI agents):
+  browse skills show
+
+  The bundled skill ships with the CLI (always version-matched) and covers
+  workflows, session management, and common failure recovery. Prefer it over
+  guessing commands from flag docs alone.
+`;
+export default class BrowseHelp extends Help {
+    async showRootHelp() {
+        this.log(AGENT_HEADER);
+        await super.showRootHelp();
+    }
+}

package/dist/lib/cloud/reduce-logs.js

@@ -0,0 +1,107 @@
+// Deterministic reducer for `browse cloud sessions logs --only-errors`.
+// Turns the raw CDP firehose (~hundreds of events per session) into the high-signal error slice:
+// console errors/warnings/asserts, uncaught exceptions, HTTP 4xx/5xx responses, and net-level load
+// failures. No LLM — pure allowlist + severity/status filter + field projection + dedupe + stack trim.
+function paramsOf(e) {
+    try {
+        const parsed = JSON.parse(e.request?.rawBody ?? "{}");
+        return parsed.params ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+// Keep the message line + the app (`/src/`) stack frames; drop framework/vendor frames and hosts.
+function trimStack(s) {
+    return (s || "")
+        .split("\n")
+        .filter((l, i) => i === 0 || (/\/src\//.test(l) && !/node_modules|\.vite/.test(l)))
+        .slice(0, 4)
+        .map((l) => l
+        .replace(/https?:\/\/[^/)]+/g, "")
+        .replace(/\?[^):]*/, "")
+        .trim())
+        .join("\n");
+}
+export function reduceLogs(raw, opts = {}) {
+    const out = [];
+    const seen = new Set();
+    const push = (rec) => {
+        const k = JSON.stringify(rec);
+        if (!seen.has(k)) {
+            seen.add(k);
+            out.push(rec);
+        }
+    };
+    for (const e of raw) {
+        const p = paramsOf(e);
+        const m = e.method;
+        const responseStatus = p.response?.status;
+        let rec = null;
+        if (m === "Runtime.consoleAPICalled" &&
+            typeof p.type === "string" &&
+            ["error", "warning", "assert"].includes(p.type)) {
+            const text = (Array.isArray(p.args) ? p.args : [])
+                .map((a) => a && typeof a === "object" ? a.description || a.value || "" : "")
+                .filter(Boolean)
+                .join(" ");
+            if (text && !/^%[os]/.test(text))
+                rec = {
+                    kind: `console.${p.type}`,
+                    domain: "Runtime",
+                    severity: p.type,
+                    text: trimStack(text),
+                };
+        }
+        else if (m === "Runtime.exceptionThrown") {
+            rec = {
+                kind: "exception",
+                domain: "Runtime",
+                severity: "error",
+                text: trimStack(p.exceptionDetails?.exception?.description ??
+                    p.exceptionDetails?.text ??
+                    ""),
+            };
+        }
+        else if (m === "Log.entryAdded" &&
+            typeof p.entry?.level === "string" &&
+            ["error", "warning"].includes(p.entry?.level)) {
+            rec = {
+                kind: `log.${p.entry.level}`,
+                domain: "Log",
+                severity: p.entry.level,
+                text: p.entry.text,
+                url: p.entry.url,
+            };
+        }
+        else if (m === "Network.responseReceived" &&
+            typeof responseStatus === "number" &&
+            responseStatus >= 400) {
+            rec = {
+                kind: "network",
+                domain: "Network",
+                status: responseStatus,
+                url: p.response?.url,
+                type: p.type,
+            };
+        }
+        else if (m === "Network.loadingFailed" &&
+            p.errorText !== "net::ERR_ABORTED") {
+            rec = {
+                kind: "network.failed",
+                domain: "Network",
+                error: p.errorText,
+                type: p.type,
+            };
+        }
+        else {
+            continue; // everything else (byte-chunk / lifecycle events) is noise
+        }
+        if (!rec)
+            continue; // e.g. a console.error whose text was empty / formatting noise
+        if (opts.failedRequests && rec.domain !== "Network")
+            continue;
+        push(rec);
+    }
+    return out;
+}

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

@@ -70,6 +70,12 @@ export async function stopDriverDaemon(session, force = false) {
         });
     }
     catch (error) {
+        if (!force &&
+            error instanceof CommandFailure &&
+            error.telemetry.resultCode === "daemon_not_running") {
+            await cleanupStoppedDaemonFiles(session);
+            return { stopped: false };
+        }
         if (!force)
             throw error;
         await cleanupDaemonFiles(session);
@@ -154,6 +160,10 @@ async function sendDriverRequest(session, request) {
             }
         });
         socket.on("error", (error) => {
+            if (isDaemonUnavailableError(error)) {
+                failRequest(daemonNotRunningError(session, request));
+                return;
+            }
             failRequest(error);
         });
         socket.on("end", () => {
@@ -219,6 +229,20 @@ async function cleanupStaleDaemonFiles(session) {
         return;
     await cleanupDaemonFiles(session, { includeLock: false });
 }
+async function cleanupStoppedDaemonFiles(session) {
+    const locked = await acquireLock(session);
+    if (!locked)
+        return;
+    try {
+        const status = await tryDriverStatus(session);
+        if (status?.session === session)
+            return;
+        await cleanupDaemonFiles(session, { includeLock: false });
+    }
+    finally {
+        await releaseLock(session);
+    }
+}
 async function acquireLock(session, timeoutMs = 10_000) {
     const lockPath = getLockPath(session);
     const start = Date.now();
@@ -281,3 +305,20 @@ async function removeStaleLock(lockPath) {
 function requestId() {
     return `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 }
+function isDaemonUnavailableError(error) {
+    const code = error.code;
+    return code === "ECONNREFUSED" || code === "ENOENT";
+}
+function daemonNotRunningError(session, request) {
+    const sessionFlag = session === "default" ? "" : ` --session ${formatCommandArgument(session)}`;
+    const startCommand = request.type === "open"
+        ? `browse open ${formatCommandArgument(request.url)}${sessionFlag}`
+        : `browse open <url>${sessionFlag}`;
+    return new CommandFailure(`Driver daemon session "${session}" is not running. Start it with: ${startCommand}`, 1, { resultCode: "daemon_not_running" });
+}
+function formatCommandArgument(value) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    const escaped = value.replaceAll("'", "'\"'\"'");
+    return `'${escaped}'`;
+}

package/dist/lib/skills/install.js

@@ -167,7 +167,7 @@ function localSkillPath(skillId) {
     const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
     return join(configHome, "browserbase", "skills", skillId.domain, skillId.task);
 }
-function bundledCliSkillPath() {
+export function bundledCliSkillPath() {
     return join(packageRoot(), "skills", "browse");
 }
 function packageRoot() {

package/oclif.manifest.json

@@ -4536,6 +4536,29 @@
         "list.js"
       ]
     },
+    "skills:show": {
+      "aliases": [],
+      "args": {},
+      "description": "Print the bundled browse skill (usage patterns, workflows, gotchas) to stdout. Run before using browse in an agent.",
+      "examples": [
+        "browse skills show"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "skills:show",
+      "pluginAlias": "browse",
+      "pluginName": "browse",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "skills",
+        "show.js"
+      ]
+    },
     "tab:close": {
       "aliases": [],
       "args": {
@@ -6177,7 +6200,9 @@
       },
       "description": "Get Browserbase session logs.",
       "examples": [
-        "browse cloud sessions logs <session-id>"
+        "browse cloud sessions logs <session-id>",
+        "browse cloud sessions logs <session-id> --only-errors",
+        "browse cloud sessions logs <session-id> --only-errors --failed-requests"
       ],
       "flags": {
         "api-key": {
@@ -6195,6 +6220,21 @@
           "helpValue": "<baseUrl>",
           "multiple": false,
           "type": "option"
+        },
+        "only-errors": {
+          "description": "Return only the high-signal error records (console errors/exceptions, HTTP 4xx/5xx, network failures) instead of the full CDP firehose.",
+          "name": "only-errors",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "failed-requests": {
+          "dependsOn": [
+            "only-errors"
+          ],
+          "description": "With --only-errors, narrow to failed / error-status network requests only.",
+          "name": "failed-requests",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -6398,5 +6438,5 @@
       ]
     }
   },
-  "version": "0.9.4"
+  "version": "0.9.5"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browse",
-  "version": "0.9.4",
+  "version": "0.9.5-alpha-04c8ee4",
   "description": "Unified Browserbase CLI for browser automation and cloud APIs.",
   "type": "module",
   "private": false,
@@ -24,6 +24,7 @@
     "bin": "browse",
     "dirname": "browse",
     "commands": "./dist/commands",
+    "helpClass": "./dist/help.js",
     "hooks": {
       "init": "./dist/hooks/init.js",
       "prerun": "./dist/hooks/prerun.js",
@@ -100,7 +101,7 @@
     "tsx": "^4.20.6",
     "ws": "^8.18.3",
     "zod": "^4.2.1",
-    "@browserbasehq/stagehand": "3.6.0"
+    "@browserbasehq/stagehand": "3.7.1"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/skills/browse/SKILL.md

@@ -65,12 +65,16 @@ browse open https://example.com --cdp ws://127.0.0.1:9222/devtools/browser/<id>
 
 Use local mode for development, localhost, trusted sites, and fast iteration. Use `--auto-connect` only when the user explicitly wants to attach to an already-running debuggable Chrome session with existing cookies or login state; use `--local` when no debuggable Chrome is available. Use remote mode when Browserbase credentials are available and the site needs hosted browser infrastructure, Verified browser mode, CAPTCHA solving, proxies, or session persistence.
 
+`--local` requires Chrome or Chromium already installed on the machine. In containers, CI, and sandboxes with no browser installed, use `--remote` instead of `--local`. If `--local` fails with "No Chrome or Chromium found" and `BROWSERBASE_API_KEY` is set, switch to `--remote` — do not retry `--local`.
+
 For a Verified and/or proxied remote session, add `--verified` and/or `--proxies` to `--remote` — a single command that keeps the Browserbase session identity, so `browse status` and `browse doctor` report the session ID and live-view URL. `--verified` requires a Browserbase Scale plan. These flags only apply to `--remote` and are sticky for the session's lifetime, like `--headed`. Reach for `browse cloud sessions create` + `--cdp` only when you need session options `open` doesn't expose (region, keep-alive, contexts).
 
 Choose headed/headless and local/remote mode when starting a session. A running session keeps its mode: passing a conflicting flag such as `--headed` to an already-running headless session fails until you run `browse stop --session <name>` or target a different session.
 
 Use named sessions for any non-trivial work, especially when multiple agents or parallel tasks may run at once. Every browser command accepts `--session <name>` (or `-s <name>`); the `BROWSE_SESSION` env var sets the default, and commands without either share the `default` session.
 
+If `BROWSE_SESSION` is already set in the environment, every command already targets that session — do not pass `--session` or invent a new name. An explicit `--session <name>` always overrides `BROWSE_SESSION` for that command, so only pass it to deliberately target a different session.
+
 ```bash
 browse open https://example.com --session research --local
 browse snapshot --session research
@@ -82,6 +86,8 @@ Remote browser and cloud API commands require:
 export BROWSERBASE_API_KEY=...
 ```
 
+The CLI forwards `BROWSERBASE_API_KEY` from the caller on every browser command, even when the daemon is already running. If a remote command first fails because the key was missing, set or export the key and retry the command; do not restart the daemon just to refresh the environment.
+
 ## Browser Automation Workflow
 
 Start by opening the page, then inspect state, act, and verify.
@@ -196,6 +202,8 @@ browse stop --force
 
 Use `browse doctor` before debugging a broken browser session. Use `browse doctor --json` when another agent or CI needs structured diagnostics.
 
+`browse stop` is idempotent. If no daemon is running, `{ "stopped": false }` with exit code `0` is successful cleanup, not an error.
+
 If a page command reports that no active page is available, inspect and recover the named session:
 
 ```bash
@@ -356,6 +364,7 @@ JSON output includes every match with full descriptions and ignores `--limit`; `
 ## Troubleshooting
 
 - "No active page": run `browse status --session <name>`, then `browse open <url> --session <name>` or `browse tab new <url> --session <name>`; use `browse stop --force` if the daemon is stale.
+- "Driver daemon ... is not running": run the exact `browse open` command printed by the error. Browser commands start the daemon automatically.
 - Chrome not found: use `--remote` with Browserbase credentials, install Chrome, or attach with `--cdp`.
 - Action fails: run `browse snapshot` and use a visible ref from the current page state.
 - 401 Unauthorized on `open`, `get`, or other driver commands: a set `BROWSERBASE_API_KEY` makes `browse` default to remote mode. Fix the key at https://browserbase.com/settings, unset it, or pass `--local` to run a managed local browser (no key needed).