rea-agents 4.0.1 → 5.0.0

package/dist/process/ProcessOwnershipObservation.js

@@ -1,5 +1,7 @@
+import { readFile } from "node:fs/promises";
 import { launcherIdentityFailure } from "./ProcessOwnershipIdentity.js";
 import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
+import { execFileOutput } from "./ExecFileOutput.js";
 /** Observe one group without signaling it, failing closed on identity doubt. */
 export const observeOwnedProcessGroupWithHost = async (ownership, host) => {
     let members;
@@ -95,12 +97,70 @@ const unavailableLineage = (ownership, reason) => ({
     processGroupId: ownership.processGroupId,
     reason,
 });
+/** Parse the NUL-delimited Linux process environment without nameless keys. */
+export const parseProcessEnvironment = (value) => Object.fromEntries(value
+    .split("\0")
+    .filter((entry) => entry.indexOf("=") > 0)
+    .map((entry) => {
+    const separator = entry.indexOf("=");
+    return [entry.slice(0, separator), entry.slice(separator + 1)];
+}));
+/** Create the operating-system process inspector for an explicit host context. */
+export const createSystemProcessOwnershipHost = (platform = process.platform, hostEnvironment = process.env) => ({
+    platform,
+    async listProcesses() {
+        if (platform === "win32")
+            return [];
+        const { stdout } = await execFileOutput("ps", ["-axo", "pid=,ppid=,pgid=,stat=,command="], { env: hostEnvironment });
+        return stdout
+            .split("\n")
+            .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)/u.exec(line))
+            .filter((match) => match !== null)
+            .map((match) => ({
+            pid: Number(match[1]),
+            parentPid: Number(match[2]),
+            processGroupId: Number(match[3]),
+            state: match[4] ?? "",
+            command: match[5] ?? "",
+        }));
+    },
+    async environment(pid) {
+        if (platform === "linux")
+            return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, "utf8"));
+        const { stdout } = await execFileOutput("ps", ["eww", "-p", String(pid)], {
+            env: hostEnvironment,
+        });
+        const observedEnvironment = {};
+        for (const match of stdout.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s]*)/gu)) {
+            const name = match[1];
+            if (name !== undefined)
+                observedEnvironment[name] = match[2] ?? "";
+        }
+        return observedEnvironment;
+    },
+    signalGroup(processGroupId, signal) {
+        process.kill(-processGroupId, signal);
+    },
+});
+const systemHost = createSystemProcessOwnershipHost();
+/** Observe one group without signaling it, failing closed on identity doubt. */
+export const observeOwnedProcessGroup = async (ownership, host = systemHost) => observeOwnedProcessGroupWithHost(ownership, host);
+/**
+ * Record the live launcher and descendant lineage after run-token validation.
+ *
+ * The observation is intentionally point-in-time. A verified empty descendant
+ * list means no descendants were live during this observation, not that the
+ * run never created a short-lived child.
+ */
+export const observeOwnedProcessLineage = async (ownership, host = systemHost) => observeOwnedProcessLineageWithHost(ownership, host);
 const processIsGone = async (host, pid) => {
     try {
         return !liveProcesses(await host.listProcesses()).some((process) => process.pid === pid);
     }
-    catch {
+    catch (cause) {
+        // best-effort cleanup: optional liveness probing; failure means not gone.
+        void cause;
         return false;
     }
 };
-const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+export const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/process/ProcessOwnershipProcessTree.js

@@ -20,3 +20,16 @@ export const descendantsOf = (launcherPid, processes) => {
     }
     return descendants;
 };
+/** Select the PTY root group and groups led by an observed captured process. */
+export const selectCapturedProcessGroupIds = (rootPid, samples) => {
+    const processGroupIds = new Set([rootPid]);
+    for (const sample of samples) {
+        // A sampled member may transiently inherit an unrelated group. POSIX group
+        // leaders have pid === pgid, so only that observation establishes that the
+        // group leader itself belonged to the captured tree. Token checks below
+        // remain the final authority immediately before observation or signaling.
+        if (sample.pid === sample.process_group_id)
+            processGroupIds.add(sample.pid);
+    }
+    return [...processGroupIds];
+};

package/dist/process/ProviderProcess.js

@@ -1,8 +1,9 @@
 import { spawn } from "node:child_process";
