muonroi-cli 1.4.0 → 1.5.0

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",
         });

package/dist/src/mcp/runtime.d.ts

@@ -1,3 +1,4 @@
+import { type MCPClient } from "@ai-sdk/mcp";
 import type { ToolSet } from "ai";
 import type { McpServerConfig } from "../utils/settings.js";
 export interface McpToolBundle {
@@ -8,4 +9,31 @@ export interface McpToolBundle {
 export interface McpBuildOptions {
     onOAuthRequired?: (serverId: string, url: URL) => void;
 }
+/**
+ * Total wall-clock budget for building the MCP tool set. Servers connect in
+ * PARALLEL and whatever has connected by the deadline is returned; slower
+ * servers are reported in `.errors` (and closed if they connect late) instead
+ * of sinking the whole bundle. Default 2500ms; override with
+ * MUONROI_MCP_BUILD_DEADLINE_MS (500–20000).
+ *
+ * Phase 1c — the OLD design built servers SEQUENTIALLY under an outer race
+ * (message-processor) that discarded EVERYTHING on timeout, so one slow `npx`
+ * stdio spawn starved a fast HTTP server and left the agent blind to MCP tools
+ * that were actually reachable (live: muonroi-docs ~300ms dropped behind slow
+ * npx servers, session f6f7881a5fae). Parallel + partial-at-deadline fixes it.
+ */
+export declare function getMcpBuildDeadlineMs(): number;
+export interface ConnectedServer {
+    tools: ToolSet;
+    client: MCPClient;
+    /** OAuth provider teardown, when one was created for this server. */
+    cleanup?: () => void;
+}
+/**
+ * Connect ONE server and build its prefixed, output-capped tool set. Throws on
+ * any failure; the caller owns lifecycle of the returned client/cleanup.
+ * Exported so the cross-turn client pool (client-pool.ts) can reuse it as its
+ * connect primitive.
+ */
+export declare function connectOneServer(rawServer: McpServerConfig, opts?: McpBuildOptions): Promise<ConnectedServer>;
 export declare function buildMcpToolSet(servers: McpServerConfig[], opts?: McpBuildOptions): Promise<McpToolBundle>;

package/dist/src/mcp/runtime.js

@@ -82,70 +82,136 @@ function toTransport(server, authProvider) {
         ...(authProvider ? { authProvider: authProvider } : {}),
     };
 }
+/**
+ * Total wall-clock budget for building the MCP tool set. Servers connect in
+ * PARALLEL and whatever has connected by the deadline is returned; slower
+ * servers are reported in `.errors` (and closed if they connect late) instead
+ * of sinking the whole bundle. Default 2500ms; override with
+ * MUONROI_MCP_BUILD_DEADLINE_MS (500–20000).
+ *
+ * Phase 1c — the OLD design built servers SEQUENTIALLY under an outer race
+ * (message-processor) that discarded EVERYTHING on timeout, so one slow `npx`
+ * stdio spawn starved a fast HTTP server and left the agent blind to MCP tools
+ * that were actually reachable (live: muonroi-docs ~300ms dropped behind slow
+ * npx servers, session f6f7881a5fae). Parallel + partial-at-deadline fixes it.
+ */
+export function getMcpBuildDeadlineMs() {
+    const v = Number(process.env.MUONROI_MCP_BUILD_DEADLINE_MS);
+    if (Number.isFinite(v) && v >= 500 && v <= 20_000)
+        return v;
+    return 2500;
+}
+/**
+ * Connect ONE server and build its prefixed, output-capped tool set. Throws on
+ * any failure; the caller owns lifecycle of the returned client/cleanup.
+ * Exported so the cross-turn client pool (client-pool.ts) can reuse it as its
+ * connect primitive.
+ */
+export async function connectOneServer(rawServer, opts) {
+    // Hydrate env vars from the OS keychain before spawning — e.g. inject
+    // TAVILY_API_KEY for the tavily MCP if stored via the research-onboarding wizard.
+    const server = await hydrateServerEnv(rawServer);
+    let authProvider;
+    let cleanup;
+    if (server.transport !== "stdio" && opts?.onOAuthRequired) {
+        const oauthResult = await createOAuthProviderWithCallback({
+            serverId: server.id,
+            onAuthorizationUrl: (url) => opts.onOAuthRequired(server.id, url),
+        });
+        authProvider = oauthResult.provider;
+        cleanup = oauthResult.close;
+    }
+    const client = await createMCPClient({
+        transport: toTransport(server, authProvider),
+        name: `muonroi-cli-${server.id}`,
+        version: "1.0.0",
+    });
+    const mcpTools = await client.tools();
+    const prefix = mcpToolPrefix(server);
+    const tools = {};
+    for (const [name, tool] of Object.entries(mcpTools)) {
+        // OpenAI/DeepSeek function-name regex: ^[a-zA-Z0-9_-]+$. MCP spec does not
+        // restrict server-side tool names, so we sanitize here. The tool's execute()
+        // closure still calls the MCP server with the original name.
+        const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+        const prefixedName = `${prefix}__${safeName}`;
+        const stripped = stripMcpInputSchema(tool);
+        // Cap MCP tool output the same way built-in tools are capped so the raw
+        // server payload doesn't stream into context uncapped. See cap-tool-result.ts.
+        const baseExecute = stripped.execute;
+        tools[prefixedName] = {
+            ...stripped,
+            description: `[MCP ${server.label}] ${tool.description ?? name}`,
+            ...(typeof baseExecute === "function"
+                ? { execute: async (args, options) => capMcpToolResult(await baseExecute(args, options)) }
+                : {}),
+        };
+    }
+    return { tools, client, cleanup };
+}
 export async function buildMcpToolSet(servers, opts) {
     const tools = {};
     const errors = [];
     const clients = [];
     const cleanups = [];
-    for (const rawServer of servers) {
-        if (!rawServer.enabled)
-            continue;
+    const enabled = servers.filter((s) => s.enabled);
+    const slots = enabled.map((s) => ({ label: s.label, done: false }));
+    const attempts = enabled.map((rawServer, i) => {
         const validation = validateMcpServerConfig(rawServer);
         if (!validation.ok) {
-            errors.push(`${rawServer.label}: ${validation.error}`);
-            continue;
+            slots[i] = { label: rawServer.label, done: true, error: validation.error };
+            return Promise.resolve();
         }
-        try {
-            // Hydrate env vars from the OS keychain before spawning — e.g. inject
-            // TAVILY_API_KEY for the tavily MCP if the user stored it via the
-            // research-onboarding wizard.
-            const server = await hydrateServerEnv(rawServer);
-            let authProvider;
-            if (server.transport !== "stdio" && opts?.onOAuthRequired) {
-                const oauthResult = await createOAuthProviderWithCallback({
-                    serverId: server.id,
-                    onAuthorizationUrl: (url) => opts.onOAuthRequired(server.id, url),
-                });
-                authProvider = oauthResult.provider;
-                cleanups.push(oauthResult.close);
+        return connectOneServer(rawServer, opts).then((result) => {
+            slots[i] = { label: rawServer.label, done: true, result };
+        }, (error) => {
+            slots[i] = {
+                label: rawServer.label,
+                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 (let i = 0; i < slots.length; i++) {
+        const slot = slots[i];
+        if (slot.done) {
+            if (slot.error) {
+                errors.push(`${slot.label}: ${slot.error}`);
             }
-            const client = await createMCPClient({
-                transport: toTransport(server, authProvider),
-                name: `muonroi-cli-${server.id}`,
-                version: "1.0.0",
-            });
-            clients.push(client);
-            const mcpTools = await client.tools();
-            const prefix = mcpToolPrefix(server);
-            for (const [name, tool] of Object.entries(mcpTools)) {
-                // OpenAI/DeepSeek function-name regex: ^[a-zA-Z0-9_-]+$. MCP spec
-                // does not restrict server-side tool names, so we sanitize here.
-                // The tool's execute() closure still calls the MCP server with the
-                // original name — we only rename what the LLM sees.
-                const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
-                const prefixedName = `${prefix}__${safeName}`;
-                const stripped = stripMcpInputSchema(tool);
-                // Cap MCP tool output the same way built-in tools are capped
-                // (`truncateOutput` / MAX_TOOL_OUTPUT_CHARS). Without this wrap the raw
-                // server payload streams into the model context uncapped — a cost leak
-                // that hits cheap models hardest. See cap-tool-result.ts.
-                const baseExecute = stripped.execute;
-                tools[prefixedName] = {
-                    ...stripped,
-                    description: `[MCP ${server.label}] ${tool.description ?? name}`,
-                    ...(typeof baseExecute === "function"
-                        ? {
-                            execute: async (args, options) => capMcpToolResult(await baseExecute(args, options)),
-                        }
-                        : {}),
-                };
+            else if (slot.result) {
+                Object.assign(tools, slot.result.tools);
+                clients.push(slot.result.client);
+                if (slot.result.cleanup)
+                    cleanups.push(slot.result.cleanup);
             }
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            errors.push(`${rawServer.label}: ${message}`);
+        else {
+            // Still connecting at the deadline: report it and close it if/when it
+            // eventually connects so the child process / socket doesn't leak.
+            errors.push(`${slot.label}: not ready within ${deadlineMs}ms (slow MCP server — excluded this turn)`);
+            void attempts[i]?.then(() => {
+                const late = slots[i]?.result;
+                if (late) {
+                    late.cleanup?.();
+                    void late.client.close().catch(() => { });
+                }
+            });
         }
     }
+    // Surface (not swallow) any server that didn't make it — never silently
+    // degrade to "builtins only" without a trace.
+    if (errors.length > 0) {
+        console.error(`[MCP] ${errors.length} server(s) unavailable this turn: ${errors.join(" | ")}`);
+    }
     return {
         tools,
         errors,

package/dist/src/mcp/self-verify-runner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * src/mcp/self-verify-runner.ts
+ *
+ * The default self-verify Runner (drives runSelfVerify / runAgenticLoop in
+ * process) plus a process-shared JobManager singleton. Shared by BOTH surfaces:
+ * the native in-CLI selfverify_* builtins (src/tools/native-tools.ts) and the
+ * muonroi-tools MCP server (src/mcp/tools-server.ts, for external agents) — so a
+ * run started on either surface is visible to both, and there is one job space.
+ */
+import { JobManager, type Runner } from "./self-verify-jobs.js";
+/** Default runner: drives the real self-verify functions in-process. */
+export declare const defaultRunner: Runner;
+/** Process-shared self-verify JobManager (created lazily on first use). */
+export declare function getSelfVerifyJobManager(): JobManager;

package/dist/src/mcp/self-verify-runner.js

@@ -0,0 +1,38 @@
+/**
+ * src/mcp/self-verify-runner.ts
+ *
+ * The default self-verify Runner (drives runSelfVerify / runAgenticLoop in
+ * process) plus a process-shared JobManager singleton. Shared by BOTH surfaces:
+ * the native in-CLI selfverify_* builtins (src/tools/native-tools.ts) and the
+ * muonroi-tools MCP server (src/mcp/tools-server.ts, for external agents) — so a
+ * run started on either surface is visible to both, and there is one job space.
+ */
+import { JobManager } from "./self-verify-jobs.js";
+/** Default runner: drives the real self-verify functions in-process. */
+export const defaultRunner = {
+    async tier1(opts, log) {
+        // signal intentionally not forwarded: runSelfVerify/runAgenticLoop do not yet
+        // accept an AbortSignal. cancel() marks the job and discards the late result.
+        const { runSelfVerify } = await import("../self-qa/index.js");
+        return runSelfVerify({
+            baseRef: opts.since,
+            maxScenarios: opts.max,
+            emitSpecs: opts.emit,
+            specOutDir: opts.out,
+            log,
+        });
+    },
+    async agentic(opts, log) {
+        const { createLLMBrain, runAgenticLoop } = await import("../self-qa/agentic-loop.js");
+        const brain = await createLLMBrain({ modelId: opts.llm });
+        return runAgenticLoop({ goal: opts.goal, brain, maxTurns: opts.turns ?? 20, log });
+    },
+};
+let shared = null;
+/** Process-shared self-verify JobManager (created lazily on first use). */
+export function getSelfVerifyJobManager() {
+    if (!shared)
+        shared = new JobManager(defaultRunner);
+    return shared;
+}
+//# sourceMappingURL=self-verify-runner.js.map

package/dist/src/mcp/setup-guide-text.d.ts

@@ -0,0 +1,9 @@
+/**
+ * src/mcp/setup-guide-text.ts
+ *
+ * Single source of the muonroi-cli setup guide, shared by BOTH surfaces that
+ * expose it: the native in-CLI `setup_guide` builtin (src/tools/native-tools.ts)
+ * and the muonroi-tools MCP server (src/mcp/tools-server.ts, for external agents).
+ * Keeping it here avoids duplicating ~70 lines across the two.
+ */
+export declare const SETUP_GUIDE_TEXT = "# muonroi-cli Setup Guide\n\n## Install (zero runtime deps \u2014 recommended)\nLinux / macOS:\n  curl -fsSL https://raw.githubusercontent.com/muonroi/muonroi-cli/master/install.sh | bash\n\nWindows PowerShell:\n  irm https://raw.githubusercontent.com/muonroi/muonroi-cli/master/install.ps1 | iex\n\nBun (requires Bun >= 1.3):\n  bun add -g muonroi-cli\n  # (npm install -g is NOT supported \u2014 TUI engine uses Bun-only ESM features)\n\nThe installers fetch a pre-compiled single binary from GitHub Releases.\n\n## First run\n- Wizard appears automatically.\n- Lists supported providers (DeepSeek + SiliconFlow ready; others via BYOK).\n- Four credential options: paste key, Bitwarden sync (B in /providers), keys export/import (encrypted bundle), or skip for later.\n- Keys land in OS keychain (keytar). Settings written to ~/.muonroi-cli/user-settings.json.\n- Role routing (leader/implement/verify/research) is configured for you.\n\nAfter setup: run `muonroi-cli doctor` to validate.\n\n## Essential commands\n- Interactive TUI: `muonroi-cli` (or `node dist/index.js` after build)\n- Headless one-shot: `muonroi-cli --prompt \"your task\" --max-tool-rounds 8`\n- Health + MCP nudge: `muonroi-cli doctor`\n- Update: `muonroi-cli update` (or set \"autoUpdate\": true in user-settings)\n- Keys move between machines: `muonroi-cli keys export file.json` then import on target\n- Native tools MCP (for external agents): `muonroi-cli tools-mcp` (stdio)\n- Harness driver MCP: `muonroi-cli mcp-driver`\n\n## MCP integration (for Claude Desktop, Cursor, other agents)\nAdd to your MCP client config:\n\n{\n  \"mcpServers\": {\n    \"muonroi-tools\": {\n      \"command\": \"bun\",\n      \"args\": [\"run\", \"/absolute/path/to/muonroi-cli/src/index.ts\", \"tools-mcp\"]\n    }\n  }\n}\n\n(Use absolute path. After `bun run build`: \"node\", \"dist/index.js\", \"tools-mcp\")\n\nThe CLI's OWN inner agent exposes these as NATIVE in-process tools (no MCP self-spawn):\n- setup_guide (this document)\n- ee_query / ee_health / ee_feedback \u2014 Experience Engine semantic recall + compaction checkpoints + feedback for learning\n- usage_forensics <id-prefix> \u2014 per-session cost/token forensics (peak input, cache hits, anomalies)\n- lsp_query \u2014 goToDefinition, findReferences, hover, symbols, call hierarchy etc.\n- selfverify_* \u2014 Tier-1 heuristic + Tier-2 agentic self-QA harness runs (start/poll/result/cancel/list)\n\nFor BB/.NET template recipes and package docs, also connect an external \"muonroi-docs\" MCP server if available (provides docs_search + setup_guide for the templates).\n\n## Development\ngit clone https://github.com/muonroi/muonroi-cli.git\ncd muonroi-cli && bun install\n\nbun run dev                 # run from source (TUI)\nbun run typecheck           # tsc --noEmit\nbun run test                # vitest (unit + headless)\nbunx vitest -c vitest.harness.config.ts run tests/harness/   # TUI E2E (named-pipes on Win, fd3/4 on POSIX)\nbun run build               # or build:binary for standalone exe\n\nSee AGENTS.md (quick ref + rules), CLAUDE.md (harness verification), README.md.\n\n## Verify\nmuonroi-cli doctor\n# Checks runtimes, catalog load, keychain, MCP servers enabled, council research MCP nudge, EE reachability, recent error rate.\n# Any \"warn\" entries tell you exactly what to enable (e.g. tavily for web research in council).\n\nFor BB-aware scaffolding (/ideal on a muonroi-building-block target): ensure dotnet SDK + the three Muonroi.*.Template packages are installed via NuGet; doctor surfaces missing feed/template cases.\n";

package/dist/src/mcp/setup-guide-text.js

@@ -0,0 +1,84 @@
+/**
+ * src/mcp/setup-guide-text.ts
+ *
+ * Single source of the muonroi-cli setup guide, shared by BOTH surfaces that
+ * expose it: the native in-CLI `setup_guide` builtin (src/tools/native-tools.ts)
+ * and the muonroi-tools MCP server (src/mcp/tools-server.ts, for external agents).
+ * Keeping it here avoids duplicating ~70 lines across the two.
+ */
+export const SETUP_GUIDE_TEXT = `# muonroi-cli Setup Guide
+
+## Install (zero runtime deps — recommended)
+Linux / macOS:
+  curl -fsSL https://raw.githubusercontent.com/muonroi/muonroi-cli/master/install.sh | bash
+
+Windows PowerShell:
+  irm https://raw.githubusercontent.com/muonroi/muonroi-cli/master/install.ps1 | iex
+
+Bun (requires Bun >= 1.3):
+  bun add -g muonroi-cli
+  # (npm install -g is NOT supported — TUI engine uses Bun-only ESM features)
+
+The installers fetch a pre-compiled single binary from GitHub Releases.
+
+## First run
+- Wizard appears automatically.
+- Lists supported providers (DeepSeek + SiliconFlow ready; others via BYOK).
+- Four credential options: paste key, Bitwarden sync (B in /providers), keys export/import (encrypted bundle), or skip for later.
+- Keys land in OS keychain (keytar). Settings written to ~/.muonroi-cli/user-settings.json.
+- Role routing (leader/implement/verify/research) is configured for you.
+
+After setup: run \`muonroi-cli doctor\` to validate.
+
+## Essential commands
+- Interactive TUI: \`muonroi-cli\` (or \`node dist/index.js\` after build)
+- Headless one-shot: \`muonroi-cli --prompt "your task" --max-tool-rounds 8\`
+- Health + MCP nudge: \`muonroi-cli doctor\`
+- Update: \`muonroi-cli update\` (or set "autoUpdate": true in user-settings)
+- Keys move between machines: \`muonroi-cli keys export file.json\` then import on target
+- Native tools MCP (for external agents): \`muonroi-cli tools-mcp\` (stdio)
+- Harness driver MCP: \`muonroi-cli mcp-driver\`
+
+## MCP integration (for Claude Desktop, Cursor, other agents)
+Add to your MCP client config:
+
+{
+  "mcpServers": {
+    "muonroi-tools": {
+      "command": "bun",
+      "args": ["run", "/absolute/path/to/muonroi-cli/src/index.ts", "tools-mcp"]
+    }
+  }
+}
+
+(Use absolute path. After \`bun run build\`: "node", "dist/index.js", "tools-mcp")
+
+The CLI's OWN inner agent exposes these as NATIVE in-process tools (no MCP self-spawn):
+- setup_guide (this document)
+- ee_query / ee_health / ee_feedback — Experience Engine semantic recall + compaction checkpoints + feedback for learning
+- usage_forensics <id-prefix> — per-session cost/token forensics (peak input, cache hits, anomalies)
+- lsp_query — goToDefinition, findReferences, hover, symbols, call hierarchy etc.
+- selfverify_* — Tier-1 heuristic + Tier-2 agentic self-QA harness runs (start/poll/result/cancel/list)
+
+For BB/.NET template recipes and package docs, also connect an external "muonroi-docs" MCP server if available (provides docs_search + setup_guide for the templates).
+
+## Development
+git clone https://github.com/muonroi/muonroi-cli.git
+cd muonroi-cli && bun install
+
+bun run dev                 # run from source (TUI)
+bun run typecheck           # tsc --noEmit
+bun run test                # vitest (unit + headless)
+bunx vitest -c vitest.harness.config.ts run tests/harness/   # TUI E2E (named-pipes on Win, fd3/4 on POSIX)
+bun run build               # or build:binary for standalone exe
+
+See AGENTS.md (quick ref + rules), CLAUDE.md (harness verification), README.md.
+
+## Verify
+muonroi-cli doctor
+# Checks runtimes, catalog load, keychain, MCP servers enabled, council research MCP nudge, EE reachability, recent error rate.
+# Any "warn" entries tell you exactly what to enable (e.g. tavily for web research in council).
+
+For BB-aware scaffolding (/ideal on a muonroi-building-block target): ensure dotnet SDK + the three Muonroi.*.Template packages are installed via NuGet; doctor surfaces missing feed/template cases.
+`;
+//# sourceMappingURL=setup-guide-text.js.map