mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 11:43:20 +00:00
refactor(mcp): bind artifact and bundle comparison through a derived binding that acquires under the artifact resource scope (#11554)
* refactor(mcp): bind artifact and bundle comparison through an acquiring derived binding that owns their artifact resource scope compare_artifacts and compare_bundles registered bespoke handlers that read caller-named files under the server's artifact resource scope and then repeated the session-derived delivery. The derived binding kind now takes an optional acquisition with the resource scope it reads under; the table passes the scope, the readers open and release handles in it (failed releases stay owned for retry), and acquisition failures are delivered unchanged. The artifact unknown and the bundle Evidence moved to application owners. * fix(mcp): return a bundle comparison's record-pair failure as a typed Result bundleComparisonExecution declared a Result but let compareBundles throw AnalysisInputError for missing or repeated record pairs. It now returns the typed failure; unexpected errors still propagate.
This commit is contained in:
1 parent
a447161a84
commit
f6df353002
11 files changed
+369
-297
No files matched your search
@@ -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,
|
||||
|
||||
@@ -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<never, EvidenceIntegrityError> =>
|
||||
`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<InvestigationWorkflowExecution, AnalysisError> => {
|
||||
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: [],
|
||||
};
|
||||
};
|
||||
@@ -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]),
|
||||
);
|
||||
});
|
||||
@@ -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<typeof compareBundles>[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<Result<BundleComparisonSources, AnalysisError>> => {
|
||||
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<typeof compareBundles>;
|
||||
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 });
|
||||
};
|
||||
@@ -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<Input = unknown> = (
|
||||
readonly summary?: never;
|
||||
readonly value?: never;
|
||||
readonly derive?: never;
|
||||
readonly acquire?: never;
|
||||
}
|
||||
| {
|
||||
readonly admission: "application";
|
||||
@@ -76,6 +80,7 @@ type EvidenceBinding<Input = unknown> = (
|
||||
readonly summary?: never;
|
||||
readonly value?: never;
|
||||
readonly derive?: never;
|
||||
readonly acquire?: never;
|
||||
}
|
||||
) & {
|
||||
/**
|
||||
@@ -103,6 +108,7 @@ type ValueBinding<Input = unknown> =
|
||||
readonly run?: never;
|
||||
readonly summary?: never;
|
||||
readonly derive?: never;
|
||||
readonly acquire?: never;
|
||||
}
|
||||
| {
|
||||
readonly admission: "application";
|
||||
@@ -110,6 +116,7 @@ type ValueBinding<Input = unknown> =
|
||||
readonly run?: never;
|
||||
readonly summary?: never;
|
||||
readonly derive?: never;
|
||||
readonly acquire?: never;
|
||||
};
|
||||
|
||||
/**
|
||||
@@ -119,19 +126,41 @@ type ValueBinding<Input = unknown> =
|
||||
* 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<InvestigationWorkflowExecution, AnalysisError>;
|
||||
readonly run?: never;
|
||||
readonly summary?: never;
|
||||
readonly value?: never;
|
||||
}
|
||||
} & (
|
||||
| {
|
||||
readonly derive: (
|
||||
input: unknown,
|
||||
evidenceForAnalysis: BinarySessionPort["evidenceForAnalysis"],
|
||||
signal: AbortSignal,
|
||||
) => Result<InvestigationWorkflowExecution, AnalysisError>;
|
||||
readonly acquire?: never;
|
||||
readonly resources?: never;
|
||||
}
|
||||
| {
|
||||
readonly resources: ArtifactResourceScope;
|
||||
readonly acquire: (
|
||||
input: unknown,
|
||||
sources: DerivedSources & {
|
||||
readonly resources: ArtifactResourceScope;
|
||||
},
|
||||
) => ReturnType<DerivedAcquisition>;
|
||||
readonly derive?: never;
|
||||
}
|
||||
);
|
||||
|
||||
/**
|
||||
* Admit `detail`/`view` in the adapter, run the workflow on the remaining
|
||||
@@ -143,6 +172,7 @@ interface RetainedSummaryBinding<Input> {
|
||||
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 = <Name extends CatalogToolName>(
|
||||
service: ContractToolService<Name>,
|
||||
@@ -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
|
||||
|
||||
@@ -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<InvestigationWorkflowExecution, AnalysisError>,
|
||||
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<InvestigationWorkflowExecution, AnalysisError>,
|
||||
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);
|
||||
},
|
||||
);
|
||||
};
|
||||
|
||||
|
||||
@@ -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<typeof toolContract<"compare_artifacts">>,
|
||||
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: [],
|
||||
};
|
||||
};
|
||||
@@ -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<typeof toolContract<"compare_bundles">>,
|
||||
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,
|
||||
);
|
||||
},
|
||||
),
|
||||
);
|
||||
};
|
||||
@@ -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);
|
||||
};
|
||||
|
||||
@@ -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<AnalysisViewToolOptions>,
|
||||
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<BinarySessionPort>,
|
||||
// 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<SessionDerivedToolOptions>,
|
||||
sessionStatus: ((options) => ({
|
||||
binary_session: {
|
||||
admission: "sdk",
|
||||
|
||||
+8
-9
@@ -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<StandardSchemaWithJSON>
|
||||
| undefined;
|
||||
const callback = registration.mock.calls.find(
|
||||
([name]) => name === "compare_artifacts",
|
||||
)?.[2] as ToolCallback<StandardSchemaWithJSON> | undefined;
|
||||
if (callback === undefined)
|
||||
throw new Error("Comparison was not registered");
|
||||
const controller = new AbortController();
|
||||
Reference in new issue
Block a user