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

[shrey150]

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: e0e9ffe

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

All reported issues were addressed across 22 files

Architecture diagram

sequenceDiagram
    participant CLI as Browse CLI Client
    participant Daemon as Driver Daemon
    participant Manager as Driver Session Manager
    participant Factory as Stagehand V4 Browser Factories
    participant BB as Browserbase
    participant Browser as Browser or CDP Target
    participant Stagehand as Stagehand V4 Session
    participant Context as Browser Context and Pages
    participant Page as Active Page and Locators

    Note over CLI,Page: Browse runtime uses a daemon-owned session and Stagehand V4 browser lifecycle

    CLI->>Daemon: Open or execute driver command
    Daemon->>Daemon: Resolve session, target, and forwarded environment
    Daemon->>Manager: Dispatch request

    alt Managed local target
        Manager->>Factory: localBrowser.launch(headless, Chrome args)
        Factory->>Browser: Launch local browser
        Browser-->>Factory: Browser handle
    else Browserbase remote target
        Manager->>Factory: browserbase.launch(apiKey, userMetadata, flags)
        Factory->>BB: Create managed remote session
        BB-->>Factory: Browser handle and session identity
        Factory->>BB: Lookup debug URL
        BB-->>Factory: Optional live-view URL
        Factory-->>Manager: Browser and Browserbase identity
    else Attached CDP target
        Manager->>Factory: localBrowser.connect(cdpUrl)
        Factory->>Browser: Attach to existing browser
        Browser-->>Factory: Browser handle
    end

    Manager->>Stagehand: Stagehand.create(browser, logging off)
    Stagehand->>Context: Resolve browser context
    Context-->>Manager: Context and page collection
    Manager-->>Daemon: Session initialized
    Daemon-->>CLI: Open result, mode, pages, and session identity

    CLI->>Daemon: Navigation, query, input, tab, or runtime command
    Daemon->>Manager: Dispatch command
    Manager->>Context: Resolve active or requested page
    Context-->>Manager: Active page
    Manager->>Page: Call V4 page API

    alt Standard command succeeds
        Page->>Page: Navigate, query locator, click, fill, select, type, screenshot, eval, or manage tabs
        Page-->>Manager: Result
        Manager-->>Daemon: Command response
        Daemon-->>CLI: Result data
    else Coordinate XPath requested
        Page-->>Manager: Error: coordinate XPath unavailable in V4
        Manager-->>Daemon: Explicit capability error
        Daemon-->>CLI: Command failure
    else Cursor or network capability requested
        Manager-->>Daemon: Explicit unavailable capability error
        Daemon-->>CLI: Command failure
    end

    Note over Daemon,Manager: Open requests allow browser initialization time plus the configured navigation timeout

    CLI->>Daemon: Stop session
    Daemon->>Manager: Close session
    Manager->>Stagehand: Close Stagehand session
    Manager->>Browser: Close owned browser
    alt Attached CDP target
        Manager->>Browser: Preserve externally owned browser
    else Managed local or Browserbase target
        Browser-->>Manager: Owned resources cleaned up
    end
    Manager-->>Daemon: Session stopped
    Daemon-->>CLI: Stop result

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[AzamAbdul]

LGTM at first pass of v4 vs v3 contract changes. One comment from Astra wrt potential left over connections