rea-agents 2.5.0 → 3.0.0

package/dist/server/registerEvidenceResources.js

@@ -4,13 +4,12 @@ import canonicalize from "canonicalize";
 import { registerJavaScriptApplicationGraphResource } from "./registerJavaScriptApplicationGraphResource.js";
 import { registerReconstructionObligationLedgerResource } from "./registerReconstructionObligationLedgerResource.js";
 import { registerReconstructionReadinessResource } from "./registerReconstructionReadinessResource.js";
-const evidenceUri = (evidenceId) => `rea://evidence/${evidenceId}`;
 /** Expose immutable session-owned Evidence v2 records as MCP resources. */
 export const registerEvidenceResources = (server, session) => {
     registerReconstructionCoverageResource(server, session);
     registerInvestigationWorkspaceResource(server, session);
     registerSessionEvidenceResource(server, session);
-    registerActiveResidualUnknownsResource(server, session);
+    registerEvidenceBundleResource(server, session);
     registerAnalysisSnapshotResource(server, session);
     registerArtifactPageResource(server, session);
     registerFunctionDossierResource(server, session);
@@ -19,20 +18,15 @@ export const registerEvidenceResources = (server, session) => {
     registerReconstructionReadinessResource(server, session);
     registerJavaScriptApplicationGraphResource(server, session);
     registerResidualUnknownResource(server, session);
+    session.onAnalysisSnapshotChanged?.(() => {
+        void server.server
+            .sendResourceUpdated({ uri: "rea://snapshot/current" })
+            .catch(() => undefined);
+    });
 };
 const registerReconstructionCoverageResource = (server, session) => {
     server.registerResource("reconstruction-coverage-revision", 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,
     }), {
         title: "Reconstruction coverage revision",
         description: "Canonical CAS-linked surfaces, owners, claims, verifiers, evidence, and completion boundaries.",
@@ -50,27 +44,7 @@ const registerReconstructionCoverageResource = (server, session) => {
 };
 const registerInvestigationWorkspaceResource = (server, session) => {
     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",
         description: "Immutable session-retained workspace with CAS linkage.",
@@ -88,21 +62,7 @@ const registerInvestigationWorkspaceResource = (server, session) => {
 };
 const registerSessionEvidenceResource = (server, session) => {
     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",
         description: "Immutable Evidence v2 records owned by this REA session.",
@@ -125,42 +85,52 @@ const registerSessionEvidenceResource = (server, session) => {
         };
     });
 };
-const registerActiveResidualUnknownsResource = (server, session) => {
-    server.registerResource("active-residual-unknowns", "rea://unknowns/active", {
-        title: "Active residual unknowns",
-        description: "Current unresolved session-owned residual unknown heads.",
+const registerEvidenceBundleResource = (server, session) => {
+    server.registerResource("evidence-bundle", new ResourceTemplate("rea://evidence-bundle/{bundleDigest}", {
+        list: undefined,
+    }), {
+        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,
+                },
+            ],
+        };
+    });
 };
 const registerAnalysisSnapshotResource = (server, session) => {
-    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",
-                    },
-                ],
-            };
-        },
-    }), {
+    server.registerResource("analysis-snapshot", "rea://snapshot/current", {
         title: "Analysis snapshot",
-        description: "Current provider-neutral analysis snapshot by content digest.",
+        description: "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. After metadata mutation, call open_binary again for the current target to begin a fresh cache.",
+            });
+        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,
+        });
     });
 };
 const registerArtifactPageResource = (server, session) => {
@@ -221,7 +191,6 @@ const registerEvidenceSectionResource = (server, session) => {
     server.registerResource("evidence-section", new ResourceTemplate("rea://evidence/{evidenceId}/section/{section}", {
         list: undefined,
         complete: {
-            evidenceId: (prefix) => evidenceIds(session, prefix),
             section: (prefix) => EVIDENCE_SECTIONS.filter((section) => section.startsWith(prefix)),
         },
     }), {
@@ -251,21 +220,7 @@ const registerEvidenceSectionResource = (server, session) => {
 };
 const registerResidualUnknownResource = (server, session) => {
     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",
         description: "Current session-owned residual unknown head.",
@@ -283,8 +238,6 @@ const registerResidualUnknownResource = (server, session) => {
         return jsonResource(uri.href, { current: unknown, history });
     });
 };
-const coverageWorkspaceUri = (workspaceId, revision) => `rea://reconstruction-coverage/${workspaceId}/revision/${String(revision)}`;
-const workspaceUri = (workspaceId, revision) => `rea://workspace/${workspaceId}/revision/${String(revision)}`;
 const EVIDENCE_SECTIONS = [
     "result",
     "terminal",
@@ -295,10 +248,6 @@ const EVIDENCE_SECTIONS = [
     "occurrences",
     "edges",
 ];
-const evidenceIds = (session, prefix) => session
-    .exportEvidenceBundle()
-    .records.map(({ evidence_id }) => evidence_id)
-    .filter((evidenceId) => evidenceId.startsWith(prefix));
 const stringVariable = (value, uri) => {
     if (typeof value !== "string")
         throw new ResourceNotFoundError(uri);

package/dist/server/registerInvestigationTools.js

@@ -114,8 +114,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);
     const toolResult = toCallToolResult(recordWorkflowEvidence(session, investigated.value.evidence, input.unknownRegistryApproved, isIncomplete(result.behavior_status), {
         question: `Automatic changed behavior run ${result.investigation_run?.run_id ?? "unknown"} remains ${result.behavior_status}`,

package/dist/server/registerJavaScriptApplicationGraphResource.js

@@ -5,10 +5,6 @@ export const registerJavaScriptApplicationGraphResource = (server, session) => {
     server.registerResource("javascript-application-graph-page", new ResourceTemplate("rea://evidence/{evidenceId}/application-graph/{collection}/offset/{offset}/limit/{limit}", {
         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)),
         },
     }), {

package/dist/server/registerReconstructionObligationLedgerResource.js

@@ -4,13 +4,6 @@ import { reconstructionObligationLedgerPageSchema } from "../domain/reconstructi
 export const registerReconstructionObligationLedgerResource = (server, session) => {
     server.registerResource("reconstruction-obligation-ledger-page", new ResourceTemplate("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)),
-        },
     }), {
         title: "Reconstruction obligation ledger page",
         description: "One deterministic Evidence v2-backed obligation page with full-ledger closure digest and summaries.",

package/dist/server/registerReconstructionReadinessResource.js

@@ -4,13 +4,6 @@ import { reconstructionReadinessReportSchema } from "../domain/reconstructionRea
 export const registerReconstructionReadinessResource = (server, session) => {
     server.registerResource("reconstruction-readiness-report", new ResourceTemplate("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)),
-        },
     }), {
         title: "Reconstruction readiness report",
         description: "Full deterministic nine-stage conformance report and replay identity.",

package/dist/server/registerSessionRecordTools.js

@@ -1,5 +1,5 @@
 import { readEvidenceBundle, writeEvidenceBundle, } from "../application/EvidenceBundleFiles.js";
-import { exportEvidenceBundleInputSchema, importEvidenceBundleInputSchema, listUnknownsInputSchema, SESSION_TOOL_CONTRACTS, verifyUnknownResolutionInputSchema, } from "../contracts/toolContracts.js";
+import { exportEvidenceBundleInputSchema, importEvidenceBundleInputSchema, listUnknownsInputSchema, snapshotEvidenceBundleInputSchema, SESSION_TOOL_CONTRACTS, verifyUnknownResolutionInputSchema, } from "../contracts/toolContracts.js";
 import { AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
 import { recordUnknownInputSchema, updateUnknownInputSchema, } from "../domain/residualUnknown.js";
 import { err, ok } from "../domain/result.js";
@@ -10,6 +10,7 @@ import { toCallToolResult } from "./toolResult.js";
 export const registerEvidenceTools = (registration) => {
     registerExportEvidenceTool(registration);
     registerImportEvidenceTool(registration);
+    registerSnapshotEvidenceTool(registration);
 };
 const registerExportEvidenceTool = ({ server, session, exportContract, filePolicy, permissionAuthority, }) => {
     server.registerTool(exportContract.name, toolRegistrationOptions(exportContract), async (input) => {
@@ -18,8 +19,6 @@ const registerExportEvidenceTool = ({ server, session, exportContract, filePolic
             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",
@@ -35,10 +34,38 @@ const registerExportEvidenceTool = ({ server, session, exportContract, filePolic
                 path: written.value.path,
                 bytes: written.value.bytes,
                 records: bundle.records.length,
+                unknowns: bundle.unknowns.length,
             }), exportContract)
             : toCallToolResult(written, exportContract);
     });
 };
+const registerSnapshotEvidenceTool = ({ server, session, snapshotContract, }) => {
+    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,
+        };
+        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, importContract, filePolicy, permissionAuthority, }) => {
     server.registerTool(importContract.name, toolRegistrationOptions(importContract), async (input) => {
         const parsedInput = safeParseToolInput(importEvidenceBundleInputSchema, input, importContract.name);
@@ -58,8 +85,6 @@ const registerImportEvidenceTool = ({ server, session, importContract, filePolic
         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({
                 imported: imported.value,
@@ -93,22 +118,53 @@ export const registerUnknownTools = ({ server, session, contracts, }) => {
         if (!parsed.ok)
             return toCallToolResult(parsed, listContract);
         const filters = parsed.value;
-        return toCallToolResult(ok(session.listUnknowns({
+        const all = session.listUnknowns({
             ...(filters.status === undefined ? {} : { status: filters.status }),
             ...(filters.severity === undefined
                 ? {}
                 : { severity: filters.severity }),
             ...(filters.domain === undefined ? {} : { domain: filters.domain }),
-        })), listContract);
+        });
+        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({
+            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`,
+            })),
+        });
     });
     server.registerTool(recordContract.name, toolRegistrationOptions(recordContract), (input) => {
         const parsed = safeParseToolInput(recordUnknownInputSchema, input, recordContract.name);
         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(updateContract.name, toolRegistrationOptions(updateContract), (input) => {
         const parsed = safeParseToolInput(updateUnknownInputSchema, input, updateContract.name);
@@ -116,8 +172,22 @@ export const registerUnknownTools = ({ server, session, contracts, }) => {
             return toCallToolResult(parsed, updateContract);
         const result = session.updateUnknown(parsed.value);
         if (result.ok)
-            server.sendResourceListChanged();
-        return toCallToolResult(result, updateContract);
+            void server.server
+                .sendResourceUpdated({
+                uri: `rea://unknown/${result.value.unknown_id}`,
+            })
+                .catch(() => undefined);
+        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(verifyContract.name, toolRegistrationOptions(verifyContract), (input) => {
         const parsed = safeParseToolInput(verifyUnknownResolutionInputSchema, input, verifyContract.name);

package/dist/server/registerSessionStatusTool.js

@@ -118,7 +118,7 @@ const recommendedActions = (open, alignment) => [
         : []),
     ...(!open
         ? [
-            "Route the supplied target directly: ASAR/JavaScript to analyze_javascript_application, unfamiliar packages to inspect_artifact, managed PE/CLI to inspect_managed_artifact, browser/Electron runtimes to their list-target tools, and native binaries to open_binary.",
+            "For a supplied target, route by format: ASAR/JavaScript to analyze_javascript_application; archive/package to open_binary(path), then inspect_artifact or inventory_artifact on the active target; managed PE/CLI to inspect_managed_artifact; browser/Electron runtimes to their list-target tools; native binaries to open_binary.",
         ]
         : [
             "Continue from the active target with binary_overview or a bounded target-specific query.",

package/dist/server/registerSessionTools.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+import { addressContextInputSchema, navigationContextInputSchema, SESSION_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
 import { toCallToolResult } from "./toolResult.js";
 import { logToolExecution } from "./toolLogging.js";
 import { ok } from "../domain/result.js";
@@ -27,6 +27,7 @@ import { registerReplayMachineTool } from "./registerReplayMachineTool.js";
 import { sessionAvailabilityPolicy, } from "./sessionAvailabilityPolicy.js";
 import { permissionFailure } from "./permissionFailure.js";
 import { registerCloseLifecycleTool } from "./registerCloseLifecycleTool.js";
+import { getNavigationContext, inspectAddressContext, } from "../application/AnalysisContextQueries.js";
 const recordProcessResidualUnknowns = (session, scenario, evidence, residuals) => {
     if (scenario.unknown_registry_approved !== true)
         return ok(null);
@@ -171,11 +172,28 @@ const registerRecordAndReplayTools = (server, session, logger) => {
     });
     registerReplayMachineTool(server, logger);
 };
+const registerContextTools = (server, session) => {
+    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, session, logger, options = {}) => {
     const processPolicy = options.processPolicy ?? DENY_PROCESS_POLICY;
     const evidenceFilePolicy = options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY;
     const analysisSnapshotFilePolicy = options.analysisSnapshotFilePolicy ?? DENY_EVIDENCE_FILE_POLICY;
     const [openContract, closeContract, statusContract, exportContract, importContract, captureContract, compareContract, compareArtifactsContract, compareFunctionsContract, compareBundlesContract, changedBehaviorContract, callPathContract, staticRuntimeContract, reconstructionContract,] = SESSION_TOOL_CONTRACTS;
+    const snapshotContract = SESSION_TOOL_CONTRACTS[19];
     registerLifecycleTools({
         server,
         session,
@@ -197,6 +215,7 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
         session,
         exportContract,
         importContract,
+        snapshotContract,
         filePolicy: evidenceFilePolicy,
         ...(options.permissionAuthority === undefined
             ? {}
@@ -238,4 +257,5 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
             : { permissionAuthority: options.permissionAuthority }),
     });
     registerRecordAndReplayTools(server, session, logger);
+    registerContextTools(server, session);
 };

package/dist/server/toolRegistrationOptions.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
+const ADVERTISED_INPUT_SCHEMAS = new WeakMap();
+const ADVERTISED_OUTPUT_SCHEMAS = new WeakMap();
 /** Project the public contract fields accepted by MCP tool registration. */
 export const toolRegistrationOptions = (contract) => ({
     title: contract.title,
     description: contract.description,
-    inputSchema: advertisedInputSchema(contract.inputSchema),
+    inputSchema: advertisedInputSchema(contract),
     outputSchema: advertisedOutputSchema(contract.outputSchema),
     annotations: contract.annotations,
 });
@@ -12,14 +14,14 @@ export const toolRegistrationOptions = (contract) => ({
  * The SDK otherwise converts validation failures to text-only JSON-RPC errors
  * before REA can return its stable structured error envelope.
  */
-const advertisedInputSchema = (schema) => ({
+const advertisedInputSchema = (contract) => ({
     "~standard": {
         version: 1,
         vendor: "rea",
         validate: (input) => ({ value: input }),
         jsonSchema: {
-            input: () => describeProperties(closeObjectSchemas(inputJsonSchema(schema))),
-            output: () => describeProperties(closeObjectSchemas(inputJsonSchema(schema))),
+            input: () => advertisedInputJsonSchema(contract),
+            output: () => advertisedInputJsonSchema(contract),
         },
     },
 });
@@ -32,12 +34,25 @@ const advertisedOutputSchema = (schema) => {
         "~standard": {
             ...standard,
             jsonSchema: {
-                input: () => describeRootProperties(closeObjectSchemas(converter({ target: "draft-2020-12" }))),
-                output: () => describeRootProperties(closeObjectSchemas(converter({ target: "draft-2020-12" }))),
+                input: () => advertisedOutputJsonSchema(schema, converter),
+                output: () => advertisedOutputJsonSchema(schema, converter),
             },
         },
     };
 };
+const advertisedInputJsonSchema = (contract) => cachedJsonSchema(ADVERTISED_INPUT_SCHEMAS, contract.inputSchema, () => ({
+    ...describeProperties(closeObjectSchemas(inputJsonSchema(contract.inputSchema))),
+    examples: contract.examples.map(({ input }) => input),
+}));
+const advertisedOutputJsonSchema = (schema, converter) => cachedJsonSchema(ADVERTISED_OUTPUT_SCHEMAS, schema, () => describeRootProperties(closeObjectSchemas(converter({ target: "draft-2020-12" }))));
+const cachedJsonSchema = (cache, schema, create) => {
+    const cached = cache.get(schema);
+    if (cached !== undefined)
+        return cached;
+    const created = create();
+    cache.set(schema, created);
+    return created;
+};
 const inputJsonSchema = (schema) => {
     const converter = schema["~standard"].jsonSchema?.input;
     if (converter === undefined)

package/dist/server/toolResult.js

@@ -49,6 +49,14 @@ const successResult = (value, contract, options) => {
                     : (compactEvidence(value, options.evidenceTextProjection) ??
                         options.evidenceTextProjection)),
             },
+            ...(hasResourceLinks(value, contract, options)
+                ? [
+                    {
+                        type: "text",
+                        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" ||
                 options.evidenceResourcesAvailable === true),
             ...(options.resourceLinks ?? []).map((resource) => ({
@@ -60,6 +68,10 @@ const successResult = (value, contract, options) => {
         structuredContent: candidate,
     };
 };
+const hasResourceLinks = (value, contract, options) => options.resourceLinks !== undefined && options.resourceLinks.length > 0
+    ? true
+    : evidenceResourceLinks(value, contract.kind === "session" ||
+        options.evidenceResourcesAvailable === true).length > 0;
 const compactEvidence = (value, resultProjection) => {
     if (typeof value !== "object" ||
         value === null ||