@ouro.bot/cli 0.1.0-alpha.81 → 0.1.0-alpha.810

package/dist/repertoire/mcp-client.js

@@ -1,11 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpClient = void 0;
+exports.isMcpTransportError = isMcpTransportError;
 const child_process_1 = require("child_process");
 const readline_1 = require("readline");
 const runtime_1 = require("../nerves/runtime");
+const runtime_cwd_1 = require("../heart/runtime-cwd");
 const MCP_PROTOCOL_VERSION = "2024-11-05";
+const DEFAULT_REQUEST_TIMEOUT = 10_000;
 const DEFAULT_TOOL_CALL_TIMEOUT = 30_000;
+function isMcpTransportError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const normalized = message.toLowerCase();
+    return normalized.includes("disconnected")
+        || normalized.includes("transport")
+        || normalized.includes("closed")
+        || normalized.includes("econnreset")
+        || normalized.includes("econnrefused")
+        || normalized.includes("enoent")
+        || normalized.includes("epipe")
+        || normalized.includes("broken pipe")
+        || normalized.includes("not writable");
+}
 class McpClient {
     config;
     process = null;
@@ -18,6 +34,9 @@ class McpClient {
         this.config = config;
     }
     async connect() {
+        if (this.connected)
+            return;
+        this.shutdownProcessOnly();
         (0, runtime_1.emitNervesEvent)({
             event: "mcp.connect_start",
             component: "repertoire",
@@ -25,9 +44,11 @@ class McpClient {
             meta: { command: this.config.command },
         });
         const env = { ...process.env, ...this.config.env };
+        const spawnCwd = this.config.cwd ?? (0, runtime_cwd_1.recoverRuntimeCwd)();
         this.process = (0, child_process_1.spawn)(this.config.command, this.config.args ?? [], {
             env,
             stdio: ["pipe", "pipe", "pipe"],
+            cwd: spawnCwd,
         });
         this.setupLineReader();
         this.setupProcessHandlers();
@@ -43,6 +64,7 @@ class McpClient {
         }
         catch (error) {
             this.connected = false;
+            this.shutdownProcessOnly();
             (0, runtime_1.emitNervesEvent)({
                 level: "error",
                 event: "mcp.connect_error",
@@ -75,6 +97,10 @@ class McpClient {
         this.cachedTools = allTools;
         return allTools;
     }
+    async refreshTools() {
+        this.cachedTools = null;
+        return this.listTools();
+    }
     async callTool(name, args, timeout = DEFAULT_TOOL_CALL_TIMEOUT) {
         (0, runtime_1.emitNervesEvent)({
             event: "mcp.tool_call_start",
@@ -138,7 +164,7 @@ class McpClient {
         });
         return result;
     }
-    sendRequest(method, params, timeout) {
+    sendRequest(method, params, timeout = DEFAULT_REQUEST_TIMEOUT) {
         return new Promise((resolve, reject) => {
             if (!this.process || !this.connected && method !== "initialize") {
                 reject(new Error("MCP client is disconnected"));
@@ -159,14 +185,21 @@ class McpClient {
                 method,
                 params,
             };
-            this.writeMessage(request);
+            if (!this.writeMessage(request)) {
+                this.pending.delete(id);
+                if (pending.timer) {
+                    clearTimeout(pending.timer);
+                }
+                reject(new Error(`MCP transport is not writable for request: ${method}`));
+            }
         });
     }
     writeMessage(message) {
-        /* v8 ignore next -- defensive: stdin always writable during active connection @preserve */
         if (this.process?.stdin?.writable) {
             this.process.stdin.write(JSON.stringify(message) + "\n");
+            return true;
         }
+        return false;
     }
     setupLineReader() {
         /* v8 ignore next -- defensive: stdout always exists after spawn @preserve */
@@ -250,5 +283,13 @@ class McpClient {
             this.pending.delete(id);
         }
     }
+    shutdownProcessOnly() {
+        this.rejectAllPending(new Error("MCP transport closed during reconnect"));
+        /* v8 ignore next -- defensive: process may already be absent @preserve */
+        if (this.process && !this.process.killed) {
+            this.process.kill();
+        }
+        this.process = null;
+    }
 }
 exports.McpClient = McpClient;

package/dist/repertoire/mcp-manager.js

@@ -2,49 +2,232 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpManager = void 0;
 exports.getSharedMcpManager = getSharedMcpManager;
+exports.releaseRuntimeMcpServers = releaseRuntimeMcpServers;
 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 };
+}
+function sameMcpServerConfig(left, right) {
+    const leftEnv = Object.entries(left.env ?? {}).sort();
+    const rightEnv = Object.entries(right.env ?? {}).sort();
+    return left.command === right.command
+        && JSON.stringify(left.args ?? []) === JSON.stringify(right.args ?? [])
+        && JSON.stringify(leftEnv) === JSON.stringify(rightEnv)
+        && (left.cwd ?? "") === (right.cwd ?? "");
+}
 class McpManager {
     servers = new Map();
+    desiredGenerations = new Map();
+    nextGeneration = 0;
     shuttingDown = false;
-    async start(servers) {
+    async start(servers, pluginOrigins = {}, ownerAgent) {
         (0, runtime_1.emitNervesEvent)({
             event: "mcp.manager_start",
             component: "repertoire",
             message: "starting MCP manager",
-            meta: { serverCount: Object.keys(servers).length },
+            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);
+            await this.connectServer(name, config, pluginOrigins[name], ownerAgent);
         }
     }
     listAllTools() {
         const result = [];
         for (const [name, entry] of this.servers) {
-            result.push({ server: name, tools: entry.cachedTools });
+            result.push({ server: name, tools: entry.cachedTools, pluginId: entry.pluginId });
         }
         return result;
     }
     async callTool(server, tool, args) {
-        const entry = this.servers.get(server);
+        let entry = this.servers.get(server);
         if (!entry) {
             throw new Error(`Unknown server: ${server}`);
         }
         if (!entry.client.isConnected()) {
-            throw new Error(`Server "${server}" is disconnected`);
+            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 ownerAgent = (0, identity_1.getAgentName)();
+            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)) {
+                const current = this.servers.get(name);
+                const pluginId = pluginOrigins[name];
+                if (!current) {
+                    (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, pluginId, ownerAgent);
+                }
+                else if (!sameMcpServerConfig(current.config, cfg)
+                    || current.pluginId !== pluginId
+                    || current.ownerAgent !== ownerAgent) {
+                    (0, runtime_1.emitNervesEvent)({
+                        event: "mcp.server_changed",
+                        component: "repertoire",
+                        message: `reconnecting changed MCP server: ${name}`,
+                        meta: { server: name, command: cfg.command },
+                    });
+                    current.client.shutdown();
+                    this.servers.delete(name);
+                    await this.connectServer(name, cfg, pluginId, ownerAgent);
+                }
+            }
+            // 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);
+                    this.desiredGenerations.delete(name);
+                }
+            }
+            return true;
+        }
+        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) },
+            });
+            this.shutdown();
+            return false;
         }
