rea-agents 6.1.0 → 6.2.0

package/dist/native/NativeUiHelperRuntime.js

@@ -1,12 +1,15 @@
-import { mkdtemp, rm, symlink } from "node:fs/promises";
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
+import { mkdir, mkdtemp, rm, symlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { SWIFTC_INTERRUPT } from "../process/DarwinProcessRunTokenReader.js";
 import { execFileOutput } from "../process/ExecFileOutput.js";
 import { safeParseJson } from "../domain/safeJson.js";
 import { NATIVE_UI_HELPER_MAX_BUFFER } from "./NativeUiOutputBudget.js";
 /** Lazily compile one owned helper per observation/scenario and remove its compiler cache. */
-export const createNativeUiHelperRuntime = () => {
+export const createNativeUiHelperRuntime = (environment) => {
+    const selectedEnvironment = snapshotEnvironment(environment);
     let root;
     let executable;
     const invoke = async (parameters, signal) => {
@@ -15,6 +18,9 @@ export const createNativeUiHelperRuntime = () => {
             const output = join(root, "observer");
             const main = join(root, "main.swift");
             await symlink(fileURLToPath(new URL("../../bridge/native/ReaNativeUI.swift", import.meta.url)), main);
+            // Keep swiftc's intermediate objects inside the removable root.
+            const compilerTemporary = join(root, "tmp");
+            await mkdir(compilerTemporary);
             await execFileOutput("/usr/bin/xcrun", [
                 "swiftc",
                 "-module-cache-path",
@@ -26,6 +32,8 @@ export const createNativeUiHelperRuntime = () => {
             ], {
                 timeout: 60_000,
                 maxBuffer: 1024 * 1024,
+                stopSignal: SWIFTC_INTERRUPT,
+                env: { ...selectedEnvironment, TMPDIR: compilerTemporary },
                 ...(signal === undefined ? {} : { signal }),
             });
             executable = output;
@@ -33,6 +41,7 @@ export const createNativeUiHelperRuntime = () => {
         const output = await execFileOutput(executable, [JSON.stringify(parameters)], {
             timeout: 30_000,
             maxBuffer: NATIVE_UI_HELPER_MAX_BUFFER,
+            env: selectedEnvironment,
             ...(signal === undefined ? {} : { signal }),
         });
         const parsed = safeParseJson(output.stdout);

package/dist/native/NativeUiObservation.js

@@ -17,8 +17,8 @@ const responseSchema = z.discriminatedUnion("ok", [
     }),
 ]);
 /** Capture a selected existing app window and run explicitly selected scenarios. */
-export const observeNativeUi = async (target, operation, parameters, options = {}) => {
-    const runtime = createNativeUiHelperRuntime();
+export const observeNativeUi = async (target, operation, parameters, options) => {
+    const runtime = createNativeUiHelperRuntime(options.environment);
     try {
         return await observeWithHelper(target, operation, parameters, {
             ...options,

package/dist/native/pwntools/PwntoolsDecoder.js

@@ -16,6 +16,7 @@ import { OwnedCommandFailure } from "../../process/OwnedCommand.js";
 import { pwntoolsResourceLimitsSchema, readPwntoolsFailureEvidence, } from "./PwntoolsResourceLimits.js";
 import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
 import { PWNTOOLS_PROVIDER_IDENTITY, PWNTOOLS_LIMITS, } from "./PwntoolsRelease.js";
+const HOST_REQUIREMENT = "The initial real-verified pwntools artifact profile supports Linux x64 only.";
 /** Thin owned-process adapter; all ELF parsing and heuristics come from unchanged upstream code. */
 export class PwntoolsDecoder {
     profile;
@@ -64,7 +65,7 @@ export class PwntoolsDecoder {
             if (options?.signal?.aborted)
                 throw new AnalysisCancelledError(OPERATION);
             if (process.platform !== "linux" || process.arch !== "x64")
-                throw new AnalysisCapabilityUnavailableError(this.identity.id, OPERATION, "The initial real-verified pwntools artifact profile supports Linux x64 only.");
+                throw new AnalysisCapabilityUnavailableError(this.identity.id, OPERATION, HOST_REQUIREMENT, { userMessage: HOST_REQUIREMENT });
             if (!isAbsolute(selectedPath))
                 throw pwntoolsUnavailable("Set REA_PWNTOOLS_PYTHON to an absolute caller-supplied Python executable with pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2; REA never installs Python or packages.", selectedPath, undefined, undefined, context);
             await access(selectedPath, constants.X_OK);

package/dist/process/DarwinProcessRunTokenReader.js

@@ -1,4 +1,4 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -42,6 +42,12 @@ const sourceFiles = [
     fileURLToPath(new URL("../../bridge/process/ProcessRunTokenReader.swift", import.meta.url)),
     fileURLToPath(new URL("../../bridge/process/ProcessRunTokenReaderMain.swift", import.meta.url)),
 ];
+/**
+ * swift-driver runs each frontend job in its own process group. On SIGINT it
+ * stops those jobs and deletes their objects before exiting; on SIGTERM it
+ * exits while a job can still write objects under TMPDIR.
+ */
+export const SWIFTC_INTERRUPT = "SIGINT";
 /** The native Darwin process-ownership reader could not be prepared. */
 export class DarwinProcessOwnershipInspectionError extends Error {
     constructor(message, options) {
@@ -114,7 +120,14 @@ export const createDarwinProcessRunTokenReader = (options = {}) => {
             if (signal.aborted || closed)
                 throw abortReason(signal);
             const output = join(operationRoot, "reader");
-            const compilerEnvironment = { ...process.env };
+            // swiftc keeps intermediate objects under TMPDIR, so keep them inside
+            // the root that cleanup removes.
+            const compilerTemporary = join(operationRoot, "tmp");
+            await mkdir(compilerTemporary);
+            const compilerEnvironment = {
+                ...process.env,
+                TMPDIR: compilerTemporary,
+            };
             // Use Swift's reusable default cache for REA's internal helper compilation.
             delete compilerEnvironment.CLANG_MODULE_CACHE_PATH;
             try {
@@ -122,6 +135,7 @@ export const createDarwinProcessRunTokenReader = (options = {}) => {
                     timeout: 60_000,
                     maxBuffer: 1024 * 1024,
                     signal,
+                    stopSignal: SWIFTC_INTERRUPT,
                     env: compilerEnvironment,
                 });
             }

package/dist/process/ExecFileOutput.js

@@ -1,4 +1,38 @@
 import { execFile, } from "node:child_process";
+/** How long a stopped process may take to exit before it is killed. */
+const STOP_GRACE_MS = 5_000;
+const abortError = (signal) => {
+    const error = new Error("The operation was aborted", {
+        cause: signal.reason,
+    });
+    error.name = "AbortError";
+    Reflect.set(error, "code", "ABORT_ERR");
+    return error;
+};
+/**
+ * A command stopped at its timeout can still exit cleanly, so the timeout is
+ * the failure. Like Node's execFile timeout, it reports `killed: true`.
+ */
+const timeoutError = (command, timeout, exit) => {
+    const error = new Error(`Command timed out after ${String(timeout)} ms: ${command}`, exit === null ? undefined : { cause: exit });
+    Reflect.set(error, "code", "ETIMEDOUT");
+    Reflect.set(error, "killed", true);
+    Reflect.set(error, "signal", exit === null ? null : (Reflect.get(exit, "signal") ?? null));
+    return error;
+};
+/**
+ * The `timeout` contract for both modes, checked before spawning. A stoppable
+ * command keeps its own deadline, so execFile never validates it. Node 26's
+ * execFile also caps it at Number.MAX_SAFE_INTEGER; Node 22 and 24 accept
+ * larger integers, which their timers then clamp to 1 ms.
+ */
+const invalidTimeout = (timeout) => {
+    if (Number.isSafeInteger(timeout) && timeout >= 0)
+        return undefined;
+    const error = new RangeError(`The value of "timeout" is out of range. It must be an unsigned integer. Received ${String(timeout)}`);
+    Reflect.set(error, "code", "ERR_OUT_OF_RANGE");
+    return error;
+};
 /** Read captured output metadata from a failed execFileOutput invocation. */
 export const execFileOutputFailure = (cause) => {
     if (!(cause instanceof Error))
@@ -21,17 +55,65 @@ export const execFileOutputFailure = (cause) => {
 };
 /** Run a shell-free command while capturing its complete UTF-8 output. */
 export const execFileOutput = (command, arguments_, options = {}) => new Promise((resolve, reject) => {
-    execFile(command, [...arguments_], {
-        ...options,
+    const { stopSignal, signal, timeout, ...execOptions } = options;
+    const invalid = timeout === undefined ? undefined : invalidTimeout(timeout);
+    if (invalid !== undefined) {
+        reject(invalid);
+        return;
+    }
+    if (stopSignal !== undefined && signal?.aborted === true) {
+        reject(abortError(signal));
+        return;
+    }
+    let stopped;
+    let deadline;
+    let grace;
+    const child = execFile(command, [...arguments_], {
+        ...execOptions,
+        // A stoppable command's abort and timeout are handled below, because
+        // execFile neither waits for the exit on abort nor kills a process
+        // that ignores its timeout signal.
+        ...(stopSignal === undefined
+            ? {
+                ...(signal === undefined ? {} : { signal }),
+                ...(timeout === undefined ? {} : { timeout }),
+            }
+            : { killSignal: stopSignal }),
         encoding: "utf8",
         maxBuffer: options.maxBuffer ?? Number.POSITIVE_INFINITY,
     }, (error, stdout, stderr) => {
-        if (error !== null) {
-            Reflect.set(error, "stdout", stdout);
-            Reflect.set(error, "stderr", stderr);
-            reject(error);
+        signal?.removeEventListener("abort", onAbort);
+        clearTimeout(deadline);
+        clearTimeout(grace);
+        const failure = stopped === "abort" && signal !== undefined
+            ? abortError(signal)
+            : stopped === "timeout" && timeout !== undefined
+                ? timeoutError(command, timeout, error)
+                : error;
+        if (failure !== null) {
+            Reflect.set(failure, "stdout", stdout);
+            Reflect.set(failure, "stderr", stderr);
+            reject(failure);
             return;
         }
         resolve({ stdout, stderr });
     });
+    // The first stop request names the failure; a later one is not resent.
+    const stop = (reason) => {
+        if (stopped !== undefined)
+            return;
+        stopped = reason;
+        child.kill(stopSignal);
+        grace = setTimeout(() => child.kill("SIGKILL"), STOP_GRACE_MS);
+    };
+    const onAbort = () => {
+        stop("abort");
+    };
+    if (stopSignal === undefined)
+        return;
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (timeout !== undefined && timeout > 0)
+        deadline = setTimeout(() => {
+            stop("timeout");
+        }, timeout);
 });

package/dist/process/PrivateRuntimeRoot.js

@@ -50,12 +50,17 @@ export class PrivateRuntimeRoot {
             throw cause;
         }
     }
-    /** Remove the runtime root; concurrent and repeated callers share cleanup. */
+    /**
+     * Remove the runtime root; concurrent callers share one attempt. A failed
+     * attempt is not cached, so a later close retries the removal.
+     */
     close() {
-        this.#closePromise ??=
-            this.windowsRuntime === undefined
-                ? rm(this.path, { recursive: true, force: true })
-                : Promise.resolve().then(() => this.windowsRuntime?.close());
+        this.#closePromise ??= (this.windowsRuntime === undefined
+            ? rm(this.path, { recursive: true, force: true })
+            : Promise.resolve().then(() => this.windowsRuntime?.close())).catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
         return this.#closePromise;
     }
 }

package/dist/process/ProcessOwnership.js

@@ -19,12 +19,9 @@ export const cleanupWindowsProcessTree = async (rootPid, host = systemWindowsPro
         return { cleaned: true, signaled: result === "terminated" };
     }
     catch (cause) {
-        // The reason string is a pinned validation contract; keep it stable and
-        // do not interpolate the cause into caller-visible diagnostics here.
-        void cause;
         return {
             cleaned: false,
-            reason: "Windows P0 process-tree termination failed; Job Object ownership is unavailable",
+            reason: `Windows process-tree termination failed for PID ${String(rootPid)}: ${errorMessage(cause)}`,
         };
     }
 };

package/dist/process/ProcessOwnershipObservation.js

@@ -5,30 +5,36 @@ import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
 import { execFileOutput } from "./ExecFileOutput.js";
 import { createDarwinProcessRunTokenReader } from "./DarwinProcessRunTokenReader.js";
 /** Observe one group without signaling it, failing closed on identity doubt. */
-export const observeOwnedProcessGroupWithHost = async (ownership, host) => {
+export const observeOwnedProcessGroupWithHost = async (ownership, host, signal) => {
+    signal?.throwIfAborted();
     let members;
     try {
-        members = (await host.listProcesses()).filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
+        members = (await host.listProcesses(signal)).filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
     }
     catch (cause) {
+        signal?.throwIfAborted();
         return {
             state: "unverifiable",
             reason: `process group could not be inspected: ${errorMessage(cause)}`,
         };
     }
+    signal?.throwIfAborted();
     const liveMembers = liveProcesses(members);
     if (liveMembers.length === 0)
         return { state: "empty" };
     for (const member of liveMembers) {
+        signal?.throwIfAborted();
         try {
-            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
-                ownership.runId)
+            const runId = (await host.environment(member.pid)).REA_PROCESS_RUN_ID;
+            signal?.throwIfAborted();
+            if (runId !== ownership.runId)
                 return {
                     state: "unverifiable",
                     reason: "process ownership did not match",
                 };
         }
         catch (cause) {
+            signal?.throwIfAborted();
             if (!(await processIsGone(host, member.pid))) {
                 return {
                     state: "unverifiable",
@@ -326,7 +332,7 @@ export const prepareProcessOwnershipInspection = async (signal) => {
     await systemProcessOwnershipHost.prepare?.(signal);
 };
 /** Observe one group without signaling it, failing closed on identity doubt. */
-export const observeOwnedProcessGroup = async (ownership, host = systemProcessOwnershipHost) => observeOwnedProcessGroupWithHost(ownership, host);
+export const observeOwnedProcessGroup = async (ownership, host = systemProcessOwnershipHost, signal) => observeOwnedProcessGroupWithHost(ownership, host, signal);
 /**
  * Record the live launcher and descendant lineage after run-token validation.
  *

package/dist/process/ProviderProcess.js

@@ -21,9 +21,7 @@ export const spawnOwnedProviderProcess = async (options) => {
         REA_PROCESS_RUN_ID: options.runId,
     };
     if (platform === "win32" && process.platform === "win32") {
-        if (options.stdin === "pipe")
-            throw new Error("Owned Windows provider processes do not support protocol stdin");
-        const child = new WindowsOwnedProcess(options.command, options.arguments, options.cwd, environment, options.windowsVerbatimArguments ?? false);
+        const child = new WindowsOwnedProcess(options.command, options.arguments, options.cwd, environment, options.windowsVerbatimArguments ?? false, options.stdin === "pipe");
         return {
             process: child,
             ownership: {

package/dist/process/capture/FilesystemSnapshot.js

@@ -59,25 +59,33 @@ export const hashFile = async (path, expected, maxBytes, signal) => {
 /** Capture bounded, root-aliased filesystem state without following symlinks. */
 export const snapshotRoots = async (scenario, signal) => {
     const entries = [];
+    const completeRoots = [];
     let remainingBytes = scenario.limits.file_bytes;
     let truncated = false;
+    const enumerationReasons = new Set();
+    const hashOmissions = [];
     const visit = async (root, rootAlias, path, depth) => {
         signal?.throwIfAborted();
         if (entries.length >= scenario.limits.files ||
             depth > scenario.limits.filesystem_depth) {
             truncated = true;
-            return;
+            if (entries.length >= scenario.limits.files)
+                enumerationReasons.add("files_limit");
+            if (depth > scenario.limits.filesystem_depth)
+                enumerationReasons.add("depth_limit");
+            return false;
         }
         const stats = await lstatIfPresent(path);
         if (stats === undefined)
-            return;
+            return true;
         const relativePath = relative(root, path) || ".";
         if (stats.isSymbolicLink()) {
             const target = resolve(dirname(path), await readlink(path));
             const afterRead = await lstat(path);
             if (!hasSameIdentity(stats, afterRead, "symlink")) {
                 truncated = true;
-                return;
+                enumerationReasons.add("identity_changed");
+                return false;
             }
             entries.push({
                 path: `${rootAlias}:${relativePath}`,
@@ -87,15 +95,24 @@ export const snapshotRoots = async (scenario, signal) => {
                 sha256: null,
                 symlink_target: target,
             });
-            return;
+            return true;
         }
         if (stats.isFile()) {
             const sha256 = remainingBytes >= stats.size
                 ? await hashFile(path, stats, remainingBytes, signal)
                 : null;
             remainingBytes -= sha256 === null ? 0 : stats.size;
-            if (sha256 === null)
+            if (sha256 === null) {
                 truncated = true;
+                hashOmissions.push({
+                    path: `${rootAlias}:${relativePath}`,
+                    size_bytes: stats.size,
+                    remaining_budget_bytes: remainingBytes,
+                    reason: remainingBytes < stats.size
+                        ? "file_bytes_budget"
+                        : "file_changed_or_short_read",
+                });
+            }
             entries.push({
                 path: `${rootAlias}:${relativePath}`,
                 type: "file",
@@ -104,7 +121,7 @@ export const snapshotRoots = async (scenario, signal) => {
                 sha256,
                 symlink_target: null,
             });
-            return;
+            return true;
         }
         const type = stats.isDirectory() ? "directory" : "other";
         entries.push({
@@ -116,22 +133,42 @@ export const snapshotRoots = async (scenario, signal) => {
             symlink_target: null,
         });
         if (type !== "directory")
-            return;
+            return true;
         const children = await readdir(path);
         const afterRead = await lstat(path);
         if (!hasSameIdentity(stats, afterRead, "directory")) {
             truncated = true;
-            return;
+            enumerationReasons.add("identity_changed");
+            return false;
+        }
+        let complete = true;
+        for (const child of children.sort()) {
+            if (!(await visit(root, rootAlias, join(path, child), depth + 1)))
+                complete = false;
         }
-        for (const child of children.sort())
-            await visit(root, rootAlias, join(path, child), depth + 1);
+        return complete;
     };
     for (const [index, root] of scenario.filesystem_observation_paths.entries()) {
+        const alias = `root_${String(index)}`;
         if ((await lstatIfPresent(root)) === undefined) {
-            truncated = true;
+            completeRoots.push(alias);
             continue;
         }
-        await visit(root, `root_${String(index)}`, root, 0);
+        if (await visit(root, alias, root, 0))
+            completeRoots.push(alias);
     }
-    return { files: entries, truncated };
+    return {
+        files: entries,
+        truncated,
+        completeRoots,
+        coverage: {
+            files_limit: scenario.limits.files,
+            depth_limit: scenario.limits.filesystem_depth,
+            enumeration_truncated: completeRoots.length !== scenario.filesystem_observation_paths.length,
+            enumeration_reasons: [...enumerationReasons],
+            hash_budget_bytes: scenario.limits.file_bytes,
+            hashed_bytes: scenario.limits.file_bytes - remainingBytes,
+            hash_omissions: hashOmissions,
+        },
+    };
 };

package/dist/process/capture/ProcessCaptureError.js

@@ -1,3 +1,4 @@
+import { DarwinProcessOwnershipInspectionError } from "../DarwinProcessRunTokenReader.js";
 import { AnalysisError } from "../../domain/analysisErrorBase.js";
 /** Typed application failure produced by controlled process capture. */
 export class ProcessCaptureError extends AnalysisError {
@@ -40,3 +41,15 @@ export const processCaptureCancelled = () => new ProcessCaptureError("process ca
     reason: "cancelled",
     userMessage: "Process capture was cancelled. Start it again when ready.",
 });
+/** Preserve typed process-inspection preflight failures at the capture boundary. */
+export const normalizeCaptureFailure = (cause, signal) => {
+    if (cause instanceof ProcessCaptureError)
+        return cause;
+    if (cause instanceof DarwinProcessOwnershipInspectionError)
+        return new ProcessCaptureError(cause.message, { cause });
+    if (signal?.aborted === true &&
+        (cause === signal.reason ||
+            (cause instanceof Error && cause.name === "AbortError")))
+        return processCaptureCancelled();
+    return cause;
+};