rea-agents 1.2.0 → 1.4.0

package/dist/server/registerInvestigationTools.js

@@ -1,7 +1,8 @@
+import { runCrossVersionInvestigation } from "../application/CrossVersionInvestigation.js";
 import { buildCallPath, callPathInputSchema } from "../domain/callPath.js";
 import { correlateStaticAndRuntime, staticRuntimeCorrelationInputSchema, } from "../domain/staticRuntimeCorrelation.js";
 import { reconstructionVerificationInputSchema, verifyReconstruction, } from "../domain/reconstructionVerification.js";
-import { changedBehaviorInputSchema, findChangedBehavior, } from "../domain/changedBehavior.js";
+import { changedBehaviorResultSchema, changedBehaviorInputSchema, findChangedBehavior, } from "../domain/changedBehavior.js";
 import { createEvidence } from "../domain/evidence.js";
 import { EvidenceIntegrityError } from "../domain/errors.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
@@ -9,21 +10,105 @@ import { err, ok } from "../domain/result.js";
 import { CALL_PATH_PROVIDER, CHANGED_BEHAVIOR_PROVIDER, RECONSTRUCTION_PROVIDER, STATIC_RUNTIME_PROVIDER, } from "./sessionToolPolicies.js";
 import { toCallToolResult } from "./toolResult.js";
 import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
