rea-agents 2.0.0 → 2.2.0

package/dist/server/createServer.js

@@ -1,4 +1,5 @@
-import { McpServer } from "@modelcontextprotocol/server";
+import { randomBytes } from "node:crypto";
+import { CLIENT_CAPABILITIES_META_KEY, createRequestStateCodec, McpServer, PROTOCOL_VERSION_META_KEY, } from "@modelcontextprotocol/server";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { registerEnhancedTools } from "./registerEnhancedTools.js";
 import { registerOfficialTools } from "./registerOfficialTools.js";
@@ -14,8 +15,11 @@ import { createServerIdentity } from "../serverIdentity.js";
 import { registerBrowserTools } from "./registerBrowserTools.js";
 import { registerElectronTools } from "./registerElectronTools.js";
 import { registerApplicationTools } from "./registerApplicationTools.js";
+const TARGET_FREE_INSTRUCTIONS = "REA analyzes shipped artifacts and approved runtime evidence; use repository tools for source. Route: ASAR/JavaScript -> analyze_javascript_application; archive/package -> inventory_artifact; managed PE/CLI -> inspect_managed_artifact; browser/Electron runtime -> list_browser_targets/list_electron_targets; native binary/database -> open_binary, then binary_overview. Start with summaries and cite Evidence IDs. Never repeat identical analysis or read full Evidence unless a missing detail requires it.";
+const ACTIVE_TARGET_INSTRUCTIONS = "REA analyzes the active reverse-engineering target. Start native analysis with binary_overview, then narrow with analyze_function, literal search, callers, callees, and xrefs. Prefer summary views, never repeat an identical call, and read full Evidence only when the task requires it.";
 import { LinuxJavaScriptReplayRunner } from "../replay/LinuxJavaScriptReplayRunner.js";
 import { SystemJavaScriptReplayHost } from "../replay/SystemJavaScriptReplayHost.js";
