rea-agents 1.4.0 → 1.6.0

package/dist/browser/CdpConnection.js

@@ -0,0 +1,241 @@
+import WebSocket, {} from "ws";
+import { AnalysisCancelledError, AnalysisError, AnalysisTimeoutError, BrowserObservationError, } from "../domain/errors.js";
+const CONNECT_TIMEOUT_MS = 5_000;
+const COMMAND_TIMEOUT_MS = 5_000;
+const MAX_PAYLOAD_BYTES = 16 * 1_024 * 1_024;
+const MAX_PENDING_COMMANDS = 128;
+/** Correlated, bounded JSON-RPC transport for one CDP target operation. */
+export class CdpConnection {
+    socket;
+    operation;
+    #pending = new Map();
+    #listeners = new Set();
+    #disconnectListeners = new Set();
+    #nextId = 1;
+    #closed = false;
+    #protocolFailed = false;
+    constructor(socket, operation) {
+        this.socket = socket;
+        this.operation = operation;
+        socket.on("message", (data) => this.#receive(data));
+        socket.on("close", () => this.#disconnect());
+        socket.on("error", () => this.#disconnect());
+    }
+    /** Connect to one already-validated loopback CDP WebSocket. */
+    static async connect(url, operation, signal) {
+        if (signal?.aborted === true)
+            throw new AnalysisCancelledError(operation);
+        const socket = new WebSocket(url, {
+            handshakeTimeout: CONNECT_TIMEOUT_MS,
+            maxPayload: MAX_PAYLOAD_BYTES,
+            perMessageDeflate: false,
+        });
+        await waitForOpen(socket, operation, signal);
+        return new CdpConnection(socket, operation);
+    }
+    /** Subscribe to validated CDP event envelopes. */
+    onEvent(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    /** Subscribe to an unexpected transport loss while an operation is active. */
+    onDisconnect(listener) {
+        if (this.#closed) {
+            listener();
+            return () => undefined;
+        }
+        this.#disconnectListeners.add(listener);
+        return () => this.#disconnectListeners.delete(listener);
+    }
+    /** Execute one bounded 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");
+        if (this.#pending.size >= MAX_PENDING_COMMANDS)
+            throw new BrowserObservationError(this.operation, "payload_limit");
+        if (signal?.aborted === true)
+            throw new AnalysisCancelledError(this.operation);
+        const id = this.#nextId;
+        this.#nextId += 1;
+        return await new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const pending = this.#pending.get(id);
+                if (pending === undefined)
+                    return;
+                clearTimeout(pending.timer);
+                pending.removeAbort();
+                this.#pending.delete(id);
+                reject(new AnalysisCancelledError(this.operation));
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                this.#pending.delete(id);
+                reject(new AnalysisTimeoutError(this.operation, COMMAND_TIMEOUT_MS));
+            }, COMMAND_TIMEOUT_MS);
+            this.#pending.set(id, {
+                resolve,
+                reject,
+                timer,
+                removeAbort: () => signal?.removeEventListener("abort", onAbort),
+            });
+            this.socket.send(JSON.stringify({
+                id,
+                method,
+                params,
+                ...(sessionId === undefined ? {} : { sessionId }),
+            }), (error) => {
+                if (error === undefined || error === null)
+                    return;
+                const pending = this.#pending.get(id);
+                if (pending === undefined)
+                    return;
+                this.#complete(id, pending);
+                reject(new BrowserObservationError(this.operation, "disconnected", {
+                    cause: error,
+                }));
+            });
+        });
+    }
+    /** Close only REA's socket; never close the browser or selected page. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#failPending("disconnected");
+        if (this.socket.readyState === WebSocket.CLOSED)
+            return;
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.socket.terminate();
+                resolve();
+            }, 1_000);
+            this.socket.once("close", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            this.socket.close();
+        });
+    }
+    #receive(data) {
+        let message;
+        try {
+            message = JSON.parse(rawText(data));
+        }
+        catch {
+            this.#failPending("protocol_error");
+            return;
+        }
+        if (!isRecord(message)) {
+            this.#failPending("protocol_error");
+            return;
+        }
+        if ("id" in message) {
+            if (typeof message.id !== "number" ||
+                !Number.isSafeInteger(message.id) ||
+                message.id < 1) {
+                this.#failPending("protocol_error");
+                return;
+            }
+            this.#receiveResponse(message, message.id);
+            return;
+        }
+        if (typeof message.method !== "string" ||
+            message.method.length === 0 ||
+            ("params" in message && !isRecord(message.params)) ||
+            ("sessionId" in message && typeof message.sessionId !== "string")) {
+            this.#failPending("protocol_error");
+            return;
+        }
+        const event = {
+            method: message.method,
+            params: "params" in message ? message.params : {},
+            ...(typeof message.sessionId === "string"
+                ? { sessionId: message.sessionId }
+                : {}),
+        };
+        for (const listener of this.#listeners)
+            listener(event);
+    }
+    #receiveResponse(message, id) {
+        const pending = this.#pending.get(id);
+        if (pending === undefined)
+            return;
+        this.#complete(id, pending);
+        if ("error" in message) {
+            pending.reject(new BrowserObservationError(this.operation, "protocol_error"));
+            return;
+        }
+        pending.resolve("result" in message ? message.result : {});
+    }
+    #complete(id, pending) {
+        clearTimeout(pending.timer);
+        pending.removeAbort();
+        this.#pending.delete(id);
+    }
+    #failPending(reason) {
+        if (reason === "disconnected")
+            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));
+        }
+    }
+    #disconnect() {
+        const wasClosed = this.#closed;
+        this.#failPending("disconnected");
+        if (wasClosed)
+            return;
+        for (const listener of this.#disconnectListeners)
+            listener();
+        this.#disconnectListeners.clear();
+    }
+}
+const rawText = (data) => Array.isArray(data)
+    ? Buffer.concat(data).toString("utf8")
+    : Buffer.isBuffer(data)
+        ? data.toString("utf8")
+        : Buffer.from(data).toString("utf8");
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const waitForOpen = async (socket, operation, signal) => await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+        cleanup();
+        terminateSocket(socket);
+        reject(new AnalysisTimeoutError(operation, CONNECT_TIMEOUT_MS));
+    }, CONNECT_TIMEOUT_MS);
+    const onOpen = () => {
+        cleanup();
+        resolve();
+    };
+    const onFailure = (cause) => {
+        cleanup();
+        reject(signal?.aborted === true
+            ? new AnalysisCancelledError(operation)
+            : new BrowserObservationError(operation, "endpoint_unreachable", {
+                cause,
+            }));
+    };
+    const onAbort = () => {
+        terminateSocket(socket);
+        onFailure(new AnalysisCancelledError(operation));
+    };
+    const cleanup = () => {
+        clearTimeout(timer);
+        socket.off("open", onOpen);
+        socket.off("error", onFailure);
+        signal?.removeEventListener("abort", onAbort);
+    };
+    socket.once("open", onOpen);
+    socket.once("error", onFailure);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted === true)
+        onAbort();
+});
+const terminateSocket = (socket) => {
+    socket.once("error", () => undefined);
+    socket.terminate();
+};

package/dist/browser/CdpElectronInspection.js

@@ -0,0 +1,330 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { BrowserObservationError } from "../domain/errors.js";
+import { createWebTextArtifact } from "../domain/webContentArtifact.js";
+import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
+import { boundedText, delayWithCancellation, numberValue, recordValue, recordsValue, requiredRecord, stringValue, } from "./CdpCaptureValues.js";
+import { authorizedElectronFile, canonicalElectronRoots, } from "./ElectronFileScope.js";
+/** Passively inspect one root-confined Electron file page. */
+export const inspectCdpElectronPage = async (context) => {
+    const roots = await canonicalElectronRoots(context.input.allowed_file_roots);
+    const completeness = new CdpCaptureCompleteness();
+    const scripts = [];
+    let mainFrameId;
+    let navigationDuringCapture = false;
+    const removeListener = context.connection.onEvent((event) => {
+        if (event.sessionId !== context.sessionId)
+            return;
+        ingestScript(event, scripts, completeness);
+        if (mainFrameId !== undefined && navigatedFrameId(event) === mainFrameId)
+            navigationDuringCapture = true;
+    });
+    const startedAt = new Date().toISOString();
+    try {
+        await report(context.progress, 1, "Authorizing Electron file frames");
+        await context.connection.send("Page.enable", {}, context.sessionId, context.signal);
+        const before = await context.connection.send("Page.getFrameTree", {}, context.sessionId, context.signal);
+        const frames = await captureFrames(before, roots, context.input.limits.max_frames, completeness);
+        const main = frames[0];
+        if (main === undefined)
+            throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+        mainFrameId = main.frame_id;
+        await context.connection.send("Debugger.enable", { maxScriptsCacheSize: 4 * 1_024 * 1_024 }, context.sessionId, context.signal);
+        await delayWithCancellation(context.input.observation_ms, "inspect_electron_page", context.signal);
+        await report(context.progress, 2, "Capturing Electron structure");
+        const resources = await captureResources(context, roots, completeness);
+        const dom = await captureDom(context, roots, completeness);
+        const normalizedScripts = await captureScripts(context, roots, scripts, completeness);
+        const after = await context.connection.send("Page.getFrameTree", {}, context.sessionId, context.signal);
+        const afterMain = await mainFilePath(after, roots);
+        if (afterMain === undefined)
+            throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+        if (navigationDuringCapture || afterMain !== main.file_path)
+            throw new BrowserObservationError("inspect_web_page", "target_changed");
+        await report(context.progress, 3, "Electron inspection complete");
+        return {
+            schema_version: 1,
+            browser: context.discovery.version,
+            target: {
+                target_id: context.target.id,
+                type: context.target.type,
+                title: context.target.title.slice(0, 16_384),
+                file_path: main.file_path,
+                attached: context.target.attached,
+            },
+            capture_window: {
+                started_at: startedAt,
+                ended_at: new Date().toISOString(),
+                observation_ms: context.input.observation_ms,
+            },
+            completeness: completeness.snapshot(),
+            frames,
+            dom,
+            scripts: normalizedScripts,
+            resources,
+            limitations: [
+                "Only canonical file paths contained by an approved root are retained.",
+                "REA does not evaluate renderer JavaScript, invoke Electron APIs, navigate, click, or close the page.",
+                "Script contents require separate source-capture approval and remain byte bounded.",
+            ],
+        };
+    }
+    finally {
+        removeListener();
+    }
+};
+const navigatedFrameId = (event) => {
+    const params = recordValue(event.params);
+    if (params === undefined)
+        return undefined;
+    if (event.method === "Page.frameNavigated")
+        return stringValue(recordValue(params.frame)?.id);
+    if (event.method === "Page.navigatedWithinDocument")
+        return stringValue(params.frameId);
+    return undefined;
+};
+const ingestScript = (event, scripts, completeness) => {
+    if (event.method !== "Debugger.scriptParsed")
+        return;
+    const value = recordValue(event.params);
+    const scriptId = stringValue(value?.scriptId);
+    const rawUrl = stringValue(value?.url);
+    if (scriptId === undefined || scriptId.length > 256) {
+        completeness.exclude("scripts", "invalid_protocol_value");
+        return;
+    }
+    if (rawUrl === undefined || rawUrl === "") {
+        completeness.exclude("scripts", "unattributed_origin");
+        return;
+    }
+    if (scripts.length >= 2_000) {
+        completeness.drop("scripts");
+        return;
+    }
+    scripts.push({
+        scriptId,
+        rawUrl,
+        hash: (stringValue(value?.hash) ?? "").slice(0, 512),
+        length: nonnegativeInteger(value?.length),
+        isModule: value?.isModule === true,
+        language: boundedText(value?.scriptLanguage, 100),
+    });
+};
+const captureFrames = async (result, roots, maximum, completeness) => {
+    const frameTree = recordValue(requiredRecord(result).frameTree);
+    if (frameTree === undefined)
+        throw new BrowserObservationError("inspect_web_page", "protocol_error");
+    const pending = [{ tree: frameTree, parent: null }];
+    const frames = [];
+    while (pending.length > 0) {
+        const current = pending.shift();
+        if (current === undefined)
+            break;
+        const frame = recordValue(current.tree.frame);
+        const frameId = stringValue(frame?.id);
+        const path = await authorizedElectronFile(stringValue(frame?.url) ?? "", roots);
+        if (frameId === undefined || path === undefined) {
+            completeness.exclude("frames", "out_of_target_scope");
+            continue;
+        }
+        if (frames.length >= maximum) {
+            completeness.truncate("frames");
+            continue;
+        }
+        frames.push({
+            frame_id: frameId.slice(0, 256),
+            parent_frame_id: current.parent,
+            file_path: path,
+        });
+        for (const child of recordsValue(current.tree.childFrames))
+            pending.push({ tree: child, parent: frameId.slice(0, 256) });
+    }
+    return frames;
+};
+const captureResources = async (context, roots, completeness) => {
+    const result = await context.connection.send("Page.getResourceTree", {}, context.sessionId, context.signal);
+    const root = recordValue(requiredRecord(result).frameTree);
+    if (root === undefined)
+        throw new BrowserObservationError("inspect_web_page", "protocol_error");
+    const pending = [root];
+    const resources = [];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const tree = pending.shift();
+        if (tree === undefined)
+            break;
+        for (const resource of recordsValue(tree.resources)) {
+            const path = await authorizedElectronFile(stringValue(resource.url) ?? "", roots);
+            if (path === undefined) {
+                completeness.exclude("resources", "out_of_target_scope");
+                continue;
+            }
+            const item = {
+                file_path: path,
+                type: (stringValue(resource.type) ?? "Other").slice(0, 100),
+                mime_type: (stringValue(resource.mimeType) ?? "").slice(0, 256),
+                content_size: numberValue(resource.contentSize) === undefined
+                    ? null
+                    : Math.max(0, numberValue(resource.contentSize) ?? 0),
+            };
+            const resourceKey = `electron_resource_${digest(item)}`;
+            if (seen.has(resourceKey))
+                continue;
+            seen.add(resourceKey);
+            if (resources.length >= context.input.limits.max_resources) {
+                completeness.truncate("resources");
+                continue;
+            }
+            resources.push({
+                resource_key: resourceKey,
+                ...item,
+            });
+        }
+        pending.push(...recordsValue(tree.childFrames));
+    }
+    return resources.sort((left, right) => left.resource_key.localeCompare(right.resource_key));
+};
+const captureDom = async (context, roots, completeness) => {
+    const result = requiredRecord(await context.connection.send("DOMSnapshot.captureSnapshot", { computedStyles: [], includePaintOrder: false, includeDOMRects: false }, context.sessionId, context.signal));
+    const strings = Array.isArray(result.strings)
+        ? result.strings.map((value) => (typeof value === "string" ? value : ""))
+        : [];
+    const nodes = [];
+    let total = 0;
+    for (const document of recordsValue(result.documents)) {
+        const documentUrl = stringAt(strings, document.documentURL);
+        if ((await authorizedElectronFile(documentUrl, roots)) === undefined) {
+            completeness.exclude("dom", "out_of_target_scope");
+            continue;
+        }
+        const nodeData = recordValue(document.nodes);
+        const nodeTypes = arrayValue(nodeData?.nodeType);
+        const nodeNames = arrayValue(nodeData?.nodeName);
+        const nodeValues = arrayValue(nodeData?.nodeValue);
+        const parents = arrayValue(nodeData?.parentIndex);
+        const attributes = arrayValue(nodeData?.attributes);
+        const baseIndex = nodes.length;
+        total += nodeTypes.length;
+        for (let index = 0; index < nodeTypes.length; index += 1) {
+            if (nodes.length >= context.input.limits.max_dom_nodes)
+                continue;
+            const attributeIndexes = arrayValue(attributes[index]);
+            const parent = integer(parents[index], -1);
+            nodes.push({
+                index: nodes.length,
+                parent_index: parent < 0 ? -1 : baseIndex + parent,
+                node_type: integer(nodeTypes[index], 0),
+                node_name: stringAt(strings, nodeNames[index]).slice(0, 1_024),
+                node_value_length: Buffer.byteLength(stringAt(strings, nodeValues[index])),
+                attribute_names: attributeIndexes
+                    .filter((_value, attributeIndex) => attributeIndex % 2 === 0)
+                    .map((value) => stringAt(strings, value).slice(0, 1_024))
+                    .slice(0, 256),
+            });
+        }
+    }
+    if (total > nodes.length)
+        completeness.truncate("dom");
+    return { total_nodes: total, nodes };
+};
+const captureScripts = async (context, roots, scripts, completeness) => {
+    let total = 0;
+    let sourceBytes = 0;
+    const items = [];
+    const seen = new Set();
+    for (const script of scripts) {
+        const path = await authorizedElectronFile(script.rawUrl, roots);
+        if (path === undefined) {
+            completeness.exclude("scripts", "out_of_target_scope");
+            continue;
+        }
+        const identity = {
+            file_path: path,
+            cdp_hash: script.hash,
+            length: script.length,
+            is_module: script.isModule,
+            language: script.language,
+        };
+        const scriptKey = `electron_script_${digest(identity)}`;
+        if (seen.has(scriptKey))
+            continue;
+        seen.add(scriptKey);
+        total += 1;
+        if (items.length >= context.input.limits.max_scripts) {
+            completeness.drop("scripts");
+            continue;
+        }
+        let source = {
+            included: false,
+            reason: "source capture was not approved",
+        };
+        if (context.input.include_script_sources) {
+            if (script.length > context.input.limits.max_script_source_bytes ||
+                sourceBytes + script.length >
+                    context.input.limits.max_total_script_source_bytes) {
+                source = {
+                    included: false,
+                    reason: "script source byte limit reached",
+                };
+                completeness.truncate("script_sources");
+            }
+            else {
+                const result = requiredRecord(await context.connection.send("Debugger.getScriptSource", { scriptId: script.scriptId }, context.sessionId, context.signal));
+                const text = stringValue(result.scriptSource) ?? "";
+                const bytes = Buffer.byteLength(text);
+                if (bytes > context.input.limits.max_script_source_bytes ||
+                    sourceBytes + bytes >
+                        context.input.limits.max_total_script_source_bytes) {
+                    source = {
+                        included: false,
+                        reason: "script source byte limit reached",
+                    };
+                    completeness.truncate("script_sources");
+                }
+                else {
+                    source = {
+                        included: true,
+                        artifact: createWebTextArtifact(text, "text/javascript"),
+                    };
+                    sourceBytes += bytes;
+                }
+            }
+        }
+        items.push({
+            script_key: scriptKey,
+            ...identity,
+            source,
+        });
+    }
+    if (!context.input.include_script_sources)
+        completeness.exclude("script_sources", "not_approved", total);
+    return {
+        total,
+        items: items.sort((left, right) => left.script_key.localeCompare(right.script_key)),
+    };
+};
+const mainFilePath = async (result, roots) => {
+    const frameTree = recordValue(requiredRecord(result).frameTree);
+    const frame = recordValue(frameTree?.frame);
+    return await authorizedElectronFile(stringValue(frame?.url) ?? "", roots);
+};
+const arrayValue = (value) => Array.isArray(value) ? value : [];
+const stringAt = (strings, value) => strings[integer(value, -1)] ?? "";
+const integer = (value, fallback) => {
+    const number = numberValue(value);
+    return number === undefined ? fallback : Math.trunc(number);
+};
+const nonnegativeInteger = (value) => Math.max(0, integer(value, 0));
+const digest = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Expected canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const report = async (progress, completed, message) => await progress?.report({
+    phase: "browser_observation",
+    completed,
+    total: 3,
+    message,
+    ...(completed === 3 ? { terminal: true } : {}),
+});