rea-agents 2.3.0 → 2.5.0

package/dist/mcpDoctor.js

@@ -61,10 +61,11 @@ const inspectProductionMcpSession = async (client, deadline, signal) => {
         client.listResources(undefined, request),
         client.listResourceTemplates(undefined, request),
         client.readResource({ uri: "rea://server/identity" }, request),
-        client.callTool({ name: "binary_session", arguments: {} }, request),
+        client.callTool({ name: "binary_session", arguments: { detail: "full" } }, request),
     ]);
+    const expectedToolNames = availableToolNames(requestFlow.structuredContent) ?? [];
     const inventory = {
-        tools: compareInventory(CATALOG_IDENTITY.tools.map(({ name }) => name), tools.tools.map(({ name }) => name)),
+        tools: compareInventory(expectedToolNames, tools.tools.map(({ name }) => name)),
         prompts: compareInventory(PROMPT_CONTRACTS.map(({ name }) => name), prompts.prompts.map(({ name }) => name)),
         resources: compareInventory(MCP_RESOURCE_CATALOG.map(({ name }) => name), resources.resources.map(({ name }) => name)),
         resource_templates: compareInventory(MCP_RESOURCE_TEMPLATE_CATALOG.map(({ name }) => name), templates.resourceTemplates.map(({ name }) => name)),
@@ -116,6 +117,28 @@ const inspectProductionMcpSession = async (client, deadline, signal) => {
         checks,
     };
 };
+const availableToolNames = (structuredContent) => {
+    if (typeof structuredContent !== "object" || structuredContent === null)
+        return undefined;
+    const result = Reflect.get(structuredContent, "result");
+    if (typeof result !== "object" || result === null)
+        return undefined;
+    const availability = Reflect.get(result, "tool_availability");
+    if (!Array.isArray(availability))
+        return undefined;
+    const names = [];
+    for (const item of availability) {
+        if (typeof item !== "object" || item === null)
+            return undefined;
+        const name = Reflect.get(item, "name");
+        const available = Reflect.get(item, "available");
+        if (typeof name !== "string" || typeof available !== "boolean")
+            return undefined;
+        if (available)
+            names.push(name);
+    }
+    return names;
+};
 /**
  * Dispatcher entry for `rea mcp doctor`, kept separate from Incur MCP setup.
  * @public

package/dist/native/NativeMacOSProvider.js

@@ -35,6 +35,7 @@ export class NativeMacOSProvider {
                 ? { available: true, reason: null }
                 : {
                     available: false,
+                    availabilityCode: "unsupported_host",
                     reason: "Native macOS utilities require macOS.",
                 };
             return Object.freeze({

package/dist/process/ProcessCommandIdentity.js

@@ -0,0 +1,19 @@
+import { basename } from "node:path";
+/** Match process-table command text while handling macOS executable-name normalization. */
+export const matchesOwnedProcessCommand = (actual, expected, platform = process.platform) => {
+    const actualCommand = actual.trim();
+    const expectedCommand = expected.trim();
+    if (actualCommand === expectedCommand ||
+        actualCommand.startsWith(`${expectedCommand} `))
+        return true;
+    if (platform !== "darwin")
+        return false;
+    const actualExecutable = actualCommand.split(/\s+/u, 1)[0];
+    const expectedExecutable = expectedCommand.split(/\s+/u, 1)[0];
+    const normalizedActualExecutable = actualExecutable?.startsWith("(") === true && actualExecutable.endsWith(")")
+        ? actualExecutable.slice(1, -1)
+        : actualExecutable;
+    return (normalizedActualExecutable !== undefined &&
+        expectedExecutable !== undefined &&
+        basename(normalizedActualExecutable) === basename(expectedExecutable));
+};

