muonroi-cli 1.4.1 → 1.6.0

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

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

@@ -47,6 +47,37 @@ function hasDocsSignal(message) {
     return (/https?:\/\/\S+/i.test(message) ||
         /\b(docs?|documentation|api|sdk|library|libraries|framework|package|npm|pip|cargo|crate|gem|maven|nuget|install|migrat\w*|changelog|release\s*notes?|reference|usage|fetch|download|http|web|google|search\s+(the\s+)?web|news|weather|headlines|look\s*up|online|internet)\b/i.test(message));
 }
+/**
+ * Matches a question ABOUT the Muonroi ecosystem — where muonroi-docs (the
+ * authoritative ecosystem source: BB/.NET recipes, package docs, open-core
+ * boundary) is exactly what's needed, even though the message carries no generic
+ * docs/api keyword. Deliberately ecosystem-specific so it only ever KEEPS
+ * muonroi-docs (never other docs servers). EN + VI.
+ */
+function hasEcosystemSignal(message) {
+    return /\bmuonroi\b|\becosystem\b|hệ\s*sinh\s*thái|he\s*sinh\s*thai|building[-\s]?block|\bbb\b|open[-\s]?core/i.test(message);
+}
+/**
+ * Explicit "use a tool / MCP tool" intent. The filter only sees server *ids*,
+ * not their tool lists (MCP tools are fetched lazily at build time), so when the
+ * user asks to call a specific tool by name we cannot tell which server owns it.
+ * Dropping any optional server then risks stripping the exact tool requested.
+ *
+ * Live miss (session f6f7881a5fae): "bạn thử call tool setup_guide ... ( call
+ * tool chứ không phải đọc code )" carried no docs keyword, so `muonroi-docs`
+ * (id matches /docs/) was dropped — the model had no `setup_guide` tool and
+ * resorted to driving the server by hand over bash JSON-RPC, fabricating output.
+ *
+ * When this fires we keep ALL optional servers for the turn. Over-keeping costs
+ * tokens but never removes capability — this module's documented safe direction.
+ * EN + VI: "call/use/invoke/run the X tool", "tool call", "gọi/dùng/chạy tool".
+ */
+function hasExplicitToolIntent(message) {
+    return (/\b(?:call|use|invoke|run|exercise|trigger|try)\s+(?:the\s+)?(?:mcp\s+)?(?:[a-z0-9_.-]+\s+)?tool(?:s)?\b/i.test(message) ||
+        /\btool[\s_-]?call\b/i.test(message) ||
+        /\bmcp\b[^\n]*\btool/i.test(message) ||
+        /\b(?:gọi|dùng|chạy|thử)\s+(?:tool|mcp)\b/i.test(message));
+}
 /**
  * Filesystem-MCP tool names that 1:1 duplicate a first-class BUILTIN file tool.
  * The builtin `read_file`/`write_file`/`edit_file` are strictly better (read-
@@ -102,9 +133,27 @@ export function dropRedundantFsMcpTools(mcpTools, builtinToolNames) {
 export function filterMcpServersByMessage(servers, userMessage, opts = {}) {
     if (opts.disabled)
         return servers;
+    // Explicit "call the X tool" intent → keep every server this turn. We can't map
+    // a named tool back to its server from config alone (tool lists load lazily),
+    // so dropping any optional server risks stripping the exact tool requested.
+    if (hasExplicitToolIntent(userMessage))
+        return servers;
     const browser = hasBrowserSignal(userMessage);
     const docs = hasDocsSignal(userMessage);
+    const ecosystem = hasEcosystemSignal(userMessage);
+    const lower = userMessage.toLowerCase();
     return servers.filter((s) => {
+        // A server named outright in the message ("check the muonroi-docs MCP") is
+        // always relevant — never let a category skip override an explicit mention.
+        if (s.id && lower.includes(s.id.toLowerCase()))
+            return true;
+        // muonroi-docs is the AUTHORITATIVE ecosystem source. A question about the
+        // Muonroi ecosystem ("hệ sinh thái muonroi", "building-block", "bb rule
+        // engine") matches no generic docs/api keyword, so SKIP_WHEN_NO_DOCS would
+        // wrongly drop it and the agent falls back to guessing from files (live
+        // session dbe408937a3d turn 1). Keep it whenever the turn is ecosystem-about.
+        if (ecosystem && /(^|[-_])docs([-_]|$)/.test(s.id) && /muonroi/i.test(s.id))
+            return true;
         if (!browser && SKIP_WHEN_NO_BROWSER.test(s.id))
             return false;
         if (!docs && SKIP_WHEN_NO_DOCS.test(s.id))

package/dist/src/mcp/smoke.test.js

@@ -86,49 +86,49 @@ describe("MCP smoke test — buildMcpToolSet", () => {
     it.skipIf(process.platform === "win32" || !!process.env.CI)("discovers tools from stdio MCP echo stub", async () => {
         // Inline MCP echo server script — handles initialize, notifications/initialized,
         // and tools/list using Content-Length framing per the MCP JSON-RPC spec.
-        const echoServerScript = `
-const { stdin, stdout } = require('process');
-let buf = '';
-stdin.setEncoding('utf8');
-stdin.on('data', (chunk) => {
-  buf += chunk;
-  while (true) {
-    const headerEnd = buf.indexOf('\\r\\n\\r\\n');
-    if (headerEnd === -1) break;
-    const header = buf.slice(0, headerEnd);
-    const match = header.match(/Content-Length:\\s*(\\d+)/i);
-    if (!match) { buf = buf.slice(headerEnd + 4); continue; }
-    const len = parseInt(match[1], 10);
-    const bodyStart = headerEnd + 4;
-    if (buf.length < bodyStart + len) break;
-    const body = buf.slice(bodyStart, bodyStart + len);
-    buf = buf.slice(bodyStart + len);
-    handleMessage(JSON.parse(body));
-  }
-});
-function send(obj) {
-  const s = JSON.stringify(obj);
-  stdout.write('Content-Length: ' + Buffer.byteLength(s) + '\\r\\n\\r\\n' + s);
-}
-function handleMessage(msg) {
-  if (msg.method === 'initialize') {
-    send({ jsonrpc: '2.0', id: msg.id, result: {
-      protocolVersion: '2024-11-05',
-      capabilities: { tools: { listChanged: false } },
-      serverInfo: { name: 'echo-stub', version: '1.0.0' }
-    }});
-  } else if (msg.method === 'notifications/initialized') {
-    // no response needed
-  } else if (msg.method === 'tools/list') {
-    send({ jsonrpc: '2.0', id: msg.id, result: {
-      tools: [{
-        name: 'echo',
-        description: 'Echoes input',
-        inputSchema: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] }
-      }]
-    }});
-  }
-}
+        const echoServerScript = `
+const { stdin, stdout } = require('process');
+let buf = '';
+stdin.setEncoding('utf8');
+stdin.on('data', (chunk) => {
+  buf += chunk;
+  while (true) {
+    const headerEnd = buf.indexOf('\\r\\n\\r\\n');
+    if (headerEnd === -1) break;
+    const header = buf.slice(0, headerEnd);
+    const match = header.match(/Content-Length:\\s*(\\d+)/i);
+    if (!match) { buf = buf.slice(headerEnd + 4); continue; }
+    const len = parseInt(match[1], 10);
+    const bodyStart = headerEnd + 4;
+    if (buf.length < bodyStart + len) break;
+    const body = buf.slice(bodyStart, bodyStart + len);
+    buf = buf.slice(bodyStart + len);
+    handleMessage(JSON.parse(body));
+  }
+});
+function send(obj) {
+  const s = JSON.stringify(obj);
+  stdout.write('Content-Length: ' + Buffer.byteLength(s) + '\\r\\n\\r\\n' + s);
+}
+function handleMessage(msg) {
+  if (msg.method === 'initialize') {
+    send({ jsonrpc: '2.0', id: msg.id, result: {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: 'echo-stub', version: '1.0.0' }
+    }});
+  } else if (msg.method === 'notifications/initialized') {
+    // no response needed
+  } else if (msg.method === 'tools/list') {
+    send({ jsonrpc: '2.0', id: msg.id, result: {
+      tools: [{
+        name: 'echo',
+        description: 'Echoes input',
+        inputSchema: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] }
+      }]
+    }});
+  }
+}
 `;
         const tmpDir = await mkdtemp(join(tmpdir(), "mcp-echo-stub-"));
         const scriptPath = join(tmpDir, "echo-server.js");

package/dist/src/mcp/tools-server.d.ts

@@ -6,9 +6,16 @@
  * immediately; poll with selfverify.status; fetch selfverify.result when done.
  *
  * Lives at the app layer (NOT agent-harness-core) so it may import src/self-qa.
+ *
+ * NOTE: this server is for EXTERNAL agents (Claude Code etc.). The CLI's OWN
+ * inner agent now exposes the same capabilities as NATIVE in-process builtins
+ * (src/tools/native-tools.ts) — it no longer self-spawns this server. The two
+ * surfaces share their cores (self-verify-runner.ts, setup-guide-text.ts, the
+ * ee/forensics/lsp modules) so behaviour is identical.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { JobManager, type Runner } from "./self-verify-jobs.js";
 export declare function registerSelfVerifyTools(server: McpServer, jm: JobManager): void;
+export declare function registerSetupGuideTool(server: McpServer): void;
 export declare function createToolsServer(runner?: Runner): McpServer;
 export declare function runToolsMcpServer(): Promise<void>;

package/dist/src/mcp/tools-server.js

@@ -6,6 +6,12 @@
  * immediately; poll with selfverify.status; fetch selfverify.result when done.
  *
  * Lives at the app layer (NOT agent-harness-core) so it may import src/self-qa.
+ *
+ * NOTE: this server is for EXTERNAL agents (Claude Code etc.). The CLI's OWN
+ * inner agent now exposes the same capabilities as NATIVE in-process builtins
+ * (src/tools/native-tools.ts) — it no longer self-spawns this server. The two
+ * surfaces share their cores (self-verify-runner.ts, setup-guide-text.ts, the
+ * ee/forensics/lsp modules) so behaviour is identical.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -14,29 +20,9 @@ import { registerEETools } from "./ee-tools.js";
 import { registerForensicsTools } from "./forensics-tools.js";
 import { registerLspTools } from "./lsp-tools.js";
 import { JobManager } from "./self-verify-jobs.js";
+import { defaultRunner } from "./self-verify-runner.js";
+import { SETUP_GUIDE_TEXT } from "./setup-guide-text.js";
 const LOG_TAIL = 40;
-/** Default runner: drives the real self-verify functions in-process. */
-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) {
-        // signal intentionally not forwarded: runSelfVerify/runAgenticLoop do not yet
-        // accept an AbortSignal. cancel() marks the job and discards the late result.
-        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 });
-    },
-};
 function ok(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
@@ -129,6 +115,16 @@ export function registerSelfVerifyTools(server, jm) {
     });
     server.registerTool("selfverify_cancel", { description: "Cancel a running self-verify run (best-effort).", inputSchema: { runId: z.string() } }, async ({ runId }) => ok({ cancelled: jm.cancel(runId) }));
 }
+export function registerSetupGuideTool(server) {
+    server.registerTool("setup_guide", {
+        description: "Returns a concise, up-to-date setup, install, first-run, MCP wiring, and verification guide for muonroi-cli. " +
+            "Call this directly (setup_guide) when the user asks for setup instructions, onboarding, or 'how do I start' — " +
+            "instead of guessing, reading files, or shelling commands. Keeps agents on the happy path.",
+        inputSchema: {},
+    }, async () => {
+        return { content: [{ type: "text", text: SETUP_GUIDE_TEXT }] };
+    });
+}
 export function createToolsServer(runner = defaultRunner) {
     const server = new McpServer({ name: "muonroi-tools", version: "0.1.0" });
     const jm = new JobManager(runner);
@@ -136,6 +132,7 @@ export function createToolsServer(runner = defaultRunner) {
     registerEETools(server);
     registerForensicsTools(server);
     registerLspTools(server);
+    registerSetupGuideTool(server);
     return server;
 }
 export async function runToolsMcpServer() {