rea-agents 0.2.1

package/dist/server/createServer.js

@@ -0,0 +1,30 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { registerEnhancedTools } from "./registerEnhancedTools.js";
+import { registerOfficialTools } from "./registerOfficialTools.js";
+import { registerSessionTools } from "./registerSessionTools.js";
+import { silentLogger } from "../logger.js";
+/**
+ * Construct one MCP server without acquiring subprocess resources.
+ * Supplying a session adds target lifecycle tools; omitting it retains the
+ * fixed-target seam used by focused tests and embedders.
+ */
+export const createServer = (analysis, session, logger = silentLogger, processPolicy) => {
+    const server = new McpServer({ name: PRODUCT_IDENTITY.mcpServerKey, version: "0.1.0" }, {
+        capabilities: { tools: {} },
+        instructions: session === undefined
+            ? "Reverse-engineering tools for an active analysis target. Start with binary_overview."
+            : "Reverse-engineering tools for configured analysis providers. Open a target with open_binary, then start with binary_overview.",
+    });
+    const toolLogger = logger.child({ layer: "server" });
+    const activeTarget = session === undefined ? undefined : () => session.activeTarget();
+    const provider = session?.providerIdentity();
+    const recordEvidence = session === undefined
+        ? undefined
+        : (evidence) => session.recordEvidence(evidence);
+    registerOfficialTools(server, analysis, toolLogger, activeTarget, provider, recordEvidence);
+    registerEnhancedTools(server, analysis, toolLogger, activeTarget, provider, recordEvidence);
+    if (session !== undefined)
+        registerSessionTools(server, session, toolLogger, processPolicy);
+    return server;
+};

package/dist/server/registerEnhancedTools.js

