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(session): admit direct native dispatch metadata providers
morluto50b6975d8610
diff --git a/docs/native-investigation.md b/docs/native-investigation.mdindex 61f199654..1a19d6fd8 100644--- a/docs/native-investigation.md+++ b/docs/native-investigation.md@@ -430,6 +430,12 @@ complete observation.address is retained as `reported_address` in the symbol's evidence, whoselocation also remains unknown. Nonempty provider address syntax is preserved.+ Session discovery reports this workflow available when the bound provider+ offers direct metadata inspection or a `list_names` symbol inventory. The+ workflow tries direct metadata first and uses the symbol fallback only when+ that operation is unavailable; runtime failures remain failures rather than+ being replaced by symbol-only results.+## Native desktop observation`observe_native_ui` captures one explicitly selected existing PID/window ID.diff --git a/src/application/CapabilityInventory.test.ts b/src/application/CapabilityInventory.test.tsindex 231340a46..f5bba9843 100644--- a/src/application/CapabilityInventory.test.ts+++ b/src/application/CapabilityInventory.test.ts@@ -177,7 +177,7 @@ describe("capability failure reasons", () => {],}),),- ).toMatchObject({ available: false, reason: "provider_missing" });+ ).toMatchObject({ available: true, reason: "available" });});it.each([diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.tsindex 9520cf255..4d7c6890b 100644--- a/src/application/CapabilityInventory.ts+++ b/src/application/CapabilityInventory.ts@@ -1,5 +1,6 @@import { DEFAULT_CALL_RELATIONSHIP_DIRECTION } from "../contracts/enhancedInputs.js";import { CALL_RELATIONSHIP_TRAVERSALS } from "./CallRelationshipTraversal.js";+import { NATIVE_DISPATCH_METADATA_SOURCES } from "./native/NativeDispatchMetadataInspection.js";import { z } from "zod";import { sqliteDatabaseCapability } from "./sqlite/SqliteDatabaseCapability.js";import type {@@ -144,7 +145,9 @@ const ENHANCED_REQUIREMENTS: ReadonlyMap<string, ProviderComposition> = new Map("list_names","procedure_callees",],- inspect_native_dispatch_metadata: ["list_names"],+ inspect_native_dispatch_metadata: [+ Object.values(NATIVE_DISPATCH_METADATA_SOURCES),+ ],get_objc_classes: ["list_names"],get_objc_protocols: ["list_names"],batch_decompile: ["procedure_pseudo_code"],diff --git a/src/application/native/NativeDispatchMetadataInspection.ts b/src/application/native/NativeDispatchMetadataInspection.tsindex e72d17dbf..da5e31264 100644--- a/src/application/native/NativeDispatchMetadataInspection.ts+++ b/src/application/native/NativeDispatchMetadataInspection.ts@@ -9,6 +9,13 @@ import { jsonValueSchema } from "../../domain/jsonValue.js";import { err, ok } from "../../domain/result.js";import type { AnalysisOperationPort } from "../AnalysisProvider.js";import type { EnhancedResult } from "../EnhancedToolTypes.js";++/** Source operations for this workflow, shared with capability discovery. */+export const NATIVE_DISPATCH_METADATA_SOURCES = {+ binary: "inspect_native_dispatch_metadata",+ symbols: "list_names",+} as const;+/** Prefer validated binary metadata, otherwise preserve the bound provider's symbol-only coverage. */export const inspectNativeDispatch = async (analysis: AnalysisOperationPort,@@ -16,7 +23,7 @@ export const inspectNativeDispatch = async (signal?: AbortSignal,): EnhancedResult => {const binaryMetadata = await analysis.execute(- "inspect_native_dispatch_metadata",+ NATIVE_DISPATCH_METADATA_SOURCES.binary,{ max_records: maxRecords },signal === undefined ? {} : { signal },);@@ -29,7 +36,7 @@ export const inspectNativeDispatch = async (if (binaryMetadata.error._tag !== "AnalysisCapabilityUnavailableError")return err(binaryMetadata.error);const execution = await analysis.execute(- "list_names",+ NATIVE_DISPATCH_METADATA_SOURCES.symbols,{},signal === undefined ? {} : { signal },);@@ -48,7 +55,7 @@ export const inspectNativeDispatch = async (if (!names.success)return err(new AnalysisOutputError(- "list_names",+ NATIVE_DISPATCH_METADATA_SOURCES.symbols,"provider returned an invalid inventory",),);diff --git a/tests/boundary/mcp/nativeDispatchAvailability.test.ts b/tests/boundary/mcp/nativeDispatchAvailability.test.tsnew file mode 100644index 000000000..793fc28cd--- /dev/null+++ b/tests/boundary/mcp/nativeDispatchAvailability.test.ts@@ -0,0 +1,332 @@+import { rm } from "node:fs/promises";++import type { Client } from "@modelcontextprotocol/client";+import type { CallToolResult } from "@modelcontextprotocol/server";+import { afterEach, describe, expect, it } from "vitest";++import type {+ AnalysisClient,+ AnalysisProvider,+ CapabilityDescriptor,+} from "../../../src/application/AnalysisProvider.js";+import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";+import { AnalysisOutputError } from "../../../src/domain/analysisErrorCore.js";+import { inspectNativeDispatchMetadata } from "../../../src/domain/native/objcSwiftMetadata.js";+import { err, ok } from "../../../src/domain/result.js";+import type { ProviderRejectionCode } from "../../../src/contracts/providerSelection.js";+import { toolContract } from "../../../src/contracts/toolContracts.js";+import { expandToolAvailability } from "../../../src/contracts/toolOutputSchemaPrimitives.js";+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { createSessionMcpHarness } from "./sessionMcpHarness.js";++const resources: Array<{ close(): Promise<unknown> }> = [];+let directory: string | undefined;++afterEach(async () => {+ await Promise.all(resources.splice(0).map((resource) => resource.close()));+ if (directory !== undefined)+ await rm(directory, { recursive: true, force: true });+ directory = undefined;+});++const identity = {+ id: "fixture",+ name: "Fixture analysis provider",+ version: "1",+};+const dispatchMetadata = inspectNativeDispatchMetadata([+ {+ address: "0x1000",+ name: "-[BuildViewController buildTapped:]",+ },+]);+const symbolInventory = [+ { address: "0x1000", name: "-[BuildViewController buildTapped:]" },+];++type Operation = "inspect_native_dispatch_metadata" | "list_names";+type Scenario = {+ readonly name: string;+ readonly capabilities: readonly {+ readonly operation: Operation;+ readonly available: boolean;+ readonly reason?: string;+ readonly availabilityCode?: ProviderRejectionCode;+ }[];+ readonly directRuntimeFailure?: boolean;+ readonly unavailableReason?: "provider_unavailable" | "unsupported_host";+};++const directOnly: Scenario = {+ name: "direct metadata only",+ capabilities: [+ { operation: "inspect_native_dispatch_metadata", available: true },+ ],+};+const scenarios: readonly Scenario[] = [+ directOnly,+ {+ name: "symbol-only fallback",+ capabilities: [{ operation: "list_names", available: true }],+ },+ { name: "neither operation", capabilities: [] },+ {+ name: "direct operation unavailable with symbol fallback",+ capabilities: [+ {+ operation: "inspect_native_dispatch_metadata",+ available: false,+ reason: "Direct metadata inspection is unavailable.",+ },+ { operation: "list_names", available: true },+ ],+ },+ {+ name: "direct runtime failure with symbol fallback",+ capabilities: [+ { operation: "inspect_native_dispatch_metadata", available: true },+ { operation: "list_names", available: true },+ ],+ directRuntimeFailure: true,+ },+ {+ name: "direct host denial with usable symbol fallback",+ capabilities: [+ {+ operation: "inspect_native_dispatch_metadata",+ available: false,+ reason: "Direct metadata inspection requires another host.",+ availabilityCode: "unsupported_host",+ },+ { operation: "list_names", available: true },+ ],+ },+ {+ name: "unavailable direct operation without symbol fallback",+ capabilities: [+ {+ operation: "inspect_native_dispatch_metadata",+ available: false,+ reason: "Direct metadata inspection is unavailable.",+ },+ ],+ unavailableReason: "provider_unavailable",+ },+];++describe("native dispatch availability at the public MCP boundary", () => {+ it.each(scenarios)(+ "preserves $name capability semantics",+ async (scenario) => {+ directory = await createTestTempDirectory(+ "rea-native-dispatch-availability-",+ );+ const calls: Operation[] = [];+ const { mcp, first } = await createSessionMcpHarness(+ directory,+ () => provider(scenario, calls),+ resources,+ );+ const opened = await mcp.callTool({+ name: "open_binary",+ arguments: { path: first },+ });+ expect(opened.isError).not.toBe(true);++ try {+ const inventory = await readInventory(mcp);+ const availability = dispatchAvailability(inventory);+ const result = await mcp.callTool({+ name: "inspect_native_dispatch_metadata",+ arguments: { max_records: 10 },+ });+ assertExecution(scenario, result, calls);++ if (scenario.unavailableReason !== undefined) {+ expect(availability).toMatchObject({+ available: false,+ reason: scenario.unavailableReason,+ remediation: "Direct metadata inspection is unavailable.",+ });+ } else if (scenario === directOnly) {+ expect(availability).toMatchObject({+ available: true,+ reason: "available",+ remediation: null,+ });+ } else if (scenario.capabilities.length === 0) {+ expect(availability).toMatchObject({+ available: false,+ reason: "provider_missing",+ });+ } else {+ expect(availability).toMatchObject({+ available: true,+ reason: "available",+ });+ }+ } finally {+ const closed = await mcp.callTool({+ name: "close_binary",+ arguments: {},+ });+ expect(closed.isError).not.toBe(true);+ }+ },+ );++ it("reports a target requirement before probing provider operations", async () => {+ directory = await createTestTempDirectory("rea-native-dispatch-no-target-");+ const calls: Operation[] = [];+ const { mcp } = await createSessionMcpHarness(+ directory,+ () => provider(directOnly, calls),+ resources,+ );+ const inventory = await readInventory(mcp);+ expect(inventory.result.open).toBe(false);+ expect(dispatchAvailability(inventory)).toMatchObject({+ available: false,+ reason: "target_required",+ });+ expect(calls).toEqual([]);+ });+});++const readInventory = async (mcp: Client) => {+ const result = await mcp.callTool({ name: "binary_session", arguments: {} });+ return toolContract("binary_session").outputSchema.parse(+ result.structuredContent,+ );+};++const dispatchAvailability = (+ inventory: Awaited<ReturnType<typeof readInventory>>,+) =>+ expandToolAvailability(inventory.result.tool_availability).find(+ (entry) => entry.name === "inspect_native_dispatch_metadata",+ );++const assertExecution = (+ scenario: Scenario,+ result: CallToolResult,+ calls: readonly Operation[],+): void => {+ if (scenario.directRuntimeFailure) {+ expect(result.isError).toBe(true);+ expect(parseMcpToolError(result)).toMatchObject({+ error: { details: { operation: "inspect_native_dispatch_metadata" } },+ });+ expect(calls).toEqual(["inspect_native_dispatch_metadata"]);+ return;+ }+ if (+ scenario.capabilities.length === 0 ||+ scenario.unavailableReason !== undefined+ ) {+ expect(result.isError).toBe(true);+ expect(parseMcpToolError(result)).toMatchObject({+ error: { code: "capability_unavailable" },+ });+ expect(calls).toEqual([]);+ return;+ }+ expect(result.isError).not.toBe(true);+ expect(result.structuredContent).toMatchObject({+ normalized_result: {+ result: {+ objc_dispatch_implementations: [+ {+ class_name: "BuildViewController",+ selector: "buildTapped:",+ implementation_address: "0x1000",+ },+ ],+ },+ },+ });+ if (+ scenario.capabilities.some(+ ({ operation, available }) =>+ operation === "inspect_native_dispatch_metadata" && available,+ )+ )+ expect(calls).toEqual(["inspect_native_dispatch_metadata"]);+ else expect(calls).toEqual(["list_names"]);+};++const provider = (scenario: Scenario, calls: Operation[]): AnalysisProvider => {+ const capabilities: CapabilityDescriptor[] = scenario.capabilities.map(+ (capability) => {+ const common = {+ provider: identity,+ operation: capability.operation,+ effects: {+ mutatesArtifact: false,+ launchesProcess: false,+ mayShowUi: false,+ mayAccessNetwork: false,+ mayWriteFilesystem: false,+ changesPermissions: false,+ requiresRoot: false,+ },+ limitations: [],+ };+ return capability.available+ ? { ...common, available: true as const, reason: null }+ : {+ ...common,+ available: false as const,+ reason: capability.reason ?? "Fixture capability is unavailable.",+ ...(capability.availabilityCode === undefined+ ? {}+ : { availabilityCode: capability.availabilityCode }),+ };+ },+ );+ return {+ identity: () => identity,+ capabilities: () => capabilities,+ createClient: (target, profile): AnalysisClient => ({+ execute: async (operation) => {+ if (operation === "health")+ return ok(createAnalysisExecution(null, identity));+ if (+ operation !== "inspect_native_dispatch_metadata" &&+ operation !== "list_names"+ )+ throw new Error(`Unexpected provider operation: ${operation}`);+ calls.push(operation);+ if (operation === "inspect_native_dispatch_metadata") {+ if (scenario.directRuntimeFailure)+ return err(+ new AnalysisOutputError(+ operation,+ "fixture direct metadata runtime failure",+ ),+ );+ return ok(+ createAnalysisExecution(+ {+ target_sha256: target.sha256,+ provider: identity,+ analysis_profile_digest: profile?.digest ?? null,+ result: dispatchMetadata,+ },+ identity,+ { subject: target },+ ),+ );+ }+ return ok(+ createAnalysisExecution(symbolInventory, identity, {+ subject: target,+ ...(profile === undefined ? {} : { analysisProfile: profile }),+ }),+ );+ },+ close: async () => ok(null),+ }),+ };+};