diff --git a/scripts/verify/baselines/bespoke-mcp-tool-registration.json b/scripts/verify/baselines/bespoke-mcp-tool-registration.json index 2e10bce629..fafacfc92c 100644 --- a/scripts/verify/baselines/bespoke-mcp-tool-registration.json +++ b/scripts/verify/baselines/bespoke-mcp-tool-registration.json @@ -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, diff --git a/src/application/managed/ManagedApplicationGraphService.ts b/src/application/managed/ManagedApplicationGraphService.ts index 7c48862e99..1c39e1c7c7 100644 --- a/src/application/managed/ManagedApplicationGraphService.ts +++ b/src/application/managed/ManagedApplicationGraphService.ts @@ -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 = {}, +): Result => { + 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 = {}, ): Result => { - 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 = {}, @@ -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( diff --git a/src/application/managed/ManagedMemberComparisonService.ts b/src/application/managed/ManagedMemberComparisonService.ts index d2b18ad76a..540dd5688e 100644 --- a/src/application/managed/ManagedMemberComparisonService.ts +++ b/src/application/managed/ManagedMemberComparisonService.ts @@ -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, +): Result => { + 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, diff --git a/src/application/managed/ManagedNativeVerificationService.ts b/src/application/managed/ManagedNativeVerificationService.ts index f13698e159..8547d8c6d0 100644 --- a/src/application/managed/ManagedNativeVerificationService.ts +++ b/src/application/managed/ManagedNativeVerificationService.ts @@ -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, +): Result => { + 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, diff --git a/src/application/managed/ManagedReconstructionService.ts b/src/application/managed/ManagedReconstructionService.ts index a30f880909..d7ba3f091c 100644 --- a/src/application/managed/ManagedReconstructionService.ts +++ b/src/application/managed/ManagedReconstructionService.ts @@ -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 = {}, @@ -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 => { - 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 = {}, +): Result => { + 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 = {}, ): Result => { - 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 = ( diff --git a/src/server/contractToolBindings.ts b/src/server/contractToolBindings.ts index 17afe82462..b1b0bbbdbf 100644 --- a/src/server/contractToolBindings.ts +++ b/src/server/contractToolBindings.ts @@ -105,11 +105,14 @@ type ValueOperation = ( /** * 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 = +type ValueBinding = { + readonly admitted?: true; +} & ( | { readonly admission: "sdk"; readonly value: ValueOperation; @@ -127,7 +130,8 @@ type ValueBinding = 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, diff --git a/src/server/contractToolHandler.ts b/src/server/contractToolHandler.ts index 11c7a765c1..5bf4899b44 100644 --- a/src/server/contractToolHandler.ts +++ b/src/server/contractToolHandler.ts @@ -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>, logger: Logger, + withAdmittedAnalysis?: WithAdmittedAnalysis, ) => (contract: ToolContract) => async (input: unknown, context: ServerContext): Promise => - 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. */ diff --git a/src/server/createServer.ts b/src/server/createServer.ts index 8e8fd0e855..428823332c 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -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: () => { diff --git a/src/server/registerApplicationTools.ts b/src/server/registerApplicationTools.ts deleted file mode 100644 index 916c8c68ac..0000000000 --- a/src/server/registerApplicationTools.ts +++ /dev/null @@ -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); -}; diff --git a/src/server/registerApplicationTools/coverage.ts b/src/server/registerApplicationTools/coverage.ts deleted file mode 100644 index 53d24c0cf7..0000000000 --- a/src/server/registerApplicationTools/coverage.ts +++ /dev/null @@ -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); - }, - ), - ); -}; diff --git a/src/server/registerApplicationTools/environmentBundle.ts b/src/server/registerApplicationTools/environmentBundle.ts deleted file mode 100644 index 45de5f847d..0000000000 --- a/src/server/registerApplicationTools/environmentBundle.ts +++ /dev/null @@ -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); - }, - ), - ); -}; diff --git a/src/server/registerApplicationTools/types.ts b/src/server/registerApplicationTools/types.ts deleted file mode 100644 index c59d12cf9c..0000000000 --- a/src/server/registerApplicationTools/types.ts +++ /dev/null @@ -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; -} diff --git a/src/server/registerManagedWorkflowTools.ts b/src/server/registerManagedWorkflowTools.ts deleted file mode 100644 index 096ab99271..0000000000 --- a/src/server/registerManagedWorkflowTools.ts +++ /dev/null @@ -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); -}; diff --git a/src/server/registerManagedWorkflowTools/compareManagedMembers.ts b/src/server/registerManagedWorkflowTools/compareManagedMembers.ts deleted file mode 100644 index 046dbeb958..0000000000 --- a/src/server/registerManagedWorkflowTools/compareManagedMembers.ts +++ /dev/null @@ -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, - ); - }, - ), - ); -}; diff --git a/src/server/registerManagedWorkflowTools/importManagedReconstruction.ts b/src/server/registerManagedWorkflowTools/importManagedReconstruction.ts deleted file mode 100644 index c769e2ca96..0000000000 --- a/src/server/registerManagedWorkflowTools/importManagedReconstruction.ts +++ /dev/null @@ -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, - ); - }, - ), - ); -}; diff --git a/src/server/registerManagedWorkflowTools/projectManagedApplicationGraph.ts b/src/server/registerManagedWorkflowTools/projectManagedApplicationGraph.ts deleted file mode 100644 index 85f2d64301..0000000000 --- a/src/server/registerManagedWorkflowTools/projectManagedApplicationGraph.ts +++ /dev/null @@ -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, - ); - }, - ), - ); -}; diff --git a/src/server/registerManagedWorkflowTools/types.ts b/src/server/registerManagedWorkflowTools/types.ts deleted file mode 100644 index f66ab56fc0..0000000000 --- a/src/server/registerManagedWorkflowTools/types.ts +++ /dev/null @@ -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; -} diff --git a/src/server/registerManagedWorkflowTools/verifyManagedNativeBoundaries.ts b/src/server/registerManagedWorkflowTools/verifyManagedNativeBoundaries.ts deleted file mode 100644 index bc738f6ec2..0000000000 --- a/src/server/registerManagedWorkflowTools/verifyManagedNativeBoundaries.ts +++ /dev/null @@ -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, - ); - }, - ), - ); -}; diff --git a/src/server/serviceToolBindings.ts b/src/server/serviceToolBindings.ts index ccae34e312..c190ec51e6 100644 --- a/src/server/serviceToolBindings.ts +++ b/src/server/serviceToolBindings.ts @@ -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, @@ -704,8 +714,43 @@ const SERVICE_TOOL_BINDINGS = { }, }, })) satisfies Bind, + // 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, // 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, sessionStatus: ((options) => ({ diff --git a/tests/boundary/mcp/contractToolBindings.test.ts b/tests/boundary/mcp/contractToolBindings.test.ts index cd38d7a97e..564b92c34e 100644 --- a/tests/boundary/mcp/contractToolBindings.test.ts +++ b/tests/boundary/mcp/contractToolBindings.test.ts @@ -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; type DevicetreeBinding = NonNullable< ContractToolBindings["inspect_devicetree"] diff --git a/tests/boundary/mcp/managedEvidenceReferencesMcp.test.ts b/tests/boundary/mcp/managedEvidenceReferencesMcp.test.ts index 72169a6407..5350ccc91c 100644 --- a/tests/boundary/mcp/managedEvidenceReferencesMcp.test.ts +++ b/tests/boundary/mcp/managedEvidenceReferencesMcp.test.ts @@ -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] }, },