+import { PROCESS_CAPTURE_ELICITATION_POLICY, } from "./ProcessCaptureElicitation.js";
 /**
  * Construct one MCP server without acquiring subprocess resources.
  * Supplying a session adds target lifecycle tools; omitting it retains the
@@ -24,6 +28,11 @@ import { SystemJavaScriptReplayHost } from "../replay/SystemJavaScriptReplayHost
 export const createServer = (analysis, session, options = {}) => {
     const startedAt = new Date().toISOString();
     const logger = options.logger ?? silentLogger;
+    const permissionAuthority = options.permissionAuthority?.createConnectionAuthority();
+    const processCaptureStateCodec = createRequestStateCodec({
+        key: randomBytes(32),
+        ttlSeconds: PROCESS_CAPTURE_ELICITATION_POLICY.stateTtlSeconds,
+    });
     const server = new McpServer({
         name: PRODUCT_IDENTITY.mcpServerKey,
         version: PRODUCT_IDENTITY.packageVersion,
@@ -32,17 +41,88 @@ export const createServer = (analysis, session, options = {}) => {
             tools: { listChanged: true },
             resources: { listChanged: true },
         },
+        inputRequired: {
+            maxRounds: 3,
+            roundTimeoutMs: PROCESS_CAPTURE_ELICITATION_POLICY.roundTimeoutMs,
+        },
+        requestState: { verify: processCaptureStateCodec.verify },
         instructions: session === undefined
-            ? "Reverse-engineering tools for an active analysis target. Start with binary_overview."
-            : "Reverse-engineering tools for configured analysis providers. Open a target with open_binary, then start with binary_overview.",
+            ? ACTIVE_TARGET_INSTRUCTIONS
+            : TARGET_FREE_INSTRUCTIONS,
     });
+    server.server.onclose = () => {
+        permissionAuthority?.clearSessionGrants();
+    };
     session?.onAvailabilityChanged?.(() => server.sendToolListChanged());
+    registerServerIdentityResource(server, startedAt);
+    const toolLogger = logger.child({ layer: "server" });
+    const { activeTarget, recordEvidence, recordEvidenceWithUnknown } = createSessionRecorders(server, session);
+    const toolContext = {
+        server,
+        analysis,
+        session,
+        options,
+        logger: toolLogger,
+        permissionAuthority,
+        activeTarget,
+        recordEvidence,
+        recordEvidenceWithUnknown,
+    };
+    registerBinaryAnalysisTools(toolContext);
+    registerObservationTools(toolContext);
+    registerGuidedPrompts(server, analysis, session);
+    if (session !== undefined) {
+        registerEvidenceResources(server, session);
+        registerSessionTools(server, session, toolLogger, {
+            ...options,
+            ...(permissionAuthority === undefined ? {} : { permissionAuthority }),
+            startedAt,
+            processCaptureElicitation: {
+                stateCodec: processCaptureStateCodec,
+                supported: (context) => {
+                    const envelope = context.mcpReq.envelope;
+                    const version = envelope?.[PROTOCOL_VERSION_META_KEY];
+                    const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY];
+                    return (typeof version === "string" &&
+                        PROCESS_CAPTURE_ELICITATION_POLICY.protocolVersions.some((supported) => supported === version) &&
+                        isRecord(capabilities) &&
+                        isRecord(capabilities.elicitation) &&
+                        capabilities.elicitation.form !== undefined);
+                },
+                now: Date.now,
+                consumedNonces: new Map(),
+            },
+        });
+    }
+    return server;
+};
+const createSessionRecorders = (server, session) => ({
+    activeTarget: session === undefined ? undefined : () => session.activeTarget(),
+    recordEvidence: session === undefined
+        ? undefined
+        : (evidence) => {
+            const recorded = session.recordEvidence(evidence);
+            if (recorded.ok && recorded.value === "added")
+                server.sendResourceListChanged();
+            return recorded;
+        },
+    recordEvidenceWithUnknown: session === undefined
+        ? undefined
+        : (evidence, input) => {
+            const recorded = session.recordEvidenceWithUnknown(evidence, input);
+            if (recorded.ok)
+                server.sendResourceListChanged();
+            return recorded;
+        },
+});
+const registerServerIdentityResource = (server, startedAt) => {
     server.registerResource("server-identity", "rea://server/identity", {
         title: "REA server identity",
         description: "Live package, SDK, protocol, and catalog identity.",
         mimeType: "application/json",
     }, (uri) => {
         const client = server.server.getClientVersion();
+        const protocolVersion = server.server.getNegotiatedProtocolVersion();
         return {
             contents: [
                 {
@@ -51,72 +131,50 @@ export const createServer = (analysis, session, options = {}) => {
                     text: JSON.stringify(createServerIdentity({
                         startedAt,
                         ...(client === undefined ? {} : { client }),
-                        ...(server.server.getNegotiatedProtocolVersion() === undefined
-                            ? {}
-                            : {
-                                protocolVersion: server.server.getNegotiatedProtocolVersion(),
-                            }),
+                        ...(protocolVersion === undefined ? {} : { protocolVersion }),
                     }), null, 2),
                 },
             ],
         };
     });
-    const toolLogger = logger.child({ layer: "server" });
-    const activeTarget = session === undefined ? undefined : () => session.activeTarget();
-    const recordEvidence = session === undefined
-        ? undefined
-        : (evidence) => {
-            const recorded = session.recordEvidence(evidence);
-            if (recorded.ok && recorded.value === "added")
-                server.sendResourceListChanged();
-            return recorded;
-        };
-    const recordEvidenceWithUnknown = session === undefined
+};
+const registerBinaryAnalysisTools = ({ server, analysis, session, options, logger, permissionAuthority, activeTarget, recordEvidence, recordEvidenceWithUnknown, }) => {
+    const recordUnknown = session === undefined
         ? undefined
-        : (evidence, input) => {
-            const recorded = session.recordEvidenceWithUnknown(evidence, input);
-            if (recorded.ok)
-                server.sendResourceListChanged();
-            return recorded;
-        };
+        : (input) => session.recordUnknown(input);
     registerOfficialTools(server, analysis, {
-        logger: toolLogger,
+        logger,
         activeTarget,
         recordEvidence,
-        recordUnknown: session === undefined
-            ? undefined
-            : (input) => session.recordUnknown(input),
+        recordUnknown,
     });
     registerEnhancedTools(server, analysis, {
-        logger: toolLogger,
+        logger,
         activeTarget,
         analysisProfile: session === undefined ? undefined : () => session.analysisProfile(),
         recordEvidence,
-        recordUnknown: session === undefined
-            ? undefined
-            : (input) => session.recordUnknown(input),
+        recordUnknown,
     });
     registerNativeTools(server, analysis, {
-        logger: toolLogger,
+        logger,
         activeTarget,
         recordEvidence,
     });
     registerArtifactTools(server, analysis, {
-        logger: toolLogger,
+        logger,
         activeTarget,
         recordEvidence,
-        ...(options.permissionAuthority === undefined
-            ? {}
-            : { permissionAuthority: options.permissionAuthority }),
+        ...(permissionAuthority === undefined ? {} : { permissionAuthority }),
     });
     registerManagedTools(server, analysis, {
-        logger: toolLogger,
+        logger,
         activeTarget,
         recordEvidence,
+        session,
     });
     if (session !== undefined)
         registerManagedWorkflowTools(server, {
-            logger: toolLogger,
+            logger,
             recordEvidence,
             recordEvidenceWithUnknown,
             session,
@@ -126,25 +184,43 @@ export const createServer = (analysis, session, options = {}) => {
                     roots: [],
                     executablePath: "/usr/bin/dotnet",
                 },
-                authority: options.permissionAuthority,
+                authority: permissionAuthority,
             },
         });
+};
+const registerObservationTools = ({ server, session, options, logger, permissionAuthority, recordEvidence, recordEvidenceWithUnknown, }) => {
     registerBrowserTools(server, {
-        logger: toolLogger,
+        logger,
         browser: options.browserObservation,
-        permissionAuthority: options.permissionAuthority,
+        permissionAuthority,
         recordEvidence,
     });
     registerElectronTools(server, {
-        logger: toolLogger,
+        logger,
         electron: options.electronObservation,
-        permissionAuthority: options.permissionAuthority,
+        permissionAuthority,
         recordEvidence,
     });
     registerApplicationTools(server, {
-        logger: toolLogger,
+        logger,
         recordEvidence,
         recordEvidenceWithUnknown,
+        evidenceFilePolicy: options.evidenceFilePolicy ?? {
+            roots: [],
+            maxBytes: 1,
+            maxDepth: 1,
+            maxStringLength: 1,
+            maxNodes: 1,
+        },
+        permissionAuthority,
+        retainCoverageWorkspace: session === undefined
+            ? undefined
+            : (workspace) => {
+                const retained = session.retainReconstructionCoverageWorkspace(workspace);
+                if (retained === "added")
+                    server.sendResourceListChanged();
+                return retained;
+            },
         replay: {
             policy: options.javascriptReplayPolicy ?? {
                 enabled: false,
@@ -157,16 +233,8 @@ export const createServer = (analysis, session, options = {}) => {
             },
             host: options.javascriptReplayHost ?? new SystemJavaScriptReplayHost(),
             runner: options.javascriptReplayRunner ?? new LinuxJavaScriptReplayRunner(),
-            authority: options.permissionAuthority,
+            authority: permissionAuthority,
         },
     });
-    registerGuidedPrompts(server, analysis, session);
-    if (session !== undefined) {
-        registerEvidenceResources(server, session);
-        registerSessionTools(server, session, toolLogger, {
-            ...options,
-            startedAt,
-        });
-    }
-    return server;
 };
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/server/javascriptApplicationResult.js

@@ -0,0 +1,85 @@
+import { javascriptApplicationAnalysisResultSchema } from "../domain/javascriptApplicationAnalysis.js";
+import { compareCodePoints } from "../domain/javascriptApplicationGraph.js";
+import { javascriptApplicationAnalysisSummarySchema } from "../contracts/electronToolContracts.js";
+const DEFAULT_GRAPH_PAGE_LIMIT = 100;
+const ROOT_SAMPLE_LIMIT = 10;
+const TOP_FINDING_LIMIT = 20;
+const FINDING_PRIORITY = {
+    "browser-window": 0,
+    "electron-preload": 1,
+    "context-bridge-api": 2,
+    "ipc-channel": 3,
+    "ipc-handler": 4,
+    "electron-utility": 5,
+    endpoint: 6,
+    storage: 7,
+    worker: 8,
+    "service-worker": 9,
+    "native-addon": 10,
+    "native-export": 11,
+    "source-map": 12,
+};
+/** Project complete JavaScript application Evidence into a bounded agent result. */
+export const summarizeJavaScriptApplicationEvidence = (evidence) => {
+    const result = javascriptApplicationAnalysisResultSchema.parse(evidence.normalized_result);
+    const nodeKinds = new Map();
+    for (const node of result.graph.nodes)
+        nodeKinds.set(node.kind, (nodeKinds.get(node.kind) ?? 0) + 1);
+    const rootItems = result.graph.root_node_ids.slice(0, ROOT_SAMPLE_LIMIT);
+    const pageRoot = `rea://evidence/${evidence.evidence_id}/application-graph`;
+    const topFindings = [...result.graph.nodes]
+        .sort((left, right) => (FINDING_PRIORITY[left.kind] ?? Number.MAX_SAFE_INTEGER) -
+        (FINDING_PRIORITY[right.kind] ?? Number.MAX_SAFE_INTEGER) ||
+        compareCodePoints(left.node_id, right.node_id))
+        .slice(0, TOP_FINDING_LIMIT)
+        .map((node) => {
+        const observation = node.observations[0];
+        if (observation === undefined)
+            throw new TypeError("Application graph node has no observation");
+        return {
+            node_id: node.node_id,
+            kind: node.kind,
+            label: observation.label,
+            authority: observation.evidence.authority,
+            state: observation.evidence.state,
+            confidence: observation.evidence.confidence,
+            location: observation.evidence.location,
+        };
+    });
+    const { graph: _graph, ...summary } = result;
+    const unknowns = new Set([
+        ...result.limitations,
+        ...result.graph.limitations,
+    ]);
+    if (result.statistics.parse_failures > 0)
+        unknowns.add(`${String(result.statistics.parse_failures)} JavaScript file(s) could not be parsed.`);
+    if (result.statistics.truncated_scopes > 0)
+        unknowns.add(`${String(result.statistics.truncated_scopes)} analysis scope(s) were truncated.`);
+    if (result.graph.coverage.status !== "complete")
+        unknowns.add(`Application graph coverage is ${result.graph.coverage.status}; omitted facts remain unknown.`);
+    return javascriptApplicationAnalysisSummarySchema.parse({
+        ...summary,
+        unknowns: [...unknowns],
+        graph: {
+            graph_id: result.graph.graph_id,
+            node_count: result.graph.nodes.length,
+            edge_count: result.graph.edges.length,
+            roots: {
+                items: rootItems,
+                total: result.graph.root_node_ids.length,
+                truncated: rootItems.length < result.graph.root_node_ids.length,
+            },
+            node_kinds: [...nodeKinds]
+                .sort(([left], [right]) => compareCodePoints(left, right))
+                .map(([kind, count]) => ({ kind, count })),
+            top_findings: topFindings,
+            coverage: result.graph.coverage,
+            limitations: result.graph.limitations,
+            pages: {
+                nodes: `${pageRoot}/nodes/offset/0/limit/${String(DEFAULT_GRAPH_PAGE_LIMIT)}`,
+                edges: `${pageRoot}/edges/offset/0/limit/${String(DEFAULT_GRAPH_PAGE_LIMIT)}`,
+                page_limit: DEFAULT_GRAPH_PAGE_LIMIT,
+            },
+        },
+    });
+};

