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(mcp): keep prompt completion within ready provider sessions
morluto07b36c148946
diff --git a/src/application/AnalysisProvider.ts b/src/application/AnalysisProvider.tsindex 87a717795..cc17cac82 100644--- a/src/application/AnalysisProvider.ts+++ b/src/application/AnalysisProvider.ts@@ -123,6 +123,12 @@ export interface ProviderRequestActivitySnapshot {/** Provider session bound to exactly one parsed artifact. */export interface AnalysisClient extends AnalysisOperationPort {+ /** Execute only if this operation can run without loading or starting a provider. */+ executeIfReady?(+ operation: AnalysisOperation,+ parameters: Readonly<Record<string, JsonValue>>,+ options?: ExecutionOptions,+ ): Promise<Result<AnalysisExecution, AnalysisError> | undefined>;/** Retained token-verified process snapshots for dynamic providers this client started. */runtimeLineageSnapshots?(): readonly ProviderRuntimeLineageSnapshot[];/** Current provider work that may outlive a timed-out or cancelled caller. */diff --git a/src/application/binary/BinarySession.ts b/src/application/binary/BinarySession.tsindex 9eff0e0b8..f7b2d3529 100644--- a/src/application/binary/BinarySession.ts+++ b/src/application/binary/BinarySession.ts@@ -81,7 +81,9 @@ export class BinarySession| undefined;#transition: Promise<void> = Promise.resolve();#transitionGeneration = 0;+ #transitionPending = 0;readonly #calls = new Map<Promise<unknown>, number>();+ readonly #promptCompletionControllers = new Set<AbortController>();readonly #providerRouter: SessionProviderRouter;readonly #runtimeUnavailability = new Map<string,@@ -532,6 +534,38 @@ export class BinarySessionreturn call.finally(() => this.#calls.delete(call));}+ /** Run a prompt lookup only against an already connected provider child. */+ executeIfProviderReady(+ name: Parameters<AnalysisOperationPort["execute"]>[0],+ arguments_: Readonly<Record<string, JsonValue>>,+ options?: Pick<ExecutionOptions, "signal" | "selectorOrigin">,+ ): Promise<Result<AnalysisExecution, AnalysisError> | undefined> {+ const active = this.#active;+ if (+ this.#transitionPending > 0 ||+ active === undefined ||+ active.client.executeIfReady === undefined+ )+ return Promise.resolve(undefined);++ const controller = new AbortController();+ this.#promptCompletionControllers.add(controller);+ const signal =+ options?.signal === undefined+ ? controller.signal+ : AbortSignal.any([controller.signal, options.signal]);+ const generation = this.#transitionGeneration;+ const call = active.client.executeIfReady(name, arguments_, {+ ...options,+ signal,+ });+ this.#calls.set(call, generation);+ return call.finally(() => {+ this.#calls.delete(call);+ this.#promptCompletionControllers.delete(controller);+ });+ }+/** Admit one composed request until its result and session bookkeeping settle. */withAdmittedAnalysis<Value>(operationName: string,@@ -728,6 +762,9 @@ export class BinarySession#serialize<T>(operation: (admittedThrough: number) => Promise<T>,): Promise<T> {+ for (const controller of this.#promptCompletionControllers)+ controller.abort();+ this.#transitionPending += 1;// Later calls wait for this transition and must not be included in its drain.const admittedThrough = this.#transitionGeneration++;const result = this.#transition.then(@@ -738,6 +775,14 @@ export class BinarySession() => undefined,() => undefined,);+ void result.then(+ () => {+ this.#transitionPending -= 1;+ },+ () => {+ this.#transitionPending -= 1;+ },+ );return result;}diff --git a/src/application/binary/BinarySessionPort.ts b/src/application/binary/BinarySessionPort.tsindex ee666f665..749e98b2f 100644--- a/src/application/binary/BinarySessionPort.ts+++ b/src/application/binary/BinarySessionPort.ts@@ -14,6 +14,7 @@ import type { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";import type { WorkflowSnapshotRecordInput } from "./BinarySessionRecords.js";import type {+ AnalysisExecution,AnalysisOperation,AnalysisOperationPort,ExecutionOptions,@@ -35,6 +36,12 @@ export interface SavedAnalysisSnapshot {/** Target lifecycle used by CLI and MCP without exposing a concrete provider. */export interface BinarySessionPortextends AnalysisOperationPort, InvestigationRecordPort {+ /** Execute only against a positively ready, already-created provider client. */+ executeIfProviderReady(+ operation: AnalysisOperation,+ parameters: Readonly<Record<string, JsonValue>>,+ options?: Pick<ExecutionOptions, "signal" | "selectorOrigin">,+ ): Promise<Result<AnalysisExecution, AnalysisError> | undefined>;/** Hold the active target binding through a complete composed operation. */withAdmittedAnalysis<Value>(operationName: string,diff --git a/src/application/binary/CompositeProvider.ts b/src/application/binary/CompositeProvider.tsindex b0a7e7c13..05184d279 100644--- a/src/application/binary/CompositeProvider.ts+++ b/src/application/binary/CompositeProvider.ts@@ -94,6 +94,15 @@ export class CompositeProvider implements AnalysisProvider {return outcomes.find((outcome) => !outcome.ok) ?? ok(null);};return {+ executeIfReady: (operation, parameters, options) => {+ const provider = this.#providerByOperation.get(operation);+ const client =+ provider === undefined ? undefined : clients.get(provider);+ return (+ client?.executeIfReady?.(operation, parameters, options) ??+ Promise.resolve(undefined)+ );+ },execute: (operation, parameters, options) => {if (operation === "health")return Promise.resolve(diff --git a/src/application/binary/LazyAnalysisProvider.ts b/src/application/binary/LazyAnalysisProvider.tsindex b9127e48b..a87e77445 100644--- a/src/application/binary/LazyAnalysisProvider.ts+++ b/src/application/binary/LazyAnalysisProvider.ts@@ -79,6 +79,14 @@ class LazyAnalysisClient implements AnalysisClient {#loading: Promise<AnalysisClient> | undefined;#closed = false;+ executeIfReady: NonNullable<AnalysisClient["executeIfReady"]> = (+ operation,+ parameters,+ options,+ ) =>+ this.#client?.executeIfReady?.(operation, parameters, options) ??+ Promise.resolve(undefined);+constructor(loadClient: () => Promise<AnalysisClient>, providerId: string) {this.#loadClient = loadClient;this.#providerId = providerId;diff --git a/src/ghidra/GhidraClient.ts b/src/ghidra/GhidraClient.tsindex 7731cf872..d1dee3f01 100644--- a/src/ghidra/GhidraClient.ts+++ b/src/ghidra/GhidraClient.ts@@ -115,6 +115,7 @@ export class GhidraClient {#lastDiagnostics: Readonly<Record<string, JsonValue>> = {};#startupController: AbortController | undefined;#startPromise: Promise<GhidraStartResult> | undefined;+ #ready = false;#closePromise: Promise<void> | undefined;readonly #failure = bindGhidraSessionFailure(() => this.#diagnostics(),@@ -216,7 +217,8 @@ export class GhidraClient {void started.then((result) => {signal?.removeEventListener("abort", onAbort);- if (!result.ok) reset();+ if (result.ok) this.#ready = true;+ else reset();},(cause: unknown) => {this.#logger.debug(@@ -293,6 +295,20 @@ export class GhidraClient {);}+ /** Dispatch against the connected bridge without invoking startup or retry. */+ callToolIfReady(+ operation: GhidraOperation,+ parameters: Readonly<Record<string, JsonValue>>,+ options: { readonly signal?: AbortSignal } = {},+ ): Promise<Result<JsonValue, GhidraSessionError> | undefined> {+ if (!this.isReady()) return Promise.resolve(undefined);+ return this.#requestQueue.run(+ operation,+ parameters,+ options.signal === undefined ? {} : { signal: options.signal },+ );+ }+/** Read the private immutable source for format parsers that require captured bytes. */readTargetSnapshot(maximumBytes?: number,@@ -416,6 +432,16 @@ export class GhidraClient {}}+ /** True only after the authenticated startup handshake has completed. */+ isReady(): boolean {+ return (+ this.#ready &&+ this.#socket !== undefined &&+ !this.#socket.destroyed &&+ this.#closePromise === undefined+ );+ }+#cleanupError(cause: unknown): AnalysisError {if (cause instanceof AnalysisError && cause.cleanupIncomplete) return cause;return new ProviderCleanupError(@@ -462,6 +488,7 @@ export class GhidraClient {}#requestClose(forceStop: boolean): Promise<void> {+ this.#ready = false;const starting = this.#startPromise;const controller = this.#startupController;controller?.abort();diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.tsindex d2b963e52..fc0297789 100644--- a/src/ghidra/GhidraProviderClient.ts+++ b/src/ghidra/GhidraProviderClient.ts@@ -108,6 +108,7 @@ export type GhidraProviderClientFactory = (Partial<Pick<GhidraClient,+ | "callToolIfReady"| "operationHealthSnapshot"| "runtimeLineage"| "readTargetSnapshot"@@ -667,6 +668,40 @@ export const createGhidraProviderClient = (input: {startupTimeoutMs: config.ghidraStartupTimeoutMs,}): undefined;+ const projectExecution = (+ operation: AnalysisOperation,+ normalized: JsonValue,+ rawResult: JsonValue,+ observationLimitations: readonly string[] = [],+ ) => {+ const relationshipCoverage = relationshipCoverageFor(operation);+ return createAnalysisExecution(normalized, committedProfile.provider, {+ rawResult,+ analysisProfile: committedProfile,+ ...(relationshipCoverage === undefined ? {} : { relationshipCoverage }),+ limitations: [+ ...limitationsFor(operation),+ ...observationLimitations,+ ...sessionLimitations(),+ ],+ });+ };+ const inventoryExecution = (+ operation: "list_documents" | "list_procedures",+ called: Result<JsonValue, GhidraSessionError>,+ ) => {+ if (!called.ok)+ return err(+ projectSessionError(+ operation,+ called.error,+ config.ghidraStartupTimeoutMs,+ ),+ );+ const parsed = parseGhidraInventoryResult(operation, called.value);+ if (!parsed.ok) return parsed;+ return ok(projectExecution(operation, parsed.value, called.value));+ };return {execute: async (operation, parameters, options) => {if (extensionFailure !== undefined) return err(extensionFailure);@@ -724,6 +759,8 @@ export const createGhidraProviderClient = (input: {? {}: { progress: options.progress }),});+ if (operation === "list_documents" || operation === "list_procedures")+ return inventoryExecution(operation, called);if (!called.ok)return err(projectSessionError(@@ -827,21 +864,29 @@ export const createGhidraProviderClient = (input: {if (!attested.ok) return attested;normalized = attested.value;}- const relationshipCoverage = relationshipCoverageFor(operation);return ok(- createAnalysisExecution(normalized, committedProfile.provider, {- rawResult: called.value,- analysisProfile: committedProfile,- ...(relationshipCoverage === undefined- ? {}- : { relationshipCoverage }),- limitations: [- ...limitationsFor(operation),- ...observationLimitations,- ...sessionLimitations(),- ],- }),+ projectExecution(+ operation,+ normalized,+ called.value,+ observationLimitations,+ ),+ );+ },+ executeIfReady: async (operation, parameters, options) => {+ if (operation !== "list_documents" && operation !== "list_procedures")+ return undefined;+ if (extensionFailure !== undefined) return err(extensionFailure);+ const input = parseGhidraInventoryInput(operation, parameters);+ if (!input.ok) return input;+ if (client.callToolIfReady === undefined) return undefined;+ const called = await client.callToolIfReady(+ operation,+ input.value,+ options?.signal === undefined ? {} : { signal: options.signal },);+ if (called === undefined) return undefined;+ return inventoryExecution(operation, called);},operationHealthSnapshot: () => client.operationHealthSnapshot?.(),runtimeLineageSnapshots: () => {diff --git a/src/hopper/HopperClient.ts b/src/hopper/HopperClient.tsindex 2e903c8d2..8196adcee 100644--- a/src/hopper/HopperClient.ts+++ b/src/hopper/HopperClient.ts@@ -121,6 +121,7 @@ export class HopperClient {#launcherFailureDiagnostic: HopperStartupFailureDiagnostic | undefined;#operationFailure: OperationFailureRecord | undefined;#startupController: AbortController | undefined;+ #ready = false;#startupFailureResult: AnalysisError | undefined;#runId: string | undefined;#startPromise: Promise<Result<HopperServerInfo, AnalysisError>> | undefined;@@ -257,6 +258,16 @@ export class HopperClient {};}+ /** True only after the authenticated health handshake has completed. */+ isReady(): boolean {+ return (+ this.#ready &&+ this.#socket !== undefined &&+ !this.#socket.destroyed &&+ this.#closePromise === undefined+ );+ }+/** Launch the bridge once and complete its authenticated health handshake. */start(signal?: AbortSignal,@@ -292,7 +303,7 @@ export class HopperClient {if (!result.ok) {this.#rememberStartupFailure(result.error);reset();- }+ } else this.#ready = true;},(cause: unknown) => {this.#logger.debug(@@ -466,7 +477,28 @@ export class HopperClient {): Promise<Result<JsonValue, AnalysisError>> {const started = await this.start(options.signal);if (!started.ok) return started;- const result = await this.#request(name, arguments_, options);+ return this.#normalizeToolResult(+ name,+ await this.#request(name, arguments_, options),+ );+ }++ /** Dispatch against the connected bridge without invoking startup or retry. */+ callToolIfReady(+ name: string,+ arguments_: Readonly<Record<string, JsonValue>> = {},+ options: { readonly signal?: AbortSignal } = {},+ ): Promise<Result<JsonValue, AnalysisError> | undefined> {+ if (!this.isReady()) return Promise.resolve(undefined);+ return this.#request(name, arguments_, options).then((result) =>+ this.#normalizeToolResult(name, result),+ );+ }++ #normalizeToolResult(+ name: string,+ result: Result<JsonValue, AnalysisError>,+ ): Result<JsonValue, AnalysisError> {return !result.ok &&result.error instanceof HopperRemoteError &&result.error.diagnosticType === "capability_unavailable"@@ -579,6 +611,7 @@ export class HopperClient {options: HopperClientCloseOptions = {},): Promise<Result<null, AnalysisError>> {this.#closing = true;+ this.#ready = false;try {return await cleanupHopperSession({socket: this.#socket,diff --git a/src/hopper/HopperProvider.ts b/src/hopper/HopperProvider.tsindex 0b7316a19..c52eefe28 100644--- a/src/hopper/HopperProvider.ts+++ b/src/hopper/HopperProvider.ts@@ -5,6 +5,7 @@ import { accessSync, constants, statSync } from "node:fs";import { createAnalysisExecution } from "../application/AnalysisProvider.js";import type {AnalysisClient,+ AnalysisOperation,AnalysisClientContext,AnalysisProfileResolutionOptions,AnalysisProviderCandidate,@@ -16,6 +17,7 @@ import type {import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";import type { AppConfig } from "../config/types.js";import type { BinaryTarget } from "../domain/binaryTargetTypes.js";+import type { JsonValue } from "../domain/jsonValue.js";import type { Logger } from "pino";import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";import { err, ok } from "../domain/result.js";@@ -251,6 +253,40 @@ export class HopperProvider implements AnalysisProviderCandidate {this.logger.info(diagnostic, "Hopper bridge reported a diagnostic"),});const regexSearch = new HopperRegexSearch(client);+ const projectExecution = (+ operation: AnalysisOperation,+ normalized: JsonValue,+ rawResult: JsonValue | null = null,+ ) =>+ createAnalysisExecution(normalized, executionProvider, {+ // Only the file-offset mapping differs from Hopper's reply.+ rawResult,+ ...(profile === undefined ? {} : { analysisProfile: profile }),+ ...(operation === "procedure_callers" ||+ operation === "procedure_callees"+ ? { relationshipCoverage: { status: "complete" as const } }+ : {}),+ limitations: [+ ...(preparedImage === undefined+ ? []+ : [+ "REA loaded a verified thin Mach-O slice from the original FAT64 source. Identity and file offsets refer to the original file. The owned temporary image and its Hopper document close together, including on MCP shutdown.",+ ]),+ ...(CAPABILITIES.find(+ (descriptor) => descriptor.operation === operation,+ )?.limitations ?? []),+ ...(operation === "read_bytes"+ ? [+ "Hopper byte reads stop at the containing segment's exclusive end; a readable prefix is returned with complete=false when the requested range crosses it.",+ ]+ : []),+ ...(operation === "procedure_references"+ ? [+ "Native CallReference classifications and unresolved targets are preserved. Detailed reference flags and coverage beyond reported CallReference objects remain unknown.",+ ]+ : []),+ ],+ });return {execute: async (operation, parameters, options) => {const result =@@ -265,40 +301,26 @@ export class HopperProvider implements AnalysisProviderCandidate {? await mapHopperFileOffset(target, result.value, options?.signal): result;return mapped.ok- ? {- ok: true,- value: createAnalysisExecution(mapped.value, executionProvider, {- // Only the file-offset mapping differs from Hopper's reply.- rawResult: mapped === result ? null : result.value,- ...(profile === undefined ? {} : { analysisProfile: profile }),- ...(operation === "procedure_callers" ||- operation === "procedure_callees"- ? { relationshipCoverage: { status: "complete" as const } }- : {}),- limitations: [- ...(preparedImage === undefined- ? []- : [- "REA loaded a verified thin Mach-O slice from the original FAT64 source. Identity and file offsets refer to the original file. The owned temporary image and its Hopper document close together, including on MCP shutdown.",- ]),- ...(CAPABILITIES.find(- (descriptor) => descriptor.operation === operation,- )?.limitations ?? []),- ...(operation === "read_bytes"- ? [- "Hopper byte reads stop at the containing segment's exclusive end; a readable prefix is returned with complete=false when the requested range crosses it.",- ]- : []),- ...(operation === "procedure_references"- ? [- "Native CallReference classifications and unresolved targets are preserved. Detailed reference flags and coverage beyond reported CallReference objects remain unknown.",- ]- : []),- ],- }),- }+ ? ok(+ projectExecution(+ operation,+ mapped.value,+ mapped === result ? null : result.value,+ ),+ ): mapped;},+ executeIfReady: async (operation, parameters, options) => {+ if (operation !== "list_documents" && operation !== "list_procedures")+ return undefined;+ const result = await client.callToolIfReady(+ operation,+ parameters,+ options?.signal === undefined ? {} : { signal: options.signal },+ );+ if (result === undefined || !result.ok) return result;+ return ok(projectExecution(operation, result.value));+ },runtimeLineageSnapshots: () => {const observation = client.runtimeLineage();return observation === nulldiff --git a/src/ida/IdaSessionClient.test.ts b/src/ida/IdaSessionClient.test.tsindex a7d7be083..e43f18cf7 100644--- a/src/ida/IdaSessionClient.test.ts+++ b/src/ida/IdaSessionClient.test.ts@@ -116,6 +116,86 @@ describe("headless IDA producer pagination", () => {});describe("attached IDA observation semantics", () => {+ it("returns cold and pending startup calls immediately, then cancels queued work before dispatch", async () => {+ const { producer, client } = await fixture("headless");+ await expect(client.executeIfReady("list_procedures", {})).resolves.toBe(+ undefined,+ );+ expect(producer.connects).toBe(0);++ let enterOpen: (() => void) | undefined;+ let finishOpen: (() => void) | undefined;+ const openEntered = new Promise<void>((resolve) => {+ enterOpen = resolve;+ });+ const openGate = new Promise<void>((resolve) => {+ finishOpen = resolve;+ });+ producer.beforeCall = async (name) => {+ if (name === "idb_open") {+ enterOpen?.();+ await openGate;+ }+ };+ const startup = client.execute("list_procedures", {});+ await openEntered;+ await expect(client.executeIfReady("list_strings", {})).resolves.toBe(+ undefined,+ );+ expect(+ producer.calls.filter(({ name }) => name === "idb_open"),+ ).toHaveLength(1);+ finishOpen?.();+ const started = await startup;+ if (!started.ok) throw started.error;+ const warm = await client.executeIfReady("list_procedures", {});+ if (warm === undefined) throw new Error("expected ready IDA dispatch");+ if (!warm.ok) throw warm.error;+ expect(warm.value.result).toEqual([+ expect.objectContaining({ address: "0x1000", value: "main" }),+ ]);++ let enterRead: (() => void) | undefined;+ let finishRead: (() => void) | undefined;+ const readEntered = new Promise<void>((resolve) => {+ enterRead = resolve;+ });+ const readGate = new Promise<void>((resolve) => {+ finishRead = resolve;+ });+ producer.beforeCall = async (name) => {+ if (name === "list_funcs") {+ enterRead?.();+ await readGate;+ }+ };+ const active = client.execute("list_procedures", {});+ await readEntered;+ const controller = new AbortController();+ const queued = client.executeIfReady(+ "list_strings",+ {},+ {+ signal: controller.signal,+ },+ );+ controller.abort();+ await expect(queued).resolves.toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCancelledError" },+ });+ finishRead?.();+ const activeResult = await active;+ if (!activeResult.ok) throw activeResult.error;+ expect(+ producer.calls.filter(({ name }) => name === "list_funcs"),+ ).toHaveLength(3);+ expect(producer.calls.some(({ name }) => name === "find_regex")).toBe(+ false,+ );+ await client.close();+ });+it("accepts a normalized spelling of the bound document path", async () => {const { target, producer, client } = await fixture();const equivalent =diff --git a/src/ida/IdaSessionClient.ts b/src/ida/IdaSessionClient.tsindex 0633d9f68..f2a624569 100644--- a/src/ida/IdaSessionClient.ts+++ b/src/ida/IdaSessionClient.ts@@ -1,4 +1,8 @@import { z } from "zod";+import {+ ABORTED,+ waitForAbortable,+} from "../application/binary/AbortablePromise.js";import {createAnalysisExecution,type AnalysisClient,@@ -141,10 +145,35 @@ export class IdaSessionClient implements AnalysisClient {return call;}+ async executeIfReady(+ operation: AnalysisOperation,+ parameters: Readonly<Record<string, JsonValue>>,+ options?: ExecutionOptions,+ ) {+ if (!this.#openCompleted || this.#closed || this.#closing)+ return Promise.resolve(undefined);+ const call = this.#tail.then(() => {+ if (!this.#openCompleted || this.#closed || this.#closing)+ return undefined;+ if (wasCancelled(options))+ return err(new AnalysisCancelledError(operation));+ return this.#execute(operation, parameters, options, true);+ });+ this.#tail = call.then(+ () => undefined,+ () => undefined,+ );+ const result = await waitForAbortable(call, options?.signal);+ return result === ABORTED+ ? err(new AnalysisCancelledError(operation))+ : result;+ }+async #execute(operation: AnalysisOperation,parameters: Readonly<Record<string, JsonValue>>,options?: ExecutionOptions,+ readyOnly = false,) {if (this.#closed || this.#closing)return err(@@ -202,7 +231,7 @@ export class IdaSessionClient implements AnalysisClient {parameters,};try {- await this.#start();+ if (!readyOnly) await this.#start();const before = await this.#observe(options);failureContext.metadataBefore = before;if (wasCancelled(options)) throw new AnalysisCancelledError(operation);diff --git a/src/server/EvidenceMcpServer.ts b/src/server/EvidenceMcpServer.tsindex d5f5e0598..dda6d17f3 100644--- a/src/server/EvidenceMcpServer.ts+++ b/src/server/EvidenceMcpServer.ts@@ -1,3 +1,5 @@+import { AsyncLocalStorage } from "node:async_hooks";+import {McpServer,isCallToolResult,@@ -34,6 +36,12 @@ export interface CompactInputSchemaPresentation {readonly budgetBytes: number;}+const currentRequestSignal = new AsyncLocalStorage<AbortSignal>();++/** Signal for the completion request currently being dispatched by the SDK. */+export const currentMcpRequestSignal = (): AbortSignal | undefined =>+ currentRequestSignal.getStore();+/** A Zod schema whose standard interface exposes a JSON Schema projection. */const hasAdvertisedInputJsonSchema = (value: unknown): boolean => {if (typeof value !== "object" || value === null) return false;@@ -124,6 +132,7 @@ class ErrorEvidenceTransport implements Transport {onmessage: Transport["onmessage"];readonly hasPerRequestStream?: boolean;private readonly pendingTools = new Map<RequestId, string>();+ private readonly pendingCompletions = new Map<RequestId, AbortController>();constructor(private readonly transport: Transport,@@ -141,6 +150,8 @@ class ErrorEvidenceTransport implements Transport {typeof message.params?.["name"] === "string")this.pendingTools.set(message.id, message.params["name"]);+ if (isJSONRPCRequest(message) && message.method === "completion/complete")+ this.pendingCompletions.set(message.id, new AbortController());// The SDK suppresses replies after cancellation, so send() cannot release// this bookkeeping. Keep transport authentication outside retained data.if (@@ -148,14 +159,28 @@ class ErrorEvidenceTransport implements Transport {message.method === "notifications/cancelled") {const id = message.params?.["requestId"];- if (typeof id === "string" || typeof id === "number")+ if (typeof id === "string" || typeof id === "number") {this.pendingTools.delete(id);+ this.pendingCompletions.get(id)?.abort();+ this.pendingCompletions.delete(id);+ }}- this.onmessage?.(message, extra);+ const completion =+ isJSONRPCRequest(message) && message.method === "completion/complete"+ ? this.pendingCompletions.get(message.id)+ : undefined;+ if (completion === undefined) this.onmessage?.(message, extra);+ else+ currentRequestSignal.run(completion.signal, () =>+ this.onmessage?.(message, extra),+ );};transport.onerror = (error) => this.onerror?.(error);transport.onclose = () => {this.pendingTools.clear();+ for (const completion of this.pendingCompletions.values())+ completion.abort();+ this.pendingCompletions.clear();this.onclose?.();};}@@ -176,6 +201,9 @@ class ErrorEvidenceTransport implements Transport {await this.transport.close();} finally {this.pendingTools.clear();+ for (const completion of this.pendingCompletions.values())+ completion.abort();+ this.pendingCompletions.clear();}}@@ -211,8 +239,10 @@ class ErrorEvidenceTransport implements Transport {await this.transport.send({ ...recovered, result }, options);} else await this.transport.send(recovered, options);} finally {- if (!isJSONRPCRequest(message) && id !== undefined)+ if (!isJSONRPCRequest(message) && id !== undefined) {this.pendingTools.delete(id);+ this.pendingCompletions.delete(id);+ }}}diff --git a/src/server/promptCompletion.ts b/src/server/promptCompletion.tsindex bc37e8fda..c4a4c028a 100644--- a/src/server/promptCompletion.ts+++ b/src/server/promptCompletion.ts@@ -2,9 +2,11 @@ import type { EvidenceReader } from "../application/investigation/InvestigationRimport { z } from "zod";import { uniqueSorted } from "../domain/canonicalOrdering.js";+import type { JsonValue } from "../domain/jsonValue.js";import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";import type { PromptCompletionKind } from "../contracts/promptContracts.js";+import { currentMcpRequestSignal } from "./EvidenceMcpServer.js";import { artifactInventoryResultSchema } from "../domain/artifactGraph.js";import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";import { parseProcessCapture } from "../domain/process/processCaptureParsing.js";@@ -57,9 +59,13 @@ const completionCandidates = async (): Promise<readonly string[]> => {switch (kind) {case "document":- return documentCandidates(analysis);+ return documentCandidates(analysis, session);case "procedure":- return procedureCandidates(analysis, context?.arguments?.document);+ return procedureCandidates(+ analysis,+ session,+ context?.arguments?.document,+ );case "provider":return providerCandidates(session);case "evidence":@@ -74,8 +80,15 @@ const completionCandidates = async (const documentCandidates = async (analysis: AnalysisOperationPort,+ session: BinarySessionPort | undefined,): Promise<readonly string[]> => {- const result = await analysis.execute("list_documents", {});+ const result = await completionInventoryLookup(+ analysis,+ session,+ "list_documents",+ {},+ );+ if (result === undefined) return [];if (!result.ok) return [];const parsed = documentListSchema.safeParse(result.value.result);return parsed.success ? parsed.data : [];@@ -83,12 +96,19 @@ const documentCandidates = async (const procedureCandidates = async (analysis: AnalysisOperationPort,+ session: BinarySessionPort | undefined,document: string | undefined,): Promise<readonly string[]> => {const byAddress = new Map<string, string>();const input =document === undefined || document.length === 0 ? {} : { document };- const result = await analysis.execute("list_procedures", input);+ const result = await completionInventoryLookup(+ analysis,+ session,+ "list_procedures",+ input,+ );+ if (result === undefined) return [];if (result.ok) {const parsed = z.array(z.object({ address: z.string(), value: z.string() }))@@ -111,6 +131,21 @@ const procedureCandidates = async (return candidates;};+const completionInventoryLookup = async (+ analysis: AnalysisOperationPort,+ session: BinarySessionPort | undefined,+ operation: "list_documents" | "list_procedures",+ parameters: Readonly<Record<string, JsonValue>>,+) => {+ const signal = currentMcpRequestSignal();+ const options = signal === undefined ? {} : { signal };+ const result =+ session === undefined+ ? await analysis.execute(operation, parameters, options)+ : await session.executeIfProviderReady(operation, parameters, options);+ return signal?.aborted === true ? undefined : result;+};+const providerCandidates = (session: BinarySessionPort | undefined,): readonly string[] => {diff --git a/tests/boundary/mcp/promptMcp.test.ts b/tests/boundary/mcp/promptMcp.test.tsindex 4e0072e8f..9138a102d 100644--- a/tests/boundary/mcp/promptMcp.test.ts+++ b/tests/boundary/mcp/promptMcp.test.ts@@ -11,7 +11,22 @@ import { afterEach, describe, expect, it } from "vitest";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";-import type { AnalysisClient } from "../../../src/application/AnalysisProvider.js";+import {+ createAnalysisExecution,+ type AnalysisClient,+} from "../../../src/application/AnalysisProvider.js";+import type { JsonValue } from "../../../src/domain/jsonValue.js";+import type {+ AnalysisProvider,+ AnalysisProviderCandidate,+ CapabilityDescriptor,+ ProviderIdentity,+} from "../../../src/application/AnalysisProvider.js";+import { AnalysisProviderRegistry } from "../../../src/application/binary/AnalysisProviderRegistry.js";+import { composeBinarySession } from "../../../src/application/binary/BinarySessionComposition.js";+import { createAnalysisProfile } from "../../../src/domain/analysisProfile.js";+import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js";+import { err, ok } from "../../../src/domain/result.js";import {createCacheProvider,createTestBinarySession,@@ -304,6 +319,67 @@ describe("guided prompt completion registry", () => {});});+it("guided prompt completion avoids cold startup and cancels warm lookup on close", async () => {+ const directory = await createTestTempDirectory("rea-prompt-warm-only-");+ temporaryDirectories.push(directory);+ const target = join(directory, "target.hop");+ await writeFile(target, "fixture target");+ const fixture = await createWarmCompletionFixture(target);+ const { client } = fixture;++ const opened = await client.callTool({+ name: "open_binary",+ arguments: { path: target },+ });+ expect(opened.isError).not.toBe(true);+ expect(fixture.childrenCreated()).toBe(0);+ expect(await complete(client, "document", "")).toEqual([]);+ expect(await complete(client, "procedure", "")).toEqual([]);+ expect(fixture.childrenCreated()).toBe(0);++ const startup = fixture.holdStartup();+ const warming = client.callTool({ name: "list_documents", arguments: {} });+ await startup.started;+ expect(await complete(client, "document", "")).toEqual([]);+ expect(await complete(client, "procedure", "")).toEqual([]);+ expect(fixture.childrenCreated()).toBe(1);+ startup.finish();+ const warmed = await warming;+ expect(warmed.isError, JSON.stringify(warmed)).not.toBe(true);+ expect(fixture.childrenCreated()).toBe(1);+ expect(await complete(client, "document", "fixture")).toEqual([+ "fixture-document",+ ]);++ const cancellation = fixture.holdCompletion();+ const controller = new AbortController();+ const cancelled = client.complete(+ {+ ref: { type: "ref/prompt", name: "investigate_feature" },+ argument: { name: "document", value: "" },+ },+ { signal: controller.signal },+ );+ await cancellation.started;+ controller.abort();+ await expect(cancelled).rejects.toThrow();+ await cancellation.aborted;++ const lifecycle = fixture.holdCompletion();+ const pending = client.complete({+ ref: { type: "ref/prompt", name: "investigate_feature" },+ argument: { name: "document", value: "" },+ });+ await lifecycle.started;+ const closed = await client.callTool({+ name: "close_binary",+ arguments: {},+ });+ expect(closed.isError).not.toBe(true);+ await lifecycle.aborted;+ expect((await pending).completion.values).toEqual([]);+}, 10_000);+describe("guided prompt completion lifecycle", () => {it("survives a cancelled completion and ignores its late result", async () => {let calls = 0;@@ -410,6 +486,181 @@ describe("guided prompt completion lifecycle", () => {}, 10_000);});+const createWarmCompletionFixture = async (target: string) => {+ const identity = {+ id: "deep-fixture",+ name: "Deep fixture provider",+ version: "1",+ };+ const analysisProfile = createAnalysisProfile(identity, { fixture: true });+ const observeCompletion = (result: JsonValue) =>+ resultOk(createAnalysisExecution(result, identity, { analysisProfile }));+ let childrenCreated = 0;+ let ready = false;+ let startupGate:+ | {+ readonly started: () => void;+ readonly release: Promise<void>;+ }+ | undefined;+ let completionGate:+ | {+ readonly started: () => void;+ readonly aborted: () => void;+ }+ | undefined;+ const deep = deepProvider(identity, {+ createClient() {+ childrenCreated += 1;+ return {+ execute: async (operation) => {+ if (operation !== "health") {+ const gate = startupGate;+ if (gate !== undefined) {+ startupGate = undefined;+ gate.started();+ await gate.release;+ }+ ready = true;+ }+ return observeCompletion(+ operation === "list_documents"+ ? ["fixture-document"]+ : operation === "list_procedures"+ ? [{ address: "0x1000", value: "fixture-procedure" }]+ : null,+ );+ },+ executeIfReady(operation, _parameters, options) {+ if (+ !ready ||+ (operation !== "list_documents" && operation !== "list_procedures")+ )+ return Promise.resolve(undefined);+ const gate = completionGate;+ if (gate === undefined)+ return Promise.resolve(+ observeCompletion(+ operation === "list_documents"+ ? ["fixture-document"]+ : [{ address: "0x1000", value: "fixture-procedure" }],+ ),+ );+ completionGate = undefined;+ gate.started();+ return new Promise((resolve) => {+ const signal = options?.signal;+ const cancel = (): void => {+ gate.aborted();+ resolve(err(new AnalysisCancelledError(operation)));+ };+ if (signal?.aborted === true) cancel();+ else signal?.addEventListener("abort", cancel, { once: true });+ });+ },+ close: () => Promise.resolve(resultOk(null)),+ };+ },+ });+ const auxiliaryIdentity: ProviderIdentity = {+ id: "aux-fixture",+ name: "Aux fixture",+ version: "1",+ };+ const auxiliary: AnalysisProvider = {+ identity: () => auxiliaryIdentity,+ capabilities: () => [+ promptCapability(auxiliaryIdentity, "inspect_artifact"),+ ],+ createClient: () => ({+ execute: () => Promise.resolve(observed(null)),+ close: () => Promise.resolve(resultOk(null)),+ }),+ };+ const session = composeBinarySession(new AnalysisProviderRegistry([deep]), [+ auxiliary,+ ]);+ const client = await connect(createServer({ kind: "session", session }));+ resources.push(session);+ return {+ client,+ childrenCreated: () => childrenCreated,+ holdStartup: () => {+ let started = (): void => undefined;+ let finish = (): void => undefined;+ const observedStart = new Promise<void>((resolve) => {+ started = resolve;+ });+ const release = new Promise<void>((resolve) => {+ finish = resolve;+ });+ startupGate = { started, release };+ return { started: observedStart, finish };+ },+ holdCompletion: () => {+ let started = (): void => undefined;+ let aborted = (): void => undefined;+ const observedStart = new Promise<void>((resolve) => {+ started = resolve;+ });+ const observedAbort = new Promise<void>((resolve) => {+ aborted = resolve;+ });+ completionGate = { started, aborted };+ return { started: observedStart, aborted: observedAbort };+ },+ };+};++const deepProvider = (+ identity: Parameters<typeof createAnalysisProfile>[0],+ options: {+ readonly createClient: AnalysisProviderCandidate["createClient"];+ },+): AnalysisProviderCandidate => ({+ identity: () => identity,+ capabilities: () => [+ promptCapability(identity, "list_documents"),+ promptCapability(identity, "list_procedures"),+ ],+ inspectAvailability: () => ({+ status: "available",+ code: null,+ reason: null,+ diagnostics: {},+ }),+ inspectTargetSupport: () => ({+ status: "supported",+ code: null,+ reason: null,+ diagnostics: {},+ }),+ resolveAnalysisProfile: async () =>+ ok({ profile: createAnalysisProfile(identity, { fixture: true }) }),+ createClient: options.createClient,+});++const promptCapability = (+ provider: ProviderIdentity,+ operation: CapabilityDescriptor["operation"],+): CapabilityDescriptor => ({+ provider,+ operation,+ available: true,+ reason: null,+ cachePolicy: "live",+ effects: {+ mutatesArtifact: false,+ launchesProcess: false,+ mayShowUi: false,+ mayAccessNetwork: false,+ mayWriteFilesystem: false,+ changesPermissions: false,+ requiresRoot: false,+ },+ limitations: [],+});+const fixtureProvider = { id: "fixture", name: "Fixture", version: "1" };const fixtureSession = (@@ -461,6 +712,22 @@ const lifecycleClient = (}return Promise.resolve(observed(null));},+ executeIfReady(operation, parameters) {+ if (operation === "list_documents")+ return Promise.resolve(observed([`${target}-document`]));+ if (operation === "list_procedures") {+ requests.push(parameters);+ return Promise.resolve(+ observed([+ {+ address: target === "first" ? "0x1000" : "0x2000",+ value: `${target}-procedure`,+ },+ ]),+ );+ }+ return Promise.resolve(undefined);+ },close: () => Promise.resolve(resultOk(null)),});diff --git a/tests/boundary/providers/ghidra/ghidraClient.test.ts b/tests/boundary/providers/ghidra/ghidraClient.test.tsindex 43abedb3d..9ce3f77ce 100644--- a/tests/boundary/providers/ghidra/ghidraClient.test.ts+++ b/tests/boundary/providers/ghidra/ghidraClient.test.ts@@ -150,6 +150,26 @@ afterEach(async () => {await Promise.all(clients.splice(0).map((client) => client.close()));});+describe("GhidraClient ready-only dispatch", () => {+ it("does not start cold and preserves the normal result once ready", async () => {+ const launcher = new FixtureLauncher();+ const client = clientFor(launcher);++ await expect(client.callToolIfReady("list_strings", {})).resolves.toBe(+ undefined,+ );+ expect(launcher.processes).toEqual([]);++ const started = await client.start();+ if (!started.ok) throw started.error;+ await expect(client.callToolIfReady("list_strings", {})).resolves.toEqual({+ ok: true,+ value: [expect.objectContaining({ value: "fixture value" })],+ });+ expect(launcher.processes).toHaveLength(1);+ });+});+it("reports unknown startup work and stops notifications when cancellation releases the process", async () => {vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });const launcher = new FixtureLauncher("silent");diff --git a/tests/boundary/providers/hopper/hopperClient.protocol.test.ts b/tests/boundary/providers/hopper/hopperClient.protocol.test.tsindex 007f9d336..02a6ae73b 100644--- a/tests/boundary/providers/hopper/hopperClient.protocol.test.ts+++ b/tests/boundary/providers/hopper/hopperClient.protocol.test.ts@@ -15,6 +15,26 @@ import {} from "./hopperClient.fixture.js";describe("HopperClient protocol", () => {+ it("does not start cold and preserves normal dispatch once ready", async () => {+ const launcher = new FixtureLauncher();+ const client = new HopperClient({ launcher, startupTimeoutMs: 1_000 });+ onTestFinished(async () => {+ await client.close();+ });++ await expect(+ client.callToolIfReady("echo", { label: "cold" }),+ ).resolves.toBe(undefined);+ expect(launcher.processes).toEqual([]);++ const started = await client.start();+ if (!started.ok) throw started.error;+ await expect(+ client.callToolIfReady("echo", { label: "warm" }),+ ).resolves.toEqual({ ok: true, value: { label: "warm" } });+ expect(launcher.processes).toHaveLength(1);+ });+it("sanitizes unexpected owned-cleanup exceptions", () => {expect(providerCleanupFailure(