@ouro.bot/cli 0.1.0-alpha.66 → 0.1.0-alpha.661

package/dist/repertoire/mcp-manager.js

@@ -0,0 +1,434 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpManager = void 0;
+exports.getSharedMcpManager = getSharedMcpManager;
+exports.shutdownSharedMcpManager = shutdownSharedMcpManager;
+exports.resetSharedMcpManager = resetSharedMcpManager;
+const mcp_client_1 = require("./mcp-client");
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const credential_access_1 = require("./credential-access");
+const plugin_mcp_1 = require("./plugin-mcp");
+const MAX_RESTART_RETRIES = 5;
+const RESTART_DELAY_MS = 1000;
+/**
+ * Merge builtin (agent.json mcpServers) + plugin-declared (.mcp.json) servers.
+ *
+ * Builtin wins on name collision. Returns the merged config map plus a
+ * `pluginOrigins` map (server-name → plugin-id) for tools-surfacing namespace.
+ *
+ * Shared by `getSharedMcpManager()` (initial start) and `McpManager.reconcile()`
+ * (re-read on each turn). Both code paths MUST use the same merge logic — if
+ * reconcile reads only builtin, plugin servers get classified as "removed"
+ * on the second turn and torn down. See alpha.635 fix.
+ *
+ * `runtimeServers` are per-turn, per-agent overrides (e.g. Workbench's
+ * `ouro_workbench`) supplied as PARAMETER data for the current turn — never read
+ * from module state. They merge with the HIGHEST precedence (after builtin), so
+ * a stale `agent.json` entry loses to the live runtime path. Because they are a
+ * parameter, a turn that omits them produces a merged set WITHOUT them, and
+ * `reconcile()` then tears the runtime server down — this is the no-leak
+ * invariant that keeps the runtime MCP from bleeding into a different agent's
+ * concurrent turn on the shared daemon.
+ */
+function buildMergedServerConfig(runtimeServers) {
+    const config = (0, identity_1.loadAgentConfig)();
+    const builtinServers = config.mcpServers ?? {};
+    const pluginServers = (0, plugin_mcp_1.listPluginMcpServers)();
+    const mergedServers = {};
+    const pluginOrigins = {};
+    for (const p of pluginServers) {
+        if (builtinServers[p.serverName] !== undefined)
+            continue;
+        mergedServers[p.serverName] = (0, plugin_mcp_1.pluginMcpServerToConfig)(p);
+        pluginOrigins[p.serverName] = p.pluginId;
+    }
+    for (const [name, cfg] of Object.entries(builtinServers)) {
+        mergedServers[name] = cfg;
+    }
+    // Runtime overrides win over both plugin and builtin (highest precedence).
+    // They are NOT recorded in pluginOrigins, so they surface as builtin-style
+    // (un-namespaced) tools — matching how an agent.json mcpServers entry would.
+    if (runtimeServers) {
+        for (const [name, cfg] of Object.entries(runtimeServers)) {
+            mergedServers[name] = cfg;
+            delete pluginOrigins[name];
+        }
+    }
+    return { mergedServers, pluginOrigins };
+}
+class McpManager {
+    servers = new Map();
+    shuttingDown = false;
+    async start(servers, pluginOrigins = {}) {
+        (0, runtime_1.emitNervesEvent)({
+            event: "mcp.manager_start",
+            component: "repertoire",
+            message: "starting MCP manager",
+            meta: {
+                serverCount: Object.keys(servers).length,
+                pluginServerCount: Object.keys(pluginOrigins).length,
+            },
+        });
+        const entries = Object.entries(servers);
+        for (const [name, config] of entries) {
+            await this.connectServer(name, config, pluginOrigins[name]);
+        }
+    }
+    listAllTools() {
+        const result = [];
+        for (const [name, entry] of this.servers) {
+            result.push({ server: name, tools: entry.cachedTools, pluginId: entry.pluginId });
+        }
+        return result;
+    }
+    async callTool(server, tool, args) {
+        let entry = this.servers.get(server);
+        if (!entry) {
+            throw new Error(`Unknown server: ${server}`);
+        }
+        if (!entry.client.isConnected()) {
+            await this.recoverStaleTransport(server, "pre-call disconnected");
+            entry = this.servers.get(server);
+            if (!entry?.client.isConnected()) {
+                throw new Error(`Server "${server}" is disconnected`);
+            }
+        }
+        try {
+            return await entry.client.callTool(tool, args);
+        }
+        catch (error) {
+            if (!(0, mcp_client_1.isMcpTransportError)(error)) {
+                throw error;
+            }
+            const reason = error instanceof Error ? error.message : String(error);
+            await this.recoverStaleTransport(server, reason);
+            const recovered = this.servers.get(server);
+            if (!recovered?.client.isConnected()) {
+                throw new Error(`Server "${server}" is disconnected after recovery: ${reason}`);
+            }
+            return recovered.client.callTool(tool, args);
+        }
+    }
+    async runCanaries() {
+        const results = [];
+        for (const [server, entry] of [...this.servers]) {
+            try {
+                if (!entry.client.isConnected()) {
+                    await this.recoverStaleTransport(server, "canary disconnected");
+                }
+                const current = this.servers.get(server);
+                if (!current?.client.isConnected()) {
+                    results.push({ server, ok: false, detail: "disconnected after recovery attempt" });
+                    continue;
+                }
+                const tools = await current.client.refreshTools();
+                current.cachedTools = tools;
+                current.consecutiveFailures = 0;
+                results.push({ server, ok: true, detail: `${tools.length} tools listed` });
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                if ((0, mcp_client_1.isMcpTransportError)(error)) {
+                    await this.recoverStaleTransport(server, reason);
+                }
+                results.push({ server, ok: false, detail: reason });
+            }
+        }
+        return results;
+    }
+    /** Re-read agent config AND enabled-plugin .mcp.json files, then connect new
+     *  servers / disconnect removed ones. Must include plugin-declared servers
+     *  in the desired set — otherwise plugin servers (e.g. mcp__desk__*) are
+     *  treated as "removed" on every call and get torn down between turns.
+     *
+     *  `runtimeServers` are the current turn's per-agent overrides. They MUST be
+     *  passed on every reconcile for the agent that owns them, otherwise the
+     *  runtime server (e.g. ouro_workbench) is classified as "removed" and torn
+     *  down — which is exactly the desired no-leak behavior for a turn that omits
+     *  them. */
+    async reconcile(runtimeServers) {
+        try {
+            const { mergedServers, pluginOrigins } = buildMergedServerConfig(runtimeServers);
+            const currentNames = new Set(this.servers.keys());
+            const desiredNames = new Set(Object.keys(mergedServers));
+            // Connect new servers
+            for (const [name, cfg] of Object.entries(mergedServers)) {
+                if (!currentNames.has(name)) {
+                    (0, runtime_1.emitNervesEvent)({
+                        event: "mcp.server_added",
+                        component: "repertoire",
+                        message: `connecting new MCP server: ${name}`,
+                        meta: { server: name, command: cfg.command },
+                    });
+                    await this.connectServer(name, cfg, pluginOrigins[name]);
+                }
+            }
+            // Disconnect removed servers
+            for (const name of currentNames) {
+                if (!desiredNames.has(name)) {
+                    (0, runtime_1.emitNervesEvent)({
+                        event: "mcp.server_removed",
+                        component: "repertoire",
+                        message: `disconnecting removed MCP server: ${name}`,
+                        meta: { server: name },
+                    });
+                    const entry = this.servers.get(name);
+                    /* v8 ignore next -- defensive: name comes from this.servers.keys() this same tick, so entry is always present; the guard only protects against an awaited connectServer crash-handler racing a delete @preserve */
+                    if (entry)
+                        entry.client.shutdown();
+                    this.servers.delete(name);
+                }
+            }
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                event: "mcp.reconcile_error",
+                component: "repertoire",
+                message: "failed to reconcile MCP servers",
+                meta: { reason: error instanceof Error ? error.message : String(error) },
+            });
+        }
+    }
+    shutdown() {
+        this.shuttingDown = true;
+        // `_end` (not `_stop`) to pair with `mcp.manager_start` under the
+        // nerves audit start/end pairing rule.
+        (0, runtime_1.emitNervesEvent)({
+            event: "mcp.manager_end",
+            component: "repertoire",
+            message: "shutting down MCP manager",
+            meta: { serverCount: this.servers.size },
+        });
+        for (const [, entry] of this.servers) {
+            entry.client.shutdown();
+        }
+        this.servers.clear();
+    }
+    /**
+     * Resolve `vault:DOMAIN/FIELD` references in server env config.
+     * Returns resolved env or throws with a descriptive error.
+     */
+    async resolveVaultEnv(_serverName, env) {
+        const resolved = { ...env };
+        // Short-circuit: only spin up a credential store if at least one env value
+        // actually requests vault resolution. Plugin MCP servers commonly ship with
+        // `env: {}` or pure-string envs, and we shouldn't pay the credential-store
+        // boot cost (or fail in test envs that have no vault) for those cases.
+        const hasVaultRef = Object.values(resolved).some((v) => /^vault:/.test(v));
+        if (!hasVaultRef)
+            return resolved;
+        const store = (0, credential_access_1.getCredentialStore)();
+        for (const [key, value] of Object.entries(resolved)) {
+            const match = value.match(/^vault:([^/]+)\/(.+)$/);
+            if (!match)
+                continue;
+            const [, domain, field] = match;
+            try {
+                resolved[key] = await store.getRawSecret(domain, field);
+            }
+            catch (err) {
+                /* v8 ignore next -- reason @preserve */
+                const reason = err instanceof Error ? err.message : String(err);
+                // Classify the error for actionable messaging
+                let classification = "vault unreachable";
+                if (reason.includes("no credential found")) {
+                    classification = "item not found";
+                }
+                else if (reason.includes("field") && reason.includes("not found")) {
+                    classification = "field empty";
+                }
+                throw new Error(`vault:${domain}/${field} could not be resolved: ${classification}`);
+            }
+        }
+        return resolved;
+    }
+    async connectServer(name, config, pluginId) {
+        // Resolve vault: references in env before spawning
+        let resolvedConfig = config;
+        if (config.env) {
+            try {
+                const resolvedEnv = await this.resolveVaultEnv(name, config.env);
+                resolvedConfig = { ...config, env: resolvedEnv };
+            }
+            catch (err) {
+                /* v8 ignore next -- reason @preserve */
+                const reason = err instanceof Error ? err.message : String(err);
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    event: "mcp.vault_resolve_error",
+                    component: "repertoire",
+                    message: `skipping MCP server "${name}": ${reason}`,
+                    meta: { server: name, reason },
+                });
+                return; // Skip this server, continue to next
+            }
+        }
+        const client = new mcp_client_1.McpClient(resolvedConfig);
+        const entry = {
+            name,
+            config,
+            client,
+            cachedTools: [],
+            consecutiveFailures: 0,
+            pluginId,
+        };
+        this.servers.set(name, entry);
+        client.onClose(() => {
+            if (this.shuttingDown)
+                return;
+            this.handleServerCrash(name);
+        });
+        try {
+            await client.connect();
+            const tools = await client.listTools();
+            entry.cachedTools = tools;
+            entry.consecutiveFailures = 0;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                event: "mcp.connect_error",
+                component: "repertoire",
+                message: `failed to connect MCP server "${name}" (command: ${config.command}). Check that the command exists and is properly configured. Reason: ${reason}`,
+                meta: {
+                    server: name,
+                    command: config.command,
+                    args: config.args,
+                    reason,
+                },
+            });
+        }
+    }
+    handleServerCrash(name) {
+        const entry = this.servers.get(name);
+        /* v8 ignore next -- defensive: entry removed between close event and handler @preserve */
+        if (!entry)
+            return;
+        entry.consecutiveFailures++;
+        if (entry.consecutiveFailures > MAX_RESTART_RETRIES) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                event: "mcp.connect_error",
+                component: "repertoire",
+                message: `MCP server "${name}" exceeded max restart retries (${MAX_RESTART_RETRIES}). Giving up — check that "${entry.config.command}" exists and is properly configured in agent.json mcpServers.`,
+                meta: { server: name, command: entry.config.command, failures: entry.consecutiveFailures },
+            });
+            return;
+        }
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            event: "mcp.server_restart",
+            component: "repertoire",
+            message: `restarting crashed MCP server: ${name}`,
+            meta: { server: name, attempt: entry.consecutiveFailures },
+        });
+        /* v8 ignore start -- timer callback: covered by mcp-manager.test.ts via fake timers but v8 can't trace @preserve */
+        setTimeout(() => {
+            if (this.shuttingDown)
+                return;
+            this.restartServer(name).catch(() => {
+                // Error handling is inside restartServer
+            });
+        }, RESTART_DELAY_MS);
+        /* v8 ignore stop */
+    }
+    /* v8 ignore start -- called from timer callback: covered by mcp-manager.test.ts via fake timers but v8 can't trace @preserve */
+    async restartServer(name) {
+        const entry = this.servers.get(name);
+        if (!entry)
+            return;
+        // Remove old entry and reconnect
+        this.servers.delete(name);
+        entry.client.shutdown();
+        await this.connectServer(name, entry.config);
+        // Preserve failure count
+        const newEntry = this.servers.get(name);
+        if (newEntry) {
+            newEntry.consecutiveFailures = entry.consecutiveFailures;
+        }
+    }
+    /* v8 ignore stop */
+    async recoverStaleTransport(name, reason) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            event: "mcp.transport_recovery",
+            component: "repertoire",
+            message: `recovering stale MCP transport: ${name}`,
+            meta: { server: name, reason },
+        });
+        await this.restartServer(name);
+    }
+}
+exports.McpManager = McpManager;
+let _sharedManager = null;
+let _sharedManagerPromise = null;
+/**
+ * Get or create a shared McpManager instance from the agent's config.
+ * Returns null if no mcpServers are configured.
+ * Safe to call from multiple senses — will only create one instance.
+ *
+ * `options.runtimeServers` are the current turn's per-agent MCP overrides (e.g.
+ * Workbench's `ouro_workbench`). They are PARAMETER data for this call only —
+ * passed into the merge for both the initial `start()` and every subsequent
+ * `reconcile()`, and never persisted as module state. A call that omits them
+ * reconciles to a set WITHOUT them, tearing any prior runtime server down — the
+ * no-leak invariant for the shared multi-agent daemon.
+ */
+async function getSharedMcpManager(options) {
+    const runtimeServers = options?.runtimeServers;
+    // If manager exists, reconcile to pick up config changes (new/removed servers)
+    // AND this turn's runtime overrides. Passing runtimeServers per-call is what
+    // scopes the runtime MCP to the active agent's turn.
+    if (_sharedManager) {
+        await _sharedManager.reconcile(runtimeServers);
+        return _sharedManager;
+    }
+    /* v8 ignore next -- race guard: deduplicates concurrent initialization calls @preserve */
+    if (_sharedManagerPromise)
+        return _sharedManagerPromise;
+    // Always re-check config — agent may have added servers since last call
+    _sharedManagerPromise = (async () => {
+        try {
+            const { mergedServers, pluginOrigins } = buildMergedServerConfig(runtimeServers);
+            if (Object.keys(mergedServers).length === 0)
+                return null;
+            const manager = new McpManager();
+            await manager.start(mergedServers, pluginOrigins);
+            _sharedManager = manager;
+            return manager;
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                event: "mcp.manager_start",
+                component: "repertoire",
+                message: "failed to initialize shared MCP manager",
+                /* v8 ignore next -- both branches tested: Error in wiring test, non-Error is defensive @preserve */
+                meta: { reason: error instanceof Error ? error.message : String(error) },
+            });
+            return null;
+        }
+        finally {
+            _sharedManagerPromise = null;
+        }
+    })();
+    return _sharedManagerPromise;
+}
+/**
+ * Shut down the shared MCP manager and clear the singleton.
+ * Called during daemon/agent shutdown.
+ */
+function shutdownSharedMcpManager() {
+    if (_sharedManager) {
+        _sharedManager.shutdown();
+        _sharedManager = null;
+    }
+}
+/** Reset for testing only */
+function resetSharedMcpManager() {
+    _sharedManager = null;
+    _sharedManagerPromise = null;
+}

