rea-agents 6.0.0 → 6.2.0

package/dist/hopper/HopperRegexSearch.js

@@ -0,0 +1,134 @@
+import { Worker } from "node:worker_threads";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisOutputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { analysisStringSchema } from "../domain/hopperValues.js";
+import { HopperRemoteError } from "../domain/hopperErrors.js";
+import { err, ok } from "../domain/result.js";
+import { analysisSearchInput } from "../contracts/analysisSearchContract.js";
+const MATCHING_DEADLINE_MS = 5_000;
+const inputSchema = z.strictObject({
+    ...analysisSearchInput,
+    mode: z.literal("regex"),
+});
+const replySchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.literal("matched"),
+        indices: z.array(z.number().int().nonnegative()),
+    }),
+    z.strictObject({ status: z.literal("invalid_pattern"), reason: z.string() }),
+]);
+/** Match collected native facts off Hopper's API thread, with cancellable lifetime. */
+export class HopperRegexSearch {
+    client;
+    #active = new Map();
+    constructor(client) {
+        this.client = client;
+    }
+    execute(operation, parameters, options) {
+        const controller = new AbortController();
+        const signal = options?.signal === undefined
+            ? controller.signal
+            : AbortSignal.any([controller.signal, options.signal]);
+        const pending = this.#execute(operation, parameters, {
+            ...options,
+            signal,
+        });
+        this.#active.set(controller, pending);
+        void pending.then(() => this.#active.delete(controller), () => this.#active.delete(controller));
+        return pending;
+    }
+    /** Abort matching workers before their provider session closes. */
+    async close() {
+        for (const controller of this.#active.keys())
+            controller.abort();
+        await Promise.all(this.#active.values());
+    }
+    async #execute(operation, parameters, options) {
+        const input = inputSchema.safeParse(parameters);
+        if (!input.success)
+            return err(new HopperRemoteError(-32000, `Invalid search arguments: ${input.error.message}`, { diagnosticType: "invalid_request", operation }));
+        const inventoryOptions = {
+            ...options,
+            ...(options.progress === undefined
+                ? {}
+                : {
+                    progress: {
+                        report: (update) => options.progress?.report({
+                            ...update,
+                            completed: update.total === null || update.total === 0
+                                ? 0
+                                : Math.min(0.5, update.completed / update.total / 2),
+                            total: 1,
+                        }) ?? Promise.resolve(),
+                    },
+                }),
+        };
+        const inventory = await this.client.callTool(operation === "search_strings" ? "list_strings" : "list_procedures", input.data.document === undefined
+            ? {}
+            : { document: input.data.document }, inventoryOptions);
+        if (!inventory.ok)
+            return inventory;
+        const parsed = z.array(analysisStringSchema).safeParse(inventory.value);
+        if (!parsed.success)
+            return err(new AnalysisOutputError(operation, "Hopper search inventory is malformed"));
+        if (options.signal?.aborted)
+            return err(new AnalysisCancelledError(operation));
+        await options.progress
+            ?.report({
+            phase: "hopper_regex",
+            completed: 0.5,
+            total: 1,
+            message: "Matching inventory in cancellable regex worker",
+        })
+            .catch(() => undefined);
+        if (options.signal?.aborted)
+            return err(new AnalysisCancelledError(operation));
+        let worker;
+        try {
+            worker = new Worker(new URL("./HopperRegexWorker.js", import.meta.url), {
+                workerData: {
+                    pattern: input.data.pattern,
+                    caseSensitive: input.data.case_sensitive,
+                    values: parsed.data.map((item) => item.value),
+                },
+            });
+        }
+        catch (cause) {
+            return err(new AnalysisOutputError(operation, `Cannot start regex worker: ${cause instanceof Error ? cause.message : String(cause)}`, { cause }));
+        }
+        try {
+            return await new Promise((resolve) => {
+                const finish = (result) => {
+                    clearTimeout(timer);
+                    options.signal?.removeEventListener("abort", onAbort);
+                    resolve(result);
+                };
+                const onAbort = () => finish(err(new AnalysisCancelledError(operation)));
+                const timer = setTimeout(() => finish(err(new AnalysisResourceConstraintError(operation, "cpu", "Regex matching exceeded its supervised deadline; the Hopper API thread remains available.", { matching_deadline_ms: MATCHING_DEADLINE_MS }, {
+                    remediationAction: "Simplify the ECMAScript Unicode regex or use literal mode, then retry in the same session.",
+                }))), MATCHING_DEADLINE_MS);
+                options.signal?.addEventListener("abort", onAbort, { once: true });
+                if (options.signal?.aborted)
+                    onAbort();
+                worker.once("message", (message) => {
+                    const reply = replySchema.safeParse(message);
+                    if (!reply.success)
+                        return finish(err(new AnalysisOutputError(operation, "Regex worker reply is malformed")));
+                    if (reply.data.status === "invalid_pattern")
+                        return finish(err(new HopperRemoteError(-32000, `Invalid regex pattern: ${reply.data.reason}`, { diagnosticType: "invalid_request", operation })));
+                    const indices = reply.data.indices;
+                    if (indices.some((index, position) => index >= parsed.data.length ||
+                        (position > 0 && index <= (indices[position - 1] ?? -1))))
+                        return finish(err(new AnalysisOutputError(operation, "Regex worker returned invalid inventory indices")));
+                    const selected = new Set(indices);
+                    finish(ok(parsed.data.filter((_, index) => selected.has(index))));
+                });
+                worker.once("error", (cause) => finish(err(new AnalysisOutputError(operation, `Regex worker failed: ${cause.message}`, { cause }))));
+                worker.once("exit", (code) => finish(err(new AnalysisOutputError(operation, `Regex worker exited without a result (${code})`))));
+            });
+        }
+        finally {
+            await worker.terminate();
+        }
+    }
+}

