Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix: retain completed observations when later analysis steps fail
morluto35f121f4acac
diff --git a/docs/android-analysis.md b/docs/android-analysis.mdindex 63b935da5..efcb05c64 100644--- a/docs/android-analysis.md+++ b/docs/android-analysis.md@@ -118,6 +118,12 @@ selected overload. Native/abstract methods with no decompiled body reportresponses remain in Evidence. Source revision is populated only for bytesmatching the audited release JAR.+If a later step fails, the error's `details.partial_observation` retains the+selected and resolved APK paths, digest, observed provider identity and versions,+and each upstream request and reply collected before the failure. Failed replies+remain available even when their payload cannot be interpreted. Cancellation+also stops target hashing before provider admission.+These operations do not execute the APK or provide split APK/AAB handling,signature validation, full resource-table semantics, native-library analysis orAndroid runtime capture. Existing artifact inventory/extraction tools can supplydiff --git a/src/android/JadxProvider.ts b/src/android/JadxProvider.tsindex e1dc7d4ab..98e798cf7 100644--- a/src/android/JadxProvider.ts+++ b/src/android/JadxProvider.ts@@ -123,24 +123,25 @@ const cleanup = async (resources.session = undefined;} catch (cause) {// Retain an uncertain workspace until the caller can resolve process ownership.- return err(- new ProviderCleanupError(- "jadx",- [- session?.transport.runId ?? "unknown",- ...(root === undefined ? [] : [root.path]),- ],- {- ...diagnostics,- reason: cause instanceof Error ? cause.message : String(cause),- provider_cleanup:- cause instanceof ProviderCleanupError- ? (cause.diagnostics ?? null)- : null,- },- { cause: previousError ?? cause },- ),+ const error = new ProviderCleanupError(+ "jadx",+ [+ session?.transport.runId ?? "unknown",+ ...(root === undefined ? [] : [root.path]),+ ],+ {+ ...diagnostics,+ reason: cause instanceof Error ? cause.message : String(cause),+ provider_cleanup:+ cause instanceof ProviderCleanupError+ ? (cause.diagnostics ?? null)+ : null,+ },+ { cause: previousError ?? cause },);+ if (previousError?.partialObservation !== undefined)+ error.retainPartialObservation(previousError.partialObservation);+ return err(error);}try {await root?.close();@@ -396,6 +397,9 @@ export class JadxProvider implements AndroidAnalysisPort {signal: options?.signal,session,});+ const partialObservation = session?.partialObservation();+ if (partialObservation !== undefined)+ previousError.retainPartialObservation(partialObservation);// Admission can fail before selecting an existing session for execution.root ??= this.#retained?.root;session ??= this.#retained?.session;diff --git a/src/android/JadxSession.ts b/src/android/JadxSession.tsindex b8e11f285..13f154b2e 100644--- a/src/android/JadxSession.ts+++ b/src/android/JadxSession.ts@@ -4,6 +4,7 @@ import {type AnalysisExecution,} from "../application/AnalysisProvider.js";import type { AndroidRequest } from "../domain/android/androidAnalysis.js";+import type { AndroidPartialObservation } from "../domain/android/androidPartialObservation.js";import {AnalysisCapabilityUnavailableError,AnalysisInputError,@@ -35,6 +36,23 @@ export class JadxSession {readonly #client = new Client({ name: "rea-android-adapter", version: "1" });#loaded: ReturnType<typeof jadxLoadSchema.parse> | undefined;#connected = false;+ #partialContext:+ | {+ readonly operation: AndroidRequest["operation"];+ readonly selectedPath: string;+ readonly target: BinaryTarget;+ readonly jarHash: string;+ readonly bridgeHash: string;+ }+ | undefined;+ #observedCalls: {+ readonly operation: string;+ readonly input: Readonly<Record<string, JsonValue>>;+ readonly response: JsonValue;+ }[] = [];+ #serverName: string | null = null;+ #serverVersion: string | null = null;+ #engineVersion: string | null = null;constructor(options: Omit<OwnedProviderProcessSpawnOptions, "runId" | "stdin">,@@ -53,6 +71,17 @@ export class JadxSession {readonly signal: AbortSignal;}): Promise<AnalysisExecution> {const { request, target, snapshot, jarHash, signal } = context;+ this.#partialContext = {+ operation: request.operation,+ selectedPath: request.input.path,+ target,+ jarHash,+ bridgeHash: context.bridgeHash,+ };+ this.#observedCalls = [];+ this.#serverName = null;+ this.#serverVersion = null;+ this.#engineVersion = null;const abort = () => {void this.transport.close().catch(() => undefined);};@@ -60,12 +89,13 @@ export class JadxSession {try {signal.throwIfAborted();this.transport.beginOperation();- const raw: JsonValue[] = [];if (!this.#connected) {await this.#client.connect(this.transport, { timeout: 30_000 });this.#connected = true;}const server = this.#client.getServerVersion();+ this.#serverName = server?.name ?? null;+ this.#serverVersion = server?.version ?? null;if (server?.name !== JADX_BRIDGE_IDENTITY.name ||server.version !== JADX_BRIDGE_IDENTITY.version@@ -75,10 +105,11 @@ export class JadxSession {request.operation,`Expected ${JADX_BRIDGE_IDENTITY.name} ${JADX_BRIDGE_IDENTITY.version}; server reported ${server?.name ?? "unknown"} ${server?.version ?? "unknown"}.`,);- const tools = this.#tools(request, target, signal, raw);+ const tools = this.#tools(request, target, signal);const runtime = jadxRuntimeSchema.parse(await tools.json("rea_jvm_status", {}),);+ this.#engineVersion = runtime.engine_reported_version;if (runtime.engine_reported_version !== JADX_RELEASE.version)throw new AnalysisCapabilityUnavailableError("jadx",@@ -117,7 +148,7 @@ export class JadxSession {bridge_sha256: context.bridgeHash,jar_sha256: jarHash,loaded,- calls: raw,+ calls: this.#observedCalls,},subject: target,limitations: JADX_LIMITATIONS,@@ -131,6 +162,32 @@ export class JadxSession {}}+ /** Facts and upstream replies retained if a later request step fails. */+ partialObservation(): AndroidPartialObservation | undefined {+ const context = this.#partialContext;+ if (context === undefined) return undefined;+ return {+ provider_id: "jadx",+ operation: context.operation,+ target: {+ selected_path: context.selectedPath,+ path: context.target.path,+ sha256: context.target.sha256,+ format: "apk",+ },+ provider_facts: {+ jar_sha256: context.jarHash,+ bridge_sha256: context.bridgeHash,+ bridge_name: JADX_BRIDGE_IDENTITY.name,+ bridge_version: JADX_BRIDGE_IDENTITY.version,+ server_name: this.#serverName,+ server_version: this.#serverVersion,+ engine_version: this.#engineVersion,+ },+ calls: this.#observedCalls,+ };+ }+/** Whether the selected Java runtime established the REA bridge protocol. */initialized(): boolean {return this.#connected;@@ -149,7 +206,6 @@ export class JadxSession {request: AndroidRequest,target: BinaryTarget,signal: AbortSignal,- raw: JsonValue[],): JadxToolPort {const call = async (name: string,@@ -160,12 +216,10 @@ export class JadxSession {{ name, arguments: input },{ timeout: 120_000, signal },);+ const observedResponse = jsonValueSchema.parse(response);+ const call = { operation: name, input, response: observedResponse };+ this.#observedCalls.push(call);const envelope = parseJadxEnvelope(response, request.operation);- raw.push({- operation: name,- input,- response: jsonValueSchema.parse(response),- });if (envelope.failed) {if (envelope.text.startsWith("{")) {const failure = jadxInputFailureSchema.safeParse(diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.tsindex b51c88656..b24e9cfb2 100644--- a/src/application/DirectAnalysis.ts+++ b/src/application/DirectAnalysis.ts@@ -269,7 +269,8 @@ const runAnalysis = async (});if (evidence !== undefined) {const recorded = session.recordEvidence(evidence);- if (!recorded.ok) return cliError(recorded.error);+ if (!recorded.ok)+ return cliError(recorded.error.retainPartialObservation(evidence));if (isWorkflowEvidenceTool(tool)) {const unknowns = recordWorkflowUnknowns({name: tool,@@ -277,7 +278,8 @@ const runAnalysis = async (evidenceId: evidence.evidence_id,recordUnknown: (unknown) => session.recordUnknown(unknown),});- if (!unknowns.ok) return cliError(unknowns.error);+ if (!unknowns.ok)+ return cliError(unknowns.error.retainPartialObservation(evidence));}}if (@@ -290,7 +292,8 @@ const runAnalysis = async (const workflowRecord = workflowSnapshotRecord(evidence, tool);if (workflowRecord !== undefined) {const recorded = session.recordWorkflowSnapshot(workflowRecord);- if (!recorded.ok) return cliError(recorded.error);+ if (!recorded.ok)+ return cliError(recorded.error.retainPartialObservation(evidence));}}if (@@ -299,13 +302,15 @@ const runAnalysis = async (evidence !== undefined) {const snapshot = session.exportAnalysisSnapshot();- if (!snapshot.ok) return cliError(snapshot.error);+ if (!snapshot.ok)+ return cliError(snapshot.error.retainPartialObservation(evidence));const written = await writeAnalysisSnapshot(snapshot.value,snapshotPath,true,);- if (!written.ok) return cliError(written.error);+ if (!written.ok)+ return cliError(written.error.retainPartialObservation(evidence));}return output;},diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.tsindex 97638ecd8..a8449146e 100644--- a/src/domain/analysisErrorBase.ts+++ b/src/domain/analysisErrorBase.ts@@ -77,8 +77,14 @@ export abstract class AnalysisError extends Error {readonly userMessage: string | undefined = undefined;readonly userCategory: "cancelled" | undefined = undefined;readonly executionFailure: string | undefined = undefined;- readonly partialObservation: AnalysisPartialObservation | undefined;+ partialObservation: AnalysisPartialObservation | undefined;readonly cleanupReport: ProcessCaptureCleanupReport | undefined = undefined;++ /** Retain a completed observation when a later step fails. */+ retainPartialObservation(observation: AnalysisPartialObservation): this {+ this.partialObservation ??= observation;+ return this;+ }}import type {PartialProcessCaptureObservation,@@ -90,6 +96,8 @@ import type { ElectronActivePartialObservation } from "./javascript/electronActiimport type { JavaScriptRuntimeObservation } from "./javascript/javascriptRuntimeObservation.js";import type { ArtifactInventoryPartialObservation } from "./artifactPartialObservation.js";import type { BrowserScenarioPartialObservation } from "./browserScenarioCapture.js";+import type { Evidence } from "./evidence.js";+import type { AndroidPartialObservation } from "./android/androidPartialObservation.js";/** Provider-neutral evidence collected before a typed analysis failure. */export type AnalysisPartialObservation =@@ -99,4 +107,6 @@ export type AnalysisPartialObservation =| ElectronActivePartialObservation| BrowserScenarioPartialObservation| JavaScriptRuntimeObservation- | ArtifactInventoryPartialObservation;+ | ArtifactInventoryPartialObservation+ | Evidence+ | AndroidPartialObservation;diff --git a/src/domain/android/androidPartialObservation.ts b/src/domain/android/androidPartialObservation.tsnew file mode 100644index 000000000..6a0cbf947--- /dev/null+++ b/src/domain/android/androidPartialObservation.ts@@ -0,0 +1,46 @@+import { z } from "zod";++import { digestSchema } from "../digests.js";+import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js";+import { localPathStringSchema } from "../localPath.js";++const operationSchema = z.enum([+ "inspect_android_package",+ "search_android_classes",+ "inspect_android_class",+ "inspect_android_method",+ "trace_android_references",+]);++/** JSON-safe Android provider facts collected before an analysis failure. */+export const androidPartialObservationSchema = z.strictObject({+ provider_id: z.literal("jadx"),+ operation: operationSchema,+ target: z.strictObject({+ selected_path: localPathStringSchema,+ path: localPathStringSchema,+ sha256: digestSchema,+ format: z.literal("apk"),+ }),+ provider_facts: z.strictObject({+ jar_sha256: digestSchema.nullable(),+ bridge_sha256: digestSchema.nullable(),+ bridge_name: z.string().min(1),+ bridge_version: z.string().min(1),+ server_name: z.string().nullable(),+ server_version: z.string().nullable(),+ engine_version: z.string().min(1).nullable(),+ }),+ calls: z.array(+ z.strictObject({+ operation: z.string().min(1),+ input: jsonObjectSchema,+ response: jsonValueSchema,+ }),+ ),+});++/** JSON-safe Android provider facts retained when analysis fails. */+export type AndroidPartialObservation = z.infer<+ typeof androidPartialObservationSchema+>;diff --git a/tests/boundary/process/androidAnalysisMcp.test.ts b/tests/boundary/process/androidAnalysisMcp.test.tsindex de2827fb8..d0179f3c5 100644--- a/tests/boundary/process/androidAnalysisMcp.test.ts+++ b/tests/boundary/process/androidAnalysisMcp.test.ts@@ -5,7 +5,9 @@ import { expect, it as test, onTestFinished } from "vitest";import { z } from "zod";import { access } from "node:fs/promises";import { ANDROID_TOOL_CONTRACTS } from "../../../src/contracts/android/androidToolContracts.js";+import { androidPartialObservationSchema } from "../../../src/domain/android/androidPartialObservation.js";import { parseEvidence } from "../../../src/domain/evidence.js";+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";import { createServer } from "../../../src/server/createServer.js";import { ToolResultDelivery } from "../../../src/server/toolResult.js";import { startMcpTransport } from "../../../src/main/transport.js";@@ -14,6 +16,7 @@ import type { AndroidAnalysisPort } from "../../../src/application/android/Androimport { silentLogger } from "../../../src/logger.js";import { parseBinaryTarget } from "../../../src/application/BinaryTargetResolver.js";import { createTestBinarySession } from "../../fixtures/binarySession.js";+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";import {createJadxProtocolFixture,verifyJadxFixtureCleanup,@@ -148,6 +151,137 @@ it("publishes and executes all APK contracts with inline Evidence and no activeawait verifyJadxFixtureCleanup(launches);});+test.each([+ {+ scenario: "failed upstream reply",+ mode: "tool-error",+ errorCode: "execution_failure",+ serverName: "rea-jadx-bridge",+ serverVersion: "1",+ engineVersion: "0.7.1",+ calls: [+ { operation: "rea_jvm_status" },+ { operation: "load_apk" },+ { operation: "get_app_info" },+ {+ operation: "get_android_manifest",+ response: { isError: true },+ },+ ],+ containsAmbientEnvironment: false,+ },+ {+ scenario: "transport error after successful replies",+ mode: "rpc-disconnect",+ errorCode: "execution_failure",+ serverName: "rea-jadx-bridge",+ serverVersion: "1",+ engineVersion: "0.7.1",+ calls: [{ operation: "rea_jvm_status" }, { operation: "load_apk" }],+ containsAmbientEnvironment: true,+ },+ {+ scenario: "empty handshake identity mismatch",+ mode: "empty-server-identity",+ errorCode: "capability_unavailable",+ serverName: "",+ serverVersion: "",+ engineVersion: null,+ calls: [],+ containsAmbientEnvironment: true,+ },+])(+ "retains Android partial observations for $scenario through MCP",+ async ({+ mode,+ errorCode,+ serverName,+ serverVersion,+ engineVersion,+ calls,+ containsAmbientEnvironment,+ }) => {+ const { provider, apk, launches } = await createJadxProtocolFixture(mode);+ const session = createTestBinarySession(() => {+ throw new Error("Unexpected native provider acquisition");+ });+ const server = createServer(+ { kind: "session", session },+ { androidAnalysis: provider },+ );+ const client = new Client({+ name: "android-partial-observation-regression",+ version: "1",+ });+ onTestFinished(async () => {+ await client.close();+ await server.close();+ await session.close();+ });+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ await server.connect(serverTransport);+ await client.connect(clientTransport);++ const response = await client.callTool({+ name: "inspect_android_package",+ arguments: { path: apk },+ });+ const projected = parseMcpToolError(response).error;+ expect(projected.code).toBe(errorCode);+ const details = z.record(z.string(), z.unknown()).parse(projected.details);+ const partial = androidPartialObservationSchema.parse(+ details.partial_observation,+ );+ expect(partial).toMatchObject({+ provider_id: "jadx",+ operation: "inspect_android_package",+ target: { selected_path: apk, path: apk, format: "apk" },+ provider_facts: {+ bridge_name: "rea-jadx-bridge",+ bridge_version: "1",+ server_name: serverName,+ server_version: serverVersion,+ engine_version: engineVersion,+ },+ calls,+ });+ if (!containsAmbientEnvironment)+ expect(JSON.stringify(partial)).not.toContain("JAVA_HOME");+ await client.close();+ await server.close();+ await verifyJadxFixtureCleanup(launches);+ },+);++it("retains partial JADX replies when owned cleanup also fails", async () => {+ const { service, apk } = await createJadxProtocolFixture("cleanup-failure");+ const result = await service.execute("inspect_android_package", {+ path: apk,+ });+ if (result.ok) throw new Error("Expected the fixture tool to fail");++ const projected = projectAnalysisError(result.error);+ expect(projected.code).toBe("cleanup_incomplete");+ expect(projected.details).toMatchObject({+ cleanup: "incomplete",+ execution_failure: "execution_failure",+ partial_observation: {+ provider_id: "jadx",+ operation: "inspect_android_package",+ calls: [+ { operation: "rea_jvm_status" },+ { operation: "load_apk" },+ { operation: "get_app_info" },+ {+ operation: "get_android_manifest",+ response: { isError: true },+ },+ ],+ },+ });+});+it("cleans an active engine when the MCP client disconnects", async () => {const { provider, apk, launches } = await createJadxProtocolFixture("stall");const session = createTestBinarySession(() => {diff --git a/tests/composition/directAnalysisSnapshotReplay.test.ts b/tests/composition/directAnalysisSnapshotReplay.test.tsindex 0a2332e0d..3fbf5d268 100644--- a/tests/composition/directAnalysisSnapshotReplay.test.ts+++ b/tests/composition/directAnalysisSnapshotReplay.test.ts@@ -3,6 +3,7 @@ import { writeFile } from "node:fs/promises";import { join } from "node:path";import { describe, expect, it } from "vitest";+import { z } from "zod";import { runDirectAnalysis } from "../../src/application/DirectAnalysis.js";import type {@@ -18,7 +19,11 @@ import {readAnalysisSnapshot,writeAnalysisSnapshot,} from "../../src/application/binary/AnalysisSnapshotFiles.js";-import { createEvidence, type Evidence } from "../../src/domain/evidence.js";+import {+ createEvidence,+ parseEvidence,+ type Evidence,+} from "../../src/domain/evidence.js";import { createEvidenceBundle } from "../../src/domain/evidenceBundle.js";import {REA_WORKFLOW_PROVIDER,@@ -646,7 +651,51 @@ describe("snapshot replay provider identity", () => {});});+const assertEvidenceSurvivesSnapshotSaveFailure = async (): Promise<void> => {+ const directory = await createTestTempDirectory("rea-workflow-save-error-");+ const path = join(directory, "fixture.hop");+ const snapshotPath = join(directory, "missing", "snapshot.json");+ await writeFile(path, "fixture");+ const starts: string[] = [];+ const calls: string[] = [];+ const provider = makeProvider(starts, calls);+ const dependencies: DirectAnalysisDependencies = {+ readConfiguration: () => parseConfig({}),+ createBinarySession: () => createTestBinarySession(provider),+ createManagedBinarySession: () => createTestBinarySession(provider),+ };++ const result = await runDirectAnalysis(+ dependencies,+ path,+ "binary_overview",+ {},+ { snapshotPath },+ );++ expect(result).toMatchObject({+ code: "invalid_request",+ details: {+ partial_observation: {+ operation: "binary_overview",+ subject: { local_path: path },+ },+ },+ });+ const partial = z+ .object({+ details: z.object({ partial_observation: z.unknown() }),+ })+ .parse(result).details.partial_observation;+ expect(parseEvidence(partial).operation).toBe("binary_overview");+ expect(calls.toSorted()).toEqual(operations.toSorted());+};+describe("workflow snapshot profile and cancellation binding", () => {+ it(+ "preserves completed Evidence when CLI snapshot persistence fails",+ assertEvidenceSurvivesSnapshotSaveFailure,+ );it("does not replay a valid entry from a different workflow profile", async () => {const directory = await createTestTempDirectory("rea-workflow-profile-");const path = join(directory, "fixture.hop");diff --git a/tests/fixtures/android/jadx-mcp.mjs b/tests/fixtures/android/jadx-mcp.mjsindex 1ab39e866..e95029d53 100644--- a/tests/fixtures/android/jadx-mcp.mjs+++ b/tests/fixtures/android/jadx-mcp.mjs@@ -6,8 +6,9 @@ import { z } from "zod";// It is a protocol fixture, not evidence of JADX decompiler support.const mode = process.env.REA_FAKE_JADX_MODE ?? "normal";const server = new McpServer({- name: "rea-jadx-bridge",- version: mode === "version" ? "99.0.0" : "1",+ name: mode === "empty-server-identity" ? "" : "rea-jadx-bridge",+ version:+ mode === "empty-server-identity" ? "" : mode === "version" ? "99.0.0" : "1",});const classes = ["fixture.Target",@@ -60,16 +61,17 @@ register("load_apk", async ({ path }) => {resources: "full",});});-register("get_app_info", () =>- json({+register("get_app_info", () => {+ if (mode === "rpc-disconnect") process.exit(17);+ return json({package: "fixture",version_name: "1",version_code: "1",min_sdk: "26",target_sdk: "33",permissions: ["android.permission.INTERNET"],- }),-);+ });+});register("get_android_manifest", () => {if (mode === "tool-error" || mode === "cleanup-failure")return {