fix(cli): persist context names in Browserbase by shrey150 · Pull Request #2839 · browserbase/stagehand

shrey150 · 2026-08-27T20:46:16Z

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)

chore(cli): import Browse V3 baseline #2833 — exact Browse V3 baseline import
refactor(cli): migrate Browse runtime and commands to Stagehand V4 #2834 — Stagehand V4 runtime and standard command parity
feat(cli): restore cursor overlay through page.evaluate #2869 — CLI-owned cursor overlay
fix(cli): restore V3 network capture through a CDP sidecar #2849 — CLI-private CDP sidecar; V3 network parity
refactor(cli): remove coordinate XPath return flag #2835 — remove --return-xpath; supported V3 parity/release checkpoint
test(evals): exercise the workspace V4 CLI #2838 — eval and packaging integration
fix(cli): persist context names in Browserbase #2839 — managed Context names (fast-follow)
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

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.

changeset-bot · 2026-08-27T20:46:21Z

🦋 Changeset detected

Latest commit: 998652c

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 · 2026-08-27T20:46:48Z

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.20.0

View full report

shrey150 · 2026-08-27T21:06:53Z

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 · 2026-08-27T21:17:01Z

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.

## Summary Import `packages/cli/**` exactly from the published `browse@0.9.6` V3 release, without changing its source or runtime behavior. This is intentionally a provenance checkpoint, not a line-by-line feature review. The imported source is kept runnable by a root, version-scoped pnpm override that resolves its unchanged Stagehand dependency to `3.7.1`. #2834 removes that override and starts the V4 migration. ## Exact-source provenance - Annotated tag: `browse@0.9.6` (`548c56407431db27823a212f53475443c7e8358d`) - Release commit: `1d49a95c0c230c346f8d50647e10303d6310fcd2` - Authoritative CLI tree: `b4048badce921cf54f199f96033d9a014ef977ec` - This PR's `HEAD:packages/cli` tree: `b4048badce921cf54f199f96033d9a014ef977ec` The tag's ignored README whitespace is retained too; formatting the import would invalidate the tree proof. ## Verification - Current remote head: `a77e1507b85e3c02553f36ead6ebd0237b0cccc6`, based on current `main`. - `HEAD:packages/cli` exactly equals the published V3 tree hash above. - pnpm 11 frozen install and the repository supply-chain release-age policy pass. - Browse lint, typecheck, and build pass; the full baseline suite passes: 25 files / 366 tests. - A fresh extension build still exactly matches the Go-embedded archive: SHA-256 `8efc7d171a625cca95c02d02d369b59435fae776cae6c7dd2f6fe72eb19785c0` on both files. This specifically verifies that adding the V3 dependency graph does not perturb the current V4 extension artifact. - This layer intentionally exercises V3 through the scoped Stagehand 3.7.1 override. V4 behavior starts in #2834. ## 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) ## Review and landing boundary Review this PR by verifying the tree hashes, dependency pin, root package wiring, and changeset—not by treating the imported V3 source as newly authored code. This head deliberately imports V3 code into the V4 repository and is not independently publishable. It lands only as the base of the complete stack. The framework network-event schema proposal in #2832 is intentionally outside this landing stack.

