rea-agents 2.2.0 → 2.4.0

package/dist/server/registerApplicationTools/traceSemantics.js

@@ -0,0 +1,30 @@
+import { resolveTraceJavaScriptSemanticsRequestValidated } from "../../application/ApplicationWorkflowEvidenceResolver.js";
+import { traceJavaScriptSemanticsEvidenceValidated } from "../../application/JavaScriptSemanticTraceService.js";
+import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
+import { traceJavaScriptSemanticsRequestSchema } from "../../contracts/applicationWorkflowInputContracts.js";
+import { safeParseToolInput } from "../toolInputValidation.js";
+import { logToolExecution } from "../toolLogging.js";
+import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
+import { toCallToolResult } from "../toolResult.js";
+import { recordResult, recordSources } from "./helpers.js";
+const contract = applicationToolContract("trace_javascript_semantics");
+/** Register the bounded JavaScript semantic relation trace tool. */
+export const registerTraceJavaScriptSemanticsTool = (server, options) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
+        const parsedInput = safeParseToolInput(traceJavaScriptSemanticsRequestSchema, input, contract.name);
+        if (!parsedInput.ok)
+            return toCallToolResult(parsedInput, contract);
+        const resolved = resolveTraceJavaScriptSemanticsRequestValidated(parsedInput.value, options.evidenceLookup);
+        if (!resolved.ok)
+            return toCallToolResult(resolved, contract);
+        const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(traceJavaScriptSemanticsEvidenceValidated(resolved.value)));
+        if (!result.ok)
+            return toCallToolResult(result, contract);
+        const recorded = recordSources(options.recordEvidence, [
+            resolved.value.application,
+        ]);
+        if (!recorded.ok)
+            return toCallToolResult(recorded, contract);
+        return recordResult(options, contract, result.value);
+    });
+};

package/dist/server/registerApplicationTools.js

@@ -1,12 +1,16 @@
 import { registerTraceFeatureTool } from "./registerApplicationTools/traceFeature.js";
+import { registerTraceJavaScriptSemanticsTool } from "./registerApplicationTools/traceSemantics.js";
 import { registerCompareApplicationVersionsTool } from "./registerApplicationTools/compareVersions.js";
