browxai 0.7.0

package/dist/page/network-substrate.d.ts

@@ -0,0 +1,109 @@
+import type { BrowserContext, CDPSession, Page } from "playwright-core";
+import type { SecretRegistry } from "../util/secrets.js";
+import { NetworkBuffer, WsBuffer, type NetworkEntry, type NetworkSummary, type MutationEntry, type SessionNetworkRing, type SessionWsRing } from "./network.js";
+import { PlaywrightNetworkBuffer, PlaywrightWsBuffer } from "./network-playwright.js";
+/** The per-action network tap — opened before an action dispatches, closed after
+ *  the settle window. `close()` returns the same `{summary, requests, mutations}`
+ *  shape on every engine so the ActionResult envelope builder is engine-blind. */
+export interface ActionNetworkTap {
+    open(): Promise<void>;
+    close(): Promise<{
+        summary: NetworkSummary;
+        requests: NetworkEntry[];
+        mutations: MutationEntry[];
+    }>;
+}
+/** The full-response-body result shape returned by `fetchBody` — the same shape
+ *  `fetchResponseBody` (the CDP path) returns, so `network_body` is engine-blind. */
+export interface FetchBodyResult {
+    ok: boolean;
+    body?: string;
+    base64Encoded?: boolean;
+    truncated?: boolean;
+    error?: string;
+}
+/** The network observation source the network tools + the action window consume.
+ *  One instance wraps one session's engine handle(s); the methods carry no engine
+ *  type, so the surface above this seam is engine-agnostic. Mirrors the
+ *  SnapshotSubstrate shape: an interface selected by capability, the handle
+ *  captured at construction, the session-wide buffers owned here and attached
+ *  once, no per-call allocation on the hot path beyond the per-action tap the CDP
+ *  path already allocated. */
+export interface NetworkSubstrate {
+    /** Engine tag — for diagnostics + the per-engine keystone matrix. */
+    readonly engine: string;
+    /** Session-wide ring of recent HTTP requests (network_read; asset_export's
+     *  `iter()`; session_metrics). Attached once at session creation. */
+    readonly http: SessionNetworkRing;
+    /** Session-wide ring of recent WebSocket / SSE frames (ws_read; the action
+     *  window's `wsFrames` slice via `since()`). Attached once at session
+     *  creation. */
+    readonly ws: SessionWsRing;
+    /** Attach the session-wide rings to their engine source. Idempotent. */
+    attach(): Promise<void>;
+    /** Wire the per-session secrets registry into every egress sink the substrate
+     *  owns (both rings + the per-action taps it mints). */
+    setSecrets(secrets: SecretRegistry): void;
+    /** Mint a per-action tap for one action window. On chromium this is the
+     *  verbatim CDP `NetworkTap`; off Chromium it is the Playwright-event tap. */
+    openActionTap(): ActionNetworkTap;
+    /** Fetch a full response body by request id (network_body, capability
+     *  `network-body`). CDP fetches on demand; the Playwright path returns a body
+     *  captured at response time. */
+    fetchBody(requestId: string, secrets: SecretRegistry | null): Promise<FetchBodyResult>;
+}
+/** Chromium substrate — the existing CDP network path, moved behind the interface
+ *  VERBATIM. The buffers are the same `NetworkBuffer` / `WsBuffer` constructed on
+ *  the CDP handle, `openActionTap` mints the same `NetworkTap`, and `fetchBody`
+ *  delegates to the same `fetchResponseBody`. Output is byte-identical to the
+ *  pre-seam path, so the chromium keystones + unit tests are unchanged. The CDP
+ *  handle is captured here once; callers never see it. */
+export declare class CdpNetworkSubstrate implements NetworkSubstrate {
+    private readonly cdp;
+    readonly engine = "chromium";
+    readonly http: NetworkBuffer;
+    readonly ws: WsBuffer;
+    private secrets;
+    constructor(cdp: CDPSession);
+    attach(): Promise<void>;
+    setSecrets(secrets: SecretRegistry): void;
+    openActionTap(): ActionNetworkTap;
+    fetchBody(requestId: string, secrets: SecretRegistry | null): Promise<FetchBodyResult>;
+}
+/** Firefox / WebKit substrate — the Playwright context-event network path. No
+ *  CDP. The session-wide rings are `PlaywrightNetworkBuffer` / `PlaywrightWsBuffer`
+ *  (the same ring shapes, fed by `context.on('request'|'response'|'requestfailed')`
+ *  and `page.on('websocket')`). The per-action tap is the Playwright-event
+ *  `PlaywrightNetworkTap`, and `fetchBody` reads from the body cache the buffer
+ *  captured at response time. */
+export declare class PlaywrightNetworkSubstrate implements NetworkSubstrate {
+    private readonly context;
+    readonly engine: string;
+    readonly http: PlaywrightNetworkBuffer;
+    readonly ws: PlaywrightWsBuffer;
+    private secrets;
+    constructor(context: BrowserContext, page: Page, engine?: string);
+    attach(): Promise<void>;
+    setSecrets(secrets: SecretRegistry): void;
+    openActionTap(): ActionNetworkTap;
+    fetchBody(requestId: string, secrets: SecretRegistry | null): Promise<FetchBodyResult>;
+}
+/** Safari substrate — a NO-OP. Real Safari has NO protocol-level
+ *  network observation or interception at all: safaridriver's WebDriver Classic
+ *  has no network tap, and Safari's experimental BiDi ships only
+ *  `network.setCacheBehavior` (the `network` observation domain is absent). So
+ *  the network tools are
+ *  capability-gated on Safari and the action-window network slice is empty. This
+ *  empty substrate keeps the session-creation + envelope code engine-blind: the
+ *  rings are always empty, the per-action tap reports zero traffic, and
+ *  `network_body` returns a structured "not available". It is never the source of
+ *  truth for any surfaced network claim — the gate refuses the tools first. */
+export declare class SafariNoopNetworkSubstrate implements NetworkSubstrate {
+    readonly engine = "safari";
+    readonly http: SessionNetworkRing;
+    readonly ws: SessionWsRing;
+    attach(): Promise<void>;
+    setSecrets(): void;
+    openActionTap(): ActionNetworkTap;
+    fetchBody(): Promise<FetchBodyResult>;
+}

