Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
Merge remote-tracking branch 'origin/main' into feat/persistent-workspace-investigation-runs
morlutoee785ca9a9aa
diff --cc README.mdindex 5c569cc7e,344531b6e..c45137c10--- a/README.md+++ b/README.md@@@ -191,16 -191,16 +191,17 @@@ rea uninstall --purge-data # also removUninstall 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.mjsindex dded1094c,c111edb41..9f7d55842--- a/scripts/verify-package.mjs+++ b/scripts/verify-package.mjs@@@ -15,7 -15,7 +15,8 @@@ import { Client } from "@modelcontextprimport { 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.tsindex 5d2f74967,99d1d7f13..d667e1a97--- a/src/cli.ts+++ b/src/cli.ts@@@ -18,7 -18,8 +18,9 @@@ import { parseConfig } from "./config.jimport { 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.tsindex 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.tsindex 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.tsindex 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.tsindex aaebe1675,0417eb79c..24f9cd9dc--- a/tests/investigationMcp.test.ts+++ b/tests/investigationMcp.test.ts@@@ -14,75 -11,12 +14,76 @@@ importPROCESS_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 =