+import { WindowsOwnedProcess } from "../windows/WindowsOwnedProcess.js";
 const DEFAULT_TERMINATION_GRACE_MS = 250;
 const DEFAULT_KILL_GRACE_MS = 1_000;
 /**
- * Spawn a provider in a dedicated POSIX process group with an ownership token.
+ * Spawn a provider in an owned Windows job or dedicated POSIX process group.
  *
  * The caller remains responsible for persisting any ownership manifest and for
  * selecting provider-specific command arguments or environment values.
@@ -10,17 +11,33 @@ const DEFAULT_KILL_GRACE_MS = 1_000;
 export const spawnOwnedProviderProcess = async (options) => {
     const platform = options.platform ?? process.platform;
     const hostEnvironment = options.hostEnvironment ?? process.env;
+    const environment = {
+        ...hostEnvironment,
+        ...options.env,
+        REA_PROCESS_RUN_ID: options.runId,
+    };
+    if (platform === "win32" && process.platform === "win32") {
+        if (options.stdin === "pipe")
+            throw new Error("Owned Windows provider processes do not support protocol stdin");
+        const child = new WindowsOwnedProcess(options.command, options.arguments, options.cwd, environment, options.windowsVerbatimArguments ?? false);
+        return {
+            process: child,
+            ownership: {
+                runId: options.runId,
+                leaderPid: child.pid,
+                processGroupId: child.pid,
+                expectedParentPid: process.pid,
+            },
+            cleanup: () => child.cleanup(),
+        };
+    }
     const child = spawn(options.command, [...options.arguments], {
         shell: false,
         windowsHide: true,
-        stdio: ["ignore", "pipe", "pipe"],
+        stdio: [options.stdin ?? "ignore", "pipe", "pipe"],
         detached: platform !== "win32",
         windowsVerbatimArguments: options.windowsVerbatimArguments ?? false,
-        env: {
-            ...hostEnvironment,
-            ...options.env,
-            REA_PROCESS_RUN_ID: options.runId,
-        },
+        env: environment,
         ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
     });
     await waitForSpawn(child);
@@ -41,7 +58,7 @@ export const spawnOwnedProviderProcess = async (options) => {
 /**
  * Supervises only generic process resources; wire protocol remains adapter-owned.
  *
- * Output retention is bounded per stream while byte totals remain exact. Stop
+ * Output retention is complete per stream; adapters own resource budgets. Stop
  * first honors token-verified group cleanup when supplied, otherwise it uses a
  * bounded TERM-to-KILL escalation for a directly owned child.
  */
@@ -51,6 +68,8 @@ export class ProviderProcessSupervisor {
     #stdout = new ProcessOutputCapture();
     #stderr = new ProcessOutputCapture();
     #exit = deferred();
+    #outputClose = deferred();
+    #outputClosed = false;
     #onStdout = (chunk) => {
         this.#capture("stdout", this.#stdout, chunk);
     };
@@ -62,6 +81,8 @@ export class ProviderProcessSupervisor {
     };
     #onClose = (code, signal) => {
         this.#recordExit(code, signal);
+        this.#outputClosed = true;
+        this.#outputClose.resolve(undefined);
     };
     #onError = (cause) => {
         this.#options.onDiagnostic?.({ type: "error", message: cause.message });