package/dist/page/network-substrate.js

@@ -0,0 +1,161 @@
+// The NetworkSubstrate interface — the engine-agnostic seam beneath the network
+// tools (network_read / ws_read / network_body) and the per-action ActionResult
+// network slice. It is the network side of the hybrid network substrate, with
+// Playwright events as the portable layer: the tools + the action window ask a
+// substrate for "the session network ring", "the WS/SSE ring", "a per-action tap",
+// and "a response body"; an engine-specific implementation answers.
+//
+// Dependency direction: tools / action-window →
+// NetworkSubstrate (this interface) → implementation → CDP / Playwright events. A
+// tool never reaches a CDPSession or a raw context event through this seam; the
+// engine handle is captured at substrate construction, so the per-call surface
+// carries no engine type. That is what un-couples the network slice from CDP and
+// lets network_read / ws_read / network_body run on Firefox.
+//
+// Two implementations behind it (hybrid):
+//   - CdpNetworkSubstrate (chromium): owns the EXISTING NetworkBuffer / WsBuffer /
+//     NetworkTap / fetchResponseBody CDP path VERBATIM — byte-identical buffers
+//     and per-action tap, so the chromium keystones + unit tests stay green
+//     unchanged. The CDP path is kept on chromium deliberately: the envelope is
+//     browxai's hottest path and benchmarking put the CDP
+//     tap at parity with the event tap on chromium, so there is no reason to move
+//     chromium off the substrate it already has.
+//   - PlaywrightNetworkSubstrate (firefox / webkit): the Playwright context
+//     `request` / `response` / `requestfailed` events feed the same NetworkBuffer
+//     shape; `page.on('websocket')` `framesent` / `framereceived` feed the same
+//     WsBuffer shape. network_body captures the response body at response time
+//     (Playwright `response.body()`), because — unlike CDP `Network.getResponseBody`
+//     — there is no after-the-fact body fetch off Chromium.
+//
+// Documented degradation off Chromium (honest, not a regression):
+//   - resourceType nuance: Playwright `request.resourceType()` is lowercase and a
+//     slightly coarser taxonomy than CDP's; mapped to the CDP-capitalised bucket
+//     names so the noise-folding + `byType` summary stay identical in shape.
+//   - timing precision: `ms` is wall-clock (request-seen → response-seen), the
+//     same approximation the CDP tap uses — no high-resolution `timing()` deltas.
+//   - body availability: bodies are captured at response time into a bounded LRU
+//     keyed by a synthetic request id; a body for a request that predates the
+//     capture window (or was evicted) is reported "not available", same best-
+//     effort contract as the CDP renderer-discard behaviour.
+import { NetworkBuffer, WsBuffer, NetworkTap, fetchResponseBody, } from "./network.js";
+// RFC 0004 P4 / D10 — the off-Chromium Playwright network classes are imported
+// DIRECTLY from their defining module, not re-exported through the `network.js`
+// barrel. The barrel re-export was a genuine RUNTIME cycle
+// (`network.ts` → `network-playwright.ts` → `network.ts`); routing this sole
+// runtime consumer to the source module breaks it so the no-circular rule is
+// clean at `error`. (network-playwright.ts still imports runtime helpers from
+// network.ts — that edge is one-directional now, so no cycle.)
+import { PlaywrightNetworkBuffer, PlaywrightWsBuffer, PlaywrightNetworkTap, } from "./network-playwright.js";
+/** Chromium substrate — the existing CDP network path, moved behind the interface
+ *  VERBATIM. The buffers are the same `NetworkBuffer` / `WsBuffer` constructed on
+ *  the CDP handle, `openActionTap` mints the same `NetworkTap`, and `fetchBody`
+ *  delegates to the same `fetchResponseBody`. Output is byte-identical to the
+ *  pre-seam path, so the chromium keystones + unit tests are unchanged. The CDP
+ *  handle is captured here once; callers never see it. */
+export class CdpNetworkSubstrate {
+    cdp;
+    engine = "chromium";
+    http;
+    ws;
+    secrets = null;
+    constructor(cdp) {
+        this.cdp = cdp;
+        this.http = new NetworkBuffer(cdp);
+        this.ws = new WsBuffer(cdp);
+    }
+    async attach() {
+        await this.http.attach();
+        await this.ws.attach();
+    }
+    setSecrets(secrets) {
+        this.secrets = secrets;
+        this.http.setSecrets(secrets);
+        this.ws.setSecrets(secrets);
+    }
+    openActionTap() {
+        return new NetworkTap(this.cdp, this.secrets);
+    }
+    fetchBody(requestId, secrets) {
+        return fetchResponseBody(this.cdp, requestId, undefined, secrets);
+    }
+}
+/** Firefox / WebKit substrate — the Playwright context-event network path. No
+ *  CDP. The session-wide rings are `PlaywrightNetworkBuffer` / `PlaywrightWsBuffer`
+ *  (the same ring shapes, fed by `context.on('request'|'response'|'requestfailed')`
+ *  and `page.on('websocket')`). The per-action tap is the Playwright-event
+ *  `PlaywrightNetworkTap`, and `fetchBody` reads from the body cache the buffer
+ *  captured at response time. */
+export class PlaywrightNetworkSubstrate {
+    context;
+    engine;
+    http;
+    ws;
+    secrets = null;
+    constructor(context, page, engine = "firefox") {
+        this.context = context;
+        this.engine = engine;
+        this.http = new PlaywrightNetworkBuffer(context);
+        this.ws = new PlaywrightWsBuffer(page);
+    }
+    async attach() {
+        await this.http.attach();
+        await this.ws.attach();
+    }
+    setSecrets(secrets) {
+        this.secrets = secrets;
+        this.http.setSecrets(secrets);
+        this.ws.setSecrets(secrets);
+    }
+    openActionTap() {
+        return new PlaywrightNetworkTap(this.context, this.secrets);
+    }
+    fetchBody(requestId, secrets) {
+        return this.http.fetchBody(requestId, secrets);
+    }
+}
+/** Safari substrate — a NO-OP. Real Safari has NO protocol-level
+ *  network observation or interception at all: safaridriver's WebDriver Classic
+ *  has no network tap, and Safari's experimental BiDi ships only
+ *  `network.setCacheBehavior` (the `network` observation domain is absent). So
+ *  the network tools are
+ *  capability-gated on Safari and the action-window network slice is empty. This
+ *  empty substrate keeps the session-creation + envelope code engine-blind: the
+ *  rings are always empty, the per-action tap reports zero traffic, and
+ *  `network_body` returns a structured "not available". It is never the source of
+ *  truth for any surfaced network claim — the gate refuses the tools first. */
+export class SafariNoopNetworkSubstrate {
+    engine = "safari";
+    http = {
+        setSecrets: () => undefined,
+        iter: () => [],
+        recent: () => ({ summary: { total: 0, byType: {}, failed: 0 }, requests: [] }),
+    };
+    ws = {
+        setSecrets: () => undefined,
+        recent: () => ({ total: 0, frames: [] }),
+        since: () => [],
+    };
+    attach() {
+        return Promise.resolve();
+    }
+    setSecrets() {
+        // No egress sinks to wire — the rings + tap are permanently empty on Safari.
+    }
+    openActionTap() {
+        return {
+            open: () => Promise.resolve(),
+            close: () => Promise.resolve({
+                summary: { total: 0, byType: {}, failed: 0 },
+                requests: [],
+                mutations: [],
+            }),
+        };
+    }
+    fetchBody() {
+        return Promise.resolve({
+            ok: false,
+            error: "network_body is not available on the safari engine — Safari exposes no protocol-level " +
+                "network observation. Use a chromium/firefox/webkit session for network bodies.",
+        });
+    }
+}

