feat(stagehand): expose typed network capture events

Draft
SH
3mo ago
+667-81

Summary

Expose a public, typed page-scoped network stream for Browse and other Stagehand V4 clients.

  • page.on("network", listener) emits request, completion, and failure events.
  • Completion events include response metadata, duration, and best-effort response bodies.
  • Request keys include the CDP session ID, so identical request IDs in OOPIFs cannot collide.
  • Capture follows current and future page-owned OOPIF sessions.
  • Unsubscribe removes only this observer; it deliberately does not call Network.disable, because Stagehand navigation and networkidle share that domain.

Landing status

This public network-event API draft is intentionally not part of the Browse V4 landing stack. It remains open because it has already been shared for framework/API design review.

The Browse CLI restores its V3 network command through a CLI-private CDP sidecar in #2849, without depending on this PR or committing Stagehand to these schemas.

Landing stack (#2872): #2833 → #2834 → #2869 → #2849 → #2835 → #2838 → #2839 → #2701

Review boundary

This is an independent core Stagehand API-design draft. No PR in the Browse V4 landing stack consumes it. The proposal extends the existing NetworkManager; TypeScript exports a discriminated PageNetworkEvent union, while Python and Go receive compatible generated additions. Review it on the merits of that long-lived public contract, not as migration plumbing.

Usage proven by E2E

The following standalone Stagehand script was typechecked and rerun against real Chromium on the cursor-free rewritten head c0de0a14c:

import {
  localBrowser,
  Stagehand,
  type PageNetworkEvent,
} from "@browserbasehq/stagehand";

const browser = await localBrowser.launch({ headless: true });
const stagehand = await Stagehand.create({ browser });
const pages = await stagehand.browser.context.pages();
const page = pages[0] ?? (await stagehand.browser.context.newPage());

const events: PageNetworkEvent[] = [];
const subscription = await page.on("network", (event) => {
  events.push(event);

  if (event.method === "Network.requestWillBeSent") {
    console.log(event.params.httpMethod, event.params.url, event.params.body);
  }
  if (event.method === "Network.loadingFinished") {
    console.log(event.params.status, event.params.mimeType, event.params.body);
  }
  if (event.method === "Network.loadingFailed") {
    console.error(event.params.errorText);
  }
});

await page.goto("https://example.com");
await subscription.unsubscribe();
await stagehand.close();
await browser.close();

E2E Test Matrix

Command / flowObserved outputConfidence / sufficiency
Build the extension and TypeScript SDK, then typecheck and run the script above against real ChromiumNETWORK_STREAM_PASS; document title Network E2EProves the public SDK API is executable, not only mocked
Page load plus POST /api/data3 Network.requestWillBeSent and 3 Network.loadingFinished eventsProves the page-level stream exposes the network firehose used by Browse
Inspect the captured POSTMethod POST, path /api/data, body {"probe":"network-firehose"}Proves request bodies are available
Inspect the captured responseStatus 200, MIME application/json, body {"value":"network-body-ok"}, base64Encoded: falseProves response metadata and best-effort bodies are available
Call subscription.unsubscribe(), then issue more trafficNo further delivery to the listenerProves observer cleanup without disrupting the shared Network domain
Protocol, extension, SDK, Python, and Go checksUnit/type/build/generator-drift checks passed, including OOPIF request-ID collision coverageCovers cross-language shape and OOPIF bookkeeping beyond the main-frame browser smoke
Exact cursor-free rewritten head4 files / 135 network, protocol, extension, and SDK tests passedProves removing the unrelated cursor API did not disturb the network event contract

The real-browser smoke covers a local main page. OOPIF collision handling, redirects/failures, and cross-language generation are covered by automated tests rather than a second live-browser fixture.