rea-agents 6.3.0 → 6.5.0

package/dist/server/registerAndroidTools.js

@@ -1,23 +1,32 @@
 import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js";
+import { inspectAndroidPackage } from "../application/android/AndroidPackageInspection.js";
+import { summarizeRetainedAndroidSearch } from "../application/android/AndroidSearchEvidenceSummary.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, evidenceById) => {
+    const handler = createContractToolHandler(server, service, logger, recordEvidence, withAdmittedAnalysis);
+    // Focused class searches keep complete raw inventory in the retained
+    // record and deliver a bounded summary inline; the generic handler then
+    // records and delivers the summary as the search contract's Evidence.
+    const searchService = {
+        execute: async (operation, input, options) => {
+            const executed = await service.execute(operation, input, options);
+            if (!executed.ok)
+                return executed;
+            return summarizeRetainedAndroidSearch(executed.value, recordEvidence);
+        },
     };
+    const searchHandler = createContractToolHandler(server, searchService, logger, recordEvidence, withAdmittedAnalysis);
     const packageContract = toolContract("inspect_android_package");
-    server.registerTool(packageContract.name, toolRegistrationOptions(packageContract), handler(packageContract));
+    const packageService = {
+        execute: (_operation, input, options) => inspectAndroidPackage(service, input, { recordEvidence, evidenceById }, options),
+    };
+    const packageHandler = createContractToolHandler(server, packageService, logger, recordEvidence, withAdmittedAnalysis);
+    server.registerTool(packageContract.name, toolRegistrationOptions(packageContract), packageHandler(packageContract));
     const searchContract = toolContract("search_android_classes");
-    server.registerTool(searchContract.name, toolRegistrationOptions(searchContract), handler(searchContract));
+    server.registerTool(searchContract.name, toolRegistrationOptions(searchContract), searchHandler(searchContract));
     const classContract = toolContract("inspect_android_class");
     server.registerTool(classContract.name, toolRegistrationOptions(classContract), handler(classContract));
     const methodContract = toolContract("inspect_android_method");

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,15 +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 ||
             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/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,11 +1,13 @@
+import { runAdmittedToolOperation } from "../admittedToolOperation.js";
 import { projectAndroidApplicationEvidence } from "../../application/android/AndroidApplicationService.js";
 import { projectAppleApplicationEvidence } from "../../application/apple/AppleApplicationService.js";
+import { projectHarmonyApplicationEvidence } from "../../application/harmony/HarmonyApplicationService.js";
 import { APPLICATION_TOOL_CONTRACTS, applicationToolContract, } from "../../contracts/applicationToolContracts.js";
 import { recordSessionEvidenceSources } from "../sessionEvidence.js";
 import { logToolExecution } from "../toolLogging.js";
 import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
 import { recordResult } from "./helpers.js";
-/** Register execution-free Android and Apple inventory projection tools. */
+/** Register execution-free mobile application inventory projection tools. */
 export const registerProjectMobileApplicationGraphTools = (server, options) => {
     registerProjection({
         server,
@@ -19,10 +21,16 @@ export const registerProjectMobileApplicationGraphTools = (server, options) => {
         contract: applicationToolContract("project_apple_application_graph"),
         project: projectAppleApplicationEvidence,
     });
+    registerProjection({
+        server,
+        options,
+        contract: applicationToolContract("project_harmony_application_graph"),
+        project: projectHarmonyApplicationEvidence,
+    });
 };
 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 +38,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);
-    });
+    }));
 };

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

@@ -1,10 +1,30 @@
-import { ARTIFACT_TOOL_CONTRACTS } from "../contracts/artifactToolContracts.js";
+import { ARTIFACT_TOOL_CONTRACTS, artifactInspectionInputSchema, } from "../contracts/artifactToolContracts.js";
+import { createArtifactExtractionDestination } from "../application/artifacts/ArtifactExtractionDestination.js";
 import { registerEvidenceTools } from "./registerEvidenceTools.js";
 import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
