rea-agents 1.1.0 → 1.2.0

package/dist/application/ProcessCaptureLifecycle.js

@@ -0,0 +1,269 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { authorizeProcessScenario, digestProcessCommitment, processComparisonContract, processScenarioCommitment, } from "../domain/processCapture.js";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { snapshotRoots } from "./FilesystemSnapshot.js";
+import { cleanupOwnedProcessGroup, observeOwnedProcessGroup, } from "./ProcessOwnership.js";
+import { classifyFilesystemEffects, ProcessCheckpoints, } from "./ProcessCheckpoints.js";
+import { ProcessCaptureError } from "./ProcessCaptureError.js";
+import { assertNotCancelled, assertRealPathAuthority, } from "./ProcessCaptureAuthority.js";
+import { normalizeProcessSamples, normalizeProcessText, redactProtocolEvents, } from "./ProcessNormalization.js";
+import { PROCESS_PROVIDER } from "./ProcessEvidence.js";
+import { TerminalRenderer } from "./TerminalRenderer.js";
+export const buildCaptureResult = (options) => ({
+    schema_version: 4,
+    manifest: options.manifest,
+    normalization: options.scenario.normalization,
+    frames: options.frames,
+    rendered_frames: [...options.renderedFrames]
+        .sort((left, right) => left.at_ms - right.at_ms || left.sequence - right.sequence)
+        .map((frame, sequence) => ({ ...frame, sequence })),
+    interaction_events: options.interactions,
+    exit: {
+        code: options.exit.reason === "exited" && options.exit.exitCode >= 0
+            ? options.exit.exitCode
+            : null,
+        signal: options.exit.signal ?? null,
+        reason: options.exit.reason,
+    },
+    settlement: options.settlement,
+    process_samples: normalizeProcessSamples(options.samples, options.scenario, options.rootPid),
+    filesystem_checkpoints: options.checkpoints,
+    shim_events: options.shimEvents,
+    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 hashFile = async (path) => {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+};
+export const createRunManifest = async (scenario, startedAt, completedAt) => {
+    const executableSha256 = await hashFile(scenario.executable);
+    const scenarioCommitment = processScenarioCommitment(scenario, executableSha256);
+    const comparisonContract = processComparisonContract(scenario);
+    return {
+        rea_version: PRODUCT_IDENTITY.packageVersion,
+        provider_version: PROCESS_PROVIDER.version,
+        platform: process.platform,
+        architecture: process.arch,
+        pty_backend: "node-pty",
+        started_at: startedAt.toISOString(),
+        completed_at: completedAt.toISOString(),
+        scenario: scenarioCommitment,
+        comparison_contract: comparisonContract,
+        shim_plan: scenario.command_shims,
+        replay_plan: scenario.replay,
+        full_scenario_sha256: digestProcessCommitment(scenarioCommitment),
+        comparison_contract_sha256: digestProcessCommitment(comparisonContract),
+        executable_sha256: executableSha256,
+        normalization_sha256: digestProcessCommitment(scenario.normalization),
+        shim_plan_sha256: digestProcessCommitment(scenario.command_shims),
+        replay_plan_sha256: digestProcessCommitment(scenario.replay),
+    };
+};
+export const observeSettlement = async (runId, processGroupIds, settleMs) => {
+    if (process.platform === "win32")
+        return { state: "unverifiable", elapsed_ms: 0 };
+    const started = Date.now();
+    let consecutiveEmpty = 0;
+    let deadlineReached = false;
+    while (!deadlineReached) {
+        const observations = await Promise.all([...new Set(processGroupIds)].map((processGroupId) => observeOwnedProcessGroup({
+            runId,
+            leaderPid: processGroupId,
+            processGroupId,
+        })));
+        if (observations.some(({ state }) => state === "unverifiable"))
+            return { state: "unverifiable", elapsed_ms: Date.now() - started };
+        if (observations.every(({ state }) => state === "empty")) {
+            consecutiveEmpty += 1;
+            if (consecutiveEmpty >= 2)
+                return { state: "quiesced", elapsed_ms: Date.now() - started };
+        }
+        else
+            consecutiveEmpty = 0;
+        deadlineReached = Date.now() - started >= settleMs;
+        if (deadlineReached)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };
+};
+export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, interactions, dispatchedEventIndexes, }) => new Promise((resolveExit) => {
+    // The kill caused by a deadline is observed later as an ordinary PTY exit.
+    // Keep the initiating lifecycle reason so comparisons distinguish a target
+    // exit from harness-owned timeout, idle-timeout, and cancellation cleanup.
+    let reason = "exited";
+    terminal.onExit((exit) => {
+        for (const [eventIndex, event] of scenario.events.entries()) {
+            if (dispatchedEventIndexes.has(eventIndex))
+                continue;
+            interactions.push({
+                sequence: interactions.length,
+                scheduled_at_ms: event.at_ms,
+                dispatched_at_ms: Math.max(0, Date.now() - started),
+                type: event.type,
+                data: event.type === "input"
+                    ? "<not-dispatched>"
+                    : event.type === "resize"
+                        ? `${String(event.columns)}x${String(event.rows)}`
+                        : event.signal,
+                outcome: "target_exited",
+            });
+        }
+        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);
+});
+export 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";
+    }
+    try {
+        await options.shimReplay?.close();
+    }
+    catch {
+        failure ??= "command shim replay cleanup failed";
+    }
+    try {
+        await options.renderer?.dispose();
+    }
+    catch {
+        failure ??= "terminal renderer cleanup failed";
+    }
+    try {
+        await options.checkpoints?.dispose();
+    }
+    catch {
+        failure ??= "filesystem checkpoint cleanup failed";
+    }
+    if (options.terminal !== undefined && process.platform !== "win32") {
+        const processGroupIds = new Set([
+            options.terminal.pid,
+            ...options.sampledProcessGroupIds,
+        ]);
+        for (const processGroupId of processGroupIds) {
+            const cleaned = await cleanupOwnedProcessGroup({
+                runId: options.runId,
+                leaderPid: processGroupId,
+                processGroupId,
+            });
+            if (!cleaned.cleaned)
+                failure ??= cleaned.reason;
+        }
+    }
+    try {
+        await rm(options.temporaryRoot, { recursive: true, force: true });
+    }
+    catch {
+        failure ??= "temporary process root cleanup failed";
+    }
+    return failure;
+};
+export 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;
+        const atMs = Math.floor((Date.now() - options.started) /
+            options.scenario.normalization.time_bucket_ms) * options.scenario.normalization.time_bucket_ms;
+        const normalized = normalizeProcessText(data, options.scenario, options.temporaryRoot, options.terminal.pid);
+        options.frames.push({
+            sequence: options.frames.length,
+            at_ms: atMs,
+            data: normalized,
+        });
+        options.renderer.write(data, atMs);
+        options.checkpoints.observeTerminal(normalized);
+    });
+    return () => truncated;
+};
+export 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;
+};
+export 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 };
+};

