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

The actual built CLI on final head 24178275f was rerun against a deterministic synthetic page in a real Browserbase browser. Attached-browser ownership was separately exercised against a real external Chromium CDP endpoint.

Command / flow	Observed output	Confidence / sufficiency
Built CLI: browse open <synthetic-data-url> --remote; browse status	Connected and initialized in remote mode	Exercises the production Browserbase launch and daemon lifecycle on the exact PR head
browse get with CSS and XPath	Both resolved; XPath <h1> returned Ready	Covers deterministic selector reads, including V4 deep-locator-compatible XPath
browse fill; select; click; is; highlight; wait; viewport; screenshot	Filled Ada, selected b, checkbox checked, click result Clicked; screenshot 9,391 bytes	Covers the standard non-LLM command translation against a real browser
browse tab list; tab new; tab close	Tab count changed 1 → 2 → 1	Covers V4 tab creation, selection, and cleanup
Cursor, network, and coordinate-XPath boundary calls	Each exited 1 with its intended explicit capability error	Confirms this intermediate head fails honestly until later stack layers
browse stop; then browse cloud sessions get <redacted-id>	Stop succeeded; owned Browserbase session reached COMPLETED	Proves owned remote cleanup, not only daemon shutdown
Attach to an externally launched Chromium with --cdp; then browse stop	Stop reported success while the external browser stayed alive and its CDP endpoint remained responsive	Directly proves connected-browser ownership is preserved; this is local Chromium, not Browserbase
pnpm --filter browse lint	Prettier, ESLint, and TypeScript passed	Static verification for the exact head
pnpm --filter browse test	25 files / 385 tests passed	Full Browse unit/integration suite; supplements rather than replaces the live runs

The fixture is synthetic and deterministic; no LLM path is involved.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2417827

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>