rea-agents 4.0.1 → 5.0.0

package/dist/browser/assets/ScenarioScriptCapture.js

@@ -0,0 +1,76 @@
+/** Join script response bytes only through explicit transaction and event identity. */
+export const scenarioScripts = (capture) => {
+    const index = indexResponses(capture.events.items);
+    return capture.events.items.flatMap((request) => {
+        if (request.kind !== "request" || request.resource_type !== "script")
+            return [];
+        return [projectRequest(request, index)];
+    });
+};
+const indexResponses = (events) => {
+    const index = {
+        responses: new Map(),
+        contents: new Map(),
+        requests: new Map(),
+    };
+    for (const event of events) {
+        if (event.kind === "request" && event.transaction_id !== undefined)
+            index.requests.set(event.transaction_id, (index.requests.get(event.transaction_id) ?? 0) + 1);
+        if (event.kind === "response" && event.transaction_id !== undefined)
+            append(index.responses, event.transaction_id, event);
+        if (event.kind === "network-content" && event.phase === "response")
+            append(index.contents, event.source_event_sequence, event);
+    }
+    return index;
+};
+const projectRequest = (request, index) => {
+    const id = request.transaction_id;
+    const matches = id === undefined ? [] : (index.responses.get(id) ?? []);
+    const response = matches.length === 1 ? matches[0] : undefined;
+    const bodies = response === undefined ? [] : (index.contents.get(response.sequence) ?? []);
+    const body = bodies.length === 1 ? bodies[0]?.body : undefined;
+    const ambiguous = (id !== undefined && index.requests.get(id) !== 1) ||
+        matches.length > 1 ||
+        bodies.length > 1;
+    return {
+        source: {
+            kind: "scenario-response",
+            transaction_id: id ?? null,
+            request_sequence: request.sequence,
+            response_sequence: ambiguous ? null : (response?.sequence ?? null),
+            status: ambiguous ? null : (response?.status ?? null),
+        },
+        url: request.url.url,
+        content: projectBody(body, id, ambiguous),
+    };
+};
+const unavailable = (reason, message) => ({ state: "unavailable", reason, message });
+const projectBody = (body, transactionId, ambiguous) => {
+    if (ambiguous)
+        return unavailable("ambiguous-transaction", "The capture does not identify one request, response, and content record for this transaction.");
+    if (body === undefined)
+        return unavailable(transactionId === undefined
+            ? "transaction-identity-unavailable"
+            : "response-content-not-retained", "No selected, completed script response bytes were retained for this request.");
+    if (body.state === "unavailable")
+        return unavailable(body.reason, body.message);
+    if (body.state !== "captured")
+        return unavailable(body.state, "No selected, completed script response bytes were retained for this request.");
+    if (body.representation !== "browser-decoded-response-bytes")
+        return unavailable("unsupported-body-representation", `Captured representation ${body.representation} is not script response bytes.`);
+    return {
+        state: "captured",
+        bytes: Buffer.from(body.content, "base64"),
+        sha256: body.sha256,
+        media_type: body.media_type,
+        redacted: body.redacted,
+        representation: body.representation,
+    };
+};
+const append = (map, key, value) => {
+    const existing = map.get(key);
+    if (existing === undefined)
+        map.set(key, [value]);
+    else
+        existing.push(value);
+};

package/dist/browser/assets/ScriptCaptureAdapters.js

