refactor(mcp): bind plain-value application tools under analysis admission (#11591)

* refactor(mcp): bind plain-value application tools under analysis admission

A value binding that declares admitted: true runs under analysis admission. evaluate_reconstruction_coverage and export_environment_bundle move to the shared binding table; registerApplicationTools and its folder are removed.

* refactor(mcp): bind the managed-code workflows as session derivations (#11593)

Each managed workflow's application owner returns its sources and residual unknown; the four MCP tools bind through the shared session-derivation kind, and registerManagedWorkflowTools is removed.
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 07:55:43 +08:00
1 parent dbd2113fcb
commit f8cec67e44
21 files changed
+304 -541

No files matched your search

@@ -1,6 +1,4 @@
{
"src/server/registerApplicationTools/coverage.ts": 1,
"src/server/registerApplicationTools/environmentBundle.ts": 1,
"src/server/registerBinaryDiagnosticsTools.ts": 1,
"src/server/registerBrowserScenarioTool.ts": 1,
"src/server/registerBrowserTools.ts": 8,
@@ -14,10 +12,6 @@
"src/server/registerGdbTools.ts": 4,
"src/server/registerGuidedWorkflowTool.ts": 1,
"src/server/registerJavaScriptRuntimeObservationTools.ts": 2,
"src/server/registerManagedWorkflowTools/compareManagedMembers.ts": 1,
"src/server/registerManagedWorkflowTools/importManagedReconstruction.ts": 1,
"src/server/registerManagedWorkflowTools/projectManagedApplicationGraph.ts": 1,
"src/server/registerManagedWorkflowTools/verifyManagedNativeBoundaries.ts": 1,
"src/server/registerNativeFunctionMatchingTool.ts": 1,
"src/server/registerResetInvestigationTool.ts": 1,
"src/server/registerReverseEngineeringTools.ts": 2,
@@ -4,6 +4,7 @@ import {
type EvidenceLookup,
} from "../EvidenceInputResolver.js";
import type { ExecutionOptions } from "../../ports/AnalysisProvider.js";
import type { InvestigationWorkflowExecution } from "../investigation/InvestigationWorkflows.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
createEvidence,
@@ -24,19 +25,43 @@ import { MANAGED_WORKFLOW_PROVIDER } from "../../domain/investigationProviders.j
const OPERATION = "project_managed_application_graph" as const;
/**
* Project authenticated managed Evidence into a provider-neutral graph; the
* selected artifact, member and boundary records are its sources.
*/
export const projectManagedApplicationGraphExecution = (
rawInput: unknown,
lookup?: EvidenceLookup,
options: Pick<ExecutionOptions, "signal"> = {},
): Result<InvestigationWorkflowExecution, AnalysisError> => {
const request = resolveManagedGraphEvidenceInput(rawInput, lookup, options);
if (!request.ok) return request;
const { artifact, members, boundaries } = request.value.sources;
return ok({
evidence: projectManagedGraphEvidence(request.value),
sources: [artifact, members, boundaries].flatMap((source) =>
source === undefined || source === null ? [] : [source.evidence],
),
unknown: undefined,
});
};
/** Project authenticated managed Evidence into a provider-neutral graph. */
export const projectManagedApplicationGraphEvidence = (
rawInput: unknown,
lookup?: EvidenceLookup,
options: Pick<ExecutionOptions, "signal"> = {},
): Result<Evidence, AnalysisError> => {
const request = resolveManagedGraphEvidenceInput(rawInput, lookup, options);
if (!request.ok) return request;
return ok(projectManagedGraphEvidence(request.value));
const projected = projectManagedApplicationGraphExecution(
rawInput,
lookup,
options,
);
return projected.ok ? ok(projected.value.evidence) : projected;
};
/** Resolve selected records before the managed owner authenticates and joins them. */
export const resolveManagedGraphEvidenceInput = (
const resolveManagedGraphEvidenceInput = (
rawInput: unknown,
lookup?: EvidenceLookup,
options: Pick<ExecutionOptions, "signal"> = {},
@@ -52,7 +77,7 @@ export const resolveManagedGraphEvidenceInput = (
};
/** Project the workflow owner's authenticated, identity-checked source facts. */
export const projectManagedGraphEvidence = (
const projectManagedGraphEvidence = (
request: ManagedGraphProjection,
): Evidence =>
createManagedApplicationGraphEvidence(
@@ -17,6 +17,8 @@ import { createEvidence, type Evidence } from "../../domain/evidence.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import { err, ok, type Result } from "../../domain/result.js";
import { MANAGED_WORKFLOW_PROVIDER } from "../../domain/investigationProviders.js";
import type { InvestigationWorkflowExecution } from "../investigation/InvestigationWorkflows.js";
import { workflowUnknownInput } from "../investigation/WorkflowUnknown.js";
export interface ManagedMemberComparisonExecution {
readonly evidence: Evidence;
@@ -88,6 +90,42 @@ export const executeManagedMemberComparison = (
});
};
/**
* Compare session-held inspections and keep members that remain unmatched or
* ambiguous as the comparison's residual unknown.
*/
export const compareManagedMembersExecution = (
input: unknown,
lookup: EvidenceLookup,
options: Pick<ExecutionOptions, "signal">,
): Result<InvestigationWorkflowExecution, AnalysisError> => {
const compared = executeManagedMemberComparison(input, lookup, options);
if (!compared.ok) return compared;
const { evidence, sources, summary } = compared.value;
if (summary.unknown === 0)
return ok({ evidence, sources, unknown: undefined });
const unknown = workflowUnknownInput(evidence.evidence_id, {
question:
"Which managed members remain unmatched or ambiguous across these versions?",
severity: "medium",
domain: "managed-member-comparison",
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: "inspect_managed_members",
rationale:
"Review the inspection Evidence coverage and limit diagnostics; this operation has no page override, so unresolved members must remain unknown.",
},
],
relationships: [],
});
return unknown.ok
? ok({ evidence, sources, unknown: unknown.value })
: unknown;
};
const createManagedMemberComparisonEvidence = (
left: Evidence,
right: Evidence,
@@ -20,6 +20,8 @@ import {
type ManagedNativeVerificationResult,
} from "../../domain/managed/managedNativeVerificationSchemas.js";
import { MANAGED_WORKFLOW_PROVIDER } from "../../domain/investigationProviders.js";
import type { InvestigationWorkflowExecution } from "../investigation/InvestigationWorkflows.js";
import { workflowUnknownInput } from "../investigation/WorkflowUnknown.js";
const OPERATION = "verify_managed_native_boundaries" as const;
@@ -30,6 +32,46 @@ export interface ManagedNativeVerificationExecution {
readonly hasUnknowns: boolean;
}
/**
* Verify session-held boundaries and keep declarations that remain
* unresolved or contradicted as the verification's residual unknown.
*/
export const verifyManagedNativeBoundariesExecution = (
rawInput: unknown,
lookup: EvidenceLookup,
options: Pick<ExecutionOptions, "signal">,
): Result<InvestigationWorkflowExecution, AnalysisError> => {
const verified = executeManagedNativeBoundaries(rawInput, lookup, options);
if (!verified.ok) return verified;
const { evidence, sourceEvidence: sources, hasUnknowns } = verified.value;
if (!hasUnknowns) return ok({ evidence, sources, unknown: undefined });
const unknown = workflowUnknownInput(evidence.evidence_id, {
question:
"Which managed/native boundaries remain unresolved or contradicted by the supplied native Evidence?",
severity: "medium",
domain: "managed-native-verification",
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: "inspect_managed_native_boundaries",
rationale:
"Review the inspection Evidence coverage and limit diagnostics; this operation has no page override, so unresolved declarations must remain unknown.",
},
{
operation: "analyze_function",
rationale:
"Analyze the provider-resolved native function candidate for the declared export.",
},
],
relationships: [],
});
return unknown.ok
? ok({ evidence, sources, unknown: unknown.value })
: unknown;
};
/** Resolve untrusted source Evidence, then execute over the trusted parsed source. */
export const executeManagedNativeBoundaries = (
rawInput: unknown,
@@ -15,11 +15,12 @@ import {
type EvidenceLookup,
} from "../EvidenceInputResolver.js";
import type { ExecutionOptions } from "../../ports/AnalysisProvider.js";
import type { InvestigationWorkflowExecution } from "../investigation/InvestigationWorkflows.js";
const OPERATION = "import_managed_reconstruction" as const;
/** Validate the request envelope and authenticate its managed Evidence source once. */
export const resolveManagedReconstructionEvidenceInput = (
const resolveManagedReconstructionEvidenceInput = (
rawInput: unknown,
lookup?: EvidenceLookup,
options: Pick<ExecutionOptions, "signal"> = {},
@@ -35,12 +36,30 @@ export const resolveManagedReconstructionEvidenceInput = (
return resolveManagedReconstructionImport(parsed.value.input);
};
/** Execute from the source facts returned by the resolver. */
export const importManagedReconstructionEvidenceResolved = (
resolved: ResolvedManagedReconstructionImport,
): Result<Evidence, AnalysisError> => {
const result = executeManagedReconstructionImport(resolved);
return ok(createManagedReconstructionEvidence(resolved.request, result));
/**
* Validate the raw request envelope, then authenticate and import its source;
* the authenticated static Evidence is the import's source.
*/
export const importManagedReconstructionExecution = (
rawInput: unknown,
lookup?: EvidenceLookup,
options: Pick<ExecutionOptions, "signal"> = {},
): Result<InvestigationWorkflowExecution, AnalysisError> => {
const resolved = resolveManagedReconstructionEvidenceInput(
rawInput,
lookup,
options,
);
if (!resolved.ok) return resolved;
const result = executeManagedReconstructionImport(resolved.value);
return ok({
evidence: createManagedReconstructionEvidence(
resolved.value.request,
result,
),
sources: [resolved.value.staticEvidence],
unknown: undefined,
});
};
/** Validate the raw request envelope, then authenticate and import its source. */
@@ -49,13 +68,12 @@ export const importManagedReconstructionEvidence = (
lookup?: EvidenceLookup,
options: Pick<ExecutionOptions, "signal"> = {},
): Result<Evidence, AnalysisError> => {
const resolved = resolveManagedReconstructionEvidenceInput(
const imported = importManagedReconstructionExecution(
rawInput,
lookup,
options,
);
if (!resolved.ok) return resolved;
return importManagedReconstructionEvidenceResolved(resolved.value);
return imported.ok ? ok(imported.value.evidence) : imported;
};
const createManagedReconstructionEvidence = (
+15 -6
View File
@@ -105,11 +105,14 @@ type ValueOperation<Input> = (
/**
* Run a workflow that returns a plain JSON value rather than Evidence, and
* deliver it against the contract's output schema. It records no Evidence
* and runs outside analysis admission, so provider-free guidance, discovery
* and status reads answer without waiting on an analysis.
* deliver it against the contract's output schema. It records no Evidence.
* It runs outside analysis admission, so provider-free guidance, discovery
* and status reads answer without waiting on an analysis; one that declares
* `admitted: true` runs under analysis admission like an Evidence workflow.
*/
type ValueBinding<Input = unknown> =
type ValueBinding<Input = unknown> = {
readonly admitted?: true;
} & (
| {
readonly admission: "sdk";
readonly value: ValueOperation<Input>;
@@ -127,7 +130,8 @@ type ValueBinding<Input = unknown> =
readonly derive?: never;
readonly acquire?: never;
readonly workflow?: never;
};
}
);
/**
* Derive Evidence from Evidence the session holds (a comparison or an
@@ -325,7 +329,12 @@ export const registerContractTools = (
: applicationToolRegistrationOptions(contract);
const handler =
binding.value !== undefined
? createValueToolHandler(server, binding.value, logger)(contract)
? createValueToolHandler(
server,
binding.value,
logger,
binding.admitted === true ? withAdmittedAnalysis : undefined,
)(contract)
: binding.workflow !== undefined
? createApplicationToolHandler(
server,
+19 -10
View File
@@ -181,7 +181,8 @@ export interface ValueToolRequest {
/**
* Bind a named workflow returning a plain JSON value to shared logging and
* delivery. It records no Evidence and runs outside analysis admission.
* delivery. It records no Evidence; it runs under analysis admission only
* when one is supplied.
*/
export const createValueToolHandler =
(
@@ -191,18 +192,26 @@ export const createValueToolHandler =
request: ValueToolRequest,
) => Promise<Result<JsonValue, AnalysisError>>,
logger: Logger,
withAdmittedAnalysis?: WithAdmittedAnalysis,
) =>
(contract: ToolContract) =>
async (input: unknown, context: ServerContext): Promise<CallToolResult> =>
server.delivery.toCallToolResult(
await logToolExecution(logger, contract.name, () =>
operation(input, {
signal: context.mcpReq.signal,
progress: mcpProgressReporter(context),
context,
}),
),
contract,
runAdmittedToolOperation(
server,
withAdmittedAnalysis,
contract.name,
context.mcpReq.signal,
async () =>
server.delivery.toCallToolResult(
await logToolExecution(logger, contract.name, () =>
operation(input, {
signal: context.mcpReq.signal,
progress: mcpProgressReporter(context),
context,
}),
),
contract,
),
);
/** What a derivation may read before it runs. */
+7 -14
View File
@@ -30,7 +30,7 @@ import type { BinarySessionPort } from "../application/binary/BinarySessionPort.
import { PRODUCT_IDENTITY } from "../identity.js";
import { silentLogger } from "../logger.js";
import type { Logger } from "pino";
import { registerApplicationTools } from "./registerApplicationTools.js";
import { registerGuidedWorkflowTool } from "./registerGuidedWorkflowTool.js";
import { registerArtifactTools } from "./registerArtifactTools.js";
import { registerNativeTools } from "./registerNativeTools.js";
import { registerBrowserScenarioTool } from "./registerBrowserScenarioTool.js";
@@ -46,7 +46,6 @@ import { PcapAnalysisService } from "../application/pcap/PcapAnalysisService.js"
import { ApktoolResourceAnalysisService } from "../application/apktool/ApktoolResourceAnalysisService.js";
import { FlutterBuildAnalysisService } from "../application/flutter/FlutterBuildAnalysisService.js";
import { AdbDeviceAnalysisService } from "../application/adb/AdbDeviceAnalysisService.js";
import { registerManagedWorkflowTools } from "./registerManagedWorkflowTools.js";
import { registerOfficialTools } from "./registerOfficialTools.js";
import { registerGuidedPrompts } from "./registerPrompts.js";
import { registerSessionTools } from "./registerSessionTools.js";
@@ -506,13 +505,11 @@ export const createServer = (
managed: () => {
registerManagedTools(server, { ...evidenceOptions, evidenceById });
if (session !== undefined)
registerManagedWorkflowTools(server, {
logger: toolLogger,
recordEvidence,
recordEvidenceWithUnknown,
session,
withAdmittedAnalysis: analysisAdmission,
});
registerServiceTools(
server,
{ managedWorkflows: session },
contractTools,
);
},
firmware: () =>
registerServiceTools(server, { firmwareAnalysis }, contractTools),
@@ -624,11 +621,7 @@ export const createServer = (
},
contractTools,
);
registerApplicationTools(server, {
evidenceById,
logger: toolLogger,
withAdmittedAnalysis: analysisAdmission,
});
registerGuidedWorkflowTool(server);
registerDesktopBuildTools(server, desktopBuildComputers, toolLogger);
},
session: () => {
-19
View File
@@ -1,19 +0,0 @@
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
import { registerCoverageTools } from "./registerApplicationTools/coverage.js";
import { registerEnvironmentBundleTool } from "./registerApplicationTools/environmentBundle.js";
import type { ApplicationToolRegistration } from "./registerApplicationTools/types.js";
import { registerGuidedWorkflowTool } from "./registerGuidedWorkflowTool.js";
/**
* Register the application tools that deliver plain results. Application
* workflows that complete Evidence are bound through the shared table
* (`applicationWorkflows` in serviceToolBindings.ts).
*/
export const registerApplicationTools = (
server: EvidenceMcpServer,
options: ApplicationToolRegistration,
): void => {
registerGuidedWorkflowTool(server);
registerCoverageTools(server, options);
registerEnvironmentBundleTool(server, options);
};
@@ -1,36 +0,0 @@
import type { EvidenceMcpServer } from "../EvidenceMcpServer.js";
import { runAdmittedToolOperation } from "../admittedToolOperation.js";
import { evaluateReconstructionCoverage } from "../../application/ReconstructionCoverageService.js";
import { toolContract } from "../../contracts/toolContracts.js";
import { logToolExecution } from "../toolLogging.js";
import { applicationToolRegistrationOptions } from "../toolRegistrationOptions.js";
import type { ApplicationToolRegistration } from "./types.js";
const contract = toolContract("evaluate_reconstruction_coverage");
/** Register the inline fail-closed reconstruction coverage evaluator. */
export const registerCoverageTools = (
server: EvidenceMcpServer,
options: ApplicationToolRegistration,
): void => {
server.registerTool(
contract.name,
applicationToolRegistrationOptions(contract),
async (input, context) =>
runAdmittedToolOperation(
server,
options.withAdmittedAnalysis,
contract.name,
context.mcpReq.signal,
async () => {
const result = await logToolExecution(
options.logger,
contract.name,
() => Promise.resolve(evaluateReconstructionCoverage(input)),
);
return server.delivery.toCallToolResult(result, contract);
},
),
);
};
@@ -1,54 +0,0 @@
import type { EvidenceMcpServer } from "../EvidenceMcpServer.js";
import { runAdmittedToolOperation } from "../admittedToolOperation.js";
import { exportEnvironmentBundleTool } from "../../application/environment/environmentBundleTool.js";
import { toolContract } from "../../contracts/toolContracts.js";
import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
import { err } from "../../domain/result.js";
import { logToolExecution } from "../toolLogging.js";
import { applicationToolRegistrationOptions } from "../toolRegistrationOptions.js";
import type { ApplicationToolRegistration } from "./types.js";
const contract = toolContract("export_environment_bundle");
/** Register the agent environment bundle export; it validates its own input so refusals name the field. */
export const registerEnvironmentBundleTool = (
server: EvidenceMcpServer,
options: ApplicationToolRegistration,
): void => {
server.registerTool(
contract.name,
applicationToolRegistrationOptions(contract),
async (rawInput, context) =>
runAdmittedToolOperation(
server,
options.withAdmittedAnalysis,
contract.name,
context.mcpReq.signal,
async () => {
const result = await logToolExecution(
options.logger,
contract.name,
async () => {
const parsed = contract.inputSchema.safeParse(rawInput);
if (!parsed.success)
return err(
analysisInputErrorFromIssues(
contract.name,
parsed.error.issues,
rawInput,
{ cause: parsed.error },
),
);
return exportEnvironmentBundleTool(
parsed.data,
options.evidenceById,
{ signal: context.mcpReq.signal },
);
},
);
return server.delivery.toCallToolResult(result, contract);
},
),
);
};
@@ -1,10 +0,0 @@
import type { EvidenceReader } from "../../application/investigation/InvestigationRecordPort.js";
import type { Logger } from "pino";
import type { WithAdmittedAnalysis } from "../analysisAdmission.js";
/** Shared services for the application tools that deliver plain results. */
export interface ApplicationToolRegistration {
readonly withAdmittedAnalysis?: WithAdmittedAnalysis;
readonly logger: Logger;
readonly evidenceById: EvidenceReader["evidenceById"] | undefined;
}
@@ -1,18 +0,0 @@
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
import { registerCompareManagedMembers } from "./registerManagedWorkflowTools/compareManagedMembers.js";
import { registerVerifyManagedNativeBoundaries } from "./registerManagedWorkflowTools/verifyManagedNativeBoundaries.js";
import { registerImportManagedReconstruction } from "./registerManagedWorkflowTools/importManagedReconstruction.js";
import { registerProjectManagedApplicationGraph } from "./registerManagedWorkflowTools/projectManagedApplicationGraph.js";
import type { ManagedWorkflowToolRegistration } from "./registerManagedWorkflowTools/types.js";
/** Register provider-neutral managed-code workflows. */
export const registerManagedWorkflowTools = (
server: EvidenceMcpServer,
options: ManagedWorkflowToolRegistration,
): void => {
registerCompareManagedMembers(server, options);
registerVerifyManagedNativeBoundaries(server, options);
registerImportManagedReconstruction(server, options);
registerProjectManagedApplicationGraph(server, options);
};
@@ -1,88 +0,0 @@
import { workflowUnknownInput } from "../../application/investigation/WorkflowUnknown.js";
import type { EvidenceMcpServer } from "../EvidenceMcpServer.js";
import { runAdmittedToolOperation } from "../admittedToolOperation.js";
import { recordEvidenceSources } from "../../application/investigation/recordEvidenceSources.js";
import { executeManagedMemberComparison } from "../../application/managed/ManagedMemberComparisonService.js";
import { logToolExecution } from "../toolLogging.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toolContract } from "../../contracts/toolContracts.js";
import type { ManagedWorkflowToolRegistration } from "./types.js";
const compareContract = toolContract("compare_managed_members");
/** Register the managed member comparison workflow tool. */
export const registerCompareManagedMembers = (
server: EvidenceMcpServer,
options: ManagedWorkflowToolRegistration,
): void => {
server.registerTool(
compareContract.name,
toolRegistrationOptions(compareContract),
async (input, context) =>
runAdmittedToolOperation(
server,
options.withAdmittedAnalysis,
compareContract.name,
context.mcpReq.signal,
async () => {
const result = await logToolExecution(
options.logger,
compareContract.name,
() =>
Promise.resolve(
executeManagedMemberComparison(
input,
options.session.evidenceForAnalysis.bind(options.session),
{ signal: context.mcpReq.signal },
),
),
);
if (!result.ok)
return server.delivery.toCallToolResult(result, compareContract);
const recorded = recordEvidenceSources(
options.recordEvidence,
result.value.sources,
{ evidence: result.value.evidence },
);
if (!recorded.ok)
return server.delivery.toCallToolResult(recorded, compareContract);
const comparison = result.value.summary;
const unknown = comparison.unknown > 0;
const unknownInput = unknown
? workflowUnknownInput(result.value.evidence.evidence_id, {
question:
"Which managed members remain unmatched or ambiguous across these versions?",
severity: "medium",
domain: "managed-member-comparison",
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: "inspect_managed_members",
rationale:
"Review the inspection Evidence coverage and limit diagnostics; this operation has no page override, so unresolved members must remain unknown.",
},
],
relationships: [],
})
: undefined;
const output =
unknownInput === undefined
? options.recordEvidence?.(result.value.evidence)
: unknownInput.ok
? options.recordEvidenceWithUnknown?.(
result.value.evidence,
unknownInput.value,
)
: unknownInput;
return server.delivery.toEvidenceToolResult(
result.value.evidence,
compareContract,
output,
);
},
),
);
};
@@ -1,73 +0,0 @@
import type { EvidenceMcpServer } from "../EvidenceMcpServer.js";
import { runAdmittedToolOperation } from "../admittedToolOperation.js";
import { recordEvidenceSources } from "../../application/investigation/recordEvidenceSources.js";
import {
importManagedReconstructionEvidenceResolved,
resolveManagedReconstructionEvidenceInput,
} from "../../application/managed/ManagedReconstructionService.js";
import { logToolExecution } from "../toolLogging.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toolContract } from "../../contracts/toolContracts.js";
import type { ManagedWorkflowToolRegistration } from "./types.js";
const reconstructionContract = toolContract("import_managed_reconstruction");
/** Register the managed reconstruction import workflow tool. */
export const registerImportManagedReconstruction = (
server: EvidenceMcpServer,
options: ManagedWorkflowToolRegistration,
): void => {
server.registerTool(
reconstructionContract.name,
toolRegistrationOptions(reconstructionContract),
async (input, context) =>
runAdmittedToolOperation(
server,
options.withAdmittedAnalysis,
reconstructionContract.name,
context.mcpReq.signal,
async () => {
const resolved = resolveManagedReconstructionEvidenceInput(
input,
options.session.evidenceForAnalysis.bind(options.session),
{ signal: context.mcpReq.signal },
);
if (!resolved.ok)
return server.delivery.toCallToolResult(
resolved,
reconstructionContract,
);
const result = await logToolExecution(
options.logger,
reconstructionContract.name,
() =>
Promise.resolve(
importManagedReconstructionEvidenceResolved(resolved.value),
),
);
if (!result.ok)
return server.delivery.toCallToolResult(
result,
reconstructionContract,
);
const recordedSource = recordEvidenceSources(
options.recordEvidence,
[resolved.value.staticEvidence],
{ evidence: result.value },
);
if (!recordedSource.ok)
return server.delivery.toCallToolResult(
recordedSource,
reconstructionContract,
);
const recorded = options.recordEvidence?.(result.value);
return server.delivery.toEvidenceToolResult(
result.value,
reconstructionContract,
recorded,
);
},
),
);
};
@@ -1,71 +0,0 @@
import type { EvidenceMcpServer } from "../EvidenceMcpServer.js";
import { runAdmittedToolOperation } from "../admittedToolOperation.js";
import { recordEvidenceSources } from "../../application/investigation/recordEvidenceSources.js";
import {
projectManagedGraphEvidence,
resolveManagedGraphEvidenceInput,
} from "../../application/managed/ManagedApplicationGraphService.js";
import type { Evidence } from "../../domain/evidence.js";
import { ok } from "../../domain/result.js";
import { logToolExecution } from "../toolLogging.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toolContract } from "../../contracts/toolContracts.js";
import type { ManagedWorkflowToolRegistration } from "./types.js";
const graphContract = toolContract("project_managed_application_graph");
/** Register the managed application graph projection workflow tool. */
export const registerProjectManagedApplicationGraph = (
server: EvidenceMcpServer,
options: ManagedWorkflowToolRegistration,
): void => {
server.registerTool(
graphContract.name,
toolRegistrationOptions(graphContract),
async (input, context) =>
runAdmittedToolOperation(
server,
options.withAdmittedAnalysis,
graphContract.name,
context.mcpReq.signal,
async () => {
const request = resolveManagedGraphEvidenceInput(
input,
options.session.evidenceForAnalysis.bind(options.session),
{ signal: context.mcpReq.signal },
);
if (!request.ok)
return server.delivery.toCallToolResult(request, graphContract);
const result = await logToolExecution(
options.logger,
graphContract.name,
() =>
Promise.resolve(ok(projectManagedGraphEvidence(request.value))),
);
if (!result.ok)
return server.delivery.toCallToolResult(result, graphContract);
const recordedSources = recordEvidenceSources(
options.recordEvidence,
[
request.value.sources.artifact?.evidence,
request.value.sources.members?.evidence,
request.value.sources.boundaries?.evidence,
].filter((source): source is Evidence => source !== undefined),
{ evidence: result.value },
);
if (!recordedSources.ok)
return server.delivery.toCallToolResult(
recordedSources,
graphContract,
);
const recorded = options.recordEvidence?.(result.value);
return server.delivery.toEvidenceToolResult(
result.value,
graphContract,
recorded,
);
},
),
);
};
@@ -1,18 +0,0 @@
import type {
EvidenceWriter,
EvidenceUnknownWriter,
} from "../../application/investigation/InvestigationRecordPort.js";
import type { BinarySessionPort } from "../../application/binary/BinarySessionPort.js";
import type { Logger } from "pino";
import type { WithAdmittedAnalysis } from "../analysisAdmission.js";
/** Shared services for registering managed-code workflow tools. */
export interface ManagedWorkflowToolRegistration {
readonly withAdmittedAnalysis?: WithAdmittedAnalysis;
readonly logger: Logger;
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
readonly recordEvidenceWithUnknown:
| EvidenceUnknownWriter["recordEvidenceWithUnknown"]
| undefined;
readonly session: BinarySessionPort;
}
@@ -1,100 +0,0 @@
import { workflowUnknownInput } from "../../application/investigation/WorkflowUnknown.js";
import type { EvidenceMcpServer } from "../EvidenceMcpServer.js";
import { runAdmittedToolOperation } from "../admittedToolOperation.js";
import { recordEvidenceSources } from "../../application/investigation/recordEvidenceSources.js";
import { executeManagedNativeBoundaries } from "../../application/managed/ManagedNativeVerificationService.js";
import { logToolExecution } from "../toolLogging.js";
import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
import { toolContract } from "../../contracts/toolContracts.js";
import type { ManagedWorkflowToolRegistration } from "./types.js";
const nativeVerificationContract = toolContract(
"verify_managed_native_boundaries",
);
/** Register the managed/native boundary verification workflow tool. */
export const registerVerifyManagedNativeBoundaries = (
server: EvidenceMcpServer,
options: ManagedWorkflowToolRegistration,
): void => {
server.registerTool(
nativeVerificationContract.name,
toolRegistrationOptions(nativeVerificationContract),
async (input, context) =>
runAdmittedToolOperation(
server,
options.withAdmittedAnalysis,
nativeVerificationContract.name,
context.mcpReq.signal,
async () => {
const result = await logToolExecution(
options.logger,
nativeVerificationContract.name,
() =>
Promise.resolve(
executeManagedNativeBoundaries(
input,
options.session.evidenceForAnalysis.bind(options.session),
{ signal: context.mcpReq.signal },
),
),
);
if (!result.ok)
return server.delivery.toCallToolResult(
result,
nativeVerificationContract,
);
const execution = result.value;
const recordedSources = recordEvidenceSources(
options.recordEvidence,
execution.sourceEvidence,
{ evidence: execution.evidence },
);
if (!recordedSources.ok)
return server.delivery.toCallToolResult(
recordedSources,
nativeVerificationContract,
);
const unknownInput = execution.hasUnknowns
? workflowUnknownInput(execution.evidence.evidence_id, {
question:
"Which managed/native boundaries remain unresolved or contradicted by the supplied native Evidence?",
severity: "medium",
domain: "managed-native-verification",
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
recommended_probes: [
{
operation: "inspect_managed_native_boundaries",
rationale:
"Review the inspection Evidence coverage and limit diagnostics; this operation has no page override, so unresolved declarations must remain unknown.",
},
{
operation: "analyze_function",
rationale:
"Analyze the provider-resolved native function candidate for the declared export.",
},
],
relationships: [],
})
: undefined;
const output =
unknownInput === undefined
? options.recordEvidence?.(execution.evidence)
: unknownInput.ok
? options.recordEvidenceWithUnknown?.(
execution.evidence,
unknownInput.value,
)
: unknownInput;
return server.delivery.toEvidenceToolResult(
execution.evidence,
nativeVerificationContract,
output,
);
},
),
);
};
+73 -1
View File
@@ -54,6 +54,10 @@ import type { V8CodeCacheService } from "../application/v8CodeCache/V8CodeCacheS
import type { WasmArtifactService } from "../application/wasm/WasmArtifactService.js";
import { compareWasmInterfaces } from "../application/wasm/WasmInterfaceComparisonService.js";
import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";
import { projectManagedApplicationGraphExecution } from "../application/managed/ManagedApplicationGraphService.js";
import { compareManagedMembersExecution } from "../application/managed/ManagedMemberComparisonService.js";
import { verifyManagedNativeBoundariesExecution } from "../application/managed/ManagedNativeVerificationService.js";
import { importManagedReconstructionExecution } from "../application/managed/ManagedReconstructionService.js";
import { compareFunctionEvidence } from "../application/investigation/FunctionComparisonEvidence.js";
import { compareProcessEvidence } from "../application/process/ProcessComparisonService.js";
import {
@@ -89,6 +93,8 @@ import { traceApplicationFeatureEvidence } from "../application/javascript/JavaS
import { traceJavaScriptSemanticsEvidence } from "../application/javascript/JavaScriptSemanticTraceService.js";
import { compareStaticAndObservedEndpointsEvidence } from "../application/javascript/StaticObservedEndpointComparisonService.js";
import { inspectNtfsJournalEvidence } from "../application/ntfs/NtfsJournalService.js";
import { evaluateReconstructionCoverage } from "../application/ReconstructionCoverageService.js";
import { exportEnvironmentBundleTool } from "../application/environment/environmentBundleTool.js";
import { PlaywrightTraceService } from "../application/playwrightTrace/PlaywrightTraceService.js";
import { PlaywrightTraceDecoder } from "../browser/history/playwrightTrace/PlaywrightTraceDecoder.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
@@ -149,6 +155,10 @@ const requestedView = (input: {
}): AnalysisViewRequest | undefined =>
input.view ?? (input.detail === "summary" ? { kind: "summary" } : undefined);
const exportEnvironmentBundleContract = toolContract(
"export_environment_bundle",
);
/** A completed workflow that leaves no residual unknown. */
const settledResult = (
result: Result<EvidenceWorkflowExecution, AnalysisError>,
@@ -704,8 +714,43 @@ const SERVICE_TOOL_BINDINGS = {
},
},
})) satisfies Bind<SessionDerivedToolOptions>,
// Managed-code workflows derive from session-held managed and native
// Evidence; the CLI runs the same owners without a session.
managedWorkflows: ((session) => ({
compare_managed_members: {
admission: "sdk",
session,
derive: (input, evidenceForAnalysis, signal) =>
compareManagedMembersExecution(input, evidenceForAnalysis, { signal }),
},
verify_managed_native_boundaries: {
admission: "sdk",
session,
derive: (input, evidenceForAnalysis, signal) =>
verifyManagedNativeBoundariesExecution(input, evidenceForAnalysis, {
signal,
}),
},
import_managed_reconstruction: {
admission: "sdk",
session,
derive: (input, evidenceForAnalysis, signal) =>
importManagedReconstructionExecution(input, evidenceForAnalysis, {
signal,
}),
},
project_managed_application_graph: {
admission: "sdk",
session,
derive: (input, evidenceForAnalysis, signal) =>
projectManagedApplicationGraphExecution(input, evidenceForAnalysis, {
signal,
}),
},
})) satisfies Bind<BinarySessionPort>,
// Application workflows complete Evidence from session-held Evidence or
// caller-named files; a requested view or summary is staged against it.
// caller-named files under analysis admission; a requested view or summary
// is staged against it.
applicationWorkflows: (({ resources }, { evidenceById }) => {
const playwright = new PlaywrightTraceService(
new PlaywrightTraceDecoder(resources),
@@ -806,6 +851,33 @@ const SERVICE_TOOL_BINDINGS = {
projectHarmonyApplicationEvidence(input, evidenceById, { signal }),
),
},
// Plain results under the same admission as the workflows above.
evaluate_reconstruction_coverage: {
admission: "application",
admitted: true,
value: async (input) => evaluateReconstructionCoverage(input),
},
// The export validates its own request so refusals name the field.
export_environment_bundle: {
admission: "application",
admitted: true,
value: async (rawInput, { signal }) => {
const parsed =
exportEnvironmentBundleContract.inputSchema.safeParse(rawInput);
return parsed.success
? exportEnvironmentBundleTool(parsed.data, evidenceById, {
signal,
})
: err(
analysisInputErrorFromIssues(
exportEnvironmentBundleContract.name,
parsed.error.issues,
rawInput,
{ cause: parsed.error },
),
);
},
},
};
}) satisfies Bind<ApplicationWorkflowToolOptions>,
sessionStatus: ((options) => ({
@@ -94,6 +94,56 @@ mcpTest(
},
);
mcpTest(
"runs a value binding under analysis admission only when it declares it",
async ({ mcp }) => {
const ran: string[] = [];
const admitted: string[] = [];
const refusal = (operation: string) =>
new AnalysisInputError(operation, undefined, [
{ path: [], reason: "invalid_value", message: `${operation} refusal` },
]);
const value = (operation: string) => () => {
ran.push(operation);
return Promise.resolve(err(refusal(operation)));
};
const server = evidenceServer();
registerContractTools(
server,
{
evaluate_reconstruction_coverage: {
admission: "application",
admitted: true,
value: value("evaluate_reconstruction_coverage"),
},
search_guidance: {
admission: "application",
value: value("search_guidance"),
},
},
{
logger: silentLogger,
withAdmittedAnalysis: async (operationName) => {
admitted.push(operationName);
return err(refusal("admission"));
},
},
);
const client = await mcp.connect(server);
const call = async (name: string) =>
parseMcpToolError(await client.callTool({ name, arguments: {} }));
expect(await call("evaluate_reconstruction_coverage")).toMatchObject({
error: { details: { operation: "admission" } },
});
expect(await call("search_guidance")).toMatchObject({
error: { details: { operation: "search_guidance" } },
});
expect(admitted).toEqual(["evaluate_reconstruction_coverage"]);
expect(ran).toEqual(["search_guidance"]);
},
);
type Operation = () => Promise<never>;
type DevicetreeBinding = NonNullable<
ContractToolBindings["inspect_devicetree"]
@@ -92,9 +92,9 @@ it.each([
kind: "unretained-evidence",
evidence: source,
},
// The session owner reads the session, so retention is known.
completed_observation: {
kind: "inline-evidence",
retention: "unknown",
kind: "unretained-evidence",
source_closure: "not-established",
evidence: { operation: name, evidence_links: [source.evidence_id] },
},