package/dist/process/ProcessOwnership.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
+import { matchesOwnedProcessCommand } from "./ProcessCommandIdentity.js";
 const execFileAsync = promisify(execFile);
 /**
  * Terminate one Windows process tree through the platform utility.
@@ -168,8 +169,8 @@ const launcherIdentityFailure = (launcher, ownership) => {
         launcher.parentPid !== ownership.expectedParentPid)
         return "owned launcher parent identity did not match";
     if (ownership.expectedCommand !== undefined &&
-        !commandMatches(launcher.command, ownership.expectedCommand))
-        return "owned launcher command identity did not match";
+        !matchesOwnedProcessCommand(launcher.command, ownership.expectedCommand))
+        return `owned launcher command identity did not match (observed=${launcher.command}; expected=${ownership.expectedCommand})`;
     return null;
 };
 const revalidateOwnedProcessGroup = async (processGroupId, ownership, host) => {
@@ -218,6 +219,12 @@ const processOwnershipFailures = async (members, runId, host) => {
                 failures.push({ pid: member.pid, reason: "run-token-mismatch" });
         }
         catch {
+            try {
+                const live = liveProcesses(await host.listProcesses());
+                if (!live.some(({ pid }) => pid === member.pid))
+                    continue;
+            }
+            catch { }
             failures.push({ pid: member.pid, reason: "environment-unreadable" });
         }
     }
@@ -280,8 +287,8 @@ export const observeOwnedProcessLineage = async (ownership, host = systemHost) =
         launcher.parentPid !== ownership.expectedParentPid)
         return unavailableLineage(ownership, "owned launcher parent identity did not match");
     if (ownership.expectedCommand !== undefined &&
-        !commandMatches(launcher.command, ownership.expectedCommand))
-        return unavailableLineage(ownership, "owned launcher command identity did not match");
+        !matchesOwnedProcessCommand(launcher.command, ownership.expectedCommand))
+        return unavailableLineage(ownership, `owned launcher command identity did not match (observed=${launcher.command}; expected=${ownership.expectedCommand})`);
     const descendants = descendantsOf(launcher.pid, processes);
     for (const member of [launcher, ...descendants]) {
         try {
@@ -340,7 +347,3 @@ const unavailableLineage = (ownership, reason) => ({
     reason,
 });
 const liveProcesses = (members) => members.filter(({ state }) => !state.startsWith("Z"));
-const commandMatches = (actual, expected) => {
-    return (actual.trim() === expected.trim() ||
-        actual.trim().startsWith(`${expected.trim()} `));
-};

package/dist/server/DynamicToolAvailability.js

@@ -0,0 +1,70 @@
+import { buildCapabilityInventory, } from "../application/CapabilityInventory.js";
+/**
+ * Track public SDK tool handles and keep their visible state synchronized with
+ * the same availability projection returned by `binary_session`.
+ */
+export const installDynamicToolAvailability = (server, session, policy) => {
+    const tools = new Map();
+    const originalRegisterTool = server.registerTool.bind(server);
+    const originalSendToolListChanged = server.sendToolListChanged.bind(server);
+    let synchronizing = false;
+    const controller = {
+        synchronize: () => {
+            if (synchronizing)
+                return false;
+            synchronizing = true;
+            try {
+                const availability = new Map(buildCapabilityInventory(session.status(), policy(), clientFeatures(server)).map((item) => [item.name, item.available]));
+                let changed = false;
+                for (const [name, tool] of tools) {
+                    const enabled = availability.get(name) === true;
+                    if (tool.enabled === enabled)
+                        continue;
+                    changed = true;
+                    if (enabled)
+                        tool.enable();
+                    else
+                        tool.disable();
+                }
+                return changed;
+            }
+            finally {
+                synchronizing = false;
+            }
+        },
+    };
+    const wrappedRegisterTool = (...args) => {
+        const name = args[0];
+        if (typeof name !== "string")
+            throw new TypeError("MCP tool registration requires a string name");
+        const registered = Reflect.apply(originalRegisterTool, server, args);
+        if (!isRegisteredTool(registered))
+            throw new TypeError(`MCP SDK did not return a tool handle for ${name}`);
+        tools.set(name, registered);
+        return registered;
+    };
+    if (!Reflect.set(server, "registerTool", wrappedRegisterTool))
+        throw new TypeError("Unable to install dynamic MCP tool registration");
+    if (!Reflect.set(server, "sendToolListChanged", () => {
+        if (controller.synchronize())
+            originalSendToolListChanged();
+    }))
+        throw new TypeError("Unable to install dynamic MCP tool notifications");
+    return controller;
+};
+const clientFeatures = (server) => {
+    const capabilities = server.server.getClientCapabilities();
+    return {
+        elicitation_form: capabilities?.elicitation?.form !== undefined,
+        elicitation_url: capabilities?.elicitation?.url !== undefined,
+        roots: capabilities?.roots !== undefined,
+        sampling: capabilities?.sampling !== undefined,
+    };
+};
+const isRegisteredTool = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return (typeof Reflect.get(value, "enabled") === "boolean" &&
+        typeof Reflect.get(value, "enable") === "function" &&
+        typeof Reflect.get(value, "disable") === "function");
+};

