fix(cli): persist context names in Browserbase

Draft
SH
2mo ago
+1725-48

Summary

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

  • Send --name to 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 ... --force reconciliation.
  • Label list output as Local name so cache aliases are not mistaken for an authoritative server list.

Stack (#2872)

  1. #2833 — exact Browse V3 baseline import
  2. #2834 — Stagehand V4 runtime and standard command parity
  3. #2869 — CLI-owned cursor overlay
  4. #2849 — CLI-private CDP sidecar; V3 network parity
  5. #2835 — remove --return-xpath; supported V3 parity/release checkpoint
  6. #2838 — eval and packaging integration
  7. #2839 — managed Context names (fast-follow)
  8. #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 / flowObserved outputConfidence / sufficiency
Fully verified head b69a671a2: pnpm install --frozen-lockfile; pnpm --filter browse build; browse check; browse lintFrozen 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 suite2 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 aliasAlias 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 sessionSession 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 cacheRemote 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 writesFile 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.