package/dist/repertoire/mcp-tools.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * First-class MCP tool integration — converts MCP server tools into ToolDefinitions
+ * so the model can call them directly without shell indirection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpToolsAsDefinitions = mcpToolsAsDefinitions;
+const runtime_1 = require("../nerves/runtime");
+/**
+ * Convert all tools from an McpManager into ToolDefinition objects.
+ *
+ * Naming rules:
+ *  - Builtin servers (agent.json `mcpServers`) — legacy `{server}_{tool}`
+ *    shape (e.g., `browser_navigate`), with double-prefix avoidance when
+ *    the tool already starts with the server name.
+ *  - Plugin servers (from `<plugin>/.mcp.json`, W6 Unit 9) — Anthropic public
+ *    convention `mcp__{server}__{tool}` (e.g., `mcp__desk__task_create`).
+ *    This matches Claude Code's external naming and the on-prompt promise
+ *    in `desk-section.ts` (`mcp__desk__*`).
+ *
+ * The handler always calls `mcpManager.callTool()` with the un-prefixed
+ * `(server, tool)` pair regardless of how the surfaced name was shaped.
+ */
+function mcpToolsAsDefinitions(mcpManager) {
+    if (!mcpManager)
+        return [];
+    return mcpManager.listAllTools().flatMap((entry) => {
+        const isPluginSourced = Boolean(entry.pluginId);
+        return entry.tools.map((tool) => ({
+            tool: {
+                type: "function",
+                function: {
+                    name: isPluginSourced
+                        ? `mcp__${entry.server}__${tool.name}`
+                        : tool.name.startsWith(`${entry.server}_`) || tool.name === entry.server
+                            ? tool.name
+                            : `${entry.server}_${tool.name}`,
+                    description: tool.description || `MCP tool: ${tool.name} (server: ${entry.server})`,
+                    parameters: tool.inputSchema ?? { type: "object", properties: {} },
+                },
+            },
+            riskProfile: {
+                mutates: "external_side_effect",
+                risk: "high",
+                reason: "MCP tools may mutate external systems",
+            },
+            handler: async (args) => {
+                (0, runtime_1.emitNervesEvent)({
+                    event: "mcp.tool_start",
+                    component: "repertoire",
+                    message: `calling MCP tool ${entry.server}/${tool.name}`,
+                    meta: { server: entry.server, tool: tool.name },
+                });
+                try {
+                    const result = await mcpManager.callTool(entry.server, tool.name, args);
+                    const text = result.content
+                        .filter((c) => c.type === "text" && c.text)
+                        .map((c) => c.text)
+                        .join("");
+                    (0, runtime_1.emitNervesEvent)({
+                        event: "mcp.tool_end",
+                        component: "repertoire",
+                        message: `MCP tool ${entry.server}/${tool.name} completed`,
+                        meta: { server: entry.server, tool: tool.name },
+                    });
+                    return text;
+                }
+                catch (error) {
+                    const reason = error instanceof Error ? error.message : String(error);
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "error",
+                        event: "mcp.tool_error",
+                        component: "repertoire",
+                        message: `MCP tool ${entry.server}/${tool.name} failed: ${reason}`,
+                        meta: { server: entry.server, tool: tool.name, reason },
+                    });
+                    return `[mcp error] ${entry.server}/${tool.name}: ${reason}`;
+                }
+            },
+            mcpServer: entry.server,
+        }));
+    });
+}