package/dist/server/registerApplicationTools/characterization.js

@@ -0,0 +1,57 @@
+import { executeNodeCharacterization, prepareNodeCharacterization, } from "../../application/NodeRuntimeCharacterizationService.js";
+import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
+import { nodeCharacterizationExecutionInputSchema, nodeCharacterizationExecutionOutputSchema, nodeCharacterizationPreparationInputSchema, nodeCharacterizationPreparationOutputSchema, } from "../../domain/nodeRuntimeCharacterization.js";
+import { parseEvidence } from "../../domain/evidence.js";
+import { logToolExecution } from "../toolLogging.js";
+import { toCallToolResult } from "../toolResult.js";
+import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
+import { safeParseToolInput } from "../toolInputValidation.js";
+import { mcpProgressReporter } from "../mcpProgress.js";
+import { recordSources } from "./helpers.js";
+const prepareContract = APPLICATION_TOOL_CONTRACTS[3];
+const executeContract = APPLICATION_TOOL_CONTRACTS[4];
+/** Register node runtime characterization prepare and execute tools. */
+export const registerCharacterizationTools = (server, options) => {
+    server.registerTool(prepareContract.name, toolRegistrationOptions(prepareContract), async (input, context) => {
+        const parsed = safeParseToolInput(nodeCharacterizationPreparationInputSchema, input, prepareContract.name);
+        if (!parsed.ok)
+            return toCallToolResult(parsed, prepareContract);
+        const result = await logToolExecution(options.logger, prepareContract.name, () => prepareNodeCharacterization(options.replay, parsed.value, {
+            signal: context.mcpReq.signal,
+            progress: mcpProgressReporter(context),
+        }));
+        if (!result.ok)
+            return toCallToolResult(result, prepareContract);
+        const output = nodeCharacterizationPreparationOutputSchema.parse(result.value);
+        const recorded = options.recordEvidence?.(parseEvidence(output.transformation_evidence));
+        if (recorded !== undefined && !recorded.ok)
+            return toCallToolResult(recorded, prepareContract);
+        return toCallToolResult(result, prepareContract, {
+            evidenceResourcesAvailable: options.recordEvidence !== undefined,
+        });
+    });
+    server.registerTool(executeContract.name, toolRegistrationOptions(executeContract), async (input, context) => {
+        const parsed = safeParseToolInput(nodeCharacterizationExecutionInputSchema, input, executeContract.name);
+        if (!parsed.ok)
+            return toCallToolResult(parsed, executeContract);
+        const result = await logToolExecution(options.logger, executeContract.name, () => executeNodeCharacterization(options.replay, parsed.value, {
+            signal: context.mcpReq.signal,
+            progress: mcpProgressReporter(context),
+        }));
+        if (!result.ok)
+            return toCallToolResult(result, executeContract);
+        const output = nodeCharacterizationExecutionOutputSchema.parse(result.value);
+        const sources = [
+            output.transformation_evidence,
+            ...output.replay.source_evidence,
+            ...(output.replay.evidence === null ? [] : [output.replay.evidence]),
+            output.evidence,
+        ].map((item) => parseEvidence(item));
+        const recorded = recordSources(options.recordEvidence, sources);
+        if (!recorded.ok)
+            return toCallToolResult(recorded, executeContract);
+        return toCallToolResult(result, executeContract, {
+            evidenceResourcesAvailable: options.recordEvidence !== undefined,
+        });
+    });
+};

