rea-agents 1.6.0 → 2.0.0

package/dist/server/toolResult.js

@@ -9,43 +9,60 @@ export const toCallToolResult = (result, contract, options = {}) => result.ok
     : errorResult(result.error);
 const errorResult = (error) => {
     const projected = projectAnalysisError(error);
+    const structuredContent = { error: projected };
     return {
         content: [
             {
                 type: "text",
-                text: projected.message,
+                text: JSON.stringify(structuredContent),
             },
         ],
-        structuredContent: { error: projected },
+        structuredContent,
         isError: true,
     };
 };
 const successResult = (value, contract, options) => {
-    const candidate = contract.kind === "session" ? { result: value } : value;
+    const candidate = compactEvidence(value) ??
+        (contract.kind === "session" ? { result: value } : value);
     const parsed = contract.outputSchema.safeParse(candidate);
     if (!parsed.success) {
+        const structuredContent = {
+            error: projectAnalysisError(new AnalysisOutputError(contract.name, "output does not match the tool contract")),
+        };
         return {
             content: [
                 {
                     type: "text",
-                    text: "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",
+                    text: JSON.stringify(structuredContent),
                 },
             ],
-            structuredContent: {
-                error: projectAnalysisError(new AnalysisOutputError(contract.name, "output does not match the tool contract")),
-            },
+            structuredContent,
             isError: true,
         };
     }
     return {
         content: [
-            { type: "text", text: formatValue(value) },
+            { type: "text", text: JSON.stringify(parsed.data) },
             ...evidenceResourceLinks(value, contract.kind === "session" ||
                 options.evidenceResourcesAvailable === true),
         ],
         structuredContent: candidate,
     };
 };
+const compactEvidence = (value) => {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        typeof value.evidence_id !== "string" ||
+        !/^ev_[a-f0-9]{64}$/u.test(value.evidence_id) ||
+        !("normalized_result" in value))
+        return undefined;
+    return {
+        result: value.normalized_result,
+        evidence_id: value.evidence_id,
+        evidence_uri: `rea://evidence/${value.evidence_id}`,
+    };
+};
 const evidenceResourceLinks = (value, available) => {
     if (!available ||
         typeof value !== "object" ||
@@ -64,12 +81,3 @@ const evidenceResourceLinks = (value, available) => {
         },
     ];
 };