package/dist/hopper/HopperRegexWorker.js

@@ -0,0 +1,27 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { z } from "zod";
+const input = z
+    .strictObject({
+    pattern: z.string().min(1),
+    caseSensitive: z.boolean(),
+    values: z.array(z.string()),
+})
+    .parse(workerData);
+let expression;
+try {
+    expression = new RegExp(input.pattern, input.caseSensitive ? "u" : "iu");
+}
+catch (cause) {
+    parentPort?.postMessage({
+        status: "invalid_pattern",
+        reason: cause instanceof Error ? cause.message : String(cause),
+    });
+}
+if (expression !== undefined) {
+    const indices = [];
+    for (const [index, value] of input.values.entries()) {
+        if (expression.test(value))
+            indices.push(index);
+    }
+    parentPort?.postMessage({ status: "matched", indices });
+}

package/dist/hopper/HopperRequestQueue.js

@@ -1,5 +1,8 @@
-import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, } from "../domain/hopperErrors.js";
+import { hopperOperationStage } from "./HopperOperationStage.js";
+import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, HopperTimeoutError, } from "../domain/hopperErrors.js";
 import { err } from "../domain/result.js";
+/** Node timer ceiling; larger deadlines would be clamped instead of honored. */
+const MAX_TIMEOUT_MS = 2_147_483_647;
 /** FIFO that keeps the wire serialized until Hopper actually replies. */
 export class HopperRequestQueue {
     send;
@@ -8,10 +11,18 @@ export class HopperRequestQueue {
     constructor(send) {
         this.send = send;
     }
-    /** Queue one request until Hopper replies or the caller cancels it. */
+    /** Settle the caller on reply, cancellation, or deadline; retain active wire work. */
     run(id, method, params, options) {
         if (options.signal?.aborted === true)
             return Promise.resolve(err(new HopperCancelledError()));
+        const timeoutMs = options.timeoutMs;
+        if (timeoutMs !== undefined &&
+            (!Number.isInteger(timeoutMs) ||
+                timeoutMs < 0 ||
+                timeoutMs > MAX_TIMEOUT_MS))
+            return Promise.resolve(err(new HopperProtocolError(`Hopper timeoutMs must be an integer between 0 and ${String(MAX_TIMEOUT_MS)}`)));
+        if (timeoutMs === 0)
+            return Promise.resolve(err(new HopperTimeoutError(0, method, id, "not_started", hopperOperationStage(method))));
         return new Promise((resolve) => {
             let entry;
             const onAbort = options.signal === undefined ? undefined : () => this.#cancel(entry);
@@ -25,12 +36,18 @@ export class HopperRequestQueue {
                 onAbort,
                 callerState: "waiting",
                 callerSettled: false,
+                transmitted: false,
                 startedAt: undefined,
                 heartbeat: undefined,
+                deadline: undefined,
+                deadlineAt: timeoutMs === undefined ? undefined : performance.now() + timeoutMs,
+                timeoutMs,
             };
             this.#queue.push(entry);
             if (onAbort !== undefined)
                 options.signal?.addEventListener("abort", onAbort, { once: true });
+            if (timeoutMs !== undefined)
+                entry.deadline = setTimeout(() => this.#cancel(entry, this.#timeoutError(entry, timeoutMs)), timeoutMs);
             if (this.#active !== undefined || this.#queue.length > 1)
                 this.#report(entry, `${method} queued behind ${String(this.#size() - 1)} Hopper request(s)`);
             this.#drain();
@@ -41,17 +58,10 @@ export class HopperRequestQueue {
         const entry = this.#active;
         if (entry === undefined || entry.id !== id)
             return false;
+        this.#expireIfElapsed(entry);
         this.#releaseWire(entry);
-        if (!entry.callerSettled) {
-            const contextual = !result.ok && result.error instanceof HopperRemoteError
-                ? err(new HopperRemoteError(result.error.code, result.error.safeMessage, {
-                    diagnosticType: result.error.diagnosticType,
-                    operation: entry.method,
-                    requestId: entry.id,
-                }))
-                : result;
-            this.#settleCaller(entry, contextual, "waiting");
-        }
+        if (!entry.callerSettled)
+            this.#settleCaller(entry, result.ok ? result : err(withRequestContext(result.error, entry)), "waiting");
         this.#active = undefined;
         this.#drain();
         return true;
@@ -120,6 +130,10 @@ export class HopperRequestQueue {
         const entry = this.#queue.shift();
         if (entry === undefined)
             return;
+        if (this.#expireIfElapsed(entry)) {
+            this.#drain();
+            return;
+        }
         if (entry.signal?.aborted === true) {
             this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
             this.#drain();
@@ -128,6 +142,17 @@ export class HopperRequestQueue {
         this.#active = entry;
         entry.startedAt = performance.now();
         this.#report(entry, `${entry.method} started on Hopper's serial bridge`);
+        this.#expireIfElapsed(entry);
+        // A progress observer may cancel or tear down synchronously before send.
+        // No native work exists yet, so it is safe to release this reserved slot.
+        if (this.#active !== entry || entry.callerSettled) {
+            if (this.#active === entry) {
+                this.#active = undefined;
+                this.#releaseWire(entry);
+                this.#drain();
+            }
+            return;
+        }
         entry.heartbeat = setInterval(() => {
             if (entry.callerSettled || entry.startedAt === undefined)
                 return;
@@ -135,30 +160,44 @@ export class HopperRequestQueue {
             this.#report(entry, `${entry.method} is still running in Hopper (${String(elapsed)} ms elapsed)`);
         }, 1_000);
         try {
-            this.send({ id: entry.id, method: entry.method, params: entry.params }, () => this.accept(entry.id, err(new HopperProcessError(null))));
+            entry.transmitted = true;
+            this.send({ id: entry.id, method: entry.method, params: entry.params }, () => this.accept(entry.id, err(new HopperProcessError(null, undefined, entry.method, entry.id, "unreachable", hopperOperationStage(entry.method)))));
         }
         catch (cause) {
             this.accept(entry.id, err(new HopperProtocolError("Hopper socket write failed", { cause })));
         }
     }
-    #cancel(entry) {
+    #timeoutError(entry, timeoutMs) {
+        return new HopperTimeoutError(timeoutMs, entry.method, entry.id, entry.transmitted ? "busy" : "not_started", hopperOperationStage(entry.method));
+    }
+    #expireIfElapsed(entry) {
+        if (entry.deadlineAt !== undefined &&
+            entry.timeoutMs !== undefined &&
+            performance.now() >= entry.deadlineAt)
+            this.#settleCaller(entry, err(this.#timeoutError(entry, entry.timeoutMs)), "cancelled");
+        return entry.callerSettled;
+    }
+    #cancel(entry, error = new HopperCancelledError()) {
         if (entry.callerSettled)
             return;
         if (this.#active === entry) {
-            this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
+            this.#settleCaller(entry, err(error), "cancelled");
             return;
         }
         const index = this.#queue.indexOf(entry);
         if (index < 0)
             return;
         this.#queue.splice(index, 1);
-        this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
+        this.#settleCaller(entry, err(error), "cancelled");
     }
     #settleCaller(entry, result, callerState) {
         if (entry.callerSettled)
             return;
         entry.callerSettled = true;
         entry.callerState = callerState;
+        if (entry.deadline !== undefined)
+            clearTimeout(entry.deadline);
+        entry.deadline = undefined;
         if (this.#active === entry && entry.heartbeat !== undefined) {
             clearInterval(entry.heartbeat);
             entry.heartbeat = undefined;
@@ -195,6 +234,16 @@ export class HopperRequestQueue {
         }
     }
 }
-const withRequestContext = (error, entry) => error instanceof HopperProcessError
-    ? new HopperProcessError(error.exitCode, error.diagnostic, entry.method, entry.id)
-    : error;
+const withRequestContext = (error, entry) => {
+    if (error instanceof HopperProcessError)
+        return new HopperProcessError(error.exitCode, error.diagnostic, error.operation ?? entry.method, error.requestId ?? entry.id, error.providerState, error.operation === undefined && error.stage === "connection"
+            ? hopperOperationStage(entry.method)
+            : error.stage);
+    if (error instanceof HopperRemoteError)
+        return new HopperRemoteError(error.code, error.safeMessage, {
+            diagnosticType: error.diagnosticType,
+            operation: error.operation ?? entry.method,
+            requestId: error.requestId ?? entry.id,
+        });
+    return error;
+};

package/dist/hopper/HopperTargetLease.js

@@ -1,14 +1,13 @@
 import { createHash } from "node:crypto";
-import { chmod, lstat, mkdir, realpath, rm } from "node:fs/promises";
+import { chmod, lstat, mkdir, realpath, rm, rmdir } from "node:fs/promises";
 import { createConnection, createServer, } from "node:net";
 import { join, resolve } from "node:path";
 import { HopperStartError } from "../domain/hopperErrors.js";
 import { safeParseJson } from "../domain/safeJson.js";
-const leaseDirectory = join("/tmp", `rea-hopper-${process.getuid?.() ?? 0}`);
+/** Shared private parent of Hopper lease sockets; it outlives individual sessions. */
+export const HOPPER_TARGET_LEASE_DIRECTORY = join("/tmp", `rea-hopper-${process.getuid?.() ?? 0}`);
 /** Keep two REA processes from opening duplicate Hopper documents for one target/profile. */
 export const acquireHopperTargetLease = async (input) => {
-    const directory = input.directory ?? leaseDirectory;
-    await ensureLeaseDirectory(directory);
     // The canonical path only derives the lease key; it never authorizes access.
     // Common expected `realpath` failures include a missing target or path
     // component (ENOENT, ENOTDIR), an unreadable component (EACCES), or a
@@ -17,43 +16,105 @@ export const acquireHopperTargetLease = async (input) => {
     // still yields a deterministic key, but aliases may take separate leases
     // whenever `realpath` cannot resolve them.
     const targetPath = await realpath(input.targetPath).catch(() => resolve(input.targetPath));
+    return acquireLease({
+        ...input,
+        identity: {
+            targetPath,
+            targetKind: input.targetKind,
+            loaderArgs: input.loaderArgs,
+        },
+    });
+};
+/** Reserve the Linux demo's singleton application before it can forward a target to another owner. */
+export const acquireLinuxHopperApplicationLease = (input) => acquireLease({ ...input, identity: { application: "linux-hopper-demo" } });
+const acquireLease = async (input) => {
+    const directory = input.directory ?? HOPPER_TARGET_LEASE_DIRECTORY;
+    await ensureLeaseDirectory(directory);
     const key = createHash("sha256")
-        .update(JSON.stringify({
-        targetPath,
-        targetKind: input.targetKind,
-        loaderArgs: input.loaderArgs,
-    }))
+        .update(JSON.stringify(input.identity))
         .digest("hex")
         .slice(0, 32);
     const socketPath = join(directory, `${key}.sock`);
     const owner = { runId: input.runId, processId: process.pid };
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-        const server = createServer((socket) => sendOwner(socket, owner));
-        const bound = await bind(server, socketPath);
-        if (bound) {
-            await chmod(socketPath, 0o600);
-            let released = false;
-            return {
-                acquired: true,
-                lease: {
-                    release: async () => {
-                        if (released)
-                            return;
-                        released = true;
-                        await closeServer(server);
-                        await rm(socketPath, { force: true });
-                    },
-                },
-            };
+    const acquisition = await tryAcquireLease(socketPath, owner);
+    if (typeof acquisition !== "string")
+        return acquisition;
+    // Serialize stale cleanup through the replacement bind: otherwise two
+    // recoverers can unlink the socket that one of them has just acquired.
+    const recoveryPath = `${socketPath}.recovery`;
+    await reserveRecovery(recoveryPath);
+    let recovered;
+    try {
+        recovered = await tryAcquireLease(socketPath, owner);
+        if (recovered === "stale")
+            await rm(socketPath, { force: true });
+        if (typeof recovered === "string")
+            recovered = await tryAcquireLease(socketPath, owner);
+        if (typeof recovered !== "string")
+            return recovered;
+        throw new HopperStartError({
+            userMessage: "REA could not reserve Hopper for this request. Close competing REA sessions and retry.",
+        });
+    }
+    finally {
+        try {
+            await rmdir(recoveryPath);
         }
+        catch (cause) {
+            if (typeof recovered !== "string" && recovered?.acquired)
+                await recovered.lease.release();
+            throw new HopperStartError({
+                cause,
+                userMessage: `REA could not remove its Hopper recovery directory at ${JSON.stringify(recoveryPath)}. Check this directory's write access before retrying.`,
+            });
+        }
+    }
+};
+const reserveRecovery = async (recoveryPath) => {
+    try {
+        await mkdir(recoveryPath, { mode: 0o700 });
+    }
+    catch (cause) {
+        const busy = typeof cause === "object" &&
+            cause !== null &&
+            Reflect.get(cause, "code") === "EEXIST";
+        throw new HopperStartError({
+            cause,
+            userMessage: busy
+                ? `REA could not reserve Hopper lease recovery at ${JSON.stringify(recoveryPath)}; the existing socket was left unchanged. Retry after concurrent startup finishes. If recovery was interrupted, stop REA sessions and remove this recovery directory before retrying.`
+                : `REA could not create its Hopper recovery directory at ${JSON.stringify(recoveryPath)}; the existing socket was left unchanged. Check the parent directory's write access before retrying.`,
+        });
+    }
+};
+const tryAcquireLease = async (socketPath, owner) => {
+    const server = createServer((socket) => sendOwner(socket, owner));
+    if (!(await bind(server, socketPath))) {
         const existingOwner = await readOwner(socketPath);
-        if (existingOwner !== undefined)
-            return { acquired: false, owner: existingOwner };
-        await rm(socketPath, { force: true });
+        return typeof existingOwner === "string"
+            ? existingOwner
+            : { acquired: false, owner: existingOwner };
     }
-    throw new HopperStartError({
-        userMessage: "REA could not reserve this Hopper target. Close competing REA sessions and retry.",
-    });
+    try {
+        await chmod(socketPath, 0o600);
+    }
+    catch (cause) {
+        await closeServer(server);
+        throw cause;
+    }
+    let released = false;
+    return {
+        acquired: true,
+        lease: {
+            release: async () => {
+                if (released)
+                    return;
+                // Node removes a bound Unix socket on close. A second unlink here
+                // could remove a new owner's socket bound after that close.
+                await closeServer(server);
+                released = true;
+            },
+        },
+    };
 };
 const ensureLeaseDirectory = async (directory) => {
     let directoryStat;
@@ -95,14 +156,26 @@ const bind = (server, socketPath) => new Promise((resolveBind, reject) => {
 const sendOwner = (socket, owner) => {
     socket.end(`${JSON.stringify(owner)}\n`);
 };
-const readOwner = (socketPath) => new Promise((resolveOwner) => {
+const readOwner = (socketPath) => new Promise((resolveOwner, rejectOwner) => {
     const socket = createConnection(socketPath);
     let response = "";
-    const timer = setTimeout(() => {
+    let settled = false;
+    const fail = (reason, cause) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
         socket.destroy();
-        resolveOwner(undefined);
-    }, 250);
+        rejectOwner(new HopperStartError({
+            cause,
+            userMessage: `REA could not verify the existing Hopper lease (${reason}); it was left unchanged. Retry when the owning REA session is responsive.`,
+        }));
+    };
+    const timer = setTimeout(() => fail("owner response timed out"), 250);
     const finish = (owner) => {
+        if (settled)
+            return;
+        settled = true;
         clearTimeout(timer);
         socket.destroy();
         resolveOwner(owner);
@@ -114,23 +187,34 @@ const readOwner = (socketPath) => new Promise((resolveOwner) => {
             return;
         const parsed = safeParseJson(response.slice(0, newline));
         if (!parsed.ok) {
-            finish(undefined);
+            fail("malformed owner response");
             return;
         }
         const value = parsed.value;
-        if (typeof value === "object" &&
-            value !== null &&
-            typeof Reflect.get(value, "runId") === "string" &&
-            typeof Reflect.get(value, "processId") === "number")
-            finish({
-                runId: Reflect.get(value, "runId"),
-                processId: Reflect.get(value, "processId"),
-            });
+        const runId = typeof value === "object" && value !== null
+            ? Reflect.get(value, "runId")
+            : undefined;
+        const processId = typeof value === "object" && value !== null
+            ? Reflect.get(value, "processId")
+            : undefined;
+        if (typeof runId === "string" &&
+            runId.length > 0 &&
+            typeof processId === "number" &&
+            Number.isSafeInteger(processId) &&
+            processId > 0)
+            finish({ runId, processId });
+        else
+            fail("invalid owner identity");
+    });
+    socket.on("error", (cause) => {
+        if (cause.code === "ENOENT")
+            finish("missing");
+        else if (cause.code === "ECONNREFUSED")
+            finish("stale");
         else
-            finish(undefined);
+            fail(cause.code ?? "owner connection failed", cause);
     });
-    socket.on("error", () => finish(undefined));
-    socket.on("end", () => finish(undefined));
+    socket.on("end", () => fail("owner closed without a complete response"));
 });
 const closeServer = (server) => new Promise((resolveClose, reject) => {
     if (!server.listening) {

package/dist/hopper/LinuxPrivateDisplayProbe.js

@@ -50,6 +50,9 @@ export const runLinuxPrivateDisplayProbe = async (strategy, options) => {
             arguments: command.arguments,
             runId: randomUUID(),
             expectedCommand: null,
+            ...(options.environment === undefined
+                ? {}
+                : { hostEnvironment: options.environment }),
             ...(options.signal === undefined ? {} : { signal: options.signal }),
         });
     }
@@ -111,6 +114,9 @@ const evaluatedProbe = async (strategy, options, timeoutMs, runner) => {
     try {
         processResult = await runner(strategy, {
             helperPath: options.helperPath,
+            ...(options.environment === undefined
+                ? {}
+                : { environment: options.environment }),
             timeoutMs,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
         });

package/dist/ida/IdaConfiguration.js

@@ -40,7 +40,7 @@ const registrationSchema = z.union([
 export const readIdaConfiguration = (path) => {
     try {
         if (statSync(path).size > 65_536)
-            return err(new ConfigurationError("REA_IDA_MCP_CONFIG exceeds the 64 KiB registration size."));
+            return err(idaConfigurationError("REA_IDA_MCP_CONFIG exceeds the 64 KiB registration size."));
         const input = JSON.parse(readFileSync(path, "utf8"));
         const envelope = z
             .object({ mcpServers: z.object({ "ida-pro-mcp": z.unknown() }) })
@@ -48,9 +48,14 @@ export const readIdaConfiguration = (path) => {
         const parsed = registrationSchema.safeParse(envelope.success ? envelope.data.mcpServers["ida-pro-mcp"] : input);
         return parsed.success
             ? ok(parsed.data)
-            : err(new ConfigurationError("REA_IDA_MCP_CONFIG must contain an IDA MCP command/args or local url registration; see docs/ida-provider.md.", { cause: parsed.error }));
+            : err(idaConfigurationError("REA_IDA_MCP_CONFIG must contain an IDA MCP command/args or local url registration; see docs/ida-provider.md.", parsed.error));
     }
     catch (cause) {
-        return err(new ConfigurationError(`Cannot read IDA MCP registration ${path}; provide a readable JSON configuration.`, { cause }));
+        return err(idaConfigurationError(`Cannot read IDA MCP registration ${path}; provide a readable JSON configuration.`, cause));
     }
 };
+/** A REA_IDA_MCP_CONFIG rejection that names the setting it concerns. */
+export const idaConfigurationError = (constraint, cause) => new ConfigurationError(constraint, {
+    ...(cause === undefined ? {} : { cause }),
+    settings: [{ setting: "REA_IDA_MCP_CONFIG", constraint }],
+});

package/dist/ida/IdaInput.js

@@ -1,4 +1,3 @@
-import { z } from "zod";
 import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";
 import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import { jsonObjectSchema } from "../domain/jsonValue.js";
@@ -8,12 +7,7 @@ import { projectInputIssues } from "../domain/inputIssueProjection.js";
 /** Apply the named public contract and IDA's explicit-address boundary before startup. */
 export const parseIdaInput = (operation, parameters) => {
     const contract = TOOL_CONTRACTS.find(({ name }) => name === operation);
-    const schema = contract?.inputSchema;
-    if (schema instanceof z.ZodObject) {
-        const shape = schema.shape;
-        parameters = Object.fromEntries(Object.entries(parameters).filter(([key, value]) => value !== null || shape[key]?.safeParse(undefined).success !== true));
-    }
-    const parsed = (schema instanceof z.ZodObject ? schema.strict() : schema)?.safeParse(parameters);
+    const parsed = contract?.inputSchema.safeParse(parameters);
     if (parsed?.success !== true)
         return err(new AnalysisInputError(operation, { cause: parsed?.error }, parsed?.error === undefined
             ? []

package/dist/ida/IdaMcpConnection.js

@@ -1,5 +1,6 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { Client, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
-import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { DEFAULT_INHERITED_ENV_VARS, StdioClientTransport, } from "@modelcontextprotocol/client/stdio";
 import { z } from "zod";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
@@ -66,7 +67,7 @@ export const redactIdaTransportFailure = (cause, config) => {
     return new Error(message, { cause });
 };
 /** Create a standard SDK connection to an existing upstream registration. */
-export const createIdaMcpConnection = (config) => {
+export const createIdaMcpConnection = (config, environment) => {
     const client = new Client({ name: "rea-ida-provider", version: "1" });
     const transportFailure = (cause) => {
         throw redactIdaTransportFailure(cause, config);
@@ -76,9 +77,12 @@ export const createIdaMcpConnection = (config) => {
             command: config.command,
             args: config.args,
             env: {
-                ...Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined)),
+                // The SDK always merges ambient defaults. Its string-only environment
+                // API requires empty values to suppress omitted caller-selected keys.
+                ...Object.fromEntries(DEFAULT_INHERITED_ENV_VARS.map((key) => [key, ""])),
+                ...Object.fromEntries(Object.entries(snapshotEnvironment(environment)).filter((entry) => entry[1] !== undefined)),
                 IDA_MCP_MAX_WORKERS: "1",
-                ...config.env,
+                ...snapshotEnvironment(config.env),
             },
             stderr: "pipe",
         })