browse 0.9.0 → 0.9.1

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