muonroi-cli 1.4.1 → 1.6.0

package/dist/src/mcp/__tests__/client-pool.spec.js

@@ -0,0 +1,98 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+// Pool reuse semantics: connect a server ONCE, reuse the live client across
+// turns, evict on failure (retry) and on a post-connect connection error
+// (reconnect), and tear everything down on closeAllMcpClients().
+vi.mock("../validate.js", () => ({ validateMcpServerConfig: () => ({ ok: true }) }));
+const connectOneServer = vi.fn();
+vi.mock("../runtime.js", () => ({
+    connectOneServer: (...args) => connectOneServer(...args),
+    getMcpBuildDeadlineMs: () => 500,
+}));
+import { __mcpClientPoolSize, __resetMcpClientPoolForTests, acquireMcpTools, closeAllMcpClients, warmMcpClients, } from "../client-pool.js";
+const srv = (id) => ({ id, label: id, enabled: true, transport: "stdio", command: "x", args: [] });
+const connected = (id, close = async () => { }) => ({
+    tools: { [`mcp_${id}__ping`]: { execute: async () => "pong" } },
+    client: { close },
+});
+describe("acquireMcpTools — cross-turn client pool", () => {
+    beforeEach(() => {
+        __resetMcpClientPoolForTests();
+        connectOneServer.mockReset();
+    });
+    afterEach(async () => {
+        await closeAllMcpClients();
+    });
+    it("connects a server once and reuses it across turns (no per-turn cold-spawn)", async () => {
+        connectOneServer.mockImplementation(async (s) => connected(s.id));
+        const b1 = await acquireMcpTools([srv("fs")]);
+        expect(Object.keys(b1.tools)).toContain("mcp_fs__ping");
+        await b1.close(); // release — must NOT kill the pooled client
+        const b2 = await acquireMcpTools([srv("fs")]);
+        expect(Object.keys(b2.tools)).toContain("mcp_fs__ping");
+        expect(connectOneServer).toHaveBeenCalledTimes(1); // reused, not re-spawned
+    });
+    it("evicts a failed connect so a later turn retries", async () => {
+        connectOneServer
+            .mockRejectedValueOnce(new Error("spawn failed"))
+            .mockImplementation(async (s) => connected(s.id));
+        const b1 = await acquireMcpTools([srv("fs")]);
+        expect(b1.errors.some((e) => e.includes("fs"))).toBe(true);
+        expect(Object.keys(b1.tools)).not.toContain("mcp_fs__ping");
+        const b2 = await acquireMcpTools([srv("fs")]);
+        expect(Object.keys(b2.tools)).toContain("mcp_fs__ping");
+        expect(connectOneServer).toHaveBeenCalledTimes(2); // retried after eviction
+    });
+    it("self-heals: a tool hitting a connection error evicts the client so the next turn reconnects", async () => {
+        connectOneServer.mockImplementation(async (s) => ({
+            tools: {
+                [`mcp_${s.id}__boom`]: {
+                    execute: async () => {
+                        throw new Error("MCP transport closed");
+                    },
+                },
+            },
+            client: { close: async () => { } },
+        }));
+        const b1 = await acquireMcpTools([srv("fs")]);
+        await expect(b1.tools["mcp_fs__boom"].execute({}, {})).rejects.toThrow(/transport closed/);
+        const b2 = await acquireMcpTools([srv("fs")]);
+        expect(b2).toBeDefined();
+        expect(connectOneServer).toHaveBeenCalledTimes(2); // reconnected after the connection error
+    });
+    it("keys by cwd/config — a different command reconnects rather than reusing", async () => {
+        connectOneServer.mockImplementation(async (s) => connected(s.id));
+        await acquireMcpTools([
+            { id: "fs", label: "fs", enabled: true, transport: "stdio", command: "a", args: [] },
+        ]);
+        await acquireMcpTools([
+            { id: "fs", label: "fs", enabled: true, transport: "stdio", command: "b", args: [] },
+        ]);
+        expect(connectOneServer).toHaveBeenCalledTimes(2);
+    });
+    it("warmMcpClients pre-connects so the first real turn reuses (no extra spawn)", async () => {
+        let resolveConnect = () => { };
+        connectOneServer.mockImplementation((s) => new Promise((res) => {
+            resolveConnect = () => res(connected(s.id));
+        }));
+        // Warm starts the connect in the background.
+        warmMcpClients([srv("fs")]);
+        expect(connectOneServer).toHaveBeenCalledTimes(1);
+        expect(__mcpClientPoolSize()).toBe(1);
+        // Let the warm connect finish, then a real turn reuses it.
+        resolveConnect();
+        await new Promise((r) => setTimeout(r, 0));
+        const b = await acquireMcpTools([srv("fs")]);
+        expect(Object.keys(b.tools)).toContain("mcp_fs__ping");
+        expect(connectOneServer).toHaveBeenCalledTimes(1); // warmed, not re-spawned
+    });
+    it("closeAllMcpClients tears down every pooled client", async () => {
+        const closeSpy = vi.fn(async () => { });
+        connectOneServer.mockImplementation(async (s) => connected(s.id, closeSpy));
+        await acquireMcpTools([srv("fs"), srv("mem")]);
+        expect(__mcpClientPoolSize()).toBe(2);
+        await closeAllMcpClients();
+        expect(closeSpy).toHaveBeenCalledTimes(2);
+        expect(__mcpClientPoolSize()).toBe(0);
+    });
+});
+//# sourceMappingURL=client-pool.spec.js.map