…2834) ## Summary Migrate Browse's browser lifecycle and standard command surface together from Stagehand V3 to V4. - Replace the V3 constructor/init lifecycle with V4 browser factories and `Stagehand.create()`. - Support managed local, Browserbase remote, and attached CDP connection targets. - Preserve owned-versus-attached cleanup, daemon persistence, Browserbase session identity, and timeout handling. - Restore navigation, page information, deterministic locator actions, keyboard/mouse input, viewport/screenshot, snapshot, eval, and tab commands on V4 APIs. - Keep click/fill/select deterministic; this does not add a model-free structured `act()` path. - Make the remaining cursor, network, and coordinate-XPath gaps fail explicitly for the stack layers that restore or remove them. ## 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) ## Review shape The lifecycle and command migration remain two ordered implementation commits: 1. `389e2dae6` — V4 browser/session foundation and lifecycle ownership. 2. `b45167462` — standard command translation on that foundation. They are one PR because both commits rewrite the same nine command/test files. Reviewing their combined final diff avoids temporary deletion/stubbing followed by reimplementation, while the commits still provide useful lifecycle-versus-command checkpoints. Review follow-up `24178275f` adds narrowly scoped ownership, error-sanitization, and timeout guards. The resulting PR diff is 23 files, +988/−436. Cursor DOM injection and private CDP network transport remain separate because they are independently reviewable mechanisms and cleanly additive diffs. The legacy coordinate `returnXPath` request is still accepted here but fails explicitly until #2835 removes the option. This remains an intentionally non-publishable intermediate head. ## E2E Test Matrix Fresh post-flatten verification used the actual built CLI at final head `6f7e9c209`. Every daemon command used an isolated owner-only runtime directory. | Command / flow | Observed output | Confidence / sufficiency | | --- | --- | --- | | `pnpm install --frozen-lockfile` | Lockfile passed supply-chain policy, was already up to date, and installation completed | Proves the flattened stack resolves exactly from the committed lockfile | | `pnpm exec turbo run build --filter=browse` | Protocol, extension, Stagehand SDK, and Browse CLI built successfully (4/4 tasks) | Proves the CLI was tested against this head's protocol/extension/SDK artifacts, not stale workspace `dist` files | | Compare the rebuilt extension with `packages/sdk-go/internal/extensionassets/stagehand-extension.zip` | Exact byte match; both SHA-256 `8efc7d171a625cca95c02d02d369b59435fae776cae6c7dd2f6fe72eb19785c0`; archive manifest and package version both `1.0.2` | Confirms the TypeScript/CLI build and Go-embedded extension are synchronized | | Built CLI: `browse open <synthetic-data-url> --remote`; `browse status` | Remote browser connected and initialized; deterministic fixture loaded | Exercises production Browserbase provisioning plus the V4 daemon/session lifecycle on the exact final head | | `browse get text //h1`; `fill`; `select`; `click`; `is checked`; `wait selector`; `highlight`; `viewport`; `screenshot`; `snapshot --full` | XPath returned `Ready`; input became `Ada`; select became `b`; click produced `Clicked`; checkbox was true; PNG was 17,761 bytes; snapshot contained the fixture | Covers deterministic V4 reads, actions, waits, state, and rendering without an LLM | | Set a page marker; `tab new`; `tab list`; `tab close`; read the marker from a new CLI process | Tab count changed to 2 and the original page returned marker `yes` | Proves daemon persistence, active-tab handling, and state reuse across invocations | | Inspect the isolated runtime directory/PID; `browse stop`; poll the Browserbase session | Modes were `0700` / `0600`; the owned remote session reached `COMPLETED` | Proves owner-only daemon files and owned Browserbase resource cleanup | | `browse cursor`; `browse network on`; `browse mouse hover ... --return-xpath` | Each exited 1 with the intended explicit layer-boundary error | Confirms this intermediate layer fails honestly until the cursor, network, and flag-removal layers land | | `pnpm --filter browse test` | 25 files / 385 tests passed | Full Browse unit/integration suite on the exact final head | The runner has no Chrome/Chromium installation, so a fresh attached-CDP ownership smoke was not possible. Attached-browser non-ownership remains covered by the focused suite and is not claimed as a fresh live result here.

Send Context names to the production API while preserving the local alias cache for legacy name-to-ID lookup. Write cache updates atomically through unique private temp files.