package/dist/page/network-ws.d.ts

@@ -0,0 +1,46 @@
+import type { CDPSession } from "playwright-core";
+import type { SecretRegistry } from "../util/secrets.js";
+export interface WsFrame {
+    /** WS/SSE endpoint URL (best-effort — empty if the create event was missed). */
+    url: string;
+    dir: "sent" | "recv";
+    kind: "ws" | "sse";
+    /** WS opcode (1=text, 2=binary, 8=close, 9=ping, 10=pong). Absent for SSE. */
+    opcode?: number;
+    /** SSE event name when present (`eventName` from CDP). */
+    event?: string;
+    /** Payload, truncated to `maxPayload` chars. */
+    payload: string;
+    truncated?: boolean;
+    ts: number;
+}
+/** Egress sanitizer for a WS/SSE frame: redact the endpoint url, any url
+ *  substrings inside the payload (a stream payload can echo a credentialled
+ *  URL too), and any registered-secret real-values that landed in the
+ *  payload (chat / multiplayer / live-dashboard broadcasts routinely echo
+ *  the auth blob the client sent). Returns a copy — the ring keeps raw
+ *  frames for url filtering. */
+export declare function sanitizeFrame(f: WsFrame, secrets: SecretRegistry | null): WsFrame;
+export declare class WsBuffer {
+    private cdp;
+    private cap;
+    private maxPayload;
+    private urls;
+    private ring;
+    private enabled;
+    /** Optional per-session secrets registry; egress masking is applied on
+     *  every `recent` / `since` read. */
+    private secrets;
+    constructor(cdp: CDPSession | undefined, cap?: number, maxPayload?: number);
+    setSecrets(secrets: SecretRegistry): void;
+    private trunc;
+    private push;
+    attach(): Promise<void>;
+    /** Most-recent N frames, optionally filtered by a url substring. */
+    recent(limit?: number, urlPattern?: string): {
+        total: number;
+        frames: WsFrame[];
+    };
+    /** Frames since a timestamp — for the per-action `ActionResult` slice. */
+    since(ts: number, cap?: number): WsFrame[];
+}