package/dist/src/mcp/__tests__/parallel-build.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/mcp/__tests__/parallel-build.spec.js

@@ -0,0 +1,67 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+// Phase 1c regression: buildMcpToolSet must connect servers in PARALLEL and
+// return PARTIAL results at its deadline, so a slow server (e.g. an npx stdio
+// spawn) never starves a fast one. The OLD sequential build under an outer race
+// dropped the WHOLE bundle on timeout — the agent then saw NO MCP tools even
+// when a fast HTTP server was reachable (session f6f7881a5fae).
+vi.mock("../mcp-keychain.js", () => ({
+    getMcpKey: vi.fn(async () => null),
+    setMcpKey: vi.fn(async () => true),
+    deleteMcpKey: vi.fn(async () => true),
+}));
+vi.mock("@modelcontextprotocol/sdk/client/stdio.js", () => ({
+    StdioClientTransport: vi.fn(function (opts) {
+        Object.assign(this, opts);
+    }),
+    getDefaultEnvironment: () => ({}),
+}));
+vi.mock("../validate.js", () => ({
+    validateMcpServerConfig: () => ({ ok: true }),
+}));
+const fastClient = {
+    tools: async () => ({ ping: { description: "ping", execute: async () => ({ ok: true }) } }),
+    close: async () => { },
+};
+vi.mock("@ai-sdk/mcp", () => ({
+    // A server whose name contains "slow" never finishes connecting (simulates a
+    // slow npx spawn). Everything else connects instantly.
+    createMCPClient: vi.fn(async ({ name }) => {
+        if (name.includes("slow"))
+            return new Promise(() => { }); // never resolves
+        return fastClient;
+    }),
+}));
+describe("buildMcpToolSet — parallel build, partial results at deadline (Phase 1c)", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        delete process.env.MUONROI_MCP_BUILD_DEADLINE_MS;
+    });
+    it("returns the fast server's tools and reports the slow one — slow does NOT starve fast", async () => {
+        process.env.MUONROI_MCP_BUILD_DEADLINE_MS = "500";
+        const { buildMcpToolSet } = await import("../runtime.js");
+        const start = Date.now();
+        const bundle = await buildMcpToolSet([
+            { id: "slow-server", label: "slow-server", enabled: true, transport: "stdio", command: "node", args: [] },
+            { id: "fast-server", label: "fast-server", enabled: true, transport: "stdio", command: "node", args: [] },
+        ]);
+        const elapsed = Date.now() - start;
+        // Resolved at ~the deadline, NOT blocked behind the slow (never-ending) connect.
+        expect(elapsed).toBeLessThan(2000);
+        // The fast server's tool is available even though a slower server is pending.
+        expect(Object.keys(bundle.tools)).toContain("mcp_fast-server__ping");
+        // The slow server is surfaced as an error, never silently dropped.
+        expect(bundle.errors.some((e) => e.includes("slow-server") && /not ready within/.test(e))).toBe(true);
+        await bundle.close();
+    });
+    it("orders are independent — the fast server loads regardless of position", async () => {
+        process.env.MUONROI_MCP_BUILD_DEADLINE_MS = "500";
+        const { buildMcpToolSet } = await import("../runtime.js");
+        const bundle = await buildMcpToolSet([
+            { id: "fast-server", label: "fast-server", enabled: true, transport: "stdio", command: "node", args: [] },
+            { id: "slow-server", label: "slow-server", enabled: true, transport: "stdio", command: "node", args: [] },
+        ]);
+        expect(Object.keys(bundle.tools)).toContain("mcp_fast-server__ping");
+        await bundle.close();
+    });
+});
+//# sourceMappingURL=parallel-build.spec.js.map