-const formatValue = (value) => {
-    if (value === null)
-        return "OK";
-    if (typeof value === "string")
-        return value;
-    if (typeof value === "object")
-        return JSON.stringify(value, null, 2);
-    return String(value);
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rea-agents",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -40,6 +40,7 @@
     "dist",
     "install.sh",
     "bridge/hopper_bridge.py",
+    "bridge/ghidra/ReaGhidraBridge.java",
     "scripts/rea.mjs",
     "scripts/prepare-node-pty.mjs",
     "scripts/rebuild-native.mjs",
@@ -49,10 +50,12 @@
     "LICENSE"
   ],
   "scripts": {
-    "prebuild": "node scripts/generate-package-metadata.mjs",
+    "deps:check": "node scripts/check-dependency-install.mjs",
+    "prebuild": "npm run deps:check && node scripts/generate-package-metadata.mjs",
     "build": "tsc -p tsconfig.build.json",
     "postbuild": "node scripts/record-build-cache.mjs",
-    "check": "npm run typecheck && npm run lint && npm run format:check && npm test",
+    "precheck": "npm run deps:check",
+    "check": "npm run typecheck && npm run lint && npm run format:check && npm run docs:check && npm test",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "oxlint",
@@ -61,7 +64,7 @@
     "lint:dead": "knip",
     "jscpd": "jscpd src/ tests/",
     "scan:todos": "node scripts/scan-todos.mjs",
-    "start": "node dist/main.js",
+    "start": "node scripts/rea.mjs mcp",
     "pretest": "npm run build",
     "postinstall": "node scripts/prepare-node-pty.mjs",
     "test": "vitest run",
@@ -71,7 +74,12 @@
     "test:watch": "vitest",
     "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: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: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",
     "build:fixtures": "node scripts/build-conformance-fixtures.mjs",
@@ -79,10 +87,12 @@
     "verify:package": "npm run build && node scripts/verify-package.mjs",
     "verify:published": "node scripts/verify-published-package.mjs",
     "config:print": "node scripts/print-mcp-config.mjs",
-    "docs:generate": "npm run build && typedoc && node scripts/generate-error-schema.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 build",
-    "prepare": "husky",
+    "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",
     "rebuild:native": "node scripts/rebuild-native.mjs"
   },
   "lint-staged": {

package/scripts/rea.mjs

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 
+import { access } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
 // Route production MCP before importing Incur. Incur owns registration helpers
-// such as `mcp add`, while only dist/main.js may serve the 78-tool stdio server.
+// such as `mcp add`, while only dist/main.js may serve the stdio tool catalog.
 const args = process.argv.slice(2);
 const { default: packageJson } = await import("../package.json", {
   with: { type: "json" },
@@ -9,8 +13,17 @@ const { default: packageJson } = await import("../package.json", {
 process.env.REA_PACKAGE_VERSION = packageJson.version;
 const isMcpMode =
   args.length === 1 && (args[0] === "--mcp" || args[0] === "mcp");
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const runtimeFiles = isMcpMode
+  ? ["dist/main.js"]
+  : ["dist/cli.js", "dist/cliOutput.js"];
 
-if (isMcpMode) {
+if (!(await compiledRuntimeExists(runtimeFiles))) {
+  process.stderr.write(
+    `REA's compiled runtime is missing. Run \`npm ci\` in ${packageRoot} to install dependencies and build REA, then restart it. If this is an installed package, reinstall rea-agents.\n`,
+  );
+  process.exitCode = 1;
+} else if (isMcpMode) {
   const { runEntrypoint } = await import("../dist/main.js");
   await runEntrypoint();
 } else {
@@ -20,3 +33,24 @@ if (isMcpMode) {
     stdout: (output) => process.stdout.write(sanitizeCliOutput(output)),
   });
 }
+
+async function compiledRuntimeExists(paths) {
+  for (const path of paths) {
+    try {
+      await access(resolve(packageRoot, path));
+    } catch (cause) {
+      if (isMissing(cause)) return false;
+      throw cause;
+    }
+  }
+  return true;
+}
+
+function isMissing(cause) {
+  return (
+    typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT"
+  );
+}

package/skills/rea-analysis/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: rea-analysis
-description: Reverse engineer apps and websites with REA. Explore how features work, then build a version tailored to your project.
+description: Reverse engineer native, Electron/JavaScript, and web applications with REA. Connect static artifacts to passive runtime evidence, explain how features work, and build a version tailored to the user's project.
 metadata:
-  version: "14"
-  tool_count: 78
+  version: "20"
+  tool_count: 91
+  catalog_digest: "bdf382596e1a00ffc9d59de287b2ad647eeebe629c48a8f8cf158b300363ce53"
 ---
 
 # REA
@@ -35,6 +36,61 @@ Electron `file://` pages use `list_electron_targets` and
 filesystem-root authority. Never claim that Electron inspection invoked IPC,
 evaluated renderer JavaScript, navigated, or escaped an approved root.
 
+For an operator-supplied ASAR or extracted JavaScript/Electron application, use
+`analyze_javascript_application` after the operator configures its canonical
+root in `REA_INVESTIGATION_INPUT_ROOTS_JSON`; every call still requires
+`approved: true`. Source-map contents require the independent
+`source_map_read_approved` flag. Treat BrowserWindow preferences, preload and
+contextBridge surfaces, IPC registrations, utility processes, and native
+binding requests as static syntax observations. Treat only a unique exact
+literal IPC channel match as an inferred pairing; keep dynamic and ambiguous
+channels unresolved. A requested `.node` member is not a verified binary export.
+Never claim that this workflow executed application code or observed runtime
+registration, reachability, defaults, or policy enforcement.
+
+When static application Evidence and passive `inspect_web_page` or
+`inspect_electron_page` Evidence already exist, use
+`reconcile_javascript_runtime` to map capture-scoped targets, frames, scripts,
+and workers onto the static graph. Supply exactly one `application` layer and
+add separately analyzed `cache` or `assets` layers only when relevant. Use
+explicit file-root or URL-prefix mappings for relocated runtime paths; mappings
+are inference inputs and never broaden CDP or filesystem authority. Prefer
+approved captured-source digest identity, report path/digest disagreement as a
+mismatch, preserve ambiguity, and never call a module executed merely because
+its containing bundle was observed. Keep source-map authority separate. This
+tool maps JavaScript graph entities; `correlate_static_and_runtime` remains the
+separate workflow for explicit cross-version comparison hypotheses.
+
+Use `trace_application_feature` on authenticated static or reconciled
+application Evidence to follow one literal node ID, route, string, API, IPC
+channel, module, or native export. Choose an explicit direction and bounds.
+Preserve every graph authority in the returned subgraph. A native handoff means
+only that the exact artifact digest and requested export frontier are known;
+link Ghidra or Hopper Evidence only on exact subject digest, and never claim the
+workflow opened a provider or verified a requested export by itself.
+
+Use `compare_application_versions` after analyzing both versions independently.
+Accept only its unique digest, source-map, structural-fingerprint, or non-module
+semantic matches. Never use module ordinals or minified names as persistent
+identity, and never promote an ambiguous candidate to a match. Report added or
+removed only when opposite-side coverage is complete; otherwise report unknown.
+Use `unknown_registry_approved: true` only after approval to retain unresolved
+version matches. For local operator-provided artifacts, the packaged
+`verify:application-workflows` command reports digests and coverage without
+printing source text.
+
+Use `run_controlled_replay` only for operator-selected extracted JavaScript
+modules when the separate `javascript_replay` policy is enabled. First call
+`mode: plan`; review the exact module, stub, runtime, sandbox, case, limit, and
+policy commitments. Execute only with `approved: true` and that exact
+`plan_digest`. Prefer explicit cases plus the parser, sanitizer, or clipboard
+boundary generator. A right manifest produces a derived differential result.
+Treat return values, exceptions, denials, limits, and crashes as observations
+of the isolated experiment with `controlled-replay` authority—not facts about
+the real application. Never substitute passive browser/Electron permission,
+Process Capture, or an in-process `vm` run. Reproducer export requires its own
+literal approval and `evidence_write` authority after sandbox cleanup.
+
 ## Understand the request
 
 Identify the app and what the user wants to understand or build. Do not ask for information they already provided.