package/dist/page/network-ws.js

@@ -0,0 +1,113 @@
+// WebSocket / Server-Sent-Events frame capture (CDP substrate).
+//
+// The realtime slice of a session: anything that streams over a long-lived
+// connection (chat, multiplayer, collaborative editing, live dashboards) is only
+// observable at the frame level. `WsBuffer` is the session-wide analogue of
+// `NetworkBuffer`: a bounded ring of recent WS/SSE frames, payloads truncated.
+//
+// The frame shape (`WsFrame`) and the egress sanitiser (`sanitizeFrame`) are
+// shared with the off-Chromium Playwright WS ring (`network-playwright.ts`);
+// they live here, the home of the WS concern, and are re-exported through the
+// `./network.js` barrel so callers import them unchanged.
+import { maskedText, maskedUrl } from "./network-mask.js";
+/** Egress sanitizer for a WS/SSE frame: redact the endpoint url, any url
+ *  substrings inside the payload (a stream payload can echo a credentialled
+ *  URL too), and any registered-secret real-values that landed in the
+ *  payload (chat / multiplayer / live-dashboard broadcasts routinely echo
+ *  the auth blob the client sent). Returns a copy — the ring keeps raw
+ *  frames for url filtering. */
+export function sanitizeFrame(f, secrets) {
+    return {
+        ...f,
+        url: maskedUrl(f.url, secrets),
+        payload: maskedText(f.payload, secrets),
+    };
+}
+export class WsBuffer {
+    cdp;
+    cap;
+    maxPayload;
+    urls = new Map(); // requestId → endpoint url
+    ring = [];
+    enabled = false;
+    /** Optional per-session secrets registry; egress masking is applied on
+     *  every `recent` / `since` read. */
+    secrets = null;
+    constructor(
+    // CDP is the WS-tap substrate today; a later change will port it onto
+    // Playwright's `page.on('websocket')` so non-CDP engines are supported.
+    // On an engine without CDP (Firefox) the buffer
+    // is constructed but never attaches — reads return empty until the
+    // substrate port lands, rather than throwing at session creation.
+    cdp, cap = 500, maxPayload = 2000) {
+        this.cdp = cdp;
+        this.cap = cap;
+        this.maxPayload = maxPayload;
+    }
+    setSecrets(secrets) {
+        this.secrets = secrets;
+    }
+    trunc(s) {
+        if (s.length <= this.maxPayload)
+            return { payload: s };
+        return { payload: s.slice(0, this.maxPayload), truncated: true };
+    }
+    push(f) {
+        this.ring.push(f);
+        if (this.ring.length > this.cap)
+            this.ring.shift();
+    }
+    async attach() {
+        if (this.enabled || !this.cdp)
+            return;
+        await this.cdp.send("Network.enable").catch(() => undefined); // idempotent w/ NetworkBuffer
+        this.enabled = true;
+        this.cdp.on("Network.webSocketCreated", (e) => {
+            this.urls.set(e.requestId, e.url);
+        });
+        this.cdp.on("Network.requestWillBeSent", (e) => {
+            if (e.type === "EventSource")
+                this.urls.set(e.requestId, e.request.url);
+        });
+        const onFrame = (dir) => (e) => {
+            this.push({
+                url: this.urls.get(e.requestId) ?? "",
+                dir,
+                kind: "ws",
+                opcode: e.response.opcode,
+                ...this.trunc(e.response.payloadData ?? ""),
+                ts: Date.now(),
+            });
+        };
+        this.cdp.on("Network.webSocketFrameSent", onFrame("sent"));
+        this.cdp.on("Network.webSocketFrameReceived", onFrame("recv"));
+        this.cdp.on("Network.eventSourceMessageReceived", (e) => {
+            this.push({
+                url: this.urls.get(e.requestId) ?? "",
+                dir: "recv",
+                kind: "sse",
+                event: e.eventName || undefined,
+                ...this.trunc(e.data ?? ""),
+                ts: Date.now(),
+            });
+        });
+    }
+    /** Most-recent N frames, optionally filtered by a url substring. */
+    recent(limit = 50, urlPattern) {
+        let frames = this.ring;
+        // filter on the raw url, then sanitize the endpoint on the way out.
+        if (urlPattern)
+            frames = frames.filter((f) => f.url.includes(urlPattern));
+        return {
+            total: frames.length,
+            frames: frames.slice(-limit).map((f) => sanitizeFrame(f, this.secrets)),
+        };
+    }
+    /** Frames since a timestamp — for the per-action `ActionResult` slice. */
+    since(ts, cap = 25) {
+        return this.ring
+            .filter((f) => f.ts >= ts)
+            .slice(-cap)
+            .map((f) => sanitizeFrame(f, this.secrets));
+    }
+}

package/dist/page/network.d.ts

@@ -0,0 +1,194 @@
+import type { CDPSession } from "playwright-core";
+import type { SecretRegistry } from "../util/secrets.js";
+import type { WsFrame } from "./network-ws.js";
+export interface NetworkEntry {
+    method: string;
+    url: string;
+    status?: number;
+    type: string;
+    ms?: number;
+    failed?: boolean;
+    /** CDP request id — the handle `network_body` resolves. Short-lived:
+     *  the renderer discards bodies fairly quickly, so fetch soon after. */
+    requestId?: string;
+    /** Best-effort response `Content-Type` from CDP `Network.responseReceived`
+     *  (`response.mimeType`). Absent on failed requests, attached pre-response,
+     *  or non-HTTP transports. Captured for downstream filtering / asset export;
+     *  NOT emitted on the `network_read` egress (which only surfaces the type
+     *  bucket). */
+    mimeType?: string;
+    /** Best-effort encoded byte size from CDP `Network.loadingFinished`
+     *  (`encodedDataLength`). Absent on requests that haven't finished or where
+     *  the loadingFinished event hasn't landed yet. Captured for downstream
+     *  filtering / asset export. */
+    bytes?: number;
+}
+export interface NetworkSummary {
+    total: number;
+    byType: Record<string, number>;
+    failed: number;
+}
+/** The session-wide HTTP ring surface the tools above the engine seam consume
+ *  (network_read, asset_export, session_metrics). Both the CDP `NetworkBuffer`
+ *  and the Playwright `PlaywrightNetworkBuffer` satisfy it, so the NetworkSubstrate
+ *  exposes this engine-blind shape rather than a concrete class. */
+export interface SessionNetworkRing {
+    setSecrets(secrets: SecretRegistry): void;
+    iter(): readonly NetworkEntry[];
+    recent(limit?: number): {
+        summary: NetworkSummary;
+        requests: NetworkEntry[];
+    };
+}
+/** The session-wide WS/SSE ring surface the tools above the engine seam consume
+ *  (ws_read; the action window's `wsFrames` slice). Both `WsBuffer` and
+ *  `PlaywrightWsBuffer` satisfy it. */
+export interface SessionWsRing {
+    setSecrets(secrets: SecretRegistry): void;
+    recent(limit?: number, urlPattern?: string): {
+        total: number;
+        frames: WsFrame[];
+    };
+    since(ts: number, cap?: number): WsFrame[];
+}
+/** bounded summary of a write-shaped request whose response landed in the
+ *  action window. `responseShape` is the *top-level keys* of the parsed JSON
+ *  response — no values, no nested keys. `urlPattern` strips the query string
+ *  and replaces id-shaped path segments (numeric / UUID / hex) with `:id`. */
+export interface MutationEntry {
+    method: string;
+    urlPattern: string;
+    status: number;
+    ok: boolean;
+    /** Top-level object keys of the JSON response (or first-element keys for an
+     *  array response). Capped at 20 entries. Absent for non-JSON bodies. */
+    responseShape?: string[];
+    durationMs?: number;
+}
+export declare const MUTATION_METHODS: Set<string>;
+export declare const MAX_BODY_BYTES_TO_PARSE = 256000;
+/** Exported for unit tests of the cross-engine resourceType reconciliation. */
+export declare function cdpTypeFromPlaywright(resourceType: string): string;
+/** Fold a finished-entry list into the `{summary, requests}` the network_read /
+ *  action-tap egress emits: noise/beacon entries collapse into `summary.byType
+ *  .other` (and stay out of `requests`), failures count toward `summary.failed`,
+ *  and the surviving "interesting" entries have their URL masked at egress. This
+ *  is the EXACT logic the CDP `NetworkTap.close()` / `NetworkBuffer.recent()`
+ *  loops run inline; extracted so the Playwright-event buffers/tap produce a
+ *  byte-identical shape without duplicating the rule. */
+export declare function foldInteresting(entries: readonly NetworkEntry[], secrets: SecretRegistry | null): {
+    summary: NetworkSummary;
+    requests: NetworkEntry[];
+};
+export declare class NetworkTap {
+    private cdp;
+    private secrets;
+    private requests;
+    private finished;
+    private mutationPromises;
+    private listeners;
+    private enabled;
+    /** Optional per-session secrets registry. When non-null, every URL +
+     *  response-shape key that leaves through `close()` is run through the
+     *  egress masking layer in addition to the URL sanitiser. */
+    constructor(cdp: CDPSession, secrets?: SecretRegistry | null);
+    open(): Promise<void>;
+    /**
+     * Stop listening and produce a `{ summary, requests, mutations }` snapshot of
+     * the window. `requests` only includes the "interesting" entries (non-noise,
+     * non-beacon). Noise still counts toward `summary.byType.other`. `mutations`
+     * is awaited from the response-body probes kicked off during the window.
+     */
+    close(): Promise<{
+        summary: NetworkSummary;
+        requests: NetworkEntry[];
+        mutations: MutationEntry[];
+    }>;
+}
+export type { WsFrame } from "./network-ws.js";
+export { sanitizeFrame, WsBuffer } from "./network-ws.js";
+/**
+ * fetch a response body by CDP request id. Gated behind the off-by-
+ * default `network-body` capability — full bodies can carry PII / tokens.
+ * Bounded (`maxBytes`, default 256 KB). Best-effort: the renderer discards
+ * bodies fairly quickly, so this can legitimately fail with "not available".
+ */
+export declare function fetchResponseBody(cdp: CDPSession, requestId: string, maxBytes?: number, secrets?: SecretRegistry | null): Promise<{
+    ok: boolean;
+    body?: string;
+    base64Encoded?: boolean;
+    truncated?: boolean;
+    error?: string;
+}>;
+/**
+ * Best-effort mutation-detail probe. Fetches the response body via
+ * `Network.getResponseBody`, extracts only the *top-level keys* of the parsed
+ * JSON. Returns null on any failure (body discarded, non-JSON, parse error,
+ * over-size body) so the caller can simply filter nulls out.
+ *
+ * Exported for unit tests of the urlPattern / responseShape helpers via
+ * `patterniseUrl` / `extractTopLevelKeys`.
+ */
+/** The request/response detail describing one mutation, threaded as a single
+ *  group so the probe signatures stay within the param budget (the CDP and
+ *  Playwright probes both carry the same four fields alongside their transport
+ *  handle). */
+export interface MutationDetail {
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+}
+export declare function mutationWithoutShape(detail: MutationDetail): MutationEntry;
+/** Build a mutation entry, attaching the response shape only when non-empty —
+ *  the success path shared by the CDP and Playwright probes. */
+export declare function mutationWithShape(detail: MutationDetail, responseShape: string[] | null): MutationEntry;
+/**
+ * Strip the query string and replace id-shaped path segments with `:id`. Keeps
+ * the route stable across requests for the same logical endpoint without
+ * leaking the specific record id in the result.
+ *
+ * Exported for unit tests.
+ */
+export declare function patterniseUrl(url: string): string;
+/**
+ * Extract the top-level keys of a parsed JSON body. For an object, returns
+ * `Object.keys()`. For an array of objects, returns the first element's keys
+ * (prefixed with `[].` to signal array shape). Returns null otherwise.
+ *
+ * Capped at MAX_RESPONSE_SHAPE_KEYS entries. Exported for unit tests.
+ */
+export declare function extractTopLevelKeys(parsed: unknown): string[] | null;
+/**
+ * Session-wide ring buffer of network requests. Same shape as NetworkTap but
+ * always-on for the lifetime of the session — exposed via the `network_read`
+ * MCP tool. Per-action attribution still lives in `ActionResult.network`;
+ * this is the "what happened recently across the session" surface.
+ */
+export declare class NetworkBuffer {
+    private cdp;
+    private cap;
+    private requests;
+    private ring;
+    /** requestId → entry pointer for the entries currently in `ring`. Lets
+     *  `Network.loadingFinished` stamp `bytes` onto the corresponding entry
+     *  without a linear scan. Pruned in `push` when an entry is evicted. */
+    private byReqId;
+    private enabled;
+    private secrets;
+    constructor(cdp: CDPSession | undefined, cap?: number);
+    setSecrets(secrets: SecretRegistry): void;
+    attach(): Promise<void>;
+    private push;
+    /** Raw, read-only snapshot of the ring — every entry, no noise/beacon
+     *  folding, no egress masking. The masked / bucketed shape used by the
+     *  `network_read` tool stays unchanged (see `recent`). This view is for
+     *  consumers that need the full set as captured (e.g. `asset_export`
+     *  iterating to pick image/font/media responses out of the ring). */
+    iter(): readonly NetworkEntry[];
+    /** Most-recent N entries; noise + beacons are folded into the `other` bucket of the summary. */
+    recent(limit?: number): {
+        summary: NetworkSummary;
+        requests: NetworkEntry[];
+    };
+}