package/dist/server/createServer.js

@@ -13,13 +13,39 @@ import { registerGuidedPrompts } from "./registerPrompts.js";
 import { registerEvidenceResources } from "./registerEvidenceResources.js";
 import { createServerIdentity } from "../serverIdentity.js";
 import { registerBrowserTools } from "./registerBrowserTools.js";
+import { registerBrowserScenarioTool } from "./registerBrowserScenarioTool.js";
 import { registerElectronTools } from "./registerElectronTools.js";
+import { registerJavaScriptRuntimeObservationTools } from "./registerJavaScriptRuntimeObservationTools.js";
 import { registerApplicationTools } from "./registerApplicationTools.js";
-const TARGET_FREE_INSTRUCTIONS = "REA analyzes shipped artifacts. Route: ASAR/JavaScript -> analyze_javascript_application (configured root required); archive/package -> inventory_artifact; managed PE/CLI -> inspect_managed_artifact; browser/Electron runtime -> list_browser_targets/list_electron_targets; native binary/database -> open_binary, then binary_overview. Check binary_session for policy. Start with summaries and cite Evidence IDs. Never repeat identical analysis or read full Evidence without a specific need.";
+import { sessionAvailabilityPolicy } from "./sessionAvailabilityPolicy.js";
+import { DENY_EVIDENCE_FILE_POLICY, DENY_PROCESS_POLICY, } from "./sessionToolPolicies.js";
+import { installDynamicToolAvailability } from "./DynamicToolAvailability.js";
+const TARGET_FREE_INSTRUCTIONS = "REA analyzes shipped artifacts. Route: ASAR/JavaScript -> analyze_javascript_application (configured root); archive/package -> inspect_artifact; managed PE/CLI -> inspect_managed_artifact; passive browser/Electron -> list_browser_targets/list_electron_targets; approved browser interaction -> capture_browser_scenario; Node/Electron Inspector -> list_javascript_runtime_targets; native binary/database -> open_binary, then binary_overview. Check binary_session policy. Start with summaries and cite Evidence IDs. Never repeat identical analysis or read full Evidence without need.";
 const ACTIVE_TARGET_INSTRUCTIONS = "REA analyzes the active reverse-engineering target. Start native analysis with binary_overview, then narrow with analyze_function, literal search, callers, callees, and xrefs. Prefer summary views, never repeat an identical call, and read full Evidence only when the task requires it.";
 import { LinuxJavaScriptReplayRunner } from "../replay/LinuxJavaScriptReplayRunner.js";
 import { SystemJavaScriptReplayHost } from "../replay/SystemJavaScriptReplayHost.js";
 import { PROCESS_CAPTURE_ELICITATION_POLICY, } from "./ProcessCaptureElicitation.js";
