rea-agents 3.2.1 → 4.0.0

package/dist/application/ProcessCaptureLifecycle.js

@@ -1,94 +1,128 @@
 import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+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 { digestProcessCommitment, processComparisonContract, processScenarioCommitment, } from "../domain/processCapture.js";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { snapshotRoots } from "./FilesystemSnapshot.js";
+import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
 import { cleanupOwnedProcessGroup, observeOwnedProcessGroup, } from "../process/ProcessOwnership.js";
-import { classifyFilesystemEffects, ProcessCheckpoints, } from "./ProcessCheckpoints.js";
 import { ProcessCaptureError } from "./ProcessCaptureError.js";
-import { assertNotCancelled, assertRealPathAuthority, } from "./ProcessCaptureAuthority.js";
-import { normalizeProcessElapsedTime, normalizeProcessSamples, normalizeProcessText, redactProtocolEvents, } from "./ProcessNormalization.js";
+import { assertNotCancelled } from "./ProcessScenarioRuntimeValidation.js";
+import { normalizeProcessElapsedTime, normalizeProcessSamples, normalizeProcessText, } from "./ProcessNormalization.js";
 import { PROCESS_PROVIDER } from "./ProcessEvidence.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
 import { scheduleProcessInterval } from "./ProcessTimer.js";
-export const buildCaptureResult = (options) => ({
-    manifest: options.manifest,
-    normalization: options.scenario.normalization,
-    frames: options.frames,
-    rendered_frames: options.renderedFrames,
-    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),
-    replay_transitions: options.replay.transitions,
-    event_journal: options.eventJournal,
-    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.",
+/** Wait for trailing PTY callbacks before the capture becomes immutable. */
+export const settleProcessCaptureJournal = async (journal, quietMs = 25, maxWaitMs = 500) => {
+    const deadline = Date.now() + maxWaitMs;
+    let observed = journal.length;
+    let lastChangeAt = Date.now();
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 4));
+        if (journal.length !== observed) {
+            observed = journal.length;
+            lastChangeAt = Date.now();
+        }
+        else if (Date.now() - lastChangeAt >= quietMs)
+            return;
+    }
+};
+export const buildCaptureResult = (options) => {
+    const hasSensitiveScriptedInput = options.scenario.events.some((event) => event.type === "input" && event.sensitive);
+    const sensitiveInputUnknown = "Sensitive scripted input values are redacted from process capture Evidence.";
+    const filesystemObservationUnknown = "No filesystem observation paths were selected; filesystem effects remain unknown.";
+    const hasFilesystemObservations = options.scenario.filesystem_observation_paths.length > 0;
+    return {
+        manifest: options.manifest,
+        normalization: options.scenario.normalization,
+        frames: options.frames,
+        rendered_frames: options.renderedFrames,
+        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,
+        event_journal: options.eventJournal,
+        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.",
+            "Inherited host environment variables are not recorded and may affect results.",
+            ...(!hasFilesystemObservations ? [filesystemObservationUnknown] : []),
+            ...(hasSensitiveScriptedInput ? [sensitiveInputUnknown] : []),
+        ],
+        residual_unknowns: [
+            {
+                scope: "process",
+                reason: "Process trees are sampled and may omit short-lived descendants.",
+            },
+            {
+                scope: "environment",
+                reason: "Inherited host environment variables are not recorded.",
+            },
+            {
+                scope: "network",
+                reason: "Network activity is not observed by this capture.",
+            },
+            ...(!hasFilesystemObservations
+                ? [
+                    {
+                        scope: "filesystem",
+                        reason: filesystemObservationUnknown,
+                    },
+                ]
+                : []),
+            ...(hasSensitiveScriptedInput
+                ? [{ scope: "interaction", reason: sensitiveInputUnknown }]
+                : []),
+        ],
+    };
+};
 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) => {
+export const createRunManifest = async (scenario, startedAt, completedAt, host = {
+    platform: process.platform,
+    architecture: process.arch,
+}) => {
     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,
+        platform: host.platform,
+        architecture: host.architecture,
         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, recordEvent = () => undefined) => {
-    if (process.platform === "win32") {
+export const observeSettlement = async (runId, processGroupIds, settleMs, recordEvent = () => undefined, platform = process.platform) => {
+    if (platform === "win32") {
         recordEvent("lifecycle", 1);
         return { state: "unverifiable", elapsed_ms: 0 };
     }
@@ -169,37 +203,25 @@ export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutpu
     }, 20);
     timers.add(timeout);
 });
