rea-agents 4.1.0 → 5.0.0

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;
+    }
+};

package/dist/browser/execution/CdpPreciseCoverage.js

@@ -0,0 +1,48 @@
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { preciseCoverageSchema } from "./CdpRuntimeProtocol.js";
+/** Validate source-range bounds against exact retained UTF-16 text without flattening nested counts. */
+export const normalizePreciseCoverage = (raw, sources, retained) => {
+    const parsed = preciseCoverageSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new AnalysisOutputError(sources.session.operation, `Malformed precise coverage: ${parsed.error.message}`);
+    const scripts = [];
+    let excluded = 0;
+    for (const script of parsed.data.result) {
+        if (!sources.belongsToDocument(script.scriptId)) {
+            excluded += 1;
+            continue;
+        }
+        const source = retained.find((item) => item.script_id === script.scriptId)?.source;
+        scripts.push({
+            script_id: script.scriptId,
+            reported_url: sources.sourceUrl(script.scriptId, script.url),
+            functions: script.functions.map((fn) => ({
+                name: fn.functionName,
+                is_block_coverage: fn.isBlockCoverage,
+                ranges: fn.ranges.map((range) => {
+                    if (range.endOffset < range.startOffset ||
+                        (source?.state === "captured" &&
+                            range.endOffset > source.utf16_units))
+                        throw new AnalysisOutputError(sources.session.operation, `Script ${script.scriptId} coverage range ${range.startOffset}:${range.endOffset} is outside retained source bounds.`);
+                    return {
+                        start_offset: range.startOffset,
+                        end_offset: range.endOffset,
+                        count: range.count,
+                        source_bounds: source?.state === "captured" ? "verified" : "unknown",
+                    };
+                }),
+            })),
+        });
+    }
+    return {
+        timestamp: parsed.data.timestamp,
+        coverage: {
+            state: "captured",
+            reason: null,
+            offset_units: "utf16-code-units",
+            end_offset: "exclusive",
+            scripts,
+            excluded_scripts: excluded,
+        },
+    };
+};

package/dist/browser/execution/CdpRuntimeInitiator.js

@@ -0,0 +1,18 @@
+import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Sanitize known transport fields while retaining declarations and every unknown producer field. */
+export const sanitizeRuntimeInitiator = (initiator, sources) => {
+    if (typeof initiator.url === "string")
+        initiator.url = sanitizeBrowserUrl(initiator.url).url;
+    let stack = initiator.stack;
+    while (isObject(stack)) {
+        if (Array.isArray(stack.callFrames))
+            for (const frame of stack.callFrames)
+                if (isObject(frame) &&
+                    typeof frame.url === "string" &&
+                    typeof frame.scriptId === "string")
+                    frame.url = sources.sourceUrl(frame.scriptId, frame.url);
+        stack = stack.parent;
+    }
+    return initiator;
+};