## Summary Restore Browse's visible cursor as a CLI-owned DOM overlay, without adding a cursor API to core Stagehand V4. - Keep the overlay implementation in one dedicated `cursor-overlay.ts` file. - Install it idempotently for the current document through `page.evaluate(CURSOR_OVERLAY_SCRIPT)` and for future navigations through `page.addInitScript(...)`. - Retry installation on `DOMContentLoaded` when the init script runs before the document root exists. - Keep injection in the top frame and update the marker from coordinate input, including when input lands inside a child frame. - Treat visual position updates as best-effort so they cannot block or invalidate real mouse input. - Preserve the V3 `browse cursor` JSON response: `{ "cursor": "enabled" }`. ## 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 this is separate The cursor is a self-contained optional visual feature with different review concerns from the combined V4 runtime/command migration: injected DOM/CSS, idempotency, event handling, and screenshot behavior. Keeping it additive on #2834 lets this feature be reviewed or reverted without disturbing browser lifecycle or commands. ## E2E Test Matrix Review-feedback verification compared the exact prior head `6a9d6aa09` with fixed implementation head `1035fbbf5` through the built CLI and real Browserbase browsers. Final head `68f6fcb2c` only expands automated coverage and does not change runtime code. Targets were the public `example.com` and `example.org` pages. | Command / flow | Observed output | Confidence / sufficiency | | --- | --- | --- | | Prior head: enable cursor, alternate 20 cross-origin navigations, inspect `#__browse_cursor_overlay__` before any mouse input | Overlay count was `0` after 20/20 navigations | Reproduces the DOM-readiness bug raised in review | | Fixed head: repeat the same 20-navigation flow | Overlay count was `1` after 20/20 navigations (0 misses) | Proves the `DOMContentLoaded` retry restores the overlay after navigation in the real browser path | | Prior head: replace the page's cursor-position callback with a throwing function, then run `browse mouse click 200 200` against an oversized synthetic button | Command exited `1`; the page's click state remained `null` | Reproduces the visual-update failure blocking real mouse input | | Fixed head: repeat the same forced overlay failure and click | CLI returned `{ "clicked": true }`; page click state became `"yes"` | Proves overlay rendering is best-effort while real input still executes | | Built CLI: `browse cursor` | `{ "cursor": "enabled" }` (prior head returned `{ "enabled": true }`) | Confirms V3-compatible output for existing scripts | | `pnpm --filter browse lint` | Passed formatting, ESLint, and TypeScript checks | Static validation on the final head | | `pnpm --filter browse test:cli` | 26 files / 393 tests passed | Full Browse suite, including DOM readiness, safe styling, idempotency, top-frame isolation, cursor positioning/clamping, and all four coordinate input commands | | `browse stop` after each live run | Completed successfully | Covers Browserbase session and daemon cleanup | The already-uploaded screenshot below remains representative visual proof of the same overlay behavior. ![Browse V4 CLI cursor overlay surviving navigation and pointing inside an iframe](https://raw.githubusercontent.com/browserbase/stagehand/agent/browse-v4-e2e-assets/e2e-proof/browse-v4-cli-cursor-navigation-iframe-20260901.png) No LLM path or customer data was involved.

shrey150 force-pushed the agent/browse-v4-7-context-names branch from 787d68e to 3137f75 Compare August 28, 2026 02:52

shrey150 force-pushed the agent/browse-v4-7-context-names branch from 82ba9d7 to d2bee7e Compare September 11, 2026 17:49

shrey150 force-pushed the agent/browse-v4-7-context-names branch from d2bee7e to b69a671 Compare September 11, 2026 18:23

shrey150 force-pushed the agent/browse-v4-7-context-names branch from b69a671 to af0261a Compare September 11, 2026 20:19

shrey150 force-pushed the agent/browse-v4-7-context-names branch from af0261a to ca065c8 Compare September 15, 2026 23:10

shrey150 force-pushed the agent/browse-v4-7-context-names branch from ca065c8 to a93dd61 Compare September 15, 2026 23:31

feat(cli): use Browserbase-managed Context names

998652c

Send Context names to the production API while preserving the local alias cache for legacy name-to-ID lookup. Write cache updates atomically through unique private temp files.

shrey150 force-pushed the agent/browse-v4-7-context-names branch from a93dd61 to 998652c Compare September 16, 2026 00:23

Navigation Menu

fix(cli): persist context names in Browserbase - #2839

fix(cli): persist context names in Browserbase#2839
shrey150 wants to merge 1 commit into
agent/browse-v4-6-releasefrom
agent/browse-v4-7-context-names

shrey150 commented Aug 27, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Aug 27, 2026 •

edited

Loading

Uh oh!

socket-security Bot commented Aug 27, 2026 •

edited

Loading

Uh oh!

shrey150 commented Aug 27, 2026

Uh oh!

shrey150 commented Aug 27, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

shrey150 commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Stack (#2872)

Why the cache remains

E2E Test Matrix

Uh oh!

changeset-bot Bot commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

socket-security Bot commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shrey150 commented Aug 27, 2026

Uh oh!

shrey150 commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

shrey150 commented Aug 27, 2026 •

edited

Loading

changeset-bot Bot commented Aug 27, 2026 •

edited

Loading

socket-security Bot commented Aug 27, 2026 •

edited

Loading

shrey150 commented Aug 27, 2026 •

edited

Loading