+const installSessionToolAvailability = (server, session, options) => {
+    if (session === undefined)
+        return undefined;
+    const policy = sessionAvailabilityPolicy(options.availabilityPolicy, {
+        processPolicy: options.processPolicy ?? DENY_PROCESS_POLICY,
+        evidenceFilePolicy: options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY,
+        investigationInputRoots: options.investigationInputRoots ?? [],
+        optionalFeatures: {
+            browserObservationEnabled: options.browserObservation !== undefined,
+            browserScenarioEnabled: options.browserScenarioCapture !== undefined,
+            electronObservationEnabled: options.electronObservation !== undefined,
+            v8InspectorObservationEnabled: options.javascriptRuntimeObservation !== undefined,
+            javascriptReplayEnabled: options.javascriptReplayPolicy?.enabled ?? false,
+            managedRuntimeEnabled: options.managedRuntimePolicy?.enabled ?? false,
+        },
+    });
+    return {
+        policy,
+        controller: installDynamicToolAvailability(server, session, policy),
+    };
+};
 /**
  * Construct one MCP server without acquiring subprocess resources.
  * Supplying a session adds target lifecycle tools; omitting it retains the
@@ -50,9 +76,12 @@ export const createServer = (analysis, session, options = {}) => {
             ? ACTIVE_TARGET_INSTRUCTIONS
             : TARGET_FREE_INSTRUCTIONS,
     });
+    const dynamicTools = installSessionToolAvailability(server, session, options);
     server.server.onclose = () => {
         permissionAuthority?.clearSessionGrants();
     };
+    if (dynamicTools !== undefined)
+        server.server.oninitialized = () => server.sendToolListChanged();
     session?.onAvailabilityChanged?.(() => server.sendToolListChanged());
     registerServerIdentityResource(server, startedAt);
     const toolLogger = logger.child({ layer: "server" });
@@ -75,6 +104,9 @@ export const createServer = (analysis, session, options = {}) => {
         registerEvidenceResources(server, session);
         registerSessionTools(server, session, toolLogger, {
             ...options,
+            ...(dynamicTools === undefined
+                ? {}
+                : { availabilityPolicy: dynamicTools.policy }),
             ...(permissionAuthority === undefined ? {} : { permissionAuthority }),
             startedAt,
             processCaptureElicitation: {
@@ -94,6 +126,7 @@ export const createServer = (analysis, session, options = {}) => {
             },
         });
     }
+    dynamicTools?.controller.synchronize();
     return server;
 };
 const createSessionRecorders = (server, session) => ({
@@ -195,12 +228,24 @@ const registerObservationTools = ({ server, session, options, logger, permission
         permissionAuthority,
         recordEvidence,
     });
+    registerBrowserScenarioTool(server, {
+        logger,
+        provider: options.browserScenarioCapture,
+        permissionAuthority,
+        recordEvidence,
+    });
     registerElectronTools(server, {
         logger,
         electron: options.electronObservation,
         permissionAuthority,
         recordEvidence,
     });
+    registerJavaScriptRuntimeObservationTools(server, {
+        logger,
+        runtime: options.javascriptRuntimeObservation,
+        permissionAuthority,
+        recordEvidence,
+    });
     registerApplicationTools(server, {
         logger,
         recordEvidence,

package/dist/server/lifecycleProgress.js

@@ -0,0 +1,10 @@
+/** Report one lifecycle operation start through the shared monotonic boundary. */
+export const reportLifecycleStart = (progress, phase, message = "started") => progress.report({ phase, completed: 0, total: 1, message });
+/** Report one lifecycle operation's terminal disposition. */
+export const reportLifecycleEnd = (progress, phase, succeeded) => progress.report({
+    phase,
+    completed: 1,
+    total: 1,
+    message: succeeded ? "completed" : "failed",
+    terminal: true,
+});