@@ -0,0 +1,57 @@
+import { webPageInspectionSchema } from "../../domain/browserObservation.js";
+import { browserScenarioCaptureSchema } from "../../domain/browserScenarioCapture.js";
+import { parseEvidence } from "../../domain/evidence.js";
+import { pageScripts } from "./PageScriptCapture.js";
+import { scenarioScripts } from "./ScenarioScriptCapture.js";
+/** Built-in adapters; add capture formats here without changing the publisher. */
+export const SCRIPT_CAPTURE_ADAPTERS = [
+    {
+        operation: "inspect_web_page",
+        parse: (input) => {
+            const parsed = webPageInspectionSchema.safeParse(input);
+            return parsed.success
+                ? {
+                    kind: "page-inspection",
+                    completeness: parsed.data.completeness,
+                    scripts: pageScripts(parsed.data),
+                    limitations: parsed.data.limitations,
+                }
+                : undefined;
+        },
+    },
+    {
+        operation: "capture_browser_scenario",
+        parse: (input) => {
+            const parsed = browserScenarioCaptureSchema.safeParse(input);
+            return parsed.success
+                ? {
+                    kind: "browser-scenario",
+                    completeness: parsed.data.completeness,
+                    scripts: scenarioScripts(parsed.data),
+                    limitations: parsed.data.limitations,
+                }
+                : undefined;
+        },
+    },
+];
+/** Reject unsupported/malformed captures and tampered Evidence before writing. */
+export const selectScriptCapture = (raw, adapters = SCRIPT_CAPTURE_ADAPTERS) => {
+    if (typeof raw === "object" &&
+        raw !== null &&
+        ("normalized_result" in raw || "evidence_id" in raw)) {
+        const evidence = parseEvidence(raw);
+        const selected = adapters
+            .find(({ operation }) => operation === evidence.operation)
+            ?.parse(evidence.normalized_result);
+        if (selected !== undefined)
+            return { ...selected, sourceEvidenceId: evidence.evidence_id };
+    }
+    else {
+        for (const adapter of adapters) {
+            const selected = adapter.parse(raw);
+            if (selected !== undefined)
+                return { ...selected, sourceEvidenceId: null };
+        }
+    }
+    throw new TypeError("Expected a valid inspect_web_page or capture_browser_scenario capture, with retained script sources or response bytes. Evidence envelopes must have a matching operation and semantic identifier.");
+};

package/dist/browser/assets/WebArtifactReads.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { AnalysisCancelledError, AnalysisInputError, } from "../../domain/analysisErrorCore.js";
+import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { safeParseJson } from "../../domain/safeJson.js";
+/** A malformed producer document, distinct from host I/O failures. */
+export class WebArtifactFormatFailure extends Error {
+}
+/** Decode exact UTF-8 content, preserving a BOM for digest verification. */
+export const decodeWebArtifact = (bytes) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new WebArtifactFormatFailure("Selected artifact is not valid UTF-8.", { cause });
+    }
+};
+/** Read one stable JSON artifact with a documented byte budget. */
+export const readWebArtifactJson = async (path, maximumBytes, signal) => {
+    const data = await readStableArtifact(path, maximumBytes, signal);
+    const value = safeParseJson(decodeWebArtifact(data.bytes));
+    if (!value.ok)
+        throw new WebArtifactFormatFailure(value.error);
+    return { ...data, value: value.value };
+};
+/** Preserve artifact format, integrity, OS I/O, and cancellation reasons. */
+export const webArtifactReadError = (cause, context, signal) => {
+    if (signal?.aborted === true)
+        return new AnalysisCancelledError(context.operation);
+    if (cause instanceof ArtifactReaderFailure)
+        return new ArtifactOperationError(context.operation, cause.reason, cause.details, cause.message);
+    if (cause instanceof Error &&
+        "code" in cause &&
+        typeof cause.code === "string" &&
+        "syscall" in cause &&
+        typeof cause.syscall === "string")
+        return new ArtifactOperationError(context.operation, "io", undefined, `${context.field.join(".")}: ${cause.code}: ${cause.message}`);
+    if (cause instanceof WebArtifactFormatFailure || cause instanceof z.ZodError)
+        return new AnalysisInputError(context.operation, { cause }, [
+            {
+                path: context.field,
+                reason: "invalid_format",
+                message: `${context.targetPath}: ${cause.message}`,
+            },
+        ]);
+    return new ProviderAdapterError("captured-web-artifacts", context.operation, {
+        cause,
+        diagnostics: {
+            target_path: context.targetPath,
+            field: context.field.join("."),
+            error_message: cause instanceof Error ? cause.message : String(cause),
+        },
+    });
+};

package/dist/browser/assets/WebSourceLocationArtifacts.js

@@ -0,0 +1,40 @@
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { WEB_SOURCE_MAP_LIMITS, } from "../../domain/webSourceLocation.js";
+import { err, ok } from "../../domain/result.js";
+import { LocalWebScriptArtifacts } from "./LocalWebScriptArtifacts.js";
+import { decodeWebArtifact, webArtifactReadError } from "./WebArtifactReads.js";
+/** Read one verified capture source and the caller-selected map, without fetching. */
+export class LocalWebSourceLocationArtifacts {
+    scripts;
+    constructor(scripts = new LocalWebScriptArtifacts("trace_web_source_location")) {
+        this.scripts = scripts;
+    }
+    /** Preserve actual map identity separately from the selected deployment URL. */
+    async load(input, options) {
+        const loaded = await this.scripts.load(input, options);
+        if (!loaded.ok)
+            return loaded;
+        try {
+            const data = await readStableArtifact(input.source_map.path, WEB_SOURCE_MAP_LIMITS.mapBytes, options?.signal);
+            return ok({
+                ...loaded.value,
+                sourceMap: {
+                    file: {
+                        path: input.source_map.path,
+                        sha256: data.sha256,
+                        bytes: data.bytes.length,
+                    },
+                    url: input.source_map.url,
+                    text: decodeWebArtifact(data.bytes),
+                },
+            });
+        }
+        catch (cause) {
+            return err(webArtifactReadError(cause, {
+                operation: "trace_web_source_location",
+                field: ["source_map", "path"],
+                targetPath: input.source_map.path,
+            }, options?.signal));
+        }
+    }
+}

