rea-agents 4.0.1 → 5.0.0

package/dist/browser/CdpCaptureValues.js

@@ -1,4 +1,6 @@
-import { AnalysisCancelledError, BrowserObservationError, } from "../domain/errors.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
+import {} from "../domain/browserObservationErrors.js";
 import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
 import { createWebTextArtifact } from "../domain/webContentArtifact.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -9,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);
@@ -24,12 +26,14 @@ export const isHttpUrl = (value) => {
         const protocol = new URL(value).protocol;
         return protocol === "http:" || protocol === "https:";
     }
-    catch {
+    catch (cause) {
+        // Non-URL input is not an HTTP URL.
+        void cause;
         return false;
     }
 };
 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

@@ -1,33 +1,44 @@
 import WebSocket, {} from "ws";
-import { AnalysisCancelledError, AnalysisError, BrowserObservationError, } from "../domain/errors.js";
+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) {
@@ -43,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;
@@ -64,6 +84,7 @@ export class CdpConnection {
             };
             signal?.addEventListener("abort", onAbort, { once: true });
             this.#pending.set(id, {
+                method,
                 resolve,
                 reject,
                 removeAbort: () => signal?.removeEventListener("abort", onAbort),
@@ -107,14 +128,14 @@ export class CdpConnection {
         });
     }
     #receive(data) {
