rea-agents 4.1.0 → 6.0.0

package/dist/native/pwntools/RecordedCrashStructureBindings.js

@@ -0,0 +1,101 @@
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+// Exact amd64/core enum projections in the pinned pyelftools 0.33 profile.
+const segmentKinds = new Map([
+    [0, "PT_NULL"],
+    [1, "PT_LOAD"],
+    [2, "PT_DYNAMIC"],
+    [3, "PT_INTERP"],
+    [4, "PT_NOTE"],
+    [5, "PT_SHLIB"],
+    [6, "PT_PHDR"],
+    [7, "PT_TLS"],
+    [0x60000000, "PT_LOOS"],
+    [0x6fffffff, "PT_HIOS"],
+    [0x6474e550, "PT_GNU_EH_FRAME"],
+    [0x6474e551, "PT_GNU_STACK"],
+    [0x6474e552, "PT_GNU_RELRO"],
+    [0x6474e553, "PT_GNU_PROPERTY"],
+]);
+const noteKinds = new Map([
+    [1, "NT_PRSTATUS"],
+    [2, "NT_FPREGSET"],
+    [3, "NT_PRPSINFO"],
+    [4, "NT_TASKSTRUCT"],
+    [6, "NT_AUXV"],
+    [0x53494749, "NT_SIGINFO"],
+    [0x46494c45, "NT_FILE"],
+]);
+const matchesKind = (raw, reported, kinds) => {
+    const known = kinds.get(raw);
+    return typeof reported === "string"
+        ? reported === known
+        : known === undefined && reported === raw;
+};
+const segmentMatches = (segment, raw) => {
+    const type = raw.readUInt32LE(0);
+    return (matchesKind(type, segment.type, segmentKinds) &&
+        BigInt(segment.flags) === BigInt(raw.readUInt32LE(4)) &&
+        segment.file_backing ===
+            (type === 0 || raw.readBigUInt64LE(32) === 0n ? "none" : "file") &&
+        [
+            [segment.offset, 8],
+            [segment.virtual_address, 16],
+            [segment.physical_address, 24],
+            [segment.file_size, 32],
+            [segment.memory_size, 40],
+            [segment.alignment, 48],
+        ].every(([field, relative]) => BigInt(field) === raw.readBigUInt64LE(relative)));
+};
+/** Bind coverage-bearing ELF and note headers to the same snapshot as their payloads. */
+export function validateRecordedCrashStructure(report, snapshot, diagnostics) {
+    const fail = () => {
+        throw new AnalysisOutputError("inspect_recorded_crash", "Reported core structure differs from its original ELF/note headers.", { capturedOutput: diagnostics });
+    };
+    const bytesAt = (offset, bytes) => {
+        if (offset < 0n || offset > BigInt(snapshot.length - bytes))
+            return fail();
+        return snapshot.subarray(Number(offset), Number(offset) + bytes);
+    };
+    const header = bytesAt(0n, 64);
+    if (!header
+        .subarray(0, 6)
+        .equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46, 2, 1])) ||
+        ![0, 3].includes(header[7] ?? -1) ||
+        header[8] !== 0 ||
+        header.readUInt16LE(16) !== 4 ||
+        header.readUInt16LE(18) !== 62)
+        fail();
+    const table = header.readBigUInt64LE(32);
+    const entryBytes = header.readUInt16LE(54);
+    let count = header.readUInt16LE(56);
+    if (count === 0xffff) {
+        if (header.readUInt16LE(58) < 64)
+            return fail();
+        count = bytesAt(header.readBigUInt64LE(40), 64).readUInt32LE(44);
+    }
+    if (count !== report.segments.length || (count > 0 && entryBytes < 56))
+        fail();
+    for (const segment of report.segments) {
+        const offset = table + BigInt(segment.index) * BigInt(entryBytes);
+        if (BigInt(segment.header_location.offset) !== offset ||
+            BigInt(segment.header_location.bytes) !== BigInt(entryBytes))
+            fail();
+        const raw = bytesAt(offset, entryBytes);
+        if (!segmentMatches(segment, raw))
+            fail();
+    }
+    for (const note of report.notes) {
+        const raw = bytesAt(BigInt(note.location.offset), 12);
+        if (BigInt(note.owner_location.bytes) !== BigInt(raw.readUInt32LE(0)) ||
+            BigInt(note.descriptor_location.bytes) !== BigInt(raw.readUInt32LE(4)) ||
+            !matchesKind(raw.readUInt32LE(8), note.type, noteKinds))
+            fail();
+        const owner = bytesAt(BigInt(note.owner_location.offset), raw.readUInt32LE(0));
+        const terminator = owner.indexOf(0);
+        const display = owner.length === 0
+            ? null
+            : owner.subarray(0, terminator).toString("utf8");
+        if ((owner.length > 0 && terminator < 0) || note.owner_display !== display)
+            fail();
+    }
+}

