browse 0.8.5 → 0.9.0-alpha-263e4d4

package/dist/base.js

@@ -1,7 +1,17 @@
 import { Command } from "@oclif/core";
 import { CommandFailure } from "./lib/errors.js";
+import { setCliVersion } from "./lib/identity.js";
 import { recordCommandError } from "./lib/telemetry.js";
 export class BrowseCommand extends Command {
+    async init() {
+        await super.init();
+        // Seed the CLI version from oclif's Config (the single source of truth) so
+        // non-command contexts — remote session userMetadata and cloud API headers
+        // — can stamp the real version without any filesystem read. This runs in
+        // every process before run(), including the background `browse daemon` that
+        // creates Browserbase sessions, so cli_version never regresses to "unknown".
+        setCliVersion(this.config.version);
+    }
     async catch(err) {
         if (err instanceof CommandFailure) {
             recordCommandError("runtime", "COMMAND_FAILURE", err.telemetry);

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

@@ -2,6 +2,7 @@ import { Flags } from "@oclif/core";
 import { createBrowserbaseClient, deepMerge, outputJson, resolveBody, withBrowserbaseApi, } from "../../../lib/cloud/api.js";
 import { apiCommonFlags, toApiOptions } from "../../../lib/cloud/flags.js";
 import { fail } from "../../../lib/errors.js";
+import { getCliVersion, resolveInstallId, toMetadataValue, } from "../../../lib/identity.js";
 import { BrowseCommand } from "../../../base.js";
 const REGIONS = [
     "us-west-2",
@@ -56,6 +57,39 @@ function buildSessionCreateBody(flags) {
     }
     return body;
 }
+/**
+ * Stamp anonymous CLI attribution onto the session-create `userMetadata` so
+ * every CLI-created cloud session is attributable to the CLI (matching the
+ * driver `open --remote` path). Any user-supplied `userMetadata` (via --body or
+ * --stdin) is preserved; our attribution keys (browse_cli/install_id/
+ * cli_version) are authoritative and override caller values for those keys.
+ *
+ * Resolving the install id is best-effort and never throws; if it can't be
+ * resolved we still send browse_cli + cli_version. Values are run through
+ * toMetadataValue() so the session-create validator never 400s on a stray
+ * character or an over-length value.
+ */
+async function applyCliAttribution(body) {
+    const rawExisting = body.userMetadata && typeof body.userMetadata === "object"
+        ? body.userMetadata
+        : {};
+    // Strip any caller-supplied install_id before merging so it cannot be
+    // spoofed when resolution fails (our authoritative value is set below).
+    const existing = Object.fromEntries(Object.entries(rawExisting).filter(([k]) => k !== "install_id"));
+    const userMetadata = {
+        ...existing,
+        browse_cli: "true",
+        cli_version: toMetadataValue(getCliVersion()),
+    };
+    const installId = await resolveInstallId(process.env).catch(() => undefined);
+    if (installId) {
+        const sanitized = toMetadataValue(installId);
+        if (sanitized) {
+            userMetadata.install_id = sanitized;
+        }
+    }
+    body.userMetadata = userMetadata;
+}
 export default class SessionsCreate extends BrowseCommand {
     static description = "Create a new browser session. Use flags for common options, or --body/--stdin for the full API.";
     static examples = [
@@ -136,6 +170,7 @@ export default class SessionsCreate extends BrowseCommand {
             });
             const flagBody = buildSessionCreateBody(flags);
             const body = deepMerge(jsonBody, flagBody);
+            await applyCliAttribution(body);
             outputJson(await client.sessions.create(body));
         });
     }

package/dist/commands/screenshot.js

@@ -1,13 +1,17 @@
+import { closeSync, openSync, statSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
 import { Flags } from "@oclif/core";
 import { BrowseCommand } from "../base.js";
 import { driverCommandFlags, parseClip, runDriverCommandFromFlags, } from "../lib/driver/command-cli.js";
 export default class Screenshot extends BrowseCommand {
     static description = "Capture a screenshot of the active browser page.";
     static examples = [
+        "browse screenshot",
         "browse screenshot --path page.png",
-        "browse screenshot --full-page --path page.png",
+        "browse screenshot --full-page",
         "browse screenshot --type jpeg --quality 80",
         "browse screenshot --clip 0,0,800,600 --path clipped.png",
+        "browse screenshot --base64",
     ];
     static flags = {
         ...driverCommandFlags,
@@ -15,6 +19,10 @@ export default class Screenshot extends BrowseCommand {
             description: "Whether CSS animations run during capture.",
             options: ["allow", "disabled"],
         }),
+        base64: Flags.boolean({
+            description: "Print base64 to stdout instead of writing a file (legacy default).",
+            exclusive: ["path"],
+        }),
         caret: Flags.string({
             description: "Whether text caret is hidden during capture.",
             options: ["hide", "initial"],
@@ -28,7 +36,7 @@ export default class Screenshot extends BrowseCommand {
         }),
         path: Flags.string({
             char: "p",
-            description: "Write the screenshot to a file. Without this flag, base64 is printed.",
+            description: "Write the screenshot to this file. Defaults to screenshot-<timestamp>.png (or .jpeg with --type jpeg) in the current directory.",
             helpValue: "<path>",
         }),
         quality: Flags.integer({
@@ -42,14 +50,77 @@ export default class Screenshot extends BrowseCommand {
     };
     async run() {
         const { flags } = await this.parse(Screenshot);
-        await runDriverCommandFromFlags("screenshot", {
-            animations: flags.animations,
-            caret: flags.caret,
-            clip: parseClip(flags.clip),
-            fullPage: flags["full-page"],
-            path: flags.path,
-            quality: flags.quality,
-            type: flags.type,
-        }, flags);
+        const defaultPath = getDefaultPathFromFlags(flags);
+        try {
+            await runDriverCommandFromFlags("screenshot", {
+                animations: flags.animations,
+                caret: flags.caret,
+                clip: parseClip(flags.clip),
+                fullPage: flags["full-page"],
+                path: flags.path ?? defaultPath,
+                quality: flags.quality,
+                type: flags.type,
+            }, flags);
+        }
+        catch (error) {
+            if (defaultPath)
+                removeIfEmpty(defaultPath);
+            throw error;
+        }
+    }
+}
+// Generous upper bound on filename-collision retries; far beyond any real
+// same-second burst, it just guarantees the loop below always terminates.
+const MAX_RESERVE_ATTEMPTS = 1000;
+/**
+ * Resolves the file the screenshot should be written to, or undefined when the
+ * driver should return base64 (explicit --path is handled separately; --base64
+ * opts out of a file entirely).
+ */
+function getDefaultPathFromFlags(flags) {
+    if (flags.path || flags.base64)
+        return undefined;
+    return reserveDefaultScreenshotPath(flags.type);
+}
+/**
+ * Picks the next free screenshot-<timestamp>[-<counter>].<type> name in the
+ * current directory and reserves it. "Reserve" = create the file with an
+ * exclusive open (`wx` → O_CREAT|O_EXCL), which atomically fails with EEXIST if
+ * the name already exists, so two concurrent runs can never claim the same
+ * file. On EEXIST we advance the counter and try the next name.
+ */
+function reserveDefaultScreenshotPath(type) {
+    const now = new Date();
+    const pad = (value) => String(value).padStart(2, "0");
+    const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}` +
+        `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    const extension = type === "jpeg" ? "jpeg" : "png";
+    for (let counter = 1; counter <= MAX_RESERVE_ATTEMPTS; counter += 1) {
+        const suffix = counter === 1 ? "" : `-${counter}`;
+        const candidate = resolve(`screenshot-${stamp}${suffix}.${extension}`);
+        try {
+            // Exclusive create reserves the name; close immediately since the driver
+            // (re)writes the file. The empty placeholder is cleaned up on failure.
+            closeSync(openSync(candidate, "wx"));
+            return candidate;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    throw new Error(`Could not reserve a screenshot filename after ${MAX_RESERVE_ATTEMPTS} attempts; pass --path to choose one.`);
+}
+// Removes the reserved placeholder when the screenshot failed before the driver
+// wrote to it. `path` is always a file we created via openSync above, so the
+// isFile guard is just defensive against an unexpected directory/symlink.
+function removeIfEmpty(path) {
+    try {
+        const stats = statSync(path);
+        if (stats.isFile() && stats.size === 0)
+            unlinkSync(path);
+    }
+    catch {
+        // Best effort: leave the placeholder behind rather than mask the error.
     }
 }

package/dist/lib/cloud/api.js

@@ -4,10 +4,30 @@ import { access, mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { Readable } from "node:stream";
 import { CommandFailure, fail } from "../errors.js";
+import { getCliVersion, peekInstallId, resolveInstallId } from "../identity.js";
 import { setRunTelemetryCompletion } from "../run-telemetry.js";
 export { outputJson } from "../output.js";
 const defaultBrowserbaseApiUrl = "https://api.browserbase.com";
 const browserbaseSettingsUrl = "https://browserbase.com/settings";
+// Kick off install-id resolution at module load so the value is usually cached
+// by the time a cloud request runs. Resolution is best-effort and never throws.
+void resolveInstallId(process.env).catch(() => undefined);
+/**
+ * Attribution headers stamped onto cloud (Search/Fetch) requests so CLI usage
+ * is attributable to an install. `x-bb-client` is always sent;
+ * `x-bb-install-id` is included only when already resolved (we never block a
+ * request on disk I/O) and never sent as an empty string.
+ */
+function attributionHeaders() {
+    const headers = {
+        "x-bb-client": `browse-cli/${getCliVersion()}`,
+    };
+    const installId = peekInstallId();
+    if (installId) {
+        headers["x-bb-install-id"] = installId;
+    }
+    return headers;
+}
 export function resolveApiKey(args) {
     const apiKey = args.apiKey ?? process.env.BROWSERBASE_API_KEY;
     return (apiKey ||
@@ -32,6 +52,7 @@ export function createBrowserbaseClient(args) {
     return new Browserbase({
         apiKey: resolveApiKey(args),
         baseURL: resolveBaseUrl(args),
+        defaultHeaders: attributionHeaders(),
     });
 }
 export async function withBrowserbaseApi(command, operation) {
@@ -104,6 +125,7 @@ export async function requestBrowserbase(args, pathname, init = {}) {
             ...init,
             headers: {
                 "x-bb-api-key": resolveApiKey(args),
+                ...attributionHeaders(),
                 ...(init.headers ?? {}),
             },
         });

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

@@ -10,7 +10,7 @@ export function resolveExplicitRemoteTarget() {
 export function autoSelectRemoteTarget() {
     return null;
 }
-export function remoteStagehandOptions() {
+export async function remoteStagehandOptions() {
     throw new Error(DISABLED_MESSAGE);
 }
 export function classifyRemoteInitError(error) {

package/dist/lib/driver/remote.js

@@ -1,4 +1,5 @@
 import { StatusCodes } from "http-status-codes";
+import { getCliVersion, resolveInstallId, toMetadataValue, } from "../identity.js";
 /**
  * Real Browserbase capability. This is the ONLY module that reads
  * `BROWSERBASE_API_KEY`; it is excluded from `build:local-only` so that
@@ -10,15 +11,26 @@ export function resolveExplicitRemoteTarget() {
 export function autoSelectRemoteTarget() {
     return process.env.BROWSERBASE_API_KEY ? { kind: "remote" } : null;
 }
-export function remoteStagehandOptions() {
+export async function remoteStagehandOptions() {
     const apiKey = process.env.BROWSERBASE_API_KEY;
     if (!apiKey) {
         throw new Error("Missing BROWSERBASE_API_KEY for remote mode. Pass --local to run a managed local browser (no key needed), or set BROWSERBASE_API_KEY for cloud sessions.");
     }
+    // Stamp anonymous attribution onto the session. Resolving the install id is
+    // best-effort and never throws; if it can't be resolved we still send
+    // browse_cli + cli_version so the session stays attributable to the CLI.
+    const userMetadata = {
+        browse_cli: "true",
+        cli_version: toMetadataValue(getCliVersion()),
+    };
+    const installId = await resolveInstallId(process.env).catch(() => undefined);
+    if (installId) {
+        userMetadata.install_id = toMetadataValue(installId);
+    }
     return {
         apiKey,
         browserbaseSessionCreateParams: {
-            userMetadata: { browse_cli: "true" },
+            userMetadata,
         },
         disableAPI: true,
         disablePino: true,

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

@@ -262,7 +262,7 @@ export class DriverSessionManager {
     }
     async stagehandOptions(target) {
         if (target.kind === "remote") {
-            return (await getRemote()).remoteStagehandOptions();
+            return await (await getRemote()).remoteStagehandOptions();
         }
         if (target.kind === "managed-local") {
             return {

package/dist/lib/identity.js

@@ -0,0 +1,257 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Shared anonymous-install identity for the CLI.
+ *
+ * The install id is a stable, per-machine anonymous UUID persisted to a marker
+ * file. It is reused for (a) telemetry, (b) remote browser session
+ * `userMetadata`, and (c) cloud API request headers so that CLI-driven usage is
+ * attributable to a single install without identifying the user.
+ *
+ * The marker lives in the standardized Browserbase config dir on every platform
+ * (`(XDG_CONFIG_HOME||~/.config)/browserbase/install-id`, honoring
+ * `BROWSERBASE_CONFIG_DIR`), matching where core and the CLI's own
+ * skills/sessions already live. An earlier build wrote per-OS marker paths; the
+ * id is forward-migrated from those legacy locations on first resolution so an
+ * install keeps its stable id across the path change.
+ *
+ * Resolution is best-effort and must never throw: a read/write failure falls
+ * back to an in-memory UUID. After the first async resolution, the value is
+ * cached so it can be read synchronously via {@link peekInstallId}.
+ */
+let cachedInstallId;
+let inFlightResolution;
+/**
+ * Resolve the anonymous install id, reading (or creating) the marker file.
+ * Memoizes the result so repeated calls share one resolution. Reads the
+ * canonical marker, forward-migrates an id from a legacy per-OS marker if one
+ * exists, mints a UUID on a true miss, and swallows write failures.
+ */
+export async function resolveInstallId(env, fallbackId) {
+    if (cachedInstallId !== undefined) {
+        return cachedInstallId;
+    }
+    inFlightResolution ??= resolveAnonymousInstallId(env, fallbackId).then((id) => {
+        cachedInstallId = id;
+        return id;
+    });
+    return inFlightResolution;
+}
+/**
+ * Read the install id synchronously if it has already been resolved. Returns
+ * `undefined` when resolution has not completed yet — callers must not block on
+ * it (e.g. cloud API headers omit the id rather than wait for disk I/O).
+ */
+export function peekInstallId() {
+    return cachedInstallId;
+}
+const INSTALL_ID_MAX_ATTEMPTS = 5;
+/**
+ * Resolve (or create) the anonymous install id with a bounded, race-safe loop.
+ *
+ * The contract is: never return an id that wasn't persisted, and converge so
+ * concurrent first-run processes all settle on a single stable id. Resolution
+ * is best-effort and never throws — a hard FS failure (e.g. read-only volume)
+ * falls back to an in-memory id.
+ *
+ * Each attempt:
+ *  1. Read the marker; if it holds a non-empty id, that id won — use it.
+ *  2. Try an exclusive create (`open(path, "wx")`) and write our id; if the
+ *     create succeeds we won the race — persist and return our id.
+ *  3. On EEXIST the file exists but was empty (another process created it and
+ *     hasn't written yet, or a stale empty marker). Back off briefly and loop
+ *     so the next read can pick up the winner's id.
+ *  4. On any non-EEXIST `open` error (e.g. EACCES/EROFS), the FS is unwritable;
+ *     return the in-memory id without throwing.
+ *
+ * If every attempt sees an empty marker (no one ever wrote), we take ownership
+ * after the loop with a truncating `writeFile` so we still return a persisted
+ * id rather than a non-persistent one.
+ */
+async function resolveAnonymousInstallId(env, fallbackId) {
+    const installIdPath = resolveInstallIdPath(env);
+    const installId = fallbackId ?? randomUUID();
+    // Carry an existing id forward from a legacy per-OS marker before minting a
+    // new one, so the path change never resets a stable install id. An explicit
+    // path override short-circuits migration entirely (tests / callers pinning a
+    // specific marker should not silently inherit a legacy id).
+    if (!env.BROWSERBASE_TELEMETRY_INSTALL_ID_FILE) {
+        const migrated = await migrateLegacyInstallId(env, installIdPath);
+        if (migrated) {
+            return migrated;
+        }
+    }
+    for (let attempt = 0; attempt < INSTALL_ID_MAX_ATTEMPTS; attempt++) {
+        // 1. Prefer an already-persisted, non-empty id.
+        try {
+            const existing = (await readFile(installIdPath, "utf8")).trim();
+            if (existing) {
+                return existing;
+            }
+        }
+        catch {
+            // No readable file yet — fall through to attempt an exclusive create.
+        }
+        // 2. Try to win the create race with an exclusive-create write.
+        try {
+            await mkdir(dirname(installIdPath), { recursive: true });
+            const fh = await open(installIdPath, "wx");
+            try {
+                await fh.writeFile(`${installId}\n`, "utf8");
+            }
+            finally {
+                await fh.close();
+            }
+            return installId;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST") {
+                // 4. FS is unwritable (permissions, read-only) — best-effort fallback.
+                return installId;
+            }
+            // 3. File exists but was empty on our read. Another process is about to
+            //    write it; back off and loop so the next read picks up its id.
+            await delay(1 << attempt); // ~1, 2, 4, 8 ms
+        }
+    }
+    // 5. The marker exists but stayed empty across every attempt (no winner ever
+    //    wrote). Take ownership with a truncating write so we never return a
+    //    non-persisted id.
+    try {
+        await writeFile(installIdPath, `${installId}\n`, "utf8");
+    }
+    catch {
+        // If even this fails, return the in-memory id without throwing.
+    }
+    return installId;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function resolveInstallIdPath(env) {
+    const overriddenPath = env.BROWSERBASE_TELEMETRY_INSTALL_ID_FILE;
+    if (overriddenPath) {
+        // An explicit override short-circuits everything, including migration.
+        return overriddenPath;
+    }
+    return join(resolveConfigDir(env), "install-id");
+}
+/**
+ * The shared Browserbase config dir, matching core (`BROWSERBASE_CONFIG_DIR`)
+ * and the CLI's own skills/sessions locations. Honors BROWSERBASE_CONFIG_DIR
+ * when set (already includes the `browserbase` segment, e.g. `~/.config/browserbase`);
+ * otherwise `(XDG_CONFIG_HOME||~/.config)/browserbase` on every platform.
+ */
+function resolveConfigDir(env) {
+    if (env.BROWSERBASE_CONFIG_DIR) {
+        return env.BROWSERBASE_CONFIG_DIR;
+    }
+    const xdg = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(xdg, "browserbase");
+}
+/**
+ * The OLD per-platform marker locations the install id used to live in, in
+ * priority order. We always include the XDG-style legacy path on every platform
+ * (it makes the migration unit-testable via XDG_CONFIG_HOME), plus the
+ * platform-specific one. Deduped so linux (platform path == xdg path) yields one
+ * entry.
+ */
+function legacyInstallIdPaths(env) {
+    const paths = [];
+    if (process.platform === "win32") {
+        const baseDir = env.APPDATA ?? env.LOCALAPPDATA ?? join(homedir(), "AppData", "Roaming");
+        paths.push(join(baseDir, "Browserbase", "cli", "telemetry-id"));
+    }
+    else if (process.platform === "darwin") {
+        paths.push(join(homedir(), "Library", "Application Support", "Browserbase", "cli", "telemetry-id"));
+    }
+    const xdg = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    paths.push(join(xdg, "browserbase", "cli", "telemetry-id"));
+    return [...new Set(paths)];
+}
+/**
+ * One-time path migration. If the canonical marker already exists, return its
+ * id. Otherwise, if a legacy per-platform marker holds an id, copy that id
+ * forward to the canonical path (best-effort, atomic exclusive-create) and
+ * return it, so the install keeps its stable id across the path change. Returns
+ * `undefined` when no id exists anywhere (truly first run) — the caller's create
+ * loop then mints a fresh id. Never throws. The legacy file is left in place
+ * (harmless, avoids a destructive op).
+ */
+async function migrateLegacyInstallId(env, canonicalPath) {
+    try {
+        const existing = (await readFile(canonicalPath, "utf8")).trim();
+        if (existing) {
+            return existing;
+        }
+    }
+    catch {
+        // Canonical marker missing — fall through to the legacy lookup.
+    }
+    for (const legacyPath of legacyInstallIdPaths(env)) {
+        if (legacyPath === canonicalPath) {
+            continue;
+        }
+        let legacyId;
+        try {
+            legacyId = (await readFile(legacyPath, "utf8")).trim();
+        }
+        catch {
+            continue;
+        }
+        if (!legacyId) {
+            continue;
+        }
+        try {
+            await mkdir(dirname(canonicalPath), { recursive: true });
+            const fh = await open(canonicalPath, "wx");
+            try {
+                await fh.writeFile(`${legacyId}\n`, "utf8");
+            }
+            finally {
+                await fh.close();
+            }
+        }
+        catch {
+            // Race lost or FS unwritable — returning the legacy id still keeps it
+            // stable for this run.
+        }
+        return legacyId;
+    }
+    return undefined;
+}
+/**
+ * Sanitize a value for use in Browserbase `userMetadata`. The session-create
+ * validator only accepts characters matching `[\w\-_,;:.()&$%#@!?~]` and
+ * enforces a total length limit; this function strips everything else and
+ * truncates to `max` characters (default 64) so a semver `+build` suffix or
+ * any other unexpected character cannot cause a 400 on every remote session.
+ */
+export function toMetadataValue(v, max = 64) {
+    return v.replace(/[^\w\-_,;:.()&$%#@!?~]/g, "").slice(0, max);
+}
+let cachedCliVersion;
+/**
+ * Seed the CLI version from oclif's `Config.version` (the single source of
+ * truth). This is called once at startup from `BrowseCommand.init()` in base.ts
+ * — and because every command (including the background `browse daemon` that
+ * creates Browserbase sessions) extends `BrowseCommand`, the cache is populated
+ * in whichever process builds a session/header. Only truthy values are stored
+ * so a missing version leaves the `"unknown"` fallback intact.
+ */
+export function setCliVersion(version) {
+    if (version) {
+        cachedCliVersion = version;
+    }
+}
+/**
+ * The CLI version for non-command contexts (remote session `userMetadata`,
+ * cloud API headers). It is seeded once from `Config.version` in base.ts at
+ * startup via {@link setCliVersion}; this reads back the cached value with no
+ * filesystem access. Falls back to `"unknown"` if it was never seeded.
+ */
+export function getCliVersion() {
+    return cachedCliVersion ?? "unknown";
+}

package/dist/lib/skills/install.js

@@ -13,6 +13,18 @@ const domainPattern = /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/;
 const taskPattern = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 const maxSkillFiles = 100;
 const maxCapturedOutputBytes = 2048;
+const defaultInstallTimeoutMs = 180_000;
+const defaultFetchTimeoutMs = 10_000;
+function envTimeoutMs(name, fallback) {
+    const value = Number(process.env[name]);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function installTimeoutMs() {
+    return envTimeoutMs("BROWSE_SKILLS_INSTALL_TIMEOUT_MS", defaultInstallTimeoutMs);
+}
+function fetchTimeoutSignal() {
+    return AbortSignal.timeout(envTimeoutMs("BROWSE_SKILLS_FETCH_TIMEOUT_MS", defaultFetchTimeoutMs));
+}
 export function parseSkillId(rawSkillId) {
     const parts = rawSkillId.split("/");
     if (parts.length !== 2) {
@@ -103,10 +115,14 @@ export async function installBundledCliSkill() {
 // message (including a tail of the child's output) when the child exits nonzero
 // so the failure is recorded in telemetry instead of an opaque exit code.
 async function runSkillsInstall(npxPath, args) {
-    const result = await spawnPassthrough(npxPath, args);
-    if (result.exitCode === 0) {
+    const timeoutMs = installTimeoutMs();
+    const result = await spawnPassthrough(npxPath, args, timeoutMs);
+    if (result.exitCode === 0 && !result.timedOut) {
         return;
     }
+    if (result.timedOut) {
+        fail(`Skill install timed out after ${Math.round(timeoutMs / 1000)}s waiting for \`npx skills add\`. Check your network connection and rerun \`browse skills add\`.`, 1, { resultCode: "skill_install_timeout" });
+    }
     const detail = result.output.trim();
     const reason = detail
         ? `: ${detail}`
@@ -188,9 +204,11 @@ async function fetchSkillFilesFromApi(skillId) {
     const url = skillFilesApiUrl(skillId);
     let response;
     try {
-        response = await fetch(url);
+        response = await fetch(url, { signal: fetchTimeoutSignal() });
     }
     catch {
+        // Network failures and timeouts both mean the catalog is unavailable;
+        // callers fall back (or fail cleanly) exactly as before.
         return { status: "unavailable" };
     }
     if (response.status === 404) {
@@ -219,6 +237,7 @@ async function directBlobSkillExists(skillId) {
     try {
         response = await fetch(skillBlobUrl(skillId, "SKILL.md"), {
             method: "HEAD",
+            signal: fetchTimeoutSignal(),
         });
     }
     catch {
@@ -294,7 +313,7 @@ async function fetchSkillFile(url, label) {
 async function fetchFromUrl(url, label) {
     let response;
     try {
-        response = await fetch(url);
+        response = await fetch(url, { signal: fetchTimeoutSignal() });
     }
     catch (error) {
         fail(`Could not download ${label}: ${error.message}`);
@@ -347,15 +366,43 @@ async function findExecutable(command) {
     }
     return null;
 }
+// Quotes a single token for the command line Node hands to cmd.exe when
+// `shell: true`. Node joins command+args UNQUOTED into `cmd.exe /d /s /c
+// "..."`, so an unquoted `C:\Program Files\nodejs\npx.cmd` splits at the
+// space and cmd runs `C:\Program`. Wrapping tokens that contain whitespace,
+// quotes, or cmd metacharacters in double quotes (with embedded quotes
+// doubled) keeps them intact; `/s` makes cmd strip only the outer quotes.
+export function quoteForCmdShell(token) {
+    if (token === "") {
+        return '""';
+    }
+    return /[\s"^&|<>]/.test(token) ? `"${token.replaceAll('"', '""')}"` : token;
+}
 // Like `stdio: "inherit"` for the human watching, but the child's stdout/stderr
 // are also buffered (tail only) so a nonzero exit can surface a real reason to
-// telemetry instead of a bare exit code.
-async function spawnPassthrough(command, args) {
+// telemetry instead of a bare exit code. The child is killed after `timeoutMs`
+// (SIGTERM, then SIGKILL) so a hung `npx` cannot stall the install forever.
+// Exported for tests.
+export async function spawnPassthrough(command, args, timeoutMs = installTimeoutMs()) {
+    const useWindowsShell = shouldUseWindowsShell(command);
+    const spawnCommand = useWindowsShell ? quoteForCmdShell(command) : command;
+    const spawnArgs = useWindowsShell ? args.map(quoteForCmdShell) : args;
     return await new Promise((resolvePromise) => {
-        const child = spawn(command, args, {
+        const child = spawn(spawnCommand, spawnArgs, {
             stdio: ["inherit", "pipe", "pipe"],
-            shell: shouldUseWindowsShell(command),
+            shell: useWindowsShell,
         });
+        let timedOut = false;
+        let killTimer;
+        const deadline = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => child.kill("SIGKILL"), 5_000);
+        }, timeoutMs);
+        const clearTimers = () => {
+            clearTimeout(deadline);
+            clearTimeout(killTimer);
+        };
         let captured = "";
         const capture = (chunk) => {
             captured += chunk.toString();
@@ -375,16 +422,20 @@ async function spawnPassthrough(command, args) {
         // `skill_install_failed` by runSkillsInstall instead of escaping as an
         // unclassified runtime error.
         child.on("error", (error) => {
+            clearTimers();
             const message = error instanceof Error ? error.message : String(error);
             resolvePromise({
                 exitCode: 1,
                 output: captured ? `${captured}\n${message}` : message,
+                timedOut,
             });
         });
         child.on("close", (exitCode, signal) => {
+            clearTimers();
             resolvePromise({
                 exitCode: signal ? 1 : (exitCode ?? 0),
                 output: captured,
+                timedOut,
             });
         });
     });

package/dist/lib/telemetry.js

@@ -1,8 +1,5 @@
-import { randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
 import { detectAgent } from "./agent.js";
+import { resolveInstallId } from "./identity.js";
 import { getRunTelemetry, resetRunTelemetry } from "./run-telemetry.js";
 const browserbaseTelemetrySource = "cli";
 const browserbaseTelemetryHost = "https://us.i.posthog.com";
@@ -76,7 +73,7 @@ function createCliTelemetry(options) {
     const transport = resolveTransportConfig(env);
     const telemetryEnabled = !isTelemetryDisabled(env);
     const distinctIdPromise = telemetryEnabled
-        ? resolveAnonymousInstallId(env, options.sessionId)
+        ? resolveInstallId(env, options.sessionId)
         : Promise.resolve("");
     const agentPromise = telemetryEnabled ? detectAgent() : Promise.resolve(null);
     const baseProperties = {
@@ -237,42 +234,6 @@ function parseTimeoutMs(value) {
 function normalizeHost(host) {
     return host.endsWith("/") ? host.slice(0, -1) : host;
 }
-async function resolveAnonymousInstallId(env, fallbackId) {
-    const installIdPath = resolveInstallIdPath(env);
-    try {
-        const existing = (await readFile(installIdPath, "utf8")).trim();
-        if (existing) {
-            return existing;
-        }
-    }
-    catch {
-        // Fall through and create a new anonymous install ID.
-    }
-    const installId = fallbackId ?? randomUUID();
-    try {
-        await mkdir(dirname(installIdPath), { recursive: true });
-        await writeFile(installIdPath, `${installId}\n`, "utf8");
-    }
-    catch {
-        // If persistence fails, continue with an in-memory anonymous ID.
-    }
-    return installId;
-}
-function resolveInstallIdPath(env) {
-    const overriddenPath = env.BROWSERBASE_TELEMETRY_INSTALL_ID_FILE;
-    if (overriddenPath) {
-        return overriddenPath;
-    }
-    if (process.platform === "win32") {
-        const baseDir = env.APPDATA ?? env.LOCALAPPDATA ?? join(homedir(), "AppData", "Roaming");
-        return join(baseDir, "Browserbase", "cli", "telemetry-id");
-    }
-    if (process.platform === "darwin") {
-        return join(homedir(), "Library", "Application Support", "Browserbase", "cli", "telemetry-id");
-    }
-    const baseDir = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
-    return join(baseDir, "browserbase", "cli", "telemetry-id");
-}
 function isTelemetryDisabled(env) {
     return (envFlagEnabled(env.DO_NOT_TRACK) ||
         envFlagEnabled(env.BROWSERBASE_TELEMETRY_DISABLED) ||

package/oclif.manifest.json

@@ -1716,10 +1716,12 @@
       "args": {},
       "description": "Capture a screenshot of the active browser page.",
       "examples": [
+        "browse screenshot",
         "browse screenshot --path page.png",
-        "browse screenshot --full-page --path page.png",
+        "browse screenshot --full-page",
         "browse screenshot --type jpeg --quality 80",
-        "browse screenshot --clip 0,0,800,600 --path clipped.png"
+        "browse screenshot --clip 0,0,800,600 --path clipped.png",
+        "browse screenshot --base64"
       ],
       "flags": {
         "auto-connect": {
@@ -1810,6 +1812,15 @@
           ],
           "type": "option"
         },
+        "base64": {
+          "description": "Print base64 to stdout instead of writing a file (legacy default).",
+          "exclusive": [
+            "path"
+          ],
+          "name": "base64",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "caret": {
           "description": "Whether text caret is hidden during capture.",
           "name": "caret",
@@ -1837,7 +1848,7 @@
         },
         "path": {
           "char": "p",
-          "description": "Write the screenshot to a file. Without this flag, base64 is printed.",
+          "description": "Write the screenshot to this file. Defaults to screenshot-<timestamp>.png (or .jpeg with --type jpeg) in the current directory.",
           "name": "path",
           "hasDynamicHelp": false,
           "helpValue": "<path>",
@@ -5992,5 +6003,5 @@
       ]
     }
   },
-  "version": "0.8.5"
+  "version": "0.9.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browse",
-  "version": "0.8.5",
+  "version": "0.9.0-alpha-263e4d4",
   "description": "Unified Browserbase CLI for browser automation and cloud APIs.",
   "type": "module",
   "private": false,
@@ -100,7 +100,7 @@
     "tsx": "^4.20.6",
     "ws": "^8.18.3",
     "zod": "^4.2.1",
-    "@browserbasehq/stagehand": "3.5.0"
+    "@browserbasehq/stagehand": "3.6.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/skills/browse/SKILL.md

@@ -139,8 +139,9 @@ browse get html "#main"
 browse get value "#email"
 browse get markdown body                   # page/element content as markdown
 browse eval "document.title"              # run JavaScript in the active page
-browse screenshot                         # print base64 JSON
-browse screenshot --path page.png
+browse screenshot                         # saves screenshot-<timestamp>.png, prints { "saved": "<path>" }
+browse screenshot --path page.png         # choose the output path
+browse screenshot --base64                # legacy: print base64 JSON to stdout (avoid in agent loops)
 ```
 
 Interaction: