rea-agents 4.1.0 → 5.0.0

package/dist/browser/CdpCaptureEventHandlers.js

@@ -1,12 +1,12 @@
 import { inferJsonShape } from "../domain/jsonShape.js";
 import { safeResponseMetadata } from "./CdpSafeMetadata.js";
-import { allowedSanitizedUrl, isHttpUrl, numberValue, recordValue, recordsValue, stringValue, } from "./CdpCaptureValues.js";
+import { allowedSanitizedUrl, isHttpUrl, numberValue, recordValue, recordsValue, cdpStringValue, } from "./CdpCaptureValues.js";
 import { requestBodyShape } from "./CdpCaptureEventBodyShapes.js";
 import { consolePrimitive, decodeBase64, exclusionReasonForUrl, executionContextKey, firstCallFrame, initiatorLocation, integerOrNull, isMainFrameNavigation, } from "./CdpCaptureEventHelpers.js";
 export const handleExecutionContextCreated = (state, params) => {
     const context = recordValue(params.context);
     const identifier = numberValue(context?.id);
-    const frameId = stringValue(recordValue(context?.auxData)?.frameId);
+    const frameId = cdpStringValue(recordValue(context?.auxData)?.frameId);
     if (identifier === undefined ||
         !Number.isSafeInteger(identifier) ||
         frameId === undefined)
@@ -20,8 +20,8 @@ export const handleExecutionContextDestroyed = (state, params) => {
         state.executionContextFrames.delete(key);
 };
 export const handleScriptParsed = (state, params) => {
-    const scriptId = stringValue(params.scriptId);
-    const rawUrl = stringValue(params.url) ?? "";
+    const scriptId = cdpStringValue(params.scriptId);
+    const rawUrl = cdpStringValue(params.url) ?? "";
     const sanitized = allowedSanitizedUrl(rawUrl, state.allowedOrigins);
     if (scriptId === undefined) {
         state.completeness.exclude("scripts", "invalid_protocol_value");
@@ -37,10 +37,10 @@ export const handleScriptParsed = (state, params) => {
         rawUrl,
         url: sanitized.url,
         origin: sanitized.origin,
-        hash: stringValue(params.hash) ?? "",
+        hash: cdpStringValue(params.hash) ?? "",
         length: Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, Math.trunc(numberValue(params.length) ?? 0))),
         isModule: params.isModule === true,
-        language: stringValue(params.scriptLanguage) ?? null,
+        language: cdpStringValue(params.scriptLanguage) ?? null,
         sourceMapUrl: sourceMap.sanitized,
         sourceMapRawUrl: sourceMap.raw,
         executionContextKey: executionContextKey(params.executionContextId),
@@ -48,7 +48,7 @@ export const handleScriptParsed = (state, params) => {
     state.scripts.set(scriptId, script);
 };
 const sourceMapForScript = (value, scriptUrl, state) => {
-    const declaredUrl = stringValue(value);
+    const declaredUrl = cdpStringValue(value);
     if (declaredUrl === undefined || declaredUrl === "")
         return { sanitized: null, raw: null };
     let rawUrl;
@@ -68,7 +68,7 @@ const sourceMapForScript = (value, scriptUrl, state) => {
     return { sanitized: null, raw: null };
 };
 export const handleRequestWillBeSent = (state, params) => {
-    const requestId = stringValue(params.requestId);
+    const requestId = cdpStringValue(params.requestId);
     const request = recordValue(params.request);
     if (requestId === undefined) {
         state.completeness.exclude("network_requests", "invalid_protocol_value");
@@ -81,13 +81,13 @@ export const handleRequestWillBeSent = (state, params) => {
     }
     const sanitized = allowedSanitizedUrl(request.url, state.allowedOrigins);
     if (sanitized === undefined) {
-        state.completeness.exclude("network_requests", exclusionReasonForUrl(stringValue(request.url)));
+        state.completeness.exclude("network_requests", exclusionReasonForUrl(cdpStringValue(request.url)));
         state.network.delete(requestId);
         return;
     }
     const initiator = recordValue(params.initiator);
     const initiatorFrame = initiatorLocation(initiator);
-    const rawInitiatorUrl = stringValue(initiatorFrame?.url);
+    const rawInitiatorUrl = cdpStringValue(initiatorFrame?.url);
     const initiatorUrl = allowedSanitizedUrl(rawInitiatorUrl, state.allowedOrigins);
     if (rawInitiatorUrl !== undefined && initiatorUrl === undefined)
         state.completeness.exclude("network_initiators", exclusionReasonForUrl(rawInitiatorUrl));
@@ -95,13 +95,13 @@ export const handleRequestWillBeSent = (state, params) => {
         request_id: requestId,
         url: sanitized.url,
         origin: sanitized.origin ?? "",
-        method: stringValue(request.method) ?? "GET",
-        resource_type: stringValue(params.type) ?? null,
+        method: cdpStringValue(request.method) ?? "GET",
+        resource_type: cdpStringValue(params.type) ?? null,
         status: null,
         mime_type: null,
         encoded_data_length: null,
         initiator: {
-            type: stringValue(initiator?.type) ?? "other",
+            type: cdpStringValue(initiator?.type) ?? "other",
             url: initiatorUrl?.url ?? null,
             line: integerOrNull(initiatorFrame?.lineNumber),
             column: integerOrNull(initiatorFrame?.columnNumber),
@@ -110,7 +110,7 @@ export const handleRequestWillBeSent = (state, params) => {
     });
 };
 export const handleResponseReceived = (state, params) => {
-    const requestId = stringValue(params.requestId);
+    const requestId = cdpStringValue(params.requestId);
     if (requestId === undefined) {
         state.completeness.exclude("network_requests", "invalid_protocol_value");
         return;
@@ -123,21 +123,21 @@ export const handleResponseReceived = (state, params) => {
     if (response === undefined || sanitized === undefined) {
         state.completeness.exclude("network_requests", response === undefined
             ? "invalid_protocol_value"
-            : exclusionReasonForUrl(stringValue(response.url)));
+            : exclusionReasonForUrl(cdpStringValue(response.url)));
         state.network.delete(requestId);
         return;
     }
     state.network.set(requestId, {
         ...current,
         status: numberValue(response.status) ?? null,
-        mime_type: stringValue(response.mimeType) ?? null,
+        mime_type: cdpStringValue(response.mimeType) ?? null,
     });
     const metadata = safeResponseMetadata(requestId, sanitized.url, response, state.allowedOrigins);
     state.responseMetadata.push(metadata.response);
     state.agentHints.push(...metadata.agentHints);
 };
 export const handleLoadingFinished = (state, params) => {
-    const requestId = stringValue(params.requestId);
+    const requestId = cdpStringValue(params.requestId);
     if (requestId === undefined)
         return;
     const current = state.network.get(requestId);
@@ -156,14 +156,14 @@ export const handleConsoleAPICalled = (state, params) => {
     }
     const source = allowedSanitizedUrl(frame.url, state.allowedOrigins);
     if (source === undefined) {
-        state.completeness.exclude("console_events", exclusionReasonForUrl(stringValue(frame.url)));
+        state.completeness.exclude("console_events", exclusionReasonForUrl(cdpStringValue(frame.url)));
         return;
     }
     const arguments_ = recordsValue(params.args);
     state.console.push({
-        type: stringValue(params.type) ?? "unknown",
+        type: cdpStringValue(params.type) ?? "unknown",
         timestamp: numberValue(params.timestamp) ?? 0,
-        argument_types: arguments_.map((argument) => stringValue(argument.type) ?? "unknown"),
+        argument_types: arguments_.map((argument) => cdpStringValue(argument.type) ?? "unknown"),
         url: source.url,
         line: integerOrNull(frame.lineNumber),
         column: integerOrNull(frame.columnNumber),
@@ -198,12 +198,12 @@ const captureConsoleText = (state, arguments_) => {
     };
 };
 export const handleWebSocketFrame = (state, params, direction) => {
-    const requestId = stringValue(params.requestId);
+    const requestId = cdpStringValue(params.requestId);
     if (requestId === undefined ||
         (!state.network.has(requestId) && !state.allowedWebSockets.has(requestId)))
         return;
     const response = recordValue(params.response);
-    const payload = stringValue(response?.payloadData) ?? "";
+    const payload = cdpStringValue(response?.payloadData) ?? "";
     const opcode = Math.max(0, Math.trunc(numberValue(response?.opcode) ?? 0));
     const decoded = opcode === 1 ? undefined : decodeBase64(payload);
     if (opcode !== 1 && decoded === undefined)
@@ -228,8 +228,8 @@ const captureWebSocketShape = (state, payload, opcode) => {
     };
 };
 export const handleWebSocketCreated = (state, params) => {
-    const requestId = stringValue(params.requestId);
-    const rawUrl = stringValue(params.url);
+    const requestId = cdpStringValue(params.requestId);
+    const rawUrl = cdpStringValue(params.url);
     if (requestId === undefined) {
         state.completeness.exclude("websocket_connections", "invalid_protocol_value");
         return;
@@ -268,8 +268,8 @@ export const handleFrameNavigated = (state, params) => {
         return;
     if (!isMainFrameNavigation({ method: "Page.frameNavigated", params }, state.mainFrameId))
         return;
-    const rawUrl = stringValue(frame?.url);
-    const loaderId = stringValue(frame?.loaderId);
+    const rawUrl = cdpStringValue(frame?.url);
+    const loaderId = cdpStringValue(frame?.loaderId);
     // `frameNavigated` re-fires for a document already reported (same URL and
     // loader). Treating that as a navigation aborted a valid capture with
     // `target_changed`, which is a false claim that the target moved.

package/dist/browser/CdpCaptureEventHelpers.js

@@ -1,14 +1,14 @@
-import { isHttpUrl, numberValue, recordValue, recordsValue, stringValue, } from "./CdpCaptureValues.js";
+import { isHttpUrl, numberValue, recordValue, recordsValue, cdpStringValue, } from "./CdpCaptureValues.js";
 /** Identify a top-level navigation event from its untrusted CDP envelope. */
 export const isMainFrameNavigation = (event, mainFrameId) => {
     const params = recordValue(event.params);
     if (params === undefined)
         return false;
     const frameId = event.method === "Page.frameNavigated"
-        ? stringValue(recordValue(params.frame)?.id)
+        ? cdpStringValue(recordValue(params.frame)?.id)
         : event.method === "Page.frameRequestedNavigation" ||
             event.method === "Page.navigatedWithinDocument"
-            ? stringValue(params.frameId)
+            ? cdpStringValue(params.frameId)
             : undefined;
     return frameId === mainFrameId;
 };
@@ -21,7 +21,7 @@ export const initiatorLocation = (initiator) => {
             return frame;
         stack = recordValue(stack.parent);
     }
-    return stringValue(initiator?.url) === undefined ? undefined : initiator;
+    return cdpStringValue(initiator?.url) === undefined ? undefined : initiator;
 };
 export const exclusionReasonForUrl = (value) => value === undefined || value === ""
     ? "unattributed_origin"
@@ -43,7 +43,7 @@ export const isJsonContentType = (headers) => {
         return false;
     for (const [name, value] of Object.entries(headers))
         if (name.toLowerCase() === "content-type" &&
-            isJsonMediaType(stringValue(value)))
+            isJsonMediaType(cdpStringValue(value)))
             return true;
     return false;
 };
@@ -52,7 +52,7 @@ export const isJsonMediaType = (value) => {
     return (mediaType === "application/json" || mediaType?.endsWith("+json") === true);
 };
 export const consolePrimitive = (value) => {
-    const type = stringValue(value.type);
+    const type = cdpStringValue(value.type);
     switch (type) {
         case "string":
             return typeof value.value === "string"

package/dist/browser/CdpCaptureStorage.js

@@ -1,9 +1,10 @@
 import { CdpConnection } from "./CdpConnection.js";
 import { optionalCdpCommand } from "./CdpOptionalCommand.js";
 import { captureStorageFingerprints, } from "./CdpCaptureStorageFingerprints.js";
-import { numberValue, recordValue, recordsValue, stringValue, } from "./CdpCaptureValues.js";
-/** Capture redacted storage metadata for one authorized origin. */
-export const captureStorage = async (context, origin, limitations) => {
+import { numberValue, recordValue, recordsValue, cdpStringValue, } from "./CdpCaptureValues.js";
+/** Capture redacted storage metadata for an authorized page and its origin. */
+export const captureStorage = async (context, pageUrl, limitations) => {
+    const origin = new URL(pageUrl).origin;
     const quota = recordValue(await optionalCdpCommand(context, "Storage.getUsageAndQuota", { origin }, limitations));
     const local = context.input.include_storage_keys
         ? await storageItems(context, origin, true, limitations)
@@ -25,6 +26,7 @@ export const captureStorage = async (context, origin, limitations) => {
         ? await captureStorageFingerprints({
             context,
             origin,
+            cookieUrl: pageUrl,
             local,
             session,
             indexedDbNames: indexed,
@@ -58,8 +60,8 @@ const emptyStorageItems = {
     complete: false,
 };
 const capturedCaches = (values) => values.flatMap((cache) => {
-    const name = stringValue(cache.cacheName);
-    const id = stringValue(cache.cacheId);
+    const name = cdpStringValue(cache.cacheName);
+    const id = cdpStringValue(cache.cacheId);
     return name === undefined || id === undefined ? [] : [{ name, id }];
 });
 const storageItems = async (context, origin, isLocalStorage, limitations) => {
@@ -70,15 +72,15 @@ const storageItems = async (context, origin, isLocalStorage, limitations) => {
     const items = entries.flatMap((entry) => {
         if (!Array.isArray(entry))
             return [];
-        const key = stringValue(entry[0]);
-        const value = stringValue(entry[1]);
+        const key = cdpStringValue(entry[0]);
+        const value = cdpStringValue(entry[1]);
         return key === undefined || value === undefined ? [] : [{ key, value }];
     });
     return { items, complete: items.length === entries.length };
 };
 const stringArray = (value) => Array.isArray(value)
     ? value.flatMap((item) => {
-        const text = stringValue(item);
+        const text = cdpStringValue(item);
         return text === undefined ? [] : [text];
     })
     : [];

package/dist/browser/CdpCaptureStorageFingerprints.js

@@ -3,9 +3,9 @@ import canonicalize from "canonicalize";
 import { compareCodePoints } from "../domain/canonicalOrdering.js";
 import { CdpConnection } from "./CdpConnection.js";
 import { optionalCdpCommand } from "./CdpOptionalCommand.js";
-import { recordValue, recordsValue, stringValue } from "./CdpCaptureValues.js";
+import { recordValue, recordsValue, cdpStringValue, } from "./CdpCaptureValues.js";
 /** Capture stable hashes of approved storage content without returning values. */
-export const captureStorageFingerprints = async ({ context, origin, local, session, indexedDbNames, caches, limitations, }) => {
+export const captureStorageFingerprints = async ({ context, origin, cookieUrl, local, session, indexedDbNames, caches, limitations, }) => {
     const state = {
         items: [],
         complete: local.complete && session.complete,
@@ -13,7 +13,7 @@ export const captureStorageFingerprints = async ({ context, origin, local, sessi
     const run = { context, limitations, state };
     addStorageItems(state, "local_storage", local.items);
     addStorageItems(state, "session_storage", session.items);
-    await addCookies(run, origin);
+    await addCookies(run, cookieUrl);
     await addIndexedDb(run, origin, indexedDbNames);
     await addCaches(run, caches);
     state.items.sort((left, right) => compareCodePoints(`${left.scope}:${left.identity_sha256}`, `${right.scope}:${right.identity_sha256}`));
@@ -29,8 +29,9 @@ const addStorageItems = (state, scope, items) => {
             complete: true,
         });
 };
-const addCookies = async (run, origin) => {
-    const raw = await optionalCdpCommand(run.context, "Network.getCookies", { urls: [origin] }, run.limitations);
+const addCookies = async (run, pageUrl) => {
+    run.limitations.push("Cookie fingerprints cover cookies applicable to the current main-frame URL, not every path on its origin.");
+    const raw = await optionalCdpCommand(run.context, "Network.getCookies", { urls: [pageUrl] }, run.limitations);
     if (raw === undefined) {
         run.state.complete = false;
         return;
@@ -44,10 +45,10 @@ const addCookies = async (run, origin) => {
     if (cookies.length !== cookieValues.length)
         run.state.complete = false;
     for (const cookie of cookies) {
-        const name = stringValue(cookie.name);
-        const value = stringValue(cookie.value);
-        const domain = stringValue(cookie.domain);
-        const path = stringValue(cookie.path);
+        const name = cdpStringValue(cookie.name);
+        const value = cdpStringValue(cookie.value);
+        const domain = cdpStringValue(cookie.domain);
+        const path = cdpStringValue(cookie.path);
         if (name === undefined ||
             value === undefined ||
             domain === undefined ||
@@ -76,7 +77,7 @@ const addIndexedDb = async (run, origin, names) => {
             run.state.complete = false;
             continue;
         }
-        if (stringValue(database.name) !== databaseName) {
+        if (cdpStringValue(database.name) !== databaseName) {
             run.state.complete = false;
             continue;
         }
@@ -94,7 +95,7 @@ const addIndexedDb = async (run, origin, names) => {
             complete: indexedDbSchemaComplete(stores),
         });
         for (const store of stores) {
-            const objectStoreName = stringValue(store.name);
+            const objectStoreName = cdpStringValue(store.name);
             if (objectStoreName === undefined) {
                 run.state.complete = false;
                 continue;
@@ -108,22 +109,22 @@ const addIndexedDb = async (run, origin, names) => {
     }
 };
 const indexedDbStoreSchema = (store) => ({
-    name: stringValue(store.name) ?? null,
+    name: cdpStringValue(store.name) ?? null,
     key_path: stableValue(store.keyPath),
     auto_increment: store.autoIncrement === true,
     indexes: recordsValue(store.indexes).map((index) => ({
-        name: stringValue(index.name) ?? null,
+        name: cdpStringValue(index.name) ?? null,
         key_path: stableValue(index.keyPath),
         unique: index.unique === true,
         multi_entry: index.multiEntry === true,
     })),
 });
-const indexedDbSchemaComplete = (stores) => stores.every((store) => stringValue(store.name) !== undefined &&
+const indexedDbSchemaComplete = (stores) => stores.every((store) => cdpStringValue(store.name) !== undefined &&
     stableValueComplete(store.keyPath) &&
     typeof store.autoIncrement === "boolean" &&
     Array.isArray(store.indexes) &&
     recordsValue(store.indexes).length === store.indexes.length &&
-    recordsValue(store.indexes).every((index) => stringValue(index.name) !== undefined &&
+    recordsValue(store.indexes).every((index) => cdpStringValue(index.name) !== undefined &&
         stableValueComplete(index.keyPath) &&
         typeof index.unique === "boolean" &&
         typeof index.multiEntry === "boolean"));
@@ -134,7 +135,6 @@ const addIndexedDbRecords = async (run, input) => {
             securityOrigin: input.origin,
             databaseName: input.databaseName,
             objectStoreName: input.objectStoreName,
-            indexName: "",
             skipCount,
             pageSize: STORAGE_ENTRY_PAGE_SIZE,
         }, run.limitations);
@@ -164,7 +164,9 @@ const addIndexedDbRecords = async (run, input) => {
                     primaryKey,
                 },
                 value,
-                complete: remoteObjectComplete(entry.value),
+                complete: remoteObjectComplete(entry.key) &&
+                    remoteObjectComplete(entry.primaryKey) &&
+                    remoteObjectComplete(entry.value),
             });
         }
         if (result.hasMore !== true)
@@ -213,8 +215,8 @@ const addCaches = async (run, caches) => {
     }
 };
 const addCacheEntry = async (run, cache, entry) => {
-    const requestURL = stringValue(entry.requestURL);
-    const requestMethod = stringValue(entry.requestMethod);
+    const requestURL = cdpStringValue(entry.requestURL);
+    const requestMethod = cdpStringValue(entry.requestMethod);
     if (requestURL === undefined || requestMethod === undefined) {
         run.state.complete = false;
         return;
@@ -225,8 +227,8 @@ const addCacheEntry = async (run, cache, entry) => {
     }
     const headerRecords = recordsValue(entry.requestHeaders);
     const requestHeaders = headerRecords.flatMap((header) => {
-        const name = stringValue(header.name);
-        const value = stringValue(header.value);
+        const name = cdpStringValue(header.name);
+        const value = cdpStringValue(header.value);
         return name === undefined || value === undefined ? [] : [{ name, value }];
     });
     if (headerRecords.length !== entry.requestHeaders.length ||
@@ -235,7 +237,7 @@ const addCacheEntry = async (run, cache, entry) => {
         return;
     }
     const raw = await optionalCdpCommand(run.context, "CacheStorage.requestCachedResponse", { cacheId: cache.id, requestURL, requestHeaders }, run.limitations);
-    const body = stringValue(recordValue(recordValue(raw)?.response)?.body);
+    const body = cdpStringValue(recordValue(recordValue(raw)?.response)?.body);
     const decoded = body === undefined ? null : decodeBase64(body);
     const complete = decoded !== null;
     if (!complete)

package/dist/browser/CdpCaptureValues.js

@@ -11,7 +11,7 @@ export const recordsValue = (value) => Array.isArray(value)
         return record === undefined ? [] : [record];
     })
     : [];
-export const stringValue = (value) => typeof value === "string" ? value : undefined;
+export const cdpStringValue = (value) => typeof value === "string" ? value : undefined;
 export const numberValue = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
 export const requiredRecord = (value) => {
     const record = recordValue(value);
@@ -33,7 +33,7 @@ export const isHttpUrl = (value) => {
     }
 };
 export const allowedSanitizedUrl = (value, allowedOrigins) => {
-    const text = stringValue(value);
+    const text = cdpStringValue(value);
     if (text === undefined)
         return undefined;
     const sanitized = sanitizeBrowserUrl(text);

package/dist/browser/CdpCommandRejection.js

@@ -0,0 +1,17 @@
+import { BrowserObservationError } from "../domain/browserObservationError.js";
+/** Preserve a producer's command rejection independently from fatal transport parsing errors. */
+export class CdpCommandRejection extends BrowserObservationError {
+    command;
+    code;
+    reportedMessage;
+    constructor(operation, command, code, reportedMessage) {
+        super(operation, "protocol_error", {
+            detail: reportedMessage === null
+                ? "CDP returned a malformed command error."
+                : `CDP ${command} failed (${code === null ? "unknown code" : String(code)}): ${reportedMessage}`,
+        });
+        this.command = command;
+        this.code = code;
+        this.reportedMessage = reportedMessage;
+    }
+}

package/dist/browser/CdpConnection.js

@@ -2,36 +2,43 @@ import WebSocket, {} from "ws";
 import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
+import { CdpCommandRejection } from "./CdpCommandRejection.js";
 import {} from "../domain/browserObservationErrors.js";
 import { safeParseJson } from "../domain/safeJson.js";
 /** Correlated JSON-RPC transport for one CDP target operation. */
 export class CdpConnection {
     socket;
     operation;
+    maxPayloadBytes;
     #pending = new Map();
     #listeners = new Set();
     #disconnectListeners = new Set();
+    #protocolFailureListeners = new Set();
     #nextId = 1;
     #closed = false;
     #protocolFailed = false;
-    constructor(socket, operation) {
+    #transportFailure = "disconnected";
+    constructor(socket, operation, maxPayloadBytes) {
         this.socket = socket;
         this.operation = operation;
+        this.maxPayloadBytes = maxPayloadBytes;
         socket.on("message", (data) => this.#receive(data));
         socket.on("close", () => this.#disconnect());
-        socket.on("error", () => this.#disconnect());
+        socket.on("error", (cause) => this.#disconnect(isRecord(cause) && cause.code === "WS_ERR_UNSUPPORTED_MESSAGE_LENGTH"
+            ? "payload_limit"
+            : "disconnected"));
     }
     /** Connect to one already-validated loopback CDP WebSocket. */
-    static async connect(url, operation, signal) {
+    static async connect(url, operation, signal, limits) {
         if (signal?.aborted === true)
             throw new AnalysisCancelledError(operation);
         const socket = new WebSocket(url, {
             handshakeTimeout: 0,
-            maxPayload: 0,
+            maxPayload: limits?.maxPayloadBytes ?? 0,
             perMessageDeflate: false,
         });
         await waitForOpen(socket, operation, signal);
-        return new CdpConnection(socket, operation);
+        return new CdpConnection(socket, operation, limits?.maxPayloadBytes ?? 0);
     }
     /** Subscribe to validated CDP event envelopes. */
     onEvent(listener) {
@@ -47,12 +54,21 @@ export class CdpConnection {
         this.#disconnectListeners.add(listener);
         return () => this.#disconnectListeners.delete(listener);
     }
+    /** Notify fatal wire parsing failure even when no command is outstanding. */
+    onProtocolFailure(listener) {
+        if (this.#protocolFailed) {
+            listener(this.#transportError("protocol_error"));
+            return () => undefined;
+        }
+        this.#protocolFailureListeners.add(listener);
+        return () => this.#protocolFailureListeners.delete(listener);
+    }
     /** Execute one command, optionally within a flat target session. */
     async send(method, params = {}, sessionId, signal) {
         if (this.#protocolFailed)
             throw new BrowserObservationError(this.operation, "protocol_error");
         if (this.#closed || this.socket.readyState !== WebSocket.OPEN)
-            throw new BrowserObservationError(this.operation, "disconnected");
+            throw this.#transportError(this.#transportFailure);
         if (signal?.aborted === true)
             throw new AnalysisCancelledError(this.operation);
         const id = this.#nextId;
@@ -68,6 +84,7 @@ export class CdpConnection {
             };
             signal?.addEventListener("abort", onAbort, { once: true });
             this.#pending.set(id, {
+                method,
                 resolve,
                 reject,
                 removeAbort: () => signal?.removeEventListener("abort", onAbort),
@@ -111,6 +128,8 @@ export class CdpConnection {
         });
     }
     #receive(data) {
+        if (this.#closed || this.#protocolFailed)
+            return;
         const parsed = safeParseJson(rawText(data));
         if (!parsed.ok) {
             this.#failPending("protocol_error");
@@ -154,7 +173,12 @@ export class CdpConnection {
             return;
         this.#complete(id, pending);
         if ("error" in message) {
-            pending.reject(new BrowserObservationError(this.operation, "protocol_error"));
+            const reported = message.error;
+            pending.reject(new CdpCommandRejection(this.operation, pending.method, isRecord(reported) && typeof reported.code === "number"
+                ? reported.code
+                : null, isRecord(reported) && typeof reported.message === "string"
+                ? reported.message
+                : null));
             return;
         }
         pending.resolve("result" in message ? message.result : {});
@@ -164,24 +188,40 @@ export class CdpConnection {
         this.#pending.delete(id);
     }
     #failPending(reason) {
-        if (reason === "disconnected")
+        const wasProtocolFailed = this.#protocolFailed;
+        if (reason !== "protocol_error")
             this.#closed = true;
         else
             this.#protocolFailed = true;
         for (const [id, pending] of this.#pending) {
             this.#complete(id, pending);
-            pending.reject(new BrowserObservationError(this.operation, reason));
+            pending.reject(this.#transportError(reason));
+        }
+        if (reason === "protocol_error" && !wasProtocolFailed) {
+            const error = this.#transportError(reason);
+            for (const listener of this.#protocolFailureListeners)
+                listener(error);
+            this.#protocolFailureListeners.clear();
         }
     }
-    #disconnect() {
+    #disconnect(reason = "disconnected") {
         const wasClosed = this.#closed;
-        this.#failPending("disconnected");
+        if (!wasClosed)
+            this.#transportFailure = reason;
+        this.#failPending(reason);
         if (wasClosed)
             return;
         for (const listener of this.#disconnectListeners)
             listener();
         this.#disconnectListeners.clear();
     }
+    #transportError(reason) {
+        return new BrowserObservationError(this.operation, reason, reason === "payload_limit"
+            ? {
+                detail: `CDP message exceeded the selected ${String(this.maxPayloadBytes)} byte protocol budget.`,
+            }
+            : undefined);
+    }
 }
 const rawText = (data) => Array.isArray(data)
     ? Buffer.concat(data).toString("utf8")