[STG-2404] feat(cli): attribute usage via install_id + cli_version on sessions and cloud API headers

[shrey150]

What & why

CLI-driven Browserbase usage isn't fully attributable today:

• Remote browser sessions the CLI creates are tagged userMetadata.browse_cli:"true", but carry no install/version, so we can't tie usage to an install or correlate with the CLI's anonymous PostHog telemetry.
• browse cloud search (/v1/search) and browse cloud fetch create no session at all, so they're invisible in session metadata.

This PR stamps a stable anonymous install_id + cli_version onto both paths.

Changes (packages/cli only)

• New src/lib/identity.ts — single source for install identity: resolveInstallId (async, memoized, atomic write via exclusive-create + EEXIST re-read), peekInstallId (sync, never blocks), getCliVersion, and toMetadataValue (sanitizes session-metadata values). install-id logic moved verbatim out of telemetry.ts; its tests pass unchanged.
• Sessions — driver/remote.ts remoteStagehandOptions() adds sanitized install_id + cli_version to userMetadata (made async; resolver awaited with a safe fallback so telemetry never throws). Interface, local-only stub (now properly async so .catch works), and the call site updated.
• Cloud headers — lib/cloud/api.ts sends x-bb-client: browse-cli/<version> (+ x-bb-install-id when resolved) on both transports: the raw requestBrowserbaseJson helper (covers search, sessions, contexts, projects, extensions) and createBrowserbaseClient() defaultHeaders (covers fetch, functions). Never emits empty-value headers.
• Patch changeset.

Why sanitize values

Browserbase session-create runs validateMetadataObject — values must match [\w\-_,;:.()&$%#@!?~] and total ≤512 chars. A +build semver would otherwise 400 every remote session, so cli_version/install_id are passed through toMetadataValue() before reaching userMetadata. (HTTP headers are unconstrained, so the full version stays in x-bb-client.)

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
<local build> open https://example.com --remote → cloud sessions list --status RUNNING	session userMetadata = {stagehand:"true", browse_cli:"true", install_id:"<uuid>", cli_version:"0.9.0"}	All 3 attribution keys land on a driver-created remote session; install_id equals the on-disk marker. (Server-side ingestion out of scope.)
cloud search "..." and cloud fetch https://example.com against a local capture server (--base-url)	/v1/search and /v1/fetch each received x-bb-client: browse-cli/0.9.0 + x-bb-install-id: <uuid>	Exact outgoing headers confirmed on both the raw-helper (search) and SDK (fetch) paths.
cloud search "..." and cloud fetch https://example.com (live API)	real results JSON; fetch 200 + markdown	New headers don't break live calls.
Migration smoke against built dist/lib/identity.js: seed legacy ~/…/cli/telemetry-id = 1111…5555, then resolveInstallId with XDG_CONFIG_HOME pointed at a temp dir	returned 1111…5555; new <tmp>/browserbase/install-id contains 1111…5555 (fresh-dir case mints a new uuid instead)	Legacy id is carried forward to the new canonical path, not reset; first-run still mints. Also confirmed on real disk: existing ~/Library/.../telemetry-id id copied to ~/.config/browserbase/install-id, legacy file intact.
Read-only-FS / Lambda resilience against built dist: (a) HOME=/tmp/... writable, (b) read-only 0555 dir, (c) ENOTDIR under /dev/null, (d) unwritable HOME=/var/empty, plus real browse --version and browse cloud sessions list under unwritable HOME	(a) persists to /tmp/.../.config/browserbase/install-id; (b)(c)(d) return a valid in-memory UUID, nothing written, no throw; real CLI exits cleanly (version prints; cloud cmd returns a clean 401, not an FS crash); no illegal writes under /var/empty	install-id resolution + migration are best-effort: every read/mkdir/write is guarded and all 4 callers wrap in .catch. On Lambda (HOME=/tmp) it persists; if the dir/file is unwritable it degrades to a per-invocation in-memory id without failing the command.
turbo run build --filter=browse · pnpm lint · pnpm test:cli	build + lint clean · 299/299 tests pass (+7 path-resolution / migration tests over the prior 292)	No regressions; path change + migration covered.

Review follow-ups (addressed)

All 5 Cubic threads resolved: async local-only stub (so .catch works), atomic install-id write (race-safe on concurrent first runs — pre-existing behavior, hardened), and 12 focused unit tests for toMetadataValue (allowed-char filtering, +build stripping, truncation, UUID round-trip), the attribution headers, and the remoteStagehandOptions success + fallback paths.

Dependency / follow-up (not in this PR)

Session userMetadata keys are queryable in Snowflake today (STG_SESSIONS.SESSION_METADATA). The search/fetch headers only become useful once Platform logs x-bb-client / x-bb-install-id on those endpoints (/v1/fetch has an unpopulated fetch_tasks.headers column not yet in the Estuary mirror; /v1/search writes no DB row) — tracked as a server-side follow-up.

Update — also tags cloud sessions create

Extended attribution to the browse cloud sessions create path too (previously only the driver open --remote path carried it): its userMetadata now includes browse_cli + install_id + cli_version (sanitized via toMetadataValue), merged with any user-supplied --body metadata while keeping the attribution keys authoritative — a user can't spoof browse_cli to "false". So every CLI-created session is attributable — driver and cloud sessions create. Verified live: cloud sessions create → readback userMetadata: { browse_cli:"true", install_id:"…", cli_version:"0.9.0" } → released. +2 tests (292 total cli tests).

Update — standardized install-id path (review follow-up)

Per review (thanks @pirate), moved the anonymous install-id marker off the bespoke per-OS path (~/Library/Application Support/Browserbase/cli/telemetry-id, %APPDATA%/Browserbase/cli/telemetry-id, <xdg>/browserbase/cli/telemetry-id) to the standardized ~/.config/browserbase/install-id — consistent with core (BROWSERBASE_CONFIG_DIR) and the CLI's own ~/.config/browserbase/skills. Honors BROWSERBASE_CONFIG_DIR, falls back to XDG_CONFIG_HOME/~/.config on every platform; the BROWSERBASE_TELEMETRY_INSTALL_ID_FILE override still short-circuits everything (incl. migration).

Backwards-compatible: if the canonical file is absent but a legacy marker exists, its UUID is copied forward so existing installs keep their stable id — no attribution reset; the legacy file is left intact. Renamed telemetry-id → install-id since it's no longer telemetry-only (and install-id, not device-id, because it's a per-install id, not a hardware fingerprint). Considered and declined node-machine-id: a cross-app hardware id doesn't fix ephemeral-fleet counting (unpredictable across customer image strategies) and conflicts with the anonymous, install-scoped intent.