package/dist/application/ProcessCheckpoints.js

@@ -0,0 +1,129 @@
+import { snapshotRoots } from "./FilesystemSnapshot.js";
+/** Classify path-stable filesystem effects between two bounded states. */
+export const classifyFilesystemEffects = (before, after) => {
+    const beforeByPath = new Map(before.map((file) => [file.path, file]));
+    const afterByPath = new Map(after.map((file) => [file.path, file]));
+    return [...new Set([...beforeByPath.keys(), ...afterByPath.keys()])]
+        .sort()
+        .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 };
+    });
+};
+/** Coordinates named lifecycle filesystem observations without overlapping scans. */
+export class ProcessCheckpoints {
+    scenario;
+    started;
+    signal;
+    #captures = [];
+    #captured = new Set();
+    #terminalCounts = new Map();
+    #terminalTails = new Map();
+    #timers = new Set();
+    #pending = Promise.resolve();
+    constructor(scenario, started, before, signal) {
+        this.scenario = scenario;
+        this.started = started;
+        this.signal = signal;
+        this.#captures.push({
+            name: "before",
+            at_ms: 0,
+            files: before.files,
+            effects: [],
+            truncated: before.truncated,
+        });
+        this.#captured.add("before");
+        for (const checkpoint of scenario.checkpoints) {
+            if (checkpoint.trigger.type !== "time")
+                continue;
+            const timer = setTimeout(() => this.capture(checkpoint.name), checkpoint.trigger.at_ms);
+            this.#timers.add(timer);
+        }
+    }
+    /** Observe normalized terminal text and fire matching literal checkpoints once. */
+    observeTerminal(data) {
+        for (const checkpoint of this.scenario.checkpoints) {
+            const trigger = checkpoint.trigger;
+            if (trigger.type !== "terminal_literal" ||
+                this.#captured.has(checkpoint.name))
+                continue;
+            const combined = `${this.#terminalTails.get(checkpoint.name) ?? ""}${data}`;
+            const count = (this.#terminalCounts.get(checkpoint.name) ?? 0) +
+                countOccurrences(combined, trigger.value);
+            this.#terminalCounts.set(checkpoint.name, count);
+            this.#terminalTails.set(checkpoint.name, trigger.value.length === 1
+                ? ""
+                : combined.slice(-(trigger.value.length - 1)));
+            if (count >= trigger.occurrence)
+                this.capture(checkpoint.name);
+        }
+    }
+    /** Capture every checkpoint assigned to the specified lifecycle trigger. */
+    trigger(type) {
+        for (const checkpoint of this.scenario.checkpoints)
+            if (checkpoint.trigger.type === type)
+                this.capture(checkpoint.name);
+    }
+    /** Queue one idempotent named snapshot. */
+    capture(name) {
+        if (this.#captured.has(name))
+            return;
+        this.#captured.add(name);
+        // Serialize scans even when time, terminal, and lifecycle triggers fire
+        // together. Each effect set is intentionally relative to the immediately
+        // preceding checkpoint, which preserves transient create/delete behavior.
+        this.#pending = this.#pending.then(async () => {
+            const snapshot = await snapshotRoots(this.scenario, this.signal);
+            const previous = this.#captures.at(-1)?.files ?? [];
+            this.#captures.push({
+                name,
+                at_ms: Math.max(0, Date.now() - this.started),
+                files: snapshot.files,
+                effects: classifyFilesystemEffects(previous, snapshot.files),
+                truncated: snapshot.truncated,
+            });
+        });
+    }
+    /** Finish pending snapshots and return them in observation order. */
+    async finish(after) {
+        for (const timer of this.#timers)
+            clearTimeout(timer);
+        await this.#pending;
+        const previous = this.#captures.at(-1)?.files ?? [];
+        this.#captures.push({
+            name: "after_settlement",
+            at_ms: Math.max(0, Date.now() - this.started),
+            files: after.files,
+            effects: classifyFilesystemEffects(previous, after.files),
+            truncated: after.truncated,
+        });
+        return this.#captures;
+    }
+    /** Cancel scheduled captures and await any snapshot already in progress. */
+    async dispose() {
+        for (const timer of this.#timers)
+            clearTimeout(timer);
+        this.#timers.clear();
+        await this.#pending;
+    }
+}
+const countOccurrences = (text, value) => {
+    let count = 0;
+    let offset = 0;
+    while (offset <= text.length - value.length) {
+        const found = text.indexOf(value, offset);
+        if (found < 0)
+            break;
+        count += 1;
+        offset = found + value.length;
+    }
+    return count;
+};

