rea-agents 6.2.0 → 6.4.0

package/dist/server/createServer.js

@@ -1,4 +1,6 @@
 import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
+import { createPeResourcesService } from "../composition/binaryDiagnostics.js";
+import { registerPeResourcesTool } from "./registerPeResourcesTool.js";
 import { createEvmInterfaceService } from "../composition/evm.js";
 import { registerEvmTools } from "./registerEvmTools.js";
 import { registerRecordedCrashTools } from "./registerRecordedCrashTools.js";
@@ -9,6 +11,7 @@ import { createBinaryLayoutService } from "../composition/binaryDiagnostics.js";
 import { EvidenceMcpServer } from "./EvidenceMcpServer.js";
 import { createToolResultDelivery, } from "./toolResult.js";
 import { parseMcpResponseBudget } from "../config/mcpResponseBudget.js";
+import { COMPACT_INPUT_SCHEMA_BUDGET_BYTES, parseMcpInputSchemaProfile, } from "../config/mcpInputSchemaProfile.js";
 import { isAbsolute } from "node:path";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { silentLogger } from "../logger.js";
@@ -29,6 +32,7 @@ import { registerJavaScriptRecoveryTool } from "./registerJavaScriptRecoveryTool
 import { JavaScriptRecoveryService } from "../application/javascript/JavaScriptRecoveryService.js";
 import { createJavaScriptRecoveryProvider } from "../composition/javascriptRecovery.js";
 import { registerElectronTools } from "./registerElectronTools.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
 import { registerEnhancedTools } from "./registerEnhancedTools.js";
 import { registerJavaScriptRuntimeObservationTools } from "./registerJavaScriptRuntimeObservationTools.js";
 import { registerManagedTools } from "./registerManagedTools.js";
@@ -36,14 +40,25 @@ import { registerFirmwareTools } from "./registerFirmwareTools.js";
 import { FirmwareAnalysisService } from "../application/firmware/FirmwareAnalysisService.js";
 import { createFirmwareAnalysisProvider } from "../composition/firmware.js";
 import { registerAndroidTools } from "./registerAndroidTools.js";
+import { registerApktoolTools } from "./registerApktoolTools.js";
+import { registerJebTools } from "./registerJebTools.js";
+import { registerAdbTools } from "./registerAdbTools.js";
 import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js";
+import { JebAnalysisService } from "../application/jeb/JebAnalysisService.js";
+import { ApktoolResourceAnalysisService } from "../application/apktool/ApktoolResourceAnalysisService.js";
 import { createAndroidAnalysisProvider } from "../composition/android.js";
+import { createApktoolResourceAnalysisProvider } from "../composition/apktool.js";
+import { createJebAnalysisProvider } from "../composition/jeb.js";
+import { AdbDeviceAnalysisService } from "../application/adb/AdbDeviceAnalysisService.js";
+import { createAdbDeviceAnalysisProvider } from "../composition/adb.js";
 import { registerManagedWorkflowTools } from "./registerManagedWorkflowTools.js";
-import { registerNativeTools } from "./registerNativeTools.js";
+import { NATIVE_TOOL_CONTRACTS } from "../contracts/native/nativeToolContracts.js";
+import { registerEvidenceTools } from "./registerEvidenceTools.js";
 import { registerOfficialTools } from "./registerOfficialTools.js";
 import { registerGuidedPrompts } from "./registerPrompts.js";
 import { registerSessionTools } from "./registerSessionTools.js";
 import { sessionAvailabilityPolicy } from "./sessionAvailabilityPolicy.js";
+import { withAdmittedAnalysis, } from "./analysisAdmission.js";
 const TARGET_FREE_INSTRUCTIONS = "REA provides reverse-engineering tools for local artifacts, native binaries, managed code, browser pages, and runtimes. Use the tool that directly answers the question; discover targets or inspect inventory only when needed. Tool results include inline Evidence and report their coverage and limitations.";
 const ACTIVE_TARGET_INSTRUCTIONS = "REA analyzes the active reverse-engineering target. Use the analysis tool that answers the question directly. Search or list symbols when discovery is needed; analyze_function provides a function dossier, and focused procedure tools return individual facets.";
 const installSessionToolAvailability = (session, options, environment) => {
@@ -77,7 +92,7 @@ const installSessionToolAvailability = (session, options, environment) => {
         policy,
     };
 };