package/dist/browser/execution/CdpRuntimeProtocol.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+const integer = z.number().int().min(0);
+const contextAuxDataSchema = z
+    .object({
+    frameId: z.string().optional(),
+    isDefault: z.boolean().optional(),
+    type: z.string().optional(),
+})
+    .passthrough();
+/** Validated producer script metadata; optional declarations remain unknown when absent. */
+export const runtimeScriptParsedSchema = z.object({
+    scriptId: z.string().min(1),
+    url: z.string(),
+    executionContextId: integer,
+    startLine: integer,
+    startColumn: integer,
+    endLine: integer,
+    endColumn: integer,
+    hash: z.string().optional(),
+    sourceMapURL: z.string().optional(),
+    hasSourceURL: z.boolean().optional(),
+    scriptLanguage: z.string().optional(),
+    executionContextAuxData: contextAuxDataSchema.optional(),
+});
+/** Frame ownership is taken from producer context metadata, independently of source URLs. */
+export const runtimeContextSchema = z.object({
+    context: z
+        .object({
+        id: integer,
+        origin: z.string().optional(),
+        name: z.string().optional(),
+        uniqueId: z.string().optional(),
+        auxData: contextAuxDataSchema.optional(),
+    })
+        .passthrough(),
+});
+const range = z.object({
+    startOffset: integer,
+    endOffset: integer,
+    count: integer,
+});
+/** CDP precise coverage preserves every nested producer range. */
+export const preciseCoverageSchema = z.object({
+    timestamp: z.number().min(0),
+    result: z.array(z.object({
+        scriptId: z.string().min(1),
+        url: z.string(),
+        functions: z.array(z.object({
+            functionName: z.string(),
+            isBlockCoverage: z.boolean(),
+            ranges: z.array(range),
+        })),
+    })),
+});
+/** The full reported synchronous and embedded asynchronous stack is retained. */
+export const runtimeStackSchema = z.object({
+    callFrames: z.array(z.object({
+        scriptId: z.string(),
+        url: z.string(),
+        lineNumber: integer,
+        columnNumber: integer,
+        functionName: z.string(),
+    })),
+    parent: z.unknown().optional(),
+    parentId: z
+        .object({ id: z.string(), debuggerId: z.string().optional() })
+        .optional(),
+});
+/** Request evidence contains metadata and producer initiators; bodies and headers are outside this tool. */
+export const runtimeRequestSchema = z.object({
+    requestId: z.string().min(1),
+    frameId: z.string().optional(),
+    timestamp: z.number().min(0),
+    request: z.object({ url: z.string(), method: z.string() }),
+    initiator: z
+        .object({
+        type: z.string(),
+        stack: z.unknown().optional(),
+        url: z.string().optional(),
+        lineNumber: integer.optional(),
+        columnNumber: integer.optional(),
+    })
+        .passthrough(),
+});
+/** Native listener descriptors omit live remote handles from portable evidence. */
+export const runtimeListenersSchema = z.object({
+    listeners: z.array(z.object({
+        type: z.string(),
+        useCapture: z.boolean(),
+        passive: z.boolean(),
+        once: z.boolean(),
+        scriptId: z.string(),
+        lineNumber: integer,
+        columnNumber: integer,
+    })),
+});
+/** Current main frame identity protects same-URL reloads as well as URL changes. */
+export const runtimeFrameTreeSchema = z.object({
+    frameTree: z.object({
+        frame: z.object({
+            id: z.string().min(1),
+            url: z.string(),
+            loaderId: z.string().optional(),
+        }),
+    }),
+});

package/dist/browser/execution/CdpRuntimeRequests.js