package/dist/server/permissionFailure.js

@@ -0,0 +1,12 @@
+import { AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
+import { err } from "../domain/result.js";
+/** Preserve a typed permission denial or contain an unexpected authority error. */
+export const permissionFailure = (failure) => {
+    if (failure.ok)
+        return err(new AnalysisProtocolError("Expected a denied permission"));
+    return err(failure.error instanceof PermissionRequiredError
+        ? failure.error
+        : new AnalysisProtocolError(failure.error.message, {
+            cause: failure.error,
+        }));
+};

package/dist/server/registerApplicationTools/compareSourceToBundle.js

@@ -0,0 +1,35 @@
+import { compareSourceToBundleEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
+import { resolveCompareSourceToBundleRequestValidated } from "../../application/ApplicationWorkflowEvidenceResolver.js";
+import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
+import { compareSourceToBundleRequestSchema } from "../../contracts/applicationWorkflowInputContracts.js";
+import { sourceToBundleComparisonResultSchema } from "../../domain/sourceToBundleComparisonSchemas.js";
+import { logToolExecution } from "../toolLogging.js";
+import { safeParseToolInput } from "../toolInputValidation.js";
+import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
+import { toCallToolResult } from "../toolResult.js";
+import { recordResult, recordSources } 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) => {
+        const parsedInput = safeParseToolInput(compareSourceToBundleRequestSchema, input, contract.name);
+        if (!parsedInput.ok)
+            return toCallToolResult(parsedInput, contract);
+        const resolved = resolveCompareSourceToBundleRequestValidated(parsedInput.value, options.evidenceLookup);
+        if (!resolved.ok)
+            return toCallToolResult(resolved, contract);
+        const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(compareSourceToBundleEvidenceValidated(resolved.value)));
+        if (!result.ok)
+            return toCallToolResult(result, contract);
+        const recorded = recordSources(options.recordEvidence, [
+            resolved.value.application,
+        ]);
+        if (!recorded.ok)
+            return toCallToolResult(recorded, contract);
+        const comparison = sourceToBundleComparisonResultSchema.parse(result.value.normalized_result);
+        return recordResult(options, contract, result.value, resolved.value.unknown_registry_approved === true &&
+            comparison.summary.unknown > 0
+            ? "source-to-bundle-comparison"
+            : undefined);
+    });
+};

package/dist/server/registerApplicationTools/helpers.js

@@ -23,7 +23,9 @@ const unknownRegistration = (evidence, kind) => ({
     approved: true,
     question: kind === "application-version-comparison"
         ? "Which application entities remain unmatched or ambiguous across these versions?"
-        : "Which selected JavaScript export return shapes remain dynamic, incomplete, or ambiguously paired?",
+        : 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?",
     severity: "medium",
     domain: kind,
     supporting_evidence_ids: [evidence.evidence_id],
@@ -43,12 +45,14 @@ const unknownRegistration = (evidence, kind) => ({
                     rationale: "Add approved passive runtime Evidence without promoting it to static fact.",
                 },
             ]
-            : [
-                {
-                    operation: "run_controlled_replay",
-                    rationale: "Validate exact approved module behavior separately when runtime semantics are required.",
-                },
-            ]),
+            : kind === "source-to-bundle-comparison"
+                ? []
+                : [
+                    {
+                        operation: "run_controlled_replay",
+                        rationale: "Validate exact approved module behavior separately when runtime semantics are required.",
+                    },
+                ]),
     ],
     relationships: [],
 });

package/dist/server/registerApplicationTools/obligationLedger.js