+import { retainedSummaryDelivery, withoutDeliveryDetail, } from "./retainedSummaryDelivery.js";
+/** Operations whose MCP delivery may be a retained summary view. */
+const SUMMARY_DELIVERY = new Set([
+    "inspect_artifact",
+    "decode_interface_builder",
+]);
+/** inspect_artifact keeps an explicit detail in its Evidence parameters. */
+const decodeWithoutDelivery = withoutDeliveryDetail(new Set(["decode_interface_builder"]));
 /** Register deterministic artifact inventory and safe extraction operations. */
 export const registerArtifactTools = (server, options) => {
     registerEvidenceTools(server, ARTIFACT_TOOL_CONTRACTS, {
         ...options,
+        ...retainedSummaryDelivery(SUMMARY_DELIVERY, options),
+        parametersForExecution: (operation, parameters) => {
+            if (operation === "inspect_artifact") {
+                const { detail: _detail, ...execution } = artifactInspectionInputSchema.parse(parameters);
+                return execution;
+            }
+            return operation === "extract_artifact"
+                ? { ...parameters, output_root: createArtifactExtractionDestination() }
+                : decodeWithoutDelivery(operation, parameters);
+        },
+        parametersForEvidence: decodeWithoutDelivery,
         sourceEvidence: (operation, result) => operation === "inspect_artifact"
             ? artifactInspectionResultSchema
                 .parse(result)

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

@@ -2,15 +2,14 @@ import { optionalProviderUnavailable, } from "../application/OptionalObservation
 import { err } from "../domain/result.js";
 import { analyzeWebBundle, captureWebScreenshot, compareWebCaptureEvidence, compareWebScreenshotEvidence, discoverWebMcpTools, inspectWebPage, listBrowserTargets, observeWebSession, } from "../application/BrowserObservationService.js";
 import { toolContract } from "../contracts/toolContracts.js";
-import { analyzeWebBundleInputSchema } from "../domain/webBundleAnalysis.js";
-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");
@@ -22,8 +21,8 @@ export const registerBrowserTools = (server, options) => {
     server.registerTool(listContract.name, toolRegistrationOptions(listContract), (input, context) => runBrowserTool(registration, listContract, { input, context }, (parsed, { signal }) => listBrowserTargets(options.browser, parsed, {
         signal,
     })));
-    server.registerTool(inspectContract.name, toolRegistrationOptions(inspectContract), (input, context) => runBrowserTool(registration, inspectContract, { input, context }, (parsed, { signal, progress }) => inspectWebPage(options.browser, inspectWebPageInputSchema.parse(parsed), { signal, progress })));
-    server.registerTool(analyzeContract.name, toolRegistrationOptions(analyzeContract), (input, context) => runBrowserTool(registration, analyzeContract, { input, context }, (parsed, { signal, progress }) => analyzeWebBundle(options.browser, analyzeWebBundleInputSchema.parse(parsed), {
+    server.registerTool(inspectContract.name, toolRegistrationOptions(inspectContract), (input, context) => runBrowserTool(registration, inspectContract, { input, context }, (parsed, { signal, progress }) => inspectWebPage(options.browser, parsed, { signal, progress })));
+    server.registerTool(analyzeContract.name, toolRegistrationOptions(analyzeContract), (input, context) => runBrowserTool(registration, analyzeContract, { input, context }, (parsed, { signal, progress }) => analyzeWebBundle(options.browser, parsed, {
         signal,
         progress,
     })));
@@ -46,12 +45,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

@@ -1,17 +1,21 @@
-import { readEvidenceBundle } from "../application/EvidenceBundleFiles.js";
+import { readImmutableEvidenceBundle } from "../application/EvidenceBundleFiles.js";
 import { toolContract } from "../contracts/toolContracts.js";
 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) => {
+export const registerBundleComparisonTool = (server, session, contract, resources) => {
+    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),
+            readImmutableEvidenceBundle(input.left_bundle_path, context.mcpReq.signal, resources),
+            readImmutableEvidenceBundle(input.right_bundle_path, context.mcpReq.signal, resources),
         ]);
         if (!left.ok)
             return server.delivery.toCallToolResult(left, contract);
@@ -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/registerCaptureTools.js

@@ -0,0 +1,12 @@
+import { toolContract } from "../contracts/toolContracts.js";
+import { createEvidenceToolHandler } from "./contractToolHandler.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Bind the named capture contract through shared admission and retained Evidence delivery. */
+export const registerCaptureTools = (server, service, logger, recordEvidence, withAdmittedAnalysis) => {
+    const contract = toolContract("inspect_packet_capture");
+    const handler = createEvidenceToolHandler(server, (input, options) => service.inspect(input, options), logger, recordEvidence, withAdmittedAnalysis);
+    server.registerTool(contract.name, toolRegistrationOptions(contract), handler(contract));
+    const discovery = toolContract("inspect_packet_fields");
+    const discover = createEvidenceToolHandler(server, (input, options) => service.inspectFields(input, options), logger, recordEvidence, withAdmittedAnalysis);
+    server.registerTool(discovery.name, toolRegistrationOptions(discovery), discover(discovery));
+};

package/dist/server/registerCloseLifecycleTool.js

@@ -4,20 +4,49 @@ 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, () => session.close({ progress }));
+            const closing = logToolExecution(logger, closeContract.name, () => closeWithResources(() => session.close({ progress })));
             await reportLifecycleStart(progress, closeContract.name);
             const closed = await closing;
             await reportLifecycleEnd(progress, closeContract.name, closed.ok);
             return server.delivery.toCallToolResult(closed, closeContract);
         }
-        const closing = logToolExecution(logger, closeContract.name, () => session.closeWithSnapshot(snapshotPath, input.overwrite, { progress }));
+        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);

package/dist/server/registerCutterTools.js

@@ -0,0 +1,33 @@
+import { toolContract } from "../contracts/toolContracts.js";
+import { ok } from "../domain/result.js";
+import { evidenceSchema } from "../domain/evidence.js";
+import { runWithExternalMutationAdmission, } from "./externalMutationAdmission.js";
+import { logToolExecution } from "./toolLogging.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Register Cutter discovery and command tools against their named contracts. */
+export const registerCutterTools = (server, service, logger, delivery, recordEvidence, session) => {
+    const list = toolContract("list_cutter_sessions");
+    const command = toolContract("cutter_command");
+    server.registerTool(list.name, toolRegistrationOptions(list), async () => {
+        const result = await logToolExecution(logger, list.name, async () => ok(await service.listSessions()));
+        if (!result.ok)
+            return delivery.toCallToolResult(result, list);
+        return delivery.toCallToolResult({
+            ok: true,
+            value: { ...result.value, sessions: [...result.value.sessions] },
+        }, list);
+    });
+    server.registerTool(command.name, toolRegistrationOptions(command), async (input, context) => {
+        const result = await runWithExternalMutationAdmission(session, command.name, context.mcpReq.signal, () => logToolExecution(logger, command.name, () => service.execute(input, { signal: context.mcpReq.signal })), (value) => value, () => service.retryCleanup());
+        if (!result.ok) {
+            const partial = evidenceSchema.safeParse(result.error.partialObservation);
+            if (partial.success) {
+                const recorded = recordEvidence?.(partial.data);
+                if (recorded !== undefined)
+                    return delivery.toRecordedPartialErrorToolResult(result.error, partial.data.evidence_id, recorded, command.returnsTargetContent);
+            }
+            return delivery.toCallToolResult(result, command);
+        }
+        return delivery.toEvidenceToolResult(result.value, command, recordEvidence?.(result.value));
+    });
+};