rea-agents 4.1.0 → 6.0.0

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

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