@@ -0,0 +1,27 @@
+import { buildReconstructionObligationLedgerEvidenceValidated, resolveReconstructionObligationLedgerRequest, } from "../../application/ReconstructionObligationLedgerService.js";
+import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
+import { reconstructionObligationLedgerInputSchema } from "../../domain/reconstructionObligationLedgerSchemas.js";
+import { logToolExecution } from "../toolLogging.js";
+import { safeParseToolInput } from "../toolInputValidation.js";
+import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
+import { toCallToolResult } from "../toolResult.js";
+import { recordResult, recordSources } 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) => {
+        const parsed = safeParseToolInput(reconstructionObligationLedgerInputSchema, input, contract.name);
+        if (!parsed.ok)
+            return toCallToolResult(parsed, contract);
+        const resolved = resolveReconstructionObligationLedgerRequest(parsed.value);
+        if (!resolved.ok)
+            return toCallToolResult(resolved, contract);
+        const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(buildReconstructionObligationLedgerEvidenceValidated(resolved.value)));
+        if (!result.ok)
+            return toCallToolResult(result, contract);
+        const recorded = recordSources(options.recordEvidence, resolved.value.evidence_bundle.records);
+        if (!recorded.ok)
+            return toCallToolResult(recorded, contract);
+        return recordResult(options, contract, result.value);
+    });
+};

package/dist/server/registerApplicationTools/readiness.js

@@ -0,0 +1,55 @@
+import { evaluateReconstructionReadinessValidated, resolveReconstructionReadinessRequest, } from "../../application/ReconstructionReadinessService.js";
+import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
+import { reconstructionReadinessInputSchema } from "../../domain/reconstructionReadinessSchemas.js";
+import { reconstructionReadinessReportSchema } from "../../domain/reconstructionReadinessSchemas.js";
+import { logToolExecution } from "../toolLogging.js";
+import { safeParseToolInput } from "../toolInputValidation.js";
+import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
+import { toCallToolResult } from "../toolResult.js";
+import { recordSources } from "./helpers.js";
+const contract = applicationToolContract("evaluate_reconstruction_readiness");
+/** Register deterministic public-contract reconstruction conformance. */
+export const registerReconstructionReadinessTool = (server, options) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input) => {
+        const parsed = safeParseToolInput(reconstructionReadinessInputSchema, input, contract.name);
+        if (!parsed.ok)
+            return toCallToolResult(parsed, contract);
+        const resolved = resolveReconstructionReadinessRequest(parsed.value);
+        if (!resolved.ok)
+            return toCallToolResult(resolved, contract);
+        const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(evaluateReconstructionReadinessValidated(resolved.value)));
+        if (!result.ok)
+            return toCallToolResult(result, contract);
+        const recorded = recordSources(options.recordEvidence, resolved.value.evidence_bundle.records);
+        if (!recorded.ok)
+            return toCallToolResult(recorded, contract);
+        const recordedResult = options.recordEvidence?.(result.value);
+        if (recordedResult !== undefined && !recordedResult.ok)
+            return toCallToolResult(recordedResult, contract);
+        const report = reconstructionReadinessReportSchema.parse(result.value.normalized_result);
+        const reportUri = `rea://evidence/${result.value.evidence_id}/reconstruction-readiness-report`;
+        const projection = {
+            schema: report.schema,
+            schema_version: report.schema_version,
+            report_id: report.report_id,
+            source_digest: report.source_digest,
+            report_digest: report.report_digest,
+            status: report.status,
+            summary: report.summary,
+            metrics: report.metrics,
+            report_resource_uri: reportUri,
+        };
+        return toCallToolResult({ ok: true, value: result.value }, contract, {
+            evidenceResourcesAvailable: recordedResult !== undefined,
+            evidenceResultProjection: projection,
+            evidenceTextProjection: projection,
+            resourceLinks: [
+                {
+                    uri: reportUri,
+                    name: report.report_id,
+                    description: "Full deterministic reconstruction readiness report",
+                },
+            ],
+        });
+    });
+};

package/dist/server/registerApplicationTools.js

@@ -1,17 +1,23 @@
 import { registerTraceFeatureTool } from "./registerApplicationTools/traceFeature.js";
 import { registerTraceJavaScriptSemanticsTool } from "./registerApplicationTools/traceSemantics.js";
 import { registerCompareApplicationVersionsTool } from "./registerApplicationTools/compareVersions.js";
