Skip to content

armgit / rea

Public Imported from GitHub
0

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

fix(analysis): propagate typed cancellation across batch stages

morluto459c0951f268
diff --git a/src/application/EnhancedTools.ts b/src/application/EnhancedTools.ts
index 7bd340d3b..71d1637d4 100644
--- a/src/application/EnhancedTools.ts
+++ b/src/application/EnhancedTools.ts
@@ -47,6 +47,49 @@ import { resolveProcedureAddress } from "./ProcedureAddressResolution.js";
import { traceLiteralFeature } from "./EnhancedLiteralTracing.js";
import { projectNativeApiInspection } from "./native/NativeApiInspection.js";
+type BatchProcedureIdentity =
+ | {
+ readonly status: "resolved";
+ readonly address: string;
+ readonly name: string | null;
+ readonly name_error?: ReturnType<typeof projectAnalysisError>;
+ }
+ | {
+ readonly status: "unknown";
+ readonly error: ReturnType<typeof projectAnalysisError>;
+ };
+
+type BatchResolution = {
+ readonly address: string;
+ readonly result: Result<string, AnalysisError>;
+};
+
+type BatchReadyItem = {
+ readonly address: string;
+ readonly procedure: BatchProcedureIdentity;
+ readonly providerProcedure: string;
+};
+
+type BatchDecompileItem = {
+ readonly address: string;
+ readonly procedure: BatchProcedureIdentity;
+ readonly status: "ok" | "error";
+ readonly pseudocode?: string;
+ readonly error?: ReturnType<typeof projectAnalysisError>;
+};
+
+const isAnalysisCancellation = (
+ error: AnalysisError,
+): error is AnalysisCancelledError => error._tag === "AnalysisCancelledError";
+
+const firstAnalysisCancellation = <Value>(
+ results: readonly Result<Value, AnalysisError>[],
+): AnalysisCancelledError | undefined => {
+ for (const result of results)
+ if (!result.ok && isAnalysisCancellation(result.error)) return result.error;
+ return undefined;
+};
+
/**
* Composes direct provider operations into bounded reverse-engineering tools.
* Direct callers use `execute`; adapters that own validation use
@@ -259,52 +302,34 @@ export class EnhancedTools {
addresses: readonly string[],
signal?: AbortSignal,
): EnhancedResult {
- const items = await Promise.all(
+ const resolutions = await Promise.all(
addresses.map(async (address) => {
- const resolved = await resolveProcedureAddress(
+ const result = await resolveProcedureAddress(
this.#call.bind(this),
address,
signal,
);
- const procedure = resolved.ok
- ? await this.#batchProcedureIdentity(resolved.value, signal)
- : {
- status: "unknown" as const,
- error: projectAnalysisError(resolved.error),
- };
- const result = await this.#call(
- "procedure_pseudo_code",
- { procedure: resolved.ok ? resolved.value : address },
- signal,
- resolved.ok ? "provider" : undefined,
- );
- if (!result.ok)
- return {
- address,
- procedure,
- status: "error" as const,
- error: projectAnalysisError(result.error),
- };
- if (typeof result.value !== "string" || result.value.length === 0)
- return {
- address,
- procedure,
- status: "error" as const,
- error: projectAnalysisError(
- new AnalysisOutputError(
- "procedure_pseudo_code",
- "provider returned empty pseudocode",
- ),
- ),
- };
- return {
- address,
- procedure,
- status: "ok" as const,
- pseudocode: result.value,
- };
+ return { address, result };
}),
);
+ const resolutionCancellation = firstAnalysisCancellation(
+ resolutions.map(({ result }) => result),
+ );
+ if (resolutionCancellation !== undefined)
+ return err(resolutionCancellation);
+
+ const identities = await this.#batchIdentities(resolutions, signal);
+ const ready: BatchReadyItem[] = [];
+ for (const identity of identities) {
+ if (!identity.ok) return err(identity.error);
+ ready.push(identity.value);
+ }
+ const decompilations = await this.#batchPseudocode(ready, signal);
+ const items: BatchDecompileItem[] = [];
+ for (const decompilation of decompilations) {
+ if (!decompilation.ok) return err(decompilation.error);
+ items.push(decompilation.value);
+ }
const succeeded = items.filter(({ status }) => status === "ok").length;
return ok({
items,
@@ -314,12 +339,91 @@ export class EnhancedTools {
});
}
- async #batchProcedureIdentity(address: string, signal?: AbortSignal) {
+ async #batchIdentities(
+ resolutions: readonly BatchResolution[],
+ signal?: AbortSignal,
+ ): Promise<Result<BatchReadyItem, AnalysisCancelledError>[]> {
+ return Promise.all(
+ resolutions.map(async ({ address, result }) => {
+ if (!result.ok)
+ return ok({
+ address,
+ providerProcedure: address,
+ procedure: {
+ status: "unknown" as const,
+ error: projectAnalysisError(result.error),
+ },
+ });
+ const identity = await this.#batchProcedureIdentity(
+ result.value,
+ signal,
+ );
+ return identity.ok
+ ? ok({
+ address,
+ providerProcedure: result.value,
+ procedure: identity.value,
+ })
+ : err(identity.error);
+ }),
+ );
+ }
+
+ async #batchPseudocode(
+ ready: readonly BatchReadyItem[],
+ signal?: AbortSignal,
+ ): Promise<Result<BatchDecompileItem, AnalysisCancelledError>[]> {
+ return Promise.all(
+ ready.map(async ({ address, procedure, providerProcedure }) => {
+ const result = await this.#call(
+ "procedure_pseudo_code",
+ { procedure: providerProcedure },
+ signal,
+ procedure.status === "resolved" ? "provider" : undefined,
+ );
+ if (!result.ok && isAnalysisCancellation(result.error))
+ return err(result.error);
+ const item: BatchDecompileItem = !result.ok
+ ? {
+ address,
+ procedure,
+ status: "error",
+ error: projectAnalysisError(result.error),
+ }
+ : typeof result.value !== "string" || result.value.length === 0
+ ? {
+ address,
+ procedure,
+ status: "error",
+ error: projectAnalysisError(
+ new AnalysisOutputError(
+ "procedure_pseudo_code",
+ "provider returned empty pseudocode",
+ ),
+ ),
+ }
+ : {
+ address,
+ procedure,
+ status: "ok",
+ pseudocode: result.value,
+ };
+ return ok(item);
+ }),
+ );
+ }
+
+ async #batchProcedureIdentity(
+ address: string,
+ signal?: AbortSignal,
+ ): Promise<Result<BatchProcedureIdentity, AnalysisCancelledError>> {
const observed = await this.#call("address_name", { address }, signal);
+ if (!observed.ok && isAnalysisCancellation(observed.error))
+ return err(observed.error);
const named =
observed.ok &&
(typeof observed.value === "string" || observed.value === null);
- return {
+ return ok({
status: "resolved" as const,
address,
name: named ? observed.value : null,
@@ -335,7 +439,7 @@ export class EnhancedTools {
: observed.error,
),
}),
- };
+ });
}
async #callGraph(
@@ -385,6 +489,7 @@ export class EnhancedTools {
"provider",
);
if (!result.ok) {
+ if (isAnalysisCancellation(result.error)) return result;
graph[level].push({
address: current.address,
status: "error",
diff --git a/tests/boundary/mcp/enhancedTools.03-returns-typed-graph-failures-and.test.ts b/tests/boundary/mcp/enhancedTools.03-returns-typed-graph-failures-and.test.ts
index aaf1068ea..340bc01e4 100644
--- a/tests/boundary/mcp/enhancedTools.03-returns-typed-graph-failures-and.test.ts
+++ b/tests/boundary/mcp/enhancedTools.03-returns-typed-graph-failures-and.test.ts
@@ -2,8 +2,6 @@ import { afterEach, describe, expect, it } from "vitest";
import type { AnalysisOperationPort } from "../../../src/application/AnalysisProvider.js";
import { EnhancedTools } from "../../../src/application/EnhancedTools.js";
-import { AnalysisOutputError } from "../../../src/domain/analysisErrorCore.js";
-import { err } from "../../../src/domain/result.js";
import {
closeEnhancedToolResources,
@@ -16,43 +14,15 @@ import { observed as ok } from "../../fixtures/analysisExecution.js";
afterEach(closeEnhancedToolResources);
describe("enhanced MCP tools", () => {
- it("returns typed graph failures and stable unresolved-name results", async () => {
+ it("returns stable unresolved-name results", async () => {
const tools = new EnhancedTools({
- execute: (name) =>
- name === "procedure_address"
- ? Promise.resolve(ok("0x1"))
- : name === "procedure_callees"
- ? Promise.resolve(err(new AnalysisOutputError(name, "failed")))
- : Promise.resolve(ok(inventory({}))),
+ execute: () => Promise.resolve(ok(inventory({}))),
});
- const graph = await tools.execute("get_call_graph", {
- address: "0x1",
- direction: "forward",
- });
const unresolved = await tools.execute("find_xrefs_to_name", {
name: "missing",
});
- expect(graph).toMatchObject({
- ok: true,
- value: {
- graph: {
- "0": [
- {
- address: "0x1",
- status: "error",
- error: {
- category: "execution_failure",
- message:
- "Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",
- },
- },
- ],
- },
- limitations: [],
- },
- });
expect(unresolved).toEqual({
ok: true,
value: {
diff --git a/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts b/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts
index f9d9afcd5..38b769715 100644
--- a/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts
+++ b/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts
@@ -2,7 +2,6 @@ import { afterEach, describe, expect, it } from "vitest";
import type { AnalysisOperationPort } from "../../../src/application/AnalysisProvider.js";
import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";
-import { EnhancedTools } from "../../../src/application/EnhancedTools.js";
import {
AnalysisCapabilityUnavailableError,
AnalysisCancelledError,
@@ -11,7 +10,12 @@ import {
import type { RelationshipCoverage } from "../../../src/domain/relationshipCoverage.js";
import { err, ok as resultOk } from "../../../src/domain/result.js";
-import { closeEnhancedToolResources, connect } from "./enhancedToolsHarness.js";
+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";
+import {
+ closeEnhancedToolResources,
+ connect,
+ jsonResult,
+} from "./enhancedToolsHarness.js";
import { observed as ok } from "../../fixtures/analysisExecution.js";
afterEach(closeEnhancedToolResources);
@@ -312,6 +316,98 @@ describe("trace_call_path MCP outcome semantics", () => {
});
});
+describe("enhanced MCP batch cancellation", () => {
+ it.each([
+ {
+ stage: "selector resolution",
+ cancelAt: "procedure_address",
+ expectedCalls: ["procedure_address:0x1"],
+ operation: "procedure_address",
+ },
+ {
+ stage: "entry-label lookup",
+ cancelAt: "address_name",
+ expectedCalls: ["procedure_address:0x1", "address_name:0x1"],
+ operation: "address_name",
+ },
+ {
+ stage: "pseudocode read",
+ cancelAt: "procedure_pseudo_code",
+ expectedCalls: [
+ "procedure_address:0x1",
+ "address_name:0x1",
+ "procedure_pseudo_code:0x1",
+ ],
+ operation: "procedure_pseudo_code",
+ },
+ ] as const)(
+ "returns typed cancellation from $stage without dispatching a later stage",
+ async ({ cancelAt, expectedCalls, operation }) => {
+ const calls: string[] = [];
+ const signals: boolean[] = [];
+ const client = await connect({
+ execute: async (name, arguments_, options) => {
+ const selector = String(arguments_.procedure ?? arguments_.address);
+ calls.push(`${name}:${selector}`);
+ signals.push(options?.signal?.aborted ?? false);
+ if (name === cancelAt)
+ return err(new AnalysisCancelledError(operation));
+ if (name === "procedure_address") return ok(selector);
+ if (name === "address_name") return ok("fixture_name");
+ if (name === "procedure_pseudo_code") return ok("return 0;");
+ throw new Error(`Unexpected operation: ${name}`);
+ },
+ });
+
+ const response = await client.callTool({
+ name: "batch_decompile",
+ arguments: { addresses: ["0x1"] },
+ });
+
+ expect(response.isError).toBe(true);
+ expect(response.structuredContent).toBeUndefined();
+ expect(parseMcpToolError(response)).toMatchObject({
+ error: { code: "cancelled", details: { operation } },
+ });
+ expect(calls).toEqual(expectedCalls);
+ expect(signals).toEqual(expectedCalls.map(() => false));
+ },
+ );
+
+ it("stops later batch stages across the input when one entry lookup is cancelled", async () => {
+ const calls: string[] = [];
+ const client = await connect({
+ execute: async (name, arguments_) => {
+ const selector = String(arguments_.procedure ?? arguments_.address);
+ calls.push(`${name}:${selector}`);
+ if (name === "procedure_address") return ok(selector);
+ if (name === "address_name" && selector === "0x1")
+ return err(new AnalysisCancelledError(name));
+ if (name === "address_name") return ok("fixture_name");
+ if (name === "procedure_pseudo_code") return ok("return 0;");
+ throw new Error(`Unexpected operation: ${name}`);
+ },
+ });
+
+ const response = await client.callTool({
+ name: "batch_decompile",
+ arguments: { addresses: ["0x1", "0x2"] },
+ });
+
+ expect(response.isError).toBe(true);
+ expect(response.structuredContent).toBeUndefined();
+ expect(parseMcpToolError(response)).toMatchObject({
+ error: { code: "cancelled", details: { operation: "address_name" } },
+ });
+ expect(calls).toEqual([
+ "procedure_address:0x1",
+ "procedure_address:0x2",
+ "address_name:0x1",
+ "address_name:0x2",
+ ]);
+ });
+});
+
describe("enhanced MCP batches", () => {
it("returns every batch item in caller order with its own result", async () => {
const addresses = Array.from(
@@ -358,61 +454,143 @@ describe("enhanced MCP batches", () => {
});
it("returns ordered typed batch failures and zero counts for empty input", async () => {
- const tools = new EnhancedTools({
- execute: (name, arguments_) =>
+ const client = await connect({
+ execute: async (name, arguments_) =>
name === "procedure_address"
- ? Promise.resolve(ok(String(arguments_.procedure)))
+ ? ok(String(arguments_.procedure))
: name === "address_name"
- ? Promise.resolve(ok(null))
+ ? ok(null)
: arguments_.procedure === "0x2"
- ? Promise.resolve(
- err(new AnalysisOutputError("decompile", "failed")),
- )
- : Promise.resolve(ok("pseudo")),
+ ? err(new AnalysisOutputError("decompile", "failed"))
+ : ok("pseudo"),
});
- const result = await tools.execute("batch_decompile", {
- addresses: ["0x1", "0x2"],
+ const result = await client.callTool({
+ name: "batch_decompile",
+ arguments: { addresses: ["0x1", "0x2"] },
+ });
+ const empty = await client.callTool({
+ name: "batch_decompile",
+ arguments: { addresses: [] },
});
- const empty = await tools.execute("batch_decompile", { addresses: [] });
- expect(result).toEqual({
- ok: true,
- value: {
- items: [
- {
- address: "0x1",
- procedure: { status: "resolved", address: "0x1", name: null },
- status: "ok",
- pseudocode: "pseudo",
+ expect(result.isError).not.toBe(true);
+ expect(jsonResult(result)).toEqual({
+ items: [
+ {
+ address: "0x1",
+ procedure: { status: "resolved", address: "0x1", name: null },
+ status: "ok",
+ pseudocode: "pseudo",
+ },
+ {
+ address: "0x2",
+ procedure: { status: "resolved", address: "0x2", name: null },
+ status: "error",
+ error: {
+ code: "unreadable_output",
+ category: "execution_failure",
+ details: { operation: "decompile", reason: "failed" },
+ message:
+ "Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",
+ retryable: false,
+ remediation: {
+ action:
+ "Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",
+ },
},
+ },
+ ],
+ total: 2,
+ succeeded: 1,
+ failed: 1,
+ });
+ expect(empty.isError).not.toBe(true);
+ expect(jsonResult(empty)).toEqual({
+ items: [],
+ total: 0,
+ succeeded: 0,
+ failed: 0,
+ });
+ });
+});
+
+describe("enhanced MCP graph cancellation", () => {
+ it("returns typed relationship cancellation without expanding queued children", async () => {
+ const calls: string[] = [];
+ const signals: boolean[] = [];
+ const client = await connect({
+ execute: async (name, arguments_, options) => {
+ const selector = String(arguments_.procedure ?? arguments_.address);
+ calls.push(`${name}:${selector}`);
+ signals.push(options?.signal?.aborted ?? false);
+ if (name === "procedure_address") return relationshipExecution("0x1");
+ if (name !== "procedure_callees")
+ throw new Error(`Unexpected operation: ${name}`);
+ if (selector === "0x1") return relationshipExecution(["0x2", "0x3"]);
+ if (selector === "0x2") return err(new AnalysisCancelledError(name));
+ throw new Error("queued child 0x3 must not be expanded");
+ },
+ });
+
+ const response = await client.callTool({
+ name: "get_call_graph",
+ arguments: { address: "0x1", direction: "forward" },
+ });
+
+ expect(response.isError).toBe(true);
+ expect(response.structuredContent).toBeUndefined();
+ expect(parseMcpToolError(response)).toMatchObject({
+ error: { code: "cancelled", details: { operation: "procedure_callees" } },
+ });
+ expect(calls).toEqual([
+ "procedure_address:0x1",
+ "procedure_callees:0x1",
+ "procedure_callees:0x2",
+ ]);
+ expect(signals).toEqual([false, false, false]);
+ });
+
+ it("keeps ordinary provider failures as partial nodes and continues queued work", async () => {
+ const calls: string[] = [];
+ const client = await connect({
+ execute: async (name, arguments_) => {
+ const selector = String(arguments_.procedure ?? arguments_.address);
+ calls.push(`${name}:${selector}`);
+ if (name === "procedure_address") return relationshipExecution("0x1");
+ if (name !== "procedure_callees")
+ throw new Error(`Unexpected operation: ${name}`);
+ if (selector === "0x1") return relationshipExecution(["0x2", "0x3"]);
+ if (selector === "0x2")
+ return err(new AnalysisOutputError(name, "ordinary fixture failure"));
+ return relationshipExecution([]);
+ },
+ });
+
+ const response = await client.callTool({
+ name: "get_call_graph",
+ arguments: { address: "0x1", direction: "forward" },
+ });
+
+ expect(response.isError).not.toBe(true);
+ expect(jsonResult(response)).toMatchObject({
+ graph: {
+ "1": [
{
address: "0x2",
- procedure: { status: "resolved", address: "0x2", name: null },
status: "error",
- error: {
- code: "unreadable_output",
- category: "execution_failure",
- details: { operation: "decompile", reason: "failed" },
- message:
- "Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",
- retryable: false,
- remediation: {
- action:
- "Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",
- },
- },
+ error: { code: "unreadable_output" },
},
+ { address: "0x3", status: "ok", calls: [] },
],
- total: 2,
- succeeded: 1,
- failed: 1,
},
});
- expect(empty).toEqual({
- ok: true,
- value: { items: [], total: 0, succeeded: 0, failed: 0 },
- });
+ expect(calls).toEqual([
+ "procedure_address:0x1",
+ "procedure_callees:0x1",
+ "procedure_callees:0x2",
+ "procedure_callees:0x3",
+ ]);
});
});