rea-agents 6.1.0 → 6.3.0

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 observeOwnedProcessGroup = async (ownership, host = systemProcessOwnershipHost, 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",
@@ -39,8 +45,14 @@ export const observeOwnedProcessGroupWithHost = async (ownership, host) => {
     }
     return { state: "alive" };
 };
-/** Record the live launcher and descendant lineage after run-token validation. */
-export const observeOwnedProcessLineageWithHost = async (ownership, host) => {
+/**
+ * Record the live launcher and descendant lineage after run-token validation.
+ *
+ * The observation is intentionally point-in-time. A verified empty descendant
+ * list means no descendants were live during this observation, not that the
+ * run never created a short-lived child.
+ */
+export const observeOwnedProcessLineage = async (ownership, host = systemProcessOwnershipHost) => {
     let processes;
     try {
         processes = liveProcesses(await host.listProcesses());
@@ -325,16 +337,6 @@ export const signalProcessWithStartIdentity = async (pid, expectedIdentity, sign
 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);
-/**
- * Record the live launcher and descendant lineage after run-token validation.
- *
- * The observation is intentionally point-in-time. A verified empty descendant
- * list means no descendants were live during this observation, not that the
- * run never created a short-lived child.
- */
-export const observeOwnedProcessLineage = async (ownership, host = systemProcessOwnershipHost) => observeOwnedProcessLineageWithHost(ownership, host);
 const processIsGone = async (host, pid) => {
     try {
         return !liveProcesses(await host.listProcesses()).some((process) => process.pid === pid);

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

@@ -13,6 +13,23 @@ const hasSameFileState = (before, after) => before.dev === after.dev &&
     before.size === after.size &&
     before.mtimeMs === after.mtimeMs &&
     before.ctimeMs === after.ctimeMs;
+const fileUnavailableSystemCode = (cause) => {
+    if (!(cause instanceof Error) || !("code" in cause))
+        return undefined;
+    const code = cause.code;
+    return typeof code === "string" &&
+        [
+            "EACCES",
+            "EISDIR",
+            "ELOOP",
+            "ENOTDIR",
+            "ENOENT",
+            "EPERM",
+            "ESTALE",
+        ].includes(code)
+        ? code
+        : undefined;
+};
 const lstatIfPresent = async (path) => {
     try {
         return await lstat(path);
@@ -26,15 +43,33 @@ const lstatIfPresent = async (path) => {
 /** Hash a file only when its opened descriptor still matches the captured path state. */
 export const hashFile = async (path, expected, maxBytes, signal) => {
     signal?.throwIfAborted();
-    const handle = await open(path, fsConstants.O_RDONLY |
-        (fsConstants.O_NOFOLLOW ?? 0) |
-        (fsConstants.O_NONBLOCK ?? 0));
+    let handle;
+    try {
+        handle = await open(path, fsConstants.O_RDONLY |
+            (fsConstants.O_NOFOLLOW ?? 0) |
+            (fsConstants.O_NONBLOCK ?? 0));
+    }
+    catch (cause) {
+        signal?.throwIfAborted();
+        const systemCode = fileUnavailableSystemCode(cause);
+        if (systemCode === undefined)
+            throw cause;
+        return {
+            state: "omitted",
+            reason: "file_unavailable",
+            system_code: systemCode,
+        };
+    }
     try {
         signal?.throwIfAborted();
         const stats = await handle.stat();
         signal?.throwIfAborted();
         if (!hasSameFileState(expected, stats) || stats.size > maxBytes)
-            return null;
+            return {
+                state: "omitted",
+                reason: "file_changed_or_short_read",
+                system_code: null,
+            };
         const hash = createHash("sha256");
         const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes));
         let position = 0;
@@ -42,15 +77,34 @@ export const hashFile = async (path, expected, maxBytes, signal) => {
             signal?.throwIfAborted();
             const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, stats.size - position), position);
             if (bytesRead === 0)
-                return null;
+                return {
+                    state: "omitted",
+                    reason: "file_changed_or_short_read",
+                    system_code: null,
+                };
             hash.update(buffer.subarray(0, bytesRead));
             position += bytesRead;
         }
         const after = await handle.stat();
         signal?.throwIfAborted();
         if (!hasSameFileState(stats, after))
-            return null;
-        return hash.digest("hex");
+            return {
+                state: "omitted",
+                reason: "file_changed_or_short_read",
+                system_code: null,
+            };
+        return { state: "hashed", sha256: hash.digest("hex") };
+    }
+    catch (cause) {
+        signal?.throwIfAborted();
+        const systemCode = fileUnavailableSystemCode(cause);
+        if (systemCode === undefined)
+            throw cause;
+        return {
+            state: "omitted",
+            reason: "file_unavailable",
+            system_code: systemCode,
+        };
     }
     finally {
         await handle.close();
@@ -59,25 +113,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 +149,40 @@ 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)
+            let sha256 = null;
+            let omission;
+            if (remainingBytes < stats.size) {
+                omission = {
+                    path: `${rootAlias}:${relativePath}`,
+                    size_bytes: stats.size,
+                    remaining_budget_bytes: remainingBytes,
+                    reason: "file_bytes_budget",
+                    system_code: null,
+                };
+            }
+            else {
+                const outcome = await hashFile(path, stats, remainingBytes, signal);
+                if (outcome.state === "hashed") {
+                    sha256 = outcome.sha256;
+                    remainingBytes -= stats.size;
+                }
+                else {
+                    omission = {
+                        path: `${rootAlias}:${relativePath}`,
+                        size_bytes: stats.size,
+                        remaining_budget_bytes: remainingBytes,
+                        reason: outcome.reason,
+                        system_code: outcome.system_code,
+                    };
+                }
+            }
+            if (omission !== undefined) {
                 truncated = true;
+                hashOmissions.push(omission);
+            }
             entries.push({
                 path: `${rootAlias}:${relativePath}`,
                 type: "file",
@@ -104,7 +191,7 @@ export const snapshotRoots = async (scenario, signal) => {
                 sha256,
                 symlink_target: null,
             });
-            return;
+            return true;
         }
         const type = stats.isDirectory() ? "directory" : "other";
         entries.push({
@@ -116,22 +203,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;
         }
-        for (const child of children.sort())
-            await visit(root, rootAlias, join(path, child), depth + 1);
+        let complete = true;
+        for (const child of children.sort()) {
+            if (!(await visit(root, rootAlias, join(path, child), depth + 1)))
+                complete = false;
+        }
+        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;
+};