+import { registerCompareSourceToBundleTool } from "./registerApplicationTools/compareSourceToBundle.js";
 import { registerCompareJavaScriptExportShapesTool } from "./registerApplicationTools/compareExportShapes.js";
 import { registerControlledReplayTool } from "./registerApplicationTools/controlledReplay.js";
 import { registerCharacterizationTools } from "./registerApplicationTools/characterization.js";
 import { registerCoverageTools } from "./registerApplicationTools/coverage.js";
+import { registerReconstructionObligationLedgerTool } from "./registerApplicationTools/obligationLedger.js";
+import { registerReconstructionReadinessTool } from "./registerApplicationTools/readiness.js";
 /** Register provider-neutral JavaScript application graph workflows. */
 export const registerApplicationTools = (server, options) => {
     registerTraceFeatureTool(server, options);
     registerTraceJavaScriptSemanticsTool(server, options);
     registerCompareApplicationVersionsTool(server, options);
+    registerCompareSourceToBundleTool(server, options);
     registerCompareJavaScriptExportShapesTool(server, options);
     registerControlledReplayTool(server, options);
     registerCharacterizationTools(server, options);
+    registerReconstructionObligationLedgerTool(server, options);
+    registerReconstructionReadinessTool(server, options);
     registerCoverageTools(server, options);
 };

package/dist/server/registerArtifactTools.js

@@ -1,6 +1,14 @@
 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, options);
+    registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, {
+        ...options,
+        sourceEvidence: (operation, result) => operation === "inspect_artifact"
+            ? artifactInspectionResultSchema
+                .parse(result)
+                .substeps.map(({ evidence }) => evidence)
+            : [],
+    });
 };

package/dist/server/registerBrowserScenarioTool.js

@@ -0,0 +1,25 @@
+import { captureBrowserScenario } from "../application/BrowserScenarioCaptureService.js";
+import { BROWSER_SCENARIO_TOOL_CONTRACTS } from "../contracts/browserScenarioToolContracts.js";
+import { browserScenarioSchema } from "../domain/browserScenario.js";
+import { logToolExecution } from "./toolLogging.js";
+import { safeParseToolInput } from "./toolInputValidation.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { toCallToolResult } from "./toolResult.js";
+/** Register the controlled browser scenario tool even when policy disables it. */
+export const registerBrowserScenarioTool = (server, options) => {
+    const [contract] = BROWSER_SCENARIO_TOOL_CONTRACTS;
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
+        const parsed = safeParseToolInput(browserScenarioSchema, input, contract.name);
+        if (!parsed.ok)
+            return toCallToolResult(parsed, contract);
+        const result = await logToolExecution(options.logger, contract.name, () => captureBrowserScenario(options.provider, options.permissionAuthority, parsed.value, { signal: context.mcpReq.signal }));
+        if (!result.ok)
+            return toCallToolResult(result, contract);
+        const recorded = options.recordEvidence?.(result.value);
+        return recorded !== undefined && !recorded.ok
+            ? toCallToolResult(recorded, contract)
+            : toCallToolResult({ ok: true, value: result.value }, contract, {
+                evidenceResourcesAvailable: recorded !== undefined,
+            });
+    });
+};

package/dist/server/registerBrowserTools.js

@@ -4,7 +4,7 @@ import { inspectWebPageInputSchema, listBrowserTargetsInputSchema, } from "../do
 import { analyzeWebBundleInputSchema } from "../domain/webBundleAnalysis.js";
 import { observeWebSessionInputSchema } from "../domain/browserSession.js";
 import { discoverWebMcpToolsInputSchema } from "../domain/webMcpDiscovery.js";
