rea-agents 0.2.1 → 0.4.0

package/dist/application/ProcessHarness.js

@@ -1,15 +1,16 @@
-import { createHash } from "node:crypto";
-import { lstat, mkdtemp, readdir, readFile, readlink, realpath, rm, } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { mkdtemp, realpath, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { join } from "node:path";
 import { spawn } from "node-pty";
 import { authorizeProcessScenario } from "../domain/processCapture.js";
 import { err, ok } from "../domain/result.js";
 import { AnalysisError } from "../domain/errors.js";
 import { startLoopbackReplay } from "./LoopbackReplay.js";
-const execFileAsync = promisify(execFile);
+import { cleanupOwnedProcessGroup } from "./ProcessOwnership.js";
+import { startProcessSampler } from "./ProcessSampling.js";
+import { snapshotRoots } from "./FilesystemSnapshot.js";
+import { normalizeProcessSamples, normalizeProcessText, redactProtocolEvents, } from "./ProcessNormalization.js";
 const isWithin = (candidate, root) => candidate === root ||
     candidate.startsWith(`${root.endsWith("/") ? root.slice(0, -1) : root}/`);
 const assertRealPathAuthority = async (scenario, policy) => {
@@ -31,6 +32,10 @@ const assertRealPathAuthority = async (scenario, policy) => {
 export class ProcessCaptureError extends AnalysisError {
     _tag = "ProcessCaptureError";
 }
+const assertNotCancelled = (signal) => {
+    if (signal?.aborted === true)
+        throw new ProcessCaptureError("process capture was cancelled");
+};
 /** Probe the actual native PTY seam instead of inferring support from the OS name. */
 export const probeProcessCaptureCapability = async () => {
     try {
@@ -52,110 +57,12 @@ export const probeProcessCaptureCapability = async () => {
         };
     }
 };
-const hashFile = async (path, maxBytes) => {
-    const value = await readFile(path);
-    if (value.byteLength > maxBytes)
-        return null;
-    return createHash("sha256").update(value).digest("hex");
-};
-const snapshotRoots = async (scenario) => {
-    const entries = [];
-    let remainingBytes = scenario.limits.file_bytes;
-    let truncated = false;
-    const visit = async (root, path) => {
-        if (entries.length >= scenario.limits.files) {
-            truncated = true;
-            return;
-        }
-        let stats;
-        try {
-            stats = await lstat(path);
-        }
-        catch (error) {
-            if (error instanceof Error && "code" in error && error.code === "ENOENT")
-                return;
-            throw error;
-        }
-        const relativePath = relative(root, path) || ".";
-        if (stats.isSymbolicLink()) {
-            entries.push({
-                path: `${root}:${relativePath}`,
-                type: "symlink",
-                mode: stats.mode,
-                size: stats.size,
-                sha256: null,
-                symlink_target: await readlink(path),
-            });
-            return;
-        }
-        if (stats.isFile()) {
-            const allowedBytes = Math.max(0, Math.min(remainingBytes, scenario.limits.file_bytes));
-            const sha256 = allowedBytes >= stats.size ? await hashFile(path, allowedBytes) : null;
-            remainingBytes -= sha256 === null ? 0 : stats.size;
-            if (sha256 === null)
-                truncated = true;
-            entries.push({
-                path: `${root}:${relativePath}`,
-                type: "file",
-                mode: stats.mode,
-                size: stats.size,
-                sha256,
-                symlink_target: null,
-            });
-            return;
-        }
-        const type = stats.isDirectory() ? "directory" : "other";
-        entries.push({
-            path: `${root}:${relativePath}`,
-            type,
-            mode: stats.mode,
-            size: stats.size,
-            sha256: null,
-            symlink_target: null,
-        });
-        if (type !== "directory")
-            return;
-        for (const child of (await readdir(path)).sort())
-            await visit(root, join(path, child));
-    };
-    for (const root of scenario.filesystem_roots)
-        await visit(root, root);
-    return { files: entries, truncated };
-};
-const sampleProcesses = async (rootPid, elapsedMs, limit) => {
-    if (process.platform === "win32")
-        return [];
-    const { stdout } = await execFileAsync("ps", ["-axo", "pid=,ppid=,command="]);
-    const rows = stdout
-        .split("\n")
-        .map((line) => /\s*(\d+)\s+(\d+)\s+(.*)/.exec(line))
-        .filter((match) => match !== null)
-        .map((match) => ({
-        pid: Number(match[1]),
-        parent_pid: Number(match[2]),
-        command: match[3] ?? "",
-    }));
-    const owned = new Set([rootPid]);
-    let changed = true;
-    while (changed) {
-        changed = false;
-        for (const row of rows) {
-            if (owned.has(row.parent_pid) && !owned.has(row.pid)) {
-                owned.add(row.pid);
-                changed = true;
-            }
-        }
-    }
-    return rows
-        .filter((row) => owned.has(row.pid))
-        .slice(0, limit)
-        .map((row) => ({ at_ms: elapsedMs, ...row }));
-};
-const makeEnvironment = (scenario, home, replay) => {
+const makeEnvironment = (scenario, home, replay, runId) => {
     const environment = {
+        ...scenario.environment,
         HOME: home,
         TERM: "xterm-256color",
-        ...scenario.environment,
+        REA_PROCESS_RUN_ID: runId,
     };
     for (const name of scenario.inherit_environment) {
         const value = process.env[name];
@@ -166,23 +73,6 @@ const makeEnvironment = (scenario, home, replay) => {
     environment.REA_REPLAY_WEBSOCKET_URL = replay.websocketUrl;
     return environment;
 };
-const normalizeTerminalData = (value, scenario, temporaryRoot, pid) => {
-    let normalized = value;
-    for (const alias of scenario.secret_aliases) {
-        const secret = scenario.environment[alias];
-        if (secret !== undefined && secret.length > 0)
-            normalized = normalized.replaceAll(secret, "<redacted>");
-    }
-    if (scenario.normalization.paths)
-        normalized = normalized.replaceAll(temporaryRoot, "<temporary-root>");
-    if (scenario.normalization.pids)
-        normalized = normalized.replaceAll(String(pid), "<pid>");
-    if (scenario.normalization.ports)
-        normalized = normalized.replaceAll(/(?<=[:=])\d{2,5}\b/g, "<port>");
-    for (const pattern of scenario.normalization.patterns)
-        normalized = normalized.replaceAll(pattern.pattern, pattern.replacement);
-    return normalized;
-};
 const scheduleScenarioEvents = (scenario, getTerminal, timers) => {
     for (const event of scenario.events) {
         const timer = setTimeout(() => {
@@ -197,108 +87,214 @@ const scheduleScenarioEvents = (scenario, getTerminal, timers) => {
         timers.add(timer);
     }
 };
-const normalizeSamples = (samples, scenario, rootPid) => {
-    const identifiers = [
-        rootPid,
-        ...samples.flatMap((sample) => [sample.pid, sample.parent_pid]),
-    ];
-    const mapping = new Map();
-    for (const identifier of identifiers)
-        if (identifier > 0 && !mapping.has(identifier))
-            mapping.set(identifier, mapping.size + 1);
-    return samples.map((sample) => ({
-        at_ms: Math.floor(sample.at_ms / scenario.normalization.time_bucket_ms) *
-            scenario.normalization.time_bucket_ms,
-        pid: mapping.get(sample.pid) ?? 1,
-        parent_pid: mapping.get(sample.parent_pid) ?? 0,
-        command: normalizeTerminalData(sample.command, scenario, "<no-temporary-root>", rootPid),
-    }));
+const startScenarioEvents = (scenario, getTerminal, timers) => {
+    let started = false;
+    return () => {
+        if (started)
+            return;
+        started = true;
+        scheduleScenarioEvents(scenario, getTerminal, timers);
+    };
+};
+const eventsRequireReadiness = (scenario) => scenario.events.some((event) => event.type === "input" || event.type === "resize");
+const classifyFilesystemEffects = (before, after) => {
+    const beforeByPath = new Map(before.map((file) => [file.path, file]));
+    const afterByPath = new Map(after.map((file) => [file.path, file]));
+    const paths = [
+        ...new Set([...beforeByPath.keys(), ...afterByPath.keys()]),
+    ].sort();
+    return paths.map((path) => {
+        const beforeFile = beforeByPath.get(path) ?? null;
+        const afterFile = afterByPath.get(path) ?? null;
+        const status = beforeFile === null
+            ? "created"
+            : afterFile === null
+                ? "deleted"
+                : JSON.stringify(beforeFile) === JSON.stringify(afterFile)
+                    ? "unchanged"
+                    : "modified";
+        return { path, status, before: beforeFile, after: afterFile };
+    });
 };
-const redactProtocolEvents = (events, scenario) => events.map((event) => ({
-    ...event,
-    data: normalizeTerminalData(event.data, scenario, "<no-temporary-root>", -1),
-}));
 const buildCaptureResult = (options) => ({
-    schema_version: 1,
+    schema_version: 2,
+    normalization: options.scenario.normalization,
     frames: options.frames,
     exit: {
         code: options.exit.exitCode < 0 ? null : options.exit.exitCode,
         signal: options.exit.signal ?? null,
+        reason: options.exit.reason,
     },
-    process_samples: normalizeSamples(options.samples, options.scenario, options.rootPid),
+    process_samples: normalizeProcessSamples(options.samples, options.scenario, options.rootPid),
     protocol_events: redactProtocolEvents(options.replay.events, options.scenario),
     files_before: options.before.files,
     files_after: options.after.files,
+    filesystem_effects: classifyFilesystemEffects(options.before.files, options.after.files),
     truncated: options.truncated,
     limitations: [
         "Process trees are sampled and may omit short-lived descendants.",
+        ...(options.samplingPartial
+            ? ["Process-tree sampling ended with an incomplete observation."]
+            : []),
         "Filesystem observations are before/after snapshots, not syscall traces.",
         "The harness does not enforce external network isolation.",
     ],
+    residual_unknowns: [
+        {
+            scope: "process",
+            reason: "Process trees are sampled and may omit short-lived descendants.",
+        },
+        {
+            scope: "network",
+            reason: "External network isolation is not enforced by this adapter.",
+        },
+    ],
+    cleanup: {
+        owned_process_group: "verified",
+        temporary_root: "removed",
+    },
 });
 const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, }) => new Promise((resolveExit) => {
-    terminal.onExit(resolveExit);
+    let reason = "exited";
+    terminal.onExit((exit) => {
+        for (const timer of timers) {
+            clearTimeout(timer);
+            clearInterval(timer);
+        }
+        timers.clear();
+        resolveExit({ ...exit, reason });
+    });
     const timeout = setInterval(() => {
-        if (Date.now() - started >= scenario.timeout_ms ||
-            Date.now() - lastOutput() >= scenario.idle_timeout_ms ||
-            signal?.aborted === true) {
+        if (signal?.aborted === true) {
+            reason = "cancelled";
+            terminal.kill("SIGKILL");
+        }
+        else if (Date.now() - started >= scenario.timeout_ms) {
+            reason = "timeout";
+            terminal.kill("SIGKILL");
+        }
+        else if (Date.now() - lastOutput() >= scenario.idle_timeout_ms) {
+            reason = "idle_timeout";
             terminal.kill("SIGKILL");
         }
     }, 20);
     timers.add(timeout);
 });
-/** Execute one authorized scenario and return bounded observations. */
-const runProcessScenario = async (scenario, policy, signal) => {
+const releaseProcessResources = async (options) => {
+    for (const timer of options.timers)
+        clearTimeout(timer);
+    let failure;
+    try {
+        await options.replay?.close();
+    }
+    catch {
+        failure = "loopback replay cleanup failed";
+    }
+    if (options.terminal !== undefined && process.platform !== "win32") {
+        const cleaned = await cleanupOwnedProcessGroup({
+            runId: options.runId,
+            leaderPid: options.terminal.pid,
+            processGroupId: options.terminal.pid,
+        });
+        if (!cleaned.cleaned)
+            failure ??= cleaned.reason;
+    }
+    try {
+        await rm(options.temporaryRoot, { recursive: true, force: true });
+    }
+    catch {
+        failure ??= "temporary process root cleanup failed";
+    }
+    return failure;
+};
+const captureTerminalFrames = (options) => {
+    let outputBytes = 0;
+    let truncated = false;
+    options.terminal.onData((data) => {
+        options.onFirstOutput();
+        options.onOutput();
+        const bytes = Buffer.byteLength(data);
+        if (options.frames.length >= options.scenario.limits.frames ||
+            outputBytes + bytes > options.scenario.limits.output_bytes) {
+            truncated = true;
+            return;
+        }
+        outputBytes += bytes;
+        options.frames.push({
+            sequence: options.frames.length,
+            at_ms: Math.floor((Date.now() - options.started) /
+                options.scenario.normalization.time_bucket_ms) * options.scenario.normalization.time_bucket_ms,
+            data: normalizeProcessText(data, options.scenario, options.temporaryRoot, options.terminal.pid),
+        });
+    });
+    return () => truncated;
+};
+const resolveProcessResult = (capture, executionFailure, cleanupFailure) => {
+    if (executionFailure instanceof ProcessCaptureError)
+        throw executionFailure;
+    if (executionFailure !== undefined)
+        throw new ProcessCaptureError("process capture failed", {
+            cause: executionFailure,
+        });
+    if (cleanupFailure !== undefined)
+        throw new ProcessCaptureError(cleanupFailure);
+    if (capture === undefined)
+        throw new ProcessCaptureError("process capture produced no result");
+    return capture;
+};
+const prepareProcessCapture = async (scenario, policy, signal) => {
     const decision = authorizeProcessScenario(scenario, policy);
     if (!decision.allowed)
         throw new ProcessCaptureError(decision.reason);
     await assertRealPathAuthority(scenario, policy);
-    if (signal?.aborted === true)
-        throw new ProcessCaptureError("process capture was cancelled");
+    assertNotCancelled(signal);
+    const before = await snapshotRoots(scenario, signal);
     const temporaryRoot = await mkdtemp(join(tmpdir(), "rea-process-"));
+    const runId = randomUUID();
     const home = join(temporaryRoot, "home");
     await import("node:fs/promises").then(({ mkdir }) => mkdir(home));
-    const before = await snapshotRoots(scenario);
+    return { temporaryRoot, runId, home, before };
+};
+/** Execute one authorized scenario and return bounded observations. */
+const runProcessScenario = async (scenario, policy, signal) => {
+    const { temporaryRoot, runId, home, before } = await prepareProcessCapture(scenario, policy, signal);
     const frames = [];
     const samples = [];
-    let outputBytes = 0;
     let truncated = before.truncated;
     let terminal;
     let replay;
-    const started = Date.now();
-    let lastOutput = started;
+    let started = 0;
+    let lastOutput = 0;
     const timers = new Set();
+    let capture;
+    let executionFailure;
+    let framesTruncated = () => false;
+    let stopSampler = async () => ({ partial: false });
+    let samplingPartial = false;
     try {
         replay = await startLoopbackReplay(scenario);
+        started = Date.now();
+        lastOutput = started;
         terminal = spawn(scenario.executable, [...scenario.arguments], {
             cwd: scenario.working_directory,
-            env: makeEnvironment(scenario, home, replay),
+            env: makeEnvironment(scenario, home, replay, runId),
             cols: 80,
             rows: 24,
             name: "xterm-256color",
         });
-        terminal.onData((data) => {
-            lastOutput = Date.now();
-            const bytes = Buffer.byteLength(data);
-            if (frames.length >= scenario.limits.frames ||
-                outputBytes + bytes > scenario.limits.output_bytes) {
-                truncated = true;
-                return;
-            }
-            outputBytes += bytes;
-            frames.push({
-                sequence: frames.length,
-                at_ms: Math.floor((Date.now() - started) / scenario.normalization.time_bucket_ms) * scenario.normalization.time_bucket_ms,
-                data: normalizeTerminalData(data, scenario, temporaryRoot, terminal?.pid ?? -1),
-            });
+        const startEvents = startScenarioEvents(scenario, () => terminal, timers);
+        if (!eventsRequireReadiness(scenario))
+            startEvents();
+        framesTruncated = captureTerminalFrames({
+            terminal,
+            scenario,
+            frames,
+            started,
+            temporaryRoot,
+            onOutput: () => (lastOutput = Date.now()),
+            onFirstOutput: startEvents,
         });
-        scheduleScenarioEvents(scenario, () => terminal, timers);
-        const sampler = setInterval(() => {
-            void sampleProcesses(terminal?.pid ?? -1, Date.now() - started, scenario.limits.processes - samples.length)
-                .then((values) => samples.push(...values))
-                .catch(() => undefined);
-        }, 50);
-        timers.add(sampler);
+        stopSampler = startProcessSampler(terminal.pid, started, scenario.limits.processes, samples);
         const exit = await awaitTerminalExit({
             terminal,
             scenario,
@@ -307,13 +303,22 @@ const runProcessScenario = async (scenario, policy, signal) => {
             signal,
             timers,
         });
+        const exitReason = exit.reason;
+        samplingPartial = (await stopSampler()).partial;
+        if (exitReason === "cancelled")
+            throw new ProcessCaptureError("process capture was cancelled");
         await new Promise((resolveSettle) => setTimeout(resolveSettle, scenario.settle_ms));
-        const after = await snapshotRoots(scenario);
+        assertNotCancelled(signal);
+        const after = await snapshotRoots(scenario, signal);
         truncated ||=
-            after.truncated || samples.length >= scenario.limits.processes;
-        return buildCaptureResult({
+            after.truncated ||
+                replay.truncated ||
+                framesTruncated() ||
+                samples.length >= scenario.limits.processes;
+        truncated ||= samplingPartial;
+        capture = buildCaptureResult({
             frames,
-            exit,
+            exit: { ...exit, reason: exitReason },
             samples,
             replay,
             before,
@@ -321,18 +326,22 @@ const runProcessScenario = async (scenario, policy, signal) => {
             truncated,
             scenario,
             rootPid: terminal.pid,
+            samplingPartial,
         });
     }
     catch (cause) {
         terminal?.kill("SIGKILL");
-        throw new ProcessCaptureError("process capture failed", { cause });
-    }
-    finally {
-        for (const timer of timers)
-            clearTimeout(timer);
-        await replay?.close();
-        await rm(temporaryRoot, { recursive: true, force: true });
+        executionFailure = cause;
     }
+    samplingPartial ||= (await stopSampler()).partial;
+    const cleanupFailure = await releaseProcessResources({
+        timers,
+        replay,
+        terminal,
+        runId,
+        temporaryRoot,
+    });
+    return resolveProcessResult(capture, executionFailure, cleanupFailure);
 };
 /** Execute one scenario through a typed expected-failure channel. */
 export const captureProcessScenario = async (scenario, policy, signal) => {

package/dist/application/ProcessNormalization.js

@@ -0,0 +1,44 @@
+/** Normalize and redact one terminal/protocol payload under scenario rules. */
+export const normalizeProcessText = (value, scenario, temporaryRoot, pid) => {
+    let normalized = value;
+    for (const alias of scenario.secret_aliases) {
+        const secret = scenario.environment[alias];
+        if (secret !== undefined && secret.length > 0)
+            normalized = normalized.replaceAll(secret, "<redacted>");
+    }
+    if (scenario.normalization.paths) {
+        normalized = normalized.replaceAll(temporaryRoot, "<temporary-root>");
+        normalized = normalized.replaceAll(scenario.working_directory, "<working-directory>");
+        normalized = normalized.replaceAll(scenario.executable, "<executable>");
+        for (const [index, root] of scenario.filesystem_roots.entries())
+            normalized = normalized.replaceAll(root, `<filesystem-root-${String(index)}>`);
+    }
+    if (scenario.normalization.pids)
+        normalized = normalized.replaceAll(String(pid), "<pid>");
+    if (scenario.normalization.ports)
+        normalized = normalized.replaceAll(/(?<=[:=])\d{2,5}\b/g, "<port>");
+    for (const pattern of scenario.normalization.patterns)
+        normalized = normalized.replaceAll(pattern.pattern, pattern.replacement);
+    return normalized;
+};
+export const normalizeProcessSamples = (samples, scenario, rootPid) => {
+    const identifiers = [
+        rootPid,
+        ...samples.flatMap((sample) => [sample.pid, sample.parent_pid]),
+    ];
+    const mapping = new Map();
+    for (const identifier of identifiers)
+        if (identifier > 0 && !mapping.has(identifier))
+            mapping.set(identifier, mapping.size + 1);
+    return samples.map((sample) => ({
+        at_ms: Math.floor(sample.at_ms / scenario.normalization.time_bucket_ms) *
+            scenario.normalization.time_bucket_ms,
+        pid: mapping.get(sample.pid) ?? 1,
+        parent_pid: mapping.get(sample.parent_pid) ?? 0,
+        command: normalizeProcessText(sample.command, scenario, "<no-temporary-root>", rootPid),
+    }));
+};
+export const redactProtocolEvents = (events, scenario) => events.map((event) => ({
+    ...event,
+    data: normalizeProcessText(event.data, scenario, "<no-temporary-root>", -1),
+}));

package/dist/application/ProcessOwnership.js

@@ -0,0 +1,84 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const parseEnvironment = (value) => Object.fromEntries(value
+    .split("\0")
+    .filter((entry) => entry.includes("="))
+    .map((entry) => {
+    const separator = entry.indexOf("=");
+    return [entry.slice(0, separator), entry.slice(separator + 1)];
+}));
+const systemHost = {
+    async listMembers(processGroupId) {
+        if (process.platform === "win32")
+            return [];
+        const { stdout } = await execFileAsync("ps", [
+            "-axo",
+            "pid=,ppid=,pgid=,command=",
+        ]);
+        return stdout
+            .split("\n")
+            .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(.*)/u.exec(line))
+            .filter((match) => match !== null)
+            .map((match) => ({
+            pid: Number(match[1]),
+            parentPid: Number(match[2]),
+            processGroupId: Number(match[3]),
+            command: match[4] ?? "",
+        }))
+            .filter((member) => member.processGroupId === processGroupId);
+    },
+    async environment(pid) {
+        if (process.platform === "linux") {
+            return parseEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
+        }
+        const { stdout } = await execFileAsync("ps", ["eww", "-p", String(pid)]);
+        const environment = {};
+        for (const match of stdout.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s]*)/gu))
+            environment[match[1]] = match[2] ?? "";
+        return environment;
+    },
+    signalGroup(processGroupId, signal) {
+        process.kill(-processGroupId, signal);
+    },
+};
+/** Verify run-token ownership before signaling a POSIX process group. */
+export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) => {
+    let members;
+    try {
+        members = await host.listMembers(ownership.processGroupId);
+    }
+    catch {
+        return { cleaned: false, reason: "process group could not be inspected" };
+    }
+    if (members.length === 0)
+        return { cleaned: true, signaled: false };
+    for (const member of members) {
+        let environment;
+        try {
+            environment = await host.environment(member.pid);
+        }
+        catch {
+            return {
+                cleaned: false,
+                reason: "process ownership could not be revalidated",
+            };
+        }
+        if (environment.REA_PROCESS_RUN_ID !== ownership.runId) {
+            return {
+                cleaned: false,
+                reason: "process group contains an unowned or PID-reused process",
+            };
+        }
+    }
+    try {
+        host.signalGroup(ownership.processGroupId, "SIGKILL");
+    }
+    catch (cause) {
+        const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
+        if (code !== "ESRCH")
+            return { cleaned: false, reason: "owned process group signal failed" };
+    }
+    return { cleaned: true, signaled: true };
+};