rea-agents 1.1.0 → 1.2.0

package/dist/server/registerProcessComparisonTool.js

@@ -4,14 +4,14 @@ import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
 import { createEvidence } from "../domain/evidence.js";
 import { EvidenceIntegrityError } from "../domain/errors.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
-import { compareProcessCaptures, processCaptureSchema, } from "../domain/processCapture.js";
+import { compareProcessCaptures, processCaptureSchema, parseProcessCapture, } from "../domain/processCapture.js";
 import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
 import { err } from "../domain/result.js";
 import { PROCESS_PROVIDER } from "./sessionToolPolicies.js";
 import { toCallToolResult } from "./toolResult.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
 /** Register deterministic process-capture comparison and contradiction tracking. */
-export const registerProcessComparisonTool = (server, session, contract) => {
+export const registerProcessComparisonTool = (server, session, contract, now = Date.now) => {
     server.registerTool(contract.name, toolRegistrationOptions(contract), (input) => {
         const parsed = z
             .object({
@@ -19,15 +19,29 @@ export const registerProcessComparisonTool = (server, session, contract) => {
             left: processCaptureSchema,
             right_evidence_id: z.string(),
             right: processCaptureSchema,
+            max_capture_age_ms: z.number().int().nonnegative().optional(),
             unknown_registry_approved: z.literal(true).optional(),
         })
             .parse(input);
         const validated = validateCaptureSources(session, parsed);
         if (!validated.ok)
             return toCallToolResult(validated, contract);
-        const comparison = compareProcessCaptures(parsed.left, parsed.right);
+        let comparison;
+        try {
+            comparison = compareProcessCaptures(parsed.left, parsed.right, {
+                ...(parsed.max_capture_age_ms === undefined
+                    ? {}
+                    : { maxCaptureAgeMs: parsed.max_capture_age_ms }),
+                now,
+            });
+        }
+        catch (cause) {
+            return toCallToolResult(err(new EvidenceIntegrityError(cause instanceof Error
+                ? cause.message
+                : "Invalid Process Capture v4")), contract);
+        }
         const evidence = createEvidence(undefined, PROCESS_PROVIDER, {
-            predicateType: "rea.process-comparison/v1",
+            predicateType: "rea.process-comparison/v3",
             operation: contract.name,
             parameters: {
                 left_evidence_id: parsed.left_evidence_id,
@@ -50,17 +64,23 @@ const validateCaptureSources = (session, parsed) => {
         [parsed.right_evidence_id, parsed.right],
     ]) {
         const evidence = session.evidenceById(evidenceId);
-        const result = processCaptureSchema.safeParse(evidence?.normalized_result);
+        let evidenceCapture;
+        try {
+            evidenceCapture = parseProcessCapture(evidence?.normalized_result);
+        }
+        catch {
+            evidenceCapture = undefined;
+        }
         if (evidence === undefined ||
             evidence.operation !== "capture_process_scenario" ||
-            evidence.predicate_type !== "rea.process-capture/v2" ||
+            evidence.predicate_type !== "rea.process-capture/v4" ||
             evidence.provider.id !== PROCESS_PROVIDER.id ||
             evidence.provider.name !== PROCESS_PROVIDER.name ||
             evidence.provider.version !== PROCESS_PROVIDER.version ||
             evidence.confidence !== "observed" ||
             evidence.authority !== "controlled-replay" ||
-            !result.success ||
-            canonicalJson(result.data) !== canonicalJson(capture))
+            evidenceCapture === undefined ||
+            canonicalJson(evidenceCapture) !== canonicalJson(capture))
             return err(new EvidenceIntegrityError("Process comparison payload does not match its source Evidence"));
     }
     return { ok: true, value: null };

package/dist/server/registerSessionTools.js

@@ -5,12 +5,11 @@ import { logToolExecution } from "./toolLogging.js";
 import { ok } from "../domain/result.js";
 import { processScenarioSchema } from "../domain/processCapture.js";
 import { captureProcessScenario } from "../application/ProcessHarness.js";
-import { createEvidence } from "../domain/evidence.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
 import { recordUnknownInputSchema, updateUnknownInputSchema, } from "../domain/residualUnknown.js";
 import { readEvidenceBundle, writeEvidenceBundle, } from "../application/EvidenceBundleFiles.js";
 import { UnknownRegistryError } from "../domain/errors.js";
-import { DENY_EVIDENCE_FILE_POLICY, DENY_PROCESS_POLICY, PROCESS_PROVIDER, } from "./sessionToolPolicies.js";
+import { DENY_EVIDENCE_FILE_POLICY, DENY_PROCESS_POLICY, } from "./sessionToolPolicies.js";
+import { createProcessCaptureEvidence } from "../application/ProcessEvidence.js";
 import { registerProcessComparisonTool } from "./registerProcessComparisonTool.js";
 import { registerArtifactComparisonTool } from "./registerArtifactComparisonTool.js";
 import { registerFunctionComparisonTool } from "./registerFunctionComparisonTool.js";
@@ -45,13 +44,6 @@ const recordProcessResidualUnknowns = (session, scenario, evidence, residuals) =
     }
     return ok(null);
 };
-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,
-    normalization: scenario.normalization,
-});
 const registerProcessTools = ({ server, session, logger, processPolicy, captureContract, }) => {
     server.registerTool(captureContract.name, {
         description: captureContract.description,
@@ -63,21 +55,7 @@ const registerProcessTools = ({ server, session, logger, processPolicy, captureC
         const captured = await logToolExecution(logger, captureContract.name, () => captureProcessScenario(scenario, processPolicy, context.mcpReq.signal));
         if (!captured.ok)
             return toCallToolResult(captured, captureContract);
-        const evidence = createEvidence(undefined, PROCESS_PROVIDER, {
-            predicateType: "rea.process-capture/v2",
-            operation: captureContract.name,
-            parameters: processEvidenceParameters(scenario),
-            result: jsonValueSchema.parse(captured.value),
-            confidence: "observed",
-            authority: "controlled-replay",
-            environment: {
-                id: `${process.platform}-${process.arch}`,
-                platform: process.platform,
-                architecture: process.arch,
-                isolation: "process",
-            },
-            limitations: captured.value.limitations,
-        });
+        const evidence = createProcessCaptureEvidence(scenario, captured.value);
         const recorded = session.recordEvidence(evidence);
         if (!recorded.ok)
             return toCallToolResult(recorded, captureContract);

package/dist/server/sessionToolPolicies.js

@@ -14,12 +14,7 @@ export const DENY_EVIDENCE_FILE_POLICY = {
     maxStringLength: 1024 * 1024,
     maxNodes: 1_000_000,
 };
-/** Provider identity for controlled process-capture evidence. */
-export const PROCESS_PROVIDER = {
-    id: "rea-process",
-    name: "REA deterministic process harness",
-    version: "1",
-};
+export { PROCESS_PROVIDER } from "../application/ProcessEvidence.js";
 /** Provider identity for deterministic cross-artifact comparisons. */
 export const ARTIFACT_COMPARISON_PROVIDER = {
     id: "rea-artifact-comparison",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rea-agents",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Reverse engineer anything from your terminal or coding agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -41,6 +41,7 @@
     "install.sh",
     "bridge/hopper_bridge.py",
     "scripts/rea.mjs",
+    "scripts/prepare-node-pty.mjs",
     "scripts/rebuild-native.mjs",
     "skills",
     "README.md",
@@ -59,6 +60,7 @@
     "scan:todos": "node scripts/scan-todos.mjs",
     "start": "node dist/main.js",
     "pretest": "npm run build",
+    "postinstall": "node scripts/prepare-node-pty.mjs",
     "test": "vitest run",
     "pretest:coverage": "npm run build",
     "test:coverage": "vitest run --coverage.enabled --coverage.provider=v8",
@@ -86,6 +88,8 @@
     "@babel/types": "8.0.4",
     "@electron/asar": "4.2.0",
     "@modelcontextprotocol/server": "2.0.0-beta.3",
+    "@xterm/addon-serialize": "0.14.0",
+    "@xterm/headless": "6.0.0",
     "@zip.js/zip.js": "2.8.26",
     "canonicalize": "3.0.0",
     "diff": "9.0.0",

package/scripts/prepare-node-pty.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import { chmod, lstat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+if (process.platform !== "win32") {
+  const require = createRequire(import.meta.url);
+  const packageRoot = dirname(
+    require.resolve("node-pty/package.json", {
+      paths: [dirname(fileURLToPath(import.meta.url))],
+    }),
+  );
+  const helperPath = join(
+    packageRoot,
+    "prebuilds",
+    `${process.platform}-${process.arch}`,
+    "spawn-helper",
+  );
+
+  try {
+    const helper = await lstat(helperPath);
+    if (!helper.isFile() || helper.isSymbolicLink()) {
+      throw new Error("node-pty spawn helper is not a regular file");
+    }
+    await chmod(helperPath, helper.mode | 0o111);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      // Source builds place their correctly-modeled helper under build/Release.
+    } else {
+      throw error;
+    }
+  }
+}

package/skills/rea-analysis/SKILL.md

@@ -2,7 +2,7 @@
 name: rea-analysis
 description: Reverse engineer apps with REA. Explore how features work, then build a version tailored to your project.
 metadata:
-  version: "10"
+  version: "11"
   tool_count: 68
 ---
 
@@ -36,13 +36,19 @@ REA accepts a `.app` bundle directly. Do not expose its internal `Contents/MacOS
 
 Briefly tell the user what you will investigate. Open the app with `open_binary`, begin with `binary_overview`, and narrow the investigation around the requested feature. Use decompilation, strings, names, callers, callees, and cross-references as needed.
 
-For applications, ZIP/APK/IPA packages, or Electron ASAR archives, call
+For applications, ZIP/APK/IPA packages, Electron ASAR archives, or DMGs, call
 `inventory_artifact` before extraction. Follow its deterministic occurrence
 pages and cite graph manifest IDs. `extract_artifact` requires explicit user
 approval, an absent absolute output root, and selected occurrence IDs; never
 extract every entry implicitly. Symlinks and encrypted entries are inventory
-facts, not extractable files. Nested containers require a separate deliberate
-inventory step.
+facts, not extractable files. Inventory traverses discovered ASARs within the
+same graph and shared limits, including ASARs inside an approved mounted DMG.
+
+Native DMG traversal is macOS-only, read-only, and disabled by default. Use it
+only when the user approves that inventory call with
+`native_mount_approved: true` and the operator has separately enabled
+`REA_ARTIFACT_NATIVE_MOUNT_ENABLED=true`. Without both gates, retain the DMG
+root-hash-only result. Never imply that approval changes extraction authority.
 
 Explain conclusions in plain language. Point to the relevant decompiled code, strings, names, and connections so the user can see how the explanation was reached. Do not claim to recover original source code or automatically clone an application.
 
@@ -57,6 +63,15 @@ requires per-call approval plus operator policy, and uses host networking only
 when the operator explicitly permits it. It is behavioral evidence, not a
 security sandbox.
 
+`capture_process_scenario` produces Process Capture v4 only. If a boundary
+reports Process Capture v3, tell the user or calling agent to rerun the original
+scenario; v3 cannot be upgraded because it lacks required manifest and
+settlement evidence. Treat the v4 manifest commitments as compatibility and
+provenance evidence, and distinguish root exit from descendant settlement.
+When comparing stored captures, set `max_capture_age_ms` when the task requires
+fresh behavioral evidence. Different scenario and executable digests are
+allowed, but schema and comparison-contract digests must be compatible.
+
 Do not let unanswered questions disappear. Use `record_unknown` only with
 explicit approval, attach supporting and contradicting evidence IDs, and record
 the authority/environment still required. Use `update_unknown` with the current