+import { registerCompareJavaScriptExportShapesTool } from "./registerApplicationTools/compareExportShapes.js";
 import { registerControlledReplayTool } from "./registerApplicationTools/controlledReplay.js";
 import { registerCharacterizationTools } from "./registerApplicationTools/characterization.js";
 import { registerCoverageTools } from "./registerApplicationTools/coverage.js";
 /** Register provider-neutral JavaScript application graph workflows. */
 export const registerApplicationTools = (server, options) => {
     registerTraceFeatureTool(server, options);
+    registerTraceJavaScriptSemanticsTool(server, options);
     registerCompareApplicationVersionsTool(server, options);
+    registerCompareJavaScriptExportShapesTool(server, options);
     registerControlledReplayTool(server, options);
     registerCharacterizationTools(server, options);
     registerCoverageTools(server, options);

package/dist/server/registerEvidenceResources.js

@@ -317,7 +317,11 @@ const evidenceSection = (result, section) => {
     if (section === "process")
         return pick(result, ["process_samples", "exit", "settlement", "cleanup"]);
     if (section === "protocol")
-        return pick(result, ["protocol_events", "shim_events"]);
+        return pick(result, [
+            "protocol_events",
+            "replay_transitions",
+            "shim_events",
+        ]);
     const value = result[section];
     return value === undefined ? undefined : value;
 };

package/dist/server/registerProcessComparisonTool.js

@@ -11,6 +11,11 @@ import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
 import { runDerivedOperation } from "./runDerivedOperation.js";
 import { safeParseToolInput } from "./toolInputValidation.js";
 import { resolveSessionEvidenceIds } from "./sessionEvidence.js";
+const PROCESS_CAPTURE_EVIDENCE = {
+    operation: "capture_process_scenario",
+    predicate: "rea.process-capture/v4",
+};
+const sourceLocations = (left, right) => [...(left ?? []), ...(right ?? [])];
 /** Register deterministic process-capture comparison and contradiction tracking. */
 export const registerProcessComparisonTool = (server, session, contract, now = Date.now) => {
     server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
@@ -18,14 +23,10 @@ export const registerProcessComparisonTool = (server, session, contract, now = D
         if (!parsedInput.ok)
             return toCallToolResult(parsedInput, contract);
         const parsed = parsedInput.value;
-        const expected = {
-            operation: "capture_process_scenario",
-            predicate: "rea.process-capture/v4",
-        };
-        const leftRecord = resolveSessionEvidenceIds(session, [parsed.left_evidence_id], expected);
+        const leftRecord = resolveSessionEvidenceIds(session, [parsed.left_evidence_id], PROCESS_CAPTURE_EVIDENCE);
         if (!leftRecord.ok)
             return toCallToolResult(leftRecord, contract);
-        const rightRecord = resolveSessionEvidenceIds(session, [parsed.right_evidence_id], expected);
+        const rightRecord = resolveSessionEvidenceIds(session, [parsed.right_evidence_id], PROCESS_CAPTURE_EVIDENCE);
         if (!rightRecord.ok)
             return toCallToolResult(rightRecord, contract);
         let comparison;
@@ -38,6 +39,9 @@ export const registerProcessComparisonTool = (server, session, contract, now = D
                 ...(parsed.max_capture_age_ms === undefined
                     ? {}
                     : { maxCaptureAgeMs: parsed.max_capture_age_ms }),
+                ...(parsed.trace_spec === undefined
+                    ? {}
+                    : { traceSpecification: parsed.trace_spec }),
                 now,
             }));
             if (!computed.ok)
@@ -50,18 +54,24 @@ export const registerProcessComparisonTool = (server, session, contract, now = D
                 : "Invalid Process Capture v4")), contract);
         }
         const evidence = createEvidence(undefined, PROCESS_PROVIDER, {
-            predicateType: "rea.process-comparison/v3",
+            predicateType: parsed.trace_spec === undefined
+                ? "rea.process-comparison/v3"
+                : "rea.process-comparison/v4",
             operation: contract.name,
             parameters: {
                 left_evidence_id: parsed.left_evidence_id,
                 right_evidence_id: parsed.right_evidence_id,
                 left_normalization: leftCapture.normalization,
                 right_normalization: rightCapture.normalization,
+                ...(parsed.trace_spec === undefined
+                    ? {}
+                    : { trace_spec: jsonValueSchema.parse(parsed.trace_spec) }),
             },
             result: jsonValueSchema.parse(comparison),
             confidence: "derived",
             authority: "analyst-inference",
             limitations: comparison.limitations,
+            locations: sourceLocations(leftRecord.value[0]?.locations, rightRecord.value[0]?.locations),
             evidenceLinks: [parsed.left_evidence_id, parsed.right_evidence_id],
         });
         return toCallToolResult(recordDerivedEvidence(session, evidence, comparisonUnknownInput(parsed, comparison)), contract);

package/dist/server/registerReplayMachineTool.js

@@ -0,0 +1,20 @@
+import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+import { replayMachineRunInputSchema, runReplayMachine, } from "../domain/replayMachineRun.js";
+import { ok } from "../domain/result.js";
+import { safeParseToolInput } from "./toolInputValidation.js";
+import { logToolExecution } from "./toolLogging.js";
+import { toCallToolResult } from "./toolResult.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+const contract = SESSION_TOOL_CONTRACTS.find(({ name }) => name === "run_replay_machine");
+if (contract === undefined)
+    throw new TypeError("Missing run_replay_machine tool contract");
+/** Register direct execution-free finite replay-machine evaluation. */
+export const registerReplayMachineTool = (server, logger) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
+        const parsed = safeParseToolInput(replayMachineRunInputSchema, input, contract.name);
+        if (!parsed.ok)
+            return toCallToolResult(parsed, contract);
+        const result = await logToolExecution(logger, contract.name, () => Promise.resolve(ok(runReplayMachine(parsed.value))));
+        return toCallToolResult(result, contract);
+    });
+};

package/dist/server/registerSessionTools.js

@@ -23,7 +23,8 @@ import { mcpProgressReporter } from "./mcpProgress.js";
 import { authorizeProcessCaptureWithElicitation, } from "./ProcessCaptureElicitation.js";
 import { isInputRequiredResult } from "@modelcontextprotocol/server";
 import { registerEvidenceTools, registerUnknownTools, } from "./registerSessionRecordTools.js";
