rea-agents 2.4.0 → 3.0.0

package/dist/server/registerReconstructionObligationLedgerResource.js

@@ -0,0 +1,32 @@
+import { ResourceNotFoundError, ResourceTemplate, } from "@modelcontextprotocol/server";
+import { reconstructionObligationLedgerPageSchema } from "../domain/reconstructionObligationLedgerSchemas.js";
+/** Expose retained obligation-ledger pages as typed Evidence resources. */
+export const registerReconstructionObligationLedgerResource = (server, session) => {
+    server.registerResource("reconstruction-obligation-ledger-page", new ResourceTemplate("rea://evidence/{evidenceId}/reconstruction-obligation-ledger", {
+        list: undefined,
+    }), {
+        title: "Reconstruction obligation ledger page",
+        description: "One deterministic Evidence v2-backed obligation page with full-ledger closure digest and summaries.",
+        mimeType: "application/json",
+    }, (uri, variables) => {
+        const evidenceId = variables.evidenceId;
+        if (typeof evidenceId !== "string")
+            throw new ResourceNotFoundError(uri.href);
+        const evidence = session.evidenceById(evidenceId);
+        if (evidence === undefined ||
+            evidence.predicate_type !== "rea.reconstruction-obligation-ledger/v1")
+            throw new ResourceNotFoundError(uri.href);
+        const page = reconstructionObligationLedgerPageSchema.safeParse(evidence.normalized_result);
+        if (!page.success)
+            throw new ResourceNotFoundError(uri.href);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify({ evidence_id: evidence.evidence_id, page: page.data }, null, 2),
+                },
+            ],
+        };
+    });
+};

package/dist/server/registerReconstructionReadinessResource.js

@@ -0,0 +1,32 @@
+import { ResourceNotFoundError, ResourceTemplate, } from "@modelcontextprotocol/server";
+import { reconstructionReadinessReportSchema } from "../domain/reconstructionReadinessSchemas.js";
+/** Expose retained full readiness reports outside compact tool responses. */
+export const registerReconstructionReadinessResource = (server, session) => {
+    server.registerResource("reconstruction-readiness-report", new ResourceTemplate("rea://evidence/{evidenceId}/reconstruction-readiness-report", {
+        list: undefined,
+    }), {
+        title: "Reconstruction readiness report",
+        description: "Full deterministic nine-stage conformance report and replay identity.",
+        mimeType: "application/json",
+    }, (uri, variables) => {
+        const evidenceId = variables.evidenceId;
+        if (typeof evidenceId !== "string")
+            throw new ResourceNotFoundError(uri.href);
+        const evidence = session.evidenceById(evidenceId);
+        if (evidence === undefined ||
+            evidence.predicate_type !== "rea.reconstruction-readiness-report/v1")
+            throw new ResourceNotFoundError(uri.href);
+        const report = reconstructionReadinessReportSchema.safeParse(evidence.normalized_result);
+        if (!report.success)
+            throw new ResourceNotFoundError(uri.href);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify({ evidence_id: evidence.evidence_id, report: report.data }, null, 2),
+                },
+            ],
+        };
+    });
+};

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

@@ -15,9 +15,15 @@ export const registerSessionStatusTool = (options) => {
         const parsed = parsedInput.value;
         const client = server.server.getClientVersion();
         const clientCapabilities = server.server.getClientCapabilities();
+        const clientFeatures = {
+            elicitation_form: clientCapabilities?.elicitation?.form !== undefined,
+            elicitation_url: clientCapabilities?.elicitation?.url !== undefined,
+            roots: clientCapabilities?.roots !== undefined,
+            sampling: clientCapabilities?.sampling !== undefined,
+        };
         const status = session.status();
         const statusObject = jsonObjectSchema.parse(status);
-        const toolAvailability = buildCapabilityInventory(status, availabilityPolicy());
+        const toolAvailability = buildCapabilityInventory(status, availabilityPolicy(), clientFeatures);
         const serverIdentity = createServerIdentity({
             startedAt,
             expected: {
@@ -45,12 +51,7 @@ export const registerSessionStatusTool = (options) => {
                 status: statusObject,
                 toolAvailability,
                 serverIdentity,
-                clientFeatures: {
-                    elicitation_form: clientCapabilities?.elicitation?.form !== undefined,
-                    elicitation_url: clientCapabilities?.elicitation?.url !== undefined,
-                    roots: clientCapabilities?.roots !== undefined,
-                    sampling: clientCapabilities?.sampling !== undefined,
-                },
+                clientFeatures,
             }),
         }, contract);
     });