package/dist/application/ProcessCli.js

@@ -0,0 +1,61 @@
+import { readFile } from "node:fs/promises";
+import { parseConfig } from "../config.js";
+import { createEvidence, parseEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { compareProcessCaptures, LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessScenario, parseProcessCapture, } from "../domain/processCapture.js";
+import { captureProcessScenario } from "./ProcessHarness.js";
+import { PROCESS_PROVIDER, createProcessCaptureEvidence, } from "./ProcessEvidence.js";
+const MAX_INPUT_BYTES = 64 * 1024 * 1024;
+/** Capture one JSON scenario through the same policy and evidence contract as MCP. */
+export const captureProcessScenarioFile = async (path) => {
+    const scenario = parseProcessScenario(await readJson(path));
+    const config = parseConfig(process.env);
+    if (!config.ok)
+        throw config.error;
+    const captured = await captureProcessScenario(scenario, config.value.processExecutionPolicy);
+    if (!captured.ok)
+        throw captured.error;
+    return createProcessCaptureEvidence(scenario, captured.value);
+};
+/** Compare two capture Evidence files and emit derived comparison Evidence. */
+export const compareProcessEvidenceFiles = async (leftPath, rightPath) => {
+    const left = parseCaptureEvidence(await readJson(leftPath));
+    const right = parseCaptureEvidence(await readJson(rightPath));
+    const comparison = compareProcessCaptures(left.capture, right.capture);
+    return createEvidence(undefined, PROCESS_PROVIDER, {
+        predicateType: "rea.process-comparison/v3",
+        operation: "compare_process_captures",
+        parameters: {
+            left_evidence_id: left.id,
+            right_evidence_id: right.id,
+            left_normalization: left.capture.normalization,
+            right_normalization: right.capture.normalization,
+        },
+        result: jsonValueSchema.parse(comparison),
+        confidence: "derived",
+        authority: "analyst-inference",
+        limitations: comparison.limitations,
+        evidenceLinks: [left.id, right.id],
+    });
+};
+const parseCaptureEvidence = (input) => {
+    const evidence = parseEvidence(input);
+    if (evidence.operation !== "capture_process_scenario" ||
+        evidence.predicate_type !== "rea.process-capture/v4" ||
+        evidence.provider.id !== PROCESS_PROVIDER.id ||
+        evidence.provider.version !== PROCESS_PROVIDER.version) {
+        if (evidence.predicate_type === "rea.process-capture/v3")
+            throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);
+        throw new TypeError("Expected REA Process Capture v4 Evidence");
+    }
+    return {
+        id: evidence.evidence_id,
+        capture: parseProcessCapture(evidence.normalized_result),
+    };
+};
+const readJson = async (path) => {
+    const bytes = await readFile(path);
+    if (bytes.length > MAX_INPUT_BYTES)
+        throw new TypeError("Process JSON input exceeds byte limit");
+    return JSON.parse(bytes.toString("utf8"));
+};