@@ -0,0 +1,53 @@
+import { EnhancedTools } from "../application/EnhancedTools.js";
+import { enhancedToolNameSchema } from "../contracts/enhancedInputs.js";
+import { ENHANCED_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
+import { toCallToolResult } from "./toolResult.js";
+import { logToolExecution } from "./toolLogging.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
+/** Register composed workflows against the same port as direct bridge tools. */
+export const registerEnhancedTools = (server, analysis, logger, activeTarget, provider = {
+    id: "unidentified",
+    name: "Unidentified provider",
+    version: null,
+}, recordEvidence) => {
+    const services = new EnhancedTools(analysis);
+    for (const contract of ENHANCED_TOOL_CONTRACTS) {
+        registerEnhancedTool(server, services, contract, {
+            logger,
+            activeTarget,
+            provider,
+            recordEvidence,
+        });
+    }
+};
+const registerEnhancedTool = (server, services, contract, registration) => {
+    const name = enhancedToolNameSchema.parse(contract.name);
+    server.registerTool(name, {
+        description: contract.description,
+        inputSchema: contract.inputSchema,
+        outputSchema: contract.outputSchema,
+        annotations: contract.annotations,
+    }, async (input, context) => {
+        const parsedInput = jsonValueSchema.parse(enhancedInputSchemas[name].parse(input));
+        if (typeof parsedInput !== "object" ||
+            parsedInput === null ||
+            Array.isArray(parsedInput))
+            throw new Error("Validated enhanced input was not a JSON object");
+        const parameters = { ...parsedInput };
+        const result = await logToolExecution(registration.logger, name, () => services.execute(name, input, context.mcpReq.signal));
+        if (result.ok) {
+            const evidence = createEvidence(registration.activeTarget?.(), registration.provider, {
+                operation: name,
+                parameters,
+                result: result.value,
+                confidence: "derived",
+                redactedRawPayload: result.value,
+            });
+            registration.recordEvidence?.(evidence);
+            return toCallToolResult({ ok: true, value: evidence }, contract);
+        }
+        return toCallToolResult(result, contract);
+    });
+};

package/dist/server/registerOfficialTools.js

@@ -0,0 +1,59 @@
+import { OFFICIAL_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { toCallToolResult } from "./toolResult.js";
+import { logToolExecution } from "./toolLogging.js";
+import { createEvidence } from "../domain/evidence.js";
+/** Register direct bridge proxies, preserving MCP cancellation and typed errors. */
+export const registerOfficialTools = (server, analysis, logger, activeTarget, provider = {
+    id: "unidentified",
+    name: "Unidentified provider",
+    version: null,
+}, recordEvidence) => {
+    for (const contract of OFFICIAL_TOOL_CONTRACTS) {
+        registerOfficialTool(server, analysis, contract, {
+            logger,
+            activeTarget,
+            provider,
+            recordEvidence,
+        });
+    }
+};
+const registerOfficialTool = (server, analysis, contract, registration) => {
+    server.registerTool(contract.name, {
+        description: contract.description,
+        inputSchema: contract.inputSchema,
+        outputSchema: contract.outputSchema,
+        annotations: contract.annotations,
+    }, async (input, context) => {
+        const arguments_ = projectOfficialArguments(contract, input);
+        const result = await logToolExecution(registration.logger, contract.name, () => analysis.execute(contract.name, arguments_, {
+            signal: context.mcpReq.signal,
+        }));
+        if (result.ok) {
+            const evidence = createEvidence(registration.activeTarget?.(), registration.provider, {
+                operation: contract.name,
+                parameters: arguments_,
+                result: result.value,
+                redactedRawPayload: result.value,
+            });
+            registration.recordEvidence?.(evidence);
+            return toCallToolResult({ ok: true, value: evidence }, contract);
+        }
+        return toCallToolResult(result, contract);
+    });
+};
+const projectOfficialArguments = (contract, input) => {
+    const parsed = jsonValueSchema.safeParse(input);
+    if (!parsed.success ||
+        typeof parsed.data !== "object" ||
+        parsed.data === null ||
+        Array.isArray(parsed.data)) {
+        // The SDK validates this with the same schema before invoking the callback.
+        throw new Error("Validated MCP tool input was not a JSON object");
+    }
+    const projected = {};
+    for (const key of Object.keys(contract.inputSchema.shape)) {
+        projected[key] = parsed.data[key] ?? null;
+    }
+    return projected;
+};

package/dist/server/registerSessionTools.js

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+import { toCallToolResult } from "./toolResult.js";
+import { logToolExecution } from "./toolLogging.js";
+import { err, ok } from "../domain/result.js";
+import { EvidenceLedgerError } from "../domain/errors.js";
+import { compareProcessCaptures, processCaptureSchema, processScenarioSchema, } from "../domain/processCapture.js";
+import { captureProcessScenario } from "../application/ProcessHarness.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+const DENY_PROCESS_POLICY = {
+    enabled: false,
+    executableRoots: [],
+    workingRoots: [],
+    allowedEnvironment: [],
+};
+const PROCESS_PROVIDER = {
+    id: "rea-process",
+    name: "REA deterministic process harness",
+    version: "1",
+};
+const registerProcessTools = ({ server, session, logger, processPolicy, captureContract, compareContract, }) => {
+    server.registerTool(captureContract.name, {
+        description: captureContract.description,
+        inputSchema: captureContract.inputSchema,
+        outputSchema: captureContract.outputSchema,
+        annotations: captureContract.annotations,
+    }, async (input, context) => {
+        const scenario = processScenarioSchema.parse(input);
+        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/v1",
+            operation: captureContract.name,
+            parameters: {
+                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,
+            },
+            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,
+        });
+        session.recordEvidence(evidence);
+        return toCallToolResult(ok(evidence), captureContract);
+    });
+    server.registerTool(compareContract.name, {
+        description: compareContract.description,
+        inputSchema: compareContract.inputSchema,
+        outputSchema: compareContract.outputSchema,
+        annotations: compareContract.annotations,
+    }, (input) => {
+        const parsed = z
+            .object({
+            left_evidence_id: z.string(),
+            left: processCaptureSchema,
+            right_evidence_id: z.string(),
+            right: processCaptureSchema,
+        })
+            .parse(input);
+        const comparison = compareProcessCaptures(parsed.left, parsed.right);
+        const evidence = createEvidence(undefined, PROCESS_PROVIDER, {
+            predicateType: "rea.process-comparison/v1",
+            operation: compareContract.name,
+            parameters: {},
+            result: jsonValueSchema.parse(comparison),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: comparison.limitations,
+            evidenceLinks: [parsed.left_evidence_id, parsed.right_evidence_id],
+        });
+        session.recordEvidence(evidence);
+        return toCallToolResult(ok(evidence), compareContract);
+    });
+};
+const registerEvidenceTools = ({ server, session, exportContract, importContract, }) => {
+    server.registerTool(exportContract.name, {
+        description: exportContract.description,
+        inputSchema: exportContract.inputSchema,
+        outputSchema: exportContract.outputSchema,
+        annotations: exportContract.annotations,
+    }, () => toCallToolResult(ok(session.exportEvidenceBundle()), exportContract));
+    server.registerTool(importContract.name, {
+        description: importContract.description,
+        inputSchema: importContract.inputSchema,
+        outputSchema: importContract.outputSchema,
+        annotations: importContract.annotations,
+    }, (input) => {
+        try {
+            const bundle = z.object({ bundle: z.unknown() }).parse(input).bundle;
+            const imported = session.importEvidenceBundle(bundle);
+            return toCallToolResult(ok({
+                imported,
+                total: session.exportEvidenceBundle().records.length,
+            }), importContract);
+        }
+        catch (cause) {
+            return toCallToolResult(err(new EvidenceLedgerError("Evidence bundle validation failed", {
+                cause,
+            })), importContract);
+        }
+    });
+};
+/** Register MCP-only target lifecycle operations on a long-lived session. */
+export const registerSessionTools = (server, session, logger, processPolicy = DENY_PROCESS_POLICY) => {
+    const [openContract, closeContract, statusContract, exportContract, importContract, captureContract, compareContract,] = SESSION_TOOL_CONTRACTS;
+    server.registerTool(openContract.name, {
+        description: openContract.description,
+        inputSchema: openContract.inputSchema,
+        outputSchema: openContract.outputSchema,
+        annotations: openContract.annotations,
+    }, async (input, context) => {
+        const parsed = z.object({ path: z.string().min(1) }).parse(input);
+        const opened = await logToolExecution(logger, openContract.name, () => session.open(parsed.path, { signal: context.mcpReq.signal }));
+        return opened.ok
+            ? toCallToolResult({
+                ok: true,
+                value: {
+                    path: opened.value.path,
+                    format: opened.value.format,
+                    kind: opened.value.kind,
+                    loaderArgs: [...opened.value.loaderArgs],
+                    sha256: opened.value.sha256,
+                    architecture: opened.value.architecture ?? null,
+                },
+            }, openContract)
+            : toCallToolResult(opened, openContract);
+    });
+    server.registerTool(closeContract.name, {
+        description: closeContract.description,
+        inputSchema: closeContract.inputSchema,
+        outputSchema: closeContract.outputSchema,
+        annotations: closeContract.annotations,
+    }, async () => toCallToolResult(await logToolExecution(logger, closeContract.name, () => session.close()), closeContract));
+    server.registerTool(statusContract.name, {
+        description: statusContract.description,
+        inputSchema: statusContract.inputSchema,
+        outputSchema: statusContract.outputSchema,
+        annotations: statusContract.annotations,
+    }, () => toCallToolResult({ ok: true, value: session.status() }, statusContract));
+    registerEvidenceTools({ server, session, exportContract, importContract });
+    registerProcessTools({
+        server,
+        session,
+        logger,
+        processPolicy,
+        captureContract,
+        compareContract,
+    });
+};