Closes STG-2404.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 855738c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

4 issues found across 8 files

Confidence score: 3/5

• packages/cli/src/lib/identity.ts can race on concurrent first-run install-id creation, so different processes may persist/use different IDs and produce inconsistent attribution or downstream identity behavior — reserve the marker file with exclusive create and on EEXIST read and reuse the persisted value before merging.
• packages/cli/src/lib/driver/remote.disabled.ts exposes a Promise-shaped API but throws synchronously, which can bypass callers’ .catch handling and surface as an unhandled error path in local-only mode — return a rejected Promise instead (or make callers handle sync throws explicitly) to align behavior.
• packages/cli/src/lib/cloud/api.ts and packages/cli/src/lib/driver/remote.ts add attribution/header logic without focused coverage, so regressions in always-on fields vs conditional install_id could slip through unnoticed — add targeted unit/integration tests for header/session success and fallback paths before merging.

Architecture diagram

sequenceDiagram
    participant CLI as CLI Command
    participant Identity as identity.ts
    participant Telemetry as telemetry.ts
    participant Remote as remote.ts
    participant CloudAPI as cloud/api.ts
    participant SDK as Browserbase SDK
    participant Platform as Browserbase Platform
    
    Note over CLI,Platform: Module Load Time
    
    CloudAPI->>CloudAPI: Kick off resolveInstallId(process.env)
    CloudAPI->>Identity: resolveInstallId()
    Identity->>Identity: Check cachedInstallId
    alt Cache miss (first call)
        Identity->>Identity: Read marker file from disk
        alt File not found
            Identity->>Identity: Generate UUID
            Identity->>Identity: Write marker file (best-effort)
        end
        Identity->>Identity: Cache result
    end
    Identity-->>CloudAPI: install_id (promise, not awaited here)
    
    Note over CLI,Platform: Remote Session Flow (e.g., browse open --remote)
    
    CLI->>Remote: remoteStagehandOptions()
    Remote->>Identity: getCliVersion()
    Identity-->>Remote: "x.y.z"
    Remote->>Remote: Build userMetadata { browse_cli: "true", cli_version: "x.y.z" }
    Remote->>Identity: resolveInstallId(process.env)
    alt Resolution succeeds
        Identity-->>Remote: "uuid-abc-123"
        Remote->>Remote: Add install_id to userMetadata
    else Resolution fails (caught)
        Remote->>Remote: Continue without install_id
    end
    Remote-->>CLI: StagehandConstructorOptions with userMetadata
    
    CLI->>SDK: Stagehand.init() with userMetadata
    SDK->>Platform: Create session with userMetadata
    Platform-->>SDK: Session created
    SDK-->>CLI: Stagehand instance
    
    Note over CLI,Platform: Cloud Search/Fetch Flow (e.g., browse cloud search)
    
    CLI->>CloudAPI: search() / fetch()
    
    Note over CloudAPI: attributionHeaders() called
    CloudAPI->>Identity: getCliVersion()
    Identity-->>CloudAPI: "x.y.z"
    CloudAPI->>CloudAPI: Set x-bb-client: browse-cli/x.y.z
    CloudAPI->>Identity: peekInstallId()
    alt install_id already resolved
        Identity-->>CloudAPI: "uuid-abc-123"
        CloudAPI->>CloudAPI: Set x-bb-install-id: uuid-abc-123
    else Still resolving or failed
        Identity-->>CloudAPI: undefined
        CloudAPI->>CloudAPI: Omit x-bb-install-id header
    end
    
    alt Raw request path (search)
        CloudAPI->>Platform: GET /v1/search with x-bb-client + possibly x-bb-install-id
        Platform-->>CloudAPI: Search results
    else SDK client path (fetch)
        CloudAPI->>SDK: createBrowserbaseClient() with defaultHeaders
        SDK->>Platform: GET /v1/fetch with x-bb-client + possibly x-bb-install-id
        Platform-->>SDK: Fetch response
        SDK-->>CloudAPI: Markdown/text
    end
    CloudAPI-->>CLI: Command output
    
    Note over CLI,Platform: Telemetry Flow (unchanged, now shared)
    
    CLI->>Telemetry: initialize telemetry
    Telemetry->>Identity: resolveInstallId(env, sessionId)
    Identity-->>Telemetry: install_id (same as above)
    Telemetry->>Platform: POST telemetry events with install_id

Loading

<sub>Tip: cubic used a learning from your PR history. Let your coding agent read cubic learnings directly with the cubic MCP.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>