@@ -72,7 +93,8 @@ export class ProviderProcessSupervisor {
     constructor(launch, options = {}) {
         this.launch = launch;
         this.#options = options;
-        this.#attach(launch.process.stdout, "stdout");
+        if (options.captureStdout !== false)
+            this.#attach(launch.process.stdout, "stdout");
         this.#attach(launch.process.stderr, "stderr");
         launch.process.once("exit", this.#onExit);
         launch.process.once("close", this.#onClose);
@@ -89,23 +111,18 @@ export class ProviderProcessSupervisor {
             signal: this.#exitObservation?.signal,
         };
     }
+    /** Begin a new observation on a retained process without retaining earlier output. */
+    resetOutput() {
+        this.#stdout.reset();
+        this.#stderr.reset();
+    }
     /** Wait for process exit up to a caller-owned bounded interval. */
     async waitForExit(timeoutMs) {
-        if (this.#exitObservation !== undefined)
-            return true;
-        let timer;
-        try {
-            return await Promise.race([
-                this.#exit.promise.then(() => true),
-                new Promise((resolve) => {
-                    timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
-                }),
-            ]);
-        }
-        finally {
-            if (timer !== undefined)
-                clearTimeout(timer);
-        }
+        return waitForProcessEvent(this.#exitObservation !== undefined, this.#exit.promise, timeoutMs);
+    }
+    /** Wait until the producer has closed its output streams; exit alone does not prove complete output. */
+    async waitForOutputClose(timeoutMs) {
+        return waitForProcessEvent(this.#outputClosed, this.#outputClose.promise, timeoutMs);
     }
     /** Stop an owned process once; concurrent callers share the same escalation. */
     stop(options = {}) {
@@ -220,6 +237,10 @@ class ProcessOutputCapture {
     get bytes() {
         return this.#bytes;
     }
+    reset() {
+        this.#chunks.length = 0;
+        this.#bytes = 0;
+    }
     append(chunk) {
         this.#bytes += chunk.byteLength;
         this.#chunks.push(Buffer.from(chunk));
@@ -256,3 +277,20 @@ const waitForSpawn = (child) => new Promise((resolve, reject) => {
     child.once("spawn", onSpawn);
     child.once("error", onError);
 });
+const waitForProcessEvent = async (observed, event, timeoutMs) => {
+    if (observed)
+        return true;
+    let timer;
+    try {
+        return await Promise.race([
+            event.then(() => true),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+};

package/dist/process/ProviderRunLineage.js

@@ -1,4 +1,4 @@
-import { observeOwnedProcessLineage } from "./ProcessOwnership.js";
+import { observeOwnedProcessLineage } from "./ProcessOwnershipObservation.js";
 /** Retain the latest truthful process-lineage observation for one client. */
 export class ProviderRunLineage {
     #observation = null;

package/dist/process/WindowsAuthority.js

@@ -1,5 +1,6 @@
+import { systemWindowsNativeAuthority } from "../windows/WindowsNativeLoader.js";
 /** Stable explanation used whenever the native Windows authority is absent. */
-export const WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON = "Verified Windows native authority is unavailable: Job Object process ownership, private runtime DACL enforcement, and reparse-safe path admission are not implemented; chmod(0700) is insufficient for Windows private DACL proof, and taskkill is not a Job Object security proof";
+export const WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON = "Windows native controls are unavailable in this runtime; use the Windows x64 REA package with its matching bundled native artifact.";
 /**
  * Describe native Windows controls without inferring them from taskkill,
  * chmod, symlink creation, or a numeric POSIX open flag.
@@ -17,6 +18,21 @@ export const windowsNativeCapabilities = (platform) => {
             reparse_safe_path_admission: notApplicable,
         };
     }
+    if (process.platform === "win32") {
+        const loaded = systemWindowsNativeAuthority();
+        const capability = loaded.available
+            ? { available: true, reason: null, proof: "native-authority" }
+            : {
+                available: false,
+                reason: loaded.reason,
+                proof: "not-proven",
+            };
+        return {
+            job_object_process_ownership: capability,
+            private_runtime_dacl: capability,
+            reparse_safe_path_admission: capability,
+        };
+    }
     const notProven = {
         available: false,
         reason: WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON,
@@ -30,3 +46,6 @@ export const windowsNativeCapabilities = (platform) => {
 };
 /** Whether every native control needed for Windows isolation is proven. */
 export const hasWindowsNativeAuthority = (platform) => Object.values(windowsNativeCapabilities(platform)).every(({ available }) => available);
+/** Preserve the actual loader or operating-system constraint in provider errors. */
+export const windowsNativeAuthorityUnavailableReason = (platform) => windowsNativeCapabilities(platform).job_object_process_ownership.reason ??
+    WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON;

package/dist/reference/ReferenceSourceReaderEntries.js

@@ -31,6 +31,12 @@ export const traverseDirectory = async (state, current) => {
         state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", "changed", "Directory changed while it was read"));
         return { ok: true, value: undefined };
     }
+    if (current.path !== state.root)
+        state.entries.push({
+            status: "read",
+            kind: "directory",
+            path: pathFromRoot(state.root, current.path),
+        });
     const directories = [];
     for (const name of names.value) {
         const result = await processEntry(state, current, name, directories);
@@ -102,7 +108,6 @@ const processEntry = async (state, current, name, directories) => {
     if (metadata.value.isSymbolicLink())
         state.entries.push(await describeSymlink(state.root, absolute, path, state.signal));
     else if (metadata.value.isDirectory()) {
-        state.entries.push({ status: "read", kind: "directory", path });
         directories.push({ path: absolute });
     }
     else if (!metadata.value.isFile())
@@ -189,7 +194,11 @@ const applyExclusion = (shouldExclude, path) => {
     try {
         return { ok: true, value: shouldExclude?.(path) === true };
     }
-    catch {
+    catch (cause) {
+        // Exclusion predicates are caller-supplied; a throwing predicate fails
+        // closed and the caller-visible `{ ok: false }` preserves the rejection
+        // without propagating an arbitrary predicate cause.
+        void cause;
         return { ok: false };
     }
 };

package/dist/reference/ReferenceSourceReaderFile.js

@@ -102,6 +102,7 @@ export const readStableFile = async (request) => {
         return entryFailure(path, "file", "io", message, safeSize(expected.size));
     }
     finally {
+        // best-effort cleanup: file-handle close must not mask the read result.
         await handle?.close().catch(() => undefined);
     }
 };

package/dist/server/createServer.js

@@ -1,14 +1,31 @@
 import { McpServer } from "@modelcontextprotocol/server";
+import { isAbsolute } from "node:path";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { silentLogger } from "../logger.js";
 import { registerApplicationTools } from "./registerApplicationTools.js";
 import { registerArtifactTools } from "./registerArtifactTools.js";
 import { registerBrowserScenarioTool } from "./registerBrowserScenarioTool.js";
 import { registerBrowserTools } from "./registerBrowserTools.js";
+import { registerWebScriptTool } from "./registerWebScriptTool.js";
+import { registerWebModuleTool } from "./registerWebModuleTool.js";
+import { createWebModuleTraceService } from "../composition/webModules.js";
+import { createWebSourceLocationService } from "../composition/webSourceLocations.js";
+import { registerWebSourceLocationTool } from "./registerWebSourceLocationTool.js";
+import { createWebRuntimeService } from "../composition/webRuntime.js";
+import { registerWebRuntimeTools } from "./registerWebRuntimeTools.js";
+import { registerJavaScriptRecoveryTool } from "./registerJavaScriptRecoveryTool.js";
+import { JavaScriptRecoveryService } from "../application/javascript/JavaScriptRecoveryService.js";
+import { createJavaScriptRecoveryProvider } from "../composition/javascriptRecovery.js";
 import { registerElectronTools } from "./registerElectronTools.js";
 import { registerEnhancedTools } from "./registerEnhancedTools.js";
 import { registerJavaScriptRuntimeObservationTools } from "./registerJavaScriptRuntimeObservationTools.js";
 import { registerManagedTools } from "./registerManagedTools.js";
+import { registerFirmwareTools } from "./registerFirmwareTools.js";
+import { FirmwareAnalysisService } from "../application/firmware/FirmwareAnalysisService.js";
+import { createFirmwareAnalysisProvider } from "../composition/firmware.js";
+import { registerAndroidTools } from "./registerAndroidTools.js";
+import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js";
+import { createAndroidAnalysisProvider } from "../composition/android.js";
 import { registerManagedWorkflowTools } from "./registerManagedWorkflowTools.js";
 import { registerNativeTools } from "./registerNativeTools.js";
 import { registerOfficialTools } from "./registerOfficialTools.js";
@@ -21,8 +38,24 @@ const installSessionToolAvailability = (server, session, options) => {
     if (session === undefined)
         return undefined;
     const policy = sessionAvailabilityPolicy(options.availabilityPolicy, {
+        optionalProviderLoadFailures: options.optionalProviderLoadFailures,
         optionalFeatures: {
+            webModuleResolutionEnabled: options.webModuleTrace !== undefined ||
+                isAbsolute(process.env.REA_BROWSER_EXECUTABLE ?? ""),
+            firmwareInspectionEnabled: options.firmwareAnalysis !== undefined ||
+                (process.platform === "linux" &&
+                    isAbsolute(process.env.REA_BINWALK_COMMAND ?? "")),
+            firmwareExtractionEnabled: options.firmwareAnalysis !== undefined ||
+                (process.platform === "linux" &&
+                    isAbsolute(process.env.REA_UNBLOB_COMMAND ?? "")),
+            androidAnalysisEnabled: options.androidAnalysis !== undefined ||
+                ((process.platform === "linux" || process.platform === "darwin") &&
+                    isAbsolute(process.env.REA_JADX_MCP_JAR ?? "")),
             browserObservationEnabled: options.browserObservation !== undefined,
+            javascriptRecoveryEnabled: options.javascriptRecovery !== undefined ||
+                (process.platform === "linux" &&
+                    process.arch === "x64" &&
+                    isAbsolute(process.env.REA_WAKARU_COMMAND ?? "")),
             browserScenarioEnabled: options.browserScenarioCapture !== undefined,
             electronObservationEnabled: options.electronObservation !== undefined,
             electronAutomationEnabled: options.electronActiveObservation !== undefined,
@@ -53,19 +86,41 @@ export const createServer = (analysis, session, options = {}) => {
     const server = createMcpServer(session);
     const availability = installSessionToolAvailability(server, session, options);
     const toolLogger = logger.child({ layer: "server" });
-    const { activeTarget, recordEvidence, recordEvidenceWithUnknown } = createSessionRecorders(server, session);
+    const { evidenceById, activeTarget, recordEvidence, recordEvidenceWithUnknown, } = createSessionRecorders(server, session);
     const toolContext = {
         server,
         analysis,
         session,
         options,
         logger: toolLogger,
+        evidenceById,
         activeTarget,
         recordEvidence,
         recordEvidenceWithUnknown,
     };
     registerBinaryAnalysisTools(toolContext);
+    const android = options.androidAnalysis ?? createAndroidAnalysisProvider();
+    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");
+        });
+    };
+    const closeServer = server.close.bind(server);
+    server.close = async () => {
+        const results = await Promise.allSettled([closeServer(), android.close()]);
+        for (const result of results)
+            if (result.status === "rejected")
+                throw result.reason;
+    };
+    registerAndroidTools(server, new AndroidAnalysisService(android), toolLogger, recordEvidence);
+    registerFirmwareTools(server, new FirmwareAnalysisService(options.firmwareAnalysis ?? createFirmwareAnalysisProvider()), toolLogger, recordEvidence);
     registerObservationTools(toolContext);
+    registerWebModuleTool(server, options.webModuleTrace ?? createWebModuleTraceService(), toolLogger, recordEvidence);
+    registerWebSourceLocationTool(server, options.webSourceLocation ?? createWebSourceLocationService(), toolLogger, recordEvidence);
+    registerWebRuntimeTools(server, options.webRuntime ?? createWebRuntimeService(), toolLogger, recordEvidence);
+    registerJavaScriptRecoveryTool(server, new JavaScriptRecoveryService(options.javascriptRecovery ?? createJavaScriptRecoveryProvider()), toolLogger, recordEvidence);
     registerGuidedPrompts(server, analysis, session);
     if (session !== undefined) {
         registerSessionTools(server, session, toolLogger, {
@@ -79,6 +134,9 @@ export const createServer = (analysis, session, options = {}) => {
     return server;
 };
 const createSessionRecorders = (server, session) => ({
+    evidenceById: session === undefined
+        ? undefined
+        : (evidenceId) => session.evidenceById(evidenceId),
     activeTarget: session === undefined ? undefined : () => session.activeTarget(),
     recordEvidence: session === undefined
         ? undefined
@@ -125,26 +183,33 @@ const registerBinaryAnalysisTools = ({ server, analysis, session, logger, active
             session,
         });
 };
-const registerObservationTools = ({ server, options, logger, recordEvidence, recordEvidenceWithUnknown, }) => {
+const registerObservationTools = ({ evidenceById, server, options, logger, recordEvidence, recordEvidenceWithUnknown, }) => {
     const common = { logger, recordEvidence };
+    registerWebScriptTool(server, common);
     registerBrowserTools(server, {
         ...common,
         browser: options.browserObservation,
+        loadFailure: options.optionalProviderLoadFailures?.browserObservation,
     });
     registerBrowserScenarioTool(server, {
         ...common,
         provider: options.browserScenarioCapture,
+        loadFailure: options.optionalProviderLoadFailures?.browserScenarioCapture,
     });
     registerElectronTools(server, {
         ...common,
         electron: options.electronObservation,
         electronActive: options.electronActiveObservation,
+        observationLoadFailure: options.optionalProviderLoadFailures?.electronObservation,
+        activeLoadFailure: options.optionalProviderLoadFailures?.electronActiveObservation,
     });
     registerJavaScriptRuntimeObservationTools(server, {
         ...common,
         runtime: options.javascriptRuntimeObservation,
+        loadFailure: options.optionalProviderLoadFailures?.javascriptRuntimeObservation,
     });
     registerApplicationTools(server, {
+        evidenceById,
         logger,
         recordEvidence,
         recordEvidenceWithUnknown,

package/dist/server/mcpClientMetadata.js

@@ -21,10 +21,13 @@ const capabilityFeatures = (value) => {
     const capabilities = isRecord(value) ? value : {};
     const elicitation = isRecord(capabilities.elicitation)
         ? capabilities.elicitation
-        : {};
+        : undefined;
     return {
-        elicitation_form: elicitation.form !== undefined,
-        elicitation_url: elicitation.url !== undefined,
+        // A declared capability without modes retains the protocol's form-only
+        // compatibility rule; a missing capability still grants no support.
+        elicitation_form: elicitation !== undefined &&
+            (elicitation.form !== undefined || elicitation.url === undefined),
+        elicitation_url: elicitation?.url !== undefined,
         roots: capabilities.roots !== undefined,
         sampling: capabilities.sampling !== undefined,
     };

package/dist/server/mcpProgress.js

@@ -16,8 +16,9 @@ export const mcpProgressReporter = (context) => {
                 },
             });
         }
-        catch {
+        catch (cause) {
             // Progress is observational; transport failure cannot change tool truth.
+            void cause;
         }
     }, { minimumIntervalMs: 100 });
 };

package/dist/server/promptCompletion.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { uniqueSorted } from "../domain/canonicalOrdering.js";
 import { artifactInventoryResultSchema } from "../domain/artifactGraph.js";
 import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
 import { processCaptureSchema } from "../domain/processCapture.js";
@@ -14,7 +15,8 @@ export const createPromptCompletionSource = (analysis, session) => ({
     async complete(kind, value, context) {
         const candidates = await completionCandidates(kind, analysis, session, context);
         const prefix = normalize(value);
-        return uniqueSorted(candidates).filter((candidate) => normalize(candidate).startsWith(prefix));
+        const nonEmpty = candidates.filter((candidate) => candidate.length > 0);
+        return uniqueSorted(nonEmpty).filter((candidate) => normalize(candidate).startsWith(prefix));
     },
 });
 const completionCandidates = async (kind, analysis, session, context) => {
@@ -121,6 +123,4 @@ const unknownCandidates = (session) => session === undefined
         .listUnknowns()
         .filter(({ status }) => status !== "resolved")
         .map(({ unknown_id: id }) => id);
-const uniqueSorted = (values) => [...new Set(values.filter((value) => value.length > 0))].sort(compareText);
-const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 const normalize = (value) => value.normalize("NFKC").toLowerCase();

package/dist/server/registerAndroidTools.js

@@ -0,0 +1,30 @@
+import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js";
+import { toolContract } from "../contracts/toolContracts.js";
+import { logToolExecution } from "./toolLogging.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { toCallToolResult } from "./toolResult.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 toCallToolResult(result, contract);
+            const recorded = recordEvidence?.(result.value);
+            return recorded !== undefined && !recorded.ok
+                ? toCallToolResult(recorded, contract)
+                : toCallToolResult(result, contract);
+        };
+    };
+    const packageContract = toolContract("inspect_android_package");
+    server.registerTool(packageContract.name, toolRegistrationOptions(packageContract), handler(packageContract));
+    const searchContract = toolContract("search_android_classes");
+    server.registerTool(searchContract.name, toolRegistrationOptions(searchContract), handler(searchContract));
+    const classContract = toolContract("inspect_android_class");
+    server.registerTool(classContract.name, toolRegistrationOptions(classContract), handler(classContract));
+    const methodContract = toolContract("inspect_android_method");
+    server.registerTool(methodContract.name, toolRegistrationOptions(methodContract), handler(methodContract));
+    const referencesContract = toolContract("trace_android_references");
+    server.registerTool(referencesContract.name, toolRegistrationOptions(referencesContract), handler(referencesContract));
+};

package/dist/server/registerApplicationTools/compareExportShapes.js

@@ -1,7 +1,8 @@
+import { resolvePairedEvidenceRequest } from "../../application/EvidenceInputResolver.js";
 import { recordSessionEvidenceSources } from "../sessionEvidence.js";
-import { compareJavaScriptExportShapesEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
+import { compareJavaScriptExportShapesEvidenceValidated } from "../../application/javascript/JavaScriptApplicationWorkflowService.js";
 import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
-import { javaScriptExportShapeComparisonResultSchema } from "../../domain/javascriptExportShapeComparisonSchemas.js";
+import { javaScriptExportShapeComparisonResultSchema } from "../../domain/javascript/javascriptExportShapeComparisonSchemas.js";
 import { logToolExecution } from "../toolLogging.js";
 import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
 import { toCallToolResult } from "../toolResult.js";
@@ -10,7 +11,10 @@ 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) => {
-        const parsed = input;
+        const resolved = resolvePairedEvidenceRequest(input, options.evidenceById);
+        if (!resolved.ok)
+            return toCallToolResult(resolved, contract);
+        const parsed = resolved.value;
         const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(compareJavaScriptExportShapesEvidenceValidated(parsed)));
         if (!result.ok)
             return toCallToolResult(result, contract);

package/dist/server/registerApplicationTools/compareSourceToBundle.js

@@ -1,7 +1,8 @@
+import { resolveApplicationEvidenceRequest } from "../../application/EvidenceInputResolver.js";
 import { recordSessionEvidenceSources } from "../sessionEvidence.js";
-import { compareSourceToBundleEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
+import { compareSourceToBundleEvidenceValidated } from "../../application/javascript/JavaScriptApplicationWorkflowService.js";
 import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
-import { sourceToBundleComparisonResultSchema } from "../../domain/sourceToBundleComparisonSchemas.js";
+import { sourceToBundleComparisonResultSchema } from "../../domain/javascript/sourceToBundleComparisonSchemas.js";
 import { logToolExecution } from "../toolLogging.js";
 import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
 import { toCallToolResult } from "../toolResult.js";
@@ -10,11 +11,15 @@ 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 result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(compareSourceToBundleEvidenceValidated(input)));
+        const resolved = resolveApplicationEvidenceRequest(input, options.evidenceById);
+        if (!resolved.ok)
+            return toCallToolResult(resolved, contract);
+        const parsed = resolved.value;
+        const result = await logToolExecution(options.logger, contract.name, () => Promise.resolve(compareSourceToBundleEvidenceValidated(parsed)));
         if (!result.ok)
             return toCallToolResult(result, contract);
         const recorded = recordSessionEvidenceSources(options.recordEvidence, [
-            input.application,
+            parsed.application,
         ]);
         if (!recorded.ok)
             return toCallToolResult(recorded, contract);

package/dist/server/registerApplicationTools/compareVersions.js

@@ -1,7 +1,8 @@
+import { resolvePairedEvidenceRequest } from "../../application/EvidenceInputResolver.js";
 import { recordSessionEvidenceSources } from "../sessionEvidence.js";
-import { compareApplicationVersionsEvidenceValidated } from "../../application/JavaScriptApplicationWorkflowService.js";
+import { compareApplicationVersionsEvidenceValidated } from "../../application/javascript/JavaScriptApplicationWorkflowService.js";
 import { applicationToolContract } from "../../contracts/applicationToolContracts.js";
-import { applicationVersionComparisonResultSchema } from "../../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { applicationVersionComparisonResultSchema } from "../../domain/javascript/javascriptApplicationVersionComparisonSchemas.js";
 import { logToolExecution } from "../toolLogging.js";
 import { toolRegistrationOptions } from "../toolRegistrationOptions.js";
 import { toCallToolResult } from "../toolResult.js";
@@ -10,7 +11,10 @@ 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) => {
-        const parsed = input;
+        const resolved = resolvePairedEvidenceRequest(input, options.evidenceById);
+        if (!resolved.ok)
+            return toCallToolResult(resolved, compareContract);
+        const parsed = resolved.value;
         const result = await logToolExecution(options.logger, compareContract.name, () => Promise.resolve(compareApplicationVersionsEvidenceValidated(parsed)));
         if (!result.ok)
             return toCallToolResult(result, compareContract);