Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

Merge remote-tracking branch 'origin/main' into feat/persistent-workspace-investigation-runs

morlutoee785ca9a9aa
diff --cc README.md
index 5c569cc7e,344531b6e..c45137c10
--- a/README.md
+++ b/README.md
@@@ -191,16 -191,16 +191,17 @@@ rea uninstall --purge-data # also remov
Uninstall preserves Hopper, Node.js, evidence, captures, external evidence roots, unrelated skills, and other MCP servers. It refuses malformed client configuration and never follows purge-data symlinks.
- ### CLI or coding agent?
+ ### CLI or agent?
- | If you want to… | Use |
- | --------------------------------------------------------- | -------------------------------------------------------------- |
- | Ask an agent to investigate an app and build a feature | Install the skill, then talk to your agent |
- | Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile` |
- | Validate, canonicalize, or compare Evidence v2 bundles | `rea evidence-import`, `rea evidence-export`, or `rea compare` |
- | Run or resume a persistent two-version artifact analysis | `rea investigate-versions` |
- | Import source as historical reference | `rea import-reference-source` |
- | Capture or compare controlled process behavior | `rea capture-process` or `rea compare-process-captures` |
+ | If you want to… | Use |
+ | --------------------------------------------------------------- | ------------------------------------------------------------------------- |
+ | Ask an agent to investigate an app and build a feature | Install the skill, then talk to your agent |
+ | Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile` |
+ | Validate, canonicalize, or compare Evidence v2 bundles | `rea evidence-import`, `rea evidence-export`, or `rea compare` |
++| Run or resume a persistent two-version artifact analysis | `rea investigate-versions` |
+ | Reuse immutable analysis results without relaunching a provider | Pass `--snapshot /approved/path/analysis.json` to a deep-analysis command |
+ | Import source as historical reference | `rea import-reference-source` |
+ | Capture or compare controlled process behavior | `rea capture-process` or `rea compare-process-captures` |
Filesystem evidence commands and MCP file tools are disabled until the operator approves absolute roots:
diff --cc scripts/verify-package.mjs
index dded1094c,c111edb41..9f7d55842
--- a/scripts/verify-package.mjs
+++ b/scripts/verify-package.mjs
@@@ -15,7 -15,7 +15,8 @@@ import { Client } from "@modelcontextpr
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { TextReader, Uint8ArrayWriter, ZipWriter } from "@zip.js/zip.js";
import { TOOL_CONTRACTS } from "../dist/contracts/toolContracts.js";
+import { verifyPackagedInvestigation } from "./verify-package-investigation.mjs";
+ import { verifyPackedBridge } from "./verify-packed-bridge.mjs";
const expectedToolCount = TOOL_CONTRACTS.length;
diff --cc src/cli.ts
index 5d2f74967,99d1d7f13..d667e1a97
--- a/src/cli.ts
+++ b/src/cli.ts
@@@ -18,7 -18,8 +18,9 @@@ import { parseConfig } from "./config.j
import { importReferenceSource } from "./application/ReferenceSourceImport.js";
import { registerEvidenceCommands } from "./cliEvidenceCommands.js";
import { registerProcessCommands } from "./cliProcessCommands.js";
+import { registerInvestigationCommands } from "./cliInvestigationCommands.js";
+ import { projectAnalysisError } from "./domain/errors.js";
+ import { projectReferenceSourceImportError } from "./application/ReferenceSourceImportTypes.js";
/**
* Build the one-shot Incur CLI without starting Hopper at import time.
diff --cc src/domain/errors.ts
index 3708dd66e,b499b9c33..2dbf95e57
--- a/src/domain/errors.ts
+++ b/src/domain/errors.ts
@@@ -340,52 -326,143 +350,182 @@@ export const projectAnalysisError =
};
};
- const safeDetails = (
+ const errorCategory = (
error: AnalysisError,
- ): Readonly<Record<string, string | number | boolean | null>> => {
+ ): AnalysisErrorProjection["category"] => {
+ if (error._tag === "ProcessCaptureError")
+ return error.userCategory ?? "execution_failure";
+ if (
+ error instanceof HopperRemoteError &&
+ error.diagnosticType === "authorization"
+ )
+ return "permission_required";
+ if (error instanceof ArtifactOperationError)
+ return artifactErrorCategory(error.reason);
+ if (error instanceof EvidenceFileError && error.reason === "disabled")
+ return "unavailable";
++ if (error instanceof InvestigationWorkspaceError)
++ return investigationWorkspaceCategory(error.reason);
+ return STATIC_ERROR_CATEGORIES[error._tag] ?? "execution_failure";
+ };
+
++const investigationWorkspaceCategory = (
++ reason: InvestigationWorkspaceError["reason"],
++): AnalysisErrorProjection["category"] => {
++ if (
++ reason === "disabled" ||
++ reason === "outside-root" ||
++ reason === "not-file"
++ )
++ return "unavailable";
++ if (reason === "too-large") return "truncated";
++ if (reason === "invalid-json" || reason === "integrity")
++ return "integrity_mismatch";
++ return "execution_failure";
++};
++
+ const artifactErrorCategory = (
+ reason: ArtifactOperationError["reason"],
+ ): AnalysisErrorProjection["category"] => {
+ if (reason === "integrity") return "integrity_mismatch";
+ if (reason === "limit") return "truncated";
+ if (reason === "cancelled") return "cancelled";
+ if (reason === "unavailable") return "unavailable";
+ return "execution_failure";
+ };
+
+ const STATIC_ERROR_CATEGORIES: Readonly<
+ Partial<Record<AnalysisErrorTag, AnalysisErrorProjection["category"]>>
+ > = {
+ AnalysisInputError: "invalid_input",
+ AnalysisCapabilityUnavailableError: "unsupported_provider",
+ ProviderSelectionError: "unsupported_provider",
+ EvidenceIntegrityError: "integrity_mismatch",
+ EvidenceLimitError: "truncated",
+ AnalysisCancelledError: "cancelled",
+ HopperCancelledError: "cancelled",
+ AnalysisTimeoutError: "timeout",
+ HopperTimeoutError: "timeout",
+ NoBinaryOpenError: "unavailable",
+ BinaryTargetError: "unavailable",
+ };
+
+ const userMessage = (error: AnalysisError): string => {
if (error instanceof AnalysisInputError)
- return { operation: error.operation };
- if (error instanceof AnalysisOutputError)
- return { operation: error.operation, reason: error.reason };
- if (error instanceof AnalysisCapabilityUnavailableError)
- return {
- providerId: error.providerId,
- operation: error.operation,
- reason: error.reason,
- };
- if (error instanceof AnalysisCancelledError)
- return { operation: error.operation };
- if (error instanceof AnalysisTimeoutError)
- return { operation: error.operation, timeoutMs: error.timeoutMs };
- if (error instanceof ProviderSelectionError)
- return { operation: error.operation };
- if (error instanceof ProviderAdapterError)
- return { providerId: error.providerId, operation: error.operation };
+ return "Analysis input is invalid. Check the arguments and try again.";
+ if (UNREADABLE_OUTPUT_TAGS.has(error._tag))
+ return "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.";
+ if (UNSUPPORTED_PROVIDER_TAGS.has(error._tag))
+ return "This analysis is unavailable for the current target. Choose another analysis or target.";
+ if (CANCELLED_TAGS.has(error._tag))
+ return "Analysis was cancelled. Start it again when ready.";
+ if (TIMEOUT_TAGS.has(error._tag))
+ return "Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.";
+ if (ADAPTER_FAILURE_TAGS.has(error._tag))
+ return "Analysis could not complete. Retry once; if it continues, run `rea doctor`.";
+ if (START_FAILURE_TAGS.has(error._tag))
+ return "Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.";
if (error instanceof ArtifactOperationError)
- return {
- operation: error.operation,
- reason: error.reason,
- ...error.artifactDetails,
- };
+ return artifactMessage(error.reason);
+ if (error instanceof EvidenceIntegrityError)
+ return "Evidence is invalid or has changed. Recreate or re-import it, then try again.";
if (error instanceof EvidenceLimitError)
- return { limit: error.limit, maximum: error.maximum };
+ return "Evidence is too large for this session. Reduce the evidence set and try again.";
if (error instanceof EvidenceFileError)
- return { operation: error.operation, reason: error.reason };
+ return evidenceFileMessage(error.reason);
+ if (error instanceof InvestigationWorkspaceError)
- return { operation: error.operation, reason: error.reason };
- if (error instanceof UnknownRegistryError) return { reason: error.reason };
- if (error instanceof HopperTimeoutError)
- return { timeoutMs: error.timeoutMs };
- if (error instanceof HopperRemoteError)
- return {
- code: error.code,
- safeMessage: error.safeMessage,
- diagnosticType: error.diagnosticType,
- };
- if (error instanceof HopperProcessError) return { exitCode: error.exitCode };
- return {};
++ return investigationWorkspaceMessage(error.reason);
+ if (error instanceof UnknownRegistryError)
+ return "Evidence state changed before the update completed. Refresh the current state and try again.";
+ if (error instanceof ConfigurationError)
+ return "REA configuration is invalid. Run `rea doctor` and fix the reported setting.";
+ if (error instanceof NoBinaryOpenError) return error.message;
+ if (error instanceof BinaryTargetError)
+ return "REA could not open that app or binary. Check that the path exists, is readable, and points to a supported file.";
+ if (error._tag === "ProcessCaptureError")
+ return (
+ error.userMessage ??
+ "Process capture could not complete. Run `rea doctor`, then review capture policy and try again."
+ );
+ return "Analysis could not complete. Run `rea doctor`, then try again.";
+ };
+
+ const UNREADABLE_OUTPUT_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
+ "AnalysisProtocolError",
+ "AnalysisOutputError",
+ "HopperProtocolError",
+ ]);
+ const UNSUPPORTED_PROVIDER_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
+ "AnalysisCapabilityUnavailableError",
+ "ProviderSelectionError",
+ ]);
+ const CANCELLED_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
+ "AnalysisCancelledError",
+ "HopperCancelledError",
+ ]);
+ const TIMEOUT_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
+ "AnalysisTimeoutError",
+ "HopperTimeoutError",
+ ]);
+ const ADAPTER_FAILURE_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
+ "ProviderAdapterError",
+ "HopperRemoteError",
+ ]);
+ const START_FAILURE_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
+ "HopperProcessError",
+ "HopperStartError",
+ ]);
+
+ const artifactMessage = (reason: ArtifactOperationError["reason"]): string => {
+ if (reason === "cancelled")
+ return "Artifact operation was cancelled. Start it again when ready.";
+ if (reason === "limit")
+ return "Artifact is too large to process safely. Narrow the requested path or use a smaller artifact.";
+ if (reason === "path")
+ return "Artifact path is not allowed. Choose a path inside the artifact and try again.";
+ if (reason === "unavailable")
+ return "Artifact format is not available on this system. Choose another artifact or supported environment.";
+ if (reason === "format" || reason === "integrity")
+ return "Artifact is invalid or has changed. Get a fresh copy and try again.";
+ return "Artifact could not be read or written. Check file access and try again.";
+ };
+
+ const evidenceFileMessage = (reason: EvidenceFileError["reason"]): string => {
+ if (reason === "disabled")
+ return "Evidence file access is disabled. Enable an evidence directory or use inline evidence.";
+ if (reason === "outside-root")
+ return "Evidence path is outside the allowed directory. Choose a path inside the configured evidence directory.";
+ if (reason === "not-file")
+ return "Evidence path does not point to a file. Choose an evidence file and try again.";
+ if (reason === "too-large")
+ return "Evidence file is too large. Reduce its size and try again.";
+ if (reason === "exists")
+ return "Evidence file already exists. Choose another path or allow overwrite.";
+ if (reason === "invalid-json")
+ return "Evidence file is not valid JSON. Repair or recreate the file and try again.";
+ return "Evidence file could not be accessed. Check file permissions and try again.";
+ };
+
++const investigationWorkspaceMessage = (
++ reason: InvestigationWorkspaceError["reason"],
++): string => {
++ if (reason === "disabled")
++ return "Investigation workspace access is disabled. Configure a workspace directory and try again.";
++ if (reason === "outside-root")
++ return "Investigation workspace is outside the allowed directory. Choose a configured workspace directory and try again.";
++ if (reason === "not-file")
++ return "Investigation workspace path is not a file. Choose a workspace file and try again.";
++ if (reason === "too-large")
++ return "Investigation workspace is too large. Reduce its size and try again.";
++ if (reason === "invalid-json" || reason === "integrity")
++ return "Investigation workspace is invalid or has changed. Recreate or repair it, then try again.";
++ if (reason === "locked")
++ return "Another investigation update is in progress. Try again when it finishes.";
++ if (reason === "revision-conflict" || reason === "name-conflict")
++ return "Investigation workspace state changed. Refresh the current state and try again.";
++ return "Investigation workspace could not be accessed. Check file permissions and try again.";
+};
+
const KNOWN_ERROR_TAGS = {
AnalysisProtocolError: true,
AnalysisInputError: true,
diff --cc src/server/registerInvestigationTools.ts
index eba3fbbd6,9c73e78f4..6c583057b
--- a/src/server/registerInvestigationTools.ts
+++ b/src/server/registerInvestigationTools.ts
@@@ -53,98 -49,59 +53,99 @@@ const registerChangedBehavior =
server: McpServer,
session: BinarySessionPort,
contract: ToolContract<"find_changed_behavior">,
+ evidenceFilePolicy: EvidenceFilePolicy,
): void => {
- server.registerTool(contract.name, contractOptions(contract), (input) => {
- const parsed = changedBehaviorInputSchema.parse(input);
- const closure = evidenceClosure(
- session,
- comparisonClosure(parsed.comparisons),
- );
- if (!closure.ok) return toCallToolResult(closure, contract);
- const links = closure.value;
- const result = findChangedBehavior(
- parsed.comparisons,
- parsed.offset,
- parsed.limit,
- );
- const evidence = createEvidence(undefined, CHANGED_BEHAVIOR_PROVIDER, {
- predicateType: "rea.changed-behavior/v1",
- operation: contract.name,
- parameters: {
- comparison_evidence_ids: parsed.comparisons.map(
- ({ evidence_id: id }) => id,
- ),
- offset: parsed.offset,
- limit: parsed.limit,
- },
- result: jsonValueSchema.parse(result),
- confidence: "derived",
- authority: "analyst-inference",
- limitations: result.limitations,
- evidenceLinks: links,
- });
- const recorded = recordWorkflowEvidence(
- session,
- evidence,
- parsed.unknown_registry_approved,
- result.behavior_status === "unknown" ||
- result.behavior_status === "truncated",
- {
- question:
- "Did both versions behave the same under a complete controlled replay?",
- domain: "changed-behavior",
- requiredAuthority: "controlled-replay",
- requiredConfidence: "observed",
- probes: [
- {
- operation: "capture_process_scenario",
- rationale:
- "Capture both versions under the same bounded scenario and environment.",
- },
- ],
- },
- );
- return toCallToolResult(recorded, contract);
- });
+ server.registerTool(
+ contract.name,
+ contractOptions(contract),
+ async (input, context) => {
+ const parsed = changedBehaviorInputSchema.parse(input);
+ if (parsed.investigation_run !== undefined) {
+ const investigated = await runCrossVersionInvestigation(
+ parsed.investigation_run,
+ evidenceFilePolicy,
+ session,
+ context.mcpReq.signal,
+ );
+ if (!investigated.ok) return toCallToolResult(investigated, contract);
+ const result = changedBehaviorResultSchema.parse(
+ investigated.value.evidence.normalized_result,
+ );
+ return toCallToolResult(
+ recordWorkflowEvidence(
+ session,
+ investigated.value.evidence,
+ parsed.unknown_registry_approved,
+ result.behavior_status === "unknown" ||
+ result.behavior_status === "truncated",
+ {
+ question: `Automatic changed behavior run ${result.investigation_run?.run_id ?? "unknown"} remains ${result.behavior_status}`,
+ domain: "changed-behavior",
+ requiredAuthority: "controlled-replay",
+ requiredConfidence: "observed",
+ probes: [
+ {
+ operation: "capture_process_scenario",
+ rationale:
+ "Capture both versions under the same bounded scenario and environment.",
+ },
+ ],
+ },
+ ),
+ contract,
+ );
+ }
+ const closure = evidenceClosure(
+ session,
+ comparisonClosure(parsed.comparisons),
+ );
+ if (!closure.ok) return toCallToolResult(closure, contract);
+ const links = closure.value;
+ const result = findChangedBehavior(
+ parsed.comparisons,
+ parsed.offset,
+ parsed.limit,
+ );
+ const evidence = createEvidence(undefined, CHANGED_BEHAVIOR_PROVIDER, {
+ predicateType: "rea.changed-behavior/v1",
+ operation: contract.name,
+ parameters: {
+ comparison_evidence_ids: parsed.comparisons.map(
+ ({ evidence_id: id }) => id,
+ ),
+ offset: parsed.offset,
+ limit: parsed.limit,
+ },
+ result: jsonValueSchema.parse(result),
+ confidence: "derived",
+ authority: "analyst-inference",
+ limitations: result.limitations,
+ evidenceLinks: links,
+ });
+ const recorded = recordWorkflowEvidence(
+ session,
+ evidence,
+ parsed.unknown_registry_approved,
+ result.behavior_status === "unknown" ||
+ result.behavior_status === "truncated",
+ {
- question: `Changed behavior result ${evidence.evidence_id} remains ${result.behavior_status}`,
++ question:
++ "Did both versions behave the same under a complete controlled replay?",
+ domain: "changed-behavior",
+ requiredAuthority: "controlled-replay",
+ requiredConfidence: "observed",
+ probes: [
+ {
+ operation: "capture_process_scenario",
+ rationale:
+ "Capture both versions under the same bounded scenario and environment.",
+ },
+ ],
+ },
+ );
+ return toCallToolResult(recorded, contract);
+ },
+ );
};
const registerCallPath = (
diff --cc tests/errors.test.ts
index 80be4bac3,0077e5838..4ca57fa34
--- a/tests/errors.test.ts
+++ b/tests/errors.test.ts
@@@ -103,17 -97,42 +103,42 @@@ describe("analysis error projection", (
} satisfies Readonly<Record<AnalysisErrorTag, AnalysisError>>;
const errors = Object.values(byTag);
const projected = errors.map(projectAnalysisError);
- expect(new Set(projected.map(({ tag }) => tag)).size).toBe(errors.length);
- expect(projected).toHaveLength(23);
+ expect(projected).toHaveLength(24);
- expect(JSON.stringify(projected)).not.toContain("secret-token");
- expect(JSON.stringify(projected)).not.toContain("/secret/local/path");
+ const serialized = JSON.stringify(projected);
+ for (const hidden of [
+ "secret-token",
+ "/secret/local/path",
+ "fixture",
+ "overview",
+ "AnalysisCapabilityUnavailableError",
+ "main.js",
+ "declaredSha256",
+ ])
+ expect(serialized).not.toContain(hidden);
expect(
- projected.find(({ tag }) => tag === "HopperTimeoutError"),
- ).toMatchObject({ details: { timeoutMs: 100 } });
+ projectAnalysisError(byTag.AnalysisCapabilityUnavailableError),
+ ).toMatchObject({
+ category: "unsupported_provider",
+ });
expect(
- projected.find(({ tag }) => tag === "ProviderAdapterError"),
+ projectAnalysisError(
+ new ArtifactOperationError("inventory_artifact", "integrity", {
+ logicalPath: "main.js",
+ declaredSha256: "a".repeat(64),
+ calculatedSha256: "b".repeat(64),
+ unpacked: true,
+ }),
+ ),
).toMatchObject({
- details: { providerId: "fixture", operation: "overview" },
+ category: "integrity_mismatch",
});
+ expect(projected.every(({ message }) => message.length > 0)).toBe(true);
+ expect(
+ projected.every(({ message }) =>
+ /try again|run `rea doctor`|current target|when ready|smaller request|smaller artifact|fresh copy|re-import|reduce|inline evidence|configured evidence directory|evidence file|allow overwrite|refresh the current state|reported setting|call open_binary|supported file|review capture policy/u.test(
+ message,
+ ),
+ ),
+ ).toBe(true);
});
});
diff --cc tests/investigationMcp.test.ts
index aaebe1675,0417eb79c..24f9cd9dc
--- a/tests/investigationMcp.test.ts
+++ b/tests/investigationMcp.test.ts
@@@ -14,75 -11,12 +14,76 @@@ import
PROCESS_CAPTURE_REFERENCE,
PROCESS_COMPARISON_EVIDENCE,
} from "../src/contracts/investigationExamples.js";
- import { parseEvidence } from "../src/domain/evidence.js";
+ import { createEvidence, parseEvidence } from "../src/domain/evidence.js";
+ import { jsonObjectSchema, jsonValueSchema } from "../src/domain/jsonValue.js";
import { createServer } from "../src/server/createServer.js";
import { observed } from "./fixtures/analysisExecution.js";
+import { readInvestigationWorkspace } from "../src/application/InvestigationWorkspaceStore.js";
+import type { EvidenceFilePolicy } from "../src/domain/evidenceBundle.js";
describe("investigation MCP workflows", () => {
+ it("runs and reuses a persistent cross-version workspace", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "rea-investigation-mcp-"));
+ const left = join(directory, "left");
+ const right = join(directory, "right");
+ const workspace = join(directory, "workspace.json");
+ await Promise.all([mkdir(left), mkdir(right)]);
+ await Promise.all([
+ writeFile(join(left, "feature.txt"), "old\n"),
+ writeFile(join(right, "feature.txt"), "new\n"),
+ ]);
+ const filePolicy = evidencePolicy(directory);
+ const { session, server, client } = await connected(filePolicy);
+ try {
+ const arguments_ = {
+ investigation_run: {
+ approved: true,
+ workspace_path: workspace,
+ workspace_name: "mcp-release-diff",
+ left_path: left,
+ right_path: right,
+ options: { page_size: 500, change_limit: 100 },
+ },
+ };
+ const first = await client.callTool({
+ name: "find_changed_behavior",
+ arguments: arguments_,
+ });
+ expect(first.isError).not.toBe(true);
+ const firstEvidence = parseEvidence(
+ z.object({ result: z.unknown() }).parse(first.structuredContent).result,
+ );
+ expect(firstEvidence.normalized_result).toMatchObject({
+ behavior_status: "unknown",
+ summary: { static_candidates: 2 },
+ investigation_run: { inventory_evidence_count: 2 },
+ });
+ expect(session.hasEvidence(firstEvidence.evidence_id)).toBe(true);
+ const loaded = await readInvestigationWorkspace(workspace, filePolicy);
+ expect(loaded).toMatchObject({
+ ok: true,
+ value: { revision: 3, runs: [{ status: "complete" }] },
+ });
+
+ const second = await client.callTool({
+ name: "find_changed_behavior",
+ arguments: arguments_,
+ });
+ expect(second.isError, JSON.stringify(second)).not.toBe(true);
+ const secondEvidence = parseEvidence(
+ z.object({ result: z.unknown() }).parse(second.structuredContent)
+ .result,
+ );
+ expect(secondEvidence.evidence_id).toBe(firstEvidence.evidence_id);
+ expect(
+ await readInvestigationWorkspace(workspace, filePolicy),
+ ).toMatchObject({ ok: true, value: { revision: 3 } });
+ } finally {
+ await close(session, server, client);
+ await rm(directory, { recursive: true, force: true });
+ }
+ });
+
it("aggregates comparison Evidence and records an approved runtime gap", async () => {
const { session, server, client } = await connected();
const comparison =