-import { sessionAvailabilityPolicy } from "./sessionAvailabilityPolicy.js";
+import { registerReplayMachineTool } from "./registerReplayMachineTool.js";
+import { sessionAvailabilityPolicy, } from "./sessionAvailabilityPolicy.js";
 const permissionFailure = (failure) => {
     if (failure.ok)
         return err(new AnalysisProtocolError("Expected a denied permission"));
@@ -212,6 +213,14 @@ const registerCloseLifecycleTool = ({ server, session, logger, contracts: [, clo
             : toCallToolResult(closed, closeContract);
     });
 };
+const registerRecordAndReplayTools = (server, session, logger) => {
+    registerUnknownTools({
+        server,
+        session,
+        contracts: SESSION_TOOL_CONTRACTS,
+    });
+    registerReplayMachineTool(server, logger);
+};
 export const registerSessionTools = (server, session, logger, options = {}) => {
     const processPolicy = options.processPolicy ?? DENY_PROCESS_POLICY;
     const evidenceFilePolicy = options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY;
@@ -224,7 +233,7 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
         contracts: [openContract, closeContract, statusContract],
         snapshotFilePolicy: analysisSnapshotFilePolicy,
         startedAt: options.startedAt ?? new Date().toISOString(),
-        availabilityPolicy: sessionAvailabilityPolicy(options.availabilityPolicy, processPolicy, evidenceFilePolicy),
+        availabilityPolicy: sessionAvailabilityPolicy(options.availabilityPolicy, processPolicy, evidenceFilePolicy, options.investigationInputRoots ?? []),
         ...(options.permissionAuthority === undefined
             ? {}
             : { permissionAuthority: options.permissionAuthority }),
@@ -274,9 +283,5 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
             ? {}
             : { permissionAuthority: options.permissionAuthority }),
     });
-    registerUnknownTools({
-        server,
-        session,
-        contracts: SESSION_TOOL_CONTRACTS,
-    });
+    registerRecordAndReplayTools(server, session, logger);
 };

package/dist/server/sessionAvailabilityPolicy.js

@@ -1,8 +1,9 @@
 /** Select configured availability reporting or the target-free defaults. */
