rea-agents 2.0.0 → 2.1.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";
@@ -16,6 +17,7 @@ import { registerElectronTools } from "./registerElectronTools.js";
 import { registerApplicationTools } from "./registerApplicationTools.js";
 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 +26,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 +39,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.",
     });
+    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 +129,49 @@ 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,
     });
     if (session !== undefined)
         registerManagedWorkflowTools(server, {
-            logger: toolLogger,
+            logger,
             recordEvidence,
             recordEvidenceWithUnknown,
             session,
@@ -126,25 +181,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 +230,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/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 {};