package/dist/browser/execution/CdpEventListeners.js

@@ -0,0 +1,79 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { runtimeListenersSchema } from "./CdpRuntimeProtocol.js";
+import { queryListenerSelector } from "./CdpListenerSelector.js";
+/** Inspect native DOM listener descriptors without evaluating JavaScript or invoking handlers. */
+export const captureWebEventListeners = async (input, sources, group) => {
+    const session = sources.session;
+    session.beginCompletion();
+    const unsubscribe = session.transport.connection.onEvent((event) => sources.ingest(event));
+    try {
+        for (const domain of ["Page", "Runtime", "Debugger", "DOM"])
+            await session.enable(domain);
+        await session.assertDocument();
+        const document = z
+            .object({ root: z.object({ nodeId: z.number().int().min(1) }) })
+            .parse(await session.command("DOM.getDocument", { depth: 0 }));
+        const selected = z
+            .object({ nodeId: z.number().int().min(0) })
+            .parse(await queryListenerSelector(session, document.root.nodeId, input.selector));
+        let backendNodeId = null;
+        let descriptors = [];
+        if (selected.nodeId !== 0) {
+            const described = z
+                .object({ node: z.object({ backendNodeId: z.number().int().min(1) }) })
+                .parse(await session.command("DOM.describeNode", {
+                nodeId: selected.nodeId,
+            }));
+            backendNodeId = described.node.backendNodeId;
+            const resolved = z
+                .object({ object: z.object({ objectId: z.string().min(1) }) })
+                .parse(await session.command("DOM.resolveNode", {
+                nodeId: selected.nodeId,
+                objectGroup: group,
+            }));
+            descriptors = runtimeListenersSchema.parse(await session.command("DOMDebugger.getEventListeners", {
+                objectId: resolved.object.objectId,
+                depth: 0,
+                pierce: false,
+            })).listeners;
+        }
+        const retained = await sources.read(descriptors
+            .map((listener) => listener.scriptId)
+            .filter((id) => id.length > 0));
+        await session.assertDocument();
+        sources.check();
+        return {
+            browser: session.discovery.version,
+            target: session.target,
+            inspected_at: new Date().toISOString(),
+            selected_node: {
+                selector: input.selector,
+                match: selected.nodeId === 0 ? "not_found" : "found",
+                backend_node_id: backendNodeId,
+            },
+            listeners: descriptors.map((listener) => ({
+                type: listener.type,
+                use_capture: listener.useCapture,
+                passive: listener.passive,
+                once: listener.once,
+                location: sources.location(listener.scriptId, sources.scripts.get(listener.scriptId)?.url ?? null, listener.lineNumber, listener.columnNumber),
+                execution: "unknown",
+            })),
+            sources: retained,
+            cleanup: "confirmed",
+            limitations: [
+                "Inspects listeners registered directly on the first native CSS match in the selected main document. Delegated ancestor listeners, descendants, closed shadow roots and framework registries are not enumerated.",
+                "Native CDP listener descriptors report callback locations; registration time, dispatch history and UI causality remain unknown. REA does not dispatch an event, evaluate JavaScript or invoke a handler.",
+                "Source identity uses this session's script ID and proven main-frame default-world metadata. Isolated or unknown worlds cannot establish website callback/source joins. A URL or sourceURL declaration never establishes identity or execution.",
+                "Source text is retained inline with its independently computed UTF-8 digest; the producer hash is preserved separately. Missing source ownership or collected scripts remain explicit.",
+                "REA releases its remote object group, disables enabled domains and detaches its transport; the externally owned page remains open.",
+            ],
+        };
+    }
+    finally {
+        unsubscribe();
+    }
+};
+/** Use an owned remote object namespace so cleanup does not release caller objects. */
+export const eventListenerObjectGroup = () => `rea-listeners-${randomUUID()}`;

