From 15a2de737c3401f9ef1e22290fa1b8a1ac3fead9 Mon Sep 17 00:00:00 2001 From: Kaoru0822 Date: Thu, 12 Nov 2026 23:57:46 -0800 Subject: [PATCH] fix(navigation): offer available instruction observations (#10307) --- docs/reference/mcp-contracts.md | 11 + src/application/AnalysisProvider.ts | 5 + src/application/CapabilityInventory.ts | 33 ++- src/application/OperationAlternatives.ts | 84 ++++++ src/application/binary/BinarySession.ts | 21 +- .../binary/BinarySessionExecution.ts | 23 ++ .../BinarySessionRefusalAlternatives.test.ts | 200 ++++++++++++++ src/application/binary/BinarySessionStatus.ts | 53 ++-- src/contracts/toolOutputSchemaPrimitives.ts | 8 + src/domain/analysisErrorCore.ts | 7 + src/domain/analysisErrorProjection.ts | 3 + src/server/registerEvidenceTools.ts | 2 + src/server/registerSessionStatusTool.ts | 44 ++-- tests/boundary/mcp/ghidraMcpHarness.ts | 2 +- .../mcp/navigationAlternativesMcp.test.ts | 247 ++++++++++++++++++ .../kunaNavigationAlternativesMcp.test.ts | 113 ++++++++ 16 files changed, 809 insertions(+), 47 deletions(-) create mode 100644 src/application/OperationAlternatives.ts create mode 100644 src/application/binary/BinarySessionRefusalAlternatives.test.ts create mode 100644 tests/boundary/mcp/navigationAlternativesMcp.test.ts create mode 100644 tests/boundary/providers/kuna/kunaNavigationAlternativesMcp.test.ts diff --git a/docs/reference/mcp-contracts.md b/docs/reference/mcp-contracts.md index 221991344b..19f87b0db4 100644 --- a/docs/reference/mcp-contracts.md +++ b/docs/reference/mcp-contracts.md @@ -1065,6 +1065,17 @@ from an older request does not override a newer outcome. Request deadlines and cancellations neither mark nor clear availability. A new provider client starts without these outcomes. +A `provider_missing` group may also list `alternatives`: advertised tools the +current provider makes available for part of that operation's question. When +the provider does not declare `next_address` or `prev_address`, they list +whichever of `inspect_native_instruction`, `read_function_instructions` and +`procedure_assembly` qualify. These answer instruction-level questions only: +none navigates arbitrary analyzed objects such as data or addresses outside a +procedure, and neither listing order nor address plus length proves executed +control flow. Calling the missing operation returns `capability_unavailable` +with the same tools in `details.alternatives` and a remediation stating each +one's scope. Without a qualifying alternative, both keep their generic advice. + Standalone command operations (such as `inspect_with_objdump` and `execute_rizin_command`) similarly reflect observed executable launch failures: an unprobed executable is reported available; once a launch failure is observed, diff --git a/src/application/AnalysisProvider.ts b/src/application/AnalysisProvider.ts index 2aa8cd54a1..6f7786df23 100644 --- a/src/application/AnalysisProvider.ts +++ b/src/application/AnalysisProvider.ts @@ -53,6 +53,11 @@ export interface ExecutionOptions { * supplied it. */ readonly selectorOrigin?: "provider"; + /** + * Whether the caller's catalog advertises an operation; refusal recovery + * names only advertised operations. Absent means every operation is. + */ + readonly isOperationAdvertised?: (operation: AnalysisOperation) => boolean; } /** Closed operations accepted by provider-backed analysis sessions. */ diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.ts index 5886a117ce..c0ff145bb6 100644 --- a/src/application/CapabilityInventory.ts +++ b/src/application/CapabilityInventory.ts @@ -56,6 +56,7 @@ import { type AnalysisCleanupRetry, } from "../domain/analysisErrorRecovery.js"; import { isBundleResourceOperation } from "./binary/BundleResourceSession.js"; +import { offeredOperationAlternatives } from "./OperationAlternatives.js"; const FRIDA_OPERATION_NAMES: ReadonlySet = new Set( FRIDA_TOOL_CONTRACTS.map(({ name }) => name), @@ -126,6 +127,8 @@ export type AvailabilityPolicy = { type AvailabilityFacts = { readonly defaultModeAvailable?: boolean; readonly modes?: readonly ToolAvailabilityMode[]; + /** Advertised operations the current provider offers for part of the question. */ + readonly alternatives?: readonly AnalysisOperation[]; }; type Availability = AvailabilityFacts & ( @@ -162,6 +165,7 @@ type AvailabilityContext = { readonly targetFormat: string | undefined; readonly descriptors: ReadonlyMap; readonly policy: AvailabilityPolicy; + readonly isToolAdvertised: (name: string) => boolean; }; type EnhancedContractName = Extract< @@ -322,10 +326,15 @@ const ADDRESS_CONTEXT_EFFECT_COMPOSITION: ModeComposition = { ], }; -/** Build stable per-operation availability for discovery and tool visibility. */ +/** + * Build stable per-operation availability for the caller's advertised tools. + * Each tool's availability still derives from the complete provider facts; + * advertisement narrows only the reported tools and the alternatives named. + */ export const buildCapabilityInventory = ( sessionStatus: JsonValue, policy: AvailabilityPolicy, + isToolAdvertised: (name: string) => boolean = () => true, ): readonly ToolAvailability[] => { const status = statusSchema.parse(sessionStatus); const descriptors = new Map( @@ -345,6 +354,7 @@ export const buildCapabilityInventory = ( targetFormat: status.format, descriptors, policy, + isToolAdvertised, }); const effects = composedEffects( contract.name, @@ -398,8 +408,13 @@ export const buildCapabilityInventory = ( available: false, reason: availability.reason, remediation: availability.remediation, + ...(availability.alternatives === undefined + ? {} + : { alternatives: [...availability.alternatives] }), }; - }).sort((left, right) => compareUnicodeCodePoints(left.name, right.name)); + }) + .filter(({ name }) => isToolAdvertised(name)) + .sort((left, right) => compareUnicodeCodePoints(left.name, right.name)); }; type ClientRequirements = ToolAvailability["client_requirements"]; @@ -445,6 +460,9 @@ export function compactToolAvailability( ? {} : { default_mode_available: entry.default_mode_available }), ...(entry.modes === undefined ? {} : { modes: [...entry.modes] }), + ...(entry.available || entry.alternatives === undefined + ? {} + : { alternatives: [...entry.alternatives] }), ...(JSON.stringify(entry.client_requirements) === JSON.stringify(clientRequirements) ? {} @@ -959,6 +977,7 @@ const providerAvailability = ({ kind, name, policy, + isToolAdvertised, }: AvailabilityContext): Availability => { if (kind === "enhanced") return composedAvailability(name, descriptors); const launchFailure = @@ -976,12 +995,20 @@ const providerAvailability = ({ kind === "native-provider") ) return { reason: "available", remediation: null }; - if (descriptor === undefined) + if (descriptor === undefined) { + const offered = offeredOperationAlternatives( + name, + (alternative) => + descriptors.get(alternative)?.available === true && + isToolAdvertised(alternative), + ); return { reason: "provider_missing", remediation: "Install or configure a provider that declares this operation.", + ...(offered === undefined ? {} : { alternatives: offered.operations }), }; + } return descriptor.available ? { reason: "available", remediation: null } : { diff --git a/src/application/OperationAlternatives.ts b/src/application/OperationAlternatives.ts new file mode 100644 index 0000000000..d98cc78d76 --- /dev/null +++ b/src/application/OperationAlternatives.ts @@ -0,0 +1,84 @@ +import type { AnalysisOperation } from "./AnalysisProvider.js"; + +/** One operation that observes part of what a missing operation answers. */ +interface OperationAlternative { + readonly operation: AnalysisOperation; + /** What it returns, as a noun phrase. */ + readonly observes: string; +} + +/** + * Follow-ups for one question shape that an undeclared operation would have + * answered. They are conditional rather than substitutes: `limitation` + * states what none of them establishes. + */ +interface OperationAlternativeRelation { + readonly question: string; + readonly alternatives: readonly OperationAlternative[]; + readonly limitation: string; +} + +const INSTRUCTION_OBSERVATIONS: OperationAlternativeRelation = { + question: "instruction-level questions", + alternatives: [ + { + operation: "inspect_native_instruction", + observes: + "the decoded instruction or data at one exact address, with its length and static flow", + }, + { + operation: "read_function_instructions", + observes: "one analyzed procedure's instruction listing in address order", + }, + { + operation: "procedure_assembly", + observes: "one analyzed procedure's assembly text", + }, + ], + limitation: + "None navigates arbitrary analyzed objects such as data or addresses outside a procedure, and neither listing order nor address plus length proves executed control flow.", +}; + +/** Operations absent from this relation keep their consumer's generic advice. */ +const OPERATION_ALTERNATIVES: ReadonlyMap< + string, + OperationAlternativeRelation +> = new Map([ + ["next_address", INSTRUCTION_OBSERVATIONS], + ["prev_address", INSTRUCTION_OBSERVATIONS], +]); + +/** Declared alternatives the caller can run now, in declaration order. */ +export interface OfferedOperationAlternatives { + readonly operations: readonly AnalysisOperation[]; + /** Each offer's scope, what none establishes, and the provider choice. */ + readonly remediation: string; +} + +/** + * Select the declared alternatives for an operation the current provider does + * not declare. `isOffered` holds only for operations that provider makes + * available and the caller advertises. Undefined means none qualifies. + */ +export const offeredOperationAlternatives = ( + operation: string, + isOffered: (alternative: AnalysisOperation) => boolean, +): OfferedOperationAlternatives | undefined => { + const relation = OPERATION_ALTERNATIVES.get(operation); + if (relation === undefined) return undefined; + const offered = relation.alternatives.filter((alternative) => + isOffered(alternative.operation), + ); + if (offered.length === 0) return undefined; + const described = offered.map( + ({ operation: alternative, observes }) => `${alternative} (${observes})`, + ); + const listed = + described.length === 1 + ? described[0] + : `${described.slice(0, -1).join(", ")} and ${described.at(-1)}`; + return { + operations: offered.map((alternative) => alternative.operation), + remediation: `For ${relation.question}, the current provider offers ${listed}. ${relation.limitation} Running ${operation} itself requires a provider that declares it.`, + }; +}; diff --git a/src/application/binary/BinarySession.ts b/src/application/binary/BinarySession.ts index aa0487b8d2..aaf7f2a759 100644 --- a/src/application/binary/BinarySession.ts +++ b/src/application/binary/BinarySession.ts @@ -54,7 +54,10 @@ import { InvestigationRecords } from "../investigation/InvestigationRecords.js"; import { recordEvidenceSources } from "../investigation/recordEvidenceSources.js"; import { recoverProviderSourceFailure } from "../investigation/sourcePublicationRecovery.js"; import { BinarySessionRecords } from "./BinarySessionRecords.js"; -import { binarySessionStatus } from "./BinarySessionStatus.js"; +import { + binarySessionStatus, + currentRouteCapability, +} from "./BinarySessionStatus.js"; import { SessionRuntimeAvailability } from "./SessionRuntimeAvailability.js"; import { isSourceEvidenceRetainable } from "./AnalysisSnapshotCache.js"; import type { BinarySessionDetail } from "../../contracts/sessionStatusContract.js"; @@ -1567,6 +1570,8 @@ export class BinarySession parameters: arguments_, snapshotContext: options?.snapshotContext, nativeSourceAdmitted: this.#active?.nativeSourceAdmitted === true, + isOperationAvailable: (operation) => this.#currentlyAvailable(operation), + isOperationAdvertised: options?.isOperationAdvertised, unboundOperationError: (operation, route) => this.#providerRouter.unboundOperationError(operation, route), lookupSnapshot: (target, profile, operation, parameters) => @@ -1705,6 +1710,20 @@ export class BinarySession return execution; } + /** Whether the active route can run an operation now, as status reports it. */ + #currentlyAvailable(operation: string): boolean { + const active = this.#active; + const descriptor = active?.route.capabilities.get(operation); + return ( + descriptor !== undefined && + currentRouteCapability( + descriptor, + active?.target, + this.#runtimeAvailability.entries, + ).available + ); + } + #clearRuntimeAvailability(): void { if (this.#runtimeAvailability.clear()) this.#emitAvailabilityChanged(); } diff --git a/src/application/binary/BinarySessionExecution.ts b/src/application/binary/BinarySessionExecution.ts index b4d346d2fd..97fc8d83b2 100644 --- a/src/application/binary/BinarySessionExecution.ts +++ b/src/application/binary/BinarySessionExecution.ts @@ -17,6 +17,7 @@ import type { CapabilityDescriptor, ExecutionOptions, } from "../AnalysisProvider.js"; +import { offeredOperationAlternatives } from "../OperationAlternatives.js"; import { isSnapshotCacheable, requestsFreshIndependentDecompile, @@ -45,6 +46,11 @@ interface PrepareSessionExecutionInput { readonly parameters: Readonly>; readonly snapshotContext?: ExecutionOptions["snapshotContext"]; readonly nativeSourceAdmitted: boolean; + /** Current availability as binary_session reports it, not the declaration. */ + readonly isOperationAvailable: (operation: AnalysisOperation) => boolean; + readonly isOperationAdvertised: + | ((operation: AnalysisOperation) => boolean) + | undefined; readonly unboundOperationError: ( operation: AnalysisOperation, route: SessionProviderRoute, @@ -79,6 +85,8 @@ export const prepareSessionExecution = ( operation, parameters, nativeSourceAdmitted, + isOperationAvailable, + isOperationAdvertised, unboundOperationError, lookupSnapshot, } = input; @@ -97,6 +105,15 @@ export const prepareSessionExecution = ( capability === undefined ? undeclaredOperationGuidance(operation, entryCommentAvailable) : undefined; + const offered = + capability === undefined + ? offeredOperationAlternatives( + operation, + (alternative) => + isOperationAvailable(alternative) && + (isOperationAdvertised?.(alternative) ?? true), + ) + : undefined; return err( new AnalysisCapabilityUnavailableError( active.route.binding?.identity.id ?? active.route.identity.id, @@ -114,6 +131,12 @@ export const prepareSessionExecution = ( : { userMessage: `The selected provider does not declare ${operation}.`, fallbackRemediationAction: undeclaredGuidance, + ...(offered === undefined + ? {} + : { + alternatives: offered.operations, + remediationAction: offered.remediation, + }), }, ), ); diff --git a/src/application/binary/BinarySessionRefusalAlternatives.test.ts b/src/application/binary/BinarySessionRefusalAlternatives.test.ts new file mode 100644 index 0000000000..8f0ca826ac --- /dev/null +++ b/src/application/binary/BinarySessionRefusalAlternatives.test.ts @@ -0,0 +1,200 @@ +import { describe, expect, it, onTestFinished } from "vitest"; + +import { observed } from "../../../tests/fixtures/analysisExecution.js"; +import { + createBinarySessionTargets, + createTestBinarySession, +} from "../../../tests/fixtures/binarySession.js"; +import { createAnalysisProfile } from "../../domain/analysisProfile.js"; +import { projectAnalysisError } from "../../domain/analysisErrorProjection.js"; +import { ok } from "../../domain/result.js"; +import type { + AnalysisOperation, + AnalysisProvider, + CapabilityDescriptor, + ExecutionOptions, +} from "../AnalysisProvider.js"; +import { buildCapabilityInventory } from "../CapabilityInventory.js"; +import { offeredOperationAlternatives } from "../OperationAlternatives.js"; + +const IDENTITY = { + id: "fixture", + name: "Fixture analysis provider", + version: "1", +} as const; +const GENERIC = + "This analysis is unavailable for the current target. Choose another analysis or target."; + +/** The owning formatter's remediation for exactly these offered tools. */ +const remediationFor = (operation: string, offered: readonly string[]) => + offeredOperationAlternatives(operation, (alternative) => + offered.includes(alternative), + )?.remediation; + +const capability = ( + operation: Exclude, + available = true, +): CapabilityDescriptor => ({ + provider: IDENTITY, + operation, + ...(available + ? ({ available: true, reason: null } as const) + : ({ + available: false, + reason: `${operation} needs a loaded listing`, + } as const)), + cachePolicy: "live", + effects: { + mutatesArtifact: false, + launchesProcess: false, + mayShowUi: false, + mayAccessNetwork: false, + mayWriteFilesystem: false, + changesPermissions: false, + requiresRoot: false, + }, + limitations: [], +}); + +/** A deep provider whose declared operations alone decide the offers. */ +const openSession = async (capabilities: readonly CapabilityDescriptor[]) => { + const provider: AnalysisProvider = { + identity: () => IDENTITY, + resolveAnalysisProfile: () => + Promise.resolve( + ok({ profile: createAnalysisProfile(IDENTITY, { fixture: true }) }), + ), + capabilities: () => capabilities, + createClient: () => ({ + execute: (operation) => Promise.resolve(observed(operation)), + close: () => Promise.resolve(ok(null)), + }), + }; + const session = createTestBinarySession(provider); + onTestFinished(async () => { + expect(await session.close()).toEqual({ ok: true, value: null }); + }); + const [target] = await createBinarySessionTargets(); + expect((await session.open(target)).ok).toBe(true); + return session; +}; + +const refusal = async ( + session: Awaited>, + operation: "next_address" | "prev_address", + options?: ExecutionOptions, +) => { + const result = await session.execute(operation, {}, options); + if (result.ok) throw new Error(`${operation} unexpectedly succeeded`); + return projectAnalysisError(result.error); +}; + +const offeredInDiscovery = async ( + session: Awaited>, + isToolAdvertised?: (name: string) => boolean, +) => + buildCapabilityInventory( + await session.status(), + { processCaptureEnabled: false }, + isToolAdvertised, + ) + .filter(({ name }) => name === "next_address" || name === "prev_address") + .map((tool) => (tool.available ? undefined : tool.alternatives)); + +describe("undeclared navigation refusals", () => { + it("describe only offered tools, what none establishes and the provider choice", () => { + const offered = offeredOperationAlternatives( + "prev_address", + (alternative) => alternative === "procedure_assembly", + ); + expect(offered?.operations).toEqual(["procedure_assembly"]); + expect(offered?.remediation).toContain("procedure_assembly ("); + expect(offered?.remediation).not.toMatch( + /inspect_native_instruction|read_function_instructions/u, + ); + expect(offered?.remediation).toContain("executed control flow"); + expect(offered?.remediation).toContain("prev_address itself"); + expect( + offeredOperationAlternatives("list_procedures", () => true), + ).toBeUndefined(); + }); + + it("offer only alternatives the provider makes available", async () => { + const session = await openSession([ + capability("inspect_native_instruction", false), + capability("read_function_instructions"), + capability("procedure_assembly"), + ]); + for (const operation of ["next_address", "prev_address"] as const) + expect(await refusal(session, operation)).toMatchObject({ + code: "capability_unavailable", + remediation: { + action: remediationFor(operation, [ + "read_function_instructions", + "procedure_assembly", + ]), + }, + details: { + provider_id: "fixture", + operation, + alternatives: ["read_function_instructions", "procedure_assembly"], + }, + }); + expect(await offeredInDiscovery(session)).toEqual([ + ["read_function_instructions", "procedure_assembly"], + ["read_function_instructions", "procedure_assembly"], + ]); + }); + + it("offer only alternatives the caller advertises", async () => { + const session = await openSession([ + capability("read_function_instructions"), + capability("procedure_assembly"), + ]); + const withoutListing = (operation: string) => + operation !== "read_function_instructions"; + const narrowed = await refusal(session, "next_address", { + isOperationAdvertised: withoutListing, + }); + expect(narrowed.details?.alternatives).toEqual(["procedure_assembly"]); + expect(narrowed.remediation.action).toBe( + remediationFor("next_address", ["procedure_assembly"]), + ); + expect(await offeredInDiscovery(session, withoutListing)).toEqual([ + ["procedure_assembly"], + ["procedure_assembly"], + ]); + + const hidden = (operation: string) => + operation !== "read_function_instructions" && + operation !== "procedure_assembly"; + const generic = await refusal(session, "prev_address", { + isOperationAdvertised: hidden, + }); + expect(generic.remediation.action).toEqual( + expect.stringContaining("binary_session"), + ); + expect(generic.details).not.toHaveProperty("alternatives"); + expect(await offeredInDiscovery(session, hidden)).toEqual([ + undefined, + undefined, + ]); + }); + + it("keep a declared operation's own unavailability reason", async () => { + const session = await openSession([ + capability("next_address", false), + capability("read_function_instructions"), + ]); + const declared = await refusal(session, "next_address"); + expect(declared).toMatchObject({ + code: "capability_unavailable", + remediation: { action: GENERIC }, + details: { reason: "next_address needs a loaded listing" }, + }); + expect(declared.details).not.toHaveProperty("alternatives"); + const [next, previous] = await offeredInDiscovery(session); + expect(next).toBeUndefined(); + expect(previous).toEqual(["read_function_instructions"]); + }); +}); diff --git a/src/application/binary/BinarySessionStatus.ts b/src/application/binary/BinarySessionStatus.ts index afbb9b396f..6abb6561ba 100644 --- a/src/application/binary/BinarySessionStatus.ts +++ b/src/application/binary/BinarySessionStatus.ts @@ -51,6 +51,34 @@ interface BinarySessionStatusInput { readonly refreshCandidates?: boolean; } +/** + * One route capability as the session currently reports it: target + * applicability and observed runtime unavailability override the declaration. + */ +export const currentRouteCapability = ( + descriptor: CapabilityDescriptor, + target: BinaryTarget | undefined, + runtimeUnavailability: ReadonlyMap, +) => { + const targetRefusal = + target === undefined + ? undefined + : descriptor.targetApplicability === undefined + ? artifactTargetRefusal(descriptor.operation, target) + : targetApplicabilityRefusal(descriptor.targetApplicability, target); + if (targetRefusal !== undefined && descriptor.available) + return { + ...descriptor, + available: false as const, + availabilityCode: targetRefusal.code, + reason: targetRefusal.reason, + }; + const unavailable = runtimeUnavailability.get(descriptor.operation); + return unavailable === undefined + ? descriptor + : runtimeUnavailable(descriptor, unavailable.reason); +}; + /** Project internal provider routing state into the caller-visible session status. */ export const binarySessionStatus = async ({ investigation, @@ -79,28 +107,9 @@ export const binarySessionStatus = async ({ .sort((left, right) => compareUnicodeCodePoints(left.operation, right.operation), ) - .map((descriptor) => { - const targetRefusal = - target === undefined - ? undefined - : descriptor.targetApplicability === undefined - ? artifactTargetRefusal(descriptor.operation, target) - : targetApplicabilityRefusal( - descriptor.targetApplicability, - target, - ); - if (targetRefusal !== undefined && descriptor.available) - return { - ...descriptor, - available: false as const, - availabilityCode: targetRefusal.code, - reason: targetRefusal.reason, - }; - const unavailable = runtimeUnavailability.get(descriptor.operation); - return unavailable === undefined - ? descriptor - : runtimeUnavailable(descriptor, unavailable.reason); - }); + .map((descriptor) => + currentRouteCapability(descriptor, target, runtimeUnavailability), + ); const capabilities = providerCapabilitySets(routeCapabilities); const analysisProviderBinding = bundleResourceRoot !== undefined diff --git a/src/contracts/toolOutputSchemaPrimitives.ts b/src/contracts/toolOutputSchemaPrimitives.ts index 069dfffc3f..457fa3b91e 100644 --- a/src/contracts/toolOutputSchemaPrimitives.ts +++ b/src/contracts/toolOutputSchemaPrimitives.ts @@ -467,6 +467,12 @@ const toolAvailabilityFacts = { }), }; +/** + * Advertised operations the current provider offers for part of an + * unavailable operation's question. They do not replace that operation. + */ +const toolAvailabilityAlternatives = z.array(z.string().min(1)).min(1); + export const toolUnavailabilityReason = z.enum([ "client_capability_missing", "target_required", @@ -488,6 +494,7 @@ export const toolAvailability = z.discriminatedUnion("available", [ available: z.literal(false), reason: toolUnavailabilityReason, remediation: z.string().nullable(), + alternatives: toolAvailabilityAlternatives.optional(), }), ]); export type ToolAvailability = z.output; @@ -535,6 +542,7 @@ const toolAvailabilityGroupOf = (facts: Facts) => available: z.literal(false), reason: toolUnavailabilityReason, remediation: z.string().nullable(), + alternatives: toolAvailabilityAlternatives.optional(), }), ]); diff --git a/src/domain/analysisErrorCore.ts b/src/domain/analysisErrorCore.ts index 09714bf3e9..a69243fc1b 100644 --- a/src/domain/analysisErrorCore.ts +++ b/src/domain/analysisErrorCore.ts @@ -254,6 +254,11 @@ export class AnalysisCapabilityUnavailableError extends AnalysisError { readonly siblingReasons: Readonly> | undefined; /** Incomplete cleanup must settle before the operation can be retried. */ readonly retryable: boolean; + /** + * Operations the caller can run now that observe part of what this one + * would answer; the remediation states what they do not establish. + */ + readonly alternatives: readonly string[]; constructor( readonly providerId: string, @@ -266,6 +271,7 @@ export class AnalysisCapabilityUnavailableError extends AnalysisError { readonly siblingOperations?: readonly string[]; readonly siblingReasons?: Readonly>; readonly retryable?: boolean; + readonly alternatives?: readonly string[]; }, ) { super( @@ -278,6 +284,7 @@ export class AnalysisCapabilityUnavailableError extends AnalysisError { this.siblingOperations = options?.siblingOperations; this.siblingReasons = options?.siblingReasons; this.retryable = options?.retryable === true && !this.cleanupIncomplete; + this.alternatives = Object.freeze([...(options?.alternatives ?? [])]); } } diff --git a/src/domain/analysisErrorProjection.ts b/src/domain/analysisErrorProjection.ts index c7244177c5..02c07cabd5 100644 --- a/src/domain/analysisErrorProjection.ts +++ b/src/domain/analysisErrorProjection.ts @@ -867,6 +867,9 @@ const providerErrorDetails = ( provider_id: error.providerId, operation: error.operation, reason: error.reason, + ...(error.alternatives.length === 0 + ? {} + : { alternatives: [...error.alternatives] }), }; if (error instanceof ProviderSelectionError) return { diff --git a/src/server/registerEvidenceTools.ts b/src/server/registerEvidenceTools.ts index 493aa47b53..b77b1285ee 100644 --- a/src/server/registerEvidenceTools.ts +++ b/src/server/registerEvidenceTools.ts @@ -88,6 +88,8 @@ export const registerEvidenceTools = ( analysis.execute(contract.name, executionParameters, { signal: context.mcpReq.signal, progress, + isOperationAdvertised: (operation) => + server.advertisesTool(operation), }), ); await reportOperationEnd(progress, contract.name, execution.ok); diff --git a/src/server/registerSessionStatusTool.ts b/src/server/registerSessionStatusTool.ts index 5839e1819a..c71626d556 100644 --- a/src/server/registerSessionStatusTool.ts +++ b/src/server/registerSessionStatusTool.ts @@ -127,27 +127,31 @@ export const registerSessionStatusTool = ( return server.delivery.toCallToolResult(err(cause), contract); } const statusObject = jsonObjectSchema.parse(status); - // Availability must be derived from the complete provider facts: an + // Availability is derived from the complete provider facts: an // advertised composed tool still depends on direct operations the - // registration hides. Narrow the public report only after this. - const toolAvailability = buildCapabilityInventory(status, { - ...availabilityPolicy(), - ...(availabilityResults.android === undefined - ? {} - : { androidAnalysisAvailability: availabilityResults.android }), - ...(availabilityResults.adb === undefined - ? {} - : { adbAnalysisAvailability: availabilityResults.adb }), - ...(availabilityResults.apktool === undefined - ? {} - : { apktoolAnalysisAvailability: availabilityResults.apktool }), - ...(availabilityResults.jeb === undefined - ? {} - : { jebAnalysisAvailability: availabilityResults.jeb }), - ...(availabilityResults.evmLimiter === undefined - ? {} - : { evmLimiterAvailability: availabilityResults.evmLimiter }), - }).filter(({ name }) => server.advertisesTool(name)); + // registration hides. Advertisement narrows only the public report. + const toolAvailability = buildCapabilityInventory( + status, + { + ...availabilityPolicy(), + ...(availabilityResults.android === undefined + ? {} + : { androidAnalysisAvailability: availabilityResults.android }), + ...(availabilityResults.adb === undefined + ? {} + : { adbAnalysisAvailability: availabilityResults.adb }), + ...(availabilityResults.apktool === undefined + ? {} + : { apktoolAnalysisAvailability: availabilityResults.apktool }), + ...(availabilityResults.jeb === undefined + ? {} + : { jebAnalysisAvailability: availabilityResults.jeb }), + ...(availabilityResults.evmLimiter === undefined + ? {} + : { evmLimiterAvailability: availabilityResults.evmLimiter }), + }, + (name) => server.advertisesTool(name), + ); const serverIdentity = createServerIdentity({ startedAt, commandPath: CURRENT_ENTRYPOINT_PATH, diff --git a/tests/boundary/mcp/ghidraMcpHarness.ts b/tests/boundary/mcp/ghidraMcpHarness.ts index 36fe94a0d9..a2f6f90eed 100644 --- a/tests/boundary/mcp/ghidraMcpHarness.ts +++ b/tests/boundary/mcp/ghidraMcpHarness.ts @@ -36,7 +36,7 @@ export const connectGhidraMcp = async ( readonly attestDosTargetSnapshot?: ReturnType["attestDosTargetSnapshot"]; readonly close?: ReturnType["close"]; readonly delivery?: ToolResultDelivery; - readonly environment?: Readonly>; + readonly environment?: Readonly; readonly schemaValidator?: ReturnType; } = {}, ) => { diff --git a/tests/boundary/mcp/navigationAlternativesMcp.test.ts b/tests/boundary/mcp/navigationAlternativesMcp.test.ts new file mode 100644 index 0000000000..1cdce4417f --- /dev/null +++ b/tests/boundary/mcp/navigationAlternativesMcp.test.ts @@ -0,0 +1,247 @@ +import { describe, expect, it } from "vitest"; + +import { offeredOperationAlternatives } from "../../../src/application/OperationAlternatives.js"; +import { toolContract } from "../../../src/contracts/toolContracts.js"; +import { expandToolAvailability } from "../../../src/contracts/toolOutputSchemaPrimitives.js"; +import { parseEvidence } from "../../../src/domain/evidence.js"; +import { err, ok } from "../../../src/domain/result.js"; +import { GhidraSessionError } from "../../../src/ghidra/GhidraSessionError.js"; +import { silentLogger } from "../../../src/logger.js"; +import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js"; +import { + createBinarySessionTargets, + createCacheProvider, + createTestBinarySession, +} from "../../fixtures/binarySession.js"; +import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; +import { connectGhidraMcp, ghidraFixtureResult } from "./ghidraMcpHarness.js"; + +type Client = Awaited>["mcp"]; + +const NAVIGATION = ["next_address", "prev_address"] as const; +const GHIDRA_ALTERNATIVES = [ + "inspect_native_instruction", + "read_function_instructions", + "procedure_assembly", +]; +/** The owning formatter's remediation for exactly these offered tools. */ +const remediationFor = (operation: string, offered: readonly string[]) => + offeredOperationAlternatives(operation, (alternative) => + offered.includes(alternative), + )?.remediation; + +const navigationRefusal = async ( + client: Client, + name: (typeof NAVIGATION)[number], +) => + parseMcpToolError( + await client.callTool({ name, arguments: { address: "0x401000" } }), + ).error; + +const navigationAvailability = async ( + client: Client, + detail: "summary" | "complete", +) => { + const reply = await client.callTool({ + name: "binary_session", + arguments: { detail }, + }); + const status = toolContract("binary_session").outputSchema.parse( + reply.structuredContent, + ).result; + const groups = status.tool_availability.groups.filter((group) => + NAVIGATION.some((name) => group.names.includes(name)), + ); + return { + groups, + tools: expandToolAvailability(status.tool_availability), + }; +}; + +describe("address navigation refusals", () => { + it.each([ + // Explicitly unset so a developer's scoped catalog cannot leak in. + { + scope: "every family", + environment: { REA_MCP_TOOL_FAMILIES: undefined }, + }, + { + scope: "session and direct families", + environment: { REA_MCP_TOOL_FAMILIES: "session,direct" }, + }, + ])( + "name Ghidra's instruction observations and their scope ($scope)", + async ({ environment }) => { + const harness = await connectGhidraMcp( + "navigation-alternatives", + undefined, + { environment }, + ); + try { + for (const name of NAVIGATION) + expect(await navigationRefusal(harness.mcp, name)).toEqual({ + code: "capability_unavailable", + category: "unsupported_provider", + message: `The selected provider does not declare ${name}.`, + retryable: false, + remediation: { + action: remediationFor(name, GHIDRA_ALTERNATIVES), + }, + details: { + provider_id: "ghidra", + operation: name, + reason: "operation is not declared by this provider", + alternatives: GHIDRA_ALTERNATIVES, + }, + }); + + // Follow the suggested next step on the same connection. + const listing = parseEvidence( + ( + await harness.mcp.callTool({ + name: "read_function_instructions", + arguments: { procedure: "0x401000" }, + }) + ).structuredContent, + ); + expect(listing.provider.id).toBe("ghidra"); + expect(harness.calls).toContain("read_function_instructions"); + + // Discovery names the same relation once for both navigation tools. + for (const detail of ["summary", "complete"] as const) { + const { groups, tools } = await navigationAvailability( + harness.mcp, + detail, + ); + expect(groups).toEqual([ + expect.objectContaining({ + names: [...NAVIGATION], + available: false, + reason: "provider_missing", + remediation: + "Install or configure a provider that declares this operation.", + alternatives: GHIDRA_ALTERNATIVES, + }), + ]); + for (const alternative of GHIDRA_ALTERNATIVES) + expect(tools).toContainEqual( + expect.objectContaining({ name: alternative, available: true }), + ); + } + } finally { + await harness.close(); + } + }, + 30_000, + ); +}); + +describe("address navigation refusal alternatives", () => { + it("stop offering tools a provider failure made unavailable", async () => { + let failAssembly = true; + const harness = await connectGhidraMcp( + "navigation-after-provider-failure", + (operation, input) => { + if (operation === "procedure_assembly" && failAssembly) { + failAssembly = false; + return Promise.resolve( + err(new GhidraSessionError("protocol", "Malformed bridge reply")), + ); + } + return Promise.resolve(ok(ghidraFixtureResult(operation, input))); + }, + { environment: { REA_MCP_TOOL_FAMILIES: undefined } }, + ); + const offeredInDiscovery = async () => + (await navigationAvailability(harness.mcp, "summary")).tools + .filter(({ name }) => name === "next_address") + .map((tool) => + "alternatives" in tool ? tool.alternatives : undefined, + ); + try { + const failed = await harness.mcp.callTool({ + name: "procedure_assembly", + arguments: { procedure: "0x401000" }, + }); + expect(parseMcpToolError(failed).error.code).toBe("execution_failure"); + // The failure marks Ghidra's operations unavailable (assembly observed, + // the others inferred), so neither discovery nor the refusal offers one. + const generic = await navigationRefusal(harness.mcp, "next_address"); + expect(generic.remediation.action).toEqual( + expect.stringContaining("binary_session"), + ); + expect(generic.details).not.toHaveProperty("alternatives"); + expect(await offeredInDiscovery()).toEqual([undefined]); + + // A later Ghidra success clears the inferred entries, while the + // observed assembly failure stays until assembly itself succeeds. + const listing = await harness.mcp.callTool({ + name: "read_function_instructions", + arguments: { procedure: "0x401000" }, + }); + expect(listing.isError).not.toBe(true); + const recovered = [ + "inspect_native_instruction", + "read_function_instructions", + ]; + const restored = await navigationRefusal(harness.mcp, "next_address"); + expect(restored.details?.alternatives).toEqual(recovered); + expect(restored.remediation.action).toBe( + remediationFor("next_address", recovered), + ); + expect(await offeredInDiscovery()).toEqual([recovered]); + + const assembly = await harness.mcp.callTool({ + name: "procedure_assembly", + arguments: { procedure: "0x401000" }, + }); + expect(assembly.isError).not.toBe(true); + expect( + (await navigationRefusal(harness.mcp, "next_address")).details + ?.alternatives, + ).toEqual(GHIDRA_ALTERNATIVES); + expect(await offeredInDiscovery()).toEqual([GHIDRA_ALTERNATIVES]); + } finally { + await harness.close(); + } + }, 30_000); + + it("keep generic advice when the provider offers no declared alternative", async () => { + const [target] = await createBinarySessionTargets(); + const { client } = await createApplicationMcpHarness({ + session: createTestBinarySession(createCacheProvider([])), + clientIdentity: { name: "navigation-without-alternatives", version: "1" }, + serverOptions: { environment: {}, logger: silentLogger }, + }); + const opened = await client.callTool({ + name: "open_binary", + arguments: { path: target }, + }); + expect(opened.isError).not.toBe(true); + for (const name of NAVIGATION) { + const { error } = parseMcpToolError( + await client.callTool({ name, arguments: { address: "0x1000" } }), + ); + expect(error).toEqual({ + code: "capability_unavailable", + category: "unsupported_provider", + message: `The selected provider does not declare ${name}.`, + retryable: false, + remediation: { action: expect.stringContaining("binary_session") }, + details: { + provider_id: "fixture", + operation: name, + reason: "operation is not declared by this provider", + }, + }); + } + const { groups } = await navigationAvailability(client, "summary"); + expect(groups).toHaveLength(1); + expect(groups[0]).toMatchObject({ + available: false, + reason: "provider_missing", + }); + expect(groups[0]).not.toHaveProperty("alternatives"); + expect(groups[0]?.names).toEqual(expect.arrayContaining([...NAVIGATION])); + }); +}); diff --git a/tests/boundary/providers/kuna/kunaNavigationAlternativesMcp.test.ts b/tests/boundary/providers/kuna/kunaNavigationAlternativesMcp.test.ts new file mode 100644 index 0000000000..b06c944f91 --- /dev/null +++ b/tests/boundary/providers/kuna/kunaNavigationAlternativesMcp.test.ts @@ -0,0 +1,113 @@ +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +import { expect } from "vitest"; + +import { AnalysisProviderRegistry } from "../../../../src/application/binary/AnalysisProviderRegistry.js"; +import { offeredOperationAlternatives } from "../../../../src/application/OperationAlternatives.js"; +import { composeBinarySession } from "../../../../src/application/binary/BinarySessionComposition.js"; +import { toolContract } from "../../../../src/contracts/toolContracts.js"; +import { expandToolAvailability } from "../../../../src/contracts/toolOutputSchemaPrimitives.js"; +import { parseEvidence } from "../../../../src/domain/evidence.js"; +import { KunaProvider } from "../../../../src/kuna/KunaProvider.js"; +import { elfNoteFixture } from "../../../../src/native/elf/ElfNotes.fixture.js"; +import { createServer } from "../../../../src/server/createServer.js"; +import { parseMcpToolError } from "../../../fixtures/mcpToolError.js"; +import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js"; +import { mcpTest } from "../../../support/mcp/mcpFixture.js"; +import { writeFakeKuna } from "./fakeKuna.js"; +import { FUNCTIONS } from "./kunaSessionFixture.js"; + +const test = mcpTest.skipIf(process.platform === "win32"); + +test("names only Kuna's assembly text for navigation refusals in a scoped catalog", async ({ + mcp, +}) => { + const root = await createTestTempDirectory("rea-kuna-navigation-mcp-"); + const kuna = await writeFakeKuna(root, { functions: FUNCTIONS }); + const target = join(root, "program"); + await writeFile(target, elfNoteFixture({ bits: 64, type: 2 })); + const session = composeBinarySession( + new AnalysisProviderRegistry( + [ + new KunaProvider( + { REA_KUNA_COMMAND: kuna, REA_KUNA_CACHE_DIR: join(root, "cache") }, + { platform: process.platform }, + ), + ], + "kuna", + ), + ); + try { + const client = await mcp.connect( + createServer( + { kind: "session", session }, + { environment: { REA_MCP_TOOL_FAMILIES: "session,direct" } }, + ), + ); + const opened = await client.callTool({ + name: "open_binary", + arguments: { path: target }, + }); + expect(opened.isError).not.toBe(true); + + for (const name of ["next_address", "prev_address"]) { + const { error } = parseMcpToolError( + await client.callTool({ name, arguments: { address: "0x1000" } }), + ); + expect(error).toMatchObject({ + code: "capability_unavailable", + category: "unsupported_provider", + retryable: false, + remediation: { + action: offeredOperationAlternatives( + name, + (alternative) => alternative === "procedure_assembly", + )?.remediation, + }, + details: { + provider_id: "kuna", + operation: name, + alternatives: ["procedure_assembly"], + }, + }); + } + + const status = toolContract("binary_session").outputSchema.parse( + ( + await client.callTool({ + name: "binary_session", + arguments: { detail: "complete" }, + }) + ).structuredContent, + ).result; + const tools = expandToolAvailability(status.tool_availability); + for (const name of ["next_address", "prev_address"]) + expect(tools).toContainEqual( + expect.objectContaining({ + name, + reason: "provider_missing", + alternatives: ["procedure_assembly"], + }), + ); + // The structured reads stay unavailable and are not offered. + for (const name of [ + "inspect_native_instruction", + "read_function_instructions", + ]) + expect(tools).toContainEqual( + expect.objectContaining({ name, available: false }), + ); + + // The offered follow-up works on the same connection. + const assembly = await client.callTool({ + name: "procedure_assembly", + arguments: { procedure: "main" }, + }); + expect(assembly.isError).not.toBe(true); + expect(parseEvidence(assembly.structuredContent).provider.id).toBe("kuna"); + } finally { + await mcp.close(); + expect(await session.close()).toEqual({ ok: true, value: null }); + } +}, 60_000);