package/dist/repertoire/plugin-mcp.js

@@ -0,0 +1,175 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listPluginMcpServers = listPluginMcpServers;
+exports.pluginMcpServerToConfig = pluginMcpServerToConfig;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const plugins_1 = require("./plugins");
+/**
+ * Resolve `${VAR}` and `${VAR:-default}` against the process env (with a
+ * caller-supplied override map applied first — used to inject the `DESK`
+ * fallback bound to the agent's bundle desk root).
+ *
+ * Anything that isn't a recognized `${...}` token passes through verbatim.
+ * Multiple substitutions per string are supported.
+ */
+function resolveVars(input, overrides) {
+    return input.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(:-([^}]*))?\}/g, (_match, varName, _full, def) => {
+        if (overrides[varName] !== undefined)
+            return overrides[varName];
+        const fromEnv = process.env[varName];
+        if (fromEnv !== undefined)
+            return fromEnv;
+        if (def !== undefined)
+            return def;
+        return "";
+    });
+}
+function resolveArgs(args, overrides) {
+    return args.map((a) => resolveVars(a, overrides));
+}
+function resolveEnv(env, overrides) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        out[k] = resolveVars(v, overrides);
+    }
+    return out;
+}
+function readPluginMcpManifest(pluginRoot) {
+    const manifestPath = path.join(pluginRoot, ".mcp.json");
+    if (!fs.existsSync(manifestPath))
+        return null;
+    const raw = fs.readFileSync(manifestPath, "utf-8");
+    try {
+        const parsed = JSON.parse(raw);
+        const servers = parsed?.mcpServers;
+        if (!servers || typeof servers !== "object")
+            return {};
+        return servers;
+    }
+    catch (err) {
+        /* v8 ignore next -- err.message vs String(err) branch is defensive @preserve */
+        const reason = err instanceof Error ? err.message : String(err);
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            event: "plugin_mcp.parse_error",
+            component: "repertoire",
+            message: `failed to parse plugin .mcp.json at ${manifestPath}: ${reason}`,
+            meta: { manifestPath, reason },
+        });
+        return null;
+    }
+}
+/**
+ * List the MCP servers declared across the current agent's enabled plugins.
+ *
+ * Returns a flat list — one entry per `(plugin, server-name)` pair — already
+ * resolved against process env + the `DESK` bundle-default. The result is
+ * suitable for direct hand-off to `McpManager.start()` after key-flattening.
+ *
+ * `homeDir` is an optional override for the `~/.ouro-cli/` root (test-only).
+ */
+function listPluginMcpServers(homeDir) {
+    (0, runtime_1.emitNervesEvent)({
+        event: "plugin_mcp.list_start",
+        component: "repertoire",
+        message: "discovering plugin-declared MCP servers",
+        meta: { operation: "listPluginMcpServers" },
+    });
+    const config = (0, identity_1.loadAgentConfig)();
+    const declaredPlugins = config.plugins ?? [];
+    const pluginsRoot = (0, plugins_1.getPluginsRoot)(homeDir);
+    // Per-agent override: DESK defaults to <bundleRoot>/desk/ when not explicitly set.
+    const overrides = {};
+    if (process.env.DESK === undefined) {
+        overrides.DESK = path.join((0, identity_1.getAgentRoot)(), "desk");
+    }
+    const out = [];
+    for (const plugin of declaredPlugins) {
+        if (!plugin.enabled)
+            continue;
+        const pluginDir = (0, plugins_1.getPluginDir)(plugin.id, homeDir);
+        // If the plugins root or plugin dir doesn't exist, skip (installed-but-removed
+        // or never-installed). The manifest read does its own .mcp.json existence
+        // check; we only need to avoid touching missing plugin dirs.
+        if (!fs.existsSync(pluginsRoot))
+            break;
+        if (!fs.existsSync(pluginDir))
+            continue;
+        const manifest = readPluginMcpManifest(pluginDir);
+        if (!manifest)
+            continue;
+        for (const [serverName, entry] of Object.entries(manifest)) {
+            if (!entry || typeof entry.command !== "string" || entry.command.length === 0) {
+                continue;
+            }
+            out.push({
+                pluginId: plugin.id,
+                serverName,
+                command: resolveVars(entry.command, overrides),
+                args: resolveArgs(entry.args ?? [], overrides),
+                env: resolveEnv(entry.env ?? {}, overrides),
+                cwd: pluginDir,
+            });
+        }
+    }
+    (0, runtime_1.emitNervesEvent)({
+        event: "plugin_mcp.list_end",
+        component: "repertoire",
+        message: "discovered plugin-declared MCP servers",
+        meta: {
+            operation: "listPluginMcpServers",
+            pluginCount: declaredPlugins.length,
+            serverCount: out.length,
+        },
+    });
+    return out;
+}
+/**
+ * Adapter: convert a `PluginMcpServer` into the shape `McpManager.start()`
+ * already consumes (`McpServerConfig`). Used by `getSharedMcpManager()` so
+ * builtin + plugin servers can be merged into one start call.
+ */
+function pluginMcpServerToConfig(server) {
+    return {
+        command: server.command,
+        args: server.args,
+        env: server.env,
+        cwd: server.cwd,
+    };
+}