package/dist/browser/execution/CdpExecutionCapture.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { BrowserObservationError } from "../../domain/browserObservationError.js";
+import { AnalysisCancelledError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { CdpExecutionCollection } from "./CdpExecutionCollection.js";
+import { preciseCoverageSchema } from "./CdpRuntimeProtocol.js";
+import { normalizePreciseCoverage } from "./CdpPreciseCoverage.js";
+/** Capture one explicit resetting coverage sample and its request-source relationships. */
+export const captureWebExecution = async (input, sources) => {
+    const session = sources.session;
+    const collection = new CdpExecutionCollection(sources);
+    const { window, requests } = collection;
+    try {
+        for (const domain of ["Page", "Runtime", "Debugger", "Network", "Profiler"])
+            await session.enable(domain);
+        await session.assertDocument();
+        sources.check();
+        session.preciseCoverageMayBeActive = true;
+        const started = z.object({ timestamp: z.number().min(0) }).parse(await session.command("Profiler.startPreciseCoverage", {
+            callCount: true,
+            detailed: true,
+            allowTriggeredUpdates: false,
+        }));
+        sources.check();
+        window.check();
+        if (window.reason !== undefined)
+            throw new BrowserObservationError(session.operation, "target_changed", {
+                detail: `Selected target ${session.target.target_id} ended with ${window.reason} before execution observation could be armed.`,
+            });
+        const waiting = window.start(input.observation_ms);
+        // Cancellation may arrive while asynchronous progress is being delivered.
+        void waiting.catch(() => undefined);
+        await session.options.progress?.report({
+            phase: "browser_execution",
+            completed: 1,
+            total: 2,
+            message: "Browser execution observation armed; perform the requested action now",
+        });
+        const reason = await waiting;
+        session.beginCompletion();
+        if (session.options.signal?.aborted)
+            throw new AnalysisCancelledError(session.operation);
+        sources.check();
+        requests.check();
+        let raw;
+        if (reason === "window_elapsed") {
+            await session.assertDocument();
+            raw = await session.command("Profiler.takePreciseCoverage");
+        }
+        collection.freezeMetadata();
+        await session.command("Profiler.stopPreciseCoverage");
+        session.preciseCoverageMayBeActive = false;
+        const requestItems = requests.result();
+        const parsed = raw === undefined ? undefined : preciseCoverageSchema.safeParse(raw);
+        if (parsed !== undefined && !parsed.success)
+            throw new AnalysisOutputError(session.operation, `Malformed precise coverage: ${parsed.error.message}`);
+        const mainScripts = [...sources.scripts.keys()].filter((id) => sources.belongsToDocument(id));
+        const reportedIds = new Set(parsed?.success === true
+            ? parsed.data.result.map((script) => script.scriptId)
+            : []);
+        const ids = [
+            ...mainScripts,
+            ...requestItems
+                .flatMap((request) => request.callsites.map((site) => site.script_id))
+                .filter((id) => id.length > 0),
+        ];
+        const retained = await sources.read(ids);
+        if (reason === "window_elapsed")
+            await session.assertDocument();
+        sources.check();
+        const verifiedRequests = requests.result();
+        const verifiedMainScripts = mainScripts.filter((id) => sources.belongsToDocument(id));
+        const sample = raw === undefined
+            ? undefined
+            : normalizePreciseCoverage(raw, sources, retained);
+        await session.options.progress?.report({
+            phase: "browser_execution",
+            completed: 2,
+            total: 2,
+            message: "Browser execution observation ended",
+            terminal: true,
+        });
+        return {
+            browser: session.discovery.version,
+            target: session.target,
+            window: {
+                armed_at: window.armedAt ?? new Date().toISOString(),
+                ended_at: window.endedAt ?? new Date().toISOString(),
+                requested_ms: input.observation_ms,
+                end_reason: reason,
+                producer_started_seconds: started.timestamp,
+                producer_sampled_seconds: sample?.timestamp ?? null,
+            },
+            coverage: sample?.coverage ?? {
+                state: "unavailable",
+                reason: `The observation ended with ${reason}; no complete final precise-coverage sample was retained.`,
+                offset_units: "utf16-code-units",
+                end_offset: "exclusive",
+                scripts: [],
+                excluded_scripts: 0,
+            },
+            requests: verifiedRequests,
+            excluded_requests: requests.excluded,
+            script_inventory: {
+                main_document_scripts: verifiedMainScripts.length,
+                not_reported_script_ids: verifiedMainScripts.filter((id) => !reportedIds.has(id)),
+                coverage_absence: "unknown",
+            },
+            sources: retained,
+            instrumentation: {
+                resets_execution_counters: true,
+                disables_optimized_execution: true,
+                takes_one_resetting_sample: sample !== undefined,
+                executes_selected_code: false,
+                cleanup: "confirmed",
+                page_ownership: "external",
+            },
+            limitations: [
+                "Website source ownership requires the selected main frame and a proven default execution world. Isolated, worker and unknown worlds are excluded from coverage/source joins; referenced producer context metadata is retained.",
+                "Precise coverage resets counters, retains execution records and prevents optimized execution until stopped. Timing and JIT behavior are affected.",
+                "Only the selected main document's proven frame/context scripts are attributed. Child frames, workers, service workers, WebAssembly and scripts without ownership metadata remain outside this operation.",
+                "V8 reports nested function/block ranges and counts, not a chronological trace. Counts must not be summed across overlapping ranges; zero counts concern this instrumented window only.",
+                "Previously parsed scripts may be absent from a precise sample. Their source inventory is retained, but missing coverage never means zero execution or an unexecuted function.",
+                "A detailed-coverage request does not guarantee block granularity for already compiled functions. When is_block_coverage is false, branch execution is unknown; REA preserves the function-only producer ranges.",
+                "The local armed/end clock and backend coverage timestamps are distinct clocks. Counters start when the backend accepts instrumentation, before the armed receipt, and end at the resetting sample after the requested window. Counts may include execution during those command intervals; requests are restricted to the locally armed window.",
+                "Source metadata is collected through the final resetting sample, then frozen for source joins. Known identities remain checked during asynchronous source completion; newly parsed scripts after that cutoff are outside this evidence.",
+                "Request callsites are producer-reported initiators associated by session script ID; they do not establish UI causality. Unresolved asynchronous parent IDs are retained without fetching their stacks.",
+                "Producer hashes and UTF-8 digests of retained text are distinct identities. Inline script locations use reported resource offsets; anonymous/eval/sourceURL names are declarations.",
+                "Metadata has an 8 MiB script budget and 8 MiB request budget; complete retained sources have a 32 MiB budget. Resource failures return no partial success. The externally owned browser's CPU and memory are not controlled by REA.",
+            ],
+        };
+    }
+    finally {
+        collection.close();
+    }
+};

package/dist/browser/execution/CdpExecutionCollection.js

@@ -0,0 +1,57 @@
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { cdpTargetEventMatches } from "../CdpTargetEvents.js";
+import { CdpExecutionWindow } from "./CdpExecutionWindow.js";
+import { CdpRuntimeRequests } from "./CdpRuntimeRequests.js";
+/** Own source/request collection and failure subscriptions through a precise-sample cutoff. */
+export class CdpExecutionCollection {
+    sources;
+    window;
+    requests;
+    #unsubscribers;
+    #metadataOpen = true;
+    constructor(sources) {
+        this.sources = sources;
+        const session = sources.session;
+        this.window = new CdpExecutionWindow(session);
+        this.requests = new CdpRuntimeRequests(sources);
+        this.#unsubscribers = [
+            session.transport.connection.onEvent((event) => {
+                if (!cdpTargetEventMatches(event, session.transport.sessionId))
+                    return;
+                try {
+                    if (this.#metadataOpen &&
+                        (this.window.reason === undefined ||
+                            this.window.reason === "window_elapsed"))
+                        sources.ingest(event);
+                    else if (this.window.reason === "window_elapsed")
+                        sources.verifyKnownIdentity(event);
+                    if (this.window.active)
+                        this.requests.ingest(event);
+                    sources.check();
+                    this.requests.check();
+                }
+                catch (cause) {
+                    this.window.fail(cause instanceof AnalysisError
+                        ? cause
+                        : new AnalysisOutputError(session.operation, String(cause)));
+                }
+                this.window.ingest(event);
+            }),
+            session.transport.connection.onDisconnect(() => this.window.end("target_terminated")),
+            session.transport.connection.onProtocolFailure((error) => this.window.fail(error)),
+        ];
+    }
+    /** Freeze metadata after receiving the final sample so source joins use one fixed inventory. */
+    freezeMetadata() {
+        this.#metadataOpen = false;
+        this.sources.check();
+    }
+    /** Remove every owned subscription and local timer on success, cancellation or failure. */
+    close() {
+        this.#metadataOpen = false;
+        this.window.dispose();
+        for (const unsubscribe of this.#unsubscribers)
+            unsubscribe();
+    }
+}

package/dist/browser/execution/CdpExecutionWindow.js

@@ -0,0 +1,100 @@
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+/** One finite document-scoped window, with an actual armed point and event-driven termination. */
+export class CdpExecutionWindow {
+    session;
+    armedAt;
+    endedAt;
+    reason;
+    #timer;
+    #resolve;
+    #reject;
+    #failure;
+    #removeAbort;
+    constructor(session) {
+        this.session = session;
+    }
+    /** Collection ends on a main-document replacement, never follows source URLs into another context. */
+    ingest(event) {
+        if (event.method === "Target.detachedFromTarget" ||
+            event.method === "Inspector.targetCrashed") {
+            this.end("target_terminated");
+            return;
+        }
+        if (!this.active)
+            return;
+        if (event.method === "Runtime.executionContextsCleared")
+            this.end("document_changed");
+        if (event.method === "Page.frameNavigated" &&
+            typeof event.params === "object" &&
+            event.params !== null &&
+            "frame" in event.params) {
+            const frame = event.params.frame;
+            if (typeof frame === "object" && frame !== null && !("parentId" in frame))
+                this.end("document_changed");
+        }
+        if (event.method === "Page.frameDetached" &&
+            typeof event.params === "object" &&
+            event.params !== null &&
+            "frameId" in event.params &&
+            event.params.frameId === this.session.target.frame_id)
+            this.end("document_changed");
+    }
+    /** Metadata before arming is inventory; request events outside the window are excluded. */
+    get active() {
+        return (this.armedAt !== undefined &&
+            this.reason === undefined &&
+            this.endedAt === undefined);
+    }
+    /** The timer starts at arming, before progress delivery can delay the external action. */
+    start(duration) {
+        this.armedAt = new Date().toISOString();
+        if (this.#failure !== undefined)
+            return Promise.reject(this.#failure);
+        if (this.reason !== undefined)
+            return Promise.resolve(this.reason);
+        return new Promise((resolve, reject) => {
+            this.#resolve = resolve;
+            this.#reject = reject;
+            this.#timer = setTimeout(() => this.end("window_elapsed"), duration);
+            const signal = this.session.options.signal;
+            const abort = () => {
+                this.endedAt = new Date().toISOString();
+                this.dispose();
+                this.#reject?.(new AnalysisCancelledError(this.session.operation));
+            };
+            this.#removeAbort = () => signal?.removeEventListener("abort", abort);
+            signal?.addEventListener("abort", abort, { once: true });
+            if (signal?.aborted)
+                abort();
+        });
+    }
+    /** Transport loss ends the window; instrumentation cleanup still requires confirmation. */
+    end(reason) {
+        if (this.reason !== undefined || this.#failure !== undefined)
+            return;
+        this.reason = reason;
+        this.endedAt = new Date().toISOString();
+        this.dispose();
+        this.#resolve?.(reason);
+    }
+    /** Invalid producer data ends instrumentation immediately with its original failure. */
+    fail(error) {
+        if (this.reason !== undefined || this.#failure !== undefined)
+            return;
+        this.#failure = error;
+        this.endedAt = new Date().toISOString();
+        this.dispose();
+        this.#reject?.(error);
+    }
+    /** Surface a failure recorded before local arming without emitting misleading progress. */
+    check() {
+        if (this.#failure !== undefined)
+            throw this.#failure;
+    }
+    /** Release local timer and abort listener on every setup/failure path. */
+    dispose() {
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        this.#removeAbort?.();
+    }
+}

package/dist/browser/execution/CdpListenerSelector.js

@@ -0,0 +1,22 @@
+import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
+import { CdpCommandRejection } from "../CdpCommandRejection.js";
+/** Classify Chromium's selector syntax rejection without changing other command/transport failures. */
+export const queryListenerSelector = async (session, nodeId, selector) => {
+    try {
+        return await session.command("DOM.querySelector", { nodeId, selector });
+    }
+    catch (cause) {
+        if (cause instanceof CdpCommandRejection &&
+            cause.command === "DOM.querySelector" &&
+            cause.code === -32000 &&
+            cause.reportedMessage === "DOM Error while querying")
+            throw new AnalysisInputError(session.operation, { cause }, [
+                {
+                    path: ["selector"],
+                    reason: "invalid_format",
+                    message: `Chromium rejected the CSS selector syntax for target ${session.target.target_id}: ${selector}. ${cause.userMessage ?? cause.message}`,
+                },
+            ]);
+        throw cause;
+    }
+};