fix(mcp): admit composed analysis through result bookkeeping
This commit is contained in:
@@ -0,0 +1,29 @@
|
||||
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
|
||||
import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";
|
||||
import type { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
|
||||
/** Run a provider-backed tool while its target binding stays admitted. */
|
||||
export type WithAdmittedAnalysis = <Value>(
|
||||
operationName: string,
|
||||
signal: AbortSignal | undefined,
|
||||
operation: (analysis: AnalysisOperationPort) => Promise<Value>,
|
||||
) => Promise<Result<Value, AnalysisError>>;
|
||||
|
||||
/** Select exactly one owner for a server's analysis operation binding. */
|
||||
export type ServerAnalysisSource =
|
||||
| { readonly kind: "session"; readonly session: BinarySessionPort }
|
||||
| { readonly kind: "fixed"; readonly analysis: AnalysisOperationPort };
|
||||
|
||||
/** Run against the source's explicit owner, admitting session-scoped work. */
|
||||
export const withAdmittedAnalysis = (
|
||||
source: ServerAnalysisSource,
|
||||
): WithAdmittedAnalysis =>
|
||||
source.kind === "session"
|
||||
? (operationName, signal, operation) =>
|
||||
source.session.withAdmittedAnalysis(operationName, signal, operation)
|
||||
: async (operationName, signal, operation) =>
|
||||
signal?.aborted === true
|
||||
? err(new AnalysisCancelledError(operationName))
|
||||
: ok(await operation(source.analysis));
|
||||
+26
-25
@@ -17,7 +17,6 @@ import {
|
||||
import { parseMcpResponseBudget } from "../config/mcpResponseBudget.js";
|
||||
import { isAbsolute } from "node:path";
|
||||
|
||||
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
|
||||
import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";
|
||||
import type { BrowserObservationPort } from "../application/BrowserObservationPort.js";
|
||||
import type { BrowserScenarioCapturePort } from "../application/BrowserScenarioCapturePort.js";
|
||||
@@ -68,6 +67,11 @@ import { registerGuidedPrompts } from "./registerPrompts.js";
|
||||
import { registerSessionTools } from "./registerSessionTools.js";
|
||||
import type { AvailabilityPolicy } from "../application/CapabilityInventory.js";
|
||||
import { sessionAvailabilityPolicy } from "./sessionAvailabilityPolicy.js";
|
||||
import {
|
||||
withAdmittedAnalysis,
|
||||
type ServerAnalysisSource,
|
||||
} from "./analysisAdmission.js";
|
||||
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
|
||||
|
||||
const TARGET_FREE_INSTRUCTIONS =
|
||||
"REA provides reverse-engineering tools for local artifacts, native binaries, managed code, browser pages, and runtimes. Use the tool that directly answers the question; discover targets or inspect inventory only when needed. Tool results include inline Evidence and report their coverage and limitations.";
|
||||
@@ -168,10 +172,11 @@ const createMcpServer = (
|
||||
* fixed-target seam used by focused tests and embedders.
|
||||
*/
|
||||
export const createServer = (
|
||||
analysis: AnalysisOperationPort,
|
||||
session?: BinarySessionPort,
|
||||
source: ServerAnalysisSource,
|
||||
options: CreateServerOptions = {},
|
||||
): EvidenceMcpServer => {
|
||||
const session = source.kind === "session" ? source.session : undefined;
|
||||
const analysis = source.kind === "session" ? source.session : source.analysis;
|
||||
const environment = snapshotEnvironment(options.environment ?? process.env);
|
||||
const delivery = selectToolResultDelivery(environment, options.delivery);
|
||||
const selectedOptions = { ...options, environment, delivery };
|
||||
@@ -194,7 +199,6 @@ export const createServer = (
|
||||
} = createSessionRecorders(server, session);
|
||||
const toolContext: ServerToolContext = {
|
||||
server,
|
||||
analysis,
|
||||
session,
|
||||
options: selectedOptions,
|
||||
environment,
|
||||
@@ -203,6 +207,7 @@ export const createServer = (
|
||||
activeTarget,
|
||||
recordEvidence,
|
||||
recordEvidenceWithUnknown,
|
||||
withAdmittedAnalysis: withAdmittedAnalysis(source),
|
||||
};
|
||||
registerBinaryAnalysisTools(toolContext);
|
||||
const previousOnclose = server.server.onclose;
|
||||
@@ -344,39 +349,34 @@ const createSessionRecorders = (
|
||||
recordEvidence:
|
||||
session === undefined
|
||||
? undefined
|
||||
: (evidence: Parameters<typeof session.recordEvidence>[0]) => {
|
||||
const recorded = session.recordEvidence(evidence);
|
||||
return recorded;
|
||||
},
|
||||
: (evidence: Parameters<typeof session.recordEvidence>[0]) =>
|
||||
session.recordEvidence(evidence),
|
||||
recordEvidenceWithUnknown:
|
||||
session === undefined
|
||||
? undefined
|
||||
: (
|
||||
evidence: Parameters<typeof session.recordEvidenceWithUnknown>[0],
|
||||
input: Parameters<typeof session.recordEvidenceWithUnknown>[1],
|
||||
) => {
|
||||
const recorded = session.recordEvidenceWithUnknown(evidence, input);
|
||||
return recorded;
|
||||
},
|
||||
) => session.recordEvidenceWithUnknown(evidence, input),
|
||||
});
|
||||
|
||||
interface ServerToolContext extends ReturnType<typeof createSessionRecorders> {
|
||||
readonly server: EvidenceMcpServer;
|
||||
readonly analysis: AnalysisOperationPort;
|
||||
readonly session: BinarySessionPort | undefined;
|
||||
readonly options: CreateServerOptions;
|
||||
readonly environment: Readonly<NodeJS.ProcessEnv>;
|
||||
readonly logger: Logger;
|
||||
readonly withAdmittedAnalysis: WithAdmittedAnalysis;
|
||||
}
|
||||
|
||||
const registerBinaryAnalysisTools = ({
|
||||
server,
|
||||
analysis,
|
||||
session,
|
||||
logger,
|
||||
activeTarget,
|
||||
recordEvidence,
|
||||
recordEvidenceWithUnknown,
|
||||
withAdmittedAnalysis,
|
||||
}: ServerToolContext): void => {
|
||||
const recordUnknown =
|
||||
session === undefined
|
||||
@@ -388,9 +388,10 @@ const registerBinaryAnalysisTools = ({
|
||||
activeTarget,
|
||||
recordEvidence,
|
||||
recordUnknown,
|
||||
withAdmittedAnalysis,
|
||||
};
|
||||
registerOfficialTools(server, analysis, analysisOptions);
|
||||
registerEnhancedTools(server, analysis, {
|
||||
registerOfficialTools(server, analysisOptions);
|
||||
registerEnhancedTools(server, {
|
||||
...analysisOptions,
|
||||
analysisProfile:
|
||||
session === undefined ? undefined : () => session.analysisProfile(),
|
||||
@@ -403,15 +404,15 @@ const registerBinaryAnalysisTools = ({
|
||||
? undefined
|
||||
: (input) => session.recordWorkflowSnapshot(input),
|
||||
});
|
||||
const evidenceOptions = { logger, activeTarget, recordEvidence };
|
||||
registerNativeTools(server, analysis, evidenceOptions);
|
||||
registerArtifactTools(server, analysis, {
|
||||
...evidenceOptions,
|
||||
});
|
||||
registerManagedTools(server, analysis, {
|
||||
...evidenceOptions,
|
||||
session,
|
||||
});
|
||||
const evidenceOptions = {
|
||||
logger,
|
||||
activeTarget,
|
||||
recordEvidence,
|
||||
withAdmittedAnalysis,
|
||||
};
|
||||
registerNativeTools(server, evidenceOptions);
|
||||
registerArtifactTools(server, evidenceOptions);
|
||||
registerManagedTools(server, evidenceOptions);
|
||||
if (session !== undefined)
|
||||
registerManagedWorkflowTools(server, {
|
||||
logger,
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
|
||||
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
|
||||
|
||||
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
|
||||
import { ARTIFACT_TOOL_CONTRACTS } from "../contracts/artifactToolContracts.js";
|
||||
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
|
||||
import type { Logger } from "pino";
|
||||
@@ -11,14 +10,14 @@ import { artifactInspectionResultSchema } from "../domain/artifactInspection.js"
|
||||
/** Register deterministic artifact inventory and safe extraction operations. */
|
||||
export const registerArtifactTools = (
|
||||
server: EvidenceMcpServer,
|
||||
analysis: AnalysisOperationPort,
|
||||
options: {
|
||||
readonly logger: Logger;
|
||||
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
|
||||
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
|
||||
readonly withAdmittedAnalysis: import("./analysisAdmission.js").WithAdmittedAnalysis;
|
||||
},
|
||||
): void => {
|
||||
registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, {
|
||||
registerEvidenceTools(server, ARTIFACT_TOOL_CONTRACTS, {
|
||||
...options,
|
||||
sourceEvidence: (operation, result) =>
|
||||
operation === "inspect_artifact"
|
||||
|
||||
@@ -22,23 +22,25 @@ export const registerCloseLifecycleTool = ({
|
||||
const progress = mcpProgressReporter(context);
|
||||
const snapshotPath = input.snapshot_path;
|
||||
if (snapshotPath === undefined) {
|
||||
await reportLifecycleStart(progress, closeContract.name);
|
||||
const closed = await logToolExecution(logger, closeContract.name, () =>
|
||||
// Enqueue the lifecycle transition before awaiting progress transport so
|
||||
// a later open request cannot overtake this close.
|
||||
const closing = logToolExecution(logger, closeContract.name, () =>
|
||||
session.close({ progress }),
|
||||
);
|
||||
await reportLifecycleStart(progress, closeContract.name);
|
||||
const closed = await closing;
|
||||
await reportLifecycleEnd(progress, closeContract.name, closed.ok);
|
||||
return server.delivery.toCallToolResult(closed, closeContract);
|
||||
}
|
||||
const closing = logToolExecution(logger, closeContract.name, () =>
|
||||
session.closeWithSnapshot(snapshotPath, input.overwrite, { progress }),
|
||||
);
|
||||
await reportLifecycleStart(
|
||||
progress,
|
||||
closeContract.name,
|
||||
"saving snapshot; closing provider",
|
||||
);
|
||||
const closed = await logToolExecution(logger, closeContract.name, () =>
|
||||
session.closeWithSnapshot(snapshotPath, input.overwrite, {
|
||||
progress,
|
||||
}),
|
||||
);
|
||||
const closed = await closing;
|
||||
await reportLifecycleEnd(progress, closeContract.name, closed.ok);
|
||||
return server.delivery.toCallToolResult(
|
||||
closed.ok ? ok({ ...closed.value }) : closed,
|
||||
|
||||
@@ -28,9 +28,11 @@ import { mcpProgressReporter } from "./mcpProgress.js";
|
||||
import { logToolExecution } from "./toolLogging.js";
|
||||
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
|
||||
import { executeFunctionAnalysisEvidence } from "../application/FunctionAnalysisEvidence.js";
|
||||
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
|
||||
|
||||
/** Optional session services used by enhanced tool registration. */
|
||||
export interface EnhancedToolRegistration {
|
||||
readonly withAdmittedAnalysis: WithAdmittedAnalysis;
|
||||
readonly logger: Logger;
|
||||
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
|
||||
readonly analysisProfile:
|
||||
@@ -52,7 +54,6 @@ export interface EnhancedToolRegistration {
|
||||
// oxlint-disable-next-line max-lines-per-function -- direct SDK calls retain each schema-handler type correlation.
|
||||
export const registerEnhancedTools = (
|
||||
server: EvidenceMcpServer,
|
||||
analysis: AnalysisOperationPort,
|
||||
options: EnhancedToolRegistration,
|
||||
): void => {
|
||||
const registration = { ...options, delivery: server.delivery };
|
||||
@@ -76,7 +77,7 @@ export const registerEnhancedTools = (
|
||||
traceNativeValues.name,
|
||||
toolRegistrationOptions(traceNativeValues),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, traceNativeValues, {
|
||||
executeEnhancedTool(registration, traceNativeValues, {
|
||||
validatedCall: { name: "trace_native_values", input },
|
||||
context,
|
||||
}),
|
||||
@@ -85,7 +86,7 @@ export const registerEnhancedTools = (
|
||||
nativeDispatchMetadata.name,
|
||||
toolRegistrationOptions(nativeDispatchMetadata),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, nativeDispatchMetadata, {
|
||||
executeEnhancedTool(registration, nativeDispatchMetadata, {
|
||||
validatedCall: { name: "inspect_native_dispatch_metadata", input },
|
||||
context,
|
||||
}),
|
||||
@@ -94,7 +95,7 @@ export const registerEnhancedTools = (
|
||||
objcClasses.name,
|
||||
toolRegistrationOptions(objcClasses),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, objcClasses, {
|
||||
executeEnhancedTool(registration, objcClasses, {
|
||||
validatedCall: { name: "get_objc_classes", input },
|
||||
context,
|
||||
}),
|
||||
@@ -103,7 +104,7 @@ export const registerEnhancedTools = (
|
||||
objcProtocols.name,
|
||||
toolRegistrationOptions(objcProtocols),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, objcProtocols, {
|
||||
executeEnhancedTool(registration, objcProtocols, {
|
||||
validatedCall: { name: "get_objc_protocols", input },
|
||||
context,
|
||||
}),
|
||||
@@ -112,7 +113,7 @@ export const registerEnhancedTools = (
|
||||
batchDecompile.name,
|
||||
toolRegistrationOptions(batchDecompile),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, batchDecompile, {
|
||||
executeEnhancedTool(registration, batchDecompile, {
|
||||
validatedCall: { name: "batch_decompile", input },
|
||||
context,
|
||||
}),
|
||||
@@ -121,7 +122,7 @@ export const registerEnhancedTools = (
|
||||
callGraph.name,
|
||||
toolRegistrationOptions(callGraph),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, callGraph, {
|
||||
executeEnhancedTool(registration, callGraph, {
|
||||
validatedCall: { name: "get_call_graph", input },
|
||||
context,
|
||||
}),
|
||||
@@ -130,7 +131,7 @@ export const registerEnhancedTools = (
|
||||
swiftTypes.name,
|
||||
toolRegistrationOptions(swiftTypes),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, swiftTypes, {
|
||||
executeEnhancedTool(registration, swiftTypes, {
|
||||
validatedCall: { name: "analyze_swift_types", input },
|
||||
context,
|
||||
}),
|
||||
@@ -139,7 +140,7 @@ export const registerEnhancedTools = (
|
||||
xrefsToName.name,
|
||||
toolRegistrationOptions(xrefsToName),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, xrefsToName, {
|
||||
executeEnhancedTool(registration, xrefsToName, {
|
||||
validatedCall: { name: "find_xrefs_to_name", input },
|
||||
context,
|
||||
}),
|
||||
@@ -148,7 +149,7 @@ export const registerEnhancedTools = (
|
||||
binaryOverview.name,
|
||||
toolRegistrationOptions(binaryOverview),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, binaryOverview, {
|
||||
executeEnhancedTool(registration, binaryOverview, {
|
||||
validatedCall: { name: "binary_overview", input },
|
||||
context,
|
||||
}),
|
||||
@@ -157,7 +158,7 @@ export const registerEnhancedTools = (
|
||||
analyzeFunction.name,
|
||||
toolRegistrationOptions(analyzeFunction),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, analyzeFunction, {
|
||||
executeEnhancedTool(registration, analyzeFunction, {
|
||||
validatedCall: { name: "analyze_function", input },
|
||||
context,
|
||||
}),
|
||||
@@ -166,7 +167,7 @@ export const registerEnhancedTools = (
|
||||
inspectNativeApi.name,
|
||||
toolRegistrationOptions(inspectNativeApi),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, inspectNativeApi, {
|
||||
executeEnhancedTool(registration, inspectNativeApi, {
|
||||
validatedCall: { name: "inspect_native_api", input },
|
||||
context,
|
||||
}),
|
||||
@@ -175,7 +176,7 @@ export const registerEnhancedTools = (
|
||||
traceFeature.name,
|
||||
toolRegistrationOptions(traceFeature),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, traceFeature, {
|
||||
executeEnhancedTool(registration, traceFeature, {
|
||||
validatedCall: { name: "trace_feature", input },
|
||||
context,
|
||||
}),
|
||||
@@ -184,7 +185,7 @@ export const registerEnhancedTools = (
|
||||
traceCallPath.name,
|
||||
toolRegistrationOptions(traceCallPath),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, traceCallPath, {
|
||||
executeEnhancedTool(registration, traceCallPath, {
|
||||
validatedCall: { name: "trace_call_path", input },
|
||||
context,
|
||||
}),
|
||||
@@ -193,7 +194,7 @@ export const registerEnhancedTools = (
|
||||
traceNativeUiAction.name,
|
||||
toolRegistrationOptions(traceNativeUiAction),
|
||||
(input, context) =>
|
||||
executeEnhancedTool(analysis, registration, traceNativeUiAction, {
|
||||
executeEnhancedTool(registration, traceNativeUiAction, {
|
||||
validatedCall: { name: "trace_native_ui_action", input },
|
||||
context,
|
||||
}),
|
||||
@@ -201,7 +202,6 @@ export const registerEnhancedTools = (
|
||||
};
|
||||
|
||||
const executeEnhancedTool = async (
|
||||
analysis: AnalysisOperationPort,
|
||||
registration: EnhancedToolRegistration & {
|
||||
readonly delivery: ToolResultDelivery;
|
||||
},
|
||||
@@ -211,76 +211,86 @@ const executeEnhancedTool = async (
|
||||
readonly context: ServerContext;
|
||||
},
|
||||
): Promise<CallToolResult> => {
|
||||
const { validatedCall, context } = request;
|
||||
const name = validatedCall.name;
|
||||
const progress = mcpProgressReporter(context);
|
||||
await progress.report({
|
||||
phase: name,
|
||||
completed: 0,
|
||||
total: 1,
|
||||
message: "started",
|
||||
});
|
||||
const parsedInput = validatedCall.input;
|
||||
const parameters = jsonParameters(parsedInput);
|
||||
if (name === "analyze_function")
|
||||
return executeFunctionTool(analysis, registration, contract, {
|
||||
context,
|
||||
parameters,
|
||||
});
|
||||
const services = new EnhancedTools({
|
||||
execute: (operation, operationParameters, executionOptions) =>
|
||||
analysis.execute(operation, operationParameters, {
|
||||
...executionOptions,
|
||||
progress,
|
||||
}),
|
||||
});
|
||||
const result = await logToolExecution(registration.logger, name, () =>
|
||||
services.executeValidated(validatedCall, context.mcpReq.signal),
|
||||
);
|
||||
await progress.report({
|
||||
phase: name,
|
||||
completed: 1,
|
||||
total: 1,
|
||||
message: result.ok ? "completed" : "failed",
|
||||
terminal: true,
|
||||
});
|
||||
if (result.ok) {
|
||||
const evidence = createWorkflowEvidence({
|
||||
target: registration.activeTarget?.(),
|
||||
operation: name,
|
||||
parameters,
|
||||
result: result.value,
|
||||
upstreamProfile: registration.analysisProfile?.(),
|
||||
});
|
||||
const recorded = registration.recordEvidence?.(evidence);
|
||||
if (recorded !== undefined && !recorded.ok)
|
||||
return registration.delivery.toCallToolResult(recorded, contract);
|
||||
if (
|
||||
name !== "trace_native_ui_action" &&
|
||||
registration.allowsSnapshotReplay?.(name) === true
|
||||
) {
|
||||
const workflowRecord = workflowSnapshotRecord(evidence, name);
|
||||
if (workflowRecord !== undefined) {
|
||||
const snapshot = registration.recordWorkflowSnapshot?.(workflowRecord);
|
||||
if (snapshot !== undefined && !snapshot.ok)
|
||||
return registration.delivery.toCallToolResult(snapshot, contract);
|
||||
const admitted = await registration.withAdmittedAnalysis(
|
||||
request.validatedCall.name,
|
||||
request.context.mcpReq.signal,
|
||||
async (admittedAnalysis) => {
|
||||
const { validatedCall, context } = request;
|
||||
const name = validatedCall.name;
|
||||
const progress = mcpProgressReporter(context);
|
||||
await progress.report({
|
||||
phase: name,
|
||||
completed: 0,
|
||||
total: 1,
|
||||
message: "started",
|
||||
});
|
||||
const parsedInput = validatedCall.input;
|
||||
const parameters = jsonParameters(parsedInput);
|
||||
if (name === "analyze_function")
|
||||
return executeFunctionTool(admittedAnalysis, registration, contract, {
|
||||
context,
|
||||
parameters,
|
||||
});
|
||||
const services = new EnhancedTools({
|
||||
execute: (operation, operationParameters, executionOptions) =>
|
||||
admittedAnalysis.execute(operation, operationParameters, {
|
||||
...executionOptions,
|
||||
progress,
|
||||
}),
|
||||
});
|
||||
const result = await logToolExecution(registration.logger, name, () =>
|
||||
services.executeValidated(validatedCall, context.mcpReq.signal),
|
||||
);
|
||||
await progress.report({
|
||||
phase: name,
|
||||
completed: 1,
|
||||
total: 1,
|
||||
message: result.ok ? "completed" : "failed",
|
||||
terminal: true,
|
||||
});
|
||||
if (result.ok) {
|
||||
const evidence = createWorkflowEvidence({
|
||||
target: registration.activeTarget?.(),
|
||||
operation: name,
|
||||
parameters,
|
||||
result: result.value,
|
||||
upstreamProfile: registration.analysisProfile?.(),
|
||||
});
|
||||
const recorded = registration.recordEvidence?.(evidence);
|
||||
if (recorded !== undefined && !recorded.ok)
|
||||
return registration.delivery.toCallToolResult(recorded, contract);
|
||||
if (
|
||||
name !== "trace_native_ui_action" &&
|
||||
registration.allowsSnapshotReplay?.(name) === true
|
||||
) {
|
||||
const workflowRecord = workflowSnapshotRecord(evidence, name);
|
||||
if (workflowRecord !== undefined) {
|
||||
const snapshot =
|
||||
registration.recordWorkflowSnapshot?.(workflowRecord);
|
||||
if (snapshot !== undefined && !snapshot.ok)
|
||||
return registration.delivery.toCallToolResult(snapshot, contract);
|
||||
}
|
||||
}
|
||||
const unknowns = recordWorkflowUnknowns({
|
||||
name,
|
||||
result: result.value,
|
||||
evidenceId: evidence.evidence_id,
|
||||
recordUnknown: registration.recordUnknown,
|
||||
});
|
||||
if (!unknowns.ok)
|
||||
return registration.delivery.toCallToolResult(unknowns, contract);
|
||||
return registration.delivery.toEvidenceToolResult(
|
||||
evidence,
|
||||
contract,
|
||||
recorded,
|
||||
);
|
||||
}
|
||||
}
|
||||
const unknowns = recordWorkflowUnknowns({
|
||||
name,
|
||||
result: result.value,
|
||||
evidenceId: evidence.evidence_id,
|
||||
recordUnknown: registration.recordUnknown,
|
||||
});
|
||||
if (!unknowns.ok)
|
||||
return registration.delivery.toCallToolResult(unknowns, contract);
|
||||
return registration.delivery.toEvidenceToolResult(
|
||||
evidence,
|
||||
contract,
|
||||
recorded,
|
||||
);
|
||||
}
|
||||
return registration.delivery.toCallToolResult(result, contract);
|
||||
return registration.delivery.toCallToolResult(result, contract);
|
||||
},
|
||||
);
|
||||
return admitted.ok
|
||||
? admitted.value
|
||||
: registration.delivery.toCallToolResult(admitted, contract);
|
||||
};
|
||||
|
||||
const executeFunctionTool = async (
|
||||
|
||||
@@ -14,11 +14,16 @@ import { mcpProgressReporter } from "./mcpProgress.js";
|
||||
import { logToolExecution } from "./toolLogging.js";
|
||||
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
|
||||
import { createArtifactExtractionDestination } from "../application/artifacts/ArtifactExtractionDestination.js";
|
||||
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
|
||||
|
||||
interface EvidenceToolRegistration {
|
||||
readonly logger: Logger;
|
||||
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
|
||||
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
|
||||
readonly withAdmittedAnalysis: WithAdmittedAnalysis;
|
||||
readonly analysisForAdmission?: (
|
||||
analysis: AnalysisOperationPort,
|
||||
) => AnalysisOperationPort;
|
||||
readonly sourceEvidence?: (
|
||||
operation: Exclude<AnalysisOperation, "health">,
|
||||
result: import("../domain/jsonValue.js").JsonValue,
|
||||
@@ -28,7 +33,6 @@ interface EvidenceToolRegistration {
|
||||
/** Register provider-backed contracts that return atomic Evidence observations. */
|
||||
export const registerEvidenceTools = (
|
||||
server: EvidenceMcpServer,
|
||||
analysis: AnalysisOperationPort,
|
||||
contracts: readonly ToolContract<Exclude<AnalysisOperation, "health">>[],
|
||||
options: EvidenceToolRegistration,
|
||||
): void => {
|
||||
@@ -37,68 +41,84 @@ export const registerEvidenceTools = (
|
||||
contract.name,
|
||||
toolRegistrationOptions(contract),
|
||||
async (input, context) => {
|
||||
const progress = mcpProgressReporter(context);
|
||||
await progress.report({
|
||||
phase: contract.name,
|
||||
completed: 0,
|
||||
total: 1,
|
||||
message: "started",
|
||||
});
|
||||
const parameters = jsonObjectSchema.parse(input);
|
||||
const executionParameters =
|
||||
contract.name === "extract_artifact"
|
||||
? {
|
||||
...parameters,
|
||||
output_root: createArtifactExtractionDestination(),
|
||||
}
|
||||
: parameters;
|
||||
const execution = await logToolExecution(
|
||||
options.logger,
|
||||
const admitted = await options.withAdmittedAnalysis(
|
||||
contract.name,
|
||||
() =>
|
||||
analysis.execute(contract.name, executionParameters, {
|
||||
signal: context.mcpReq.signal,
|
||||
progress,
|
||||
}),
|
||||
);
|
||||
await progress.report({
|
||||
phase: contract.name,
|
||||
completed: 1,
|
||||
total: 1,
|
||||
message: execution.ok ? "completed" : "failed",
|
||||
terminal: true,
|
||||
});
|
||||
if (!execution.ok)
|
||||
return server.delivery.toCallToolResult(execution, contract);
|
||||
const sourceEvidence =
|
||||
options.sourceEvidence?.(contract.name, execution.value.result) ?? [];
|
||||
const evidence = createEvidence(
|
||||
execution.value.subject ?? options.activeTarget?.(),
|
||||
execution.value.provider,
|
||||
{
|
||||
operation: contract.name,
|
||||
parameters,
|
||||
result: execution.value.result,
|
||||
...(execution.value.analysisProfile === undefined
|
||||
? {}
|
||||
: { analysisProfile: execution.value.analysisProfile }),
|
||||
rawResult: execution.value.rawResult,
|
||||
limitations: execution.value.limitations,
|
||||
locations: execution.value.locations,
|
||||
evidenceLinks: sourceEvidence.map(({ evidence_id: id }) => id),
|
||||
context.mcpReq.signal,
|
||||
async (admittedAnalysis) => {
|
||||
const analysis =
|
||||
options.analysisForAdmission?.(admittedAnalysis) ??
|
||||
admittedAnalysis;
|
||||
const progress = mcpProgressReporter(context);
|
||||
await progress.report({
|
||||
phase: contract.name,
|
||||
completed: 0,
|
||||
total: 1,
|
||||
message: "started",
|
||||
});
|
||||
const parameters = jsonObjectSchema.parse(input);
|
||||
const executionParameters =
|
||||
contract.name === "extract_artifact"
|
||||
? {
|
||||
...parameters,
|
||||
output_root: createArtifactExtractionDestination(),
|
||||
}
|
||||
: parameters;
|
||||
const execution = await logToolExecution(
|
||||
options.logger,
|
||||
contract.name,
|
||||
() =>
|
||||
analysis.execute(contract.name, executionParameters, {
|
||||
signal: context.mcpReq.signal,
|
||||
progress,
|
||||
}),
|
||||
);
|
||||
await progress.report({
|
||||
phase: contract.name,
|
||||
completed: 1,
|
||||
total: 1,
|
||||
message: execution.ok ? "completed" : "failed",
|
||||
terminal: true,
|
||||
});
|
||||
if (!execution.ok)
|
||||
return server.delivery.toCallToolResult(execution, contract);
|
||||
const sourceEvidence =
|
||||
options.sourceEvidence?.(contract.name, execution.value.result) ??
|
||||
[];
|
||||
const evidence = createEvidence(
|
||||
execution.value.subject ?? options.activeTarget?.(),
|
||||
execution.value.provider,
|
||||
{
|
||||
operation: contract.name,
|
||||
parameters,
|
||||
result: execution.value.result,
|
||||
...(execution.value.analysisProfile === undefined
|
||||
? {}
|
||||
: { analysisProfile: execution.value.analysisProfile }),
|
||||
rawResult: execution.value.rawResult,
|
||||
limitations: execution.value.limitations,
|
||||
locations: execution.value.locations,
|
||||
evidenceLinks: sourceEvidence.map(({ evidence_id: id }) => id),
|
||||
},
|
||||
);
|
||||
for (const source of sourceEvidence) {
|
||||
const sourceRecorded = options.recordEvidence?.(source);
|
||||
if (sourceRecorded !== undefined && !sourceRecorded.ok)
|
||||
return server.delivery.toCallToolResult(
|
||||
sourceRecorded,
|
||||
contract,
|
||||
);
|
||||
}
|
||||
const recorded = options.recordEvidence?.(evidence);
|
||||
return server.delivery.toEvidenceToolResult(
|
||||
evidence,
|
||||
contract,
|
||||
recorded,
|
||||
);
|
||||
},
|
||||
);
|
||||
for (const source of sourceEvidence) {
|
||||
const sourceRecorded = options.recordEvidence?.(source);
|
||||
if (sourceRecorded !== undefined && !sourceRecorded.ok)
|
||||
return server.delivery.toCallToolResult(sourceRecorded, contract);
|
||||
}
|
||||
const recorded = options.recordEvidence?.(evidence);
|
||||
return server.delivery.toEvidenceToolResult(
|
||||
evidence,
|
||||
contract,
|
||||
recorded,
|
||||
);
|
||||
return admitted.ok
|
||||
? admitted.value
|
||||
: server.delivery.toCallToolResult(admitted, contract);
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
@@ -2,7 +2,6 @@ import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
|
||||
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
|
||||
|
||||
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
|
||||
import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";
|
||||
import { MANAGED_TOOL_CONTRACTS } from "../contracts/managed/managedToolContracts.js";
|
||||
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
|
||||
import { AnalysisInputError } from "../domain/analysisErrorCore.js";
|
||||
@@ -15,16 +14,17 @@ import { isManagedToolName } from "../contracts/managed/managedToolContracts.js"
|
||||
/** Register execution-free managed PE/CLI inspection. */
|
||||
export const registerManagedTools = (
|
||||
server: EvidenceMcpServer,
|
||||
analysis: AnalysisOperationPort,
|
||||
options: {
|
||||
readonly logger: Logger;
|
||||
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
|
||||
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
|
||||
readonly session: BinarySessionPort | undefined;
|
||||
readonly withAdmittedAnalysis: import("./analysisAdmission.js").WithAdmittedAnalysis;
|
||||
},
|
||||
): void => {
|
||||
let selectedManagedPath: string | undefined;
|
||||
const managedAnalysis: AnalysisOperationPort = {
|
||||
const analysisForAdmission = (
|
||||
analysis: AnalysisOperationPort,
|
||||
): AnalysisOperationPort => ({
|
||||
execute: async (operation, parameters, executionOptions) => {
|
||||
if (!isManagedToolName(operation))
|
||||
return analysis.execute(operation, parameters, executionOptions);
|
||||
@@ -57,11 +57,9 @@ export const registerManagedTools = (
|
||||
selectedManagedPath = requestedPath;
|
||||
return execution;
|
||||
},
|
||||
};
|
||||
registerEvidenceTools(
|
||||
server,
|
||||
managedAnalysis,
|
||||
MANAGED_TOOL_CONTRACTS,
|
||||
options,
|
||||
);
|
||||
});
|
||||
registerEvidenceTools(server, MANAGED_TOOL_CONTRACTS, {
|
||||
...options,
|
||||
analysisForAdmission,
|
||||
});
|
||||
};
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
|
||||
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
|
||||
|
||||
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
|
||||
import { NATIVE_TOOL_CONTRACTS } from "../contracts/native/nativeToolContracts.js";
|
||||
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
|
||||
import type { Logger } from "pino";
|
||||
@@ -10,12 +9,13 @@ import { registerEvidenceTools } from "./registerEvidenceTools.js";
|
||||
/** Register provider-neutral static inspection operations. */
|
||||
export const registerNativeTools = (
|
||||
server: EvidenceMcpServer,
|
||||
analysis: AnalysisOperationPort,
|
||||
options: {
|
||||
readonly logger: Logger;
|
||||
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
|
||||
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
|
||||
readonly withAdmittedAnalysis: import("./analysisAdmission.js").WithAdmittedAnalysis;
|
||||
},
|
||||
): void => {
|
||||
registerEvidenceTools(server, analysis, NATIVE_TOOL_CONTRACTS, options);
|
||||
};
|
||||
): void =>
|
||||
registerEvidenceTools(server, NATIVE_TOOL_CONTRACTS, {
|
||||
...options,
|
||||
});
|
||||
|
||||
@@ -17,77 +17,92 @@ import type { Logger } from "pino";
|
||||
import { mcpProgressReporter } from "./mcpProgress.js";
|
||||
import { logToolExecution } from "./toolLogging.js";
|
||||
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
|
||||
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
|
||||
|
||||
/** Optional session services used by direct tool registration. */
|
||||
export interface OfficialToolRegistration {
|
||||
readonly logger: Logger;
|
||||
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
|
||||
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
|
||||
readonly withAdmittedAnalysis: WithAdmittedAnalysis;
|
||||
}
|
||||
|
||||
/** Register direct bridge proxies, preserving MCP cancellation and typed errors. */
|
||||
export const registerOfficialTools = (
|
||||
server: EvidenceMcpServer,
|
||||
analysis: AnalysisOperationPort,
|
||||
options: OfficialToolRegistration,
|
||||
): void => {
|
||||
for (const contract of OFFICIAL_TOOL_CONTRACTS) {
|
||||
registerOfficialTool(server, analysis, contract, {
|
||||
registerOfficialTool(server, contract, {
|
||||
logger: options.logger,
|
||||
activeTarget: options.activeTarget,
|
||||
recordEvidence: options.recordEvidence,
|
||||
withAdmittedAnalysis: options.withAdmittedAnalysis,
|
||||
});
|
||||
}
|
||||
};
|
||||
|
||||
const registerOfficialTool = (
|
||||
server: EvidenceMcpServer,
|
||||
analysis: AnalysisOperationPort,
|
||||
contract: (typeof OFFICIAL_TOOL_CONTRACTS)[number],
|
||||
registration: {
|
||||
readonly logger: Logger;
|
||||
readonly activeTarget: (() => BinaryTarget | undefined) | undefined;
|
||||
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
|
||||
readonly withAdmittedAnalysis: WithAdmittedAnalysis;
|
||||
},
|
||||
): void => {
|
||||
server.registerTool(
|
||||
contract.name,
|
||||
toolRegistrationOptions(contract),
|
||||
async (input: unknown, context: ServerContext) => {
|
||||
const arguments_ = jsonObjectSchema.parse(
|
||||
contract.inputSchema.parse(input),
|
||||
);
|
||||
const progress = mcpProgressReporter(context);
|
||||
const result = await runOfficialOperation(
|
||||
analysis,
|
||||
contract,
|
||||
arguments_,
|
||||
{
|
||||
logger: registration.logger,
|
||||
signal: context.mcpReq.signal,
|
||||
progress,
|
||||
const admitted = await registration.withAdmittedAnalysis(
|
||||
contract.name,
|
||||
context.mcpReq.signal,
|
||||
async (admittedAnalysis) => {
|
||||
const arguments_ = jsonObjectSchema.parse(
|
||||
contract.inputSchema.parse(input),
|
||||
);
|
||||
const progress = mcpProgressReporter(context);
|
||||
const result = await runOfficialOperation(
|
||||
admittedAnalysis,
|
||||
contract,
|
||||
arguments_,
|
||||
{
|
||||
logger: registration.logger,
|
||||
signal: context.mcpReq.signal,
|
||||
progress,
|
||||
},
|
||||
);
|
||||
if (!result.ok) {
|
||||
return server.delivery.toCallToolResult(result, contract);
|
||||
}
|
||||
const evidence = createEvidence(
|
||||
result.value.subject ?? registration.activeTarget?.(),
|
||||
result.value.provider,
|
||||
{
|
||||
operation: contract.name,
|
||||
parameters: arguments_,
|
||||
result: result.value.result,
|
||||
...(result.value.analysisProfile === undefined
|
||||
? {}
|
||||
: { analysisProfile: result.value.analysisProfile }),
|
||||
rawResult: result.value.rawResult,
|
||||
limitations: result.value.limitations,
|
||||
locations: result.value.locations,
|
||||
},
|
||||
);
|
||||
const recorded = registration.recordEvidence?.(evidence);
|
||||
return server.delivery.toEvidenceToolResult(
|
||||
evidence,
|
||||
contract,
|
||||
recorded,
|
||||
);
|
||||
},
|
||||
);
|
||||
if (!result.ok) {
|
||||
return server.delivery.toCallToolResult(result, contract);
|
||||
}
|
||||
const evidence = createEvidence(
|
||||
result.value.subject ?? registration.activeTarget?.(),
|
||||
result.value.provider,
|
||||
{
|
||||
operation: contract.name,
|
||||
parameters: arguments_,
|
||||
result: result.value.result,
|
||||
...(result.value.analysisProfile === undefined
|
||||
? {}
|
||||
: { analysisProfile: result.value.analysisProfile }),
|
||||
rawResult: result.value.rawResult,
|
||||
limitations: result.value.limitations,
|
||||
locations: result.value.locations,
|
||||
},
|
||||
);
|
||||
const recorded = registration.recordEvidence?.(evidence);
|
||||
return server.delivery.toEvidenceToolResult(evidence, contract, recorded);
|
||||
return admitted.ok
|
||||
? admitted.value
|
||||
: server.delivery.toCallToolResult(admitted, contract);
|
||||
},
|
||||
);
|
||||
};
|
||||
|
||||
@@ -232,20 +232,36 @@ const registerContextTools = (
|
||||
navigationContract.name,
|
||||
toolRegistrationOptions(navigationContract),
|
||||
async (input, context) => {
|
||||
return server.delivery.toCallToolResult(
|
||||
await getNavigationContext(session, input, context.mcpReq.signal),
|
||||
navigationContract,
|
||||
const admitted = await session.withAdmittedAnalysis(
|
||||
navigationContract.name,
|
||||
context.mcpReq.signal,
|
||||
async (analysis) =>
|
||||
server.delivery.toCallToolResult(
|
||||
await getNavigationContext(analysis, input, context.mcpReq.signal),
|
||||
navigationContract,
|
||||
),
|
||||
);
|
||||
return admitted.ok
|
||||
? admitted.value
|
||||
: server.delivery.toCallToolResult(admitted, navigationContract);
|
||||
},
|
||||
);
|
||||
server.registerTool(
|
||||
addressContract.name,
|
||||
toolRegistrationOptions(addressContract),
|
||||
async (input, context) => {
|
||||
return server.delivery.toCallToolResult(
|
||||
await inspectAddressContext(session, input, context.mcpReq.signal),
|
||||
addressContract,
|
||||
const admitted = await session.withAdmittedAnalysis(
|
||||
addressContract.name,
|
||||
context.mcpReq.signal,
|
||||
async (analysis) =>
|
||||
server.delivery.toCallToolResult(
|
||||
await inspectAddressContext(analysis, input, context.mcpReq.signal),
|
||||
addressContract,
|
||||
),
|
||||
);
|
||||
return admitted.ok
|
||||
? admitted.value
|
||||
: server.delivery.toCallToolResult(admitted, addressContract);
|
||||
},
|
||||
);
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user