feat(mcp)!: harden contracts and evidence references

BREAKING CHANGE: comparison tools now require session-owned Evidence IDs or approved bundle paths, and structured Evidence results use compact references.
This commit is contained in:
morluto
2026-07-16 19:49:58 +08:00
parent ad398a17f5
commit ee1cd40405
47 changed files with 1387 additions and 672 deletions
+23 -3
View File
@@ -22,6 +22,7 @@ import {
import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { mcpProgressReporter } from "./mcpProgress.js";
interface ApplicationToolRegistration {
@@ -44,7 +45,13 @@ export const registerApplicationTools = (
traceContract.name,
toolRegistrationOptions(traceContract),
async (input) => {
const parsed = traceApplicationFeatureInputSchema.parse(input);
const parsedInput = safeParseToolInput(
traceApplicationFeatureInputSchema,
input,
traceContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, traceContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
traceContract.name,
@@ -61,7 +68,14 @@ export const registerApplicationTools = (
compareContract.name,
toolRegistrationOptions(compareContract),
async (input) => {
const parsed = compareApplicationVersionsInputSchema.parse(input);
const parsedInput = safeParseToolInput(
compareApplicationVersionsInputSchema,
input,
compareContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, compareContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
compareContract.name,
@@ -92,7 +106,13 @@ export const registerApplicationTools = (
replayContract.name,
toolRegistrationOptions(replayContract),
async (input, context) => {
const parsed = controlledReplayInputSchema.parse(input);
const parsedInput = safeParseToolInput(
controlledReplayInputSchema,
input,
replayContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, replayContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
replayContract.name,
+29 -21
View File
@@ -10,11 +10,12 @@ import { createEvidence } from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { RecordUnknownInput } from "../domain/residualUnknown.js";
import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
import { resolveSessionEvidence } from "./sessionEvidence.js";
import { resolveSessionEvidenceIds } from "./sessionEvidence.js";
import { ARTIFACT_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { runDerivedOperation } from "./runDerivedOperation.js";
import { safeParseToolInput } from "./toolInputValidation.js";
/** Register Evidence-backed deterministic artifact comparison. */
export const registerArtifactComparisonTool = (
@@ -26,18 +27,36 @@ export const registerArtifactComparisonTool = (
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsed = artifactComparisonInputSchema.parse(input);
const left = resolveSessionEvidence(session, parsed.left);
const parsedInput = safeParseToolInput(
artifactComparisonInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const expected = {
operation: "inventory_artifact",
predicate: "rea.analysis/v2",
};
const left = resolveSessionEvidenceIds(
session,
parsed.left_evidence_ids,
expected,
);
if (!left.ok) return toCallToolResult(left, contract);
const right = resolveSessionEvidence(session, parsed.right);
const right = resolveSessionEvidenceIds(
session,
parsed.right_evidence_ids,
expected,
);
if (!right.ok) return toCallToolResult(right, contract);
const computed = await runDerivedOperation(context, contract.name, () =>
compareArtifacts(left.value, right.value, parsed.offset, parsed.limit),
);
if (!computed.ok) return toCallToolResult(computed, contract);
const comparison = computed.value;
const leftEvidenceIds = evidenceIds(parsed.left);
const rightEvidenceIds = evidenceIds(parsed.right);
const leftEvidenceIds = parsed.left_evidence_ids;
const rightEvidenceIds = parsed.right_evidence_ids;
const evidence = createEvidence(undefined, ARTIFACT_COMPARISON_PROVIDER, {
predicateType: "rea.artifact-comparison/v1",
operation: contract.name,
@@ -67,12 +86,8 @@ export const registerArtifactComparisonTool = (
const artifactUnknownInput = (
input: {
readonly left:
| { readonly evidence_id: string }
| readonly { readonly evidence_id: string }[];
readonly right:
| { readonly evidence_id: string }
| readonly { readonly evidence_id: string }[];
readonly left_evidence_ids: readonly string[];
readonly right_evidence_ids: readonly string[];
readonly unknown_registry_approved?: true | undefined;
},
status: ReturnType<typeof compareArtifacts>["status"],
@@ -85,8 +100,8 @@ const artifactUnknownInput = (
severity:
status === "unknown" || status === "truncated" ? "high" : "medium",
domain: "artifact-comparison",
supporting_evidence_ids: evidenceIds(input.left),
contradicting_evidence_ids: evidenceIds(input.right),
supporting_evidence_ids: [...input.left_evidence_ids],
contradicting_evidence_ids: [...input.right_evidence_ids],
required_authority: "shipped-artifact",
required_confidence: "observed",
required_environment: null,
@@ -99,10 +114,3 @@ const artifactUnknownInput = (
relationships: [],
};
};
const evidenceIds = (
input:
| { readonly evidence_id: string }
| readonly { readonly evidence_id: string }[],
): string[] =>
(Array.isArray(input) ? input : [input]).map(({ evidence_id: id }) => id);
+63 -8
View File
@@ -30,6 +30,7 @@ import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { mcpProgressReporter } from "./mcpProgress.js";
interface BrowserToolRegistration {
@@ -58,7 +59,13 @@ export const registerBrowserTools = (
listContract.name,
toolRegistrationOptions(listContract),
async (input, context) => {
const parsed = listBrowserTargetsInputSchema.parse(input);
const parsedInput = safeParseToolInput(
listBrowserTargetsInputSchema,
input,
listContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, listContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
listContract.name,
@@ -78,7 +85,14 @@ export const registerBrowserTools = (
inspectContract.name,
toolRegistrationOptions(inspectContract),
async (input, context) => {
const parsed = inspectWebPageInputSchema.parse(input);
const parsedInput = safeParseToolInput(
inspectWebPageInputSchema,
input,
inspectContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, inspectContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
inspectContract.name,
@@ -96,7 +110,14 @@ export const registerBrowserTools = (
analyzeContract.name,
toolRegistrationOptions(analyzeContract),
async (input, context) => {
const parsed = analyzeWebBundleInputSchema.parse(input);
const parsedInput = safeParseToolInput(
analyzeWebBundleInputSchema,
input,
analyzeContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, analyzeContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
analyzeContract.name,
@@ -119,7 +140,14 @@ export const registerBrowserTools = (
sessionContract.name,
toolRegistrationOptions(sessionContract),
async (input, context) => {
const parsed = observeWebSessionInputSchema.parse(input);
const parsedInput = safeParseToolInput(
observeWebSessionInputSchema,
input,
sessionContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, sessionContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
sessionContract.name,
@@ -142,7 +170,13 @@ export const registerBrowserTools = (
webMcpContract.name,
toolRegistrationOptions(webMcpContract),
async (input, context) => {
const parsed = discoverWebMcpToolsInputSchema.parse(input);
const parsedInput = safeParseToolInput(
discoverWebMcpToolsInputSchema,
input,
webMcpContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, webMcpContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
webMcpContract.name,
@@ -165,7 +199,14 @@ export const registerBrowserTools = (
captureDiffContract.name,
toolRegistrationOptions(captureDiffContract),
async (input) => {
const parsed = compareWebCapturesInputSchema.parse(input);
const parsedInput = safeParseToolInput(
compareWebCapturesInputSchema,
input,
captureDiffContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, captureDiffContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
captureDiffContract.name,
@@ -179,7 +220,14 @@ export const registerBrowserTools = (
screenshotContract.name,
toolRegistrationOptions(screenshotContract),
async (input, context) => {
const parsed = captureWebScreenshotInputSchema.parse(input);
const parsedInput = safeParseToolInput(
captureWebScreenshotInputSchema,
input,
screenshotContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, screenshotContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
screenshotContract.name,
@@ -202,7 +250,14 @@ export const registerBrowserTools = (
screenshotDiffContract.name,
toolRegistrationOptions(screenshotDiffContract),
async (input) => {
const parsed = compareWebScreenshotsInputSchema.parse(input);
const parsedInput = safeParseToolInput(
compareWebScreenshotsInputSchema,
input,
screenshotDiffContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, screenshotDiffContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
screenshotDiffContract.name,
+19 -43
View File
@@ -1,73 +1,50 @@
import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { readEvidenceBundle } from "../application/EvidenceBundleFiles.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import {
bundleComparisonInputSchema,
compareBundles,
} from "../domain/bundleComparison.js";
import { createEvidence } from "../domain/evidence.js";
import { EvidenceIntegrityError } from "../domain/errors.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { err, ok } from "../domain/result.js";
import { ok } from "../domain/result.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import { BUNDLE_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
import { toCallToolResult } from "./toolResult.js";
import { isSessionEvidence } from "./sessionEvidence.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { runDerivedOperation } from "./runDerivedOperation.js";
import { safeParseToolInput } from "./toolInputValidation.js";
/** Register canonical Evidence bundle comparison. */
export const registerBundleComparisonTool = (
server: McpServer,
session: BinarySessionPort,
contract: ToolContract<"compare_bundles">,
evidenceFilePolicy: EvidenceFilePolicy,
): void => {
server.registerTool(
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsed = bundleComparisonInputSchema.parse(input);
const sourceIds = [
...new Set([
...parsed.left.records.map(({ evidence_id: id }) => id),
...parsed.right.records.map(({ evidence_id: id }) => id),
]),
].sort();
if (
[...parsed.left.records, ...parsed.right.records].some(
(evidence) => !isSessionEvidence(session, evidence),
)
)
return toCallToolResult(
err(
new EvidenceIntegrityError(
"Bundle comparison input Evidence is not present in this session",
),
),
contract,
);
const ownedUnknownDigests = new Set(
session
.exportEvidenceBundle()
.unknowns.map(({ revision_digest: digest }) => digest),
const parsedInput = safeParseToolInput(
bundleComparisonInputSchema,
input,
contract.name,
);
if (
[...parsed.left.unknowns, ...parsed.right.unknowns].some(
({ revision_digest: digest }) => !ownedUnknownDigests.has(digest),
)
)
return toCallToolResult(
err(
new EvidenceIntegrityError(
"Bundle comparison input unknown history is not present in this session",
),
),
contract,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const [left, right] = await Promise.all([
readEvidenceBundle(parsed.left_bundle_path, evidenceFilePolicy),
readEvidenceBundle(parsed.right_bundle_path, evidenceFilePolicy),
]);
if (!left.ok) return toCallToolResult(left, contract);
if (!right.ok) return toCallToolResult(right, contract);
const computed = await runDerivedOperation(context, contract.name, () =>
compareBundles(
parsed.left,
parsed.right,
left.value,
right.value,
parsed.record_pairs,
parsed.offset,
parsed.limit,
@@ -89,7 +66,6 @@ export const registerBundleComparisonTool = (
confidence: "derived",
authority: "analyst-inference",
limitations: comparison.limitations,
evidenceLinks: sourceIds,
});
const recorded = session.recordEvidence(evidence);
return toCallToolResult(recorded.ok ? ok(evidence) : recorded, contract);
+32 -4
View File
@@ -20,6 +20,7 @@ import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { mcpProgressReporter } from "./mcpProgress.js";
interface ElectronToolRegistration {
@@ -40,7 +41,13 @@ export const registerElectronTools = (
listContract.name,
toolRegistrationOptions(listContract),
async (input, context) => {
const parsed = listElectronTargetsInputSchema.parse(input);
const parsedInput = safeParseToolInput(
listElectronTargetsInputSchema,
input,
listContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, listContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
listContract.name,
@@ -60,7 +67,14 @@ export const registerElectronTools = (
inspectContract.name,
toolRegistrationOptions(inspectContract),
async (input, context) => {
const parsed = inspectElectronPageInputSchema.parse(input);
const parsedInput = safeParseToolInput(
inspectElectronPageInputSchema,
input,
inspectContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, inspectContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
inspectContract.name,
@@ -83,7 +97,14 @@ export const registerElectronTools = (
analyzeContract.name,
toolRegistrationOptions(analyzeContract),
async (input, context) => {
const parsed = analyzeJavaScriptApplicationInputSchema.parse(input);
const parsedInput = safeParseToolInput(
analyzeJavaScriptApplicationInputSchema,
input,
analyzeContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, analyzeContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
analyzeContract.name,
@@ -101,7 +122,14 @@ export const registerElectronTools = (
reconcileContract.name,
toolRegistrationOptions(reconcileContract),
async (input) => {
const parsed = reconcileJavaScriptRuntimeInputSchema.parse(input);
const parsedInput = safeParseToolInput(
reconcileJavaScriptRuntimeInputSchema,
input,
reconcileContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, reconcileContract);
const parsed = parsedInput.value;
const result = await logToolExecution(
options.logger,
reconcileContract.name,
+9 -8
View File
@@ -22,6 +22,8 @@ import {
REA_WORKFLOW_PROVIDER,
workflowAnalysisProfile,
} from "../application/InvestigationProviders.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
/** Optional session services used by enhanced tool registration. */
export interface EnhancedToolRegistration {
@@ -69,12 +71,7 @@ const registerEnhancedTool = (
const name = enhancedToolNameSchema.parse(contract.name);
server.registerTool(
name,
{
description: contract.description,
inputSchema: contract.inputSchema,
outputSchema: contract.outputSchema,
annotations: contract.annotations,
},
toolRegistrationOptions(contract),
async (input, context) => {
const progress = mcpProgressReporter(context);
await progress.report({
@@ -83,9 +80,13 @@ const registerEnhancedTool = (
total: 1,
message: "started",
});
const parsedInput = jsonObjectSchema.parse(
enhancedInputSchemas[name].parse(input),
const validatedInput = safeParseToolInput(
enhancedInputSchemas[name],
input,
name,
);
if (!validatedInput.ok) return toCallToolResult(validatedInput, contract);
const parsedInput = jsonObjectSchema.parse(validatedInput.value);
const parameters: Record<string, JsonValue> = { ...parsedInput };
const result = await logToolExecution(registration.logger, name, () =>
services.execute(name, input, context.mcpReq.signal),
+7 -2
View File
@@ -14,6 +14,7 @@ import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import {
AnalysisProtocolError,
@@ -47,9 +48,13 @@ export const registerEvidenceTools = (
total: 1,
message: "started",
});
const parameters = jsonObjectSchema.parse(
contract.inputSchema.parse(input),
const parsedInput = safeParseToolInput(
contract.inputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parameters = jsonObjectSchema.parse(parsedInput.value);
if (options.permissionAuthority !== undefined) {
const request = permissionRequest(contract.name, parameters);
if (request !== undefined) {
+26 -10
View File
@@ -6,15 +6,16 @@ import {
compareFunctions,
functionComparisonInputSchema,
} from "../domain/functionComparison.js";
import { createEvidence, type Evidence } from "../domain/evidence.js";
import { createEvidence } from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { RecordUnknownInput } from "../domain/residualUnknown.js";
import { FUNCTION_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
import { toCallToolResult } from "./toolResult.js";
import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
import { resolveSessionEvidence } from "./sessionEvidence.js";
import { resolveSessionEvidenceIds } from "./sessionEvidence.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { runDerivedOperation } from "./runDerivedOperation.js";
import { safeParseToolInput } from "./toolInputValidation.js";
/** Register explicit Evidence-backed function comparison. */
export const registerFunctionComparisonTool = (
@@ -26,13 +27,31 @@ export const registerFunctionComparisonTool = (
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsed = functionComparisonInputSchema.parse(input);
const left = resolveSessionEvidence(session, parsed.left);
const parsedInput = safeParseToolInput(
functionComparisonInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const expected = {
operation: "analyze_function",
predicate: "rea.analysis/v2",
};
const left = resolveSessionEvidenceIds(
session,
parsed.left_evidence_ids,
expected,
);
if (!left.ok) return toCallToolResult(left, contract);
const right = resolveSessionEvidence(session, parsed.right);
const right = resolveSessionEvidenceIds(
session,
parsed.right_evidence_ids,
expected,
);
if (!right.ok) return toCallToolResult(right, contract);
const leftIds = evidenceIds(left.value);
const rightIds = evidenceIds(right.value);
const leftIds = left.value.map(({ evidence_id: id }) => id);
const rightIds = right.value.map(({ evidence_id: id }) => id);
const computed = await runDerivedOperation(context, contract.name, () =>
compareFunctions(left.value, right.value, parsed.offset, parsed.limit),
);
@@ -100,6 +119,3 @@ const functionUnknownInput = ({
relationships: [],
};
};
const evidenceIds = (input: Evidence | readonly Evidence[]): string[] =>
(Array.isArray(input) ? input : [input]).map(({ evidence_id: id }) => id);
+31 -32
View File
@@ -3,6 +3,8 @@ import type { McpServer } from "@modelcontextprotocol/server";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { runCrossVersionInvestigation } from "../application/CrossVersionInvestigation.js";
import type { ToolContract } from "../contracts/toolContracts.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { buildCallPath, callPathInputSchema } from "../domain/callPath.js";
import {
correlateStaticAndRuntime,
@@ -95,7 +97,13 @@ const registerChangedBehavior = (
contract.name,
contractOptions(contract),
async (input, context) => {
const parsed = changedBehaviorInputSchema.parse(input);
const parsedInput = safeParseToolInput(
changedBehaviorInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const investigationRun = parsed.investigation_run;
if (investigationRun !== undefined) {
const progress = mcpProgressReporter(context);
@@ -250,7 +258,13 @@ const registerCallPath = (
contract.name,
contractOptions(contract),
async (input, context) => {
const parsed = callPathInputSchema.parse(input);
const parsedInput = safeParseToolInput(
callPathInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const closure = evidenceClosure(
session,
functionEvidenceIds(parsed.functions),
@@ -313,7 +327,13 @@ const registerStaticRuntime = (
contract.name,
contractOptions(contract),
async (input, context) => {
const parsed = staticRuntimeCorrelationInputSchema.parse(input);
const parsedInput = safeParseToolInput(
staticRuntimeCorrelationInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const closure = evidenceClosure(
session,
comparisonClosure([
@@ -378,30 +398,14 @@ const registerReconstruction = (
contract.name,
contractOptions(contract),
async (input, context) => {
const parsed = reconstructionVerificationInputSchema.parse(input);
const parsedInput = safeParseToolInput(
reconstructionVerificationInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const owned = session.exportEvidenceBundle();
const ownedUnknowns = new Set(
owned.unknowns.map(({ revision_digest: digest }) => digest),
);
const ownedEvidenceIds = new Set(
owned.records.map(({ evidence_id: id }) => id),
);
if (
parsed.evidence_bundle.records.some(
({ evidence_id: id }) => !ownedEvidenceIds.has(id),
) ||
parsed.evidence_bundle.unknowns.some(
({ revision_digest: digest }) => !ownedUnknowns.has(digest),
)
)
return toCallToolResult(
err(
new EvidenceIntegrityError(
"Reconstruction input unknown history is not present in this session",
),
),
contract,
);
const computed = await runDerivedOperation(context, contract.name, () =>
verifyReconstruction(
parsed.specification,
@@ -455,12 +459,7 @@ const registerReconstruction = (
);
};
const contractOptions = (contract: ToolContract) => ({
description: contract.description,
inputSchema: contract.inputSchema,
outputSchema: contract.outputSchema,
annotations: contract.annotations,
});
const contractOptions = toolRegistrationOptions;
const comparisonClosure = (comparisons: readonly Evidence[]): string[] =>
uniqueIds(
+11 -8
View File
@@ -18,6 +18,8 @@ import {
UnknownRegistryError,
} from "../domain/errors.js";
import { mcpProgressReporter } from "./mcpProgress.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
/** Optional session services used by direct tool registration. */
export interface OfficialToolRegistration {
@@ -56,14 +58,15 @@ const registerOfficialTool = (
): void => {
server.registerTool(
contract.name,
{
description: contract.description,
inputSchema: contract.inputSchema,
outputSchema: contract.outputSchema,
annotations: contract.annotations,
},
toolRegistrationOptions(contract),
async (input, context) => {
const arguments_ = projectOfficialArguments(contract, input);
const parsedInput = safeParseToolInput(
contract.inputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const arguments_ = projectOfficialArguments(contract, parsedInput.value);
const progress = mcpProgressReporter(context);
await progress.report({
phase: contract.name,
@@ -153,7 +156,7 @@ const projectOfficialArguments = (
contract: (typeof OFFICIAL_TOOL_CONTRACTS)[number],
input: unknown,
): Readonly<Record<string, JsonValue>> => {
const parsed = jsonObjectSchema.parse(contract.inputSchema.parse(input));
const parsed = jsonObjectSchema.parse(input);
const projected: Record<string, JsonValue> = {};
for (const key of Object.keys(contract.inputSchema.shape)) {
+40 -60
View File
@@ -1,16 +1,16 @@
import type { McpServer } from "@modelcontextprotocol/server";
import canonicalize from "canonicalize";
import { z } from "zod";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import {
processComparisonInputSchema,
SESSION_TOOL_CONTRACTS,
} from "../contracts/toolContracts.js";
import { createEvidence } from "../domain/evidence.js";
import { EvidenceIntegrityError } from "../domain/errors.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { RecordUnknownInput } from "../domain/residualUnknown.js";
import {
compareProcessCaptures,
processCaptureSchema,
parseProcessCapture,
} from "../domain/processCapture.js";
import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
@@ -19,6 +19,8 @@ import { PROCESS_PROVIDER } from "./sessionToolPolicies.js";
import { toCallToolResult } from "./toolResult.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { runDerivedOperation } from "./runDerivedOperation.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { resolveSessionEvidenceIds } from "./sessionEvidence.js";
/** Register deterministic process-capture comparison and contradiction tracking. */
export const registerProcessComparisonTool = (
@@ -31,22 +33,41 @@ export const registerProcessComparisonTool = (
contract.name,
toolRegistrationOptions(contract),
async (input, context) => {
const parsed = z
.object({
left_evidence_id: z.string(),
left: processCaptureSchema,
right_evidence_id: z.string(),
right: processCaptureSchema,
max_capture_age_ms: z.number().int().nonnegative().optional(),
unknown_registry_approved: z.literal(true).optional(),
})
.parse(input);
const validated = validateCaptureSources(session, parsed);
if (!validated.ok) return toCallToolResult(validated, contract);
const parsedInput = safeParseToolInput(
processComparisonInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const expected = {
operation: "capture_process_scenario",
predicate: "rea.process-capture/v4",
};
const leftRecord = resolveSessionEvidenceIds(
session,
[parsed.left_evidence_id],
expected,
);
if (!leftRecord.ok) return toCallToolResult(leftRecord, contract);
const rightRecord = resolveSessionEvidenceIds(
session,
[parsed.right_evidence_id],
expected,
);
if (!rightRecord.ok) return toCallToolResult(rightRecord, contract);
let comparison: ReturnType<typeof compareProcessCaptures>;
let leftCapture: ReturnType<typeof parseProcessCapture>;
let rightCapture: ReturnType<typeof parseProcessCapture>;
try {
leftCapture = parseProcessCapture(
leftRecord.value[0]?.normalized_result,
);
rightCapture = parseProcessCapture(
rightRecord.value[0]?.normalized_result,
);
const computed = await runDerivedOperation(context, contract.name, () =>
compareProcessCaptures(parsed.left, parsed.right, {
compareProcessCaptures(leftCapture, rightCapture, {
...(parsed.max_capture_age_ms === undefined
? {}
: { maxCaptureAgeMs: parsed.max_capture_age_ms }),
@@ -73,8 +94,8 @@ export const registerProcessComparisonTool = (
parameters: {
left_evidence_id: parsed.left_evidence_id,
right_evidence_id: parsed.right_evidence_id,
left_normalization: parsed.left.normalization,
right_normalization: parsed.right.normalization,
left_normalization: leftCapture.normalization,
right_normalization: rightCapture.normalization,
},
result: jsonValueSchema.parse(comparison),
confidence: "derived",
@@ -94,47 +115,6 @@ export const registerProcessComparisonTool = (
);
};
const validateCaptureSources = (
session: BinarySessionPort,
parsed: {
readonly left_evidence_id: string;
readonly left: z.infer<typeof processCaptureSchema>;
readonly right_evidence_id: string;
readonly right: z.infer<typeof processCaptureSchema>;
},
) => {
for (const [evidenceId, capture] of [
[parsed.left_evidence_id, parsed.left],
[parsed.right_evidence_id, parsed.right],
] as const) {
const evidence = session.evidenceById(evidenceId);
let evidenceCapture: z.infer<typeof processCaptureSchema> | undefined;
try {
evidenceCapture = parseProcessCapture(evidence?.normalized_result);
} catch {
evidenceCapture = undefined;
}
if (
evidence === undefined ||
evidence.operation !== "capture_process_scenario" ||
evidence.predicate_type !== "rea.process-capture/v4" ||
evidence.provider.id !== PROCESS_PROVIDER.id ||
evidence.provider.name !== PROCESS_PROVIDER.name ||
evidence.provider.version !== PROCESS_PROVIDER.version ||
evidence.confidence !== "observed" ||
evidence.authority !== "controlled-replay" ||
evidenceCapture === undefined ||
canonicalize(evidenceCapture) !== canonicalize(capture)
)
return err(
new EvidenceIntegrityError(
"Process comparison payload does not match its source Evidence",
),
);
}
return { ok: true as const, value: null };
};
const comparisonUnknownInput = (
parsed: {
readonly left_evidence_id: string;
+10 -7
View File
@@ -9,6 +9,8 @@ import { toCallToolResult } from "./toolResult.js";
import { jsonObjectSchema } from "../domain/jsonValue.js";
import { createServerIdentity } from "../serverIdentity.js";
import { buildCapabilityInventory } from "../application/CapabilityInventory.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
/** Register the read-only provider and target status operation. */
export const registerSessionStatusTool = (
@@ -27,14 +29,15 @@ export const registerSessionStatusTool = (
): void => {
server.registerTool(
contract.name,
{
description: contract.description,
inputSchema: contract.inputSchema,
outputSchema: contract.outputSchema,
annotations: contract.annotations,
},
toolRegistrationOptions(contract),
(input) => {
const parsed = binarySessionInputSchema.parse(input);
const parsedInput = safeParseToolInput(
binarySessionInputSchema,
input,
contract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
const client = server.server.getClientVersion();
const clientCapabilities = server.server.getClientCapabilities();
const status = session.status();
+86 -88
View File
@@ -2,7 +2,13 @@ import type { McpServer } from "@modelcontextprotocol/server";
import { z } from "zod";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import {
exportEvidenceBundleInputSchema,
importEvidenceBundleInputSchema,
listUnknownsInputSchema,
SESSION_TOOL_CONTRACTS,
verifyUnknownResolutionInputSchema,
} from "../contracts/toolContracts.js";
import { toCallToolResult } from "./toolResult.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
@@ -43,6 +49,8 @@ import { createProcessCaptureEvidence } from "../application/ProcessEvidence.js"
import { registerProcessComparisonTool } from "./registerProcessComparisonTool.js";
import { registerArtifactComparisonTool } from "./registerArtifactComparisonTool.js";
import { registerFunctionComparisonTool } from "./registerFunctionComparisonTool.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { registerBundleComparisonTool } from "./registerBundleComparisonTool.js";
import { registerInvestigationTools } from "./registerInvestigationTools.js";
import {
@@ -129,14 +137,16 @@ const registerProcessTools = ({
}: ProcessToolRegistration): void => {
server.registerTool(
captureContract.name,
{
description: captureContract.description,
inputSchema: captureContract.inputSchema,
outputSchema: captureContract.outputSchema,
annotations: captureContract.annotations,
},
toolRegistrationOptions(captureContract),
async (input, context) => {
const scenario = processScenarioSchema.parse(input);
const parsedInput = safeParseToolInput(
processScenarioSchema,
input,
captureContract.name,
);
if (!parsedInput.ok)
return toCallToolResult(parsedInput, captureContract);
const scenario = parsedInput.value;
if (permissionAuthority !== undefined) {
const authorized = await permissionAuthority.authorize(
{
@@ -218,19 +228,15 @@ const registerEvidenceTools = ({
}: EvidenceToolRegistration): void => {
server.registerTool(
exportContract.name,
{
description: exportContract.description,
inputSchema: exportContract.inputSchema,
outputSchema: exportContract.outputSchema,
annotations: exportContract.annotations,
},
toolRegistrationOptions(exportContract),
async (input) => {
const parsed = z
.object({
path: z.string().min(1).optional(),
overwrite: z.boolean().default(false),
})
.parse(input);
const parsedInput = safeParseToolInput(
exportEvidenceBundleInputSchema,
input,
exportContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, exportContract);
const parsed = parsedInput.value;
const bundle = session.exportEvidenceBundle();
if (parsed.path === undefined)
return toCallToolResult(ok(bundle), exportContract);
@@ -273,14 +279,15 @@ const registerEvidenceTools = ({
);
server.registerTool(
importContract.name,
{
description: importContract.description,
inputSchema: importContract.inputSchema,
outputSchema: importContract.outputSchema,
annotations: importContract.annotations,
},
toolRegistrationOptions(importContract),
async (input) => {
const path = z.object({ path: z.string().min(1) }).parse(input).path;
const parsedInput = safeParseToolInput(
importEvidenceBundleInputSchema,
input,
importContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, importContract);
const path = parsedInput.value.path;
if (permissionAuthority !== undefined) {
const authorized = await permissionAuthority.authorize(
{
@@ -335,28 +342,15 @@ const registerUnknownTools = ({
}: UnknownToolRegistration): void => {
server.registerTool(
listContract.name,
{
description: listContract.description,
inputSchema: listContract.inputSchema,
outputSchema: listContract.outputSchema,
annotations: listContract.annotations,
},
toolRegistrationOptions(listContract),
(input) => {
const filters = z
.object({
status: z
.enum([
"open",
"investigating",
"blocked",
"contradicted",
"resolved",
])
.optional(),
severity: z.enum(["low", "medium", "high", "critical"]).optional(),
domain: z.string().trim().min(1).max(100).optional(),
})
.parse(input);
const parsedInput = safeParseToolInput(
listUnknownsInputSchema,
input,
listContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, listContract);
const filters = parsedInput.value;
return toCallToolResult(
ok(
session.listUnknowns({
@@ -373,48 +367,45 @@ const registerUnknownTools = ({
);
server.registerTool(
recordContract.name,
{
description: recordContract.description,
inputSchema: recordContract.inputSchema,
outputSchema: recordContract.outputSchema,
annotations: recordContract.annotations,
},
toolRegistrationOptions(recordContract),
(input) => {
const recorded = session.recordUnknown(
recordUnknownInputSchema.parse(input),
const parsedInput = safeParseToolInput(
recordUnknownInputSchema,
input,
recordContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, recordContract);
const recorded = session.recordUnknown(parsedInput.value);
if (recorded.ok) server.sendResourceListChanged();
return toCallToolResult(recorded, recordContract);
},
);
server.registerTool(
updateContract.name,
{
description: updateContract.description,
inputSchema: updateContract.inputSchema,
outputSchema: updateContract.outputSchema,
annotations: updateContract.annotations,
},
toolRegistrationOptions(updateContract),
(input) => {
const updated = session.updateUnknown(
updateUnknownInputSchema.parse(input),
const parsedInput = safeParseToolInput(
updateUnknownInputSchema,
input,
updateContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, updateContract);
const updated = session.updateUnknown(parsedInput.value);
if (updated.ok) server.sendResourceListChanged();
return toCallToolResult(updated, updateContract);
},
);
server.registerTool(
verifyContract.name,
{
description: verifyContract.description,
inputSchema: verifyContract.inputSchema,
outputSchema: verifyContract.outputSchema,
annotations: verifyContract.annotations,
},
toolRegistrationOptions(verifyContract),
(input) => {
const unknownId = z
.object({ unknown_id: z.string().regex(/^unk_[a-f0-9]{64}$/u) })
.parse(input).unknown_id;
const parsedInput = safeParseToolInput(
verifyUnknownResolutionInputSchema,
input,
verifyContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, verifyContract);
const unknownId = parsedInput.value.unknown_id;
return toCallToolResult(
session.verifyUnknownResolution(unknownId),
verifyContract,
@@ -458,14 +449,15 @@ const registerLifecycleTools = ({
const [openContract, closeContract, statusContract] = contracts;
server.registerTool(
openContract.name,
{
description: openContract.description,
inputSchema: openContract.inputSchema,
outputSchema: openContract.outputSchema,
annotations: openContract.annotations,
},
toolRegistrationOptions(openContract),
async (input, context) => {
const parsed = openBinaryInputSchema.parse(input);
const parsedInput = safeParseToolInput(
openBinaryInputSchema,
input,
openContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, openContract);
const parsed = parsedInput.value;
let snapshot: AnalysisSnapshot | undefined;
if (parsed.snapshot_path !== undefined) {
if (permissionAuthority !== undefined) {
@@ -526,14 +518,15 @@ const registerLifecycleTools = ({
);
server.registerTool(
closeContract.name,
{
description: closeContract.description,
inputSchema: closeContract.inputSchema,
outputSchema: closeContract.outputSchema,
annotations: closeContract.annotations,
},
toolRegistrationOptions(closeContract),
async (input) => {
const parsed = closeBinaryInputSchema.parse(input);
const parsedInput = safeParseToolInput(
closeBinaryInputSchema,
input,
closeContract.name,
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, closeContract);
const parsed = parsedInput.value;
if (parsed.snapshot_path !== undefined) {
if (permissionAuthority !== undefined) {
const authorized = await permissionAuthority.authorize(
@@ -688,7 +681,12 @@ export const registerSessionTools = (
registerProcessComparisonTool(server, session, compareContract);
registerArtifactComparisonTool(server, session, compareArtifactsContract);
registerFunctionComparisonTool(server, session, compareFunctionsContract);
registerBundleComparisonTool(server, session, compareBundlesContract);
registerBundleComparisonTool(
server,
session,
compareBundlesContract,
evidenceFilePolicy,
);
const investigationContracts = [
changedBehaviorContract,
callPathContract,
+38 -26
View File
@@ -1,38 +1,50 @@
import canonicalize from "canonicalize";
import type { BinarySessionPort } from "../application/BinarySession.js";
import { EvidenceIntegrityError } from "../domain/errors.js";
import { parseEvidence, type Evidence } from "../domain/evidence.js";
import {
EvidenceIntegrityError,
EvidenceReferenceError,
} from "../domain/errors.js";
import type { Evidence } from "../domain/evidence.js";
import { err, ok, type Result } from "../domain/result.js";
type EvidenceAuthorityResult = Result<Evidence[], EvidenceIntegrityError>;
/** Resolve caller-supplied records to their immutable session-owned values. */
export const resolveSessionEvidence = (
/** Resolve bounded IDs to authoritative records with exact semantic identity. */
export const resolveSessionEvidenceIds = (
session: BinarySessionPort,
input: Evidence | readonly Evidence[],
evidenceIds: readonly string[],
expected: { readonly operation: string; readonly predicate: string },
): EvidenceAuthorityResult => {
const supplied = Array.isArray(input) ? input : [input];
const authoritative: Evidence[] = [];
for (const item of supplied) {
const parsed = parseEvidence(item);
const owned = session.evidenceById(parsed.evidence_id);
if (owned === undefined || canonicalize(owned) !== canonicalize(parsed))
const records: Evidence[] = [];
for (const evidenceId of evidenceIds) {
const record = session.evidenceById(evidenceId);
if (record === undefined)
return err(
new EvidenceIntegrityError(
"Comparison input does not match its session-owned Evidence",
new EvidenceReferenceError(
evidenceId,
"missing",
expected.operation,
null,
),
);
authoritative.push(owned);
if (record.operation !== expected.operation)
return err(
new EvidenceReferenceError(
evidenceId,
"wrong_operation",
expected.operation,
record.operation,
),
);
if (record.predicate_type !== expected.predicate)
return err(
new EvidenceReferenceError(
evidenceId,
"wrong_predicate",
expected.predicate,
record.predicate_type,
),
);
records.push(record);
}
return ok(authoritative);
};
/** Check exact ownership for a single Evidence record. */
export const isSessionEvidence = (
session: BinarySessionPort,
input: Evidence,
): boolean => {
const owned = session.evidenceById(input.evidence_id);
return owned !== undefined && canonicalize(owned) === canonicalize(input);
return ok(records);
};
+128
View File
@@ -0,0 +1,128 @@
import { z } from "zod";
import {
AnalysisInputError,
type AnalysisInputIssue,
} from "../domain/errors.js";
import { projectInputIssues } from "../domain/inputIssueProjection.js";
import { err, ok, type Result } from "../domain/result.js";
/** Parse one MCP request exactly once and retain only schema-owned correction data. */
export const safeParseToolInput = <Schema extends z.ZodType>(
schema: Schema,
input: unknown,
operation: string,
): Result<z.output<Schema>, AnalysisInputError> => {
const unknownIssues = unknownArgumentIssues(schema, input);
if (unknownIssues.length > 0)
return err(new AnalysisInputError(operation, undefined, unknownIssues));
const parsed = schema.safeParse(input);
return parsed.success
? ok(parsed.data)
: err(
new AnalysisInputError(
operation,
undefined,
projectInputIssues(parsed.error.issues, input),
),
);
};
const schemaCache = new WeakMap<z.ZodType, Readonly<Record<string, unknown>>>();
const unknownArgumentIssues = (
schema: z.ZodType,
input: unknown,
): readonly AnalysisInputIssue[] => {
let jsonSchema = schemaCache.get(schema);
if (jsonSchema === undefined) {
const converter = schema["~standard"].jsonSchema?.input;
if (converter === undefined)
throw new TypeError(
"Tool input schema does not expose Standard JSON Schema",
);
jsonSchema = converter({ target: "draft-2020-12" });
schemaCache.set(schema, jsonSchema);
}
return scanUnknownArguments(input, jsonSchema, jsonSchema, []);
};
const scanUnknownArguments = (
value: unknown,
schema: Readonly<Record<string, unknown>>,
root: Readonly<Record<string, unknown>>,
path: readonly (string | number)[],
): AnalysisInputIssue[] => {
const resolved = resolveSchema(schema, root);
if (Array.isArray(value)) {
const items = objectValue(resolved.items);
return items === undefined
? []
: value.flatMap((item, index) =>
scanUnknownArguments(item, items, root, [...path, index]),
);
}
if (!isObject(value)) return [];
const variants = schemaVariants(resolved, root);
const properties = Object.fromEntries(
variants.flatMap((variant) =>
Object.entries(objectValue(variant.properties) ?? {}),
),
);
const closed =
variants.length > 0 &&
variants.every(
(variant) =>
variant.additionalProperties !== true &&
!isObject(variant.additionalProperties),
);
const issues: AnalysisInputIssue[] = [];
for (const [key, child] of Object.entries(value)) {
const propertySchema = objectValue(properties[key]);
if (propertySchema === undefined) {
if (closed)
issues.push({ path: [...path, key], reason: "unknown_argument" });
continue;
}
issues.push(
...scanUnknownArguments(child, propertySchema, root, [...path, key]),
);
}
return issues;
};
const schemaVariants = (
schema: Readonly<Record<string, unknown>>,
root: Readonly<Record<string, unknown>>,
): readonly Readonly<Record<string, unknown>>[] => {
const resolved = resolveSchema(schema, root);
const variants = [resolved.oneOf, resolved.anyOf, resolved.allOf]
.flatMap((value) => (Array.isArray(value) ? value : []))
.flatMap((value) => {
const object = objectValue(value);
return object === undefined ? [] : schemaVariants(object, root);
});
if (variants.length > 0) return variants;
return resolved.type === "object" || isObject(resolved.properties)
? [resolved]
: [];
};
const resolveSchema = (
schema: Readonly<Record<string, unknown>>,
root: Readonly<Record<string, unknown>>,
): Readonly<Record<string, unknown>> => {
const reference = schema.$ref;
if (typeof reference !== "string" || !reference.startsWith("#/$defs/"))
return schema;
const definition = objectValue(objectValue(root.$defs)?.[reference.slice(8)]);
return definition === undefined ? schema : definition;
};
const isObject = (value: unknown): value is Readonly<Record<string, unknown>> =>
typeof value === "object" && value !== null && !Array.isArray(value);
const objectValue = (
value: unknown,
): Readonly<Record<string, unknown>> | undefined =>
isObject(value) ? value : undefined;
+189 -2
View File
@@ -1,9 +1,196 @@
import { z } from "zod";
import type { ToolContract } from "../contracts/toolContracts.js";
/** Project the public contract fields accepted by MCP tool registration. */
export const toolRegistrationOptions = (contract: ToolContract) => ({
title: contract.title,
description: contract.description,
inputSchema: contract.inputSchema,
outputSchema: contract.outputSchema,
inputSchema: advertisedInputSchema(contract.inputSchema),
outputSchema: advertisedOutputSchema(contract.outputSchema),
annotations: contract.annotations,
});
/**
* Advertise the exact Zod contract while leaving validation to REA's adapter.
* The SDK otherwise converts validation failures to text-only JSON-RPC errors
* before REA can return its stable structured error envelope.
*/
const advertisedInputSchema = (schema: z.ZodObject) => ({
"~standard": {
version: 1 as const,
vendor: "rea",
validate: (input: unknown) => ({ value: input }),
jsonSchema: {
input: () =>
compactJsonSchema(
describeProperties(closeObjectSchemas(inputJsonSchema(schema))),
),
output: () =>
compactJsonSchema(
describeProperties(closeObjectSchemas(inputJsonSchema(schema))),
),
},
},
});
const advertisedOutputSchema = (schema: z.ZodObject) => {
const standard = schema["~standard"];
const converter = standard.jsonSchema?.output;
if (converter === undefined)
throw new TypeError(
"Tool output schema does not expose Standard JSON Schema",
);
return {
"~standard": {
...standard,
jsonSchema: {
input: () =>
compactJsonSchema(
closeObjectSchemas(converter({ target: "draft-2020-12" })),
),
output: () =>
compactJsonSchema(
closeObjectSchemas(converter({ target: "draft-2020-12" })),
),
},
},
};
};
const inputJsonSchema = (schema: z.ZodObject): Record<string, unknown> => {
const converter = schema["~standard"].jsonSchema?.input;
if (converter === undefined)
throw new TypeError(
"Tool input schema does not expose Standard JSON Schema",
);
return converter({ target: "draft-2020-12" });
};
const closeObjectSchemas = (
value: Readonly<Record<string, unknown>>,
): Record<string, unknown> => {
const closed = Object.fromEntries(
Object.entries(value).map(([key, child]) => [key, closeSchemaValue(child)]),
);
return value.type === "object" &&
isObject(value.properties) &&
value.additionalProperties === undefined
? { ...closed, additionalProperties: false }
: closed;
};
const closeSchemaValue = (value: unknown): unknown => {
if (Array.isArray(value)) return value.map(closeSchemaValue);
if (!isObject(value)) return value;
return closeObjectSchemas(value);
};
const describeProperties = (
value: Readonly<Record<string, unknown>>,
): Record<string, unknown> =>
Object.fromEntries(
Object.entries(value).map(([key, child]) => {
if (key !== "properties" || typeof child !== "object" || child === null)
return [key, describeValue(child)];
return [
key,
Object.fromEntries(
Object.entries(child).map(([property, schema]) => [
property,
isObject(schema) && typeof schema.description !== "string"
? {
...describeProperties(schema),
description: `${property.replaceAll("_", " ")}.`,
}
: describeValue(schema),
]),
),
];
}),
);
const describeValue = (value: unknown): unknown => {
if (Array.isArray(value)) return value.map(describeValue);
return isObject(value) ? describeProperties(value) : value;
};
const isObject = (value: unknown): value is Readonly<Record<string, unknown>> =>
typeof value === "object" && value !== null && !Array.isArray(value);
/** Replace repeated schema fragments with deterministic tool-local definitions. */
const compactJsonSchema = (
schema: Readonly<Record<string, unknown>>,
): Record<string, unknown> => {
const { $schema: _dialect, ...schemaBody } = schema;
const counts = new Map<string, number>();
collectSchemas(schemaBody, counts, true);
const candidates = [...counts.entries()]
.filter(([encoded, count]) => count > 1 && encoded.length >= 128)
.sort(
([left], [right]) =>
right.length - left.length || left.localeCompare(right),
)
.map(([encoded], index) => [encoded, `rea_${String(index)}`] as const);
if (candidates.length === 0) return schemaBody;
const names = new Map(candidates);
const definitions = Object.fromEntries(
candidates.map(([encoded, name]) => [
name,
replaceSchemas(JSON.parse(encoded), names, encoded),
]),
);
const compacted = replaceSchemas(schemaBody, names);
if (!isObject(compacted))
throw new TypeError("Compacted schema root is not an object");
return {
...compacted,
$defs: {
...(isObject(schemaBody.$defs) ? schemaBody.$defs : {}),
...definitions,
},
};
};
const collectSchemas = (
value: unknown,
counts: Map<string, number>,
root = false,
keywordContainer = false,
): void => {
if (Array.isArray(value)) {
for (const item of value) collectSchemas(item, counts);
return;
}
if (!isObject(value)) return;
if (!root && !keywordContainer && value.$ref === undefined) {
const encoded = JSON.stringify(value);
counts.set(encoded, (counts.get(encoded) ?? 0) + 1);
}
for (const [key, child] of Object.entries(value))
collectSchemas(child, counts, false, schemaMapKeyword(key));
};
const replaceSchemas = (
value: unknown,
names: ReadonlyMap<string, string>,
skipped?: string,
keywordContainer = false,
): unknown => {
if (Array.isArray(value))
return value.map((item) => replaceSchemas(item, names, skipped));
if (!isObject(value)) return value;
const encoded = JSON.stringify(value);
const name = names.get(encoded);
if (!keywordContainer && name !== undefined && encoded !== skipped)
return { $ref: `#/$defs/${name}` };
return Object.fromEntries(
Object.entries(value).map(([key, child]) => [
key,
replaceSchemas(child, names, skipped, schemaMapKeyword(key)),
]),
);
};
const schemaMapKeyword = (key: string): boolean =>
key === "properties" || key === "patternProperties" || key === "$defs";
+34 -20
View File
@@ -29,14 +29,15 @@ export const toCallToolResult = (
const errorResult = (error: AnalysisError): CallToolResult => {
const projected = projectAnalysisError(error);
const structuredContent = { error: projected };
return {
content: [
{
type: "text",
text: projected.message,
text: JSON.stringify(structuredContent),
},
],
structuredContent: { error: projected },
structuredContent,
isError: true,
};
};
@@ -46,30 +47,33 @@ const successResult = (
contract: ToolContract,
options: ToolResultOptions,
): CallToolResult => {
const candidate = contract.kind === "session" ? { result: value } : value;
const candidate =
compactEvidence(value) ??
(contract.kind === "session" ? { result: value } : value);
const parsed = contract.outputSchema.safeParse(candidate);
if (!parsed.success) {
const structuredContent = {
error: projectAnalysisError(
new AnalysisOutputError(
contract.name,
"output does not match the tool contract",
),
),
};
return {
content: [
{
type: "text",
text: "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",
text: JSON.stringify(structuredContent),
},
],
structuredContent: {
error: projectAnalysisError(
new AnalysisOutputError(
contract.name,
"output does not match the tool contract",
),
),
},
structuredContent,
isError: true,
};
}
return {
content: [
{ type: "text", text: formatValue(value) },
{ type: "text", text: JSON.stringify(parsed.data) },
...evidenceResourceLinks(
value,
contract.kind === "session" ||
@@ -80,6 +84,23 @@ const successResult = (
};
};
const compactEvidence = (value: JsonValue): JsonValue | undefined => {
if (
typeof value !== "object" ||
value === null ||
Array.isArray(value) ||
typeof value.evidence_id !== "string" ||
!/^ev_[a-f0-9]{64}$/u.test(value.evidence_id) ||
!("normalized_result" in value)
)
return undefined;
return {
result: value.normalized_result,
evidence_id: value.evidence_id,
evidence_uri: `rea://evidence/${value.evidence_id}`,
};
};
const evidenceResourceLinks = (
value: JsonValue,
available: boolean,
@@ -103,10 +124,3 @@ const evidenceResourceLinks = (
},
];
};
const formatValue = (value: JsonValue): string => {
if (value === null) return "OK";
if (typeof value === "string") return value;
if (typeof value === "object") return JSON.stringify(value, null, 2);
return String(value);
};