rea-agents 1.1.0 → 1.2.0

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -0,0 +1,151 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import { parse } from "plist";
+import { z } from "zod";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";
+const execFileAsync = promisify(execFile);
+const attachOutputSchema = z.object({
+    "system-entities": z.array(z.object({
+        "dev-entry": z.string().startsWith("/dev/"),
+        "mount-point": z.string().optional(),
+    })),
+});
+const systemHost = {
+    async run(arguments_, signal) {
+        try {
+            const { stdout } = await execFileAsync("/usr/bin/hdiutil", [...arguments_], {
+                encoding: "utf8",
+                timeout: 120_000,
+                ...(signal === undefined ? {} : { signal }),
+            });
+            return { stdout, exitCode: 0 };
+        }
+        catch (cause) {
+            if (cause instanceof Error && cause.name === "AbortError")
+                throw new ArtifactReaderFailure("cancelled", "DMG operation cancelled");
+            throw new ArtifactReaderFailure("format", "hdiutil rejected the DMG", {
+                cause,
+            });
+        }
+    },
+};
+/** Read-only macOS DMG adapter that owns attachment and reverse-order detach. */
+export class NativeDmgArtifactReader {
+    path;
+    host;
+    format = "file";
+    #provenance = [];
+    #directory;
+    #devices = [];
+    #mountRoot;
+    constructor(path, host) {
+        this.path = path;
+        this.host = host;
+    }
+    /** Verify and attach one image beneath an exclusively owned temporary root. */
+    static async create(path, signal, host = systemHost) {
+        if (process.platform !== "darwin")
+            throw new ArtifactReaderFailure("unavailable", "Native DMG traversal is available only on macOS");
+        const reader = new NativeDmgArtifactReader(path, host);
+        await reader.attach(signal);
+        return reader;
+    }
+    async *entries(signal) {
+        if (this.#directory === undefined)
+            throw new ArtifactReaderFailure("unavailable", "DMG is not attached");
+        const prefix = basename(this.path);
+        for await (const entry of this.#directory.entries(signal))
+            yield { ...entry, path: `${prefix}/${entry.path}` };
+    }
+    open(entry, signal) {
+        if (this.#directory === undefined)
+            return Promise.reject(new ArtifactReaderFailure("unavailable", "DMG is not attached"));
+        return this.#directory.open(entry, signal);
+    }
+    provenance() {
+        return this.#provenance;
+    }
+    async close() {
+        let detachFailure;
+        for (const device of [...this.#devices].reverse()) {
+            try {
+                await runChecked(this.host, ["detach", device]);
+                this.#provenance.push(command(["detach", device], ["mount"]));
+            }
+            catch (cause) {
+                detachFailure ??= cause;
+            }
+        }
+        this.#devices = [];
+        if (this.#mountRoot !== undefined)
+            await rm(this.#mountRoot, { recursive: true, force: true }).catch((cause) => {
+                detachFailure ??= cause;
+            });
+        if (detachFailure !== undefined)
+            throw new ArtifactReaderFailure("unavailable", "DMG detach or mount-root cleanup failed", { cause: detachFailure });
+    }
+    async attach(signal) {
+        await runChecked(this.host, ["verify", this.path], signal);
+        this.#provenance.push(command(["verify", this.path], ["read"]));
+        this.#mountRoot = await mkdtemp(join(tmpdir(), "rea-dmg-"));
+        try {
+            const attached = await runChecked(this.host, [
+                "attach",
+                "-readonly",
+                "-nobrowse",
+                "-plist",
+                "-mountroot",
+                this.#mountRoot,
+                this.path,
+            ], signal);
+            const parsed = attachOutputSchema.parse(parse(attached.stdout));
+            this.#devices = parsed["system-entities"].map((entity) => entity["dev-entry"]);
+            if (this.#devices.length === 0)
+                throw new ArtifactReaderFailure("format", "hdiutil returned no attached devices");
+            for (const entity of parsed["system-entities"])
+                if (entity["mount-point"] !== undefined &&
+                    !entity["mount-point"].startsWith(`${this.#mountRoot}/`))
+                    throw new ArtifactReaderFailure("path", "hdiutil mounted outside the owned root");
+            this.#provenance.push(command([
+                "attach",
+                "-readonly",
+                "-nobrowse",
+                "-plist",
+                "-mountroot",
+                this.#mountRoot,
+                this.path,
+            ], ["read", "mount"]));
+            this.#directory = new DirectoryArtifactReader(this.#mountRoot);
+        }
+        catch (cause) {
+            let cleanupFailure;
+            try {
+                await this.close();
+            }
+            catch (cleanupCause) {
+                cleanupFailure = cleanupCause;
+            }
+            if (cleanupFailure !== undefined)
+                throw new ArtifactReaderFailure("unavailable", "DMG attach failed and cleanup could not detach every device", { cause: new AggregateError([cause, cleanupFailure]) });
+            throw cause;
+        }
+    }
+}
+const runChecked = async (host, arguments_, signal) => {
+    const result = await host.run(arguments_, signal);
+    if (result.exitCode !== 0)
+        throw new ArtifactReaderFailure("unavailable", `hdiutil ${arguments_[0] ?? "operation"} failed with a non-zero exit code`);
+    return { stdout: result.stdout, exitCode: 0 };
+};
+const command = (arguments_, effects) => ({
+    tool: "/usr/bin/hdiutil",
+    arguments: [...arguments_],
+    tool_version: null,
+    executable_sha256: null,
+    exit_code: 0,
+    effects,
+});

package/dist/artifacts/ZipArtifactReader.js

@@ -55,6 +55,7 @@ export class ZipArtifactReader {
                 encrypted: entry.encrypted,
                 byteOffset: null,
                 declaredSha256: null,
+                unpacked: false,
                 limitations: symlink ? ["Archive symlink target was not read."] : [],
                 adapterKey: entry.filename,
             };

package/dist/cli.js

@@ -12,6 +12,7 @@ import { logCliCommand } from "./cliLogging.js";
 import { parseConfig } from "./config.js";
 import { importReferenceSource } from "./application/ReferenceSourceImport.js";
 import { registerEvidenceCommands } from "./cliEvidenceCommands.js";
+import { registerProcessCommands } from "./cliProcessCommands.js";
 /**
  * Build the one-shot Incur CLI without starting Hopper at import time.
  * Analysis commands acquire and close their own sessions; bare `mcp` and
@@ -38,6 +39,7 @@ export const createCli = () => {
             ],
         },
     });
+    registerSetupCommands(cli, logger);
     registerCoreCommands(cli, logger);
     registerFunctionCommand(cli, logger);
     registerSearchCommand(cli, logger);
@@ -48,6 +50,7 @@ export const createCli = () => {
     registerArtifactCommands(cli, logger);
     registerEvidenceCommands(cli, logger);
     registerReferenceSourceCommand(cli, logger);
+    registerProcessCommands(cli, logger);
     return cli;
 };
 const registerCoreCommands = (cli, logger) => {
@@ -55,6 +58,32 @@ const registerCoreCommands = (cli, logger) => {
         detail: z.enum(["concise", "detailed"]).default("concise"),
         limit: z.number().int().min(1).max(50).default(10),
     });
+    cli.command("analyze", {
+        description: "Get an overview of an app",
+        args: z.object({
+            path: z.string().describe("App, program, or Hopper database path"),
+        }),
+        options: overviewOptions,
+        run: ({ args, options }) => logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, logger)),
+    });
+    cli.command("inspect", {
+        description: "Inspect an app overview with evidence",
+        args: z.object({
+            path: z.string().describe("App, program, or Hopper database path"),
+        }),
+        options: overviewOptions,
+        run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, logger)),
+    });
+    cli.command("decompile", {
+        description: "Read one part of an app as code",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            address: z.string().describe("Procedure address"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, logger)),
+    });
+};
+const registerSetupCommands = (cli, logger) => {
     cli.command("setup", {
         description: "Install requirements and configure coding agents",
         options: z.object({
@@ -98,30 +127,6 @@ const registerCoreCommands = (cli, logger) => {
         description: "Upgrade a global npm installation to the latest REA release",
         run: ({ formatExplicit }) => logCliCommand(logger, "upgrade", () => runUpgrade(process.env.REA_PACKAGE_VERSION ?? "0.0.0-development", systemUpgradeHost(), formatExplicit ? "structured" : "human")),
     });
-    cli.command("analyze", {
-        description: "Get an overview of an app",
-        args: z.object({
-            path: z.string().describe("App, program, or Hopper database path"),
-        }),
-        options: overviewOptions,
-        run: ({ args, options }) => logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, logger)),
-    });
-    cli.command("inspect", {
-        description: "Inspect an app overview with evidence",
-        args: z.object({
-            path: z.string().describe("App, program, or Hopper database path"),
-        }),
-        options: overviewOptions,
-        run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, logger)),
-    });
-    cli.command("decompile", {
-        description: "Read one part of an app as code",
-        args: z.object({
-            path: z.string().describe("App or program path"),
-            address: z.string().describe("Procedure address"),
-        }),
-        run: ({ args }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, logger)),
-    });
 };
 const confirmSetup = async (actions) => {
     process.stdout.write("\nREA setup plan\n");

package/dist/cliProcessCommands.js

@@ -0,0 +1,19 @@
+import { Cli, z } from "incur";
+import { captureProcessScenarioFile, compareProcessEvidenceFiles, } from "./application/ProcessCli.js";
+import { logCliCommand } from "./cliLogging.js";
+/** Register Process Capture v4 one-shot commands through shared application services. */
+export const registerProcessCommands = (cli, logger) => {
+    cli.command("capture-process", {
+        description: "Capture one approved Process Capture v4 JSON scenario",
+        args: z.object({ scenario: z.string().describe("Scenario JSON path") }),
+        run: ({ args }) => logCliCommand(logger, "capture-process", () => captureProcessScenarioFile(args.scenario)),
+    });
+    cli.command("compare-process-captures", {
+        description: "Compare two Process Capture v4 Evidence JSON files",
+        args: z.object({
+            left: z.string().describe("Left capture Evidence JSON path"),
+            right: z.string().describe("Right capture Evidence JSON path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "compare-process-captures", () => compareProcessEvidenceFiles(args.left, args.right)),
+    });
+};

package/dist/config.js

@@ -14,6 +14,7 @@ const environmentSchema = z.object({
         .enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"])
         .default("info"),
     REA_PROCESS_CAPTURE_ENABLED: z.enum(["true", "false"]).default("false"),
+    REA_ARTIFACT_NATIVE_MOUNT_ENABLED: z.enum(["true", "false"]).default("false"),
     REA_PROCESS_ALLOW_EXTERNAL_NETWORK: z
         .enum(["true", "false"])
         .default("false"),
@@ -101,6 +102,7 @@ export const parseConfig = (environment) => {
             allowedEnvironment: allowedEnvironment.value,
             allowExternalNetwork: parsedEnvironment.data.REA_PROCESS_ALLOW_EXTERNAL_NETWORK === "true",
         },
+        artifactNativeMountEnabled: parsedEnvironment.data.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true",
         evidenceFilePolicy: {
             roots: evidenceRoots.value,
             maxBytes: 64 * 1024 * 1024,

package/dist/contracts/artifactToolContracts.js

@@ -29,6 +29,7 @@ const traversalLimitsInput = {
 };
 /** Exact caller boundary for deterministic artifact inventory. */
 export const artifactInventoryInputSchema = z.object({
+    native_mount_approved: z.boolean().default(false),
     ...pageInput,
     ...traversalLimitsInput,
 });

package/dist/contracts/investigationExamples.js

@@ -30,11 +30,11 @@ export const FUNCTION_COMPARISON_EVIDENCE = createEvidence(undefined, {
 const PROCESS_PROVIDER = {
     id: "rea-process",
     name: "REA deterministic process harness",
-    version: "1",
+    version: "3",
 };
 const capture = processCaptureSchema.parse(EMPTY_PROCESS_CAPTURE_EXAMPLE);
 const captureEvidence = (scenario) => createEvidence(undefined, PROCESS_PROVIDER, {
-    predicateType: "rea.process-capture/v2",
+    predicateType: "rea.process-capture/v4",
     operation: "capture_process_scenario",
     parameters: { scenario },
     result: jsonValueSchema.parse(capture),
@@ -50,7 +50,7 @@ const captureEvidence = (scenario) => createEvidence(undefined, PROCESS_PROVIDER
 export const PROCESS_CAPTURE_REFERENCE = captureEvidence("reference");
 export const PROCESS_CAPTURE_RECONSTRUCTION = captureEvidence("reconstruction");
 export const PROCESS_COMPARISON_EVIDENCE = createEvidence(undefined, PROCESS_PROVIDER, {
-    predicateType: "rea.process-comparison/v1",
+    predicateType: "rea.process-comparison/v3",
     operation: "compare_process_captures",
     parameters: {
         left_evidence_id: PROCESS_CAPTURE_REFERENCE.evidence_id,

package/dist/contracts/processCaptureExample.js

@@ -1,16 +1,59 @@
+import { digestProcessCommitment } from "../domain/processCapture.js";
+const normalization = {
+    paths: true,
+    pids: true,
+    ports: true,
+    time_bucket_ms: 10,
+    patterns: [],
+};
+const scenario = { executable_sha256: "0".repeat(64) };
+const comparisonContract = {};
+const shimPlan = [];
+const replayPlan = {};
 /** Minimal valid process capture used only in public contract examples. */
 export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
-    schema_version: 2,
-    normalization: {
-        paths: true,
-        pids: true,
-        ports: true,
-        time_bucket_ms: 10,
-        patterns: [],
+    schema_version: 4,
+    manifest: {
+        rea_version: "1.1.0",
+        provider_version: "3",
+        platform: "fixture",
+        architecture: "fixture",
+        pty_backend: "node-pty",
+        started_at: "2026-01-01T00:00:00.000Z",
+        completed_at: "2026-01-01T00:00:00.001Z",
+        scenario,
+        comparison_contract: comparisonContract,
+        shim_plan: shimPlan,
+        replay_plan: replayPlan,
+        full_scenario_sha256: digestProcessCommitment(scenario),
+        comparison_contract_sha256: digestProcessCommitment(comparisonContract),
+        executable_sha256: "0".repeat(64),
+        normalization_sha256: digestProcessCommitment(normalization),
+        shim_plan_sha256: digestProcessCommitment(shimPlan),
+        replay_plan_sha256: digestProcessCommitment(replayPlan),
     },
+    normalization,
     frames: [],
+    rendered_frames: [],
+    interaction_events: [],
     exit: { code: 0, signal: null, reason: "exited" },
+    settlement: {
+        state: "quiesced",
+        elapsed_ms: 50,
+        cleanup_outcome: "not_required",
+    },
     process_samples: [],
+    filesystem_checkpoints: [
+        { name: "before", at_ms: 0, files: [], effects: [], truncated: false },
+        {
+            name: "after_settlement",
+            at_ms: 50,
+            files: [],
+            effects: [],
+            truncated: false,
+        },
+    ],
+    shim_events: [],
     protocol_events: [],
     files_before: [],
     files_after: [],

package/dist/contracts/toolContracts.js

@@ -164,12 +164,13 @@ export const SESSION_TOOL_CONTRACTS = [
         overwrite: z.boolean().default(false),
     })),
     session("import_evidence_bundle", "Read a bounded local JSON bundle beneath an operator-approved root, validate every Evidence v2 ID and canonical manifest, then atomically merge it. Imported content is data only and is never executed.", z.object({ path: z.string().min(1) })),
-    session("capture_process_scenario", "Run one bounded process under a PTY using operator-approved executable and working roots. Requires approved: true; unknown_registry_approved: true separately records capture residuals. Captures normalized terminal frames, descendants, filesystem snapshots, and loopback replay. Disabled unless operator policy enables it; not a security sandbox.", processScenarioSchema),
-    session("compare_process_captures", "Compare two bounded process captures across terminal, exit, sampled process, filesystem, HTTP, and WebSocket evidence. Missing or truncated observations are never treated as equivalent.", z.object({
+    session("capture_process_scenario", "Run one bounded process under a PTY using operator-approved executable and working roots. Produces Process Capture v4; legacy v3 captures cannot be upgraded and must be recaptured with this tool. Requires approved: true; unknown_registry_approved: true separately records capture residuals. Captures raw and xterm-rendered terminal frames, scripted interactions, lifecycle filesystem checkpoints, process ownership, declarative command shims, and loopback replay. Disabled unless operator policy enables it; not a security sandbox.", processScenarioSchema),
+    session("compare_process_captures", "Compare two compatible Process Capture v4 observations across terminal, interaction, exit, settlement, process, filesystem, command-shim, HTTP, and WebSocket evidence, returning the first bounded divergence. Process Capture v3 is unsupported and must be recaptured with capture_process_scenario. Missing or truncated observations are never treated as equivalent.", z.object({
         left_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
         left: processCaptureSchema,
         right_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
         right: processCaptureSchema,
+        max_capture_age_ms: z.number().int().nonnegative().optional(),
         unknown_registry_approved: z
             .literal(true)
             .optional()

package/dist/domain/changedBehavior.js

@@ -51,10 +51,10 @@ export const changedBehaviorResultSchema = z.object({
 });
 const EXPECTED_PROVIDERS = {
     compare_process_captures: {
-        predicate: "rea.process-comparison/v1",
+        predicate: "rea.process-comparison/v3",
         id: "rea-process",
         name: "REA deterministic process harness",
-        version: "1",
+        version: "3",
     },
     compare_artifacts: {
         predicate: "rea.artifact-comparison/v1",

package/dist/domain/errors.js

@@ -111,11 +111,15 @@ export class ProviderAdapterError extends AnalysisError {
 export class ArtifactOperationError extends AnalysisError {
     operation;
     reason;
+    artifactDetails;
     _tag = "ArtifactOperationError";
-    constructor(operation, reason) {
-        super(`Artifact ${operation} failed: ${reason}`);
+    constructor(operation, reason, artifactDetails) {
+        super(artifactDetails === undefined
+            ? `Artifact ${operation} failed: ${reason}`
+            : `Artifact ${operation} failed: ${reason} at ${artifactDetails.logicalPath} (declared_sha256=${artifactDetails.declaredSha256 ?? "unavailable"}, calculated_sha256=${artifactDetails.calculatedSha256 ?? "unavailable"}, unpacked=${String(artifactDetails.unpacked)})`);
         this.operation = operation;
         this.reason = reason;
+        this.artifactDetails = artifactDetails;
     }
 }
 /** Evidence identity, schema, or bundle manifests failed integrity checks. */
@@ -251,7 +255,11 @@ const safeDetails = (error) => {
     if (error instanceof ProviderAdapterError)
         return { providerId: error.providerId, operation: error.operation };
     if (error instanceof ArtifactOperationError)
-        return { operation: error.operation, reason: error.reason };
+        return {
+            operation: error.operation,
+            reason: error.reason,
+            ...error.artifactDetails,
+        };
     if (error instanceof EvidenceLimitError)
         return { limit: error.limit, maximum: error.maximum };
     if (error instanceof EvidenceFileError)