feat(cli): port the browser runtime to V4

[shrey150]

Summary

• migrate managed-local, CDP, and Browserbase session lifecycle to V4 browser factories and Stagehand.create
• use the supported Browserbase launch path so remote sessions receive the V4 extension and own cleanup
• consume the newly public V4 Browserbase sessionId to restore session, dashboard, and best-effort live-view output
• port navigation, tabs, page information, selector operations, uploads, highlights, coordinate actions, and screenshot byte encoding to public V4 APIs
• keep daemon open requests alive for browser initialization plus the requested navigation timeout
• return explicit errors for cursor overlay, network capture enablement, and coordinate XPath results that V4 does not expose

Refreshed on 2026-08-10 against the current parent and v4-spike commit d7556e9a.

Contract / parity status

Surface	Result
Commands, flags, oclif manifest, help, packaged file list, bundled skill, and successful JSON shapes	Exact parity with npm browse@0.9.6
Selector click/fill/select/upload/highlight	Backed directly by V4 locators
Coordinate click/hover/scroll/drag	Backed by V4 page methods; unset options are omitted
--return-xpath on coordinate commands	Explicit capability error because V4 removed the XPath result contract
Cursor overlay	Explicit capability error until a public V4 API exists
Network capture	Explicit capability error until public V4 raw-CDP/network APIs exist
Remote session identity fields	Restored from the public V4 browser handle sessionId; the CLI returns the stable dashboard URL and best-effort live-view URL
Standalone npm install	@browserbasehq/stagehand@4.0.0 is published; a clean packed-CLI install resolves workspace:* to 4.0.0. The child deterministic-action PR intentionally schedules the next Stagehand patch through its changeset

This means command-surface parity is complete, but runtime feature parity is not yet complete in the three capability areas above.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
2026-08-10 cumulative stack refresh on Chrome Stable 151	pnpm build passed 6/6 tasks; pnpm check passed 11/11 tasks with 0 errors; the full pnpm test graph exited 0, including 17/17 protocol browser tests and 15/15 local SDK browser tests	Proves the updated six-PR stack is compatible with v4-spike d7556e9a across build, static checks, unit tests, and real-browser suites.
Clean coordinated-release tarball consumer at the cumulative tip	Packed workspace Stagehand and Browse, installed both into an empty npm project, opened example.com, produced a snapshot, clicked through to IANA, filled an injected input, and read back published-v4-ok	Proves the intended co-published artifacts work outside the monorepo with a real Chrome session; it does not substitute for a credentialed Browserbase smoke.
#2525 branch build, check, and CLI unit gates	6/6 build tasks; 10/10 checks with 399 warnings and 0 errors; 25 files and 378/378 CLI tests passed	Proves the first affected stack layer compiles independently, including V4 screenshot byte encoding.
Real managed-local Chrome Stable 151 synthetic form	{ value: "hello-v4-final", color: "green", file: "package.json", clicked: "yes", title: "CLI V4" }	Exercises real CLI → daemon → V4 SDK → extension flows for snapshot refs, fill, select, upload, click, evaluate, and cleanup.
Real managed-local public navigation and tabs	Opened https://example.com, read Example Domain, created/listed/switched/closed a second tab by stable target ID	Exercises real network navigation, public page reads, tab identity, and active-page restoration.
Real screenshot base64	15,180 base64 characters decoded to 11,384 bytes with a valid PNG signature	Exercises the real V4 screenshot return type and CLI byte encoding.
Real coordinate click	Returned { "clicked": true }	Exercises supported V4 coordinate actions without XPath return.
Real unsupported capability probes	Network, cursor, and coordinate --return-xpath each exited 1 with the documented capability error	Confirms gaps fail explicitly rather than silently regressing.
Real stop race/idempotency	First stop returned stopped: true; second returned stopped: false	Exercises the published 0.9.6 daemon cleanup/race behavior.
Remote Browserbase rerun	Not run: no BROWSERBASE_API_KEY is available in this environment; session identity is covered by a focused launch/debug regression test	Remaining live verification; GitHub CI is the next credentialed gate. Previous pre-refresh remote evidence is intentionally not counted for the new heads.
Final cumulative repository gates	6/6 build tasks, 11/11 checks, 1,788 JavaScript tests, 455 Python tests, and Go live Chrome tests passed	Broad regression coverage across the refreshed V4 repository.

Includes a browse patch changeset for the V4 runtime migration.

Final release validation (2026-08-10)

At the cumulative stack tip:

• release validation now recognizes public browse changesets
• a Changesets version dry run resolves browse 0.9.7, Stagehand 4.0.1, extension 1.0.1, and Go 4.0.1
• the packed Browse 0.9.7 manifest rewrites workspace:* to exact Stagehand 4.0.1
• a clean npm consumer installed those versioned tarballs and completed real-Chrome open, snapshot, model-free click, URL read, and stop with zero audit vulnerabilities

[changeset-bot]

🦋 Changeset detected

Latest commit: feeadf7

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

[shrey150]

Superseded by #2834, which is based on the mechanical CLI baseline in #2833. The replacement performs the Stagehand V4 lifecycle/runtime cutover while keeping cursor and network API work below it in #2831 and #2832. Closing this draft.