refactor(cli): port core browser plumbing to V4

[shrey150]

Summary

• construct managed-local, CDP, and Browserbase sessions with the V4 browser-source options
• adapt session, tab, page-info, and navigation plumbing to V4's asynchronous browser context and page APIs
• preserve the existing Browserbase session ID, dashboard URL, and best-effort live-view URL fields
• register browse in the V4 pnpm lockfile and Turbo build/test graph

CLI contract changes

Existing commands, flags, and successful JSON field names remain unchanged:

• the CLI continues to expose targetId, even though the V4 SDK calls the same underlying browser target identifier pageId
• timeoutMs remains the CLI navigation input and maps internally to V4's timeout
• browserbaseSessionId, browserbaseSessionUrl, and best-effort browserbaseDebugUrl remain present for remote sessions

One runtime requirement changes: browse now requires Node.js 22.18.0 or newer, matching the V4 SDK.

Stack boundary

This child ports the core browser/session plumbing only. The next child replaces the remaining V3 action, cursor, and network calls. Until that child lands, the full CLI build is expected to remain incomplete.

No Changeset is included because this stack targets the pre-release V4 spike.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
CI=true corepack pnpm@11.10.0 install --frozen-lockfile --prefer-offline on the exact commit	Supply-chain policy check passed; the frozen lockfile installed all 1,493 packages	Proves the copied CLI is represented by the V4 workspace lockfile without mutating it
corepack pnpm@11.10.0 --dir packages/cli exec vitest run tests/remote-options.test.ts tests/remote-disabled.test.ts tests/identity-attribution.test.ts	3 files passed; 40 tests passed	Covers V4 Browserbase constructor options, local-only isolation, and preservation of existing remote session result fields
Targeted V4 session-manager cases in tests/driver-foundation.test.ts	10 tests passed; 22 unrelated tests skipped	Covers V4 local launch options, async page selection, status summaries, CDP target lookup, and forwarded environment behavior
Targeted navigation and tab cases in tests/driver-commands.test.ts	3 tests passed; 13 unrelated tests skipped	Covers timeoutMs mapping and V4 async tab close/selection while preserving public targetId output

---

Summary by cubic

Ports the CLI’s browser/session plumbing to @browserbasehq/stagehand V4, adopting async context/page APIs and V4 browser option shapes. CLI flags and output stay the same, Browserbase identity fields are preserved, and Node.js 22.18.0+ is required.

• Refactors

  • Switch managed-local, CDP, and Browserbase to V4 browser options (type: "local" | "cdp" | "browserbase") with logging off.
  • Update navigation, tabs, and page-info to async APIs; replace deepLocator with locator; use internal pageId while continuing to output targetId.
  • Normalize navigation options via a shared helper: map timeoutMs to V4 timeout and pass through waitUntil for open/reload/back/forward.
  • Preserve browserbaseSessionId, browserbaseSessionUrl, and best-effort browserbaseDebugUrl by resolving identity post-init with remoteBrowserbaseIdentity using @browserbasehq/sdk.
  • Add browse#build to the Turbo graph and a test:unit script.

• Migration

  • Node.js >=22.18.0 is required to match @browserbasehq/stagehand V4.

^{Written for commit eeb6d0b. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: eeb6d0b

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