diff --git a/scripts/verify/baselines/bespoke-mcp-tool-registration.json b/scripts/verify/baselines/bespoke-mcp-tool-registration.json index bf6116b951..f485603bac 100644 --- a/scripts/verify/baselines/bespoke-mcp-tool-registration.json +++ b/scripts/verify/baselines/bespoke-mcp-tool-registration.json @@ -12,11 +12,9 @@ "src/server/registerApplicationTools/projectMobileApplicationGraph.ts": 1, "src/server/registerApplicationTools/traceFeature.ts": 1, "src/server/registerApplicationTools/traceSemantics.ts": 1, - "src/server/registerArtifactComparisonTool.ts": 1, "src/server/registerBinaryDiagnosticsTools.ts": 1, "src/server/registerBrowserScenarioTool.ts": 1, "src/server/registerBrowserTools.ts": 8, - "src/server/registerBundleComparisonTool.ts": 1, "src/server/registerCloseLifecycleTool.ts": 1, "src/server/registerCutterTools.ts": 1, "src/server/registerDesktopBuildTools.ts": 2, diff --git a/src/application/artifacts/ArtifactComparisonEvidence.ts b/src/application/artifacts/ArtifactComparisonEvidence.ts index 8abf7002ec..252cdbe65b 100644 --- a/src/application/artifacts/ArtifactComparisonEvidence.ts +++ b/src/application/artifacts/ArtifactComparisonEvidence.ts @@ -33,6 +33,8 @@ import { sameTargetIdentity, unknownTarget, } from "../../domain/targetIdentity.js"; +import type { RecordUnknownInput } from "../../domain/residualUnknown.js"; +import type { InvestigationWorkflowExecution } from "../investigation/InvestigationWorkflows.js"; const OPERATION = "compare_artifacts"; @@ -199,3 +201,65 @@ const mismatch = (): Result => `Artifact summary does not match its retained parent inventory. A summary from an earlier Evidence format no longer matches. ${RECREATE_EVIDENCE_GUIDANCE}`, ), ); + +/** + * Compare resolved inventories for a session: the derived Evidence, both + * sources to retain, and the residual question a changed, unknown or + * truncated comparison leaves. + */ +export const artifactComparisonExecution = ( + sources: ArtifactComparisonSources, +): Result => { + const compared = compareArtifactEvidence(sources); + if (!compared.ok) return compared; + const { left, right } = sources; + const { comparison, evidence } = compared.value; + return ok({ + evidence, + sources: [left, right], + unknown: artifactUnknownInput( + left, + right, + comparison, + evidence.evidence_id, + ), + }); +}; + +const artifactUnknownInput = ( + left: { readonly evidence_id: string }, + right: { readonly evidence_id: string }, + comparison: ArtifactComparisonResult, + comparisonEvidenceId: string, +): RecordUnknownInput | undefined => { + const { status } = comparison; + if (status === "unchanged") return undefined; + const sourceIds = [...new Set([left.evidence_id, right.evidence_id])]; + const contradictingIds = comparison.integrity_mismatch_evidence_ids ?? []; + const contentContradictions = + status === "changed" && left.evidence_id !== right.evidence_id + ? [right.evidence_id] + : []; + const contradictions = + contradictingIds.length > 0 ? contradictingIds : contentContradictions; + return { + question: `Artifact comparison is ${status} (comparison ${comparisonEvidenceId})`, + severity: + status === "unknown" || status === "truncated" ? "high" : "medium", + domain: "artifact-comparison", + supporting_evidence_ids: sourceIds.filter( + (id) => !contradictions.includes(id), + ), + contradicting_evidence_ids: contradictions, + required_authority: "shipped-artifact", + required_confidence: "observed", + required_environment: null, + recommended_probes: [ + { + operation: "inspect_artifact", + rationale: "Inspect both artifacts and compare their complete graphs.", + }, + ], + relationships: [], + }; +}; diff --git a/src/application/investigation/BundleComparisonEvidence.test.ts b/src/application/investigation/BundleComparisonEvidence.test.ts new file mode 100644 index 0000000000..dd11cacef3 --- /dev/null +++ b/src/application/investigation/BundleComparisonEvidence.test.ts @@ -0,0 +1,43 @@ +import { expect, it } from "vitest"; + +import { AnalysisInputError } from "../../domain/analysisErrorCore.js"; +import { createEvidence } from "../../domain/evidence.js"; +import { createEvidenceBundle } from "../../domain/evidenceBundle.js"; +import { unknownTarget } from "../../domain/targetIdentity.js"; +import { bundleComparisonExecution } from "./BundleComparisonEvidence.js"; + +const PROVIDER = { id: "fixture", name: "Fixture", version: "1" } as const; +const evidence = (label: string) => + createEvidence(unknownTarget("not-observed"), PROVIDER, { + operation: "observe", + parameters: { label }, + result: { label }, + confidence: "derived", + authority: "analyst-inference", + }); + +it("returns a missing record pair as a typed input failure", () => { + const leftRecord = evidence("left"); + const rightRecord = evidence("right"); + const left = createEvidenceBundle([leftRecord]); + const right = createEvidenceBundle([rightRecord]); + const failed = bundleComparisonExecution({ + left, + right, + recordPairs: [ + { + left_evidence_id: evidence("missing").evidence_id, + right_evidence_id: rightRecord.evidence_id, + }, + ], + }); + expect(failed.ok).toBe(false); + if (failed.ok) throw new Error("Expected a failure"); + expect(failed.error).toBeInstanceOf(AnalysisInputError); + const compared = bundleComparisonExecution({ left, right, recordPairs: [] }); + if (!compared.ok) throw compared.error; + expect(compared.value.sources).toEqual([leftRecord, rightRecord]); + expect(compared.value.evidence.evidence_links).toEqual( + expect.arrayContaining([leftRecord.evidence_id, rightRecord.evidence_id]), + ); +}); diff --git a/src/application/investigation/BundleComparisonEvidence.ts b/src/application/investigation/BundleComparisonEvidence.ts new file mode 100644 index 0000000000..4d360482ed --- /dev/null +++ b/src/application/investigation/BundleComparisonEvidence.ts @@ -0,0 +1,100 @@ +import { bundleComparisonMcpInputSchema } from "../../contracts/sessionToolSchemas.js"; +import { AnalysisError } from "../../domain/analysisErrorBase.js"; +import { compareBundles } from "../../domain/bundleComparison.js"; +import { createEvidence } from "../../domain/evidence.js"; +import type { EvidenceBundle } from "../../domain/evidenceBundle.js"; +import { BUNDLE_COMPARISON_PROVIDER } from "../../domain/investigationProviders.js"; +import { err, ok, type Result } from "../../domain/result.js"; +import { unknownTarget } from "../../domain/targetIdentity.js"; +import type { ArtifactResourceScope } from "../../resources/index.js"; +import { parseAnalysisInput } from "../AnalysisInput.js"; +import { readComparisonEvidenceBundles } from "../EvidenceBundleFiles.js"; +import type { InvestigationWorkflowExecution } from "./InvestigationWorkflows.js"; + +const OPERATION = "compare_bundles"; + +/** Both bundles a session comparison reads, and the pairs the caller declared. */ +export interface BundleComparisonSources { + readonly left: EvidenceBundle; + readonly right: EvidenceBundle; + readonly recordPairs: Parameters[2]; +} + +/** + * Read both caller-named bundles under the resource scope. The bundle reader + * opens and releases each file in that scope, which keeps a handle whose + * release failed for a later cleanup retry. + */ +export const readBundleComparisonSources = async ( + input: unknown, + options: { + readonly signal: AbortSignal; + readonly resources: ArtifactResourceScope; + }, +): Promise> => { + const request = parseAnalysisInput( + OPERATION, + input, + bundleComparisonMcpInputSchema, + options.signal, + ); + if (!request.ok) return request; + const loaded = await readComparisonEvidenceBundles( + request.value.left_bundle_path, + request.value.right_bundle_path, + options.signal, + options.resources, + OPERATION, + ); + if (!loaded.ok) return loaded; + return ok({ ...loaded.value, recordPairs: request.value.record_pairs }); +}; + +/** + * Compare two bundles for a session. Every record of either bundle is a + * source the session retains, and the derived Evidence links each one. + */ +export const bundleComparisonExecution = ({ + left, + right, + recordPairs, +}: BundleComparisonSources): Result< + InvestigationWorkflowExecution, + AnalysisError +> => { + let comparison: ReturnType; + try { + comparison = compareBundles(left, right, recordPairs); + } catch (cause: unknown) { + // Missing or repeated record pairs are typed input failures. + if (cause instanceof AnalysisError) return err(cause); + throw cause; + } + const sources = [ + ...new Map( + [...left.records, ...right.records].map((record) => [ + record.evidence_id, + record, + ]), + ).values(), + ]; + const evidence = createEvidence( + unknownTarget("derived-from-linked-evidence"), + BUNDLE_COMPARISON_PROVIDER, + { + predicateType: "rea.bundle-comparison", + operation: OPERATION, + parameters: { + left_bundle_sha256: comparison.left_bundle_sha256, + right_bundle_sha256: comparison.right_bundle_sha256, + record_pairs: recordPairs, + }, + result: comparison, + confidence: "derived", + authority: "analyst-inference", + limitations: comparison.limitations, + evidenceLinks: sources.map(({ evidence_id }) => evidence_id), + }, + ); + return ok({ evidence, sources, unknown: undefined }); +}; diff --git a/src/server/contractToolBindings.ts b/src/server/contractToolBindings.ts index 08db01b1b4..d666951ddc 100644 --- a/src/server/contractToolBindings.ts +++ b/src/server/contractToolBindings.ts @@ -12,12 +12,15 @@ import type { AnalysisError } from "../domain/analysisErrorBase.js"; import type { Evidence } from "../domain/evidence.js"; import type { JsonValue } from "../domain/jsonValue.js"; import { invariantViolation } from "../domain/internalInvariant.js"; -import type { Result } from "../domain/result.js"; +import { ok, type Result } from "../domain/result.js"; import type { WithAdmittedAnalysis } from "./analysisAdmission.js"; import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js"; import type { InvestigationWorkflowExecution } from "../application/investigation/InvestigationWorkflows.js"; +import type { ArtifactResourceScope } from "../resources/index.js"; import { createDerivedToolHandler, + type DerivedAcquisition, + type DerivedSources, createEvidenceToolHandler, createRetainedSummaryToolHandler, createValueToolHandler, @@ -69,6 +72,7 @@ type EvidenceBinding = ( readonly summary?: never; readonly value?: never; readonly derive?: never; + readonly acquire?: never; } | { readonly admission: "application"; @@ -76,6 +80,7 @@ type EvidenceBinding = ( readonly summary?: never; readonly value?: never; readonly derive?: never; + readonly acquire?: never; } ) & { /** @@ -103,6 +108,7 @@ type ValueBinding = readonly run?: never; readonly summary?: never; readonly derive?: never; + readonly acquire?: never; } | { readonly admission: "application"; @@ -110,6 +116,7 @@ type ValueBinding = readonly run?: never; readonly summary?: never; readonly derive?: never; + readonly acquire?: never; }; /** @@ -119,19 +126,41 @@ type ValueBinding = * Evidence is recorded with its unknowns, as for every session workflow. * The workflow validates its own request, so it receives the input as the * selected admission delivers it. + * + * A derivation that also reads caller-named files (artifact inventories, + * Evidence bundles) declares the artifact resource scope it reads them + * under and `acquire`s them before deriving: the readers open and release + * every handle in that scope, which keeps any handle whose release failed + * for a later cleanup retry. An acquisition failure is delivered as is, + * before the derivation starts. */ -interface DerivedBinding { +type DerivedBinding = { readonly admission: ContractInputAdmission; readonly session: BinarySessionPort; - readonly derive: ( - input: unknown, - evidenceForAnalysis: BinarySessionPort["evidenceForAnalysis"], - signal: AbortSignal, - ) => Result; readonly run?: never; readonly summary?: never; readonly value?: never; -} +} & ( + | { + readonly derive: ( + input: unknown, + evidenceForAnalysis: BinarySessionPort["evidenceForAnalysis"], + signal: AbortSignal, + ) => Result; + readonly acquire?: never; + readonly resources?: never; + } + | { + readonly resources: ArtifactResourceScope; + readonly acquire: ( + input: unknown, + sources: DerivedSources & { + readonly resources: ArtifactResourceScope; + }, + ) => ReturnType; + readonly derive?: never; + } +); /** * Admit `detail`/`view` in the adapter, run the workflow on the remaining @@ -143,6 +172,7 @@ interface RetainedSummaryBinding { readonly run?: never; readonly value?: never; readonly derive?: never; + readonly acquire?: never; } /** How one named contract runs over MCP; only summary-capable contracts take `summary`. */ @@ -169,6 +199,17 @@ export interface ContractToolDependencies { readonly withAdmittedAnalysis?: WithAdmittedAnalysis | undefined; } +/** A session-only derivation acquires nothing; it derives from session-held Evidence. */ +const derivedAcquisition = (binding: DerivedBinding): DerivedAcquisition => { + if (binding.acquire !== undefined) { + const { acquire, resources } = binding; + return (input, sources) => acquire(input, { ...sources, resources }); + } + const { derive } = binding; + return async (input, { evidenceForAnalysis, signal }) => + ok(() => derive(input, evidenceForAnalysis, signal)); +}; + /** Bind every named operation of one contract service with one admission. */ export const contractServiceBindings = ( service: ContractToolService, @@ -232,11 +273,11 @@ export const registerContractTools = ( const handler = binding.value !== undefined ? createValueToolHandler(server, binding.value, logger)(contract) - : binding.derive !== undefined + : binding.derive !== undefined || binding.acquire !== undefined ? createDerivedToolHandler( server, binding.session, - binding.derive, + derivedAcquisition(binding), logger, )(contract) : binding.run !== undefined diff --git a/src/server/contractToolHandler.ts b/src/server/contractToolHandler.ts index 5cdff71821..bce4495bc6 100644 --- a/src/server/contractToolHandler.ts +++ b/src/server/contractToolHandler.ts @@ -201,21 +201,38 @@ export const createValueToolHandler = contract, ); +/** What a derivation may read before it runs. */ +export interface DerivedSources { + readonly evidenceForAnalysis: BinarySessionPort["evidenceForAnalysis"]; + readonly signal: AbortSignal; +} + /** - * Derive Evidence from Evidence the session holds. The session owner admits - * the call, resolves its session-held inputs, retains the sources the - * derivation read and records the derived Evidence with its unknowns, so - * provenance is the same whichever tool derives it. + * Read a derivation's inputs, then return the synchronous derivation over + * them. A derivation from session-held Evidence alone acquires nothing. + */ +export type DerivedAcquisition = ( + input: unknown, + sources: DerivedSources, +) => Promise< + Result< + () => Result, + AnalysisError + > +>; + +/** + * Derive Evidence from Evidence the session holds and the inputs the binding + * acquires. The session owner admits the call, resolves its session-held + * inputs, retains the sources the derivation read and records the derived + * Evidence with its unknowns, so provenance is the same whichever tool + * derives it. An acquisition failure is delivered as is. */ export const createDerivedToolHandler = ( server: EvidenceMcpServer, session: BinarySessionPort, - derive: ( - input: unknown, - evidenceForAnalysis: BinarySessionPort["evidenceForAnalysis"], - signal: AbortSignal, - ) => Result, + acquire: DerivedAcquisition, logger: Logger, ) => (contract: ToolContract) => { @@ -230,28 +247,35 @@ export const createDerivedToolHandler = admission, contract.name, context.mcpReq.signal, - async () => - deliverInvestigationWorkflow( - server, - session, - contract, - await logToolExecution(logger, contract.name, () => - runDerivedOperation( + async () => { + const outcome = await logToolExecution( + logger, + contract.name, + async () => { + const acquired = await acquire(input, { + evidenceForAnalysis, + signal: context.mcpReq.signal, + }); + if (!acquired.ok) + return { ...acquired, stage: "acquire" as const }; + const derive = acquired.value; + const derived = await runDerivedOperation( context, contract.name, () => { - const result = derive( - input, - evidenceForAnalysis, - context.mcpReq.signal, - ); + const result = derive(); if (!result.ok) throw result.error; return result.value; }, (value) => value, - ), - ), - ), + ); + return { ...derived, stage: "derive" as const }; + }, + ); + return outcome.stage === "acquire" + ? server.delivery.toCallToolResult(outcome, contract) + : deliverInvestigationWorkflow(server, session, contract, outcome); + }, ); }; diff --git a/src/server/registerArtifactComparisonTool.ts b/src/server/registerArtifactComparisonTool.ts deleted file mode 100644 index 250711bbf2..0000000000 --- a/src/server/registerArtifactComparisonTool.ts +++ /dev/null @@ -1,139 +0,0 @@ -import type { EvidenceMcpServer } from "./EvidenceMcpServer.js"; - -import type { ArtifactResourceScope } from "../resources/index.js"; -import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js"; -import { toolContract } from "../contracts/toolContracts.js"; -import type { ArtifactComparisonResult } from "../domain/artifactComparison.js"; -import { - compareArtifactEvidence, - resolveArtifactComparisonSources, -} from "../application/artifacts/ArtifactComparisonEvidence.js"; -import type { RecordUnknownInput } from "../domain/residualUnknown.js"; -import { recordDerivedEvidence } from "./recordDerivedEvidence.js"; -import { runDerivedOperation } from "./runDerivedOperation.js"; -import { applicationToolRegistrationOptions } from "./toolRegistrationOptions.js"; -import { withAdmittedAnalysis } from "./analysisAdmission.js"; -import { runAdmittedToolOperation } from "./admittedToolOperation.js"; -import { - recordEvidenceSources, - retainAnalysisResultSources, -} from "../application/investigation/recordEvidenceSources.js"; - -/** Register Evidence-backed deterministic artifact comparison. */ -export const registerArtifactComparisonTool = ( - server: EvidenceMcpServer, - session: BinarySessionPort, - contract: ReturnType>, - resources: ArtifactResourceScope, -): void => { - const admission = withAdmittedAnalysis({ kind: "session", session }); - const evidenceById = session.evidenceForAnalysis.bind(session); - server.registerTool( - contract.name, - applicationToolRegistrationOptions(contract), - async (input, context) => - runAdmittedToolOperation( - server, - admission, - contract.name, - context.mcpReq.signal, - async () => { - const sources = await resolveArtifactComparisonSources( - input, - evidenceById, - { signal: context.mcpReq.signal, resources }, - ); - if (!sources.ok) - return server.delivery.toCallToolResult(sources, contract); - const computed = await runDerivedOperation( - context, - contract.name, - () => { - const compared = compareArtifactEvidence(sources.value); - if (!compared.ok) throw compared.error; - return compared.value; - }, - (value) => ({ - evidence: value.evidence, - sources: [sources.value.left, sources.value.right], - }), - ); - const completed = retainAnalysisResultSources( - contract.name, - session.recordEvidence.bind(session), - computed, - ); - if (!completed.ok) - return server.delivery.toPartialErrorToolResult( - completed.error, - contract.returnsTargetContent, - session.recordEvidence.bind(session), - ); - const { left, right } = sources.value; - const { comparison, evidence } = completed.value; - const recordedSources = recordEvidenceSources( - (source) => session.recordEvidence(source), - [left, right], - { - evidence, - evidenceForAnalysis: session.evidenceForAnalysis.bind(session), - }, - ); - if (!recordedSources.ok) - return server.delivery.toCallToolResult(recordedSources, contract); - return server.delivery.toEvidenceToolResult( - evidence, - contract, - recordDerivedEvidence( - session, - evidence, - artifactUnknownInput( - left, - right, - comparison, - evidence.evidence_id, - ), - ), - ); - }, - ), - ); -}; - -const artifactUnknownInput = ( - left: { readonly evidence_id: string }, - right: { readonly evidence_id: string }, - comparison: ArtifactComparisonResult, - comparisonEvidenceId: string, -): RecordUnknownInput | undefined => { - const { status } = comparison; - if (status === "unchanged") return undefined; - const sourceIds = [...new Set([left.evidence_id, right.evidence_id])]; - const contradictingIds = comparison.integrity_mismatch_evidence_ids ?? []; - const contentContradictions = - status === "changed" && left.evidence_id !== right.evidence_id - ? [right.evidence_id] - : []; - const contradictions = - contradictingIds.length > 0 ? contradictingIds : contentContradictions; - return { - question: `Artifact comparison is ${status} (comparison ${comparisonEvidenceId})`, - severity: - status === "unknown" || status === "truncated" ? "high" : "medium", - domain: "artifact-comparison", - supporting_evidence_ids: sourceIds.filter( - (id) => !contradictions.includes(id), - ), - contradicting_evidence_ids: contradictions, - required_authority: "shipped-artifact", - required_confidence: "observed", - required_environment: null, - recommended_probes: [ - { - operation: "inspect_artifact", - rationale: "Inspect both artifacts and compare their complete graphs.", - }, - ], - relationships: [], - }; -}; diff --git a/src/server/registerBundleComparisonTool.ts b/src/server/registerBundleComparisonTool.ts deleted file mode 100644 index b51294f62b..0000000000 --- a/src/server/registerBundleComparisonTool.ts +++ /dev/null @@ -1,96 +0,0 @@ -import { unknownTarget } from "../domain/targetIdentity.js"; -import type { EvidenceMcpServer } from "./EvidenceMcpServer.js"; - -import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js"; -import { readComparisonEvidenceBundles } from "../application/EvidenceBundleFiles.js"; -import { toolContract } from "../contracts/toolContracts.js"; -import { compareBundles } from "../domain/bundleComparison.js"; -import { createEvidence } from "../domain/evidence.js"; -import { runDerivedOperation } from "./runDerivedOperation.js"; -import { recordEvidenceSources } from "../application/investigation/recordEvidenceSources.js"; -import { BUNDLE_COMPARISON_PROVIDER } from "../domain/investigationProviders.js"; -import { toolRegistrationOptions } from "./toolRegistrationOptions.js"; -import { withAdmittedAnalysis } from "./analysisAdmission.js"; -import { runAdmittedToolOperation } from "./admittedToolOperation.js"; -import type { ArtifactResourceScope } from "../resources/index.js"; - -/** Register canonical Evidence bundle comparison. */ -export const registerBundleComparisonTool = ( - server: EvidenceMcpServer, - session: BinarySessionPort, - contract: ReturnType>, - resources: ArtifactResourceScope, -): void => { - const admission = withAdmittedAnalysis({ kind: "session", session }); - server.registerTool( - contract.name, - toolRegistrationOptions(contract), - async (input, context) => - runAdmittedToolOperation( - server, - admission, - contract.name, - context.mcpReq.signal, - async () => { - const loaded = await readComparisonEvidenceBundles( - input.left_bundle_path, - input.right_bundle_path, - context.mcpReq.signal, - resources, - contract.name, - ); - if (!loaded.ok) - return server.delivery.toCallToolResult(loaded, contract); - const { left, right } = loaded.value; - const computed = await runDerivedOperation( - context, - contract.name, - () => compareBundles(left, right, input.record_pairs), - ); - if (!computed.ok) - return server.delivery.toCallToolResult(computed, contract); - const comparison = computed.value; - const sourceRecords = [ - ...new Map( - [...left.records, ...right.records].map((record) => [ - record.evidence_id, - record, - ]), - ).values(), - ]; - const recordedSources = recordEvidenceSources( - (evidence) => session.recordEvidence(evidence), - sourceRecords, - ); - if (!recordedSources.ok) - return server.delivery.toCallToolResult(recordedSources, contract); - const evidence = createEvidence( - unknownTarget("derived-from-linked-evidence"), - BUNDLE_COMPARISON_PROVIDER, - { - predicateType: "rea.bundle-comparison", - operation: contract.name, - parameters: { - left_bundle_sha256: comparison.left_bundle_sha256, - right_bundle_sha256: comparison.right_bundle_sha256, - record_pairs: input.record_pairs, - }, - result: comparison, - confidence: "derived", - authority: "analyst-inference", - limitations: comparison.limitations, - evidenceLinks: sourceRecords.map( - ({ evidence_id }) => evidence_id, - ), - }, - ); - const recorded = session.recordEvidence(evidence); - return server.delivery.toEvidenceToolResult( - evidence, - contract, - recorded, - ); - }, - ), - ); -}; diff --git a/src/server/registerSessionTools.ts b/src/server/registerSessionTools.ts index 52898e81ce..267274d6ba 100644 --- a/src/server/registerSessionTools.ts +++ b/src/server/registerSessionTools.ts @@ -29,8 +29,6 @@ import { err, ok, type Result } from "../domain/result.js"; import type { Logger } from "pino"; import type { ProviderAvailability } from "../ports/AnalysisProvider.js"; import { mcpProgressReporter } from "./mcpProgress.js"; -import { registerArtifactComparisonTool } from "./registerArtifactComparisonTool.js"; -import { registerBundleComparisonTool } from "./registerBundleComparisonTool.js"; import { registerCloseLifecycleTool } from "./registerCloseLifecycleTool.js"; import { registerResetInvestigationTool } from "./registerResetInvestigationTool.js"; import { @@ -344,8 +342,6 @@ export const registerSessionTools = ( const exportContract = toolContract("export_evidence_bundle"); const importContract = toolContract("import_evidence_bundle"); const captureContract = toolContract("capture_process_scenario"); - const compareArtifactsContract = toolContract("compare_artifacts"); - const compareBundlesContract = toolContract("compare_bundles"); const snapshotContract = toolContract("get_evidence_bundle"); const processResources = new ProcessCaptureResourceScope(); server.registerTool( @@ -464,12 +460,12 @@ export const registerSessionTools = ( }); } }; - registerServiceTools(server, { sessionDerived: session }, { logger }); - registerArtifactComparisonTool( + registerServiceTools( server, - session, - compareArtifactsContract, - options.artifactResources, + { + sessionDerived: { session, resources: options.artifactResources }, + }, + { logger }, ); registerNativeFunctionMatchingTool( server, @@ -477,12 +473,6 @@ export const registerSessionTools = ( logger, options.environment, ); - registerBundleComparisonTool( - server, - session, - compareBundlesContract, - options.artifactResources, - ); registerUnknownTools({ server, session }); registerContextTools(server, session); }; diff --git a/src/server/serviceToolBindings.ts b/src/server/serviceToolBindings.ts index 57cc1b2d6c..2c21a069f8 100644 --- a/src/server/serviceToolBindings.ts +++ b/src/server/serviceToolBindings.ts @@ -62,6 +62,14 @@ import { findChangedBehaviorEvidence, verifyReconstructionEvidence, } from "../application/investigation/InvestigationWorkflows.js"; +import { + artifactComparisonExecution, + resolveArtifactComparisonSources, +} from "../application/artifacts/ArtifactComparisonEvidence.js"; +import { + bundleComparisonExecution, + readBundleComparisonSources, +} from "../application/investigation/BundleComparisonEvidence.js"; import type { WebModuleTraceService } from "../application/WebModuleTraceService.js"; import type { WebSourceLocationService } from "../application/WebSourceLocationService.js"; import { toolContract } from "../contracts/toolContracts.js"; @@ -98,6 +106,15 @@ export interface AnalysisSettingsToolOptions { readonly delivery: ToolResultDelivery; } +/** + * The session that admits and records derived Evidence, and the artifact + * resource scope its comparisons of caller-named files read under. + */ +export interface SessionDerivedToolOptions { + readonly session: BinarySessionPort; + readonly resources: ArtifactResourceScope; +} + /** Artifact resources a selected view may read, when the server owns them. */ export interface AnalysisViewToolOptions { readonly resources?: ArtifactResourceScope | undefined; @@ -573,7 +590,7 @@ const SERVICE_TOOL_BINDINGS = { }), }, })) satisfies Bind, - sessionDerived: ((session) => ({ + sessionDerived: (({ session, resources }) => ({ compare_functions: { admission: "sdk", session, @@ -615,7 +632,38 @@ const SERVICE_TOOL_BINDINGS = { session, derive: (input) => verifyReconstructionEvidence(input, session), }, - })) satisfies Bind, + // Comparisons of caller-named files read them under the server's + // artifact resource scope before deriving. + compare_artifacts: { + admission: "application", + session, + resources, + acquire: async (input, { evidenceForAnalysis, signal, resources }) => { + const sources = await resolveArtifactComparisonSources( + input, + evidenceForAnalysis, + { signal, resources }, + ); + return sources.ok + ? ok(() => artifactComparisonExecution(sources.value)) + : sources; + }, + }, + compare_bundles: { + admission: "sdk", + session, + resources, + acquire: async (input, { signal, resources }) => { + const sources = await readBundleComparisonSources(input, { + signal, + resources, + }); + return sources.ok + ? ok(() => bundleComparisonExecution(sources.value)) + : sources; + }, + }, + })) satisfies Bind, sessionStatus: ((options) => ({ binary_session: { admission: "sdk", diff --git a/src/server/registerArtifactComparisonTool.test.ts b/src/server/sessionDerivedArtifactComparison.test.ts similarity index 91% rename from src/server/registerArtifactComparisonTool.test.ts rename to src/server/sessionDerivedArtifactComparison.test.ts index 530acd25eb..1e93f4f4e2 100644 --- a/src/server/registerArtifactComparisonTool.test.ts +++ b/src/server/sessionDerivedArtifactComparison.test.ts @@ -8,14 +8,14 @@ import { import { ArtifactResourceScope } from "../resources/ArtifactResourceScope.js"; import { ARTIFACT_COMPARISON_EXAMPLE } from "../contracts/artifactComparisonExample.js"; -import { toolContract } from "../contracts/toolContracts.js"; import { createCacheProvider, createTestBinarySession, } from "../../tests/fixtures/binarySession.js"; import { EvidenceMcpServer } from "./EvidenceMcpServer.js"; import { ToolResultDelivery } from "./ToolResultDelivery.js"; -import { registerArtifactComparisonTool } from "./registerArtifactComparisonTool.js"; +import { registerServiceTools } from "./serviceToolBindings.js"; +import { silentLogger } from "../logger.js"; it.each([false, true])( "retains the completed artifact comparison and source closure (terminal cancellation=%s)", @@ -35,16 +35,15 @@ it.each([false, true])( delivery, ); const registration = vi.spyOn(server, "registerTool"); - registerArtifactComparisonTool( + registerServiceTools( server, - session, - toolContract("compare_artifacts"), - resources, + { sessionDerived: { session, resources } }, + { logger: silentLogger }, ); // This named registration always has its contract's input schema. - const callback = registration.mock.calls[0]?.[2] as - | ToolCallback - | undefined; + const callback = registration.mock.calls.find( + ([name]) => name === "compare_artifacts", + )?.[2] as ToolCallback | undefined; if (callback === undefined) throw new Error("Comparison was not registered"); const controller = new AbortController();