package/dist/application/ProcessEvidence.js

@@ -0,0 +1,38 @@
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { parseProcessCapture } from "../domain/processCapture.js";
+/** Provider identity for controlled Process Capture v4 evidence. */
+export const PROCESS_PROVIDER = {
+    id: "rea-process",
+    name: "REA deterministic process harness",
+    version: "3",
+};
+/** Project one process scenario into secret-free Evidence parameters. */
+const processEvidenceParameters = (scenario) => ({
+    executable_name: scenario.executable.split("/").at(-1) ?? scenario.executable,
+    argument_count: scenario.arguments.length,
+    event_count: scenario.events.length,
+    filesystem_root_count: scenario.filesystem_roots.length,
+    checkpoint_count: scenario.checkpoints.length,
+    command_shim_count: scenario.command_shims.length,
+    normalization: scenario.normalization,
+});
+/** Create one canonical observed Process Capture v4 Evidence record. */
+export const createProcessCaptureEvidence = (scenario, capture) => {
+    const validatedCapture = parseProcessCapture(capture);
+    return createEvidence(undefined, PROCESS_PROVIDER, {
+        predicateType: "rea.process-capture/v4",
+        operation: "capture_process_scenario",
+        parameters: processEvidenceParameters(scenario),
+        result: jsonValueSchema.parse(validatedCapture),
+        confidence: "observed",
+        authority: "controlled-replay",
+        environment: {
+            id: `${process.platform}-${process.arch}`,
+            platform: process.platform,
+            architecture: process.arch,
+            isolation: "process",
+        },
+        limitations: validatedCapture.limitations,
+    });
+};