feat!: make evidence bundles canonical MCP resources

Add immutable session bundle snapshots, bounded resource discovery, paginated unknowns, mutable current analysis snapshots, and provider-neutral navigation/address context tools.

BREAKING CHANGE: export_evidence_bundle now requires a filesystem path and no longer returns an inline bundle.
This commit is contained in:
morluto
2026-07-29 17:36:40 +00:00
parent 3e1e8cd3f8
commit 1712e6d821
27 changed files with 901 additions and 291 deletions
+1 -4
View File
@@ -123,7 +123,7 @@ export const createServer = (
{
capabilities: {
tools: { listChanged: true },
resources: { listChanged: true },
resources: { listChanged: true, subscribe: true },
},
inputRequired: {
maxRounds: 3,
@@ -243,8 +243,6 @@ const createSessionRecorders = (
? undefined
: (evidence: Parameters<typeof session.recordEvidence>[0]) => {
const recorded = session.recordEvidence(evidence);
if (recorded.ok && recorded.value === "added")
server.sendResourceListChanged();
return recorded;
},
recordEvidenceWithUnknown:
@@ -255,7 +253,6 @@ const createSessionRecorders = (
input: Parameters<typeof session.recordEvidenceWithUnknown>[1],
) => {
const recorded = session.recordEvidenceWithUnknown(evidence, input);
if (recorded.ok) server.sendResourceListChanged();
return recorded;
},
});
+1 -4
View File
@@ -276,10 +276,7 @@ const registerApplicationFamily = async ({
session === undefined
? undefined
: (workspace) => {
const retained =
session.retainReconstructionCoverageWorkspace(workspace);
if (retained === "added") server.sendResourceListChanged();
return retained;
return session.retainReconstructionCoverageWorkspace(workspace);
},
replay: {
policy: options.javascriptReplayPolicy ?? {
+51 -127
View File
@@ -6,16 +6,12 @@ import {
import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
import type { BinarySessionPort } from "../application/BinarySessionPort.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { registerJavaScriptApplicationGraphResource } from "./registerJavaScriptApplicationGraphResource.js";
import { registerReconstructionObligationLedgerResource } from "./registerReconstructionObligationLedgerResource.js";
import { registerReconstructionReadinessResource } from "./registerReconstructionReadinessResource.js";
const evidenceUri = (evidenceId: string): string =>
`rea://evidence/${evidenceId}`;
/** Expose immutable session-owned Evidence v2 records as MCP resources. */
export const registerEvidenceResources = (
server: McpServer,
@@ -24,7 +20,7 @@ export const registerEvidenceResources = (
registerReconstructionCoverageResource(server, session);
registerInvestigationWorkspaceResource(server, session);
registerSessionEvidenceResource(server, session);
registerActiveResidualUnknownsResource(server, session);
registerEvidenceBundleResource(server, session);
registerAnalysisSnapshotResource(server, session);
registerArtifactPageResource(server, session);
registerFunctionDossierResource(server, session);
@@ -33,6 +29,11 @@ export const registerEvidenceResources = (
registerReconstructionReadinessResource(server, session);
registerJavaScriptApplicationGraphResource(server, session);
registerResidualUnknownResource(server, session);
session.onAnalysisSnapshotChanged?.(() => {
void server.server
.sendResourceUpdated({ uri: "rea://snapshot/current" })
.catch(() => undefined);
});
};
const registerReconstructionCoverageResource = (
@@ -44,21 +45,7 @@ const registerReconstructionCoverageResource = (
new ResourceTemplate(
"rea://reconstruction-coverage/{workspaceId}/revision/{revision}",
{
list: () => ({
resources: session
.reconstructionCoverageWorkspaces()
.map((workspace) => ({
uri: coverageWorkspaceUri(
workspace.workspace_id,
workspace.revision,
),
name: `${workspace.workspace_id} revision ${String(workspace.revision)}`,
title: `${workspace.name} coverage revision ${String(workspace.revision)}`,
description:
"Immutable evidence-backed reconstruction coverage workspace revision.",
mimeType: "application/json",
})),
}),
list: undefined,
},
),
{
@@ -89,34 +76,7 @@ const registerInvestigationWorkspaceResource = (
server.registerResource(
"investigation-workspace-revision",
new ResourceTemplate("rea://workspace/{workspaceId}/revision/{revision}", {
list: () => ({
resources: session.investigationWorkspaces().map((workspace) => ({
uri: workspaceUri(workspace.workspace_id, workspace.revision),
name: `${workspace.workspace_id} revision ${String(workspace.revision)}`,
title: `${workspace.name} revision ${String(workspace.revision)}`,
description: "Immutable CAS-linked investigation workspace revision.",
mimeType: "application/json",
})),
}),
complete: {
workspaceId: (prefix) =>
[
...new Set(
session
.investigationWorkspaces()
.map(({ workspace_id }) => workspace_id),
),
].filter((workspaceId) => workspaceId.startsWith(prefix)),
revision: (prefix, context) =>
session
.investigationWorkspaces()
.filter(
({ workspace_id }) =>
context?.arguments?.workspaceId === workspace_id,
)
.map(({ revision }) => String(revision))
.filter((revision) => revision.startsWith(prefix)),
},
list: undefined,
}),
{
title: "Investigation workspace revision",
@@ -145,22 +105,7 @@ const registerSessionEvidenceResource = (
server.registerResource(
"session-evidence",
new ResourceTemplate("rea://evidence/{evidenceId}", {
list: () => ({
resources: session.exportEvidenceBundle().records.map((evidence) => ({
uri: evidenceUri(evidence.evidence_id),
name: evidence.evidence_id,
title: `${evidence.operation} evidence`,
description: `Session-owned Evidence v2 record for ${evidence.operation}.`,
mimeType: "application/json",
})),
}),
complete: {
evidenceId: (prefix) =>
session
.exportEvidenceBundle()
.records.map(({ evidence_id }) => evidence_id)
.filter((evidenceId) => evidenceId.startsWith(prefix)),
},
list: undefined,
}),
{
title: "Session evidence",
@@ -186,23 +131,36 @@ const registerSessionEvidenceResource = (
);
};
const registerActiveResidualUnknownsResource = (
const registerEvidenceBundleResource = (
server: McpServer,
session: BinarySessionPort,
): void => {
server.registerResource(
"active-residual-unknowns",
"rea://unknowns/active",
"evidence-bundle",
new ResourceTemplate("rea://evidence-bundle/{bundleDigest}", {
list: undefined,
}),
{
title: "Active residual unknowns",
description: "Current unresolved session-owned residual unknown heads.",
title: "Evidence bundle",
description: "Immutable session-retained canonical Evidence v2 bundle.",
mimeType: "application/json",
},
(uri) =>
jsonResource(
uri.href,
session.listUnknowns().filter(({ status }) => status !== "resolved"),
),
(uri, variables) => {
const digest = stringVariable(variables.bundleDigest, uri.href);
if (!/^[a-f0-9]{64}$/u.test(digest))
throw new ResourceNotFoundError(uri.href);
const text = session.retainedEvidenceBundle(digest);
if (text === undefined) throw new ResourceNotFoundError(uri.href);
return {
contents: [
{
uri: uri.href,
mimeType: "application/json",
text,
},
],
};
},
);
};
@@ -212,36 +170,30 @@ const registerAnalysisSnapshotResource = (
): void => {
server.registerResource(
"analysis-snapshot",
new ResourceTemplate("rea://snapshot/{snapshotDigest}", {
list: () => {
const snapshot = session.exportAnalysisSnapshot();
if (!snapshot.ok) return { resources: [] };
const digest = contentDigest(snapshot.value);
return {
resources: [
{
uri: `rea://snapshot/${digest}`,
name: digest,
title: "Current analysis snapshot",
description: "Immutable projection of the current target cache.",
mimeType: "application/json",
},
],
};
},
}),
"rea://snapshot/current",
{
title: "Analysis snapshot",
description:
"Current provider-neutral analysis snapshot by content digest.",
"Mutable provider-neutral analysis snapshot for the current native target.",
mimeType: "application/json",
},
(uri, variables) => {
const requested = stringVariable(variables.snapshotDigest, uri.href);
(uri) => {
const snapshot = session.exportAnalysisSnapshot();
if (!snapshot.ok || contentDigest(snapshot.value) !== requested)
throw new ResourceNotFoundError(uri.href);
return jsonResource(uri.href, snapshot.value);
if (!snapshot.ok)
return jsonResource(uri.href, {
state: "unavailable",
reason: snapshot.error.message,
remediation:
"Open a native target with a concrete analysis profile, or rerun analysis after metadata mutation.",
});
return jsonResource(uri.href, {
state: "available",
target: snapshot.value.target,
profile: snapshot.value.binding,
content_digest: contentDigest(snapshot.value),
entry_count: snapshot.value.entries.length,
snapshot: snapshot.value,
});
},
);
};
@@ -333,7 +285,6 @@ const registerEvidenceSectionResource = (
new ResourceTemplate("rea://evidence/{evidenceId}/section/{section}", {
list: undefined,
complete: {
evidenceId: (prefix) => evidenceIds(session, prefix),
section: (prefix) =>
EVIDENCE_SECTIONS.filter((section) => section.startsWith(prefix)),
},
@@ -372,22 +323,7 @@ const registerResidualUnknownResource = (
server.registerResource(
"residual-unknown",
new ResourceTemplate("rea://unknown/{unknownId}", {
list: () => ({
resources: session.listUnknowns().map((unknown) => ({
uri: `rea://unknown/${unknown.unknown_id}`,
name: unknown.unknown_id,
title: unknown.question,
description: `Current ${unknown.status} residual unknown revision.`,
mimeType: "application/json",
})),
}),
complete: {
unknownId: (prefix) =>
session
.listUnknowns()
.map(({ unknown_id }) => unknown_id)
.filter((unknownId) => unknownId.startsWith(prefix)),
},
list: undefined,
}),
{
title: "Residual unknown",
@@ -408,12 +344,6 @@ const registerResidualUnknownResource = (
);
};
const coverageWorkspaceUri = (workspaceId: string, revision: number): string =>
`rea://reconstruction-coverage/${workspaceId}/revision/${String(revision)}`;
const workspaceUri = (workspaceId: string, revision: number): string =>
`rea://workspace/${workspaceId}/revision/${String(revision)}`;
const EVIDENCE_SECTIONS = [
"result",
"terminal",
@@ -425,12 +355,6 @@ const EVIDENCE_SECTIONS = [
"edges",
] as const;
const evidenceIds = (session: BinarySessionPort, prefix: string): string[] =>
session
.exportEvidenceBundle()
.records.map(({ evidence_id }) => evidence_id)
.filter((evidenceId) => evidenceId.startsWith(prefix));
const stringVariable = (value: unknown, uri: string): string => {
if (typeof value !== "string") throw new ResourceNotFoundError(uri);
return value;
+1 -2
View File
@@ -209,8 +209,7 @@ const runAutomaticInvestigation = async (input: {
);
if (!investigated.ok) return toCallToolResult(investigated, contract);
const workspace = investigated.value.workspace;
if (session.retainInvestigationWorkspace(workspace) === "added")
input.server.sendResourceListChanged();
session.retainInvestigationWorkspace(workspace);
const result = changedBehaviorResultSchema.parse(
investigated.value.evidence.normalized_result,
);
@@ -19,11 +19,6 @@ export const registerJavaScriptApplicationGraphResource = (
{
list: undefined,
complete: {
evidenceId: (prefix) =>
session
.exportEvidenceBundle()
.records.map(({ evidence_id }) => evidence_id)
.filter((evidenceId) => evidenceId.startsWith(prefix)),
collection: (prefix) =>
["nodes", "edges"].filter((name) => name.startsWith(prefix)),
},
@@ -18,17 +18,6 @@ export const registerReconstructionObligationLedgerResource = (
"rea://evidence/{evidenceId}/reconstruction-obligation-ledger",
{
list: undefined,
complete: {
evidenceId: (prefix) =>
session
.exportEvidenceBundle()
.records.filter(
({ predicate_type: predicateType }) =>
predicateType === "rea.reconstruction-obligation-ledger/v1",
)
.map(({ evidence_id: evidenceId }) => evidenceId)
.filter((evidenceId) => evidenceId.startsWith(prefix)),
},
},
),
{
@@ -18,17 +18,6 @@ export const registerReconstructionReadinessResource = (
"rea://evidence/{evidenceId}/reconstruction-readiness-report",
{
list: undefined,
complete: {
evidenceId: (prefix) =>
session
.exportEvidenceBundle()
.records.filter(
({ predicate_type: predicateType }) =>
predicateType === "rea.reconstruction-readiness-report/v1",
)
.map(({ evidence_id: evidenceId }) => evidenceId)
.filter((evidenceId) => evidenceId.startsWith(prefix)),
},
},
),
{
+96 -16
View File
@@ -10,6 +10,7 @@ import {
exportEvidenceBundleInputSchema,
importEvidenceBundleInputSchema,
listUnknownsInputSchema,
snapshotEvidenceBundleInputSchema,
SESSION_TOOL_CONTRACTS,
verifyUnknownResolutionInputSchema,
} from "../contracts/toolContracts.js";
@@ -33,6 +34,7 @@ interface EvidenceToolRegistration {
readonly session: BinarySessionPort;
readonly exportContract: (typeof SESSION_TOOL_CONTRACTS)[3];
readonly importContract: (typeof SESSION_TOOL_CONTRACTS)[4];
readonly snapshotContract: (typeof SESSION_TOOL_CONTRACTS)[19];
readonly filePolicy: EvidenceFilePolicy;
readonly permissionAuthority?: PermissionAuthority;
}
@@ -43,6 +45,7 @@ export const registerEvidenceTools = (
): void => {
registerExportEvidenceTool(registration);
registerImportEvidenceTool(registration);
registerSnapshotEvidenceTool(registration);
};
const registerExportEvidenceTool = ({
@@ -64,8 +67,6 @@ const registerExportEvidenceTool = ({
if (!parsedInput.ok) return toCallToolResult(parsedInput, exportContract);
const parsed = parsedInput.value;
const bundle = session.exportEvidenceBundle();
if (parsed.path === undefined)
return toCallToolResult(ok(bundle), exportContract);
const denied = await authorizeEvidencePath({
authority: permissionAuthority,
capability: "evidence_write",
@@ -86,6 +87,7 @@ const registerExportEvidenceTool = ({
path: written.value.path,
bytes: written.value.bytes,
records: bundle.records.length,
unknowns: bundle.unknowns.length,
}),
exportContract,
)
@@ -94,6 +96,44 @@ const registerExportEvidenceTool = ({
);
};
const registerSnapshotEvidenceTool = ({
server,
session,
snapshotContract,
}: EvidenceToolRegistration): void => {
server.registerTool(
snapshotContract.name,
toolRegistrationOptions(snapshotContract),
(input) => {
const parsed = safeParseToolInput(
snapshotEvidenceBundleInputSchema,
input,
snapshotContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, snapshotContract);
const snapshot = session.snapshotEvidenceBundle();
if (!snapshot.ok) return toCallToolResult(snapshot, snapshotContract);
const value = {
bundle_digest: snapshot.value.bundleDigest,
bundle_version: snapshot.value.bundleVersion,
bytes: snapshot.value.bytes,
records: snapshot.value.records,
unknowns: snapshot.value.unknowns,
bundle_uri: snapshot.value.uri,
} as const;
return toCallToolResult(ok(value), snapshotContract, {
resourceLinks: [
{
uri: snapshot.value.uri,
name: snapshot.value.bundleDigest,
description: "Immutable session-retained Evidence v2 bundle",
},
],
});
},
);
};
const registerImportEvidenceTool = ({
server,
session,
@@ -123,7 +163,6 @@ const registerImportEvidenceTool = ({
const loaded = await readEvidenceBundle(path, filePolicy);
if (!loaded.ok) return toCallToolResult(loaded, importContract);
const imported = session.importEvidenceBundle(loaded.value);
if (imported.ok && imported.value > 0) server.sendResourceListChanged();
return imported.ok
? toCallToolResult(
ok({
@@ -191,17 +230,40 @@ export const registerUnknownTools = ({
);
if (!parsed.ok) return toCallToolResult(parsed, listContract);
const filters = parsed.value;
const all = session.listUnknowns({
...(filters.status === undefined ? {} : { status: filters.status }),
...(filters.severity === undefined
? {}
: { severity: filters.severity }),
...(filters.domain === undefined ? {} : { domain: filters.domain }),
});
const items = all
.slice(filters.offset, filters.offset + filters.limit)
.map((unknown) => ({
unknown,
uri: `rea://unknown/${unknown.unknown_id}`,
}));
const nextOffset =
filters.offset + items.length < all.length
? filters.offset + items.length
: null;
return toCallToolResult(
ok(
session.listUnknowns({
...(filters.status === undefined ? {} : { status: filters.status }),
...(filters.severity === undefined
? {}
: { severity: filters.severity }),
...(filters.domain === undefined ? {} : { domain: filters.domain }),
}),
),
ok({
items,
offset: filters.offset,
limit: filters.limit,
total: all.length,
next_offset: nextOffset,
has_more: nextOffset !== null,
}),
listContract,
{
resourceLinks: items.map((unknown) => ({
uri: unknown.uri,
name: unknown.unknown.unknown_id,
description: `Current ${unknown.unknown.status} residual unknown revision`,
})),
},
);
},
);
@@ -216,8 +278,17 @@ export const registerUnknownTools = ({
);
if (!parsed.ok) return toCallToolResult(parsed, recordContract);
const result = session.recordUnknown(parsed.value);
if (result.ok) server.sendResourceListChanged();
return toCallToolResult(result, recordContract);
return result.ok
? toCallToolResult(result, recordContract, {
resourceLinks: [
{
uri: `rea://unknown/${result.value.unknown_id}`,
name: result.value.unknown_id,
description: "Current residual unknown head",
},
],
})
: toCallToolResult(result, recordContract);
},
);
server.registerTool(
@@ -231,8 +302,17 @@ export const registerUnknownTools = ({
);
if (!parsed.ok) return toCallToolResult(parsed, updateContract);
const result = session.updateUnknown(parsed.value);
if (result.ok) server.sendResourceListChanged();
return toCallToolResult(result, updateContract);
return result.ok
? toCallToolResult(result, updateContract, {
resourceLinks: [
{
uri: `rea://unknown/${result.value.unknown_id}`,
name: result.value.unknown_id,
description: "Updated residual unknown head",
},
],
})
: toCallToolResult(result, updateContract);
},
);
server.registerTool(
+60 -1
View File
@@ -2,7 +2,11 @@ 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 {
addressContextInputSchema,
navigationContextInputSchema,
SESSION_TOOL_CONTRACTS,
} from "../contracts/toolContracts.js";
import { toCallToolResult } from "./toolResult.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
@@ -52,6 +56,10 @@ import {
} from "./sessionAvailabilityPolicy.js";
import { permissionFailure } from "./permissionFailure.js";
import { registerCloseLifecycleTool } from "./registerCloseLifecycleTool.js";
import {
getNavigationContext,
inspectAddressContext,
} from "../application/AnalysisContextQueries.js";
const recordProcessResidualUnknowns = (
session: BinarySessionPort,
@@ -317,6 +325,54 @@ const registerRecordAndReplayTools = (
registerReplayMachineTool(server, logger);
};
const registerContextTools = (
server: McpServer,
session: BinarySessionPort,
): void => {
const navigationContract = SESSION_TOOL_CONTRACTS[20];
const addressContract = SESSION_TOOL_CONTRACTS[21];
server.registerTool(
navigationContract.name,
toolRegistrationOptions(navigationContract),
async (input, context) => {
const parsed = safeParseToolInput(
navigationContextInputSchema,
input,
navigationContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, navigationContract);
return toCallToolResult(
await getNavigationContext(
session,
parsed.value,
context.mcpReq.signal,
),
navigationContract,
);
},
);
server.registerTool(
addressContract.name,
toolRegistrationOptions(addressContract),
async (input, context) => {
const parsed = safeParseToolInput(
addressContextInputSchema,
input,
addressContract.name,
);
if (!parsed.ok) return toCallToolResult(parsed, addressContract);
return toCallToolResult(
await inspectAddressContext(
session,
parsed.value,
context.mcpReq.signal,
),
addressContract,
);
},
);
};
export const registerSessionTools = (
server: McpServer,
session: BinarySessionPort,
@@ -344,6 +400,7 @@ export const registerSessionTools = (
staticRuntimeContract,
reconstructionContract,
] = SESSION_TOOL_CONTRACTS;
const snapshotContract = SESSION_TOOL_CONTRACTS[19];
registerLifecycleTools({
server,
session,
@@ -365,6 +422,7 @@ export const registerSessionTools = (
session,
exportContract,
importContract,
snapshotContract,
filePolicy: evidenceFilePolicy,
...(options.permissionAuthority === undefined
? {}
@@ -411,4 +469,5 @@ export const registerSessionTools = (
: { permissionAuthority: options.permissionAuthority }),
});
registerRecordAndReplayTools(server, session, logger);
registerContextTools(server, session);
};
+21
View File
@@ -89,6 +89,14 @@ const successResult = (
options.evidenceTextProjection),
),
},
...(hasResourceLinks(value, contract, options)
? [
{
type: "text" as const,
text: "Full detail is available through MCP resources/read. Copy the opaque URI exactly. In Codex, call read_mcp_resource.",
},
]
: []),
...evidenceResourceLinks(
value,
contract.kind === "session" ||
@@ -104,6 +112,19 @@ const successResult = (
};
};
const hasResourceLinks = (
value: JsonValue,
contract: ToolContract,
options: ToolResultOptions,
): boolean =>
options.resourceLinks !== undefined && options.resourceLinks.length > 0
? true
: evidenceResourceLinks(
value,
contract.kind === "session" ||
options.evidenceResourcesAvailable === true,
).length > 0;
const compactEvidence = (
value: JsonValue,
resultProjection: JsonValue | undefined,