-        return entry.client.callTool(tool, args);
     }
     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_stop",
+            event: "mcp.manager_end",
             component: "repertoire",
             message: "shutting down MCP manager",
             meta: { serverCount: this.servers.size },
@@ -53,45 +236,125 @@ class McpManager {
             entry.client.shutdown();
         }
         this.servers.clear();
+        this.desiredGenerations.clear();
+    }
+    /**
+     * Resolve `vault:DOMAIN/FIELD` references in server env config.
+     * Returns resolved env or throws with a descriptive error.
+     */
+    async resolveVaultEnv(_serverName, env, ownerAgent) {
+        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)(ownerAgent);
+        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) {
-        const client = new mcp_client_1.McpClient(config);
+    async connectServer(name, config, pluginId, ownerAgent) {
+        const generation = ++this.nextGeneration;
+        this.desiredGenerations.set(name, generation);
+        // Resolve vault: references in env before spawning
+        let resolvedConfig = config;
+        if (config.env) {
+            try {
+                const resolvedEnv = await this.resolveVaultEnv(name, config.env, ownerAgent);
+                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 },
+                });
+                if (this.desiredGenerations.get(name) === generation) {
+                    this.desiredGenerations.delete(name);
+                }
+                return; // Skip this server, continue to next
+            }
+        }
+        if (this.shuttingDown || this.desiredGenerations.get(name) !== generation)
+            return;
+        const client = new mcp_client_1.McpClient(resolvedConfig);
         const entry = {
             name,
             config,
             client,
             cachedTools: [],
             consecutiveFailures: 0,
+            pluginId,
+            ownerAgent,
+            generation,
         };
         this.servers.set(name, entry);
         client.onClose(() => {
             if (this.shuttingDown)
                 return;
-            this.handleServerCrash(name);
+            if (this.servers.get(name)?.client !== client)
+                return;
+            this.handleServerCrash(name, client);
         });
         try {
             await client.connect();
             const tools = await client.listTools();
+            if (this.shuttingDown
+                || this.desiredGenerations.get(name) !== generation
+                || this.servers.get(name)?.client !== client) {
+                client.shutdown();
+                return;
+            }
             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}`,
+                message: `failed to connect MCP server "${name}" (command: ${config.command}). Check that the command exists and is properly configured. Reason: ${reason}`,
                 meta: {
                     server: name,
-                    reason: error instanceof Error ? error.message : String(error),
+                    command: config.command,
+                    args: config.args,
+                    reason,
                 },
             });
         }
     }
-    handleServerCrash(name) {
+    handleServerCrash(name, crashedClient) {
         const entry = this.servers.get(name);
-        /* v8 ignore next -- defensive: entry removed between close event and handler @preserve */
-        if (!entry)
+        /* v8 ignore next -- defensive: entry removed or replaced between close event and handler @preserve */
+        if (!entry || entry.client !== crashedClient)
             return;
         entry.consecutiveFailures++;
         if (entry.consecutiveFailures > MAX_RESTART_RETRIES) {
@@ -99,8 +362,8 @@ class McpManager {
                 level: "error",
                 event: "mcp.connect_error",
                 component: "repertoire",
-                message: `MCP server "${name}" exceeded max restart retries (${MAX_RESTART_RETRIES})`,
-                meta: { server: name, failures: entry.consecutiveFailures },
+                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;
         }
@@ -115,26 +378,43 @@ class McpManager {
         setTimeout(() => {
             if (this.shuttingDown)
                 return;
-            this.restartServer(name).catch(() => {
+            if (this.servers.get(name)?.client !== crashedClient)
+                return;
+            this.restartServer(name, crashedClient).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) {
+    async restartServer(name, expectedClient) {
         const entry = this.servers.get(name);
         if (!entry)
             return;
+        if (expectedClient && entry.client !== expectedClient)
+            return;
         // Remove old entry and reconnect
         this.servers.delete(name);
-        await this.connectServer(name, entry.config);
+        this.desiredGenerations.delete(name);
+        entry.client.shutdown();
+        await this.connectServer(name, entry.config, entry.pluginId, entry.ownerAgent);
         // 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;
@@ -143,21 +423,38 @@ 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() {
-    if (_sharedManager)
+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) {
+        const reconciled = await _sharedManager.reconcile(runtimeServers);
+        if (!reconciled) {
+            _sharedManager = null;
+            return null;
+        }
         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 config = (0, identity_1.loadAgentConfig)();
-            const servers = config.mcpServers;
-            if (!servers || Object.keys(servers).length === 0)
+            const { mergedServers, pluginOrigins } = buildMergedServerConfig(runtimeServers);
+            if (Object.keys(mergedServers).length === 0)
                 return null;
             const manager = new McpManager();
-            await manager.start(servers);
+            await manager.start(mergedServers, pluginOrigins, (0, identity_1.getAgentName)());
             _sharedManager = manager;
             return manager;
         }
@@ -178,6 +475,13 @@ async function getSharedMcpManager() {
     })();
     return _sharedManagerPromise;
 }
+async function releaseRuntimeMcpServers() {
+    if (!_sharedManager)
+        return;
+    if (!await _sharedManager.reconcile()) {
+        _sharedManager = null;
+    }
+}
 /**
  * Shut down the shared MCP manager and clear the singleton.
  * Called during daemon/agent shutdown.

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