package/dist/src/mcp/__tests__/smart-filter.test.js

@@ -6,6 +6,7 @@ const servers = [
     { id: "filesystem" },
     { id: "muonroi-tools" },
     { id: "muonroi-harness" },
+    { id: "muonroi-docs" },
     { id: "context7" },
     { id: "fetch" },
     { id: "tavily" },
@@ -62,6 +63,26 @@ describe("filterMcpServersByMessage", () => {
         expect(ids(out)).toContain("muonroi-tools");
         expect(ids(out)).toContain("muonroi-harness");
     });
+    it("keeps muonroi-docs for an ecosystem question that has no generic docs keyword", () => {
+        // Live miss (session dbe408937a3d turn 1): "bạn hiểu thế nào về hệ sinh thái
+        // muonroi" carries no docs/api keyword and doesn't say "muonroi-docs", so the
+        // authoritative ecosystem source was dropped and the agent guessed from files.
+        for (const msg of [
+            "bạn hiểu thế nào về hệ sinh thái muonroi",
+            "what is the muonroi ecosystem?",
+            "explain the building-block rule engine",
+        ]) {
+            const out = filterMcpServersByMessage(servers, msg);
+            expect(ids(out), msg).toContain("muonroi-docs");
+        }
+    });
+    it("keeping muonroi-docs for an ecosystem question does NOT over-keep other docs/web servers", () => {
+        const out = filterMcpServersByMessage(servers, "bạn hiểu thế nào về hệ sinh thái muonroi");
+        expect(ids(out)).toContain("muonroi-docs");
+        expect(ids(out)).not.toContain("context7");
+        expect(ids(out)).not.toContain("fetch");
+        expect(ids(out)).not.toContain("tavily");
+    });
     it("returns every server unchanged when disabled (MUONROI_DISABLE_SMART_MCP=1)", () => {
         const out = filterMcpServersByMessage(servers, "Reply PONG", { disabled: true });
         expect(ids(out)).toEqual(ids(servers));
@@ -74,6 +95,41 @@ describe("filterMcpServersByMessage", () => {
             expect(ids(out)).toContain("chrome-devtools");
         }
     });
+    // Regression: session f6f7881a5fae. The user asked "bạn thử call tool
+    // setup_guide ... ( call tool chứ không phải đọc code )". `muonroi-docs` (id
+    // matches /docs/) carried no docs-lookup keyword, so the category skip dropped
+    // it — the model had no `setup_guide` tool and drove the server by hand over
+    // bash JSON-RPC. An explicit tool-invocation intent (or an outright server
+    // mention) must keep the owning server.
+    const docsServers = [{ id: "filesystem" }, { id: "muonroi-docs" }, { id: "context7" }, { id: "tavily" }];
+    it("keeps an optional server when the user explicitly asks to CALL a tool by name", () => {
+        const msg = "bạn thử call tool setup_guide xem có được thông tin gì không nhé ( call tool chứ không phải đọc code nhé )";
+        expect(ids(filterMcpServersByMessage(docsServers, msg))).toContain("muonroi-docs");
+    });
+    it("recognises explicit tool-invocation intent (EN + VI)", () => {
+        for (const msg of [
+            "please call the setup_guide tool and report",
+            "use the docs_search tool",
+            "invoke the mcp tool",
+            "do a tool call to setup_guide",
+            "dùng tool docs_search giúp tôi",
+            "gọi tool setup_guide",
+            "thử mcp tool xem sao",
+        ]) {
+            expect(ids(filterMcpServersByMessage(docsServers, msg)), msg).toContain("muonroi-docs");
+        }
+    });
+    it("keeps a server named outright in the message even without a category signal", () => {
+        // "check the muonroi-docs MCP" — no docs-lookup verb, but the server is named.
+        const out = filterMcpServersByMessage(docsServers, "bạn check xem dùng được mcp muonroi-docs không nhé");
+        expect(ids(out)).toContain("muonroi-docs");
+    });
+    it("still drops optional servers on a pure code prompt (token savings preserved)", () => {
+        // The fix must NOT defeat the filter: no tool-intent, no server mention, no
+        // docs signal → muonroi-docs/context7/tavily still dropped.
+        const out = filterMcpServersByMessage(docsServers, "fix the off-by-one in parseRange()");
+        expect(ids(out)).toEqual(["filesystem"]);
+    });
 });
 describe("dropRedundantFsMcpTools", () => {
     const fn = () => ({});

package/dist/src/mcp/auto-setup.js

@@ -1,5 +1,44 @@
 import { loadMcpServers, saveMcpServers } from "../utils/settings.js";
+/**
+ * True when running inside a test runner (vitest). Used to keep seed-time
+ * persistence from mutating the user's REAL config — see ensureDefaultMcpServers.
+ */
+function isTestRunner() {
+    return process.env.VITEST === "true" || process.env.VITEST_WORKER_ID !== undefined || process.env.NODE_ENV === "test";
+}
+/**
+ * Remove a deprecated self-spawned `muonroi-tools` stdio server from the config.
+ *
+ * The CLI's OWN inner agent now exposes ee_query/ee_feedback/ee_health/
+ * usage_forensics/lsp_query/setup_guide/selfverify_* as NATIVE in-process
+ * builtins (src/tools/native-tools.ts) — strictly better than self-spawning a
+ * 137MB CLI as an MCP subprocess (which cold-started 2-3.5s, overran the build
+ * deadline, and once had a vitest-worker command persisted that crashed on
+ * launch). So the self-spawn is now pure waste: every tool it would expose is
+ * dropped as a native twin. Strip it on sight. The muonroi-tools MCP server
+ * still exists for EXTERNAL agents via their own config (e.g. ~/.claude.json) —
+ * that is a different file and is untouched here. Returns true if it changed.
+ */
+function removeDeprecatedToolsMcp(servers) {
+    const idx = servers.findIndex((s) => s.id === "muonroi-tools" && s.transport === "stdio");
+    if (idx < 0)
+        return false;
+    servers.splice(idx, 1);
+    console.error("[mcp:auto-setup] removed deprecated self-spawned muonroi-tools server — its tools are now native in-process builtins");
+    return true;
+}
 const DEFAULT_CONFIGS = [
+    {
+        // Authoritative source for the Muonroi ecosystem (BB/.NET template recipes,
+        // package docs, setup_guide, docs_search). Shipped enabled by default so any
+        // task touching the ecosystem always has a standard source to work from —
+        // the CLI behaves like a senior who knows the ecosystem, not one guessing.
+        id: "muonroi-docs",
+        label: "muonroi-docs (Ecosystem Docs)",
+        enabled: true,
+        transport: "http",
+        url: "https://docs-mcp.muonroi.com/mcp",
+    },
     {
         id: "filesystem",
         label: "Filesystem",
@@ -81,6 +120,13 @@ export function ensureDefaultMcpServers() {
     try {
         const existing = loadMcpServers();
         let dirty = migrateServers(existing);
+        // muonroi-tools is no longer self-spawned by the CLI — its capabilities
+        // (ee_query/ee_feedback/ee_health/usage_forensics/lsp_query/setup_guide/
+        // selfverify_*) are NATIVE in-process builtins now (src/tools/native-tools.ts).
+        // Strip any deprecated self-spawn entry so it stops cold-starting a redundant
+        // subprocess every turn (and removes the old vitest-worker-poisoned ones).
+        if (removeDeprecatedToolsMcp(existing))
+            dirty = true;
         const existingIds = new Set(existing.map((s) => s.id));
         const toAdd = DEFAULT_CONFIGS.filter((s) => !existingIds.has(s.id));
         if (toAdd.length > 0)
@@ -88,10 +134,18 @@ export function ensureDefaultMcpServers() {
         if (!dirty)
             return existing;
         const merged = toAdd.length > 0 ? [...toAdd, ...existing] : existing;
-        saveMcpServers(merged);
+        // Never let a test runner mutate the user's REAL config file. Tests assert on
+        // the returned array; persistence is exercised only on real runs. This closes
+        // the leak whereby the seed (run from the Orchestrator constructor, which
+        // orchestrator tests trigger) wrote into a live config.
+        if (!isTestRunner())
+            saveMcpServers(merged);
         return merged;
     }
-    catch {
+    catch (err) {
+        console.error(`[mcp:auto-setup] ensureDefaultMcpServers failed: ${err?.message}`, {
+            stack: err?.stack?.split("\n").slice(0, 3),
+        });
         return [];
     }
 }

package/dist/src/mcp/client-pool.d.ts

@@ -0,0 +1,46 @@
+/**
+ * src/mcp/client-pool.ts
+ *
+ * Cross-turn MCP client pool. The orchestrator rebuilds its tool set every turn
+ * (and closes it in a `finally`), which previously cold-spawned EVERY stdio MCP
+ * server (npx filesystem/playwright/fetch/tavily/…) on every turn — each spawn
+ * costs ~1-3s and raced the build deadline. This pool connects each server ONCE
+ * and reuses the live client across turns: only the first turn that needs a
+ * server pays the cold-start; later turns select its (already-built) tools
+ * instantly. Real teardown happens once on orchestrator/process shutdown.
+ *
+ * Per-turn smart-filtering is unchanged — the caller still passes only the
+ * servers relevant to this message; the pool just avoids re-spawning the ones
+ * it has already connected.
+ *
+ * Self-healing: a server that fails to connect is evicted (not cached as a
+ * rejection), so a later turn retries. A live client whose child process dies
+ * later is evicted when one of its tool calls hits a transport/connection error,
+ * so the next turn reconnects fresh.
+ */
+import type { McpServerConfig } from "../utils/settings.js";
+import { type McpBuildOptions, type McpToolBundle } from "./runtime.js";
+/**
+ * Acquire the tool set for `servers`, reusing pooled clients where possible.
+ * Mirrors buildMcpToolSet's parallel + partial-at-deadline contract, but only
+ * FIRST-connects can be slow — already-pooled servers resolve instantly. The
+ * returned bundle's `close()` is a no-op RELEASE: pooled clients stay alive for
+ * the next turn. Use closeAllMcpClients() for real teardown.
+ */
+export declare function acquireMcpTools(servers: McpServerConfig[], opts?: McpBuildOptions): Promise<McpToolBundle>;
+/**
+ * Fire-and-forget pre-connect: start connecting `servers` in the background so
+ * they are pooled BEFORE the first turn needs them. npx stdio servers
+ * (filesystem/memory) cold-start >2.5s and would otherwise miss the first turn's
+ * build deadline — warming them at startup means they're usually ready by the
+ * first prompt. No deadline, no return; per-turn acquireMcpTools reuses whatever
+ * has connected. Idempotent (cached entries are reused); a failed connect is
+ * evicted by getOrConnect so a real turn retries.
+ */
+export declare function warmMcpClients(servers: McpServerConfig[]): void;
+/** Tear down every pooled client. Call on orchestrator/process shutdown. */
+export declare function closeAllMcpClients(): Promise<void>;
+/** Test-only: reset pool state between cases. */
+export declare function __resetMcpClientPoolForTests(): void;
+/** Test-only: number of pooled (connecting or connected) entries. */
+export declare function __mcpClientPoolSize(): number;

package/dist/src/mcp/client-pool.js

@@ -0,0 +1,212 @@
+/**
+ * src/mcp/client-pool.ts
+ *
+ * Cross-turn MCP client pool. The orchestrator rebuilds its tool set every turn
+ * (and closes it in a `finally`), which previously cold-spawned EVERY stdio MCP
+ * server (npx filesystem/playwright/fetch/tavily/…) on every turn — each spawn
+ * costs ~1-3s and raced the build deadline. This pool connects each server ONCE
+ * and reuses the live client across turns: only the first turn that needs a
+ * server pays the cold-start; later turns select its (already-built) tools
+ * instantly. Real teardown happens once on orchestrator/process shutdown.
+ *
+ * Per-turn smart-filtering is unchanged — the caller still passes only the
+ * servers relevant to this message; the pool just avoids re-spawning the ones
+ * it has already connected.
+ *
+ * Self-healing: a server that fails to connect is evicted (not cached as a
+ * rejection), so a later turn retries. A live client whose child process dies
+ * later is evicted when one of its tool calls hits a transport/connection error,
+ * so the next turn reconnects fresh.
+ */
+import { connectOneServer, getMcpBuildDeadlineMs, } from "./runtime.js";
+import { validateMcpServerConfig } from "./validate.js";
+const pool = new Map();
+/**
+ * Stable identity for a connected server. Includes cwd (stdio servers like
+ * filesystem inherit it) + command/args/url/env so a config or cwd change
+ * reconnects instead of reusing a stale client.
+ */
+function serverKey(s) {
+    return JSON.stringify({
+        id: s.id,
+        transport: s.transport,
+        command: s.command ?? null,
+        args: s.args ?? null,
+        url: s.url ?? null,
+        headers: s.headers ?? null,
+        env: s.env ?? null,
+        cwd: s.cwd ?? process.cwd(),
+    });
+}
+/** Tear down one pooled entry (best-effort) and remove it. */
+function evict(key) {
+    const entry = pool.get(key);
+    if (!entry)
+        return;
+    pool.delete(key);
+    void entry.promise.then((cs) => {
+        cs.cleanup?.();
+        void cs.client.close().catch(() => { });
+    }, () => { });
+}
+/** Heuristic: does this error mean the MCP transport/child is gone? */
+function isConnectionError(e) {
+    const msg = (e instanceof Error ? e.message : String(e)).toLowerCase();
+    return (msg.includes("closed") ||
+        msg.includes("disconnect") ||
+        msg.includes("econnrefused") ||
+        msg.includes("epipe") ||
+        msg.includes("transport") ||
+        msg.includes("not connected") ||
+        msg.includes("terminated"));
+}
+/** Connect a server (or reuse the live cached client). Evicts on connect failure. */
+function getOrConnect(server, opts) {
+    const key = serverKey(server);
+    const existing = pool.get(key);
+    if (existing)
+        return existing.promise;
+    const promise = connectOneServer(server, opts);
+    const entry = { key, promise };
+    pool.set(key, entry);
+    // Cache a rejection only transiently: evict so the next turn retries rather
+    // than returning the same failed promise forever.
+    promise.catch(() => {
+        if (pool.get(key) === entry)
+            pool.delete(key);
+    });
+    return promise;
+}
+/**
+ * Wrap each tool's execute so a transport/connection failure evicts the pooled
+ * client (next turn reconnects). The MCP child may die after a successful
+ * connect; without this the dead client would be reused on every later turn.
+ */
+function wrapForSelfHeal(tools, key) {
+    const out = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        const base = tool.execute;
+        if (typeof base !== "function") {
+            out[name] = tool;
+            continue;
+        }
+        out[name] = {
+            ...tool,
+            execute: async (args, options) => {
+                try {
+                    return await base(args, options);
+                }
+                catch (e) {
+                    if (isConnectionError(e)) {
+                        console.error(`[mcp:pool] '${name}' hit a connection error — evicting cached client so the next turn reconnects`);
+                        evict(key);
+                    }
+                    throw e;
+                }
+            },
+        };
+    }
+    return out;
+}
+/**
+ * Acquire the tool set for `servers`, reusing pooled clients where possible.
+ * Mirrors buildMcpToolSet's parallel + partial-at-deadline contract, but only
+ * FIRST-connects can be slow — already-pooled servers resolve instantly. The
+ * returned bundle's `close()` is a no-op RELEASE: pooled clients stay alive for
+ * the next turn. Use closeAllMcpClients() for real teardown.
+ */
+export async function acquireMcpTools(servers, opts) {
+    const tools = {};
+    const errors = [];
+    const enabled = servers.filter((s) => s.enabled);
+    const slots = enabled.map((s) => ({ label: s.label, key: serverKey(s), done: false }));
+    const attempts = enabled.map((server, i) => {
+        const validation = validateMcpServerConfig(server);
+        if (!validation.ok) {
+            slots[i] = { ...slots[i], done: true, error: validation.error };
+            return Promise.resolve();
+        }
+        return getOrConnect(server, opts).then((result) => {
+            slots[i] = { ...slots[i], done: true, result };
+        }, (error) => {
+            slots[i] = { ...slots[i], done: true, error: error instanceof Error ? error.message : String(error) };
+        });
+    });
+    const deadlineMs = getMcpBuildDeadlineMs();
+    let deadlineTimer;
+    const deadline = new Promise((resolve) => {
+        deadlineTimer = setTimeout(resolve, deadlineMs);
+        deadlineTimer.unref?.();
+    });
+    await Promise.race([Promise.allSettled(attempts), deadline]);
+    if (deadlineTimer)
+        clearTimeout(deadlineTimer);
+    for (const slot of slots) {
+        if (slot.done) {
+            if (slot.error) {
+                errors.push(`${slot.label}: ${slot.error}`);
+            }
+            else if (slot.result) {
+                Object.assign(tools, wrapForSelfHeal(slot.result.tools, slot.key));
+            }
+        }
+        else {
+            // Still connecting at the deadline (a cold first-connect). It stays in the
+            // pool and will be ready for a later turn — just excluded from THIS turn.
+            errors.push(`${slot.label}: not ready within ${deadlineMs}ms (still connecting — available next turn)`);
+        }
+    }
+    if (errors.length > 0) {
+        console.error(`[mcp:pool] ${errors.length} server(s) unavailable this turn: ${errors.join(" | ")}`);
+    }
+    return {
+        tools,
+        errors,
+        // Release, not close: pooled clients persist across turns by design.
+        async close() { },
+    };
+}
+/**
+ * Fire-and-forget pre-connect: start connecting `servers` in the background so
+ * they are pooled BEFORE the first turn needs them. npx stdio servers
+ * (filesystem/memory) cold-start >2.5s and would otherwise miss the first turn's
+ * build deadline — warming them at startup means they're usually ready by the
+ * first prompt. No deadline, no return; per-turn acquireMcpTools reuses whatever
+ * has connected. Idempotent (cached entries are reused); a failed connect is
+ * evicted by getOrConnect so a real turn retries.
+ */
+export function warmMcpClients(servers) {
+    for (const s of servers) {
+        if (!s.enabled)
+            continue;
+        if (!validateMcpServerConfig(s).ok)
+            continue;
+        void getOrConnect(s).catch(() => {
+            /* warm is best-effort — the eviction in getOrConnect lets a real turn retry */
+        });
+    }
+}
+/** Tear down every pooled client. Call on orchestrator/process shutdown. */
+export async function closeAllMcpClients() {
+    const entries = [...pool.values()];
+    pool.clear();
+    await Promise.all(entries.map(async (e) => {
+        try {
+            const cs = await e.promise;
+            cs.cleanup?.();
+            await cs.client.close().catch(() => { });
+        }
+        catch {
+            /* a never-connected entry has nothing to close */
+        }
+    }));
+}
+/** Test-only: reset pool state between cases. */
+export function __resetMcpClientPoolForTests() {
+    pool.clear();
+}
+/** Test-only: number of pooled (connecting or connected) entries. */
+export function __mcpClientPoolSize() {
+    return pool.size;
+}
+//# sourceMappingURL=client-pool.js.map

package/dist/src/mcp/oauth-callback.js

@@ -1,7 +1,7 @@
 import http from "node:http";
 import { URL } from "node:url";
-const SUCCESS_HTML = `<!DOCTYPE html><html><body style="font-family:system-ui;text-align:center;padding:60px">
-<h2>Authorization successful</h2><p>You can close this tab and return to the terminal.</p>
+const SUCCESS_HTML = `<!DOCTYPE html><html><body style="font-family:system-ui;text-align:center;padding:60px">
+<h2>Authorization successful</h2><p>You can close this tab and return to the terminal.</p>
 </body></html>`;
 export function startOAuthCallbackServer(opts) {
     const callbackPath = opts.path ?? "/callback";

package/dist/src/mcp/parse-headers.test.js

@@ -2,19 +2,19 @@ import { describe, expect, it } from "vitest";
 import { parseEnvLines, parseHeaderLines } from "./parse-headers.js";
 describe("parseHeaderLines", () => {
     it("parses colon-separated headers and trims whitespace", () => {
-        expect(parseHeaderLines(`
-        Authorization: Bearer token
-        X-Trace-Id:  abc123
+        expect(parseHeaderLines(`
+        Authorization: Bearer token
+        X-Trace-Id:  abc123
       `)).toEqual({
             Authorization: "Bearer token",
             "X-Trace-Id": "abc123",
         });
     });
     it("ignores blank and malformed lines while preserving later colons in values", () => {
-        expect(parseHeaderLines(`
-        invalid
-        : missing-name
-        Host: example.com:443
+        expect(parseHeaderLines(`
+        invalid
+        : missing-name
+        Host: example.com:443
       `)).toEqual({
             Host: "example.com:443",
         });
@@ -22,19 +22,19 @@ describe("parseHeaderLines", () => {
 });
 describe("parseEnvLines", () => {
     it("parses equals-separated env assignments and trims whitespace", () => {
-        expect(parseEnvLines(`
-        API_KEY = secret
-        MODE= production
+        expect(parseEnvLines(`
+        API_KEY = secret
+        MODE= production
       `)).toEqual({
             API_KEY: "secret",
             MODE: "production",
         });
     });
     it("ignores blank and malformed lines while preserving later equals in values", () => {
-        expect(parseEnvLines(`
-        missing
-        = no-name
-        URL=https://example.com?a=b
+        expect(parseEnvLines(`
+        missing
+        = no-name
+        URL=https://example.com?a=b
       `)).toEqual({
             URL: "https://example.com?a=b",
         });