-import { compareWebCapturesInputSchema } from "../domain/webCaptureDiff.js";
+import { browserCaptureComparisonInputSchema } from "../domain/browserCaptureComparison.js";
 import { captureWebScreenshotInputSchema, compareWebScreenshotsInputSchema, } from "../domain/webScreenshot.js";
 import { logToolExecution } from "./toolLogging.js";
 import { toCallToolResult } from "./toolResult.js";
@@ -55,7 +55,7 @@ export const registerBrowserTools = (server, options) => {
     });
     registerBrowserTool(server, options, {
         contract: captureDiffContract,
-        schema: compareWebCapturesInputSchema,
+        schema: browserCaptureComparisonInputSchema,
         execute: (parsed, _context) => compareWebCaptureEvidence(options.browser, parsed),
     });
     registerBrowserTool(server, options, {

package/dist/server/registerCloseLifecycleTool.js

@@ -0,0 +1,57 @@
+import { writeAnalysisSnapshot } from "../application/AnalysisSnapshotFiles.js";
+import { closeBinaryInputSchema } from "../contracts/sessionLifecycleInputs.js";
+import { ok } from "../domain/result.js";
+import { reportLifecycleEnd, reportLifecycleStart, } from "./lifecycleProgress.js";
+import { logToolExecution } from "./toolLogging.js";
+import { toCallToolResult } from "./toolResult.js";
+import { mcpProgressReporter } from "./mcpProgress.js";
+import { permissionFailure } from "./permissionFailure.js";
+import { safeParseToolInput } from "./toolInputValidation.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Register provider cleanup and optional pre-close snapshot persistence. */
+export const registerCloseLifecycleTool = ({ server, session, logger, contracts: [, closeContract], snapshotFilePolicy, permissionAuthority, }) => {
+    server.registerTool(closeContract.name, toolRegistrationOptions(closeContract), async (input, context) => {
+        const parsedInput = safeParseToolInput(closeBinaryInputSchema, input, closeContract.name);
+        if (!parsedInput.ok)
+            return toCallToolResult(parsedInput, closeContract);
+        const parsed = parsedInput.value;
+        const progress = mcpProgressReporter(context);
+        if (parsed.snapshot_path === undefined) {
+            await reportLifecycleStart(progress, closeContract.name);
+            const closed = await logToolExecution(logger, closeContract.name, () => session.close({ progress }));
+            await reportLifecycleEnd(progress, closeContract.name, closed.ok);
+            server.sendToolListChanged();
+            return toCallToolResult(closed, closeContract);
+        }
+        if (permissionAuthority !== undefined) {
+            const authorized = await permissionAuthority.authorize({
+                capability: "snapshot_write",
+                roots: [parsed.snapshot_path],
+                executables: [],
+                environment_names: [],
+                network: "none",
+                mount: false,
+                operation_identity: `close_binary:snapshot:${parsed.snapshot_path}`,
+            }, "write");
+            if (!authorized.ok)
+                return toCallToolResult(permissionFailure(authorized), closeContract);
+        }
+        const snapshot = session.exportAnalysisSnapshot();
+        if (!snapshot.ok)
+            return toCallToolResult(snapshot, closeContract);
+        const written = await writeAnalysisSnapshot(snapshot.value, parsed.snapshot_path, parsed.overwrite, snapshotFilePolicy);
+        if (!written.ok)
+            return toCallToolResult(written, closeContract);
+        await reportLifecycleStart(progress, closeContract.name, "snapshot written; closing provider");
+        const closed = await logToolExecution(logger, closeContract.name, () => session.close({ progress }));
+        await reportLifecycleEnd(progress, closeContract.name, closed.ok);
+        server.sendToolListChanged();
+        return closed.ok
+            ? toCallToolResult(ok({
+                path: written.value.path,
+                bytes: written.value.bytes,
+                entries: snapshot.value.entries.length,
+            }), closeContract)
+            : toCallToolResult(closed, closeContract);
+    });
+};