package/dist/server/toolLogging.js

@@ -0,0 +1,11 @@
+/** Log one MCP tool's duration and status without recording caller input. */
+export const logToolExecution = async (logger, tool, execute) => {
+    const startedAt = performance.now();
+    const result = await execute();
+    logger[result.ok ? "info" : "warn"]({
+        tool,
+        durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+        status: result.ok ? "ok" : "error",
+    }, "MCP tool execution completed");
+    return result;
+};

package/dist/server/toolResult.js

@@ -0,0 +1,44 @@
+/**
+ * Translate an application result into MCP text content.
+ * Error tags and safe messages remain visible while underlying causes, process
+ * output, and other potentially sensitive details stay private.
+ */
+export const toCallToolResult = (result, contract) => result.ok
+    ? successResult(result.value, contract)
+    : {
+        content: [
+            {
+                type: "text",
+                text: `${result.error._tag}: ${result.error.message}`,
+            },
+        ],
+        isError: true,
+    };
+const successResult = (value, contract) => {
+    const candidate = contract.kind === "session" ? { result: value } : value;
+    const parsed = contract.outputSchema.safeParse(candidate);
+    if (!parsed.success) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "HopperProtocolError: Analysis output does not match the tool contract",
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: "text", text: formatValue(value) }],
+        structuredContent: candidate,
+    };
+};
+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