+import { AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
+import { mcpProgressReporter } from "./mcpProgress.js";
+import { runDerivedOperation } from "./runDerivedOperation.js";
 /** Register Evidence-composed differential investigation workflows. */
-export const registerInvestigationTools = (server, session, contracts) => {
-    registerChangedBehavior(server, session, contracts[0]);
+export const registerInvestigationTools = (server, session, contracts, policies) => {
+    registerChangedBehavior(server, session, contracts[0], policies);
     registerCallPath(server, session, contracts[1]);
     registerStaticRuntime(server, session, contracts[2]);
     registerReconstruction(server, session, contracts[3]);
 };
-const registerChangedBehavior = (server, session, contract) => {
-    server.registerTool(contract.name, contractOptions(contract), (input) => {
+const investigationExecution = (session, signal, inputRoots, integrityContinueEnabled, progress) => ({
+    session,
+    signal,
+    inputRoots,
+    integrityContinueEnabled,
+    ...(progress === undefined ? {} : { progress }),
+});
+const isIncomplete = (status) => status === "unknown" || status === "truncated";
+const registerChangedBehavior = (server, session, contract, policies) => {
+    server.registerTool(contract.name, contractOptions(contract), async (input, context) => {
         const parsed = changedBehaviorInputSchema.parse(input);
+        if (parsed.investigation_run !== undefined) {
+            const progress = mcpProgressReporter(context);
+            if (policies.permissionAuthority !== undefined) {
+                const scopes = [
+                    {
+                        capability: "investigation_workspace_read",
+                        roots: [parsed.investigation_run.workspace_path],
+                    },
+                    {
+                        capability: "investigation_workspace_write",
+                        roots: [parsed.investigation_run.workspace_path],
+                    },
+                    {
+                        capability: "investigation_input",
+                        roots: [
+                            parsed.investigation_run.left_path,
+                            parsed.investigation_run.right_path,
+                        ],
+                    },
+                ];
+                for (const scope of scopes) {
+                    const authorized = await policies.permissionAuthority.authorize({
+                        ...scope,
+                        executables: [],
+                        environment_names: [],
+                        network: "none",
+                        mount: false,
+                        operation_identity: `${contract.name}:${scope.capability}:${scope.roots.join(":")}`,
+                    }, scope.capability === "investigation_input" ? "read" : "write");
+                    if (!authorized.ok)
+                        return toCallToolResult(err(authorized.error instanceof PermissionRequiredError
+                            ? authorized.error
+                            : new AnalysisProtocolError(authorized.error.message, {
+                                cause: authorized.error,
+                            })), contract);
+                }
+            }
+            const investigated = await runCrossVersionInvestigation(parsed.investigation_run, policies.evidenceFiles, investigationExecution(session, context.mcpReq.signal, policies.inputRoots, policies.integrityContinueEnabled?.() ?? false, progress));
+            if (!investigated.ok)
+                return toCallToolResult(investigated, contract);
+            const workspace = investigated.value.workspace;
+            if (session.retainInvestigationWorkspace(workspace) === "added")
+                server.sendResourceListChanged();
+            const result = changedBehaviorResultSchema.parse(investigated.value.evidence.normalized_result);
+            const toolResult = toCallToolResult(recordWorkflowEvidence(session, investigated.value.evidence, parsed.unknown_registry_approved, isIncomplete(result.behavior_status), {
+                question: `Automatic changed behavior run ${result.investigation_run?.run_id ?? "unknown"} remains ${result.behavior_status}`,
+                domain: "changed-behavior",
+                requiredAuthority: "controlled-replay",
+                requiredConfidence: "observed",
+                probes: [
+                    {
+                        operation: "capture_process_scenario",
+                        rationale: "Capture both versions under the same bounded scenario and environment.",
+                    },
+                ],
+            }), contract);
+            return {
+                ...toolResult,
+                content: [
+                    ...toolResult.content,
+                    {
+                        type: "resource_link",
+                        uri: `rea://workspace/${workspace.workspace_id}/revision/${String(workspace.revision)}`,
+                        name: `${workspace.workspace_id} revision ${String(workspace.revision)}`,
+                        description: "Immutable CAS-linked investigation workspace revision",
+                        mimeType: "application/json",
+                    },
+                ],
+            };
+        }
         const closure = evidenceClosure(session, comparisonClosure(parsed.comparisons));
         if (!closure.ok)
             return toCallToolResult(closure, contract);
         const links = closure.value;
-        const result = findChangedBehavior(parsed.comparisons, parsed.offset, parsed.limit);
+        const computed = await runDerivedOperation(context, contract.name, () => findChangedBehavior(parsed.comparisons, parsed.offset, parsed.limit));
+        if (!computed.ok)
+            return toCallToolResult(computed, contract);
+        const result = computed.value;
         const evidence = createEvidence(undefined, CHANGED_BEHAVIOR_PROVIDER, {
             predicateType: "rea.changed-behavior/v1",
             operation: contract.name,
@@ -38,9 +123,8 @@ const registerChangedBehavior = (server, session, contract) => {
             limitations: result.limitations,
             evidenceLinks: links,
         });
-        const recorded = recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.behavior_status === "unknown" ||
-            result.behavior_status === "truncated", {
-            question: `Changed behavior result ${evidence.evidence_id} remains ${result.behavior_status}`,
+        const recorded = recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, isIncomplete(result.behavior_status), {
+            question: "Did both versions behave the same under a complete controlled replay?",
             domain: "changed-behavior",
             requiredAuthority: "controlled-replay",
             requiredConfidence: "observed",
@@ -55,13 +139,16 @@ const registerChangedBehavior = (server, session, contract) => {
     });
 };
 const registerCallPath = (server, session, contract) => {
-    server.registerTool(contract.name, contractOptions(contract), (input) => {
+    server.registerTool(contract.name, contractOptions(contract), async (input, context) => {
         const parsed = callPathInputSchema.parse(input);
         const closure = evidenceClosure(session, functionEvidenceIds(parsed.functions));
         if (!closure.ok)
             return toCallToolResult(closure, contract);
         const links = closure.value;
-        const result = buildCallPath(parsed);
+        const computed = await runDerivedOperation(context, contract.name, () => buildCallPath(parsed));
+        if (!computed.ok)
+            return toCallToolResult(computed, contract);
+        const result = computed.value;
         const evidence = createEvidence(undefined, CALL_PATH_PROVIDER, {
             predicateType: "rea.call-path/v1",
             operation: contract.name,
@@ -80,7 +167,7 @@ const registerCallPath = (server, session, contract) => {
             evidenceLinks: links,
         });
         const recorded = recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.status === "unknown" || result.status === "truncated", {
-            question: `Call path ${parsed.start.address} → ${parsed.goal.address} is ${result.status}`,
+            question: "Can the requested call path be established from complete analysis?",
             domain: "call-path",
             requiredAuthority: "shipped-artifact",
             requiredConfidence: "derived",
@@ -95,7 +182,7 @@ const registerCallPath = (server, session, contract) => {
     });
 };
 const registerStaticRuntime = (server, session, contract) => {
-    server.registerTool(contract.name, contractOptions(contract), (input) => {
+    server.registerTool(contract.name, contractOptions(contract), async (input, context) => {
         const parsed = staticRuntimeCorrelationInputSchema.parse(input);
         const closure = evidenceClosure(session, comparisonClosure([
             ...parsed.static_comparisons,
@@ -104,7 +191,10 @@ const registerStaticRuntime = (server, session, contract) => {
         if (!closure.ok)
             return toCallToolResult(closure, contract);
         const links = closure.value;
-        const result = correlateStaticAndRuntime(parsed);
+        const computed = await runDerivedOperation(context, contract.name, () => correlateStaticAndRuntime(parsed));
+        if (!computed.ok)
+            return toCallToolResult(computed, contract);
+        const result = computed.value;
         const evidence = createEvidence(undefined, STATIC_RUNTIME_PROVIDER, {
             predicateType: "rea.static-runtime-correlation/v1",
             operation: contract.name,
@@ -120,7 +210,7 @@ const registerStaticRuntime = (server, session, contract) => {
             evidenceLinks: links,
         });
         return toCallToolResult(recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.status === "unknown" || result.status === "truncated", {
-            question: `Static/runtime correlation result ${evidence.evidence_id} is ${result.status}`,
+            question: "Does runtime behavior match the available static analysis?",
             domain: "static-runtime-correlation",
             requiredAuthority: null,
             requiredConfidence: "derived",
@@ -134,7 +224,7 @@ const registerStaticRuntime = (server, session, contract) => {
     });
 };
 const registerReconstruction = (server, session, contract) => {
-    server.registerTool(contract.name, contractOptions(contract), (input) => {
+    server.registerTool(contract.name, contractOptions(contract), async (input, context) => {
         const parsed = reconstructionVerificationInputSchema.parse(input);
         const owned = session.exportEvidenceBundle();
         const ownedUnknowns = new Set(owned.unknowns.map(({ revision_digest: digest }) => digest));
@@ -142,7 +232,10 @@ const registerReconstruction = (server, session, contract) => {
         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 result = verifyReconstruction(parsed.specification, owned, parsed.offset, parsed.limit);
+        const computed = await runDerivedOperation(context, contract.name, () => verifyReconstruction(parsed.specification, owned, parsed.offset, parsed.limit));
+        if (!computed.ok)
+            return toCallToolResult(computed, contract);
+        const result = computed.value;
         const closure = evidenceClosure(session, result.evidence_links);
         if (!closure.ok)
             return toCallToolResult(closure, contract);
@@ -163,7 +256,7 @@ const registerReconstruction = (server, session, contract) => {
             evidenceLinks: links,
         });
         return toCallToolResult(recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.status === "unknown", {
-            question: `Reconstruction ${result.specification_sha256} has unknown claims`,
+            question: "Does the reconstruction satisfy every declared claim?",
             domain: "reconstruction-verification",
             requiredAuthority: null,
             requiredConfidence: "derived",

package/dist/server/registerOfficialTools.js

@@ -1,9 +1,10 @@
 import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
+import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
 import { toCallToolResult } from "./toolResult.js";
 import { logToolExecution } from "./toolLogging.js";
 import { createEvidence } from "../domain/evidence.js";
 import { AnalysisCapabilityUnavailableError, UnknownRegistryError, } from "../domain/errors.js";
+import { mcpProgressReporter } from "./mcpProgress.js";
 /** Register direct bridge proxies, preserving MCP cancellation and typed errors. */
 export const registerOfficialTools = (server, analysis, options) => {
     for (const contract of OFFICIAL_TOOL_CONTRACTS) {
@@ -23,9 +24,24 @@ const registerOfficialTool = (server, analysis, contract, registration) => {
         annotations: contract.annotations,
     }, async (input, context) => {
         const arguments_ = projectOfficialArguments(contract, input);
+        const progress = mcpProgressReporter(context);
+        await progress.report({
+            phase: contract.name,
+            completed: 0,
+            total: 1,
+            message: "started",
+        });
         const result = await logToolExecution(registration.logger, contract.name, () => analysis.execute(contract.name, arguments_, {
             signal: context.mcpReq.signal,
+            progress,
         }));
+        await progress.report({
+            phase: contract.name,
+            completed: 1,
+            total: 1,
+            message: result.ok ? "completed" : "failed",
+            terminal: true,
+        });
         if (result.ok) {
             const evidence = createEvidence(result.value.subject ?? registration.activeTarget?.(), result.value.provider, {
                 operation: contract.name,
@@ -38,16 +54,18 @@ const registerOfficialTool = (server, analysis, contract, registration) => {
             const recorded = registration.recordEvidence?.(evidence);
             if (recorded !== undefined && !recorded.ok)
                 return toCallToolResult(recorded, contract);
-            return toCallToolResult({ ok: true, value: evidence }, contract);
+            return toCallToolResult({ ok: true, value: evidence }, contract, {
+                evidenceResourcesAvailable: recorded !== undefined,
+            });
         }
         if (result.error instanceof AnalysisCapabilityUnavailableError &&
             approvedUnknownTracking(input) &&
             registration.recordUnknown !== undefined) {
             const unknown = registration.recordUnknown({
                 approved: true,
-                question: `${contract.name} is unavailable: ${result.error.reason}`,
+                question: "The requested analysis is unavailable for the current target.",
                 severity: "medium",
-                domain: "provider-capability",
+                domain: "analysis-capability",
                 supporting_evidence_ids: [],
                 contradicting_evidence_ids: [],
                 required_authority: "shipped-artifact",
@@ -56,7 +74,7 @@ const registerOfficialTool = (server, analysis, contract, registration) => {
                 recommended_probes: [
                     {
                         operation: contract.name,
-                        rationale: "Use a provider that declares this capability available.",
+                        rationale: "Choose another analysis or target that can answer this question.",
                     },
                 ],
                 relationships: [],
@@ -70,19 +88,12 @@ const registerOfficialTool = (server, analysis, contract, registration) => {
     });
 };
 const projectOfficialArguments = (contract, input) => {
-    const parsed = jsonValueSchema.safeParse(input);
-    if (!parsed.success ||
-        typeof parsed.data !== "object" ||
-        parsed.data === null ||
-        Array.isArray(parsed.data)) {
-        // The SDK validates this with the same schema before invoking the callback.
-        throw new Error("Validated MCP tool input was not a JSON object");
-    }
+    const parsed = jsonObjectSchema.parse(contract.inputSchema.parse(input));
     const projected = {};
     for (const key of Object.keys(contract.inputSchema.shape)) {
         if (key === "unknown_registry_approved")
             continue;
-        projected[key] = parsed.data[key] ?? null;
+        projected[key] = jsonValueSchema.parse(parsed[key] ?? null);
     }
     return projected;
 };

package/dist/server/registerProcessComparisonTool.js

@@ -10,9 +10,10 @@ import { err } from "../domain/result.js";
 import { PROCESS_PROVIDER } from "./sessionToolPolicies.js";
 import { toCallToolResult } from "./toolResult.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { runDerivedOperation } from "./runDerivedOperation.js";
 /** Register deterministic process-capture comparison and contradiction tracking. */
 export const registerProcessComparisonTool = (server, session, contract, now = Date.now) => {
-    server.registerTool(contract.name, toolRegistrationOptions(contract), (input) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
         const parsed = z
             .object({
             left_evidence_id: z.string(),
@@ -28,12 +29,15 @@ export const registerProcessComparisonTool = (server, session, contract, now = D
             return toCallToolResult(validated, contract);
         let comparison;
         try {
-            comparison = compareProcessCaptures(parsed.left, parsed.right, {
+            const computed = await runDerivedOperation(context, contract.name, () => compareProcessCaptures(parsed.left, parsed.right, {
                 ...(parsed.max_capture_age_ms === undefined
                     ? {}
                     : { maxCaptureAgeMs: parsed.max_capture_age_ms }),
                 now,
-            });
+            }));
+            if (!computed.ok)
+                return toCallToolResult(computed, contract);
+            comparison = computed.value;
         }
         catch (cause) {
             return toCallToolResult(err(new EvidenceIntegrityError(cause instanceof Error
@@ -80,17 +84,11 @@ const validateCaptureSources = (session, parsed) => {
             evidence.confidence !== "observed" ||
             evidence.authority !== "controlled-replay" ||
             evidenceCapture === undefined ||
-            canonicalJson(evidenceCapture) !== canonicalJson(capture))
+            canonicalize(evidenceCapture) !== canonicalize(capture))
             return err(new EvidenceIntegrityError("Process comparison payload does not match its source Evidence"));
     }
     return { ok: true, value: null };
 };
-const canonicalJson = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Process capture could not be canonicalized");
-    return encoded;
-};
 const comparisonUnknownInput = (parsed, comparison) => {
     if (parsed.unknown_registry_approved !== true ||
         comparison.status === "unchanged")

package/dist/server/registerPrompts.js

@@ -0,0 +1,67 @@
+import { completable, } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { PROMPT_CONTRACTS, renderGuidedPrompt, } from "../contracts/promptContracts.js";
+import { createPromptCompletionSource, } from "./promptCompletion.js";
+const promptValuesSchema = z.record(z.string(), z.string());
+/** Register every guided workflow and its session-scoped argument completers. */
+export const registerGuidedPrompts = (server, analysis, session) => {
+    const completion = createPromptCompletionSource(analysis, session);
+    const prompts = new Map();
+    for (const contract of PROMPT_CONTRACTS)
+        prompts.set(contract.name, registerPrompt(server, contract, completion));
+    return {
+        update(contract) {
+            const prompt = prompts.get(contract.name);
+            if (prompt === undefined)
+                throw new RangeError(`Unknown guided prompt ${contract.name}`);
+            const argsSchema = promptArgumentsSchema(contract, completion);
+            prompt.update({
+                title: contract.title,
+                description: contract.description,
+                argsSchema,
+                callback: (arguments_) => promptResult(contract, arguments_),
+            });
+        },
+    };
+};
+const registerPrompt = (server, contract, completion) => {
+    const argsSchema = promptArgumentsSchema(contract, completion);
+    return server.registerPrompt(contract.name, {
+        title: contract.title,
+        description: contract.description,
+        argsSchema,
+    }, (arguments_) => promptResult(contract, arguments_));
+};
+const promptArgumentsSchema = (contract, completion) => {
+    const shape = {};
+    for (const [name, argument] of Object.entries(contract.arguments))
+        shape[name] = argumentSchema(argument, completion);
+    return z.object(shape);
+};
+const argumentSchema = (argument, completion) => {
+    const value = z
+        .string()
+        .trim()
+        .min(1)
+        .max(4_096)
+        .describe(argument.description);
+    const kind = argument.completion;
+    const completed = kind === undefined
+        ? value
+        : completable(value, async (partial, context) => [
+            ...(await completion.complete(kind, partial, context)),
+        ]);
+    return argument.required ? completed : completed.optional();
+};
+const promptResult = (contract, arguments_) => ({
+    description: contract.description,
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: renderGuidedPrompt(contract, promptValuesSchema.parse(arguments_)),
+            },
+        },
+    ],
+});

package/dist/server/registerSessionStatusTool.js

@@ -0,0 +1,52 @@
+import { binarySessionInputSchema, SESSION_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
+import { toCallToolResult } from "./toolResult.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { createServerIdentity } from "../serverIdentity.js";
+import { buildCapabilityInventory } from "../application/CapabilityInventory.js";
+/** Register the read-only provider and target status operation. */
+export const registerSessionStatusTool = (server, session, contract, startedAt, availabilityPolicy) => {
+    server.registerTool(contract.name, {
+        description: contract.description,
+        inputSchema: contract.inputSchema,
+        outputSchema: contract.outputSchema,
+        annotations: contract.annotations,
+    }, (input) => {
+        const parsed = binarySessionInputSchema.parse(input);
+        const client = server.server.getClientVersion();
+        const clientCapabilities = server.server.getClientCapabilities();
+        const status = session.status();
+        return toCallToolResult({
+            ok: true,
+            value: {
+                ...jsonObjectSchema.parse(status),
+                tool_availability: buildCapabilityInventory(status, availabilityPolicy()),
+                client_features: {
+                    elicitation_form: clientCapabilities?.elicitation?.form !== undefined,
+                    elicitation_url: clientCapabilities?.elicitation?.url !== undefined,
+                    roots: clientCapabilities?.roots !== undefined,
+                    sampling: clientCapabilities?.sampling !== undefined,
+                },
+                server_identity: createServerIdentity({
+                    startedAt,
+                    expected: {
+                        ...(parsed.expected_package_version === undefined
+                            ? {}
+                            : { package_version: parsed.expected_package_version }),
+                        ...(parsed.expected_catalog_digest === undefined
+                            ? {}
+                            : { catalog_digest: parsed.expected_catalog_digest }),
+                        ...(parsed.expected_server_path === undefined
+                            ? {}
+                            : { server_path: parsed.expected_server_path }),
+                    },
+                    ...(client === undefined ? {} : { client }),
+                    ...(server.server.getNegotiatedProtocolVersion() === undefined
+                        ? {}
+                        : {
+                            protocolVersion: server.server.getNegotiatedProtocolVersion(),
+                        }),
+                }),
+            },
+        }, contract);
+    });
+};