@@ -0,0 +1,81 @@
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { WEB_RUNTIME_LIMITS } from "../../domain/webRuntime.js";
+import { runtimeRequestSchema, runtimeStackSchema, } from "./CdpRuntimeProtocol.js";
+import { sanitizeRuntimeInitiator } from "./CdpRuntimeInitiator.js";
+/** Join producer initiators by script ID while preserving unresolved async parent identities. */
+export class CdpRuntimeRequests {
+    sources;
+    items = [];
+    excluded = 0;
+    #bytes = 0;
+    #failure;
+    constructor(sources) {
+        this.sources = sources;
+    }
+    /** Retain only armed-window requests from the selected main frame and selected origins. */
+    ingest(event) {
+        if (event.method !== "Network.requestWillBeSent" ||
+            this.#failure !== undefined)
+            return;
+        try {
+            const request = runtimeRequestSchema.parse(event.params);
+            const url = sanitizeBrowserUrl(request.request.url);
+            if (request.frameId !== this.sources.session.target.frame_id ||
+                url.origin === null ||
+                !this.sources.session.allowedOrigins.has(url.origin)) {
+                this.excluded += 1;
+                return;
+            }
+            this.#bytes += Buffer.byteLength(JSON.stringify(event.params));
+            if (this.#bytes > WEB_RUNTIME_LIMITS.retainedEventBytes)
+                throw new Error("Request initiator evidence exceeds its complete 8 MiB event budget.");
+            const callsites = [];
+            const parents = [];
+            let current = request.initiator.stack;
+            while (current !== undefined) {
+                const stack = runtimeStackSchema.parse(current);
+                for (const frame of stack.callFrames)
+                    callsites.push(this.sources.location(frame.scriptId, frame.url, frame.lineNumber, frame.columnNumber, frame.functionName));
+                if (stack.parentId !== undefined)
+                    parents.push({
+                        id: stack.parentId.id,
+                        debugger_id: stack.parentId.debuggerId ?? null,
+                    });
+                current = stack.parent;
+            }
+            if (request.initiator.url !== undefined &&
+                request.initiator.lineNumber !== undefined)
+                callsites.push(this.sources.location("", sanitizeBrowserUrl(request.initiator.url).url, request.initiator.lineNumber, request.initiator.columnNumber ?? null));
+            this.items.push({
+                request_id: request.requestId,
+                url: url.url,
+                method: request.request.method,
+                timestamp_seconds: request.timestamp,
+                initiator_type: request.initiator.type,
+                reported_initiator: sanitizeRuntimeInitiator(jsonObjectSchema.parse(request.initiator), this.sources),
+                callsites,
+                async_parent_ids: parents,
+                causal_attribution: "unknown",
+            });
+        }
+        catch (cause) {
+            this.#failure = new AnalysisOutputError(this.sources.session.operation, cause instanceof Error ? cause.message : String(cause));
+        }
+    }
+    /** Preserve all repeated/redirect requests and bind callsites after metadata collection ends. */
+    result() {
+        this.check();
+        return this.items.map((request) => ({
+            ...request,
+            reported_initiator: sanitizeRuntimeInitiator(jsonObjectSchema.parse(request.reported_initiator), this.sources),
+            callsites: request.callsites.map((site) => this.sources.location(site.script_id, site.url, site.line_number, site.column_number, site.function_name)),
+        }));
+    }
+    /** Report malformed or oversized producer evidence without partial success. */
+    check() {
+        if (this.#failure !== undefined)
+            throw this.#failure;
+    }
+}

package/dist/browser/execution/CdpRuntimeSession.js

@@ -0,0 +1,163 @@
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisTimeoutError } from "../../domain/analysisErrorCore.js";
+import { BrowserObservationError } from "../../domain/browserObservationError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
+import { WEB_RUNTIME_LIMITS, } from "../../domain/webRuntime.js";
+import { authorizeCdpTarget } from "../CdpAuthorizedTarget.js";
+import { authorizedMainFrame } from "../CdpAuthorizedMainFrame.js";
+import { discoverCdpEndpoint, } from "../CdpEndpoint.js";
+import { openCdpTargetSession, } from "../CdpTargetSession.js";
+import { runtimeFrameTreeSchema } from "./CdpRuntimeProtocol.js";
+/** Owned transport and instrumentation; the selected browser/page remain externally owned. */
+export class CdpRuntimeSession {
+    transport;
+    discovery;
+    target;
+    allowedOrigins;
+    operation;
+    options;
+    enabledDomains = [];
+    preciseCoverageMayBeActive = false;
+    #completion;
+    #completionTimer;
+    constructor(transport, discovery, target, allowedOrigins, operation, options) {
+        this.transport = transport;
+        this.discovery = discovery;
+        this.target = target;
+        this.allowedOrigins = allowedOrigins;
+        this.operation = operation;
+        this.options = options;
+    }
+    /** Acquire a validated target; failed setup releases its owned socket. */
+    static async open(input, operation, options) {
+        return runtimeDeadline(operation, options.signal, async (signal) => {
+            const discovery = await discoverCdpEndpoint(input.cdp_endpoint, operation, signal);
+            const { target, allowedOrigins } = authorizeCdpTarget(discovery, input, operation);
+            const transport = await openCdpTargetSession(discovery, target, operation, signal, { maxPayloadBytes: WEB_RUNTIME_LIMITS.protocolBytes });
+            try {
+                const tree = runtimeFrameTreeSchema.parse(await authorizedMainFrame({
+                    ...transport,
+                    allowedOrigins,
+                    signal,
+                    operation,
+                }));
+                const frame = tree.frameTree.frame;
+                const url = sanitizeBrowserUrl(frame.url);
+                if (url.origin === null)
+                    throw new BrowserObservationError(operation, "target_not_allowed");
+                return new CdpRuntimeSession(transport, discovery, {
+                    target_id: target.id,
+                    initial_url: url.url,
+                    origin: url.origin,
+                    frame_id: frame.id,
+                    loader_id: frame.loaderId ?? null,
+                }, allowedOrigins, operation, options);
+            }
+            catch (cause) {
+                await transport.connection.close();
+                throw cause;
+            }
+        });
+    }
+    /** Bound each command separately from the caller-selected observation duration. */
+    async command(method, params = {}) {
+        const signals = [this.options.signal, this.#completion?.signal].filter((signal) => signal !== undefined);
+        try {
+            return await runtimeDeadline(this.operation, signals.length === 0 ? undefined : AbortSignal.any(signals), (signal) => this.transport.connection.send(method, params, this.transport.sessionId, signal));
+        }
+        catch (cause) {
+            if (this.#completion?.signal.aborted && !this.options.signal?.aborted)
+                throw new AnalysisTimeoutError(this.operation, WEB_RUNTIME_LIMITS.commandTimeoutMs);
+            throw cause;
+        }
+    }
+    /** Bound the complete inspection/source-join phase as well as each individual command. */
+    beginCompletion() {
+        if (this.#completion !== undefined)
+            return;
+        this.#completion = new AbortController();
+        this.#completionTimer = setTimeout(() => this.#completion?.abort(), WEB_RUNTIME_LIMITS.commandTimeoutMs);
+    }
+    /** Register cleanup before sending: cancellation can occur after producer acceptance. */
+    async enable(domain) {
+        this.enabledDomains.push(domain);
+        await this.command(`${domain}.enable`);
+    }
+    /** Check document identity before joining any live node or final coverage evidence. */
+    async assertDocument() {
+        const frame = runtimeFrameTreeSchema.parse(await this.command("Page.getFrameTree")).frameTree.frame;
+        const url = sanitizeBrowserUrl(frame.url);
+        if (frame.id !== this.target.frame_id ||
+            (frame.loaderId ?? null) !== this.target.loader_id ||
+            (this.target.loader_id === null && url.url !== this.target.initial_url))
+            throw new BrowserObservationError(this.operation, "target_changed", {
+                detail: `Selected target ${this.target.target_id} changed document during ${this.operation}.`,
+            });
+        if (url.origin === null || !this.allowedOrigins.has(url.origin))
+            throw new BrowserObservationError(this.operation, "target_not_allowed", {
+                detail: `Selected target ${this.target.target_id} moved to an unselected origin during ${this.operation}.`,
+            });
+    }
+    /** Cleanup uses its own deadline after caller cancellation, then closes REA's transport. */
+    async close(previousError, objectGroup) {
+        if (this.#completionTimer !== undefined)
+            clearTimeout(this.#completionTimer);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), WEB_RUNTIME_LIMITS.cleanupTimeoutMs);
+        const failures = [];
+        const send = async (method, params = {}) => {
+            try {
+                await this.transport.connection.send(method, params, this.transport.sessionId, controller.signal);
+            }
+            catch (cause) {
+                failures.push(`${method}: ${cause instanceof AnalysisError ? (cause.userMessage ?? cause.message) : cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        };
+        try {
+            if (this.preciseCoverageMayBeActive)
+                await send("Profiler.stopPreciseCoverage");
+            if (objectGroup !== undefined)
+                await send("Runtime.releaseObjectGroup", { objectGroup });
+            for (const domain of [...this.enabledDomains].reverse())
+                await send(`${domain}.disable`);
+            if (this.transport.sessionId !== undefined) {
+                try {
+                    await this.transport.connection.send("Target.detachFromTarget", { sessionId: this.transport.sessionId }, undefined, controller.signal);
+                }
+                catch (cause) {
+                    failures.push(`Target.detachFromTarget: ${cause instanceof AnalysisError ? (cause.userMessage ?? cause.message) : cause instanceof Error ? cause.message : String(cause)}`);
+                }
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            await this.transport.connection.close();
+        }
+        return failures.length === 0
+            ? undefined
+            : new ProviderCleanupError("rea-cdp-browser", [this.target.target_id, "runtime-instrumentation"], {
+                target_id: this.target.target_id,
+                cleanup_failures: failures,
+                previous_error: previousError?.userMessage ?? previousError?.message ?? null,
+            }, { operation: this.operation });
+    }
+}
+/** Apply a disposable command deadline without turning timeout into caller cancellation. */
+export const runtimeDeadline = async (operation, signal, run) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), WEB_RUNTIME_LIMITS.commandTimeoutMs);
+    try {
+        return await run(signal === undefined
+            ? controller.signal
+            : AbortSignal.any([signal, controller.signal]));
+    }
+    catch (cause) {
+        if (controller.signal.aborted && signal?.aborted !== true)
+            throw new AnalysisTimeoutError(operation, WEB_RUNTIME_LIMITS.commandTimeoutMs);
+        throw cause;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};