rea-agents 6.3.0 → 6.4.0

package/dist/browser/CdpWebMcpDiscovery.js

@@ -223,24 +223,29 @@ const assertStableAuthorizedFrame = async (context, initialUrl, origins) => {
 };
 const ingestWebMcpEvent = (options) => {
     const { event, input, frames, tools, completeness, transientFrames, resolvedTransientFrames, } = options;
+    if (event.method !== "WebMCP.toolsAdded" &&
+        event.method !== "WebMCP.toolsRemoved")
+        return;
     const params = recordValue(event.params);
-    if (params === undefined)
+    if (params === undefined) {
+        completeness.exclude("webmcp_tools", "invalid_protocol_value");
         return;
+    }
     if (event.method === "WebMCP.toolsRemoved") {
-        for (const removed of recordsValue(params.tools)) {
+        for (const removed of webMcpEventTools(params.tools, completeness)) {
             const name = cdpStringValue(removed.name);
             const frameId = cdpStringValue(removed.frameId);
-            if (name === undefined || frameId === undefined)
+            if (name === undefined || frameId === undefined) {
+                completeness.exclude("webmcp_tools", "invalid_protocol_value");
                 continue;
+            }
             for (const [key, tool] of tools)
                 if (tool.name === name && tool.frame_id === frameId)
                     tools.delete(key);
         }
         return;
     }
-    if (event.method !== "WebMCP.toolsAdded")
-        return;
-    for (const declared of recordsValue(params.tools)) {
+    for (const declared of webMcpEventTools(params.tools, completeness)) {
         const frameId = cdpStringValue(declared.frameId);
         if (frameId !== undefined && transientFrames.has(frameId)) {
             if (!resolvedTransientFrames.has(frameId))
@@ -254,14 +259,31 @@ const ingestWebMcpEvent = (options) => {
         tools.set(normalized.tool_key, normalized);
     }
 };
+const webMcpEventTools = (value, completeness) => {
+    if (!Array.isArray(value)) {
+        completeness.exclude("webmcp_tools", "invalid_protocol_value");
+        return [];
+    }
+    const records = [];
+    for (const item of value) {
+        const record = recordValue(item);
+        if (record === undefined) {
+            completeness.exclude("webmcp_tools", "invalid_protocol_value");
+            continue;
+        }
+        records.push(record);
+    }
+    return records;
+};
 const normalizeTool = (value, input, frames, completeness) => {
     const frameId = cdpStringValue(value.frameId);
     const name = cdpStringValue(value.name);
     const frame = frameId === undefined ? undefined : frames.get(frameId);
-    if (frameId === undefined ||
-        name === undefined ||
-        frame?.origin === null ||
-        frame === undefined) {
+    if (frameId === undefined || name === undefined) {
+        completeness.exclude("webmcp_tools", "invalid_protocol_value");
+        return undefined;
+    }
+    if (frame?.origin === null || frame === undefined) {
         completeness.exclude("webmcp_tools", "out_of_target_scope");
         return undefined;
     }

package/dist/browser/ElectronFileScope.js

@@ -1,6 +1,7 @@
-import { realpath, stat } from "node:fs/promises";
-import { isAbsolute } from "node:path";
+import { open, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { admitAsarHeader, MAX_ASAR_HEADER_BYTES, } from "../artifacts/AsarHeader.js";
 /** Resolve one local file URL while rejecting remote hosts and encoded separators. */
 export const authorizedElectronFile = async (value) => {
     if (/%(?:2f|5c)/iu.test(value))
@@ -30,16 +31,105 @@ export const authorizedElectronFile = async (value) => {
     }
     if (!isAbsolute(path) || path.includes("\0"))
         return undefined;
-    let canonical;
     try {
-        if (!(await stat(path)).isFile())
-            return undefined;
-        canonical = await realpath(path);
+        if ((await stat(path)).isFile())
+            return await realpath(path);
     }
     catch (cause) {
-        // Missing or unreadable files cannot authorize a local file.
+        // Electron serves packaged pages from inside app.asar, which the host
+        // filesystem cannot stat; resolve those through the archive header below.
         void cause;
-        return undefined;
     }
-    return canonical;
+    return await authorizedAsarMember(path);
+};
+/**
+ * Resolve `<archive>.asar/<member>` the way Electron's file protocol does: the
+ * first `.asar` path component that is a regular file is the archive, and the
+ * remainder must name a regular file in its header (packed or unpacked).
+ */
+const authorizedAsarMember = async (path) => {
+    const segments = path.split(sep);
+    for (let index = 1; index < segments.length - 1; index += 1) {
+        if (!(segments[index] ?? "").toLowerCase().endsWith(".asar"))
+            continue;
+        const archive = segments.slice(0, index + 1).join(sep);
+        const member = segments.slice(index + 1);
+        if (member.some((part) => part === "" || part === "." || part === ".."))
+            return undefined;
+        try {
+            const metadata = await stat(archive);
+            if (!metadata.isFile())
+                continue;
+            const canonical = await realpath(archive);
+            const files = await asarFiles(canonical, metadata);
+            return isAsarRegularFile(files, member)
+                ? join(canonical, ...member)
+                : undefined;
+        }
+        catch (cause) {
+            // An unreadable or malformed archive cannot authorize its members.
+            void cause;
+            return undefined;
+        }
+    }
+    return undefined;
+};
+// This is a retained-memory budget for JSON headers, shared across all archives.
+const MAX_CACHED_HEADERS = 8;
+const headerCache = new Map();
+const archiveIdentity = (metadata) => `${String(metadata.dev)}:${String(metadata.ino)}:${String(metadata.size)}:${String(metadata.mtimeMs)}`;
+/** Read the two Chromium pickle headers on one handle before allocating JSON. */
+const asarFiles = async (archive, metadata) => {
+    const identity = archiveIdentity(metadata);
+    const cached = headerCache.get(archive);
+    if (cached?.identity === identity)
+        return cached.files;
+    const handle = await open(archive, "r");
+    let files;
+    let jsonBytes;
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || archiveIdentity(opened) !== identity)
+            throw new Error("ASAR identity changed before header read");
+        const admitted = await admitAsarHeader(handle);
+        jsonBytes = admitted.jsonBytes;
+        const json = Buffer.alloc(jsonBytes);
+        let offset = 0;
+        while (offset < json.length) {
+            const part = await handle.read(json, offset, json.length - offset, 16 + offset);
+            if (part.bytesRead === 0)
+                throw new Error("Truncated ASAR JSON header");
+            offset += part.bytesRead;
+        }
+        if (archiveIdentity(await handle.stat()) !== identity)
+            throw new Error("ASAR identity changed during header read");
+        const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(json));
+        if (!isRecord(parsed) || !isRecord(parsed.files))
+            throw new Error("ASAR header has no file tree");
+        files = parsed.files;
+    }
+    finally {
+        await handle.close();
+    }
+    headerCache.delete(archive);
+    headerCache.set(archive, { identity, files, bytes: jsonBytes });
+    const retainedBytes = () => [...headerCache.values()].reduce((sum, entry) => sum + entry.bytes, 0);
+    while (headerCache.size > MAX_CACHED_HEADERS ||
+        retainedBytes() > MAX_ASAR_HEADER_BYTES)
+        headerCache.delete(headerCache.keys().next().value ?? archive);
+    return files;
+};
+const isAsarRegularFile = (files, member) => {
+    let node = { files };
+    for (const part of member) {
+        const children = isRecord(node) ? node.files : undefined;
+        if (!isRecord(children) || !Object.hasOwn(children, part))
+            return false;
+        node = children[part];
+    }
+    return (isRecord(node) &&
+        typeof node.size === "number" &&
+        !("files" in node) &&
+        !("link" in node));
 };
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/browser/PlaywrightBrowserScenarioProvider.js

@@ -135,11 +135,14 @@ const globalCompleteness = (scenario, session, steps) => {
         missing.push("events");
     return classifyBrowserScenarioCompleteness(missing, truncated);
 };
-const runScenario = async (openSession, scenario, options) => {
+const runScenario = async (openSession, scenario, options, retainCleanup) => {
     if (options.signal?.aborted === true)
         throw new BrowserObservationError(OPERATION, "cancelled");
     const startedAt = Date.now();
-    const session = await openSession(scenario, options.signal === undefined ? {} : { signal: options.signal });
+    const session = await openSession(scenario, {
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        retainCleanup,
+    });
     const steps = [];
     let operationOutcome = { ok: true };
     try {
@@ -172,6 +175,7 @@ const runScenario = async (openSession, scenario, options) => {
     }
     catch (cause) {
         cleanupOutcome = { ok: false, cause };
+        retainCleanup(() => session.close());
     }
     if (!cleanupOutcome.ok) {
         const cleanup = browserScenarioCleanupObservation(cleanupOutcome.cause);
@@ -226,15 +230,33 @@ const runScenario = async (openSession, scenario, options) => {
 /** Controlled Playwright/CDP scenario driver with exact process ownership. */
 export class PlaywrightBrowserScenarioProvider {
     openSession;
+    #tail = Promise.resolve();
+    #closing = false;
+    #closePromise;
+    #pendingCleanup = new Set();
     constructor(openSession) {
         this.openSession = openSession;
     }
     identity() {
         return PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY;
     }
-    async captureScenario(scenario, options = {}) {
+    captureScenario(scenario, options = {}) {
+        if (this.#closing)
+            return Promise.resolve(err(this.#closedError()));
+        const operation = this.#tail.then(() => this.#closing
+            ? err(this.#closedError())
+            : this.#captureScenario(scenario, options));
+        this.#tail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async #captureScenario(scenario, options) {
+        const pending = await this.#retryCleanup();
+        if (pending !== undefined)
+            return err(pending);
         try {
-            return ok(await runScenario(this.openSession, scenario, options));
+            return ok(await runScenario(this.openSession, scenario, options, (close) => {
+                this.#pendingCleanup.add(close);
+            }));
         }
         catch (cause) {
             if (cause instanceof AnalysisError)
@@ -242,4 +264,38 @@ export class PlaywrightBrowserScenarioProvider {
             return err(new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause }));
         }
     }
+    async close() {
+        this.#closing = true;
+        this.#closePromise ??= this.#tail
+            .then(async () => {
+            const failure = await this.#retryCleanup();
+            if (failure !== undefined)
+                throw failure;
+        })
+            .catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
+    }
+    #closedError() {
+        return new BrowserObservationError(OPERATION, "cleanup_failed", {
+            detail: "Browser scenario provider is closing.",
+            cleanup: { reason: "Provider is closing", resources: [] },
+        });
+    }
+    async #retryCleanup() {
+        for (const pending of this.#pendingCleanup) {
+            try {
+                await pending();
+                this.#pendingCleanup.delete(pending);
+            }
+            catch (cause) {
+                return cause instanceof AnalysisError
+                    ? cause
+                    : new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause });
+            }
+        }
+        return undefined;
+    }
 }

package/dist/browser/PlaywrightElectronActiveProvider.js

@@ -181,18 +181,23 @@ export class PlaywrightElectronActiveProvider {
         return outcome;
     }
 }
-const cleanupElectronProcesses = async (ownership, lineage) => {
-    if (process.platform === "win32") {
-        const root = await cleanupWindowsProcessTree(ownership.leaderPid);
-        if (!root.cleaned)
-            return root;
+/** Clean up an Electron launch. Windows signals a process only after lineage is verified. */
+export const cleanupElectronProcesses = async (ownership, lineage, host = {
+    platform: process.platform,
+    terminateTree: cleanupWindowsProcessTree,
+}) => {
+    if (host.platform === "win32") {
+        // An empty Windows process table is not ownership proof for this PID.
         if (lineage?.status !== "verified")
             return {
                 cleaned: false,
                 reason: "owned Electron lineage was unavailable; helper cleanup was not proven",
             };
+        const root = await host.terminateTree(ownership.leaderPid);
+        if (!root.cleaned)
+            return root;
         for (const descendant of lineage.lineage.descendants) {
-            const result = await cleanupWindowsProcessTree(descendant.pid);
+            const result = await host.terminateTree(descendant.pid);
             if (!result.cleaned)
                 return result;
         }

package/dist/browser/PlaywrightScenarioArtifacts.js

@@ -120,20 +120,20 @@ const captureStorage = async (input) => {
       }))()`));
         const value = {
             cookies: cookies.map((cookie) => ({
-                name: cookie.name,
-                domain: cookie.domain,
-                path: cookie.path,
+                name: secrets.redact(cookie.name),
+                domain: secrets.redact(cookie.domain),
+                path: secrets.redact(cookie.path),
                 secure: cookie.secure,
                 http_only: cookie.httpOnly,
                 same_site: cookie.sameSite,
                 ...secrets.fingerprint(cookie.value),
             })),
             local_storage: pageStorage.local_storage.map(([name, value]) => ({
-                name,
+                name: secrets.redact(name),
                 ...secrets.fingerprint(value),
             })),
             session_storage: pageStorage.session_storage.map(([name, value]) => ({
-                name,
+                name: secrets.redact(name),
                 ...secrets.fingerprint(value),
             })),
         };

package/dist/browser/PlaywrightScenarioBrowser.js

@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { chromium, } from "playwright-core";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { isLiteralLoopbackHostname } from "../domain/browserObservation.js";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
 const OPERATION = "capture_browser_scenario";
@@ -22,6 +23,9 @@ export class PlaywrightScenarioBrowserCleanupOwner {
         this.resources = resources;
         this.#profileRemoved = resources.removeProfile === undefined;
     }
+    get browserClosed() {
+        return this.#browserClosed;
+    }
     close(finishEvents, signal) {
         const cleanup = this.#closePromise ?? this.#closeResources(finishEvents);
         if (this.#closePromise === undefined) {
@@ -63,6 +67,9 @@ export class PlaywrightScenarioBrowserCleanupOwner {
             await eventFinalization;
         }
         catch (cause) {
+            // A failed finalization stays failed: the memoized attempt rejects on
+            // every retry so cleanup can never report success for unfinalized
+            // events.
             failures.push(cause);
         }
         if (!this.#browserClosed) {
@@ -119,10 +126,19 @@ const createAttachedScenarioRelease = (key, admission) => {
         releaseAttachedScenario(key, admission);
     };
 };
+/** One browser admission. The key is the discovery URL this endpoint already parses. */
+export const attachedScenarioLeaseKey = (endpoint, targetId) => {
+    const discovery = new URL("/json/version", endpoint);
+    // One CDP browser serves every loopback stack on one port, so spellings that
+    // reach it through 127.0.0.1 or ::1 must share a single admission.
+    if (isLiteralLoopbackHostname(discovery.hostname))
+        discovery.hostname = "127.0.0.1";
+    return JSON.stringify([discovery.href, targetId]);
+};
 const acquireAttachedScenario = (scenario, signal) => {
     if (signal?.aborted === true)
         return Promise.reject(new BrowserObservationError(OPERATION, "cancelled"));
-    const key = JSON.stringify([scenario.cdp_endpoint, scenario.target_id]);
+    const key = attachedScenarioLeaseKey(scenario.cdp_endpoint, scenario.target_id);
     const admission = attachedScenarioAdmissions.get(key) ??
         {
             active: false,
@@ -180,9 +196,23 @@ const allowedBrowserEnvironment = (environment) => {
         "XAUTHORITY",
         "XDG_RUNTIME_DIR",
     ];
-    return Object.fromEntries(allowed
+    const selected = Object.fromEntries(allowed
         .map((name) => [name, environment[name]])
         .filter((entry) => entry[1] !== undefined));
+    if (process.platform !== "android")
+        return selected;
+    // Android rejects execve() for binaries below Termux's application data
+    // directory. Termux supplies an exec interceptor that rewrites those calls
+    // through the system linker and removes itself for the launched program.
+    // Playwright must retain it for its Chromium child process.
+    const prefix = environment.PREFIX;
+    if (prefix === undefined)
+        return selected;
+    return {
+        ...selected,
+        LD_PRELOAD: `${prefix}/lib/libtermux-exec.so`,
+        TERMUX_EXEC__PROC_SELF_EXE: process.execPath,
+    };
 };
 const findConnectedPage = async (browser, targetId, signal) => {
     for (const context of browser.contexts())
@@ -254,7 +284,7 @@ export const failBrowserScenarioOperation = async (cleanup, primaryFailure, fall
     }
     throw primaryFailure;
 };
-const openAttachedScenarioBrowser = async (browserRequest, environment, launcher, signal) => {
+const openAttachedScenarioBrowser = async (browserRequest, environment, launcher, signal, retainCleanup) => {
     const lease = await acquireAttachedScenario(browserRequest, signal);
     let cleanupOwner;
     try {
@@ -291,14 +321,22 @@ const openAttachedScenarioBrowser = async (browserRequest, environment, launcher
             throw cause;
         }
         const cleanup = cleanupOwner;
-        return failBrowserScenarioOperation(() => cleanup.close(), cause);
+        const close = () => cleanup.close();
+        try {
+            return await failBrowserScenarioOperation(close, cause);
+        }
+        catch (failure) {
+            if (failure !== cause)
+                retainCleanup?.(close);
+            throw failure;
+        }
     }
 };
 /** Launch or attach using the caller-selected environment and browser engine. */
 export const openPlaywrightScenarioBrowser = async (scenario, environment, options = {}) => {
     const launcher = options.launcher ?? chromium;
     if (scenario.browser.mode === "connect")
-        return openAttachedScenarioBrowser(scenario.browser, scenario.environment, launcher, options.signal);
+        return openAttachedScenarioBrowser(scenario.browser, scenario.environment, launcher, options.signal, options.retainCleanup);
     const profilePath = await mkdtemp(join(tmpdir(), "rea-browser-scenario-"));
     let context;
     try {
@@ -322,10 +360,26 @@ export const openPlaywrightScenarioBrowser = async (scenario, environment, optio
             handleSIGINT: false,
             handleSIGTERM: false,
             timeout: 0,
+            // Termux's Chromium cannot create its renderer process through Android's
+            // executable boundary. Single-process mode keeps the browser and page in
+            // the Termux-launched process so scenario navigation remains available.
+            args: process.platform === "android"
+                ? ["--no-sandbox", "--single-process"]
+                : [],
         });
     }
     catch (cause) {
-        return failBrowserScenarioOperation(() => rm(profilePath, { recursive: true, force: true, maxRetries: 3 }), cause, ["browser_profile"]);
+        const cleanup = () => rm(profilePath, { recursive: true, force: true, maxRetries: 3 });
+        try {
+            return await failBrowserScenarioOperation(cleanup, cause, [
+                "browser_profile",
+            ]);
+        }
+        catch (failure) {
+            if (failure !== cause)
+                options.retainCleanup?.(cleanup);
+            throw failure;
+        }
     }
     const cleanup = new PlaywrightScenarioBrowserCleanupOwner({
         closeBrowser: () => context.close(),
@@ -345,6 +399,14 @@ export const openPlaywrightScenarioBrowser = async (scenario, environment, optio
         };
     }
     catch (cause) {
-        return failBrowserScenarioOperation(() => cleanup.close(), cause);
+        const close = () => cleanup.close();
+        try {
+            return await failBrowserScenarioOperation(close, cause);
+        }
+        catch (failure) {
+            if (failure !== cause)
+                options.retainCleanup?.(close);
+            throw failure;
+        }
     }
 };