+const processCaptureCleanupHost = {
+    platform: process.platform,
+    cleanupProcessGroup: cleanupOwnedProcessGroup,
+    removeTemporaryRoot: (path) => rm(path, { recursive: true, force: true }),
+};
 export const releaseProcessResources = async (options) => {
+    const host = options.host ?? processCaptureCleanupHost;
     for (const timer of options.timers)
         timer.cancel();
     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") {
+    if (options.terminal !== undefined && host.platform !== "win32") {
         for (const processGroupId of new Set(options.capturedProcessGroupIds)) {
-            const cleaned = await cleanupOwnedProcessGroup({
+            const cleaned = await host.cleanupProcessGroup({
                 runId: options.runId,
                 leaderPid: processGroupId,
                 processGroupId,
@@ -209,7 +231,7 @@ export const releaseProcessResources = async (options) => {
         }
     }
     try {
-        await rm(options.temporaryRoot, { recursive: true, force: true });
+        await host.removeTemporaryRoot(options.temporaryRoot);
     }
     catch {
         failure ??= "temporary process root cleanup failed";
@@ -235,9 +257,8 @@ export const captureTerminalFrames = (options) => {
             at_ms: atMs,
             data: normalized,
         });
-        options.recordEvent("frames", sequence);
         options.renderer.write(data, atMs);
-        options.checkpoints.observeTerminal(normalized);
+        options.recordEvent("frames", sequence);
     });
     return () => truncated;
 };
@@ -256,27 +277,13 @@ export const resolveProcessResult = (capture, executionFailure, cleanupFailure)
         throw new ProcessCaptureError("process capture produced no result");
     return capture;
 };
-export const prepareProcessCapture = async (scenario, policy, signal, host = systemProcessPreparationHost) => {
-    if (policy.status === "disabled")
-        throw new ProcessCaptureError("process capture is disabled", {
-            userCategory: "permission_required",
-            userMessage: processPolicyMessage("process capture is disabled"),
-        });
-    const decision = authorizeProcessScenario(scenario, policy);
-    if (!decision.allowed)
-        throw new ProcessCaptureError(decision.reason, {
-            userCategory: "permission_required",
-            userMessage: processPolicyMessage(decision.reason),
-        });
-    await assertRealPathAuthority(scenario, policy);
+export const prepareProcessCapture = async (scenario, signal, host = systemProcessPreparationHost) => {
     assertNotCancelled(signal);
     const before = await snapshotRoots(scenario, signal);
     const temporaryRoot = await host.createTemporaryRoot();
     try {
         const runId = randomUUID();
-        const home = join(temporaryRoot, "home");
-        await host.createHome(home);
-        return { temporaryRoot, runId, home, before };
+        return { temporaryRoot, runId, before };
     }
     catch (cause) {
         await host.cleanup(temporaryRoot);
@@ -285,21 +292,5 @@ export const prepareProcessCapture = async (scenario, policy, signal, host = sys
 };
 const systemProcessPreparationHost = {
     createTemporaryRoot: () => mkdtemp(join(tmpdir(), "rea-process-")),
-    createHome: (path) => mkdir(path),
     cleanup: (path) => rm(path, { recursive: true, force: true }),
 };
-const processPolicyMessage = (reason) => {
-    if (reason === "process capture is disabled")
-        return "Process capture is disabled. Set `REA_PROCESS_CAPTURE_ENABLED=true`, configure approved roots, then restart REA.";
-    if (reason === "host network access is not approved by operator policy")
-        return "This capture requests host network access, but policy does not allow it. Use replayed network access or ask the operator to enable external network capture.";
-    if (reason === "executable is outside approved roots")
-        return "The executable is outside the approved capture directories. Choose an approved executable or add its directory to `REA_PROCESS_EXECUTABLE_ROOTS_JSON`.";
-    if (reason === "working directory is outside approved roots")
-        return "The working directory is outside the approved capture directories. Choose an approved directory or add it to `REA_PROCESS_WORKING_ROOTS_JSON`.";
-    if (reason === "filesystem root is outside approved roots")
-        return "A requested filesystem root is outside the approved capture directories. Remove it or add its directory to `REA_PROCESS_WORKING_ROOTS_JSON`.";
-    if (reason === "scenario requests an environment variable not allowed by policy")
-        return "The capture requests an environment variable that policy does not allow. Remove it or add its name to `REA_PROCESS_ALLOWED_ENV_JSON`.";
-    return reason;
-};

package/dist/application/ProcessCli.js

@@ -1,40 +1,33 @@
-import { projectPermissionFailure } from "./PermissionFailure.js";
 import { readFile } from "node:fs/promises";
-import { parseConfig } from "../config.js";
 import { AnalysisError, AnalysisInputError, projectAnalysisError, } from "../domain/errors.js";
 import { createEvidence, parseEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { projectInputIssues } from "../domain/inputIssueProjection.js";
 import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
-import { compareProcessCaptures, parseProcessScenario, parseProcessCapture, } from "../domain/processCapture.js";
+import { processScenarioSchema } from "../domain/processScenario.js";
+import { compareProcessCaptures, parseProcessCapture, } from "../domain/processCapture.js";
 import { captureProcessScenario } from "./ProcessHarness.js";
-import { processCapturePermissionRequest } from "./ProcessCapturePermission.js";
 import { PROCESS_PROVIDER, createProcessCaptureEvidence, } from "./ProcessEvidence.js";
-import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
-/** Capture one JSON scenario through the same policy and evidence contract as MCP. */
-export const captureProcessScenarioFile = async (path) => {
+/** Identify the process workflow's typed diagnostic result for CLI exit status. */
+export const isProcessCliFailure = (value) => typeof value === "object" &&
+    value !== null &&
+    "error" in value &&
+    value.error === "Process command failed" &&
+    "category" in value &&
+    typeof value.category === "string" &&
+    "message" in value &&
+    typeof value.message === "string";
+/** Capture one JSON scenario through the shared process harness and Evidence contract. */
+export const captureProcessScenarioFile = async (path, environment = process.env) => {
     try {
         const input = await readJson(path);
-        let scenario;
-        try {
-            scenario = parseProcessScenario(input);
-        }
-        catch {
-            throw new ProcessCliFailure("invalid_input", "Process scenario is invalid. Check its required fields and limits, then try again.");
-        }
-        const config = parseConfig(process.env);
-        if (!config.ok)
-            return cliAnalysisError(config.error);
-        const authority = await loadConfiguredPermissionAuthority(config.value);
-        if (!authority.ok)
-            return cliAnalysisError(authority.error);
-        const authorized = await authority.value.authorize(processCapturePermissionRequest(scenario), "read");
-        if (!authorized.ok)
-            return cliAnalysisError(projectPermissionFailure(authorized.error));
-        const captured = await captureProcessScenario(scenario, config.value.processExecutionPolicy);
+        const parsed = processScenarioSchema.safeParse(input);
+        if (!parsed.success)
+            throw new AnalysisInputError("capture_process_scenario", { cause: parsed.error }, projectInputIssues(parsed.error.issues, input));
+        const captured = await captureProcessScenario(parsed.data, undefined, process.platform, environment);
         if (!captured.ok)
             return cliAnalysisError(captured.error);
-        return createProcessCaptureEvidence(scenario, captured.value);
+        return createProcessCaptureEvidence(parsed.data, captured.value);
     }
     catch (cause) {
         return projectProcessCliError(cause);

package/dist/application/ProcessEvidence.js

@@ -3,7 +3,7 @@ import { jsonValueSchema } from "../domain/jsonValue.js";
 /** Provider identity for controlled process capture evidence. */
 export const PROCESS_PROVIDER = {
     id: "rea-process",
-    name: "REA deterministic process harness",
+    name: "REA process capture",
     version: "3",
 };
 /** Project one process scenario into secret-free Evidence parameters. */
@@ -11,9 +11,7 @@ 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,
+    filesystem_observation_path_count: scenario.filesystem_observation_paths.length,
     normalization: scenario.normalization,
 });
 /** Create one canonical observed process capture Evidence record. */
@@ -26,9 +24,9 @@ export const createProcessCaptureEvidence = (scenario, capture) => {
         confidence: "observed",
         authority: "controlled-replay",
         environment: {
-            id: `${process.platform}-${process.arch}`,
-            platform: process.platform,
-            architecture: process.arch,
+            id: `${capture.manifest.platform}-${capture.manifest.architecture}`,
+            platform: capture.manifest.platform,
+            architecture: capture.manifest.architecture,
             isolation: "process",
         },
         limitations: capture.limitations,

package/dist/application/ProcessFilesystemEffects.js

@@ -0,0 +1,36 @@
+/** 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;
+        if (beforeFile === null) {
+            if (afterFile === null)
+                throw new TypeError(`Filesystem effect ${path} has no file state`);
+            return {
+                path,
+                status: "created",
+                before: null,
+                after: afterFile,
+            };
+        }
+        if (afterFile === null)
+            return {
+                path,
+                status: "deleted",
+                before: beforeFile,
+                after: null,
+            };
+        return {
+            path,
+            status: JSON.stringify(beforeFile) === JSON.stringify(afterFile)
+                ? "unchanged"
+                : "modified",
+            before: beforeFile,
+            after: afterFile,
+        };
+    });
+};