@@ -0,0 +1,109 @@
+{
+  "name": "rea-agents",
+  "version": "0.2.1",
+  "description": "Reverse engineering CLI and MCP server for coding agents to understand apps and build features.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/morluto/rea.git"
+  },
+  "homepage": "https://github.com/morluto/rea#readme",
+  "bugs": {
+    "url": "https://github.com/morluto/rea/issues"
+  },
+  "keywords": [
+    "reverse-engineering",
+    "binary-analysis",
+    "coding-agents",
+    "agent-skills",
+    "cli",
+    "mcp-server",
+    "model-context-protocol",
+    "static-analysis",
+    "disassembler",
+    "decompiler",
+    "mcp",
+    "hopper"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "rea": "scripts/rea.mjs"
+  },
+  "engines": {
+    "node": ">=24.18.0 <25",
+    "npm": ">=11.16.0 <12"
+  },
+  "packageManager": "npm@11.16.0",
+  "files": [
+    "dist",
+    "bridge/hopper_bridge.py",
+    "scripts/rea.mjs",
+    "scripts/rebuild-native.mjs",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "npm run typecheck && npm run lint && npm run format:check && npm test",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "knip": "knip",
+    "lint:dead": "knip",
+    "jscpd": "jscpd src/ tests/",
+    "scan:todos": "node scripts/scan-todos.mjs",
+    "start": "node dist/main.js",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "pretest:coverage": "npm run build",
+    "test:coverage": "vitest run --coverage.enabled --coverage.provider=v8",
+    "test:verbose": "vitest run --reporter=verbose",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "verify:hopper": "npm run build && node scripts/verify-real-hopper.mjs",
+    "build:fixtures": "node scripts/build-conformance-fixtures.mjs",
+    "verify:fixtures": "npm run build:fixtures && node scripts/verify-conformance-fixtures.mjs",
+    "verify:package": "npm run build && node scripts/verify-package.mjs",
+    "config:print": "node scripts/print-mcp-config.mjs",
+    "docs:generate": "typedoc",
+    "prepack": "npm run build",
+    "prepare": "husky",
+    "rebuild:native": "node scripts/rebuild-native.mjs"
+  },
+  "lint-staged": {
+    "*.{ts,mjs,json,md,yml,yaml}": "prettier --write",
+    "*.ts": "oxlint --fix"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0-beta.3",
+    "canonicalize": "3.0.0",
+    "incur": "0.4.13",
+    "node-pty": "1.1.0",
+    "pino": "9.14.0",
+    "ws": "8.21.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0-beta.3",
+    "@types/node": "24.10.1",
+    "@types/ws": "8.18.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "husky": "9.1.7",
+    "jscpd": "5.0.12",
+    "knip": "6.26.0",
+    "lint-staged": "16.4.0",
+    "oxlint": "1.73.0",
+    "prettier": "3.6.2",
+    "typedoc": "0.28.20",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
+  },
+  "allowScripts": {
+    "node-pty@1.1.0": true
+  }
+}

package/scripts/rea.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+// Route production MCP before importing Incur. Incur owns registration helpers
+// such as `mcp add`, while only dist/main.js may serve the 50-tool stdio server.
+const args = process.argv.slice(2);
+const isMcpMode =
+  args[0] === "--mcp" || (args.length === 1 && args[0] === "mcp");
+
+if (isMcpMode) {
+  const { run } = await import("../dist/main.js");
+  process.exitCode = await run();
+} else {
+  const { createCli } = await import("../dist/cli.js");
+  await createCli().serve(args);
+}

package/scripts/rebuild-native.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+
+const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+const child = spawn(npm, ["rebuild", "node-pty"], {
+  stdio: "inherit",
+  env: { ...process.env, npm_config_build_from_source: "true" },
+});
+
+child.once("error", (error) => {
+  console.error(`Unable to rebuild node-pty: ${error.message}`);
+  process.exitCode = 1;
+});
+child.once("exit", (code, signal) => {
+  if (signal !== null) {
+    console.error(`node-pty rebuild terminated by ${signal}`);
+    process.exitCode = 1;
+    return;
+  }
+  process.exitCode = code ?? 1;
+});

package/skills/rea-analysis/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: rea-analysis
+description: Reverse engineer apps with REA. Explore how features work, then build a version tailored to your project.
+---
+
+# REA
+
+Use REA when the user wants to understand how an app or feature works, compare app versions, decompile code, or build a similar feature.
+
+## Understand the request
+
+Identify the app and what the user wants to understand or build. Do not ask for information they already provided.
+
+If the app is missing, ask which app they want to reverse engineer. If the app is known but the goal is unclear, ask what they want to understand or build, and offer to start with an overview. Never require the user to supply a program path, address, architecture, or reverse-engineering terminology.
+
+Notes is only a documentation example. Never select an app unless the user names it or confirms it.
+
+## Ensure REA is ready
+
+1. Run `npx -y rea-agents doctor`.
+2. If setup is needed, explain that REA may install Homebrew and Hopper. Hopper is separate software and requires its own license.
+3. Obtain approval before installing external software, then run `npx -y rea-agents setup --yes`.
+4. If macOS or an installer requests human input, tell the user exactly what needs attention. After they finish, rerun setup and doctor.
+5. If setup registers a new MCP server, tell the user to restart their coding agent to load all REA tools. Direct CLI commands remain available before restart.
+
+## Locate the app
+
+Accept a human-readable app name. Search macOS application locations and system metadata. If one clear match is found, continue without asking for a path. If several apps match, show their names and locations and ask which one the user means. If none match, ask where the app is installed.
+
+REA accepts a `.app` bundle directly. Do not expose its internal `Contents/MacOS` path unless it helps explain an error.
+
+## Investigate
+
+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.
+
+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.
+
+## Build
+
+When requested, use normal coding tools to build a version suited to the user's project, stack, interface, and requirements. Keep the implementation tied to what the investigation established, and distinguish observed behavior from assumptions or design choices.
+
+## Human input and cleanup
+
+Hopper or macOS may show a window that needs human input. Tell the user what appeared and ask them to handle it; do not guess or take over unrelated UI. Call `close_binary` when the investigation is complete.