rea-agents 6.2.0 → 6.4.0

package/dist/server/registerArtifactComparisonTool.js

@@ -6,9 +6,12 @@ import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
 import { runDerivedOperation } from "./runDerivedOperation.js";
 import { ARTIFACT_COMPARISON_PROVIDER } from "../application/InvestigationProviders.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { withAdmittedAnalysis } from "./analysisAdmission.js";
+import { runAdmittedToolOperation } from "./admittedToolOperation.js";
 /** Register Evidence-backed deterministic artifact comparison. */
 export const registerArtifactComparisonTool = (server, session, contract) => {
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
+    const admission = withAdmittedAnalysis({ kind: "session", session });
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => runAdmittedToolOperation(server, admission, contract.name, context.mcpReq.signal, async () => {
         const computed = await runDerivedOperation(context, contract.name, () => {
             const left = parseEvidence(input.left);
             const right = parseEvidence(input.right);
@@ -39,7 +42,7 @@ export const registerArtifactComparisonTool = (server, session, contract) => {
             evidenceLinks: [...leftEvidenceIds, ...rightEvidenceIds],
         });
         return server.delivery.toEvidenceToolResult(evidence, contract, recordDerivedEvidence(session, evidence, artifactUnknownInput(left, right, comparison.status, evidence.evidence_id)));
-    });
+    }));
 };
 const artifactUnknownInput = (left, right, status, comparisonEvidenceId) => {
     if (status === "unchanged")

package/dist/server/registerArtifactTools.js

@@ -2,8 +2,8 @@ import { ARTIFACT_TOOL_CONTRACTS } from "../contracts/artifactToolContracts.js";
 import { registerEvidenceTools } from "./registerEvidenceTools.js";
 import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
 /** Register deterministic artifact inventory and safe extraction operations. */
-export const registerArtifactTools = (server, analysis, options) => {
-    registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, {
+export const registerArtifactTools = (server, options) => {
+    registerEvidenceTools(server, ARTIFACT_TOOL_CONTRACTS, {
         ...options,
         sourceEvidence: (operation, result) => operation === "inspect_artifact"
             ? artifactInspectionResultSchema

package/dist/server/registerBinaryDiagnosticsTools.js

@@ -1,14 +1,26 @@
+import { summarizeRetainedAnalysis } from "../application/analysisView/AnalysisViewService.js";
 import { toolContract } from "../contracts/toolContracts.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { runAdmittedToolOperation } from "./admittedToolOperation.js";
 /** Bind offline layout inspection to its named contract and session Evidence owner. */
-export const registerBinaryDiagnosticsTools = (server, service, logger, recordEvidence) => {
+export const registerBinaryDiagnosticsTools = (server, service, logger, recordEvidence, evidenceById, withAdmittedAnalysis) => {
     const contract = toolContract("inspect_binary_layout");
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
-        const result = await logToolExecution(logger, contract.name, () => service.inspect(input, { signal: context.mcpReq.signal }));
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async ({ detail, ...request }, context) => runAdmittedToolOperation(server, withAdmittedAnalysis, contract.name, context.mcpReq.signal, async () => {
+        const result = await logToolExecution(logger, contract.name, async () => {
+            const inspected = await service.inspect(request, {
+                signal: context.mcpReq.signal,
+            });
+            return detail === "summary" && inspected.ok
+                ? summarizeRetainedAnalysis(inspected.value, {
+                    recordEvidence,
+                    evidenceById,
+                })
+                : inspected;
+        });
         if (!result.ok)
             return server.delivery.toCallToolResult(result, contract);
         const recorded = recordEvidence?.(result.value);
         return server.delivery.toEvidenceToolResult(result.value, contract, recorded);
-    });
+    }));
 };

package/dist/server/registerBrowserScenarioTool.js

@@ -5,6 +5,7 @@ import { toolContract } from "../contracts/toolContracts.js";
 import { browserScenarioSchema } from "../domain/browserScenario.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { runAdmittedToolOperation } from "./admittedToolOperation.js";
 /** Register the browser scenario tool with execution-time provider diagnostics. */
 export const registerBrowserScenarioTool = (server, options) => {
     const contract = toolContract("capture_browser_scenario");
@@ -12,12 +13,14 @@ export const registerBrowserScenarioTool = (server, options) => {
         const scenario = browserScenarioSchema.parse(input);
         if (options.loadFailure !== undefined)
             return server.delivery.toCallToolResult(err(optionalProviderUnavailable(options.loadFailure, contract.name)), contract);
-        const result = await logToolExecution(options.logger, contract.name, () => captureBrowserScenario(options.provider, scenario, {
-            signal: context.mcpReq.signal,
-        }));
-        if (!result.ok)
-            return server.delivery.toCallToolResult(result, contract);
-        const recorded = options.recordEvidence?.(result.value);
-        return server.delivery.toEvidenceToolResult(result.value, contract, recorded);
+        return runAdmittedToolOperation(server, options.withAdmittedAnalysis, contract.name, context.mcpReq.signal, async () => {
+            const result = await logToolExecution(options.logger, contract.name, () => captureBrowserScenario(options.provider, scenario, {
+                signal: context.mcpReq.signal,
+            }));
+            if (!result.ok)
+                return server.delivery.toCallToolResult(result, contract);
+            const recorded = options.recordEvidence?.(result.value);
+            return server.delivery.toEvidenceToolResult(result.value, contract, recorded);
+        });
     });
 };

package/dist/server/registerBrowserTools.js

@@ -7,10 +7,11 @@ import { inspectWebPageInputSchema } from "../domain/browserObservation.js";
 import { mcpProgressReporter } from "./mcpProgress.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { runAdmittedToolOperation } from "./admittedToolOperation.js";
 /** Register browser tools with execution-time provider diagnostics. */
 // oxlint-disable-next-line max-lines-per-function -- direct SDK calls retain each schema-handler type correlation.
 export const registerBrowserTools = (server, options) => {
-    const registration = { ...options, delivery: server.delivery };
+    const registration = { ...options, delivery: server.delivery, server };
     const listContract = toolContract("list_browser_targets");
     const inspectContract = toolContract("inspect_web_page");
     const analyzeContract = toolContract("analyze_web_bundle");
@@ -46,12 +47,14 @@ const runBrowserTool = async (options, contract, request, execute) => {
     const { input, context } = request;
     if (options.loadFailure !== undefined)
         return options.delivery.toCallToolResult(err(optionalProviderUnavailable(options.loadFailure, contract.name)), contract);
-    const result = await logToolExecution(options.logger, contract.name, () => execute(input, {
-        signal: context.mcpReq.signal,
-        progress: mcpProgressReporter(context),
-    }));
-    if (!result.ok)
-        return options.delivery.toCallToolResult(result, contract);
-    const recorded = options.recordEvidence?.(result.value);
-    return options.delivery.toEvidenceToolResult(result.value, contract, recorded);
+    return runAdmittedToolOperation(options.server, options.withAdmittedAnalysis, contract.name, context.mcpReq.signal, async () => {
+        const result = await logToolExecution(options.logger, contract.name, () => execute(input, {
+            signal: context.mcpReq.signal,
+            progress: mcpProgressReporter(context),
+        }));
+        if (!result.ok)
+            return options.delivery.toCallToolResult(result, contract);
+        const recorded = options.recordEvidence?.(result.value);
+        return options.delivery.toEvidenceToolResult(result.value, contract, recorded);
+    });
 };

package/dist/server/registerBundleComparisonTool.js

@@ -4,11 +4,15 @@ import { compareBundles } from "../domain/bundleComparison.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { runDerivedOperation } from "./runDerivedOperation.js";
+import { recordSessionEvidenceSources } from "./sessionEvidence.js";
 import { BUNDLE_COMPARISON_PROVIDER } from "../application/InvestigationProviders.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { withAdmittedAnalysis } from "./analysisAdmission.js";
+import { runAdmittedToolOperation } from "./admittedToolOperation.js";
 /** Register canonical Evidence bundle comparison. */
 export const registerBundleComparisonTool = (server, session, contract) => {
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
+    const admission = withAdmittedAnalysis({ kind: "session", session });
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => runAdmittedToolOperation(server, admission, contract.name, context.mcpReq.signal, async () => {
         const [left, right] = await Promise.all([
             readEvidenceBundle(input.left_bundle_path),
             readEvidenceBundle(input.right_bundle_path),
@@ -21,6 +25,15 @@ export const registerBundleComparisonTool = (server, session, contract) => {
         if (!computed.ok)
             return server.delivery.toCallToolResult(computed, contract);
         const comparison = computed.value;
+        const sourceRecords = [
+            ...new Map([...left.value.records, ...right.value.records].map((record) => [
+                record.evidence_id,
+                record,
+            ])).values(),
+        ];
+        const recordedSources = recordSessionEvidenceSources((evidence) => session.recordEvidence(evidence), sourceRecords);
+        if (!recordedSources.ok)
+            return server.delivery.toCallToolResult(recordedSources, contract);
         const evidence = createEvidence(undefined, BUNDLE_COMPARISON_PROVIDER, {
             predicateType: "rea.bundle-comparison",
             operation: contract.name,
@@ -33,8 +46,9 @@ export const registerBundleComparisonTool = (server, session, contract) => {
             confidence: "derived",
             authority: "analyst-inference",
             limitations: comparison.limitations,
+            evidenceLinks: sourceRecords.map(({ evidence_id }) => evidence_id),
         });
         const recorded = session.recordEvidence(evidence);
         return server.delivery.toEvidenceToolResult(evidence, contract, recorded);
-    });
+    }));
 };

package/dist/server/registerCloseLifecycleTool.js

@@ -4,20 +4,51 @@ import { mcpProgressReporter } from "./mcpProgress.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
 /** Register provider cleanup and optional pre-close snapshot persistence. */
-export const registerCloseLifecycleTool = ({ server, session, logger, closeContract, }) => {
+export const registerCloseLifecycleTool = ({ server, session, logger, closeContract, closeProcessResources, }) => {
+    const closeWithResources = async (closeSession) => {
+        const [sessionClose, resourceClose] = await Promise.allSettled([
+            closeSession(),
+            closeProcessResources(),
+        ]);
+        if (sessionClose.status === "rejected") {
+            if (resourceClose.status === "rejected")
+                logger.warn({
+                    error: resourceClose.reason instanceof Error
+                        ? resourceClose.reason.message
+                        : String(resourceClose.reason),
+                }, "Process capture cleanup threw while closing the session");
+            else if (!resourceClose.value.ok)
+                logger.warn({ error: resourceClose.value.error.message }, "Process capture cleanup failed while closing the session");
+            throw sessionClose.reason;
+        }
+        if (resourceClose.status === "rejected")
+            throw resourceClose.reason;
+        const closed = sessionClose.value;
+        const resources = resourceClose.value;
+        if (!closed.ok) {
+            if (!resources.ok)
+                logger.warn({ error: resources.error.message }, "Process capture cleanup failed while closing the session");
+            return closed;
+        }
+        return resources.ok ? closed : resources;
+    };
     server.registerTool(closeContract.name, toolRegistrationOptions(closeContract), async (input, context) => {
         const progress = mcpProgressReporter(context);
         const snapshotPath = input.snapshot_path;
         if (snapshotPath === undefined) {
+            // Enqueue the lifecycle transition before awaiting progress transport so
+            // a later open request cannot overtake this close.
+            const closing = logToolExecution(logger, closeContract.name, () => closeWithResources(() => session.close({ progress })));
             await reportLifecycleStart(progress, closeContract.name);
-            const closed = await logToolExecution(logger, closeContract.name, () => session.close({ progress }));
+            const closed = await closing;
             await reportLifecycleEnd(progress, closeContract.name, closed.ok);
             return server.delivery.toCallToolResult(closed, closeContract);
         }
-        await reportLifecycleStart(progress, closeContract.name, "saving snapshot; closing provider");
-        const closed = await logToolExecution(logger, closeContract.name, () => session.closeWithSnapshot(snapshotPath, input.overwrite, {
+        const closing = logToolExecution(logger, closeContract.name, () => closeWithResources(() => session.closeWithSnapshot(snapshotPath, input.overwrite, {
             progress,
-        }));
+        })));
+        await reportLifecycleStart(progress, closeContract.name, "saving snapshot; closing provider");
+        const closed = await closing;
         await reportLifecycleEnd(progress, closeContract.name, closed.ok);
         return server.delivery.toCallToolResult(closed.ok ? ok({ ...closed.value }) : closed, closeContract);
     });

package/dist/server/registerElectronTools.js

@@ -1,3 +1,4 @@
+import { summarizeRetainedAnalysis } from "../application/analysisView/AnalysisViewService.js";
 import { optionalProviderUnavailable, } from "../application/OptionalObservationProviders.js";
 import { err } from "../domain/result.js";
 import { captureElectronScenario } from "../application/javascript/ElectronActiveObservationService.js";
@@ -9,10 +10,11 @@ import { inspectElectronPageInputSchema } from "../domain/javascript/electronObs
 import { mcpProgressReporter } from "./mcpProgress.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { runAdmittedToolOperation } from "./admittedToolOperation.js";
 /** Register Electron tools even when a provider is absent. */
 // oxlint-disable-next-line max-lines-per-function -- direct SDK calls retain each schema-handler type correlation.
 export const registerElectronTools = (server, options) => {
-    const registration = { ...options, delivery: server.delivery };
+    const registration = { ...options, delivery: server.delivery, server };
     const listContract = toolContract("list_electron_targets");
     const inspectContract = toolContract("inspect_electron_page");
     const analyzeContract = toolContract("analyze_javascript_application");
@@ -28,7 +30,12 @@ export const registerElectronTools = (server, options) => {
             progress,
         });
     }));
-    server.registerTool(analyzeContract.name, toolRegistrationOptions(analyzeContract), (input, context) => runElectronTool(registration, analyzeContract, { input, context }, (parsed, { signal, progress }) => analyzeJavaScriptApplicationValidated(parsed, { signal, progress })));
+    server.registerTool(analyzeContract.name, toolRegistrationOptions(analyzeContract), (input, context) => runElectronTool(registration, analyzeContract, { input, context }, async ({ detail, ...request }, { signal, progress }) => {
+        const analyzed = await analyzeJavaScriptApplicationValidated(request, options.artifactResources, { signal, progress });
+        return detail === "summary" && analyzed.ok
+            ? summarizeRetainedAnalysis(analyzed.value, options)
+            : analyzed;
+    }));
     server.registerTool(reconcileContract.name, toolRegistrationOptions(reconcileContract), (input, context) => runElectronTool(registration, reconcileContract, { input, context }, (parsed) => Promise.resolve(reconcileJavaScriptRuntimeEvidenceValidated(parsed))));
     server.registerTool(activeContract.name, toolRegistrationOptions(activeContract), (input, context) => runElectronTool(registration, activeContract, { input, context }, (parsed, { signal, progress }) => captureElectronScenario(options.electronActive, parsed, {
         signal,
@@ -45,12 +52,23 @@ const runElectronTool = async (options, contract, request, execute) => {
             : undefined;
     if (failure !== undefined)
         return options.delivery.toCallToolResult(err(optionalProviderUnavailable(failure, contract.name)), contract);
-    const result = await logToolExecution(options.logger, contract.name, () => execute(input, {
-        signal: context.mcpReq.signal,
-        progress: mcpProgressReporter(context),
-    }));
-    if (!result.ok)
-        return options.delivery.toCallToolResult(result, contract);
-    const recorded = options.recordEvidence?.(result.value);
-    return options.delivery.toEvidenceToolResult(result.value, contract, recorded);
+    return runAdmittedToolOperation(options.server, options.withAdmittedAnalysis, contract.name, context.mcpReq.signal, async () => {
+        const result = await logToolExecution(options.logger, contract.name, () => execute(input, {
+            signal: context.mcpReq.signal,
+            progress: mcpProgressReporter(context),
+        }));
+        if (!result.ok) {
+            const partial = result.error.partialObservation;
+            if (partial !== undefined &&
+                "evidence_id" in partial &&
+                typeof partial.evidence_id === "string") {
+                const recorded = options.recordEvidence?.(partial);
+                if (recorded !== undefined)
+                    return options.delivery.toRecordedPartialErrorToolResult(result.error, partial.evidence_id, recorded);
+            }
+            return options.delivery.toCallToolResult(result, contract);
+        }
+        const recorded = options.recordEvidence?.(result.value);
+        return options.delivery.toEvidenceToolResult(result.value, contract, recorded);
+    });
 };

package/dist/server/registerEnhancedTools.js

@@ -7,7 +7,7 @@ import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
 import { executeFunctionAnalysisEvidence } from "../application/FunctionAnalysisEvidence.js";
 /** Register composed workflows against the same port as direct bridge tools. */
 // oxlint-disable-next-line max-lines-per-function -- direct SDK calls retain each schema-handler type correlation.
-export const registerEnhancedTools = (server, analysis, options) => {
+export const registerEnhancedTools = (server, options) => {
     const registration = { ...options, delivery: server.delivery };
     const nativeDispatchMetadata = toolContract("inspect_native_dispatch_metadata");
     const objcClasses = toolContract("get_objc_classes");
@@ -23,125 +23,130 @@ export const registerEnhancedTools = (server, analysis, options) => {
     const traceCallPath = toolContract("trace_call_path");
     const traceNativeUiAction = toolContract("trace_native_ui_action");
     const traceNativeValues = toolContract("trace_native_values");
-    server.registerTool(traceNativeValues.name, toolRegistrationOptions(traceNativeValues), (input, context) => executeEnhancedTool(analysis, registration, traceNativeValues, {
+    server.registerTool(traceNativeValues.name, toolRegistrationOptions(traceNativeValues), (input, context) => executeEnhancedTool(registration, traceNativeValues, {
         validatedCall: { name: "trace_native_values", input },
         context,
     }));
-    server.registerTool(nativeDispatchMetadata.name, toolRegistrationOptions(nativeDispatchMetadata), (input, context) => executeEnhancedTool(analysis, registration, nativeDispatchMetadata, {
+    server.registerTool(nativeDispatchMetadata.name, toolRegistrationOptions(nativeDispatchMetadata), (input, context) => executeEnhancedTool(registration, nativeDispatchMetadata, {
         validatedCall: { name: "inspect_native_dispatch_metadata", input },
         context,
     }));
-    server.registerTool(objcClasses.name, toolRegistrationOptions(objcClasses), (input, context) => executeEnhancedTool(analysis, registration, objcClasses, {
+    server.registerTool(objcClasses.name, toolRegistrationOptions(objcClasses), (input, context) => executeEnhancedTool(registration, objcClasses, {
         validatedCall: { name: "get_objc_classes", input },
         context,
     }));
-    server.registerTool(objcProtocols.name, toolRegistrationOptions(objcProtocols), (input, context) => executeEnhancedTool(analysis, registration, objcProtocols, {
+    server.registerTool(objcProtocols.name, toolRegistrationOptions(objcProtocols), (input, context) => executeEnhancedTool(registration, objcProtocols, {
         validatedCall: { name: "get_objc_protocols", input },
         context,
     }));
-    server.registerTool(batchDecompile.name, toolRegistrationOptions(batchDecompile), (input, context) => executeEnhancedTool(analysis, registration, batchDecompile, {
+    server.registerTool(batchDecompile.name, toolRegistrationOptions(batchDecompile), (input, context) => executeEnhancedTool(registration, batchDecompile, {
         validatedCall: { name: "batch_decompile", input },
         context,
     }));
-    server.registerTool(callGraph.name, toolRegistrationOptions(callGraph), (input, context) => executeEnhancedTool(analysis, registration, callGraph, {
+    server.registerTool(callGraph.name, toolRegistrationOptions(callGraph), (input, context) => executeEnhancedTool(registration, callGraph, {
         validatedCall: { name: "get_call_graph", input },
         context,
     }));
-    server.registerTool(swiftTypes.name, toolRegistrationOptions(swiftTypes), (input, context) => executeEnhancedTool(analysis, registration, swiftTypes, {
+    server.registerTool(swiftTypes.name, toolRegistrationOptions(swiftTypes), (input, context) => executeEnhancedTool(registration, swiftTypes, {
         validatedCall: { name: "analyze_swift_types", input },
         context,
     }));
-    server.registerTool(xrefsToName.name, toolRegistrationOptions(xrefsToName), (input, context) => executeEnhancedTool(analysis, registration, xrefsToName, {
+    server.registerTool(xrefsToName.name, toolRegistrationOptions(xrefsToName), (input, context) => executeEnhancedTool(registration, xrefsToName, {
         validatedCall: { name: "find_xrefs_to_name", input },
         context,
     }));
-    server.registerTool(binaryOverview.name, toolRegistrationOptions(binaryOverview), (input, context) => executeEnhancedTool(analysis, registration, binaryOverview, {
+    server.registerTool(binaryOverview.name, toolRegistrationOptions(binaryOverview), (input, context) => executeEnhancedTool(registration, binaryOverview, {
         validatedCall: { name: "binary_overview", input },
         context,
     }));
-    server.registerTool(analyzeFunction.name, toolRegistrationOptions(analyzeFunction), (input, context) => executeEnhancedTool(analysis, registration, analyzeFunction, {
+    server.registerTool(analyzeFunction.name, toolRegistrationOptions(analyzeFunction), (input, context) => executeEnhancedTool(registration, analyzeFunction, {
         validatedCall: { name: "analyze_function", input },
         context,
     }));
-    server.registerTool(inspectNativeApi.name, toolRegistrationOptions(inspectNativeApi), (input, context) => executeEnhancedTool(analysis, registration, inspectNativeApi, {
+    server.registerTool(inspectNativeApi.name, toolRegistrationOptions(inspectNativeApi), (input, context) => executeEnhancedTool(registration, inspectNativeApi, {
         validatedCall: { name: "inspect_native_api", input },
         context,
     }));
-    server.registerTool(traceFeature.name, toolRegistrationOptions(traceFeature), (input, context) => executeEnhancedTool(analysis, registration, traceFeature, {
+    server.registerTool(traceFeature.name, toolRegistrationOptions(traceFeature), (input, context) => executeEnhancedTool(registration, traceFeature, {
         validatedCall: { name: "trace_feature", input },
         context,
     }));
-    server.registerTool(traceCallPath.name, toolRegistrationOptions(traceCallPath), (input, context) => executeEnhancedTool(analysis, registration, traceCallPath, {
+    server.registerTool(traceCallPath.name, toolRegistrationOptions(traceCallPath), (input, context) => executeEnhancedTool(registration, traceCallPath, {
         validatedCall: { name: "trace_call_path", input },
         context,
     }));
-    server.registerTool(traceNativeUiAction.name, toolRegistrationOptions(traceNativeUiAction), (input, context) => executeEnhancedTool(analysis, registration, traceNativeUiAction, {
+    server.registerTool(traceNativeUiAction.name, toolRegistrationOptions(traceNativeUiAction), (input, context) => executeEnhancedTool(registration, traceNativeUiAction, {
         validatedCall: { name: "trace_native_ui_action", input },
         context,
     }));
 };
-const executeEnhancedTool = async (analysis, registration, contract, request) => {
-    const { validatedCall, context } = request;
-    const name = validatedCall.name;
-    const progress = mcpProgressReporter(context);
-    await progress.report({
-        phase: name,
-        completed: 0,
-        total: 1,
-        message: "started",
-    });
-    const parsedInput = validatedCall.input;
-    const parameters = jsonParameters(parsedInput);
-    if (name === "analyze_function")
-        return executeFunctionTool(analysis, registration, contract, {
-            context,
-            parameters,
+const executeEnhancedTool = async (registration, contract, request) => {
+    const admitted = await registration.withAdmittedAnalysis(request.validatedCall.name, request.context.mcpReq.signal, async (admittedAnalysis) => {
+        const { validatedCall, context } = request;
+        const name = validatedCall.name;
+        const progress = mcpProgressReporter(context);
+        await progress.report({
+            phase: name,
+            completed: 0,
+            total: 1,
+            message: "started",
         });
-    const services = new EnhancedTools({
-        execute: (operation, operationParameters, executionOptions) => analysis.execute(operation, operationParameters, {
-            ...executionOptions,
-            progress,
-        }),
-    });
-    const result = await logToolExecution(registration.logger, name, () => services.executeValidated(validatedCall, context.mcpReq.signal));
-    await progress.report({
-        phase: name,
-        completed: 1,
-        total: 1,
-        message: result.ok ? "completed" : "failed",
-        terminal: true,
-    });
-    if (result.ok) {
-        const evidence = createWorkflowEvidence({
-            target: registration.activeTarget?.(),
-            operation: name,
-            parameters,
-            result: result.value,
-            upstreamProfile: registration.analysisProfile?.(),
+        const parsedInput = validatedCall.input;
+        const parameters = jsonParameters(parsedInput);
+        if (name === "analyze_function")
+            return executeFunctionTool(admittedAnalysis, registration, contract, {
+                context,
+                parameters,
+            });
+        const services = new EnhancedTools({
+            execute: (operation, operationParameters, executionOptions) => admittedAnalysis.execute(operation, operationParameters, {
+                ...executionOptions,
+                progress,
+            }),
+        });
+        const result = await logToolExecution(registration.logger, name, () => services.executeValidated(validatedCall, context.mcpReq.signal));
+        await progress.report({
+            phase: name,
+            completed: 1,
+            total: 1,
+            message: result.ok ? "completed" : "failed",
+            terminal: true,
         });
-        const recorded = registration.recordEvidence?.(evidence);
-        if (recorded !== undefined && !recorded.ok)
-            return registration.delivery.toCallToolResult(recorded, contract);
-        if (name !== "trace_native_ui_action" &&
-            registration.allowsSnapshotReplay?.(name) === true) {
-            const workflowRecord = workflowSnapshotRecord(evidence, name);
-            if (workflowRecord !== undefined) {
-                const snapshot = registration.recordWorkflowSnapshot?.(workflowRecord);
-                if (snapshot !== undefined && !snapshot.ok)
-                    return registration.delivery.toCallToolResult(snapshot, contract);
+        if (result.ok) {
+            const evidence = createWorkflowEvidence({
+                target: registration.activeTarget?.(),
+                operation: name,
+                parameters,
+                result: result.value,
+                upstreamProfile: registration.analysisProfile?.(),
+            });
+            const recorded = registration.recordEvidence?.(evidence);
+            if (recorded !== undefined && !recorded.ok)
+                return registration.delivery.toCallToolResult(recorded, contract);
+            if (name !== "trace_native_ui_action" &&
+                registration.allowsSnapshotReplay?.(name) === true) {
+                const workflowRecord = workflowSnapshotRecord(evidence, name);
+                if (workflowRecord !== undefined) {
+                    const snapshot = registration.recordWorkflowSnapshot?.(workflowRecord);
+                    if (snapshot !== undefined && !snapshot.ok)
+                        return registration.delivery.toCallToolResult(snapshot, contract);
+                }
             }
+            const unknowns = recordWorkflowUnknowns({
+                name,
+                result: result.value,
+                evidenceId: evidence.evidence_id,
+                recordUnknown: registration.recordUnknown,
+            });
+            if (!unknowns.ok)
+                return registration.delivery.toCallToolResult(unknowns, contract);
+            return registration.delivery.toEvidenceToolResult(evidence, contract, recorded);
         }
-        const unknowns = recordWorkflowUnknowns({
-            name,
-            result: result.value,
-            evidenceId: evidence.evidence_id,
-            recordUnknown: registration.recordUnknown,
-        });
-        if (!unknowns.ok)
-            return registration.delivery.toCallToolResult(unknowns, contract);
-        return registration.delivery.toEvidenceToolResult(evidence, contract, recorded);
-    }
-    return registration.delivery.toCallToolResult(result, contract);
+        return registration.delivery.toCallToolResult(result, contract);
+    });
+    return admitted.ok
+        ? admitted.value
+        : registration.delivery.toCallToolResult(admitted, contract);
 };
 const executeFunctionTool = async (analysis, registration, contract, request) => {
     const { context, parameters } = request;

package/dist/server/registerEvidenceTools.js

@@ -5,56 +5,64 @@ import { logToolExecution } from "./toolLogging.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
 import { createArtifactExtractionDestination } from "../application/artifacts/ArtifactExtractionDestination.js";
 /** Register provider-backed contracts that return atomic Evidence observations. */
-export const registerEvidenceTools = (server, analysis, contracts, options) => {
+export const registerEvidenceTools = (server, contracts, options) => {
     for (const contract of contracts) {
         server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
-            const progress = mcpProgressReporter(context);
-            await progress.report({
-                phase: contract.name,
-                completed: 0,
-                total: 1,
-                message: "started",
-            });
-            const parameters = jsonObjectSchema.parse(input);
-            const executionParameters = contract.name === "extract_artifact"
-                ? {
-                    ...parameters,
-                    output_root: createArtifactExtractionDestination(),
+            const admitted = await options.withAdmittedAnalysis(contract.name, context.mcpReq.signal, async (admittedAnalysis) => {
+                const analysis = options.analysisForAdmission?.(admittedAnalysis) ??
+                    admittedAnalysis;
+                const progress = mcpProgressReporter(context);
+                await progress.report({
+                    phase: contract.name,
+                    completed: 0,
+                    total: 1,
+                    message: "started",
+                });
+                const parameters = jsonObjectSchema.parse(input);
+                const executionParameters = contract.name === "extract_artifact"
+                    ? {
+                        ...parameters,
+                        output_root: createArtifactExtractionDestination(),
+                    }
+                    : parameters;
+                const execution = await logToolExecution(options.logger, contract.name, () => analysis.execute(contract.name, executionParameters, {
+                    signal: context.mcpReq.signal,
+                    progress,
+                }));
+                await progress.report({
+                    phase: contract.name,
+                    completed: 1,
+                    total: 1,
+                    message: execution.ok ? "completed" : "failed",
+                    terminal: true,
+                });
+                if (!execution.ok)
+                    return server.delivery.toCallToolResult(execution, contract);
+                const sourceEvidence = options.sourceEvidence?.(contract.name, execution.value.result) ??
+                    [];
+                const evidence = createEvidence(execution.value.subject ?? options.activeTarget?.(), execution.value.provider, {
+                    operation: contract.name,
+                    parameters,
+                    result: execution.value.result,
+                    ...(execution.value.analysisProfile === undefined
+                        ? {}
+                        : { analysisProfile: execution.value.analysisProfile }),
+                    rawResult: execution.value.rawResult,
+                    limitations: execution.value.limitations,
+                    locations: execution.value.locations,
+                    evidenceLinks: sourceEvidence.map(({ evidence_id: id }) => id),
+                });
+                for (const source of sourceEvidence) {
+                    const sourceRecorded = options.recordEvidence?.(source);
+                    if (sourceRecorded !== undefined && !sourceRecorded.ok)
+                        return server.delivery.toCallToolResult(sourceRecorded, contract);
                 }
-                : parameters;
-            const execution = await logToolExecution(options.logger, contract.name, () => analysis.execute(contract.name, executionParameters, {
-                signal: context.mcpReq.signal,
-                progress,
-            }));
-            await progress.report({
-                phase: contract.name,
-                completed: 1,
-                total: 1,
-                message: execution.ok ? "completed" : "failed",
-                terminal: true,
-            });
-            if (!execution.ok)
-                return server.delivery.toCallToolResult(execution, contract);
-            const sourceEvidence = options.sourceEvidence?.(contract.name, execution.value.result) ?? [];
-            const evidence = createEvidence(execution.value.subject ?? options.activeTarget?.(), execution.value.provider, {
-                operation: contract.name,
-                parameters,
-                result: execution.value.result,
-                ...(execution.value.analysisProfile === undefined
-                    ? {}
-                    : { analysisProfile: execution.value.analysisProfile }),
-                rawResult: execution.value.rawResult,
-                limitations: execution.value.limitations,
-                locations: execution.value.locations,
-                evidenceLinks: sourceEvidence.map(({ evidence_id: id }) => id),
+                const recorded = options.recordEvidence?.(evidence);
+                return server.delivery.toEvidenceToolResult(evidence, contract, recorded);
             });
-            for (const source of sourceEvidence) {
-                const sourceRecorded = options.recordEvidence?.(source);
-                if (sourceRecorded !== undefined && !sourceRecorded.ok)
-                    return server.delivery.toCallToolResult(sourceRecorded, contract);
-            }
-            const recorded = options.recordEvidence?.(evidence);
-            return server.delivery.toEvidenceToolResult(evidence, contract, recorded);
+            return admitted.ok
+                ? admitted.value
+                : server.delivery.toCallToolResult(admitted, contract);
         });
     }
 };