fix(cli): persist context names in Browserbase

[shrey150]

Summary

Move new CLI-created Context names onto the production Browserbase Contexts API while preserving existing local aliases.

• Upgrade the Browserbase SDK floor to a version whose Context create/get types include name.
• Send --name to POST /v1/contexts; Browserbase owns the canonical, project-scoped name.
• Keep the local name-to-ID file as a device cache because Context/session operations still require IDs and the public API has no list or lookup-by-name endpoint.
• Preserve arbitrary aliases created by older CLI versions, even when they differ from the Context's managed name.
• Reject a new managed-name create that would silently repoint an existing local alias; offer explicit contexts add ... --force reconciliation instead.
• Label contexts list output as Local name so cached aliases are not mistaken for an authoritative server list.

See the Browserbase Contexts documentation for the persistence model.

Stack

1. chore(cli): import Browse V3 baseline #2833 — exact Browse V3 baseline import
2. refactor(cli): migrate Browse runtime to Stagehand V4 #2834 — Stagehand V4 runtime cutover and CLI-owned cursor
3. fix(cli): restore V3 network capture through a CDP sidecar #2849 — CLI-private CDP sidecar; restores V3 network capture
4. refactor(cli): remove coordinate XPath return flag #2835 — remove --return-xpath; complete supported V3 parity
5. test(evals): exercise the workspace V4 CLI #2838 — eval, packaging, and release wiring
6. fix(cli): persist context names in Browserbase #2839 — managed Context names (fast-follow)
7. refactor(cli): consume shared Functions core #2701 — shared Functions core consumer (fast-follow)

Why the cache remains

The production API stores an optional name, but current Context and Session calls still address Contexts by opaque ID. Removing the cache would regress get <name>, sessions create --context-id <name>, and delete <name> without a server-side replacement. contexts add therefore remains explicitly a local alias, not a Browserbase rename operation.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
Live contexts create --name against Browserbase	API response returned the same managed name and an ID	Proves the name is server-owned, not CLI-only metadata
Live contexts get <local-name>	Resolved through the device cache and returned the Context with its managed name	Proves ID-based API compatibility is retained
Live contexts list --json	Cached name-to-ID entry was present	Proves the local resolution UX remains available
Live duplicate legacy-alias regression fixture	Create rejected before any POST, with explicit reconciliation guidance; original alias remained unchanged	Proves an upgrade cannot silently repoint legacy state
Live contexts delete <name> followed by get by ID	Delete removed the API resource and local alias; subsequent get returned not found	Proves both remote and device-local cleanup; the temporary resource was removed
Browse build/lint/typecheck on current restacked head b71f4e9b1	Passed	Static, generated-manifest, and style coverage after inheriting the rewritten stack
Context-name suite on current restacked head	6/6 passed (the original feature-head full Browse suite also passed)	Covers managed-name transport, local resolution, session use, deletion, raw-ID compatibility, typo hints, and legacy aliases

No Browserbase Context IDs or credentials are included in this description.

[changeset-bot]

🦋 Changeset detected

Latest commit: b71f4e9

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

This PR includes changesets to release 1 package

Name	Type
browse	Patch

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

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​browserbasehq/​sdk@​2.19.0

View full report

[shrey150]

Have we thought about how this affects existing CLI users that have their context names saved locally, and what happens if they don't match the managed name on the Browserbase platform?

[shrey150]

Re: the comment by @shrey150 — Addressed in 659d327f1. Existing cached names remain valid local aliases and keep resolving to their saved Context IDs even when the Browserbase-managed name differs. The CLI does not auto-remap them. A colliding contexts create --name now fails before making an API request, so it cannot silently overwrite a legacy mapping; help/docs and an end-to-end mismatch regression cover the migration behavior.