muonroi-cli 1.4.0 → 1.5.0

package/dist/src/headless/output.js

@@ -5,10 +5,12 @@ export function renderHeadlessPrelude(format, sessionId) {
     if (format === "json") {
         return {};
     }
-    return {
-        stdout: "\x1b[36m⏳ Processing...\x1b[0m\n",
-        stderr: sessionId ? `\x1b[2mSession: ${sessionId}\x1b[0m\n` : undefined,
-    };
+    // Status indicator + session id are progress UX, not the reply. Keep stdout
+    // pure (only the model's answer) so `--format text` pipes cleanly. VERIFY F3.
+    const statusLines = ["\x1b[36m⏳ Processing...\x1b[0m"];
+    if (sessionId)
+        statusLines.push(`\x1b[2mSession: ${sessionId}\x1b[0m`);
+    return { stderr: `${statusLines.join("\n")}\n` };
 }
 /**
  * Headless text output only. JSON streaming uses {@link createHeadlessJsonlEmitter} + `Agent.processMessage` observer.

package/dist/src/headless/output.test.js

@@ -25,10 +25,11 @@ describe("headless output helpers", () => {
         expect(isHeadlessOutputFormat("json")).toBe(true);
         expect(isHeadlessOutputFormat("xml")).toBe(false);
     });
-    it("renders the text prelude with session metadata", () => {
+    it("renders the text prelude with status on stderr (stdout stays pure for piping)", () => {
+        // VERIFY F3: spinner + session id are progress UX, not the reply — both go
+        // to stderr so `--format text` stdout contains only the model's answer.
         expect(renderHeadlessPrelude("text", "session-123")).toEqual({
-            stdout: "\u001b[36m⏳ Processing...\u001b[0m\n",
-            stderr: "\u001b[2mSession: session-123\u001b[0m\n",
+            stderr: "⏳ Processing...\nSession: session-123\n",
         });
     });
     it("suppresses the prelude in json mode", () => {

package/dist/src/index.js

@@ -982,8 +982,27 @@ program
         }
     }
     // Bootstrap EE auth (loads serverBaseUrl + token from ~/.experience/config.json)
-    const { loadEEAuthToken } = await import("./ee/auth.js");
+    const { loadEEAuthToken, getCachedServerBaseUrl } = await import("./ee/auth.js");
     await loadEEAuthToken().catch(() => { });
+    // First-run EE setup (interactive, once per install): if no EE server is
+    // configured, offer to connect one + write ~/.experience/config.json so the
+    // agent's record/recall/feedback loop has a brain. One-time, flag-gated.
+    if (isInteractive) {
+        try {
+            const { loadUserSettings, saveUserSettings } = await import("./utils/settings.js");
+            if (loadUserSettings().eeSetupPrompted !== true && !getCachedServerBaseUrl()) {
+                const { firstRunEESetup } = await import("./ee/ee-onboarding.js");
+                const wrote = await firstRunEESetup();
+                if (wrote)
+                    await loadEEAuthToken().catch(() => { });
+                saveUserSettings({ eeSetupPrompted: true });
+            }
+        }
+        catch (err) {
+            if (process.env.MUONROI_DEBUG)
+                console.error(`[muonroi-cli] EE first-run setup skipped: ${err?.message}`);
+        }
+    }
     // Auto-detect EE client mode (thin / thin-degraded / fat / disabled).
     // Result is cached for downstream callsites (PIL layers, bridge.searchByText)
     // so each request doesn't re-probe.

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

@@ -33,6 +33,80 @@ describe("ensureDefaultMcpServers — research servers", () => {
         expect(ids).toContain("fetch");
         expect(ids).toContain("tavily");
     });
+    it("registers muonroi-docs as a default, enabled, http ecosystem source", async () => {
+        const { ensureDefaultMcpServers } = await import("../auto-setup.js");
+        const merged = ensureDefaultMcpServers();
+        const docs = merged.find((s) => s.id === "muonroi-docs");
+        expect(docs).toBeDefined();
+        expect(docs?.enabled).toBe(true);
+        expect(docs?.transport).toBe("http");
+        expect(docs?.url).toContain("docs-mcp.muonroi.com");
+    });
+    it("does NOT register muonroi-tools (its tools are native in-process builtins now)", async () => {
+        // The CLI no longer self-spawns itself as an MCP server. ee_query/ee_feedback/
+        // ee_health/usage_forensics/lsp_query/setup_guide/selfverify_* are native
+        // builtins (src/tools/native-tools.ts) — strictly better than a per-turn
+        // subprocess cold-start. So muonroi-tools must NOT be seeded.
+        const { ensureDefaultMcpServers } = await import("../auto-setup.js");
+        const merged = ensureDefaultMcpServers();
+        expect(merged.find((s) => s.id === "muonroi-tools")).toBeUndefined();
+    });
+    it("removes an existing self-spawned muonroi-tools entry (incl. an old vitest-worker-poisoned one)", async () => {
+        const settingsPath = path.join(tmpHome, ".muonroi-cli", "user-settings.json");
+        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+        fs.writeFileSync(settingsPath, JSON.stringify({
+            mcp: {
+                servers: [
+                    {
+                        id: "muonroi-tools",
+                        label: "muonroi-tools (Experience + Self-Diagnostics)",
+                        enabled: true,
+                        transport: "stdio",
+                        command: "C:\\Program Files\\nodejs\\node.exe",
+                        args: [
+                            "D:\\repo\\node_modules\\.bun\\vitest@4.1.5\\node_modules\\vitest\\dist\\workers\\forks.js",
+                            "tools-mcp",
+                        ],
+                    },
+                ],
+            },
+        }));
+        const { ensureDefaultMcpServers } = await import("../auto-setup.js");
+        const merged = ensureDefaultMcpServers();
+        // Deprecated self-spawn stripped; no vitest worker path survives.
+        expect(merged.find((s) => s.id === "muonroi-tools")).toBeUndefined();
+        expect(JSON.stringify(merged)).not.toMatch(/vitest|forks\.js/);
+    });
+    it("removes a self-spawned muonroi-tools entry even with a valid bun-source command", async () => {
+        const settingsPath = path.join(tmpHome, ".muonroi-cli", "user-settings.json");
+        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+        fs.writeFileSync(settingsPath, JSON.stringify({
+            mcp: {
+                servers: [
+                    {
+                        id: "muonroi-tools",
+                        label: "muonroi-tools",
+                        enabled: true,
+                        transport: "stdio",
+                        command: "bun",
+                        args: ["/repo/src/index.ts", "tools-mcp"],
+                    },
+                    {
+                        id: "context7",
+                        label: "Context7",
+                        enabled: true,
+                        transport: "http",
+                        url: "https://mcp.context7.com/mcp",
+                    },
+                ],
+            },
+        }));
+        const { ensureDefaultMcpServers } = await import("../auto-setup.js");
+        const merged = ensureDefaultMcpServers();
+        expect(merged.find((s) => s.id === "muonroi-tools")).toBeUndefined();
+        // Unrelated user server preserved.
+        expect(merged.find((s) => s.id === "context7")).toBeDefined();
+    });
     it("context7 and fetch default to enabled", async () => {
         const { ensureDefaultMcpServers } = await import("../auto-setup.js");
         const merged = ensureDefaultMcpServers();

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

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

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;