@@ -86,6 +87,7 @@ const projectSessionStatus = (options) => {
                 next_cursor: nextCursor < filtered.length ? nextCursor : null,
                 has_more: nextCursor < filtered.length,
             },
+            client_features: options.clientFeatures,
         });
     }
     return jsonObjectSchema.parse({
@@ -95,6 +97,7 @@ const projectSessionStatus = (options) => {
         active_provider: activeProvider,
         target: open ? targetFrom(options.status) : null,
         alignment: options.serverIdentity.alignment,
+        analysis_activity: options.status.analysis_activity,
         recommended_actions: recommendedActions(open, options.serverIdentity.alignment.state),
     });
 };
@@ -115,7 +118,7 @@ const recommendedActions = (open, alignment) => [
         : []),
     ...(!open
         ? [
-            "Route the supplied target directly: ASAR/JavaScript to analyze_javascript_application, packages to inventory_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,13 +1,13 @@
 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 { err, ok } from "../domain/result.js";
+import { ok } from "../domain/result.js";
 import { processScenarioSchema } from "../domain/processCapture.js";
 import { captureProcessScenario } from "../application/ProcessHarness.js";
 import { processCapturePermissionRequest } from "../application/ProcessCapturePermission.js";
-import { readAnalysisSnapshot, writeAnalysisSnapshot, } from "../application/AnalysisSnapshotFiles.js";
-import { AnalysisProtocolError, PermissionRequiredError, UnknownRegistryError, } from "../domain/errors.js";
+import { readAnalysisSnapshot } from "../application/AnalysisSnapshotFiles.js";
+import { UnknownRegistryError } from "../domain/errors.js";
 import { DENY_EVIDENCE_FILE_POLICY, DENY_PROCESS_POLICY, } from "./sessionToolPolicies.js";
 import { createProcessCaptureEvidence } from "../application/ProcessEvidence.js";
 import { registerProcessComparisonTool } from "./registerProcessComparisonTool.js";
@@ -17,7 +17,7 @@ import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
 import { safeParseToolInput } from "./toolInputValidation.js";
 import { registerBundleComparisonTool } from "./registerBundleComparisonTool.js";
 import { registerInvestigationTools } from "./registerInvestigationTools.js";
-import { closeBinaryInputSchema, openBinaryInputSchema, } from "../contracts/sessionLifecycleInputs.js";
+import { openBinaryInputSchema } from "../contracts/sessionLifecycleInputs.js";
 import { registerSessionStatusTool } from "./registerSessionStatusTool.js";
 import { mcpProgressReporter } from "./mcpProgress.js";
 import { authorizeProcessCaptureWithElicitation, } from "./ProcessCaptureElicitation.js";
@@ -25,15 +25,9 @@ import { isInputRequiredResult } from "@modelcontextprotocol/server";
 import { registerEvidenceTools, registerUnknownTools, } from "./registerSessionRecordTools.js";
 import { registerReplayMachineTool } from "./registerReplayMachineTool.js";
 import { sessionAvailabilityPolicy, } from "./sessionAvailabilityPolicy.js";
-const permissionFailure = (failure) => {
-    if (failure.ok)
-        return err(new AnalysisProtocolError("Expected a denied permission"));
-    return err(failure.error instanceof PermissionRequiredError
-        ? failure.error
-        : new AnalysisProtocolError(failure.error.message, {
-            cause: failure.error,
-        }));
-};
+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);
@@ -170,49 +164,6 @@ const registerOpenLifecycleTool = ({ server, session, logger, contracts: [openCo
             : toCallToolResult(opened, openContract);
     });
 };
-const registerCloseLifecycleTool = ({ server, session, logger, contracts: [, closeContract], snapshotFilePolicy, permissionAuthority, }) => {
-    server.registerTool(closeContract.name, toolRegistrationOptions(closeContract), async (input) => {
-        const parsedInput = safeParseToolInput(closeBinaryInputSchema, input, closeContract.name);
-        if (!parsedInput.ok)
-            return toCallToolResult(parsedInput, closeContract);
-        const parsed = parsedInput.value;
-        if (parsed.snapshot_path === undefined) {
-            const closed = await logToolExecution(logger, closeContract.name, () => session.close());
-            if (closed.ok)
-                server.sendToolListChanged();
-            return toCallToolResult(closed, closeContract);
-        }
-        if (permissionAuthority !== undefined) {
-            const authorized = await permissionAuthority.authorize({
-                capability: "snapshot_write",
-                roots: [parsed.snapshot_path],
-                executables: [],
-                environment_names: [],
-                network: "none",
-                mount: false,
-                operation_identity: `close_binary:snapshot:${parsed.snapshot_path}`,
-            }, "write");
-            if (!authorized.ok)
-                return toCallToolResult(permissionFailure(authorized), closeContract);
-        }
-        const snapshot = session.exportAnalysisSnapshot();
-        if (!snapshot.ok)
-            return toCallToolResult(snapshot, closeContract);
-        const written = await writeAnalysisSnapshot(snapshot.value, parsed.snapshot_path, parsed.overwrite, snapshotFilePolicy);
-        if (!written.ok)
-            return toCallToolResult(written, closeContract);
-        const closed = await logToolExecution(logger, closeContract.name, () => session.close());
-        if (closed.ok)
-            server.sendToolListChanged();
-        return closed.ok
-            ? toCallToolResult(ok({
-                path: written.value.path,
-                bytes: written.value.bytes,
-                entries: snapshot.value.entries.length,
-            }), closeContract)
-            : toCallToolResult(closed, closeContract);
-    });
-};
 const registerRecordAndReplayTools = (server, session, logger) => {
     registerUnknownTools({
         server,
@@ -221,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,
@@ -233,7 +201,11 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
         contracts: [openContract, closeContract, statusContract],
         snapshotFilePolicy: analysisSnapshotFilePolicy,
         startedAt: options.startedAt ?? new Date().toISOString(),
-        availabilityPolicy: sessionAvailabilityPolicy(options.availabilityPolicy, processPolicy, evidenceFilePolicy, options.investigationInputRoots ?? []),
+        availabilityPolicy: sessionAvailabilityPolicy(options.availabilityPolicy, {
+            processPolicy,
+            evidenceFilePolicy,
+            investigationInputRoots: options.investigationInputRoots ?? [],
+        }),
         ...(options.permissionAuthority === undefined
             ? {}
             : { permissionAuthority: options.permissionAuthority }),
@@ -243,6 +215,7 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
         session,
         exportContract,
         importContract,
+        snapshotContract,
         filePolicy: evidenceFilePolicy,
         ...(options.permissionAuthority === undefined
             ? {}
@@ -284,4 +257,5 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
             : { permissionAuthority: options.permissionAuthority }),
     });
     registerRecordAndReplayTools(server, session, logger);
+    registerContextTools(server, session);
 };

package/dist/server/sessionAvailabilityPolicy.js

@@ -1,11 +1,13 @@
 /** Select configured availability reporting or the target-free defaults. */
-export const sessionAvailabilityPolicy = (configured, processPolicy, evidenceFilePolicy, investigationInputRoots) => configured ??
+export const sessionAvailabilityPolicy = (configured, defaults) => configured ??
     (() => ({
-        processCaptureEnabled: processPolicy.enabled,
-        evidenceFileRoots: evidenceFilePolicy.roots.length,
-        investigationInputRoots: investigationInputRoots.length,
-        browserObservationEnabled: false,
-        electronObservationEnabled: false,
-        javascriptReplayEnabled: false,
-        managedRuntimeEnabled: false,
+        processCaptureEnabled: defaults.processPolicy.enabled,
+        evidenceFileRoots: defaults.evidenceFilePolicy.roots.length,
+        investigationInputRoots: defaults.investigationInputRoots.length,
+        browserObservationEnabled: defaults.optionalFeatures?.browserObservationEnabled ?? false,
+        browserScenarioEnabled: defaults.optionalFeatures?.browserScenarioEnabled ?? false,
+        electronObservationEnabled: defaults.optionalFeatures?.electronObservationEnabled ?? false,
+        v8InspectorObservationEnabled: defaults.optionalFeatures?.v8InspectorObservationEnabled ?? false,
+        javascriptReplayEnabled: defaults.optionalFeatures?.javascriptReplayEnabled ?? false,
+        managedRuntimeEnabled: defaults.optionalFeatures?.managedRuntimeEnabled ?? false,
     }));

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 ||