package/dist/server/registerApplicationTools/compareVersions.js

@@ -0,0 +1,34 @@
+import { compareApplicationVersionsEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
+import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
+import { compareApplicationVersionsInputSchema } from "../../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { applicationVersionComparisonResultSchema } from "../../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { logToolExecution } from "../toolLogging.js";
+import { toCallToolResult } from "../toolResult.js";
+import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
+import { safeParseToolInput } from "../toolInputValidation.js";
+import { recordResult, recordSources } from "./helpers.js";
+const compareContract = APPLICATION_TOOL_CONTRACTS[1];
+/** Register the provider-neutral JavaScript version comparison tool. */
+export const registerCompareApplicationVersionsTool = (server, options) => {
+    server.registerTool(compareContract.name, toolRegistrationOptions(compareContract), async (input) => {
+        const parsedInput = safeParseToolInput(compareApplicationVersionsInputSchema, input, compareContract.name);
+        if (!parsedInput.ok)
+            return toCallToolResult(parsedInput, compareContract);
+        const parsed = parsedInput.value;
+        const result = await logToolExecution(options.logger, compareContract.name, () => Promise.resolve(compareApplicationVersionsEvidenceValidated(parsed)));
+        if (!result.ok)
+            return toCallToolResult(result, compareContract);
+        const sources = [
+            parsed.left,
+            parsed.right,
+            ...parsed.left_native_observations,
+            ...parsed.right_native_observations,
+        ];
+        const recorded = recordSources(options.recordEvidence, sources);
+        if (!recorded.ok)
+            return toCallToolResult(recorded, compareContract);
+        const comparison = applicationVersionComparisonResultSchema.parse(result.value.normalized_result);
+        const unknown = comparison.summary.unknown > 0;
+        return recordResult(options, compareContract, result.value, parsed.unknown_registry_approved === true && unknown);
+    });
+};

package/dist/server/registerApplicationTools/controlledReplay.js

@@ -0,0 +1,38 @@
+import { runControlledReplayValidated } from "../../application/JavaScriptReplayService.js";
+import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
+import { controlledReplayInputSchema, controlledReplayOutputSchema, } from "../../domain/javascriptReplay.js";
+import { parseEvidence } from "../../domain/evidence.js";
+import { logToolExecution } from "../toolLogging.js";
+import { toCallToolResult } from "../toolResult.js";
+import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
+import { safeParseToolInput } from "../toolInputValidation.js";
+import { mcpProgressReporter } from "../mcpProgress.js";
+import { recordSources } from "./helpers.js";
+const replayContract = APPLICATION_TOOL_CONTRACTS[2];
+/** Register the controlled JavaScript replay tool. */
+export const registerControlledReplayTool = (server, options) => {
+    server.registerTool(replayContract.name, toolRegistrationOptions(replayContract), async (input, context) => {
+        const parsedInput = safeParseToolInput(controlledReplayInputSchema, input, replayContract.name);
+        if (!parsedInput.ok)
+            return toCallToolResult(parsedInput, replayContract);
+        const parsed = parsedInput.value;
+        const result = await logToolExecution(options.logger, replayContract.name, () => runControlledReplayValidated(options.replay, parsed, {
+            signal: context.mcpReq.signal,
+            progress: mcpProgressReporter(context),
+        }));
+        if (!result.ok)
+            return toCallToolResult(result, replayContract);
+        const output = controlledReplayOutputSchema.parse(result.value);
+        if (output.evidence !== null) {
+            const sourcesRecorded = recordSources(options.recordEvidence, output.source_evidence.map((item) => parseEvidence(item)));
+            if (!sourcesRecorded.ok)
+                return toCallToolResult(sourcesRecorded, replayContract);
+            const recorded = options.recordEvidence?.(parseEvidence(output.evidence));
+            if (recorded !== undefined && !recorded.ok)
+                return toCallToolResult(recorded, replayContract);
+        }
+        return toCallToolResult(result, replayContract, {
+            evidenceResourcesAvailable: output.evidence !== null && options.recordEvidence !== undefined,
+        });
+    });
+};

package/dist/server/registerApplicationTools/coverage.js

@@ -0,0 +1,84 @@
+import { commitReconstructionCoverage, queryReconstructionCoverage, } from "../../application/ReconstructionCoverageService.js";
+import { readReconstructionCoverageWorkspace } from "../../application/ReconstructionCoverageWorkspaceStore.js";
+import { authorizeFileReadWithDeferredWrite, authorizeRootPermission, } from "../../application/DeferredFileAuthorization.js";
+import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
+import { reconstructionCoverageCommitInputSchema, reconstructionCoverageQueryInputSchema, } from "../../application/ReconstructionCoverageService.js";
+import { reconstructionClosureResultSchema } from "../../domain/reconstructionCoverage.js";
+import { AnalysisCapabilityUnavailableError, EvidenceIntegrityError, } from "../../domain/errors.js";
+import { err } from "../../domain/result.js";
+import { logToolExecution } from "../toolLogging.js";
+import { toCallToolResult } from "../toolResult.js";
+import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
+import { safeParseToolInput } from "../toolInputValidation.js";
+import { coverageWorkspaceUri } from "./helpers.js";
+const commitContract = APPLICATION_TOOL_CONTRACTS[5];
+const queryContract = APPLICATION_TOOL_CONTRACTS[6];
+/** Register reconstruction coverage commit and query tools. */
+export const registerCoverageTools = (server, options) => {
+    registerCommitTool(server, options);
+    registerQueryTool(server, options);
+};
+const registerCommitTool = (server, options) => {
+    server.registerTool(commitContract.name, toolRegistrationOptions(commitContract), async (input, context) => {
+        const parsed = safeParseToolInput(reconstructionCoverageCommitInputSchema, input, commitContract.name);
+        if (!parsed.ok)
+            return toCallToolResult(parsed, commitContract);
+        if (options.permissionAuthority === undefined)
+            return toCallToolResult(err(new AnalysisCapabilityUnavailableError("rea-reconstruction-coverage", commitContract.name, "workspace permission policy is not configured")), commitContract);
+        const authorization = await authorizeFileReadWithDeferredWrite(options.permissionAuthority, {
+            path: parsed.value.workspace_path,
+            readCapability: "investigation_workspace_read",
+            writeCapability: "investigation_workspace_write",
+            operation: commitContract.name,
+        });
+        if (!authorization.ok)
+            return toCallToolResult(authorization, commitContract);
+        const write = await authorization.value.authorizeWrite();
+        if (!write.ok)
+            return toCallToolResult(write, commitContract);
+        const result = await logToolExecution(options.logger, commitContract.name, () => commitReconstructionCoverage(parsed.value, options.evidenceFilePolicy, { signal: context.mcpReq.signal }));
+        if (!result.ok)
+            return toCallToolResult(result, commitContract);
+        options.retainCoverageWorkspace?.(parsed.value.workspace);
+        return toCallToolResult(result, commitContract, {
+            resourceLinks: options.retainCoverageWorkspace === undefined
+                ? []
+                : [
+                    {
+                        uri: coverageWorkspaceUri(parsed.value.workspace),
+                        name: parsed.value.workspace.workspace_id,
+                        description: "Session-retained reconstruction coverage workspace revision",
+                    },
+                ],
+        });
+    });
+};
+const registerQueryTool = (server, options) => {
+    server.registerTool(queryContract.name, toolRegistrationOptions(queryContract), async (input, context) => {
+        const parsed = safeParseToolInput(reconstructionCoverageQueryInputSchema, input, queryContract.name);
+        if (!parsed.ok)
+            return toCallToolResult(parsed, queryContract);
+        if (options.permissionAuthority === undefined)
+            return toCallToolResult(err(new AnalysisCapabilityUnavailableError("rea-reconstruction-coverage", queryContract.name, "workspace permission policy is not configured")), queryContract);
+        const authorized = await authorizeRootPermission(options.permissionAuthority, {
+            capability: "investigation_workspace_read",
+            roots: [parsed.value.workspace_path],
+            access: "read",
+            operation: queryContract.name,
+        });
+        if (!authorized.ok)
+            return toCallToolResult(authorized, queryContract);
+        const result = await logToolExecution(options.logger, queryContract.name, () => queryReconstructionCoverage(parsed.value, options.evidenceFilePolicy, Date.now(), { signal: context.mcpReq.signal }));
+        if (result.ok && options.retainCoverageWorkspace !== undefined) {
+            const closure = reconstructionClosureResultSchema.parse(result.value);
+            const loaded = await readReconstructionCoverageWorkspace(parsed.value.workspace_path, options.evidenceFilePolicy);
+            if (!loaded.ok)
+                return toCallToolResult(loaded, queryContract);
+            if (loaded.value === null ||
+                loaded.value.revision_sha256 !== closure.workspace_revision_sha256)
+                return toCallToolResult(err(new EvidenceIntegrityError("workspace changed while its closure was being retained")), queryContract);
+            options.retainCoverageWorkspace(loaded.value);
+        }
+        return toCallToolResult(result, queryContract);
+    });
+};

package/dist/server/registerApplicationTools/helpers.js

@@ -0,0 +1,42 @@
+import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
+import { toCallToolResult } from "../toolResult.js";
+export const coverageWorkspaceUri = (workspace) => `rea://reconstruction-coverage/${workspace.workspace_id}/revision/${String(workspace.revision)}`;
+export const recordSources = (recordEvidence, sources) => {
+    for (const source of sources) {
+        const recorded = recordEvidence?.(source);
+        if (recorded !== undefined && !recorded.ok)
+            return recorded;
+    }
+    return { ok: true, value: null };
+};
+export const recordResult = (options, contract, evidence, recordUnknown = false) => {
+    const recorded = recordUnknown
+        ? options.recordEvidenceWithUnknown?.(evidence, {
+            approved: true,
+            question: "Which application entities remain unmatched or ambiguous across these versions?",
+            severity: "medium",
+            domain: "application-version-comparison",
+            supporting_evidence_ids: [evidence.evidence_id],
+            contradicting_evidence_ids: [],
+            required_authority: "shipped-artifact",
+            required_confidence: "observed",
+            required_environment: null,
+            recommended_probes: [
+                {
+                    operation: "analyze_javascript_application",
+                    rationale: "Repeat static reconstruction with complete artifacts and source maps when available.",
+                },
+                {
+                    operation: "reconcile_javascript_runtime",
+                    rationale: "Add approved passive runtime Evidence without promoting it to static fact.",
+                },
+            ],
+            relationships: [],
+        })
+        : options.recordEvidence?.(evidence);
+    if (recorded !== undefined && !recorded.ok)
+        return toCallToolResult(recorded, contract);
+    return toCallToolResult({ ok: true, value: evidence }, contract, {
+        evidenceResourcesAvailable: recorded !== undefined,
+    });
+};

package/dist/server/registerApplicationTools/traceFeature.js

@@ -0,0 +1,26 @@
+import { traceApplicationFeatureEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
+import { APPLICATION_TOOL_CONTRACTS } from "../../contracts/applicationToolContracts.js";
+import { traceApplicationFeatureInputSchema } from "../../domain/javascriptFeatureTraceSchemas.js";
+import { logToolExecution } from "../toolLogging.js";
+import { toCallToolResult } from "../toolResult.js";
+import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
+import { safeParseToolInput } from "../toolInputValidation.js";
+import { recordResult, recordSources } from "./helpers.js";
+const traceContract = APPLICATION_TOOL_CONTRACTS[0];
+/** Register the provider-neutral JavaScript feature trace tool. */
+export const registerTraceFeatureTool = (server, options) => {
+    server.registerTool(traceContract.name, toolRegistrationOptions(traceContract), async (input) => {
+        const parsedInput = safeParseToolInput(traceApplicationFeatureInputSchema, input, traceContract.name);
+        if (!parsedInput.ok)
+            return toCallToolResult(parsedInput, traceContract);
+        const parsed = parsedInput.value;
+        const result = await logToolExecution(options.logger, traceContract.name, () => Promise.resolve(traceApplicationFeatureEvidenceValidated(parsed)));
+        if (!result.ok)
+            return toCallToolResult(result, traceContract);
+        const sources = [parsed.application, ...parsed.native_observations];
+        const recorded = recordSources(options.recordEvidence, sources);
+        if (!recorded.ok)
+            return toCallToolResult(recorded, traceContract);
+        return recordResult(options, traceContract, result.value);
+    });
+};

package/dist/server/registerApplicationTools/types.js

@@ -0,0 +1 @@
+export {};