fix(cli): restore V3 network capture through a CDP sidecar

[shrey150]

Summary

Restore Browse V3 network-capture behavior on Stagehand V4 through a CLI-private CDP sidecar, without committing core Stagehand, its protocol, or generated SDKs to a public network-event schema.

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)

Architecture

• Lazily open one CLI-private browser-level CDP WebSocket using the endpoint already held by the initialized Stagehand client.
• Attach a flattened CDP session to the active V4 page target.
• Present the unchanged V3 network writer with the same on / off / send session shape.
• On network off, remove listeners, send Network.disable, and detach the page target.
• Keep the browser-level sidecar WebSocket alive across off/on cycles; closing an auxiliary Browserbase socket during the live session can disconnect the browser.
• Close the sidecar only during Browse session cleanup.
• Never log or return the signed browser WebSocket endpoint.

The request correlation and request/response JSON writer are inherited from the V3 CLI. No public protocol schema, extension, SDK, or generated-client changes are included. #2832 remains open outside the landing stack for that separate API-design discussion.

User-visible behavior

The V3 command and file surface is retained:

browse network on
browse network path
browse network clear
browse network off

Each request directory contains request.json and, when available, response.json, including the existing treatment of POST bodies, response bodies, failures, redirects, cache hits, and binary responses.

Built V3 vs V4 differential

The actual built V3 CLI and this actual built V4 CLI were run as subprocesses against the same deterministic HTTP fixture at network implementation commit 5d39c89d7f. Current stack head 61cc82f51 additionally contains propagated upstream runtime and cursor review fixes; it does not change the sidecar implementation.

Flow	V3	V4	Result
on/path/off/path/clear return shape	Expected enabled/path states	Same	Command diffs []
Evaluation: GET, cached GET, POST, redirect, binary, aborted request	Completed	Completed	Exact result match
Captured artifacts	8 requests / 7 responses	8 requests / 7 responses	Same counts
Normalized request/response JSON	8 records	8 records	0 structural differences
POST	Request body + 201 response body	Same	Match
Redirect	request-only /redirect + response for /final	Same V3 behavior	Match
Aborted request	Status 0 failure response	Same	Match
Permissions	Directories 0700; files 0600	Same	Match
Clear	0 entries remained	0 entries remained	Match

Normalization was limited to values that cannot match across independent browser runs: CDP request ID, timestamp, duration, HTTP Date, and fixture origin/port. Header names/casing, methods, paths, bodies, statuses, MIME types, status text, error shape, counters, and file modes were compared as emitted.

Real Browserbase lifecycle

The actual built CLI completed two network on → navigate → off cycles in one Browserbase session. Each cycle captured a GET 200 and the full Example Domain response body with 0700/0600 permissions. The Browserbase session identity stayed stable, a subsequent open --wait networkidle succeeded, status remained connected/initialized/remote, and browse stop completed.

Real-site stress E2E

The exact built V3 CLI (7365a20d5) and exact built #2849 CLI (5d39c89d7f) each ran two bounded capture cycles in one real Browserbase session: network on → path → open → scroll → collect for 12s → off → path → navigate while off → status → clear. MSN and CNN were used as public, request-heavy targets.

Public target	V3 artifacts	V4 #2849 artifacts	Observed parity / robustness
MSN	368 requests / 350 responses; 363 cross-origin requests; 5 cross-origin documents; 5 failures; 193 base64 bodies	441 requests / 413 responses; 436 cross-origin requests; 5 cross-origin documents; 6 failures; 238 base64 bodies	Both captured GET/POST/OPTIONS plus Document, Script, Fetch, XHR, Image, Font, Ping, and failure traffic.
CNN	197 requests / 193 responses; 159 cross-origin requests; 2 cross-origin documents; 7 failures; 114 base64 bodies	193 requests / 186 responses; 155 cross-origin requests; 2 cross-origin documents; 7 failures; 111 base64 bodies	Both captured GET/POST/OPTIONS plus Document, Script, Fetch, XHR, Image, Font, Stylesheet, Media, and failure traffic.
Lifecycle and files	21/21 commands completed; slowest 4.2s	21/21 commands completed; slowest 6.3s	Command result shapes matched. Zero malformed JSON or response-ID mismatches; directories were 0700, files 0600; navigation after off added zero records; clear left zero entries after both cycles.
Session and endpoint safety	One stable remote session across both cycles; stopped and disconnected cleanly	Same	No hangs, sidecar disconnects, browser-session loss, or WebSocket endpoint in CLI output.

Live sites are nondeterministic, so request counts and exact request sets are reported rather than expected to match. Request-only records at the bounded off point were 18/4 for V3 and 28/7 for V4 across MSN/CNN, reflecting in-flight or long-lived traffic; every emitted response parsed and matched its request ID. This matrix exercises high-concurrency HTTP traffic and cross-origin documents, but does not claim WebSocket-frame, SSE-message, service-worker, or every out-of-process-iframe edge-case coverage.

• At network proof commit 5d39c89d7f, pnpm --filter browse lint passed.
• At network proof commit 5d39c89d7f, pnpm --filter browse test passed: 27 files / 383 tests.
• Focused coverage includes WebSocket reuse, target attach/detach, CDP routing, off/on lifecycle, request-write races, response bodies, and V3-shaped files.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 61cc82f

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