-        let message;
-        try {
-            message = JSON.parse(rawText(data));
-        }
-        catch {
+        if (this.#closed || this.#protocolFailed)
+            return;
+        const parsed = safeParseJson(rawText(data));
+        if (!parsed.ok) {
             this.#failPending("protocol_error");
             return;
         }
+        const message = parsed.value;
         if (!isRecord(message)) {
             this.#failPending("protocol_error");
             return;
@@ -152,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 : {});
@@ -162,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")

package/dist/browser/CdpElectronInspection.js

@@ -1,7 +1,7 @@
-import { BrowserObservationError } from "../domain/errors.js";
+import { canonicalDigest } from "../domain/comparisonSemantics.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
-import { canonicalJsonDigest } from "./CdpCanonicalJsonDigest.js";
-import { delayWithCancellation, numberValue, recordValue, recordsValue, requiredRecord, stringValue, } from "./CdpCaptureValues.js";
+import { delayWithCancellation, numberValue, recordValue, recordsValue, requiredRecord, cdpStringValue, } from "./CdpCaptureValues.js";
 import { walkFrameTrees } from "./CdpCaptureDocuments.js";
 import { ingestElectronScriptEvent, } from "./CdpElectronScriptEvents.js";
 import { captureElectronScripts } from "./CdpElectronScripts.js";
@@ -124,9 +124,9 @@ const navigatedFrameId = (event) => {
     if (params === undefined)
         return undefined;
     if (event.method === "Page.frameNavigated")
-        return stringValue(recordValue(params.frame)?.id);
+        return cdpStringValue(recordValue(params.frame)?.id);
     if (event.method === "Page.navigatedWithinDocument")
-        return stringValue(params.frameId);
+        return cdpStringValue(params.frameId);
     return undefined;
 };
 const captureFrames = async (result, completeness) => {
@@ -136,15 +136,15 @@ const captureFrames = async (result, completeness) => {
     const frames = [];
     for (const tree of walkFrameTrees(frameTree, () => completeness.exclude("frames", "invalid_protocol_value"))) {
         const frame = recordValue(tree.frame);
-        const frameId = stringValue(frame?.id);
-        const path = await authorizedElectronFile(stringValue(frame?.url) ?? "");
+        const frameId = cdpStringValue(frame?.id);
+        const path = await authorizedElectronFile(cdpStringValue(frame?.url) ?? "");
         if (frameId === undefined || path === undefined) {
             completeness.exclude("frames", "out_of_target_scope");
             continue;
         }
         frames.push({
             frame_id: frameId,
-            parent_frame_id: stringValue(frame?.parentId) ?? null,
+            parent_frame_id: cdpStringValue(frame?.parentId) ?? null,
             file_path: path,
         });
     }
@@ -163,20 +163,20 @@ const captureResources = async (context, completeness) => {
         if (tree === undefined)
             break;
         for (const resource of recordsValue(tree.resources)) {
-            const path = await authorizedElectronFile(stringValue(resource.url) ?? "");
+            const path = await authorizedElectronFile(cdpStringValue(resource.url) ?? "");
             if (path === undefined) {
                 completeness.exclude("resources", "out_of_target_scope");
                 continue;
             }
             const item = {
                 file_path: path,
-                type: stringValue(resource.type) ?? "Other",
-                mime_type: stringValue(resource.mimeType) ?? "",
+                type: cdpStringValue(resource.type) ?? "Other",
+                mime_type: cdpStringValue(resource.mimeType) ?? "",
                 content_size: numberValue(resource.contentSize) === undefined
                     ? null
                     : Math.max(0, numberValue(resource.contentSize) ?? 0),
             };
-            const resourceKey = `electron_resource_${canonicalJsonDigest(item)}`;
+            const resourceKey = `electron_resource_${canonicalDigest(item, "CDP capture")}`;
             if (seen.has(resourceKey))
                 continue;
             seen.add(resourceKey);
@@ -230,7 +230,7 @@ const captureDom = async (context, completeness) => {
 const mainFilePath = async (result) => {
     const frameTree = recordValue(requiredRecord(result).frameTree);
     const frame = recordValue(frameTree?.frame);
-    return await authorizedElectronFile(stringValue(frame?.url) ?? "");
+    return await authorizedElectronFile(cdpStringValue(frame?.url) ?? "");
 };
 const arrayValue = (value) => Array.isArray(value) ? value : [];
 const stringAt = (strings, value) => strings[integer(value, -1)] ?? "";

package/dist/browser/CdpElectronProvider.js

@@ -1,16 +1,16 @@
-import { electronPageInspectionSchema, electronTargetListSchema, } from "../domain/electronObservation.js";
-import { AnalysisError, BrowserObservationError, ProviderAdapterError, } from "../domain/errors.js";
+import { electronPageInspectionSchema, electronTargetListSchema, } from "../domain/javascript/electronObservation.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import {} from "../domain/browserObservationErrors.js";
 import { err, ok } from "../domain/result.js";
 import { discoverCdpEndpoint, hasCdpTargetWebSocket, } from "./CdpEndpoint.js";
 import { closeCdpTargetSession, openCdpTargetSession, } from "./CdpTargetSession.js";
 import { inspectCdpElectronPage } from "./CdpElectronInspection.js";
 import { authorizedElectronFile } from "./ElectronFileScope.js";
 /** Public identity committed by passive Electron observations. */
-export const CDP_ELECTRON_PROVIDER_IDENTITY = Object.freeze({
-    id: "rea-cdp-electron",
-    name: "REA Electron file-page CDP observation provider",
-    version: "1",
-});
+export { CDP_ELECTRON_PROVIDER_IDENTITY } from "./providerIdentities.js";
+import { CDP_ELECTRON_PROVIDER_IDENTITY } from "./providerIdentities.js";
 const IDENTITY = CDP_ELECTRON_PROVIDER_IDENTITY;
 /** Passive Electron provider for local file pages exposed by loopback CDP. */
 export class CdpElectronProvider {

package/dist/browser/CdpElectronScriptEvents.js

@@ -1,5 +1,5 @@
 import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
-import { numberValue, recordValue, stringValue } from "./CdpCaptureValues.js";
+import { numberValue, recordValue, cdpStringValue, } from "./CdpCaptureValues.js";
 /** Retain script/frame metadata from passive Electron events. */
 export const ingestElectronScriptEvent = (input) => {
     if (input.event.method === "Runtime.executionContextsCleared") {
@@ -20,8 +20,8 @@ export const ingestElectronScriptEvent = (input) => {
     if (input.event.method !== "Debugger.scriptParsed")
         return;
     const value = recordValue(input.event.params);
-    const scriptId = stringValue(value?.scriptId);
-    const rawUrl = stringValue(value?.url);
+    const scriptId = cdpStringValue(value?.scriptId);
+    const rawUrl = cdpStringValue(value?.url);
     if (scriptId === undefined) {
         input.completeness.exclude("scripts", "invalid_protocol_value");
         return;
@@ -33,10 +33,10 @@ export const ingestElectronScriptEvent = (input) => {
     input.scripts.push({
         scriptId,
         rawUrl,
-        hash: stringValue(value?.hash) ?? "",
+        hash: cdpStringValue(value?.hash) ?? "",
         length: nonnegativeInteger(value?.length),
         isModule: value?.isModule === true,
-        language: stringValue(value?.scriptLanguage) ?? null,
+        language: cdpStringValue(value?.scriptLanguage) ?? null,
         executionContextKey: executionContextKey(value?.executionContextId),
     });
 };
@@ -44,7 +44,7 @@ const retainExecutionContext = (event, frames) => {
     const parameters = recordValue(event.params);
     const runtimeContext = recordValue(parameters?.context);
     const contextKey = executionContextKey(runtimeContext?.id);
-    const frameId = stringValue(recordValue(runtimeContext?.auxData)?.frameId);
+    const frameId = cdpStringValue(recordValue(runtimeContext?.auxData)?.frameId);
     if (contextKey === null || frameId === undefined)
         return;
     frames.set(contextKey, frameId);

package/dist/browser/CdpElectronScripts.js

@@ -1,7 +1,7 @@
+import { canonicalDigest } from "../domain/comparisonSemantics.js";
 import { createWebTextArtifact } from "../domain/webContentArtifact.js";
 import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
-import { canonicalJsonDigest } from "./CdpCanonicalJsonDigest.js";
-import { requiredRecord, stringValue } from "./CdpCaptureValues.js";
+import { requiredRecord, cdpStringValue } from "./CdpCaptureValues.js";
 import { authorizedElectronFile } from "./ElectronFileScope.js";
 /** Normalize local script metadata and optionally approved source. */
 export const captureElectronScripts = async (input) => {
@@ -27,7 +27,7 @@ export const captureElectronScripts = async (input) => {
             is_module: script.isModule,
             language: script.language,
         };
-        const scriptKey = `electron_script_${canonicalJsonDigest(identity)}`;
+        const scriptKey = `electron_script_${canonicalDigest(identity, "CDP capture")}`;
         if (seen.has(scriptKey))
             continue;
         seen.add(scriptKey);
@@ -55,7 +55,7 @@ const captureScriptSource = async (input, script) => {
             },
         };
     const result = requiredRecord(await input.connection.send("Debugger.getScriptSource", { scriptId: script.scriptId }, input.sessionId, input.signal));
-    const text = stringValue(result.scriptSource) ?? "";
+    const text = cdpStringValue(result.scriptSource) ?? "";
     return {
         source: {
             included: true,

package/dist/browser/CdpElectronWorkers.js

@@ -1,5 +1,5 @@
 import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
-import { recordValue, recordsValue, stringValue } from "./CdpCaptureValues.js";
+import { recordValue, recordsValue, cdpStringValue, } from "./CdpCaptureValues.js";
 import { optionalCdpCommand } from "./CdpOptionalCommand.js";
 import { authorizedElectronFile } from "./ElectronFileScope.js";
 /** Inventory local worker targets without attaching to them. */
@@ -15,7 +15,7 @@ export const captureElectronWorkers = async (input) => {
     }
     const workers = [];
     for (const target of recordsValue(recordValue(result)?.targetInfos)) {
-        const type = stringValue(target.type) ?? "";
+        const type = cdpStringValue(target.type) ?? "";
         if (!type.includes("worker"))
             continue;
         const openerTargetId = boundedTargetField(target.openerId);
@@ -25,7 +25,7 @@ export const captureElectronWorkers = async (input) => {
             input.completeness.exclude("workers", "out_of_target_scope");
             continue;
         }
-        const path = await authorizedElectronFile(stringValue(target.url) ?? "");
+        const path = await authorizedElectronFile(cdpStringValue(target.url) ?? "");
         if (path === undefined) {
             input.completeness.exclude("workers", "out_of_target_scope");
             continue;
@@ -47,6 +47,6 @@ export const captureElectronWorkers = async (input) => {
     return workers.sort((left, right) => left.target_id.localeCompare(right.target_id));
 };
 const boundedTargetField = (value) => {
-    const field = stringValue(value);
+    const field = cdpStringValue(value);
     return field === undefined || field === "" ? null : field;
 };

package/dist/browser/CdpEndpoint.js

@@ -1,7 +1,11 @@
 import { request } from "node:http";
 import { z } from "zod";
-import { AnalysisCancelledError, AnalysisError, BrowserObservationError, } from "../domain/errors.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
+import {} from "../domain/browserObservationErrors.js";
 import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
+import { safeParseJson } from "../domain/safeJson.js";
 const endpointVersionSchema = z.object({
     Browser: z.string().min(1),
     "Protocol-Version": z.string().min(1),
@@ -49,7 +53,9 @@ const sanitizeTargetTitle = (value, targetUrl) => {
     try {
         url = new URL(value);
     }
-    catch {
+    catch (cause) {
+        // Non-URL titles fall back to alias redaction.
+        void cause;
         return sanitizeTargetUrlAlias(value, targetUrl);
     }
     return url.protocol === "http:" || url.protocol === "https:"
@@ -61,7 +67,9 @@ const sanitizeTargetUrlAlias = (value, targetUrl) => {
     try {
         parsed = new URL(targetUrl);
     }
-    catch {
+    catch (cause) {
+        // Without a parseable target URL there is nothing to redact.
+        void cause;
         return value;
     }
     const markers = [parsed.origin, `//${parsed.host}`, parsed.host];
@@ -79,7 +87,9 @@ const sanitizeSameOriginTitleUrl = (candidate, target) => {
                 ? new URL(`${target.protocol}//${candidate}`)
                 : new URL(candidate, target.origin);
     }
-    catch {
+    catch (cause) {
+        // Unparseable candidates are preserved verbatim.
+        void cause;
         return candidate;
     }
     return parsed.origin === target.origin &&
@@ -164,7 +174,9 @@ const targetWebSocket = (endpoint, target, operation) => {
             ? { webSocket }
             : {};
     }
-    catch {
+    catch (cause) {
+        // Endpoint validation failures mean no validated transport exists.
+        void cause;
         return {};
     }
 };
@@ -183,12 +195,12 @@ export const readCdpJson = async (url, operation, signal) => await new Promise((
         const chunks = [];
         response.on("data", (chunk) => chunks.push(chunk));
         response.on("end", () => {
-            try {
-                resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
-            }
-            catch (cause) {
-                reject(new BrowserObservationError(operation, "invalid_endpoint_response", { cause }));
+            const parsed = safeParseJson(Buffer.concat(chunks).toString("utf8"));
+            if (!parsed.ok) {
+                reject(new BrowserObservationError(operation, "invalid_endpoint_response", { cause: parsed.cause }));
+                return;
             }
+            resolve(parsed.value);
         });
         response.on("error", (cause) => reject(endpointFailure(cause, operation, signal)));
     });

package/dist/browser/CdpObservationSession.js

@@ -1,10 +1,12 @@
-import { AnalysisCancelledError, BrowserObservationError, } from "../domain/errors.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { CdpConnection } from "./CdpConnection.js";
 import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
 import { authorizedMainFrame } from "./CdpAuthorizedMainFrame.js";
-import { allowedSanitizedUrl, isHttpUrl, numberValue, recordValue, stringValue, } from "./CdpCaptureValues.js";
+import { allowedSanitizedUrl, isHttpUrl, numberValue, recordValue, cdpStringValue, } from "./CdpCaptureValues.js";
 import { mainFrameUrl } from "./CdpCaptureDocuments.js";
 import { isMainFrameNavigation } from "./CdpCaptureEventHelpers.js";
+import { cdpTargetEventMatches } from "./CdpTargetEvents.js";
 /** Observe external user actions without rejecting approved same-origin navigation. */
 export const observeCdpSession = async (context) => {
     const allowedOrigins = new Set(context.input.allowed_origins);
@@ -13,7 +15,7 @@ export const observeCdpSession = async (context) => {
         sessionId: context.sessionId,
         signal: context.signal,
         allowedOrigins,
-        delayOperation: "observe_web_session",
+        operation: "observe_web_session",
     });
     const initialUrl = mainFrameUrl(initial) ?? "";
     const mainFrameId = frameId(initial);
@@ -21,7 +23,7 @@ export const observeCdpSession = async (context) => {
         throw new BrowserObservationError("inspect_web_page", "protocol_error");
     const capture = new TimelineCapture(allowedOrigins, mainFrameId, initialUrl);
     const removeListener = context.connection.onEvent((event) => {
-        if (observationEventMatches(event, context.sessionId))
+        if (cdpTargetEventMatches(event, context.sessionId))
             capture.ingest(event);
     });
     const removeDisconnectListener = context.connection.onDisconnect(() => capture.targetTerminated());
@@ -159,7 +161,7 @@ class TimelineCapture {
         this.#add({
             type: "navigation_requested",
             params,
-            rawUrl: stringValue(params.url) ?? null,
+            rawUrl: cdpStringValue(params.url) ?? null,
             requestId: null,
             detail: reason,
         });
@@ -168,7 +170,7 @@ class TimelineCapture {
         const frame = recordValue(params.frame);
         if (!isMainFrameNavigation(event, this.mainFrameId))
             return;
-        const rawUrl = stringValue(frame?.url);
+        const rawUrl = cdpStringValue(frame?.url);
         const destination = scopedUrl(rawUrl, this.allowedOrigins);
         this.#add({
             type: this.#pendingReload ? "same_origin_reload" : "navigation_committed",
@@ -189,7 +191,7 @@ class TimelineCapture {
     #sameDocument(event, params) {
         if (!isMainFrameNavigation(event, this.mainFrameId))
             return;
-        const rawUrl = stringValue(params.url);
+        const rawUrl = cdpStringValue(params.url);
         const destination = scopedUrl(rawUrl, this.allowedOrigins);
         this.#add({
             type: "same_document_navigation",
@@ -207,20 +209,20 @@ class TimelineCapture {
         }
     }
     #redirect(params) {
-        const resourceType = stringValue(params.type);
+        const resourceType = cdpStringValue(params.type);
         if (resourceType !== undefined && resourceType !== "Document")
             return;
-        if (stringValue(params.frameId) !== this.mainFrameId ||
+        if (cdpStringValue(params.frameId) !== this.mainFrameId ||
             recordValue(params.redirectResponse) === undefined)
             return;
         const request = recordValue(params.request);
-        const rawUrl = stringValue(request?.url);
+        const rawUrl = cdpStringValue(request?.url);
         const destination = scopedUrl(rawUrl, this.allowedOrigins);
         this.#add({
             type: "redirect",
             params,
             rawUrl: rawUrl ?? null,
-            requestId: stringValue(params.requestId) ?? null,
+            requestId: cdpStringValue(params.requestId) ?? null,
             detail: null,
         });
         if (destination.scope !== "approved") {
@@ -229,19 +231,19 @@ class TimelineCapture {
         }
     }
     #loadingFailed(params) {
-        const frame = stringValue(params.frameId);
+        const frame = cdpStringValue(params.frameId);
         if (frame !== undefined && frame !== this.mainFrameId)
             return;
         this.#add({
             type: "load_failed",
             params,
             rawUrl: null,
-            requestId: stringValue(params.requestId) ?? null,
+            requestId: cdpStringValue(params.requestId) ?? null,
             detail: safeNetworkError(params.errorText),
         });
     }
     #lifecycle(params) {
-        if (stringValue(params.frameId) !== this.mainFrameId)
+        if (cdpStringValue(params.frameId) !== this.mainFrameId)
             return;
         this.#add({
             type: "lifecycle",
@@ -268,12 +270,6 @@ class TimelineCapture {
         });
     }
 }
-const observationEventMatches = (event, sessionId) => {
-    if (event.method !== "Target.detachedFromTarget")
-        return event.sessionId === sessionId;
-    return (sessionId !== undefined &&
-        stringValue(recordValue(event.params)?.sessionId) === sessionId);
-};
 const waitForWindow = async (durationMs, capture, signal) => await new Promise((resolve, reject) => {
     let settled = false;
     let removeEnd = () => { };
@@ -312,7 +308,7 @@ const captureFinalUrl = async (context, capture, allowedOrigins) => {
     capture.completeness.exclude("timeline", url === undefined ? "invalid_protocol_value" : "out_of_target_scope");
     return "target_left_scope";
 };
-const frameId = (result) => stringValue(recordValue(recordValue(recordValue(result)?.frameTree)?.frame)?.id);
+const frameId = (result) => cdpStringValue(recordValue(recordValue(recordValue(result)?.frameTree)?.frame)?.id);
 const scopedUrl = (value, allowedOrigins) => {
     const allowed = allowedSanitizedUrl(value, allowedOrigins);
     if (allowed !== undefined)
@@ -321,15 +317,15 @@ const scopedUrl = (value, allowedOrigins) => {
         ? { url: null, scope: "outside_policy" }
         : { url: null, scope: "unsupported" };
 };
-const boundedId = (value) => stringValue(value) ?? null;
+const boundedId = (value) => cdpStringValue(value) ?? null;
 const safeDetail = (value) => {
-    const detail = stringValue(value)?.toLowerCase();
+    const detail = cdpStringValue(value)?.toLowerCase();
     return detail !== undefined && /^[a-z0-9_.:-]{1,100}$/u.test(detail)
         ? detail
         : null;
 };
 const safeNetworkError = (value) => {
-    const error = stringValue(value);
+    const error = cdpStringValue(value);
     return error !== undefined && /^net::ERR_[A-Z0-9_]{1,100}$/u.test(error)
         ? error
         : null;

package/dist/browser/CdpOptionalCommand.js

@@ -1,4 +1,4 @@
-import { BrowserObservationError } from "../domain/errors.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { CdpConnection } from "./CdpConnection.js";
 /** Execute an optional CDP method while preserving transport and cancellation failures. */
 export const optionalCdpCommand = async (context, method, parameters, limitations) => {