rea-agents 1.0.0 → 1.2.0

package/dist/application/ProcessHarness.js

@@ -1,63 +1,20 @@
-import { randomUUID } from "node:crypto";
-import { mkdtemp, realpath, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { spawn } from "node-pty";
-import { authorizeProcessScenario } from "../domain/processCapture.js";
+import { validateProcessCapture } from "../domain/processCapture.js";
 import { err, ok } from "../domain/result.js";
-import { AnalysisError } from "../domain/errors.js";
+import { ProcessCaptureError } from "./ProcessCaptureError.js";
+export { ProcessCaptureError } from "./ProcessCaptureError.js";
 import { startLoopbackReplay } from "./LoopbackReplay.js";
-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) => {
-    const executable = await realpath(scenario.executable);
-    const executableRoots = await Promise.all(policy.executableRoots.map((root) => realpath(root)));
-    if (!executableRoots.some((root) => isWithin(executable, root)))
-        throw new ProcessCaptureError("resolved executable is outside approved roots");
-    const workingDirectory = await realpath(scenario.working_directory);
-    const workingRoots = await Promise.all(policy.workingRoots.map((root) => realpath(root)));
-    if (!workingRoots.some((root) => isWithin(workingDirectory, root)))
-        throw new ProcessCaptureError("resolved working directory is outside approved roots");
-    for (const root of scenario.filesystem_roots) {
-        const resolvedRoot = await realpath(root);
-        if (!workingRoots.some((approved) => isWithin(resolvedRoot, approved)))
-            throw new ProcessCaptureError("resolved filesystem root is outside approved roots");
-    }
-};
-/** Expected refusal or runtime failure from the process capture adapter. */
-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 {
-        const terminal = spawn(process.platform === "win32" ? "cmd.exe" : "/bin/sh", process.platform === "win32" ? ["/c", "exit", "0"] : ["-c", "exit 0"], {
-            cwd: tmpdir(),
-            env: { HOME: tmpdir(), TERM: "xterm-256color" },
-            cols: 80,
-            rows: 24,
-            name: "xterm-256color",
-        });
-        await new Promise((resolveExit) => terminal.onExit(() => resolveExit()));
-        return { available: true, backend: "node-pty" };
-    }
-    catch {
-        return {
-            available: false,
-            backend: "node-pty",
-            reason: "the native PTY backend could not start a probe process",
-        };
-    }
-};
-const makeEnvironment = (scenario, home, replay, runId) => {
+import { ProcessCheckpoints } from "./ProcessCheckpoints.js";
+import { TerminalRenderer } from "./TerminalRenderer.js";
+import { startCommandShimReplay, } from "./CommandShimReplay.js";
+import { normalizeProcessText } from "./ProcessNormalization.js";
+import { awaitTerminalExit, buildCaptureResult, captureTerminalFrames, createRunManifest, observeSettlement, prepareProcessCapture, releaseProcessResources, resolveProcessResult, } from "./ProcessCaptureLifecycle.js";
+import { assertNotCancelled } from "./ProcessCaptureAuthority.js";
+export { probeProcessCaptureCapability } from "./ProcessCaptureCapability.js";
+const makeEnvironment = (options) => {
+    const { scenario, home, replay, shimReplay, runId } = options;
     const environment = {
         ...scenario.environment,
         HOME: home,
@@ -71,277 +28,300 @@ const makeEnvironment = (scenario, home, replay, runId) => {
     }
     environment.REA_REPLAY_HTTP_URL = replay.httpUrl;
     environment.REA_REPLAY_WEBSOCKET_URL = replay.websocketUrl;
+    environment.REA_SHIM_LEDGER_URL = shimReplay.url;
+    // PATH is evidence-producing input. Inheriting the host PATH here would let
+    // the authority and reconstruction probe different tools without recording
+    // that difference. Scenarios must opt in through environment or
+    // inherit_environment; deterministic shims always take precedence.
+    environment.PATH = [shimReplay.binPath, environment.PATH ?? ""]
+        .filter((part) => part.length > 0)
+        .join(":");
     return environment;
 };
-const scheduleScenarioEvents = (scenario, getTerminal, timers) => {
-    for (const event of scenario.events) {
+const scheduleScenarioEvents = (options) => {
+    const { scenario, getTerminal, timers, interactions, renderer, started } = options;
+    for (const [eventIndex, event] of scenario.events.entries()) {
         const timer = setTimeout(() => {
+            options.dispatchedEventIndexes.add(eventIndex);
             const terminal = getTerminal();
-            if (event.type === "input")
-                terminal?.write(event.data);
-            else if (event.type === "resize")
-                terminal?.resize(event.columns, event.rows);
-            else
-                terminal?.kill(event.signal);
+            const dispatchedAt = Math.max(0, Date.now() - started);
+            let outcome = "dispatched";
+            if (terminal === undefined)
+                outcome = "target_exited";
+            else {
+                try {
+                    if (event.type === "input")
+                        terminal.write(event.data);
+                    else if (event.type === "resize") {
+                        terminal.resize(event.columns, event.rows);
+                        renderer.resize(event.columns, event.rows, dispatchedAt);
+                    }
+                    else
+                        terminal.kill(event.signal);
+                }
+                catch {
+                    outcome = "failed";
+                }
+            }
+            interactions.push({
+                sequence: interactions.length,
+                scheduled_at_ms: event.at_ms,
+                dispatched_at_ms: dispatchedAt,
+                type: event.type,
+                data: event.type === "input"
+                    ? event.sensitive
+                        ? `<redacted-input:${String(Buffer.byteLength(event.data))}-bytes>`
+                        : normalizeProcessText(event.data, scenario, "<no-temporary-root>", -1)
+                    : event.type === "resize"
+                        ? `${String(event.columns)}x${String(event.rows)}`
+                        : event.signal,
+                outcome,
+            });
         }, event.at_ms);
         timers.add(timer);
     }
 };
-const startScenarioEvents = (scenario, getTerminal, timers) => {
-    let started = false;
+const startScenarioEvents = (options) => {
+    let eventsStarted = false;
     return () => {
-        if (started)
+        if (eventsStarted)
             return;
-        started = true;
-        scheduleScenarioEvents(scenario, getTerminal, timers);
+        eventsStarted = true;
+        scheduleScenarioEvents(options);
     };
 };
 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 cleanupFailedStartup = async (options) => {
+    options.terminal?.kill("SIGKILL");
+    const cleanupFailure = await releaseProcessResources({
+        ...options,
+        sampledProcessGroupIds: [],
     });
+    if (cleanupFailure !== undefined)
+        throw new ProcessCaptureError(cleanupFailure, { cause: options.cause });
+    throw options.cause;
 };
-const buildCaptureResult = (options) => ({
-    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: 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 createTerminalRenderer = (scenario, temporaryRoot, terminalPid) => new TerminalRenderer({
+    columns: scenario.terminal.columns,
+    rows: scenario.terminal.rows,
+    scrollback: scenario.terminal.scrollback,
+    maxFrames: scenario.limits.frames,
+    maxBytes: scenario.limits.output_bytes,
+    normalize: (value) => normalizeProcessText(value, scenario, temporaryRoot, terminalPid()),
 });
-const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, }) => new Promise((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 (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);
-});
-const releaseProcessResources = async (options) => {
-    for (const timer of options.timers)
-        clearTimeout(timer);
-    let failure;
+const startCaptureRuntime = async (options) => {
+    const { scenario } = options;
+    let replay;
+    let renderer;
+    let checkpoints;
+    let shimReplay;
+    let terminal;
     try {
-        await options.replay?.close();
-    }
-    catch {
-        failure = "loopback replay cleanup failed";
+        replay = await startLoopbackReplay(scenario);
+        const startedAt = new Date();
+        const started = Date.now();
+        let lastOutput = started;
+        renderer = createTerminalRenderer(scenario, options.temporaryRoot, () => terminal?.pid ?? -1);
+        checkpoints = new ProcessCheckpoints(scenario, started, options.before, options.signal);
+        shimReplay = await startCommandShimReplay(scenario, options.temporaryRoot, started);
+        terminal = spawn(scenario.executable, [...scenario.arguments], {
+            cwd: scenario.working_directory,
+            env: makeEnvironment({ ...options, replay, shimReplay }),
+            cols: scenario.terminal.columns,
+            rows: scenario.terminal.rows,
+            name: "xterm-256color",
+        });
+        const startEvents = startScenarioEvents({
+            ...options,
+            getTerminal: () => terminal,
+            renderer,
+            started,
+        });
+        if (!eventsRequireReadiness(scenario))
+            startEvents();
+        const framesTruncated = captureTerminalFrames({
+            ...options,
+            terminal,
+            started,
+            onOutput: () => (lastOutput = Date.now()),
+            onFirstOutput: startEvents,
+            renderer,
+            checkpoints,
+        });
+        const stopSampler = startProcessSampler(terminal.pid, started, scenario.limits.processes, options.samples);
+        return {
+            replay,
+            renderer,
+            checkpoints,
+            shimReplay,
+            terminal,
+            started,
+            startedAt,
+            lastOutput: () => lastOutput,
+            framesTruncated,
+            stopSampler,
+        };
     }
-    if (options.terminal !== undefined && process.platform !== "win32") {
-        const cleaned = await cleanupOwnedProcessGroup({
+    catch (cause) {
+        return cleanupFailedStartup({
+            cause,
+            timers: options.timers,
+            replay,
+            terminal,
+            renderer,
+            shimReplay,
+            checkpoints,
             runId: options.runId,
-            leaderPid: options.terminal.pid,
-            processGroupId: options.terminal.pid,
+            temporaryRoot: options.temporaryRoot,
         });
-        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),
-        });
+const normalizedShimEvents = (runtime, scenario, temporaryRoot) => runtime.shimReplay.events.map((event) => ({
+    ...event,
+    arguments: event.arguments.map((argument) => normalizeProcessText(argument, scenario, temporaryRoot, runtime.terminal.pid)),
+    working_directory: normalizeProcessText(event.working_directory, scenario, temporaryRoot, runtime.terminal.pid),
+}));
+const finishProcessRun = async (options) => {
+    await options.stopSampler();
+    const cleanupFailure = await releaseProcessResources({
+        timers: options.timers,
+        replay: options.runtime?.replay,
+        terminal: options.runtime?.terminal,
+        renderer: options.runtime?.renderer,
+        shimReplay: options.runtime?.shimReplay,
+        checkpoints: options.runtime?.checkpoints,
+        runId: options.runId,
+        temporaryRoot: options.temporaryRoot,
+        sampledProcessGroupIds: options.samples.flatMap(({ process_group_id }) => process_group_id === null ? [] : [process_group_id]),
     });
-    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;
+    let { capture, executionFailure } = options;
+    if (capture !== undefined) {
+        capture = {
+            ...capture,
+            settlement: {
+                ...capture.settlement,
+                cleanup_outcome: capture.settlement.state === "quiesced"
+                    ? "not_required"
+                    : cleanupFailure === undefined
+                        ? "cleaned"
+                        : "failed",
+            },
+        };
+        const issue = validateProcessCapture(capture)[0];
+        if (issue !== undefined)
+            executionFailure = new ProcessCaptureError(`process capture validation failed: ${issue.path}: ${issue.message}`);
+    }
+    return resolveProcessResult(capture, executionFailure, cleanupFailure);
 };
-const prepareProcessCapture = async (scenario, policy, signal) => {
-    const decision = authorizeProcessScenario(scenario, policy);
-    if (!decision.allowed)
-        throw new ProcessCaptureError(decision.reason);
-    await assertRealPathAuthority(scenario, policy);
-    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));
-    return { temporaryRoot, runId, home, before };
+const completeCapture = async (options) => {
+    const { runtime, scenario } = options;
+    runtime.checkpoints.trigger("root_exit");
+    const { reason } = options.exit;
+    if (reason === "cancelled")
+        throw new ProcessCaptureError("process capture was cancelled");
+    const settlement = await observeSettlement(options.runId, [
+        runtime.terminal.pid,
+        ...options.samples.flatMap(({ process_group_id }) => process_group_id === null ? [] : [process_group_id]),
+    ], scenario.settle_ms);
+    runtime.checkpoints.trigger("settled");
+    const samplingPartial = (await runtime.stopSampler()).partial;
+    assertNotCancelled(options.signal);
+    const after = await snapshotRoots(scenario, options.signal);
+    const renderedFrames = await runtime.renderer.frames();
+    const checkpoints = await runtime.checkpoints.finish(after);
+    const manifest = await createRunManifest(scenario, runtime.startedAt, new Date());
+    const truncated = options.initiallyTruncated ||
+        after.truncated ||
+        runtime.replay.truncated ||
+        runtime.shimReplay.truncated ||
+        runtime.framesTruncated() ||
+        checkpoints.some(({ truncated: partial }) => partial) ||
+        samplingPartial ||
+        runtime.renderer.truncated();
+    return buildCaptureResult({
+        frames: options.frames,
+        exit: { ...options.exit, reason },
+        samples: options.samples,
+        replay: runtime.replay,
+        before: options.before,
+        after,
+        truncated,
+        scenario,
+        rootPid: runtime.terminal.pid,
+        samplingPartial,
+        renderedFrames,
+        interactions: options.interactions,
+        checkpoints,
+        shimEvents: normalizedShimEvents(runtime, scenario, options.temporaryRoot),
+        settlement: { ...settlement, cleanup_outcome: "not_required" },
+        manifest,
+    });
 };
 /** 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 truncated = before.truncated;
-    let terminal;
-    let replay;
-    let started = 0;
-    let lastOutput = 0;
+    let runtime;
     const timers = new Set();
     let capture;
     let executionFailure;
-    let framesTruncated = () => false;
     let stopSampler = async () => ({ partial: false });
-    let samplingPartial = false;
+    const interactions = [];
+    const dispatchedEventIndexes = new Set();
     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, runId),
-            cols: 80,
-            rows: 24,
-            name: "xterm-256color",
-        });
-        const startEvents = startScenarioEvents(scenario, () => terminal, timers);
-        if (!eventsRequireReadiness(scenario))
-            startEvents();
-        framesTruncated = captureTerminalFrames({
-            terminal,
+        runtime = await startCaptureRuntime({
             scenario,
-            frames,
-            started,
+            home,
             temporaryRoot,
-            onOutput: () => (lastOutput = Date.now()),
-            onFirstOutput: startEvents,
+            runId,
+            before,
+            frames,
+            samples,
+            interactions,
+            timers,
+            dispatchedEventIndexes,
+            ...(signal === undefined ? {} : { signal }),
         });
-        stopSampler = startProcessSampler(terminal.pid, started, scenario.limits.processes, samples);
+        stopSampler = runtime.stopSampler;
         const exit = await awaitTerminalExit({
-            terminal,
+            terminal: runtime.terminal,
             scenario,
-            started,
-            lastOutput: () => lastOutput,
+            started: runtime.started,
+            lastOutput: runtime.lastOutput,
             signal,
             timers,
+            interactions,
+            dispatchedEventIndexes,
         });
-        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));
-        assertNotCancelled(signal);
-        const after = await snapshotRoots(scenario, signal);
-        truncated ||=
-            after.truncated ||
-                replay.truncated ||
-                framesTruncated() ||
-                samples.length >= scenario.limits.processes;
-        truncated ||= samplingPartial;
-        capture = buildCaptureResult({
+        capture = await completeCapture({
+            scenario,
+            runtime,
+            runId,
+            temporaryRoot,
+            before,
             frames,
-            exit: { ...exit, reason: exitReason },
             samples,
-            replay,
-            before,
-            after,
-            truncated,
-            scenario,
-            rootPid: terminal.pid,
-            samplingPartial,
+            interactions,
+            exit,
+            initiallyTruncated: before.truncated,
+            ...(signal === undefined ? {} : { signal }),
         });
     }
     catch (cause) {
-        terminal?.kill("SIGKILL");
+        runtime?.terminal.kill("SIGKILL");
         executionFailure = cause;
     }
-    samplingPartial ||= (await stopSampler()).partial;
-    const cleanupFailure = await releaseProcessResources({
+    return finishProcessRun({
+        runtime,
         timers,
-        replay,
-        terminal,
         runId,
         temporaryRoot,
+        samples,
+        stopSampler,
+        capture,
+        executionFailure,
     });
-    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

@@ -24,7 +24,12 @@ export const normalizeProcessText = (value, scenario, temporaryRoot, pid) => {
 export const normalizeProcessSamples = (samples, scenario, rootPid) => {
     const identifiers = [
         rootPid,
-        ...samples.flatMap((sample) => [sample.pid, sample.parent_pid]),
+        ...samples.flatMap((sample) => [
+            sample.pid,
+            sample.parent_pid,
+            sample.process_group_id ?? 0,
+            sample.session_id ?? 0,
+        ]),
     ];
     const mapping = new Map();
     for (const identifier of identifiers)
@@ -35,6 +40,10 @@ export const normalizeProcessSamples = (samples, scenario, rootPid) => {
             scenario.normalization.time_bucket_ms,
         pid: mapping.get(sample.pid) ?? 1,
         parent_pid: mapping.get(sample.parent_pid) ?? 0,
+        process_group_id: sample.process_group_id === null
+            ? null
+            : (mapping.get(sample.process_group_id) ?? 0),
+        session_id: sample.session_id === null ? null : (mapping.get(sample.session_id) ?? 0),
         command: normalizeProcessText(sample.command, scenario, "<no-temporary-root>", rootPid),
     }));
 };