fix(cli): persist context names in Browserbase
Summary
Move new CLI-created Context names onto the production Browserbase Contexts API while preserving existing local aliases.
- Send
--nameto the Context create API; 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.
- Reject a managed-name create that would silently repoint an existing alias; offer explicit
contexts add ... --forcereconciliation. - Label list output as
Local nameso cache aliases are not mistaken for an authoritative server list.
Stack (#2872)
- #2833 — exact Browse V3 baseline import
- #2834 — Stagehand V4 runtime and standard command parity
- #2869 — CLI-owned cursor overlay
- #2849 — CLI-private CDP sidecar; V3 network parity
- #2835 — remove
--return-xpath; supported V3 parity/release checkpoint - #2838 — eval and packaging integration
- #2839 — managed Context names (fast-follow)
- #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
The current remote PR head is af0261ae6ad9b9bf4da5a56fe6edfcd94d76228b. The complete matrix below ran at b69a671a2f792112d7b1ec08027a67d3d86db34a; the only inherited change since then is #2849's test-helper timeout diagnostic, whose focused network tests and Browse lint/typecheck passed at sidecar head 9887732b6. Its product diff is unchanged from proof commit d2bee7e1cb31e53bb5df1cc793e704793b7a8cd3, where the broader live session-persistence flow below ran. Local cache and daemon paths were isolated from the user's normal configuration.
| Command / flow | Observed output | Confidence / sufficiency |
|---|---|---|
Fully verified head b69a671a2: pnpm install --frozen-lockfile; pnpm --filter browse build; browse check; browse lint | Frozen install, real Oclif/TypeScript build, typecheck, Prettier check, ESLint, and the lint-owned second typecheck all passed. | Proves the regenerated lockfile and exact current head build cleanly and satisfy package checks. |
Fully verified head b69a671a2: built CLI against the fake Browserbase server plus Context-store suite | 2 test files / 23 tests passed. The server observed POST /v1/contexts with name, and session create with resolved context ID plus persist: true. | Deterministically proves exact request shapes, managed/legacy resolution, validation, typo/raw-ID paths, atomic cache behavior, and session persistence. |
Fully verified head b69a671a2: live contexts create --name <synthetic-name>; contexts get <synthetic-name> | Production Browserbase echoed the managed name and returned a nonempty ID; get-by-name resolved to the same remote Context. | Fresh proof that the current propagated head composes the cache with the production name field. |
Fully verified head b69a671a2: contexts add <legacy-alias> <same-id>; get by alias; try managed create under the alias | Alias resolved to the same remote Context while its Browserbase-managed name stayed unchanged; conflicting create was rejected before POST with exit 1. | Fresh proof that legacy aliases remain usable and cannot be silently repointed. |
Product proof head d2bee7e1: live sessions create --context-id <synthetic-name> --persist --timeout 60; release session | Session creation succeeded with a nonempty ID and was explicitly released. The deterministic current-head server test proves the exact resolved-ID/persist: true payload. | Real-service proof of the named-context session path plus fresh deterministic current-head request-shape proof. Product code is unchanged. |
Fully verified head b69a671a2: live contexts delete <synthetic-name>; list cache | Remote delete succeeded; both names pointing at the ID were pruned; zero local aliases remained. | Fresh proof that delete-by-name reconciles remote and local state. |
Fully verified head b69a671a2: inspect isolated contexts.json after atomic writes | File mode was 0600. | Proves the cache does not regress local state permissions. |
The fully verified-head temporary Context was deleted. The earlier temporary session was released and its Context deleted. No credentials, project identifiers, Context/session IDs, or private URLs are included here.