rea-agents 1.7.0 → 2.0.0

package/dist/replay/LinuxJavaScriptReplayRunner.js

@@ -0,0 +1,434 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { open, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { digestBytes, digestJson, } from "../application/JavaScriptReplayPlanning.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { buildLinuxX64ReplaySeccomp, linuxX64ReplaySeccompDigest, } from "./LinuxSeccompPolicy.js";
+import { resolveLinuxRuntimeClosure } from "./LinuxRuntimeClosure.js";
+import { parseReplayWorkerResponse, } from "./ReplayWorkerProtocol.js";
+const isAborted = (signal) => signal?.aborted === true;
+/** Run one prepared experiment under the exact Linux ADR-0002 boundary. */
+export class LinuxJavaScriptReplayRunner {
+    async execute(prepared, policy, signal) {
+        if (isAborted(signal))
+            return terminationResult(prepared, "", "cancelled", {
+                state: "complete",
+                residual_resources: [],
+            });
+        const unit = `rea-replay-${randomBytes(8).toString("hex")}.service`;
+        const workerPath = prepared.publicPlan.runtime.worker.path;
+        const closure = await resolveLinuxRuntimeClosure(policy.nodePath);
+        assertRuntimeCommitment(prepared, closure);
+        if (digestBytes(await readFile(workerPath)) !==
+            prepared.publicPlan.runtime.worker.sha256)
+            throw new TypeError("Replay worker changed after approval");
+        if (linuxX64ReplaySeccompDigest() !==
+            prepared.publicPlan.sandbox.seccomp_sha256)
+            throw new TypeError("Replay seccomp policy changed after approval");
+        const request = workerRequest(prepared);
+        const encoded = Buffer.from(JSON.stringify(request));
+        if (encoded.byteLength > prepared.publicPlan.limits.protocol_bytes)
+            throw new RangeError("Replay worker protocol input exceeds the committed limit");
+        const filter = await temporaryFilterHandle();
+        const arguments_ = systemdArguments(unit, policy, prepared, workerPath, closure, filter.path);
+        let child;
+        let timeout;
+        let cancelled = false;
+        let timedOut = false;
+        let terminationRequest;
+        const requestTermination = () => {
+            terminationRequest ??= killUnit(policy.systemctlPath, unit);
+            child?.kill("SIGKILL");
+        };
+        const terminate = () => {
+            cancelled = true;
+            requestTermination();
+        };
+        try {
+            const completion = new Promise((resolve, reject) => {
+                child = spawn(policy.systemdRunPath, arguments_, {
+                    stdio: ["pipe", "pipe", "pipe"],
+                    env: {
+                        PATH: "/usr/bin:/bin",
+                        LANG: "C",
+                        LC_ALL: "C",
+                        TZ: "UTC",
+                        ...(process.env.XDG_RUNTIME_DIR === undefined
+                            ? {}
+                            : { XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR }),
+                        ...(process.env.DBUS_SESSION_BUS_ADDRESS === undefined
+                            ? {}
+                            : {
+                                DBUS_SESSION_BUS_ADDRESS: process.env.DBUS_SESSION_BUS_ADDRESS,
+                            }),
+                    },
+                });
+                const output = boundedCollector(prepared.publicPlan.limits.output_bytes);
+                const diagnostics = boundedCollector(prepared.publicPlan.limits.stderr_bytes);
+                child.stdout?.on("data", output.append);
+                child.stderr?.on("data", diagnostics.append);
+                child.once("error", reject);
+                child.once("close", (code, signalName) => resolve({
+                    code,
+                    signal: signalName,
+                    stdout: output.value(),
+                    stderr: diagnostics.value(),
+                    outputExceeded: output.exceeded(),
+                }));
+                child.stdin?.end(encoded);
+            });
+            signal?.addEventListener("abort", terminate, { once: true });
+            if (isAborted(signal))
+                terminate();
+            timeout = setTimeout(() => {
+                timedOut = true;
+                requestTermination();
+            }, prepared.publicPlan.limits.wall_time_ms);
+            timeout.unref();
+            const collected = await completion;
+            if (terminationRequest !== undefined)
+                await terminationRequest;
+            const unitResult = await observeUnitResult(policy.systemctlPath, unit);
+            const cleanup = await observeCleanup(policy.systemctlPath, unit);
+            if (cancelled || timedOut)
+                return terminationResult(prepared, collected.stderr, cancelled ? "cancelled" : "timeout", cleanup);
+            if (collected.outputExceeded)
+                return terminationResult(prepared, collected.stderr, "protocol_error", cleanup, "Worker stdout exceeded the committed bound");
+            if (collected.code !== 0)
+                return terminationResult(prepared, collected.stderr, collected.code === 137 || unitResult === "oom-kill" ? "oom" : "crash", cleanup);
+            let response;
+            try {
+                response = parseReplayWorkerResponse(JSON.parse(collected.stdout), prepared.publicPlan.cases, prepared.publicPlan.right !== undefined);
+            }
+            catch {
+                return terminationResult(prepared, collected.stderr, "protocol_error", cleanup);
+            }
+            const outcomes = commitOutcomes(response.left);
+            const right = response.right === undefined
+                ? undefined
+                : commitOutcomes(response.right);
+            return {
+                schema_version: 1,
+                plan_digest: prepared.publicPlan.plan_digest,
+                outcomes: [...outcomes, ...(right ?? [])],
+                ...(right === undefined
+                    ? {}
+                    : { comparison: compareOutcomes(outcomes, right) }),
+                stderr: collected.stderr,
+                termination: "completed",
+                cleanup,
+                limitations: [
+                    "Controlled replay observes the isolated extracted modules, not the original application runtime.",
+                    "Network and host filesystem access were unavailable; unsupported dependencies may change behavior.",
+                ],
+                reproducer: null,
+            };
+        }
+        finally {
+            signal?.removeEventListener("abort", terminate);
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            if (child !== undefined && child.exitCode === null) {
+                requestTermination();
+                await terminationRequest;
+            }
+            await filter.close();
+        }
+    }
+}
+const workerRequest = (prepared) => ({
+    schemaVersion: 1,
+    left: workerSide(prepared.publicPlan.left, prepared.leftSources),
+    ...(prepared.publicPlan.right === undefined ||
+        prepared.rightSources === undefined
+        ? {}
+        : { right: workerSide(prepared.publicPlan.right, prepared.rightSources) }),
+    cases: prepared.publicPlan.cases.map((item) => ({
+        caseId: item.case_id,
+        arguments: item.arguments,
+        inputSha256: item.sha256,
+    })),
+    determinism: {
+        clockIso: prepared.publicPlan.determinism.clock_iso,
+        randomSeed: prepared.publicPlan.determinism.random_seed,
+    },
+    limits: {
+        resultDepth: prepared.publicPlan.limits.result_depth,
+        resultNodes: prepared.publicPlan.limits.result_nodes,
+        exceptionBytes: Math.min(64 * 1024, prepared.publicPlan.limits.output_bytes),
+    },
+});
+const workerSide = (side, sources) => ({
+    modules: side.modules.map((module) => ({
+        alias: module.alias,
+        format: module.format,
+        dependencies: module.dependencies,
+        source: sources[module.alias] ?? "",
+    })),
+    entryAlias: side.entry_alias,
+    entryExport: side.entry_export,
+});
+const systemdArguments = (unit, policy, prepared, workerPath, closure, filterPath) => {
+    const limits = prepared.publicPlan.limits;
+    const descriptorPaths = [
+        filterPath,
+        ...closure.map(({ sourcePath }) => sourcePath),
+        workerPath,
+    ];
+    const workerFd = descriptorPaths.length + 2;
+    const wrapper = descriptorPaths
+        .map((_, index) => `exec ${String(index + 3)}<"$1"; shift`)
+        .concat('exec "$@"')
+        .join("\n");
+    return [
+        "--user",
+        "--pipe",
+        "--wait",
+        "--service-type=exec",
+        "--quiet",
+        `--unit=${unit}`,
+        `--property=MemoryMax=${String(limits.memory_bytes)}`,
+        "--property=MemorySwapMax=0",
+        `--property=TasksMax=${String(limits.tasks)}`,
+        `--property=CPUQuota=${String(limits.cpu_quota_percent)}%`,
+        "--property=KillMode=control-group",
+        "--property=SendSIGKILL=yes",
+        "--",
+        policy.shellPath,
+        "-c",
+        wrapper,
+        "rea-replay-wrapper",
+        ...descriptorPaths,
+        policy.bubblewrapPath,
+        "--unshare-all",
+        "--unshare-user",
+        "--disable-userns",
+        "--new-session",
+        "--die-with-parent",
+        "--cap-drop",
+        "ALL",
+        "--clearenv",
+        "--setenv",
+        "HOME",
+        "/work",
+        "--setenv",
+        "TMPDIR",
+        "/tmp",
+        "--setenv",
+        "TZ",
+        "UTC",
+        "--setenv",
+        "LANG",
+        "C",
+        "--setenv",
+        "LC_ALL",
+        "C",
+        "--tmpfs",
+        "/",
+        "--dir",
+        "/runtime",
+        "--dir",
+        "/work",
+        "--size",
+        String(limits.tmpfs_bytes),
+        "--tmpfs",
+        "/tmp",
+        ...bindArguments(closure),
+        "--ro-bind-fd",
+        String(workerFd),
+        "/runtime/worker.js",
+        "--proc",
+        "/proc",
+        "--dev",
+        "/dev",
+        "--remount-ro",
+        "/",
+        "--chdir",
+        "/work",
+        "--seccomp",
+        "3",
+        "--",
+        "/runtime/node",
+        `--max-old-space-size=${String(Math.max(8, Math.floor(limits.memory_bytes / 1024 / 1024 / 2)))}`,
+        "--experimental-vm-modules",
+        "--permission",
+        "--allow-fs-read=/runtime/worker.js",
+        "/runtime/worker.js",
+    ];
+};
+const bindArguments = (closure) => {
+    const arguments_ = [];
+    const directories = new Set();
+    for (const [index, item] of closure.entries()) {
+        const destination = item.destinationPath;
+        let parent = dirname(destination);
+        const chain = [];
+        while (parent !== "/" && !directories.has(parent)) {
+            chain.push(parent);
+            parent = dirname(parent);
+        }
+        for (const directory of chain.reverse()) {
+            directories.add(directory);
+            arguments_.push("--dir", directory);
+        }
+        arguments_.push("--ro-bind-fd", String(index + 4), destination);
+    }
+    return arguments_;
+};
+const assertRuntimeCommitment = (prepared, closure) => {
+    const observed = closure.map((item) => ({
+        source_path: item.sourcePath,
+        destination_path: item.destinationPath,
+        sha256: item.sha256,
+    }));
+    if (digestJson(observed) !==
+        digestJson(prepared.publicPlan.runtime.read_only_files))
+        throw new TypeError("Replay runtime closure changed after approval");
+};
+const temporaryFilterHandle = async () => {
+    const { mkdtemp, writeFile, rm } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const directory = await mkdtemp(join(tmpdir(), "rea-replay-filter-"));
+    const path = join(directory, "seccomp.bpf");
+    await writeFile(path, buildLinuxX64ReplaySeccomp(), { mode: 0o600 });
+    const handle = await open(path, "r");
+    return {
+        path,
+        handle,
+        close: async () => {
+            await handle.close();
+            await rm(directory, { recursive: true, force: true });
+        },
+    };
+};
+const boundedCollector = (maximum) => {
+    const chunks = [];
+    let bytes = 0;
+    let overflow = false;
+    return {
+        append: (chunk) => {
+            const retained = chunk.subarray(0, Math.max(0, maximum - bytes));
+            if (retained.byteLength > 0)
+                chunks.push(retained);
+            bytes += retained.byteLength;
+            if (retained.byteLength < chunk.byteLength)
+                overflow = true;
+        },
+        value: () => Buffer.concat(chunks).toString("utf8"),
+        exceeded: () => overflow,
+    };
+};
+const collect = async (executable, arguments_, maximum) => new Promise((resolve, reject) => {
+    const child = spawn(executable, [...arguments_], {
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stdout = boundedCollector(maximum);
+    const stderr = boundedCollector(maximum);
+    const timeout = setTimeout(() => child.kill("SIGKILL"), 5_000);
+    timeout.unref();
+    child.stdout?.on("data", stdout.append);
+    child.stderr?.on("data", stderr.append);
+    child.once("error", (error) => {
+        clearTimeout(timeout);
+        reject(error);
+    });
+    child.once("close", (code) => {
+        clearTimeout(timeout);
+        resolve({ code, stdout: stdout.value(), stderr: stderr.value() });
+    });
+});
+const killUnit = async (systemctl, unit) => {
+    try {
+        await collect(systemctl, ["--user", "kill", "--kill-whom=all", "--signal=SIGKILL", unit], 4096);
+    }
+    catch {
+        /* cleanup continues */
+    }
+};
+const observeCleanup = async (systemctl, unit) => {
+    try {
+        const state = await collect(systemctl, ["--user", "show", "--property=ActiveState", "--value", unit], 4096);
+        if (state.code !== 0 ||
+            state.stdout.trim() === "inactive" ||
+            state.stdout.trim() === "failed" ||
+            state.stdout.trim().length === 0) {
+            await collect(systemctl, ["--user", "reset-failed", unit], 4096);
+            return { state: "complete", residual_resources: [] };
+        }
+        return { state: "incomplete", residual_resources: [unit] };
+    }
+    catch {
+        return { state: "incomplete", residual_resources: [unit] };
+    }
+};
+const observeUnitResult = async (systemctl, unit) => {
+    try {
+        const result = await collect(systemctl, ["--user", "show", "--property=Result", "--value", unit], 4096);
+        return result.stdout.trim();
+    }
+    catch {
+        return "unknown";
+    }
+};
+const commitOutcomes = (outcomes) => outcomes.map((outcome) => {
+    const semantic = outcome.value === undefined ? (outcome.exception ?? null) : outcome.value;
+    return {
+        case_id: outcome.case_id,
+        outcome: outcome.outcome,
+        ...(outcome.value === undefined
+            ? {}
+            : { value: jsonValueSchema.parse(outcome.value) }),
+        ...(outcome.exception === undefined
+            ? {}
+            : { exception: outcome.exception }),
+        input_sha256: outcome.input_sha256,
+        output_sha256: digestJson(semantic),
+        truncated: false,
+    };
+});
+const compareOutcomes = (left, right) => left.map((item, index) => ({
+    case_id: item.case_id,
+    status: right[index] === undefined
+        ? "unknown"
+        : item.outcome === right[index].outcome &&
+            item.output_sha256 === right[index].output_sha256
+            ? "equal"
+            : "changed",
+    left_index: index,
+    right_index: index,
+}));
+const terminationResult = (prepared, stderr, termination, cleanup, limitation) => {
+    const outcomes = prepared.publicPlan.cases.map((item) => ({
+        case_id: item.case_id,
+        outcome: termination,
+        input_sha256: item.sha256,
+        output_sha256: null,
+        truncated: termination === "protocol_error",
+    }));
+    const differential = prepared.publicPlan.right !== undefined;
+    return {
+        schema_version: 1,
+        plan_digest: prepared.publicPlan.plan_digest,
+        outcomes: [...outcomes, ...(differential ? outcomes : [])],
+        ...(differential
+            ? {
+                comparison: outcomes.map((item, index) => ({
+                    case_id: item.case_id,
+                    status: "unknown",
+                    left_index: index,
+                    right_index: index,
+                })),
+            }
+            : {}),
+        stderr,
+        termination,
+        cleanup,
+        limitations: [
+            limitation ??
+                `Replay terminated with ${termination}; the requested functional result remains unknown.`,
+        ],
+        reproducer: null,
+    };
+};

package/dist/replay/LinuxRuntimeClosure.js

@@ -0,0 +1,46 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+const LDD_OUTPUT_LIMIT = 64 * 1024;
+/** Resolve and content-address the exact ELF closure mounted into a replay. */
+export const resolveLinuxRuntimeClosure = async (nodePath) => {
+    const canonicalNode = await realpath(nodePath);
+    const collected = await collectLdd(canonicalNode);
+    if (collected.code !== 0)
+        throw new TypeError("Node runtime dependency closure could not be resolved");
+    const paths = [...collected.stdout.matchAll(/(?:=>\s+)?(\/[^\s()]+)/gu)]
+        .map((match) => match[1])
+        .filter((value) => value !== undefined);
+    const libraries = await Promise.all([...new Set(paths)].map(async (path) => {
+        const sourcePath = await realpath(path);
+        return identity(sourcePath, path);
+    }));
+    return [await identity(canonicalNode, "/runtime/node"), ...libraries];
+};
+const identity = async (sourcePath, destinationPath) => ({
+    sourcePath,
+    destinationPath,
+    sha256: createHash("sha256")
+        .update(await readFile(sourcePath))
+        .digest("hex"),
+});
+const collectLdd = async (path) => new Promise((resolve, reject) => {
+    const child = spawn("/usr/bin/ldd", [path], {
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    const timeout = setTimeout(() => child.kill("SIGKILL"), 5_000);
+    timeout.unref();
+    let stdout = "";
+    child.stdout.on("data", (chunk) => {
+        const remaining = Math.max(0, LDD_OUTPUT_LIMIT - Buffer.byteLength(stdout));
+        stdout += chunk.subarray(0, remaining).toString("utf8");
+    });
+    child.once("error", (error) => {
+        clearTimeout(timeout);
+        reject(error);
+    });
+    child.once("close", (code) => {
+        clearTimeout(timeout);
+        resolve({ code, stdout });
+    });
+});

package/dist/replay/LinuxSeccompPolicy.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+const BPF_LD_W_ABS = 0x20;
+const BPF_JMP_JEQ_K = 0x15;
+const BPF_RET_K = 0x06;
+const SECCOMP_RET_KILL_PROCESS = 0x8000_0000;
+const SECCOMP_RET_ERRNO = 0x0005_0000 | 1;
+const SECCOMP_RET_ALLOW = 0x7fff_0000;
+const AUDIT_ARCH_X86_64 = 0xc000_003e;
+const IOCTL = 16;
+const TIOCSTI = 0x5412;
+const DENIED_X86_64_SYSCALLS = [
+    101, 103, 155, 161, 163, 165, 166, 167, 168, 169, 172, 173, 175, 176, 179,
+    212, 246, 248, 249, 250, 272, 298, 303, 304, 308, 310, 311, 312, 313, 320,
+    321, 323, 425, 426, 427, 428, 429, 430, 431, 432, 433, 442,
+];
+/** Build the architecture-checked deny filter committed by ADR-0002. */
+export const buildLinuxX64ReplaySeccomp = () => {
+    const instructions = [
+        { code: BPF_LD_W_ABS, jt: 0, jf: 0, k: 4 },
+        { code: BPF_JMP_JEQ_K, jt: 1, jf: 0, k: AUDIT_ARCH_X86_64 },
+        { code: BPF_RET_K, jt: 0, jf: 0, k: SECCOMP_RET_KILL_PROCESS },
+        { code: BPF_LD_W_ABS, jt: 0, jf: 0, k: 0 },
+    ];
+    for (const syscall of DENIED_X86_64_SYSCALLS) {
+        instructions.push({ code: BPF_JMP_JEQ_K, jt: 0, jf: 1, k: syscall });
+        instructions.push({ code: BPF_RET_K, jt: 0, jf: 0, k: SECCOMP_RET_ERRNO });
+    }
+    instructions.push({ code: BPF_JMP_JEQ_K, jt: 0, jf: 3, k: IOCTL }, { code: BPF_LD_W_ABS, jt: 0, jf: 0, k: 24 }, { code: BPF_JMP_JEQ_K, jt: 0, jf: 1, k: TIOCSTI }, { code: BPF_RET_K, jt: 0, jf: 0, k: SECCOMP_RET_ERRNO }, { code: BPF_RET_K, jt: 0, jf: 0, k: SECCOMP_RET_ALLOW });
+    const encoded = new Uint8Array(instructions.length * 8);
+    const view = new DataView(encoded.buffer);
+    instructions.forEach((instruction, index) => {
+        const offset = index * 8;
+        view.setUint16(offset, instruction.code, true);
+        view.setUint8(offset + 2, instruction.jt);
+        view.setUint8(offset + 3, instruction.jf);
+        view.setUint32(offset + 4, instruction.k, true);
+    });
+    return encoded;
+};
+export const linuxX64ReplaySeccompDigest = () => createHash("sha256").update(buildLinuxX64ReplaySeccomp()).digest("hex");

package/dist/replay/ReplayWorkerProtocol.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+const workerOutcomeSchema = z
+    .object({
+    case_id: z.string(),
+    outcome: z.enum(["return", "exception", "serialization_error", "denied"]),
+    value: z.json().optional(),
+    exception: z
+        .object({
+        name: z.string(),
+        message: z.string(),
+        stack: z.string().nullable(),
+    })
+        .strict()
+        .optional(),
+    input_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    output_sha256: z.null(),
+    truncated: z.literal(false),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.outcome === "return" && value.value === undefined)
+        context.addIssue({ code: "custom", message: "Return value is missing" });
+    if (value.outcome !== "return" && value.exception === undefined)
+        context.addIssue({ code: "custom", message: "Exception is missing" });
+    if (value.outcome === "return" && value.exception !== undefined)
+        context.addIssue({ code: "custom", message: "Return has an exception" });
+});
+const workerResponseSchema = z
+    .object({
+    schema_version: z.literal(1),
+    left: z.array(workerOutcomeSchema),
+    right: z.array(workerOutcomeSchema).optional(),
+})
+    .strict();
+/** Strictly authenticate case ordering and commitments in worker output. */
+export const parseReplayWorkerResponse = (rawResponse, cases, differential) => {
+    const response = workerResponseSchema.parse(rawResponse);
+    if ((response.right !== undefined) !== differential)
+        throw new TypeError("Replay worker differential response is incomplete");
+    validateOutcomeSequence(response.left, cases);
+    if (response.right !== undefined)
+        validateOutcomeSequence(response.right, cases);
+    return response;
+};
+const validateOutcomeSequence = (outcomes, cases) => {
+    if (outcomes.length !== cases.length)
+        throw new TypeError("Replay worker response case count changed");
+    outcomes.forEach((outcome, index) => {
+        const expected = cases[index];
+        if (expected === undefined ||
+            outcome.case_id !== expected.case_id ||
+            outcome.input_sha256 !== expected.sha256)
+            throw new TypeError("Replay worker response case identity changed");
+    });
+};