refactor(cli): migrate Browse runtime and commands to Stagehand V4

Merged
SH
2mo ago
+1030-460

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 / flowObserved outputConfidence / sufficiency
pnpm install --frozen-lockfileLockfile passed supply-chain policy, was already up to date, and installation completedProves the flattened stack resolves exactly from the committed lockfile
pnpm exec turbo run build --filter=browseProtocol, 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.zipExact byte match; both SHA-256 8efc7d171a625cca95c02d02d369b59435fae776cae6c7dd2f6fe72eb19785c0; archive manifest and package version both 1.0.2Confirms the TypeScript/CLI build and Go-embedded extension are synchronized
Built CLI: browse open <synthetic-data-url> --remote; browse statusRemote browser connected and initialized; deterministic fixture loadedExercises 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 --fullXPath returned Ready; input became Ada; select became b; click produced Clicked; checkbox was true; PNG was 17,761 bytes; snapshot contained the fixtureCovers 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 processTab count changed to 2 and the original page returned marker yesProves daemon persistence, active-tab handling, and state reuse across invocations
Inspect the isolated runtime directory/PID; browse stop; poll the Browserbase sessionModes were 0700 / 0600; the owned remote session reached COMPLETEDProves owner-only daemon files and owned Browserbase resource cleanup
browse cursor; browse network on; browse mouse hover ... --return-xpathEach exited 1 with the intended explicit layer-boundary errorConfirms this intermediate layer fails honestly until the cursor, network, and flag-removal layers land
pnpm --filter browse test25 files / 385 tests passedFull 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.