-export const sessionAvailabilityPolicy = (configured, processPolicy, evidenceFilePolicy) => configured ??
+export const sessionAvailabilityPolicy = (configured, processPolicy, evidenceFilePolicy, investigationInputRoots) => configured ??
     (() => ({
         processCaptureEnabled: processPolicy.enabled,
         evidenceFileRoots: evidenceFilePolicy.roots.length,
+        investigationInputRoots: investigationInputRoots.length,
         browserObservationEnabled: false,
         electronObservationEnabled: false,
         javascriptReplayEnabled: false,

package/dist/serverIdentity.js

@@ -68,3 +68,22 @@ export const createServerIdentity = (input) => {
         },
     };
 };
+/** Compact identity projection for CLI summaries; MCP retains full identity. */
+export const createServerIdentitySummary = (input) => {
+    const identity = createServerIdentity(input);
+    return {
+        package: {
+            name: identity.package.name,
+            version: identity.package.version,
+        },
+        server: {
+            name: identity.server.name,
+            version: identity.server.version,
+        },
+        catalog: {
+            counts: identity.catalog.counts,
+            digests: identity.catalog.digests,
+        },
+        alignment: identity.alignment,
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rea-agents",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -44,17 +44,29 @@
     "bridge/ghidra/ReaGhidraBridge.java",
     "scripts/rea.mjs",
     "scripts/hopper-demo-x11.py",
+    "scripts/prepack.mjs",
+    "scripts/prepare.mjs",
     "skills",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "deps:check": "node scripts/check-dependency-install.mjs",
-    "prebuild": "npm run deps:check && node scripts/generate-package-metadata.mjs",
+    "metadata:generate": "node scripts/generate-package-metadata.mjs",
+    "metadata:check": "node scripts/generate-package-metadata.mjs --check",
+    "prebuild": "npm run deps:check && npm run metadata:check",
     "build": "tsc -p tsconfig.build.json",
-    "postbuild": "node scripts/record-build-cache.mjs",
     "precheck": "npm run deps:check",
-    "check": "npm run typecheck && npm run lint && npm run format:check && npm run docs:check && npm test",
+    "check": "turbo run typecheck lint format:check knip metadata:check",
+    "precheck:fast": "npm run deps:check",
+    "check:fast": "turbo run typecheck lint",
+    "precheck:test": "npm run deps:check",
+    "check:test": "turbo run typecheck lint format:check knip metadata:check test:run",
+    "precheck:pr": "npm run deps:check",
+    "check:pr": "turbo run typecheck lint format:check knip metadata:check test:run docs:check:built",
+    "precheck:ci": "npm run deps:check",
+    "check:ci": "turbo run typecheck lint format:check knip metadata:check jscpd scan:todos",
+    "build:cached": "turbo run build",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "oxlint",
@@ -64,42 +76,61 @@
     "jscpd": "jscpd src/ tests/",
     "scan:todos": "node scripts/scan-todos.mjs",
     "start": "node scripts/rea.mjs mcp",
-    "pretest": "npm run build",
+    "pretest": "npm run build:cached",
     "test": "vitest run",
-    "pretest:coverage": "npm run build",
+    "test:run": "vitest run",
+    "pretest:fast": "npm run build:cached",
+    "test:fast": "vitest run --project parallel",
+    "pretest:integration": "npm run build:cached",
+    "test:integration": "vitest run --project serial-integration",
+    "pretest:coverage": "npm run build:cached",
     "test:coverage": "vitest run --coverage.enabled --coverage.provider=v8",
+    "test:ci": "npm run test:coverage -- --reporter=default --reporter=junit --outputFile.junit=test-results.xml",
+    "pretest:ci:shard": "npm run build:cached",
+    "test:ci:shard": "vitest run --coverage.enabled --coverage.provider=v8 --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.branches=0 --coverage.thresholds.statements=0 --reporter=default --reporter=blob",
+    "test:ci:merge": "vitest --merge-reports --coverage.enabled --coverage.provider=v8 --reporter=default --reporter=junit --outputFile.junit=test-results.xml",
+    "pretest:verbose": "npm run build:cached",
     "test:verbose": "vitest run --reporter=verbose",
-    "test:watch": "vitest",
+    "pretest:watch": "npm run build:cached",
+    "test:watch": "vitest --project parallel --changed",
     "typecheck": "tsc --noEmit",
-    "verify:hopper": "npm run build && node scripts/verify-real-hopper.mjs",
-    "verify:ghidra": "npm run build && node scripts/verify-real-ghidra.mjs",
-    "verify:ghidra:windows": "npm run build && npm run build:ghidra-windows-fixture && node scripts/verify-real-ghidra-windows.mjs",
-    "verify:browser": "npm run build && node scripts/verify-real-browser.mjs",
-    "verify:javascript-runtime": "npm run build && node scripts/verify-local-javascript-runtime.mjs",
-    "verify:application-workflows": "npm run build && node scripts/verify-local-application-workflows.mjs",
-    "verify:managed": "npm run build && node scripts/verify-managed-conformance.mjs",
-    "verify:replay": "npm run build && node scripts/verify-real-javascript-replay.mjs",
-    "verify:agent": "npm run build && node scripts/verify-agent-experience.mjs",
-    "verify:hopper:linux": "npm run build && node scripts/verify-real-hopper-linux.mjs",
-    "verify:setup:linux": "npm run build && node scripts/verify-linux-setup-e2e.mjs",
+    "verify:test-temp-hygiene": "npm run build:cached && node scripts/verify-test-temp-hygiene.mjs",
+    "verify:hopper": "npm run verify:fixtures && npm run build:cached && node scripts/verify-real-hopper.mjs",
+    "verify:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.mjs",
+    "verify:ghidra:windows": "npm run build:cached && npm run build:ghidra-windows-fixture && node scripts/verify-real-ghidra-windows.mjs",
+    "verify:browser": "npm run build:cached && node scripts/verify-real-browser.mjs",
+    "verify:javascript-runtime": "npm run build:cached && node scripts/verify-local-javascript-runtime.mjs",
+    "verify:application-workflows": "npm run build:cached && node scripts/verify-local-application-workflows.mjs",
+    "verify:managed": "npm run build:cached && node scripts/verify-managed-conformance.mjs",
+    "verify:replay": "npm run build:cached && node scripts/verify-real-javascript-replay.mjs",
+    "verify:agent": "npm run build:cached && node scripts/verify-agent-experience.mjs",
+    "verify:hopper:linux": "npm run verify:fixtures && npm run build:cached && node scripts/verify-real-hopper-linux.mjs",
+    "verify:setup:linux": "npm run build:cached && node scripts/verify-linux-setup-e2e.mjs",
     "build:fixtures": "node scripts/build-conformance-fixtures.mjs",
     "build:ghidra-windows-fixture": "node scripts/create-ghidra-windows-fixture.mjs",
     "verify:fixtures": "npm run build:fixtures && node scripts/verify-conformance-fixtures.mjs",
-    "verify:package": "npm run build && node scripts/verify-package.mjs",
-    "verify:package:windows": "npm run build && node scripts/verify-windows-package.mjs",
-    "probe:windows-capabilities": "npm run build && node scripts/windows-capabilities.mjs",
+    "verify:package": "npm run build:cached && node scripts/verify-package.mjs",
+    "verify:package:windows": "npm run build:cached && node scripts/verify-windows-package.mjs",
+    "probe:windows-capabilities": "npm run build:cached && node scripts/windows-capabilities.mjs",
     "verify:published": "node scripts/verify-published-package.mjs",
     "config:print": "node scripts/print-mcp-config.mjs",
-    "docs:generate": "npm run build && node scripts/generate-skill-metadata.mjs && node scripts/generate-product-catalog.mjs && typedoc && node scripts/generate-error-schema.mjs",
-    "docs:check": "node scripts/generate-package-metadata.mjs --check && npm run build && node scripts/generate-skill-metadata.mjs --check && node scripts/generate-product-catalog.mjs --check && node scripts/check-doc-facts.mjs && node scripts/check-typedoc.mjs && node scripts/generate-error-schema.mjs --check",
-    "docs:error-schema": "npm run build && node scripts/generate-error-schema.mjs",
-    "prepack": "npm run deps:check && node scripts/generate-skill-metadata.mjs --check",
-    "prepublishOnly": "npm run deps:check && node scripts/generate-skill-metadata.mjs --check",
-    "prepare": "npm run build && husky"
+    "evidence:generate": "npm run build:cached && node scripts/generate-completion-ledger.mjs",
+    "evidence:check": "npm run build:cached && node scripts/generate-completion-ledger.mjs --check",
+    "docs:api": "typedoc",
+    "docs:api:cached": "turbo run docs:api",
+    "docs:generate": "npm run metadata:generate && npm run build:cached && node scripts/generate-skill-metadata.mjs && node scripts/generate-product-catalog.mjs && node scripts/generate-completion-ledger.mjs && npm run docs:api:cached && node scripts/generate-error-schema.mjs",
+    "docs:check": "turbo run docs:check:built",
+    "docs:check:built": "node scripts/generate-package-metadata.mjs --check && node scripts/generate-skill-metadata.mjs --check && node scripts/generate-product-catalog.mjs --check && node scripts/generate-completion-ledger.mjs --check && node scripts/check-doc-facts.mjs && node scripts/generate-error-schema.mjs --check",
+    "docs:error-schema": "npm run build:cached && node scripts/generate-error-schema.mjs",
+    "prepack": "node scripts/prepack.mjs",
+    "prepare": "node scripts/prepare.mjs"
   },
   "lint-staged": {
-    "*.{ts,mjs,json,md,yml,yaml}": "prettier --write",
-    "*.ts": "oxlint --fix"
+    "*.{cjs,cts,js,jsx,mjs,mts,ts,tsx}": [
+      "prettier --write",
+      "oxlint --fix"
+    ],
+    "*.{json,md,yml,yaml}": "prettier --write"
   },
   "dependencies": {
     "@babel/parser": "8.0.4",
@@ -109,6 +140,7 @@
     "@jridgewell/trace-mapping": "0.3.31",
     "@lydell/node-pty": "1.1.0",
     "@modelcontextprotocol/server": "2.0.0-beta.4",
+    "@modelcontextprotocol/client": "2.0.0-beta.4",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
     "@zip.js/zip.js": "2.8.26",
@@ -129,7 +161,6 @@
   },
   "devDependencies": {
     "@fast-check/vitest": "0.4.1",
-    "@modelcontextprotocol/client": "2.0.0-beta.4",
     "@types/node": "24.10.1",
     "@types/semver": "7.7.1",
     "@types/write-file-atomic": "4.0.3",
@@ -142,6 +173,7 @@
     "oxlint": "1.73.0",
     "prettier": "3.6.2",
     "typedoc": "0.28.20",
+    "turbo": "2.10.5",
     "typescript": "5.9.3",
     "vitest": "4.1.10"
   }