package/dist/process/DarwinProcessRunTokenReader.js

@@ -0,0 +1,294 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { safeParseJson } from "../domain/safeJson.js";
+import { execFileOutput } from "./ExecFileOutput.js";
+const responseSchema = z.strictObject({
+    results: z.array(z.discriminatedUnion("state", [
+        z.strictObject({
+            pid: z.number().int().positive(),
+            state: z.literal("readable"),
+            run_id: z.string().optional(),
+            reason: z.null().optional(),
+        }),
+        z.strictObject({
+            pid: z.number().int().positive(),
+            state: z.literal("unavailable"),
+            run_id: z.union([z.string(), z.null()]).optional(),
+            reason: z.string().min(1),
+        }),
+    ])),
+});
+const identityResponseSchema = z.strictObject({
+    results: z.array(z.discriminatedUnion("state", [
+        z.strictObject({
+            pid: z.number().int().positive(),
+            state: z.literal("readable"),
+            identity: z.string().min(1),
+            reason: z.null().optional(),
+        }),
+        z.strictObject({
+            pid: z.number().int().positive(),
+            state: z.literal("unavailable"),
+            identity: z.null().optional(),
+            reason: z.string().min(1),
+        }),
+    ])),
+});
+const sourceFiles = [
+    fileURLToPath(new URL("../../bridge/process/ProcessRunTokenReader.swift", import.meta.url)),
+    fileURLToPath(new URL("../../bridge/process/ProcessRunTokenReaderMain.swift", import.meta.url)),
+];
+/** The native Darwin process-ownership reader could not be prepared. */
+export class DarwinProcessOwnershipInspectionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "DarwinProcessOwnershipInspectionError";
+    }
+}
+const abortReason = (signal) => {
+    if (signal.reason !== undefined)
+        return signal.reason;
+    const error = new Error("The operation was aborted");
+    error.name = "AbortError";
+    return error;
+};
+const isExpectedAbort = (cause, signal) => signal.aborted &&
+    (cause === signal.reason ||
+        (cause instanceof Error && cause.name === "AbortError"));
+const waitForCompilation = async (promise, signal) => {
+    if (signal === undefined)
+        return promise;
+    if (signal.aborted)
+        throw abortReason(signal);
+    return new Promise((resolve, reject) => {
+        let completed = false;
+        const finish = (callback) => {
+            if (completed)
+                return;
+            completed = true;
+            signal.removeEventListener("abort", onAbort);
+            callback();
+        };
+        const onAbort = () => finish(() => reject(abortReason(signal)));
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => finish(() => resolve(value)), (cause) => finish(() => reject(cause)));
+        if (signal.aborted)
+            onAbort();
+    });
+};
+/** Compile and retain the narrow Darwin sysctl reader for this REA process. */
+export const createDarwinProcessRunTokenReader = (options = {}) => {
+    let root;
+    let executable;
+    let compilation;
+    let closePromise;
+    let closed = false;
+    let exitCleanupInstalled = false;
+    const cleanupAtExit = () => {
+        if (root !== undefined)
+            rmSync(root, { recursive: true, force: true });
+    };
+    const cleanupRoot = async (target = root) => {
+        if (target === undefined)
+            return;
+        await rm(target, { recursive: true, force: true });
+        if (root !== target)
+            return;
+        root = undefined;
+        executable = undefined;
+        if (exitCleanupInstalled)
+            process.removeListener("exit", cleanupAtExit);
+        exitCleanupInstalled = false;
+    };
+    const runCompilation = async (signal) => {
+        let operationRoot;
+        try {
+            operationRoot = await mkdtemp(join(tmpdir(), "rea-process-token-"));
+            root = operationRoot;
+            process.once("exit", cleanupAtExit);
+            exitCleanupInstalled = true;
+            if (signal.aborted || closed)
+                throw abortReason(signal);
+            const output = join(operationRoot, "reader");
+            try {
+                await execFileOutput(options.xcrun ?? "/usr/bin/xcrun", [
+                    "swiftc",
+                    "-module-cache-path",
+                    join(operationRoot, "modules"),
+                    ...sourceFiles,
+                    "-o",
+                    output,
+                ], {
+                    timeout: 60_000,
+                    maxBuffer: 1024 * 1024,
+                    signal,
+                });
+            }
+            catch (cause) {
+                if (isExpectedAbort(cause, signal))
+                    throw cause;
+                const code = cause instanceof Error && "code" in cause
+                    ? String(cause.code)
+                    : "unknown";
+                throw new DarwinProcessOwnershipInspectionError(`macOS process ownership inspection requires the Apple Swift compiler via xcrun (compiler result: ${code})`, { cause });
+            }
+            if (signal.aborted || closed)
+                throw abortReason(signal);
+            executable = output;
+            return output;
+        }
+        catch (cause) {
+            const ownsRoot = operationRoot !== undefined && root === operationRoot;
+            if (operationRoot !== undefined) {
+                if (ownsRoot)
+                    await cleanupRoot(operationRoot);
+                else
+                    await rm(operationRoot, { recursive: true, force: true });
+            }
+            throw cause;
+        }
+    };
+    const beginCompilation = () => {
+        const controller = new AbortController();
+        const operation = {
+            controller,
+            promise: runCompilation(controller.signal).finally(() => {
+                operation.settled = true;
+                if (compilation === operation)
+                    compilation = undefined;
+            }),
+            waiters: 0,
+            aborting: false,
+            settled: false,
+        };
+        compilation = operation;
+        return operation;
+    };
+    const compile = async (signal) => {
+        if (closed)
+            throw new Error("Darwin process token reader is closed");
+        signal?.throwIfAborted();
+        while (true) {
+            if (closed)
+                throw new Error("Darwin process token reader is closed");
+            signal?.throwIfAborted();
+            if (executable !== undefined)
+                return executable;
+            if (compilation === undefined && root !== undefined) {
+                await cleanupRoot();
+                continue;
+            }
+            let operation = compilation;
+            if (operation?.aborting === true) {
+                try {
+                    await waitForCompilation(operation.promise, signal);
+                }
+                catch (cause) {
+                    if (signal !== undefined && isExpectedAbort(cause, signal))
+                        throw cause;
+                }
+                continue;
+            }
+            operation ??= beginCompilation();
+            operation.waiters += 1;
+            try {
+                return await waitForCompilation(operation.promise, signal);
+            }
+            finally {
+                operation.waiters -= 1;
+                if (operation.waiters === 0 &&
+                    !operation.settled &&
+                    !operation.aborting) {
+                    operation.aborting = true;
+                    operation.controller.abort();
+                    await operation.promise.catch(() => undefined);
+                }
+            }
+        }
+    };
+    const read = async (processes) => {
+        if (processes.length === 0)
+            return new Map();
+        const binary = await compile();
+        const pids = processes.map(({ pid }) => String(pid));
+        const { stdout } = await execFileOutput(binary, pids, { timeout: 15_000 });
+        const decoded = safeParseJson(stdout);
+        if (!decoded.ok)
+            throw new Error(`macOS process token helper returned invalid JSON: ${decoded.error}`, { cause: decoded.cause });
+        const parsed = responseSchema.safeParse(decoded.value);
+        if (!parsed.success)
+            throw new Error("macOS process token helper returned an invalid response", {
+                cause: parsed.error,
+            });
+        const requested = new Set(processes.map(({ pid }) => pid));
+        const observations = new Map();
+        for (const result of parsed.data.results) {
+            if (!requested.has(result.pid) || observations.has(result.pid))
+                throw new Error("macOS process token helper returned an unexpected PID set");
+            observations.set(result.pid, result.state === "readable"
+                ? { state: "readable", runId: result.run_id }
+                : {
+                    state: "unavailable",
+                    reason: result.reason ?? "process token observation is unavailable",
+                });
+        }
+        if (observations.size !== requested.size)
+            throw new Error("macOS process token helper returned an incomplete PID set");
+        return observations;
+    };
+    const identities = async (processes, signal) => {
+        if (processes.length === 0)
+            return new Map();
+        const binary = await compile(signal);
+        const pids = processes.map(({ pid }) => String(pid));
+        const { stdout } = await execFileOutput(binary, ["--identities", ...pids], {
+            timeout: 15_000,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        const decoded = safeParseJson(stdout);
+        if (!decoded.ok)
+            throw new Error(`macOS process identity helper returned invalid JSON: ${decoded.error}`, { cause: decoded.cause });
+        const parsed = identityResponseSchema.safeParse(decoded.value);
+        if (!parsed.success)
+            throw new Error("macOS process identity helper returned an invalid response", {
+                cause: parsed.error,
+            });
+        const requested = new Set(processes.map(({ pid }) => pid));
+        const observations = new Map();
+        for (const result of parsed.data.results) {
+            if (!requested.has(result.pid) || observations.has(result.pid))
+                throw new Error("macOS process identity helper returned an unexpected PID set");
+            observations.set(result.pid, result.state === "readable"
+                ? { state: "readable", identity: result.identity }
+                : { state: "unavailable", reason: result.reason });
+        }
+        if (observations.size !== requested.size)
+            throw new Error("macOS process identity helper returned an incomplete PID set");
+        return observations;
+    };
+    const close = () => {
+        if (closePromise !== undefined)
+            return closePromise;
+        closed = true;
+        const pendingClose = (async () => {
+            const operation = compilation;
+            if (operation !== undefined && !operation.settled) {
+                operation.aborting = true;
+                operation.controller.abort();
+                await operation.promise.catch(() => undefined);
+            }
+            await cleanupRoot();
+        })().catch((cause) => {
+            if (closePromise === pendingClose)
+                closePromise = undefined;
+            throw cause;
+        });
+        closePromise = pendingClose;
+        return closePromise;
+    };
+    return { read, identities, prepare: compile, close };
+};

package/dist/process/ExecFileOutput.js

@@ -7,6 +7,8 @@ export const execFileOutput = (command, arguments_, options = {}) => new Promise
         maxBuffer: options.maxBuffer ?? Number.POSITIVE_INFINITY,
     }, (error, stdout, stderr) => {
         if (error !== null) {
+            Reflect.set(error, "stdout", stdout);
+            Reflect.set(error, "stderr", stderr);
             reject(error);
             return;
         }

package/dist/process/OwnedCommand.js

@@ -0,0 +1,113 @@
+import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "./ProviderProcess.js";
+import { cleanupOwnedProcessGroup } from "./ProcessOwnership.js";
+import { ProviderStartupDeadline, waitForAbortableDelay, } from "./ProviderDeadline.js";
+/** A short-lived command failed its lifecycle or complete-output contract. */
+export class OwnedCommandFailure extends Error {
+    reason;
+    snapshot;
+    cleanupFailure;
+    resources;
+    constructor(reason, message, snapshot = null, cleanupFailure = null, options, resources = []) {
+        super(message, options);
+        this.reason = reason;
+        this.snapshot = snapshot;
+        this.cleanupFailure = cleanupFailure;
+        this.resources = resources;
+    }
+}
+/** Execute a single owned process with independent cleanup and bounded diagnostic retention. */
+export const runOwnedCommand = async (spawn, limits, options = {}) => {
+    const callerSignal = options.signal ?? spawn.signal;
+    if (callerSignal?.aborted)
+        throw new OwnedCommandFailure("cancelled", "Command cancelled before launch.");
+    const deadline = new ProviderStartupDeadline(limits.timeoutMs, callerSignal);
+    try {
+        return await collectOwnedCommand(spawn, limits, options.launcher ?? spawnOwnedProviderProcess, deadline, callerSignal);
+    }
+    finally {
+        deadline.dispose();
+    }
+};
+const collectOwnedCommand = async (spawn, limits, launcher, deadline, callerSignal) => {
+    const signal = deadline.signal;
+    let launched;
+    try {
+        launched = await launcher({
+            ...spawn,
+            signal,
+        });
+    }
+    catch (cause) {
+        const interruption = deadline.interruption;
+        if (interruption !== undefined)
+            throw new OwnedCommandFailure(interruption, interruption === "cancelled"
+                ? "Command cancelled during ownership preparation."
+                : "Command deadline elapsed during ownership preparation.", null, null, { cause });
+        throw cause;
+    }
+    let exceeded = false;
+    let processFailure;
+    const supervisor = new ProviderProcessSupervisor({
+        ...launched,
+        ownsProcessLifetime: true,
+        cleanup: launched.cleanup ??
+            (() => cleanupOwnedProcessGroup(launched.ownership)),
+    }, {
+        maxDiagnosticBytes: limits.diagnosticBytes,
+        onDiagnostic: (event) => {
+            if (event.type === "output" && event.truncated === true)
+                exceeded = true;
+            if (event.type === "error")
+                processFailure = event.message;
+        },
+    });
+    let failure;
+    try {
+        while (!(await supervisor.waitForOutputClose(10))) {
+            const interruption = deadline.interruption;
+            if (interruption !== undefined)
+                throw new OwnedCommandFailure(interruption, interruption === "cancelled"
+                    ? "Command cancelled."
+                    : "Command deadline elapsed.");
+            if (exceeded)
+                throw new OwnedCommandFailure("output-limit", "Command diagnostic output exceeded its complete-output budget.");
+            if (processFailure !== undefined)
+                throw new OwnedCommandFailure("process", processFailure);
+            await waitForAbortableDelay(25, signal);
+        }
+        const snapshot = supervisor.snapshot();
+        const interruption = deadline.interruption;
+        if (interruption !== undefined)
+            throw new OwnedCommandFailure(interruption, interruption === "cancelled"
+                ? "Command cancelled."
+                : "Command deadline elapsed.", snapshot);
+        if (exceeded)
+            throw new OwnedCommandFailure("output-limit", "Command diagnostic output exceeded its complete-output budget.", snapshot);
+        if (processFailure !== undefined ||
+            snapshot.exitCode !== 0 ||
+            snapshot.signal !== null)
+            throw new OwnedCommandFailure("process", processFailure ??
+                "Command failed; inspect its exit status and diagnostics.", snapshot);
+    }
+    catch (cause) {
+        failure =
+            cause instanceof OwnedCommandFailure
+                ? cause
+                : new OwnedCommandFailure("process", "Command collection failed.", null, null, { cause });
+    }
+    const stopped = await supervisor.stop();
+    const snapshot = supervisor.snapshot();
+    supervisor.dispose();
+    if (stopped.status === "incomplete")
+        throw new OwnedCommandFailure(failure?.reason ?? "process", failure?.message ?? "Command cleanup failed.", snapshot, stopped.reason, failure === undefined ? undefined : { cause: failure }, [
+            spawn.runId,
+            ...(spawn.cwd === undefined ? [] : [spawn.cwd]),
+            `pid:${launched.ownership.leaderPid}`,
+            `process-group:${launched.ownership.processGroupId}`,
+        ]);
+    if (failure !== undefined)
+        throw new OwnedCommandFailure(failure.reason, failure.message, snapshot, failure.cleanupFailure, { cause: failure }, failure.resources);
+    if (callerSignal?.aborted)
+        throw new OwnedCommandFailure("cancelled", "Command cancelled.", snapshot);
+    return snapshot;
+};