-const createMcpServer = (session, delivery) => new EvidenceMcpServer({
+const createMcpServer = (session, delivery, compactPresentation) => new EvidenceMcpServer({
     name: PRODUCT_IDENTITY.mcpServerKey,
     version: PRODUCT_IDENTITY.packageVersion,
 }, {
@@ -87,26 +102,69 @@ const createMcpServer = (session, delivery) => new EvidenceMcpServer({
         : TARGET_FREE_INSTRUCTIONS,
 }, session === undefined
     ? undefined
-    : (evidence) => session.recordEvidence(evidence), delivery);
+    : (evidence) => session.recordEvidence(evidence), delivery, compactPresentation);
 /**
  * Construct one MCP server without acquiring subprocess resources.
  * Supplying a session adds target lifecycle tools; omitting it retains the
  * fixed-target seam used by focused tests and embedders.
  */
-export const createServer = (analysis, session, options = {}) => {
+export const createServer = (source, options = {}) => {
+    const session = source.kind === "session" ? source.session : undefined;
+    const analysis = source.kind === "session" ? source.session : source.analysis;
     const environment = snapshotEnvironment(options.environment ?? process.env);
     const delivery = selectToolResultDelivery(environment, options.delivery);
-    const selectedOptions = { ...options, environment, delivery };
+    const evmInterface = options.evmInterface ?? createEvmInterfaceService(environment);
+    const webSourceLocation = options.webSourceLocation ?? createWebSourceLocationService(environment);
+    const javascriptRecovery = options.javascriptRecovery ?? createJavaScriptRecoveryProvider(environment);
+    const artifactResources = new ArtifactResourceScope();
+    const firmwareAnalysis = new FirmwareAnalysisService(options.firmwareAnalysis ?? createFirmwareAnalysisProvider(environment));
+    const selectedOptions = {
+        ...options,
+        environment,
+        delivery,
+        evmInterface,
+        webSourceLocation,
+        javascriptRecovery,
+    };
     const startedAt = new Date().toISOString();
     const logger = options.logger ?? silentLogger;
-    const server = createMcpServer(session, delivery);
+    const server = createMcpServer(session, delivery, selectCompactInputSchemaPresentation(environment));
     const android = options.androidAnalysis ?? createAndroidAnalysisProvider(environment);
-    const availability = installSessionToolAvailability(session, selectedOptions, environment);
+    const apktool = options.apktoolAnalysis ??
+        createApktoolResourceAnalysisProvider(environment);
+    const jeb = options.jebAnalysis ?? createJebAnalysisProvider(environment);
+    const adbDevice = options.adbDeviceAnalysis ?? createAdbDeviceAnalysisProvider(environment);
+    let providerClose;
+    const closeProviders = () => {
+        providerClose ??= Promise.allSettled([
+            android.close(),
+            apktool.close(),
+            jeb.close(),
+            adbDevice.close(),
+            evmInterface.close(),
+            webSourceLocation.close(),
+            javascriptRecovery.close?.() ?? Promise.resolve(),
+            artifactResources.close(),
+            firmwareAnalysis.close(),
+            options.browserScenarioCapture?.close?.() ?? Promise.resolve(),
+        ])
+            .then((results) => {
+            const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (failures.length > 0)
+                throw new AggregateError(failures, "REA provider cleanup failed");
+        })
+            .catch((cause) => {
+            providerClose = undefined;
+            throw cause;
+        });
+        return providerClose;
+    };
+    const availability = installSessionToolAvailability(session, options, environment);
     const toolLogger = logger.child({ layer: "server" });
     const { evidenceById, activeTarget, recordEvidence, recordEvidenceWithUnknown, } = createSessionRecorders(server, session);
+    const analysisAdmission = withAdmittedAnalysis(source);
     const toolContext = {
         server,
-        analysis,
         session,
         options: selectedOptions,
         environment,
@@ -115,23 +173,27 @@ export const createServer = (analysis, session, options = {}) => {
         activeTarget,
         recordEvidence,
         recordEvidenceWithUnknown,
+        withAdmittedAnalysis: analysisAdmission,
+        artifactResources,
     };
     registerBinaryAnalysisTools(toolContext);
     const previousOnclose = server.server.onclose;
     server.server.onclose = () => {
         previousOnclose?.();
-        void android.close().catch((cause) => {
-            logger.error({ error: cause instanceof Error ? cause.message : String(cause) }, "Android provider cleanup failed");
+        void closeProviders().catch((cause) => {
+            logger.error({ error: cause instanceof Error ? cause.message : String(cause) }, "Provider cleanup failed during server shutdown");
         });
     };
     const closeServer = server.close.bind(server);
     server.close = async () => {
-        const results = await Promise.allSettled([closeServer(), android.close()]);
+        const results = await Promise.allSettled([closeServer(), closeProviders()]);
         for (const result of results)
             if (result.status === "rejected")
                 throw result.reason;
     };
-    registerConfiguredAnalysisTools(toolContext, android);
+    registerConfiguredAnalysisTools(toolContext, android, jeb, firmwareAnalysis);
+    registerAdbTools(server, new AdbDeviceAnalysisService(adbDevice), toolLogger, recordEvidence, analysisAdmission);
+    registerApktoolTools(server, new ApktoolResourceAnalysisService(apktool), toolLogger, recordEvidence, analysisAdmission);
     registerObservationTools(toolContext);
     registerGuidedPrompts(server, analysis, session);
     if (session !== undefined) {
@@ -154,19 +216,29 @@ const selectToolResultDelivery = (environment, selected) => {
         throw configured.error;
     return createToolResultDelivery(configured.value);
 };
-const registerConfiguredAnalysisTools = ({ server, options, environment, logger: toolLogger, evidenceById, recordEvidence, }, android) => {
-    registerAndroidTools(server, new AndroidAnalysisService(android), toolLogger, recordEvidence);
-    registerBinaryDiagnosticsTools(server, options.binaryLayout ?? createBinaryLayoutService(environment), toolLogger, recordEvidence);
-    registerAnalysisViewTool(server, toolLogger, evidenceById, recordEvidence);
-    registerEvmTools(server, options.evmInterface ?? createEvmInterfaceService(environment), toolLogger, recordEvidence);
-    registerRecordedCrashTools(server, options.recordedCrash ?? createRecordedCrashService(environment), toolLogger, recordEvidence);
-    registerFirmwareTools(server, new FirmwareAnalysisService(options.firmwareAnalysis ?? createFirmwareAnalysisProvider(environment)), toolLogger, recordEvidence);
-    registerWebModuleTool(server, options.webModuleTrace ?? createWebModuleTraceService(environment), toolLogger, recordEvidence);
-    registerWebSourceLocationTool(server, options.webSourceLocation ?? createWebSourceLocationService(environment), toolLogger, recordEvidence);
-    registerWebRuntimeTools(server, options.webRuntime ?? createWebRuntimeService(), toolLogger, recordEvidence);
-    registerWebNetworkCaptureTool(server, options.webNetworkCapture ?? createWebNetworkCaptureService(environment), toolLogger, recordEvidence);
+const selectCompactInputSchemaPresentation = (environment) => {
+    const configured = parseMcpInputSchemaProfile(environment.REA_MCP_INPUT_SCHEMA_PROFILE);
+    if (!configured.ok)
+        throw configured.error;
+    return configured.value === "compact"
+        ? { budgetBytes: COMPACT_INPUT_SCHEMA_BUDGET_BYTES }
+        : undefined;
+};
+const registerConfiguredAnalysisTools = ({ server, options, environment, logger: toolLogger, evidenceById, recordEvidence, withAdmittedAnalysis, }, android, jeb, firmwareAnalysis) => {
+    registerAndroidTools(server, new AndroidAnalysisService(android), toolLogger, recordEvidence, withAdmittedAnalysis);
+    registerJebTools(server, new JebAnalysisService(jeb), toolLogger, recordEvidence, withAdmittedAnalysis);
+    registerBinaryDiagnosticsTools(server, options.binaryLayout ?? createBinaryLayoutService(environment), toolLogger, recordEvidence, evidenceById, withAdmittedAnalysis);
+    registerAnalysisViewTool(server, toolLogger, evidenceById, recordEvidence, withAdmittedAnalysis);
+    registerPeResourcesTool(server, createPeResourcesService(), toolLogger, recordEvidence, withAdmittedAnalysis);
+    registerEvmTools(server, options.evmInterface ?? createEvmInterfaceService(environment), toolLogger, recordEvidence, withAdmittedAnalysis);
+    registerRecordedCrashTools(server, options.recordedCrash ?? createRecordedCrashService(environment), toolLogger, recordEvidence, withAdmittedAnalysis);
+    registerFirmwareTools(server, firmwareAnalysis, toolLogger, recordEvidence, withAdmittedAnalysis);
+    registerWebModuleTool(server, options.webModuleTrace ?? createWebModuleTraceService(environment), toolLogger, recordEvidence, withAdmittedAnalysis);
+    registerWebSourceLocationTool(server, options.webSourceLocation ?? createWebSourceLocationService(environment), toolLogger, recordEvidence, withAdmittedAnalysis);
+    registerWebRuntimeTools(server, options.webRuntime ?? createWebRuntimeService(), toolLogger, recordEvidence, withAdmittedAnalysis);
+    registerWebNetworkCaptureTool(server, options.webNetworkCapture ?? createWebNetworkCaptureService(environment), toolLogger, recordEvidence, withAdmittedAnalysis);
     registerJavaScriptRecoveryTool(server, new JavaScriptRecoveryService(options.javascriptRecovery ??
-        createJavaScriptRecoveryProvider(environment)), toolLogger, recordEvidence);
+        createJavaScriptRecoveryProvider(environment)), toolLogger, recordEvidence, withAdmittedAnalysis);
 };
 const createSessionRecorders = (server, session) => ({
     evidenceById: session === undefined
@@ -176,18 +248,12 @@ const createSessionRecorders = (server, session) => ({
     activeTarget: session === undefined ? undefined : () => session.activeTarget(),
     recordEvidence: session === undefined
         ? undefined
-        : (evidence) => {
-            const recorded = session.recordEvidence(evidence);
-            return recorded;
-        },
+        : (evidence) => session.recordEvidence(evidence),
     recordEvidenceWithUnknown: session === undefined
         ? undefined
-        : (evidence, input) => {
-            const recorded = session.recordEvidenceWithUnknown(evidence, input);
-            return recorded;
-        },
+        : (evidence, input) => session.recordEvidenceWithUnknown(evidence, input),
 });
-const registerBinaryAnalysisTools = ({ server, analysis, session, logger, activeTarget, recordEvidence, recordEvidenceWithUnknown, }) => {
+const registerBinaryAnalysisTools = ({ server, session, logger, activeTarget, recordEvidence, recordEvidenceWithUnknown, withAdmittedAnalysis, }) => {
     const recordUnknown = session === undefined
         ? undefined
         : (input) => session.recordUnknown(input);
@@ -196,9 +262,10 @@ const registerBinaryAnalysisTools = ({ server, analysis, session, logger, active
         activeTarget,
         recordEvidence,
         recordUnknown,
+        withAdmittedAnalysis,
     };
-    registerOfficialTools(server, analysis, analysisOptions);
-    registerEnhancedTools(server, analysis, {
+    registerOfficialTools(server, analysisOptions);
+    registerEnhancedTools(server, {
         ...analysisOptions,
         analysisProfile: session === undefined ? undefined : () => session.analysisProfile(),
         allowsSnapshotReplay: session === undefined
@@ -208,26 +275,27 @@ const registerBinaryAnalysisTools = ({ server, analysis, session, logger, active
             ? undefined
             : (input) => session.recordWorkflowSnapshot(input),
     });
-    const evidenceOptions = { logger, activeTarget, recordEvidence };
-    registerNativeTools(server, analysis, evidenceOptions);
-    registerArtifactTools(server, analysis, {
-        ...evidenceOptions,
-    });
-    registerManagedTools(server, analysis, {
-        ...evidenceOptions,
-        session,
-    });
+    const evidenceOptions = {
+        logger,
+        activeTarget,
+        recordEvidence,
+        withAdmittedAnalysis,
+    };
+    registerEvidenceTools(server, NATIVE_TOOL_CONTRACTS, evidenceOptions);
+    registerArtifactTools(server, evidenceOptions);
+    registerManagedTools(server, evidenceOptions);
     if (session !== undefined)
         registerManagedWorkflowTools(server, {
             logger,
             recordEvidence,
             recordEvidenceWithUnknown,
             session,
+            withAdmittedAnalysis,
         });
 };
-const registerObservationTools = ({ evidenceById, server, options, logger, recordEvidence, recordEvidenceWithUnknown, }) => {
-    const common = { logger, recordEvidence };
-    registerWebScriptTool(server, common);
+const registerObservationTools = ({ evidenceById, server, options, logger, recordEvidence, recordEvidenceWithUnknown, withAdmittedAnalysis, artifactResources, }) => {
+    const common = { logger, recordEvidence, withAdmittedAnalysis };
+    registerWebScriptTool(server, { ...common, artifactResources });
     registerBrowserTools(server, {
         ...common,
         browser: options.browserObservation,
@@ -240,6 +308,8 @@ const registerObservationTools = ({ evidenceById, server, options, logger, recor
     });
     registerElectronTools(server, {
         ...common,
+        artifactResources,
+        evidenceById,
         electron: options.electronObservation,
         electronActive: options.electronActiveObservation,
         observationLoadFailure: options.optionalProviderLoadFailures?.electronObservation,
@@ -255,5 +325,6 @@ const registerObservationTools = ({ evidenceById, server, options, logger, recor
         logger,
         recordEvidence,
         recordEvidenceWithUnknown,
+        withAdmittedAnalysis,
     });
 };

package/dist/server/registerAdbTools.js

@@ -0,0 +1,36 @@
+import { AdbDeviceAnalysisService } from "../application/adb/AdbDeviceAnalysisService.js";
+import { toolContract } from "../contracts/toolContracts.js";
+import { createContractToolHandler } from "./contractToolHandler.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Bind ADB handlers to their exact named contracts through shared workflows. */
+export const registerAdbTools = (server, service, logger, recordEvidence, withAdmittedAnalysis) => {
+    const handler = createContractToolHandler(server, service, logger, recordEvidence, withAdmittedAnalysis);
+    for (const contract of [
+        toolContract("inspect_adb_client"),
+        toolContract("list_adb_devices"),
+        toolContract("inspect_adb_device"),
+        toolContract("list_adb_packages"),
+        toolContract("pull_adb_package"),
+        toolContract("read_adb_logcat"),
+        toolContract("inspect_adb_package"),
+        toolContract("pull_adb_file"),
+        toolContract("push_adb_file"),
+        toolContract("capture_adb_screen"),
+        toolContract("list_adb_processes"),
+        toolContract("list_adb_directory"),
+        toolContract("list_adb_features"),
+        toolContract("list_adb_services"),
+        toolContract("inspect_adb_display"),
+        toolContract("inspect_adb_window"),
+        toolContract("read_adb_setting"),
+        toolContract("collect_adb_bugreport"),
+        toolContract("resolve_adb_packages"),
+        toolContract("install_adb_package"),
+        toolContract("uninstall_adb_package"),
+        toolContract("start_adb_app"),
+        toolContract("start_adb_activity"),
+        toolContract("stop_adb_app"),
+    ]) {
+        server.registerTool(contract.name, toolRegistrationOptions(contract), handler(contract));
+    }
+};

package/dist/server/registerAnalysisViewTool.js

@@ -1,15 +1,10 @@
 import { inspectAnalysisView } from "../application/analysisView/AnalysisViewService.js";
 import { toolContract } from "../contracts/toolContracts.js";
-import { logToolExecution } from "./toolLogging.js";
+import { createEvidenceToolHandler } from "./contractToolHandler.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
 /** Bind selected-view projection to its named contract and session Evidence owner. */
-export const registerAnalysisViewTool = (server, logger, evidenceById, recordEvidence) => {
+export const registerAnalysisViewTool = (server, logger, evidenceById, recordEvidence, withAdmittedAnalysis) => {
     const contract = toolContract("inspect_analysis_view");
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
-        const result = await logToolExecution(logger, contract.name, () => Promise.resolve(inspectAnalysisView(input, evidenceById)));
-        if (!result.ok)
-            return server.delivery.toCallToolResult(result, contract);
-        const recorded = recordEvidence?.(result.value);
-        return server.delivery.toEvidenceToolResult(result.value, contract, recorded);
-    });
+    const handler = createEvidenceToolHandler(server, (input) => Promise.resolve(inspectAnalysisView(input, evidenceById)), logger, recordEvidence, withAdmittedAnalysis);
+    server.registerTool(contract.name, toolRegistrationOptions(contract), handler(contract));
 };

package/dist/server/registerAndroidTools.js

@@ -1,19 +1,10 @@
 import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js";
 import { toolContract } from "../contracts/toolContracts.js";
-import { logToolExecution } from "./toolLogging.js";
+import { createContractToolHandler } from "./contractToolHandler.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
 /** Bind Android handlers to their exact named contracts through shared workflows. */
-export const registerAndroidTools = (server, service, logger, recordEvidence) => {
-    const handler = (contract) => {
-        const name = contract.name;
-        return async (input, context) => {
-            const result = await logToolExecution(logger, name, () => service.execute(name, input, { signal: context.mcpReq.signal }));
-            if (!result.ok)
-                return server.delivery.toCallToolResult(result, contract);
-            const recorded = recordEvidence?.(result.value);
-            return server.delivery.toEvidenceToolResult(result.value, contract, recorded);
-        };
-    };
+export const registerAndroidTools = (server, service, logger, recordEvidence, withAdmittedAnalysis) => {
+    const handler = createContractToolHandler(server, service, logger, recordEvidence, withAdmittedAnalysis);
     const packageContract = toolContract("inspect_android_package");
     server.registerTool(packageContract.name, toolRegistrationOptions(packageContract), handler(packageContract));
     const searchContract = toolContract("search_android_classes");

package/dist/server/registerApktoolTools.js

@@ -0,0 +1,14 @@
+import { ApktoolResourceAnalysisService } from "../application/apktool/ApktoolResourceAnalysisService.js";
+import { toolContract } from "../contracts/toolContracts.js";
+import { createContractToolHandler } from "./contractToolHandler.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Bind Apktool handlers to their exact named contracts. */
+export const registerApktoolTools = (server, service, logger, recordEvidence, withAdmittedAnalysis) => {
+    const handler = createContractToolHandler(server, service, logger, recordEvidence, withAdmittedAnalysis);
+    for (const contract of [
+        toolContract("inspect_apktool_client"),
+        toolContract("decode_android_resources"),
+    ]) {
+        server.registerTool(contract.name, toolRegistrationOptions(contract), handler(contract));
+    }
+};

package/dist/server/registerApplicationTools/compareExportShapes.js

@@ -1,3 +1,4 @@
+import { runAdmittedToolOperation } from "../admittedToolOperation.js";
 import { resolvePairedEvidenceRequest } from "../../application/EvidenceInputResolver.js";
 import { recordSessionEvidenceSources } from "../sessionEvidence.js";
 import { compareJavaScriptExportShapesEvidenceValidated } from "../../application/javascript/JavaScriptApplicationWorkflowService.js";
@@ -9,7 +10,7 @@ import { recordResult } from "./helpers.js";
 const contract = applicationToolContract("compare_javascript_export_shapes");
 /** Register the execution-free exact JavaScript export-shape comparison. */
 export const registerCompareJavaScriptExportShapesTool = (server, options) => {
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => runAdmittedToolOperation(server, options.withAdmittedAnalysis, contract.name, context.mcpReq.signal, async () => {
         const resolved = resolvePairedEvidenceRequest(input, options.evidenceById);
         if (!resolved.ok)
             return server.delivery.toCallToolResult(resolved, contract);
@@ -17,14 +18,12 @@ export const registerCompareJavaScriptExportShapesTool = (server, options) => {
         const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(compareJavaScriptExportShapesEvidenceValidated(parsed)));
         if (!result.ok)
             return server.delivery.toCallToolResult(result, contract);
-        const recorded = recordSessionEvidenceSources(options.recordEvidence, [
-            parsed.left,
-            parsed.right,
-        ]);
+        const recorded = recordSessionEvidenceSources(options.recordEvidence, [parsed.left, parsed.right]);
         if (!recorded.ok)
             return server.delivery.toCallToolResult(recorded, contract);
         const comparison = javaScriptExportShapeComparisonResultSchema.parse(result.value.normalized_result);
-        const unknown = comparison.summary.unknown > 0;
+        const unknown = comparison.summary.unknown > 0 ||
+            comparison.coverage.status !== "complete-within-inputs";
         return recordResult({ ...options, delivery: server.delivery }, contract, result.value, unknown ? "javascript-export-shape" : undefined);
-    });
+    }));
 };

package/dist/server/registerApplicationTools/compareSourceToBundle.js

@@ -1,3 +1,4 @@
+import { runAdmittedToolOperation } from "../admittedToolOperation.js";
 import { resolveApplicationEvidenceRequest } from "../../application/EvidenceInputResolver.js";
 import { recordSessionEvidenceSources } from "../sessionEvidence.js";
 import { compareSourceToBundleEvidenceValidated } from "../../application/javascript/JavaScriptApplicationWorkflowService.js";
@@ -9,7 +10,7 @@ import { recordResult } from "./helpers.js";
 const contract = applicationToolContract("compare_source_to_bundle");
 /** Register conservative historical-source to bundle comparison. */
 export const registerCompareSourceToBundleTool = (server, options) => {
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => runAdmittedToolOperation(server, options.withAdmittedAnalysis, contract.name, context.mcpReq.signal, async () => {
         const resolved = resolveApplicationEvidenceRequest(input, options.evidenceById);
         if (!resolved.ok)
             return server.delivery.toCallToolResult(resolved, contract);
@@ -17,14 +18,12 @@ export const registerCompareSourceToBundleTool = (server, options) => {
         const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(compareSourceToBundleEvidenceValidated(parsed)));
         if (!result.ok)
             return server.delivery.toCallToolResult(result, contract);
-        const recorded = recordSessionEvidenceSources(options.recordEvidence, [
-            parsed.application,
-        ]);
+        const recorded = recordSessionEvidenceSources(options.recordEvidence, [parsed.application]);
         if (!recorded.ok)
             return server.delivery.toCallToolResult(recorded, contract);
         const comparison = sourceToBundleComparisonResultSchema.parse(result.value.normalized_result);
         return recordResult({ ...options, delivery: server.delivery }, contract, result.value, comparison.summary.unknown > 0
             ? "source-to-bundle-comparison"
             : undefined);
-    });
+    }));
 };

package/dist/server/registerApplicationTools/compareVersions.js

@@ -1,3 +1,4 @@
+import { runAdmittedToolOperation } from "../admittedToolOperation.js";
 import { resolvePairedEvidenceRequest } from "../../application/EvidenceInputResolver.js";
 import { recordSessionEvidenceSources } from "../sessionEvidence.js";
 import { compareApplicationVersionsEvidenceValidated } from "../../application/javascript/JavaScriptApplicationWorkflowService.js";
@@ -9,7 +10,7 @@ import { recordResult } from "./helpers.js";
 const compareContract = applicationToolContract("compare_application_versions");
 /** Register the provider-neutral JavaScript version comparison tool. */
 export const registerCompareApplicationVersionsTool = (server, options) => {
-    server.registerTool(compareContract.name, toolRegistrationOptions(compareContract), async (input) => {
+    server.registerTool(compareContract.name, toolRegistrationOptions(compareContract), async (input, context) => runAdmittedToolOperation(server, options.withAdmittedAnalysis, compareContract.name, context.mcpReq.signal, async () => {
         const resolved = resolvePairedEvidenceRequest(input, options.evidenceById);
         if (!resolved.ok)
             return server.delivery.toCallToolResult(resolved, compareContract);
@@ -29,5 +30,5 @@ export const registerCompareApplicationVersionsTool = (server, options) => {
         const comparison = applicationVersionComparisonResultSchema.parse(result.value.normalized_result);
         const unknown = comparison.summary.unknown > 0;
         return recordResult({ ...options, delivery: server.delivery }, compareContract, result.value, unknown ? "application-version-comparison" : undefined);
-    });
+    }));
 };

package/dist/server/registerApplicationTools/coverage.js

@@ -1,3 +1,4 @@
+import { runAdmittedToolOperation } from "../admittedToolOperation.js";
 import { evaluateReconstructionCoverage } from "../../application/ReconstructionCoverageService.js";
 import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
 import { logToolExecution } from "../toolLogging.js";
@@ -5,8 +6,8 @@ import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
 const contract = applicationToolContract("evaluate_reconstruction_coverage");
 /** Register the inline fail-closed reconstruction coverage evaluator. */
 export const registerCoverageTools = (server, options) => {
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => runAdmittedToolOperation(server, options.withAdmittedAnalysis, contract.name, context.mcpReq.signal, async () => {
         const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(evaluateReconstructionCoverage(input)));
         return server.delivery.toCallToolResult(result, contract);
-    });
+    }));
 };

package/dist/server/registerApplicationTools/helpers.js

@@ -6,11 +6,12 @@ export const recordResult = (options, contract, evidence, unknownKind) => {
     return options.delivery.toEvidenceToolResult(evidence, contract, recorded);
 };
 const unknownRegistration = (evidence, kind) => ({
-    question: kind === "application-version-comparison"
+    // Scope unknown identity to the comparison while keeping exact replays stable.
+    question: `${kind === "application-version-comparison"
         ? "Which application entities remain unmatched or ambiguous across these versions?"
         : kind === "source-to-bundle-comparison"
             ? "Which historical source files remain unmatched or ambiguously mapped to the shipped bundle?"
-            : "Which selected JavaScript export return shapes remain dynamic, incomplete, or ambiguously paired?",
+            : "Which selected JavaScript export return shapes remain dynamic, incomplete, or ambiguously paired?"} (comparison ${evidence.evidence_id})`,
     severity: "medium",
     domain: kind,
     supporting_evidence_ids: [evidence.evidence_id],

package/dist/server/registerApplicationTools/obligationLedger.js

@@ -1,3 +1,4 @@
+import { runAdmittedToolOperation } from "../admittedToolOperation.js";
 import { recordSessionEvidenceSources } from "../sessionEvidence.js";
 import { buildReconstructionObligationLedgerEvidenceValidated, resolveReconstructionObligationLedgerRequest, } from "../../application/ReconstructionObligationLedgerService.js";
 import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
@@ -7,7 +8,7 @@ import { recordResult } from "./helpers.js";
 const contract = applicationToolContract("build_reconstruction_obligation_ledger");
 /** Register conservative reconstruction-obligation generation and closure. */
 export const registerReconstructionObligationLedgerTool = (server, options) => {
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => runAdmittedToolOperation(server, options.withAdmittedAnalysis, contract.name, context.mcpReq.signal, async () => {
         const resolved = resolveReconstructionObligationLedgerRequest(input);
         if (!resolved.ok)
             return server.delivery.toCallToolResult(resolved, contract);
@@ -18,5 +19,5 @@ export const registerReconstructionObligationLedgerTool = (server, options) => {
         if (!recorded.ok)
             return server.delivery.toCallToolResult(recorded, contract);
         return recordResult({ ...options, delivery: server.delivery }, contract, result.value);
-    });
+    }));
 };

package/dist/server/registerApplicationTools/projectMobileApplicationGraph.js

@@ -1,3 +1,4 @@
+import { runAdmittedToolOperation } from "../admittedToolOperation.js";
 import { projectAndroidApplicationEvidence } from "../../application/android/AndroidApplicationService.js";
 import { projectAppleApplicationEvidence } from "../../application/apple/AppleApplicationService.js";
 import { APPLICATION_TOOL_CONTRACTS, applicationToolContract, } from "../../contracts/applicationToolContracts.js";
@@ -22,7 +23,7 @@ export const registerProjectMobileApplicationGraphTools = (server, options) => {
 };
 const registerProjection = (context) => {
     const { server, options, contract, project } = context;
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, request) => runAdmittedToolOperation(server, options.withAdmittedAnalysis, contract.name, request.mcpReq.signal, async () => {
         const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(project(input)));
         if (!result.ok)
             return server.delivery.toCallToolResult(result, contract);
@@ -30,7 +31,7 @@ const registerProjection = (context) => {
         if (!recordedSources.ok)
             return server.delivery.toCallToolResult(recordedSources, contract);
         return recordResult({ ...options, delivery: server.delivery }, contract, result.value);
-    });
+    }));
 };
 const inventoryEvidenceSources = (input) => {
     if (typeof input !== "object" ||

package/dist/server/registerApplicationTools/traceFeature.js

@@ -1,3 +1,4 @@
+import { runAdmittedToolOperation } from "../admittedToolOperation.js";
 import { resolveApplicationEvidenceRequest } from "../../application/EvidenceInputResolver.js";
 import { recordSessionEvidenceSources } from "../sessionEvidence.js";
 import { traceApplicationFeatureEvidenceValidated } from "../../application/javascript/JavaScriptApplicationWorkflowService.js";
@@ -8,7 +9,7 @@ import { recordResult } from "./helpers.js";
 const traceContract = applicationToolContract("trace_application_feature");
 /** Register the provider-neutral JavaScript feature trace tool. */
 export const registerTraceFeatureTool = (server, options) => {
-    server.registerTool(traceContract.name, toolRegistrationOptions(traceContract), async (input) => {
+    server.registerTool(traceContract.name, toolRegistrationOptions(traceContract), async (input, context) => runAdmittedToolOperation(server, options.withAdmittedAnalysis, traceContract.name, context.mcpReq.signal, async () => {
         const resolved = resolveApplicationEvidenceRequest(input, options.evidenceById);
         if (!resolved.ok)
             return server.delivery.toCallToolResult(resolved, traceContract);
@@ -21,5 +22,5 @@ export const registerTraceFeatureTool = (server, options) => {
         if (!recorded.ok)
             return server.delivery.toCallToolResult(recorded, traceContract);
         return recordResult({ ...options, delivery: server.delivery }, traceContract, result.value);
-    });
+    }));
 };

package/dist/server/registerApplicationTools/traceSemantics.js

@@ -1,3 +1,4 @@
+import { runAdmittedToolOperation } from "../admittedToolOperation.js";
 import { resolveApplicationEvidenceRequest } from "../../application/EvidenceInputResolver.js";
 import { recordSessionEvidenceSources } from "../sessionEvidence.js";
 import { traceJavaScriptSemanticsEvidenceValidated } from "../../application/javascript/JavaScriptSemanticTraceService.js";
@@ -8,7 +9,7 @@ import { recordResult } from "./helpers.js";
 const contract = applicationToolContract("trace_javascript_semantics");
 /** Register the bounded JavaScript semantic relation trace tool. */
 export const registerTraceJavaScriptSemanticsTool = (server, options) => {
-    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => runAdmittedToolOperation(server, options.withAdmittedAnalysis, contract.name, context.mcpReq.signal, async () => {
         const resolved = resolveApplicationEvidenceRequest(input, options.evidenceById);
         if (!resolved.ok)
             return server.delivery.toCallToolResult(resolved, contract);
@@ -16,11 +17,9 @@ export const registerTraceJavaScriptSemanticsTool = (server, options) => {
         const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(traceJavaScriptSemanticsEvidenceValidated(parsed)));
         if (!result.ok)
             return server.delivery.toCallToolResult(result, contract);
-        const recorded = recordSessionEvidenceSources(options.recordEvidence, [
-            parsed.application,
-        ]);
+        const recorded = recordSessionEvidenceSources(options.recordEvidence, [parsed.application]);
         if (!recorded.ok)
             return server.delivery.toCallToolResult(recorded, contract);
         return recordResult({ ...options, delivery: server.delivery }, contract, result.value);
-    });
+    }));
 };