@ouro.bot/cli 0.1.0-alpha.9 → 0.1.0-alpha.900

package/dist/repertoire/mcp-manager.js

@@ -0,0 +1,483 @@
+"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.McpManager = void 0;
+exports.getSharedMcpManager = getSharedMcpManager;
+exports.releaseRuntimeMcpServers = releaseRuntimeMcpServers;
+exports.shutdownSharedMcpManager = shutdownSharedMcpManager;
+exports.resetSharedMcpManager = resetSharedMcpManager;
+const path = __importStar(require("node:path"));
+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 tool_arguments_1 = require("./tool-arguments");
+const mcp_tools_1 = require("./mcp-tools");
+const MAX_RESTART_RETRIES = 5;
+const RESTART_DELAY_MS = 1000;
+function isOwner(value) {
+    return typeof value === "object" && value !== null
+        && "agentName" in value && typeof value.agentName === "string" && value.agentName.length > 0
+        && "agentRoot" in value && typeof value.agentRoot === "string" && path.isAbsolute(value.agentRoot);
+}
+function captureOwner(owner) {
+    if (!isOwner(owner)) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn", event: "mcp.owner_invalid", component: "repertoire",
+            message: "MCP requires an explicit owner", meta: { reason: "agent name and absolute root are required" },
+        });
+        throw new mcp_tools_1.McpCallRejectedError("MCP requires an explicit owner");
+    }
+    return Object.freeze({ agentName: owner.agentName, agentRoot: owner.agentRoot });
+}
+function sameOwner(left, right) {
+    return left.agentName === right.agentName && left.agentRoot === right.agentRoot;
+}
+function serverKey(owner, name) {
+    return JSON.stringify([owner.agentName, owner.agentRoot, name]);
+}
+function buildMergedServerConfig(owner, runtimeServers) {
+    const config = (0, identity_1.loadAgentConfig)(owner);
+    const desired = new Map();
+    for (const plugin of (0, plugin_mcp_1.listPluginMcpServers)(undefined, owner)) {
+        if (desired.has(plugin.serverName))
+            throw new mcp_tools_1.McpCallRejectedError(`MCP server name collision: ${plugin.serverName}`);
+        desired.set(plugin.serverName, {
+            config: (0, plugin_mcp_1.pluginMcpServerToConfig)(plugin), source: "plugin", pluginId: plugin.pluginId,
+        });
+    }
+    for (const [name, server] of Object.entries(config.mcpServers ?? {})) {
+        desired.set(name, { config: server, source: "builtin" });
+    }
+    for (const [name, server] of Object.entries(runtimeServers ?? {})) {
+        desired.set(name, { config: server, source: "runtime" });
+    }
+    return desired;
+}
+function configurationDigest(owner, desired) {
+    return (0, tool_arguments_1.digestJson)({
+        agentName: owner.agentName, agentRoot: owner.agentRoot,
+        source: desired.source, pluginId: desired.pluginId ?? null,
+        command: desired.config.command, args: desired.config.args ?? [],
+        env: desired.config.env ?? {}, cwd: desired.config.cwd ?? "",
+    });
+}
+class McpManager {
+    servers = new Map();
+    desiredGenerations = new Map();
+    nextGeneration = 0;
+    lifecycle = Promise.resolve();
+    shutdownPromise;
+    constructor() {
+        (0, runtime_1.emitNervesEvent)({
+            event: "mcp.manager_start", component: "repertoire",
+            message: "starting MCP manager", meta: { serverCount: 0 },
+        });
+    }
+    // One lifecycle tail; external tool and canary results do not hold it.
+    enqueue(operation) {
+        const result = this.lifecycle.then(operation);
+        this.lifecycle = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    enqueueBackground(operation) {
+        void this.enqueue(operation).catch((error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error", event: "mcp.lifecycle_error", component: "repertoire",
+                message: "MCP background lifecycle operation failed",
+                meta: { reason: error instanceof Error ? error.message : String(error) },
+            });
+        });
+    }
+    async start(ownerInput, servers, pluginOrigins = {}) {
+        const owner = captureOwner(ownerInput);
+        const desired = new Map(Object.entries(structuredClone(servers)).map(([name, config]) => [
+            name, { config, source: pluginOrigins[name] ? "plugin" : "builtin", pluginId: pluginOrigins[name] },
+        ]));
+        return this.enqueue(async () => {
+            if (this.shutdownPromise)
+                return null;
+            await this.applyDesired(owner, desired);
+            return this.shutdownPromise ? null : this.freezeView(owner);
+        });
+    }
+    async reconcile(ownerInput, runtimeServers) {
+        const owner = captureOwner(ownerInput);
+        const runtime = runtimeServers ? structuredClone(runtimeServers) : undefined;
+        return this.enqueue(async () => {
+            if (this.shutdownPromise)
+                return null;
+            try {
+                const desired = buildMergedServerConfig(owner, runtime);
+                await this.applyDesired(owner, desired);
+                return this.shutdownPromise || desired.size === 0 ? null : this.freezeView(owner);
+            }
+            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) },
+                });
+                for (const entry of this.ownedEntries(owner))
+                    this.removeEntry(entry);
+                return null;
+            }
+        });
+    }
+    listAllTools(owner) {
+        captureOwner(owner);
+        return this.ownedEntries(owner).filter((entry) => this.isCurrentEntry(entry)).map((entry) => ({
+            server: entry.name, tools: structuredClone(entry.cachedTools), pluginId: entry.pluginId,
+        }));
+    }
+    async callTool(binding, args, ownerInput) {
+        const owner = captureOwner(ownerInput);
+        const call = await this.enqueue(async () => {
+            let entry = this.currentBinding(binding, owner);
+            if (!entry.client.isConnected()) {
+                await this.recoverStaleTransport(entry, "pre-call disconnected");
+                entry = this.currentBinding(binding, owner);
+                if (!entry.client.isConnected())
+                    throw new mcp_tools_1.McpCallRejectedError(`Server "${entry.name}" is disconnected`);
+            }
+            return { entry, result: entry.client.callTool(binding.rawName, args) };
+        });
+        try {
+            return await call.result;
+        }
+        catch (error) {
+            if (!(0, mcp_client_1.isMcpTransportError)(error))
+                throw error;
+            const reason = error instanceof Error ? error.message : String(error);
+            // Recovery prepares later calls; the server may already have performed this one.
+            this.enqueueBackground(async () => {
+                if (this.isCurrentEntry(call.entry))
+                    await this.recoverStaleTransport(call.entry, reason);
+            });
+            throw error;
+        }
+    }
+    async validateToolBinding(binding, ownerInput) {
+        const owner = captureOwner(ownerInput);
+        await this.enqueue(() => { this.currentBinding(binding, owner); });
+    }
+    async runCanaries(ownerInput) {
+        const owner = captureOwner(ownerInput);
+        const entries = await this.enqueue(() => this.ownedEntries(owner));
+        const results = [];
+        for (const entry of entries) {
+            let current = entry;
+            try {
+                const refresh = await this.enqueue(async () => {
+                    if (!this.isCurrentEntry(entry))
+                        return null;
+                    if (!entry.client.isConnected())
+                        await this.recoverStaleTransport(entry, "canary disconnected");
+                    const recovered = this.servers.get(serverKey(owner, entry.name));
+                    if (!recovered || !this.isCurrentEntry(recovered) || !recovered.client.isConnected())
+                        return null;
+                    current = recovered;
+                    return { result: recovered.client.refreshTools() };
+                });
+                if (!refresh) {
+                    results.push({ server: entry.name, ok: false, detail: "disconnected after recovery attempt" });
+                    continue;
+                }
+                const tools = await refresh.result;
+                const updated = await this.enqueue(() => {
+                    if (!this.isCurrentEntry(current))
+                        return false;
+                    current.cachedTools = structuredClone(tools);
+                    current.consecutiveFailures = 0;
+                    return true;
+                });
+                results.push({
+                    server: entry.name, ok: updated,
+                    detail: updated ? `${tools.length} tools listed` : "server changed during canary",
+                });
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                if ((0, mcp_client_1.isMcpTransportError)(error)) {
+                    await this.enqueue(async () => {
+                        if (this.isCurrentEntry(current))
+                            await this.recoverStaleTransport(current, reason);
+                    });
+                }
+                results.push({ server: entry.name, ok: false, detail: reason });
+            }
+        }
+        return results;
+    }
+    shutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        // Publish closing before queued cleanup so pending network work cannot revive clients.
+        this.shutdownPromise = this.enqueue(() => {
+            (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.values()])
+                this.removeEntry(entry);
+            this.desiredGenerations.clear();
+        });
+        return this.shutdownPromise;
+    }
+    ownedEntries(owner) {
+        return [...this.servers.values()].filter((entry) => sameOwner(entry.owner, owner));
+    }
+    isCurrentEntry(entry) {
+        const key = serverKey(entry.owner, entry.name);
+        return !this.shutdownPromise && this.servers.get(key) === entry
+            && this.desiredGenerations.get(key) === entry.generation;
+    }
+    freezeView(owner) {
+        const entries = this.ownedEntries(owner).filter((entry) => this.isCurrentEntry(entry)).map((entry) => Object.freeze({
+            server: entry.name, source: entry.source, pluginId: entry.pluginId,
+            configDigest: entry.configDigest, generation: entry.generation,
+            tools: (0, tool_arguments_1.freezeToolValue)(structuredClone(entry.cachedTools)),
+        }));
+        return Object.freeze({ manager: this, owner, entries: Object.freeze(entries) });
+    }
+    matchesBinding(entry, binding, owner) {
+        if (binding.manager !== this || !sameOwner(binding, owner) || !sameOwner(entry.owner, owner)
+            || !this.isCurrentEntry(entry) || entry.name !== binding.server
+            || entry.source !== binding.source || entry.pluginId !== binding.pluginId
+            || entry.configDigest !== binding.configDigest || entry.generation !== binding.generation)
+            return false;
+        const tools = entry.cachedTools.filter((tool) => tool.name === binding.rawName);
+        if (tools.length !== 1)
+            return false;
+        const schema = (0, mcp_tools_1.mcpToolSchema)({ server: entry.name, pluginId: entry.pluginId }, tools[0]);
+        return schema.function.name === binding.surfacedName && (0, tool_arguments_1.digestJson)(schema) === binding.schemaDigest;
+    }
+    currentBinding(binding, owner) {
+        const entry = this.servers.get(serverKey(owner, binding.server));
+        if (!entry || !this.matchesBinding(entry, binding, owner)) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn", event: "mcp.tool_rejected", component: "repertoire",
+                message: "MCP tool binding is no longer current", meta: { reason: "stale or unavailable owned tool" },
+            });
+            throw new mcp_tools_1.McpCallRejectedError("MCP tool binding is stale or unavailable");
+        }
+        return entry;
+    }
+    removeEntry(entry) {
+        const key = serverKey(entry.owner, entry.name);
+        this.desiredGenerations.delete(key);
+        if (entry.restartTimer)
+            clearTimeout(entry.restartTimer);
+        entry.client.shutdown();
+        this.servers.delete(key);
+    }
+    async applyDesired(owner, desired) {
+        for (const [name, requested] of desired) {
+            if (this.shutdownPromise)
+                return;
+            const descriptor = { ...requested, config: structuredClone(requested.config) };
+            const configDigest = configurationDigest(owner, descriptor);
+            const current = this.servers.get(serverKey(owner, name));
+            if (current && this.isCurrentEntry(current) && current.configDigest === configDigest)
+                continue;
+            if (current) {
+                (0, runtime_1.emitNervesEvent)({
+                    event: "mcp.server_changed", component: "repertoire",
+                    message: `reconnecting changed MCP server: ${name}`, meta: { server: name },
+                });
+                this.removeEntry(current);
+            }
+            else {
+                (0, runtime_1.emitNervesEvent)({
+                    event: "mcp.server_added", component: "repertoire",
+                    message: `connecting new MCP server: ${name}`, meta: { server: name },
+                });
+            }
+            await this.connectServer({
+                ...descriptor, owner, name, configDigest, generation: ++this.nextGeneration, consecutiveFailures: 0,
+            });
+        }
+        for (const entry of this.ownedEntries(owner)) {
+            if (desired.has(entry.name))
+                continue;
+            (0, runtime_1.emitNervesEvent)({
+                event: "mcp.server_removed", component: "repertoire",
+                message: `disconnecting removed MCP server: ${entry.name}`, meta: { server: entry.name },
+            });
+            this.removeEntry(entry);
+        }
+    }
+    async resolveVaultEnv(env, owner) {
+        const resolved = { ...env };
+        if (!Object.values(resolved).some((value) => /^vault:/.test(value)))
+            return resolved;
+        const store = (0, credential_access_1.getCredentialStore)(owner.agentName);
+        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 (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                const classification = reason.includes("no credential found") ? "item not found"
+                    : reason.includes("field") && reason.includes("not found") ? "field empty" : "vault unreachable";
+                throw new Error(`vault:${domain}/${field} could not be resolved: ${classification}`);
+            }
+        }
+        return resolved;
+    }
+    async connectServer(desired) {
+        const key = serverKey(desired.owner, desired.name);
+        this.desiredGenerations.set(key, desired.generation);
+        let config = desired.config;
+        if (config.env) {
+            try {
+                config = { ...config, env: await this.resolveVaultEnv(config.env, desired.owner) };
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error", event: "mcp.vault_resolve_error", component: "repertoire",
+                    message: `skipping MCP server "${desired.name}": ${reason}`, meta: { server: desired.name, reason },
+                });
+                this.desiredGenerations.delete(key);
+                return;
+            }
+        }
+        if (this.shutdownPromise || this.desiredGenerations.get(key) !== desired.generation)
+            return;
+        const client = new mcp_client_1.McpClient(config);
+        const entry = { ...desired, client, cachedTools: [] };
+        this.servers.set(key, entry);
+        client.onClose(() => { this.enqueueBackground(() => this.handleServerCrash(entry)); });
+        try {
+            await client.connect();
+            if (!this.isCurrentEntry(entry)) {
+                client.shutdown();
+                return;
+            }
+            const tools = await client.listTools();
+            if (!this.isCurrentEntry(entry)) {
+                client.shutdown();
+                return;
+            }
+            entry.cachedTools = structuredClone(tools);
+        }
+        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 "${desired.name}"`,
+                meta: { server: desired.name, reason },
+            });
+        }
+    }
+    handleServerCrash(entry) {
+        if (!this.isCurrentEntry(entry) || entry.restartTimer)
+            return;
+        entry.consecutiveFailures++;
+        if (entry.consecutiveFailures > MAX_RESTART_RETRIES) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error", event: "mcp.connect_error", component: "repertoire",
+                message: `MCP server "${entry.name}" exceeded max restart retries`,
+                meta: { server: entry.name, failures: entry.consecutiveFailures },
+            });
+            return;
+        }
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn", event: "mcp.server_restart", component: "repertoire",
+            message: `restarting crashed MCP server: ${entry.name}`,
+            meta: { server: entry.name, attempt: entry.consecutiveFailures },
+        });
+        entry.restartTimer = setTimeout(() => {
+            this.enqueueBackground(async () => {
+                if (!this.isCurrentEntry(entry))
+                    return;
+                delete entry.restartTimer;
+                await this.restartServer(entry);
+            });
+        }, RESTART_DELAY_MS);
+    }
+    async restartServer(entry) {
+        this.removeEntry(entry);
+        await this.connectServer({
+            owner: entry.owner, name: entry.name, config: entry.config,
+            source: entry.source, pluginId: entry.pluginId,
+            configDigest: entry.configDigest, generation: entry.generation,
+            consecutiveFailures: entry.consecutiveFailures,
+        });
+    }
+    async recoverStaleTransport(entry, reason) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn", event: "mcp.transport_recovery", component: "repertoire",
+            message: `recovering stale MCP transport: ${entry.name}`, meta: { server: entry.name, reason },
+        });
+        await this.restartServer(entry);
+    }
+}
+exports.McpManager = McpManager;
+let _sharedManager = null;
+/** Every caller applies its own desired state and freezes its own view in the shared manager's lifecycle tail. */
+async function getSharedMcpManager(options) {
+    if (!isOwner(options)) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn", event: "mcp.owner_invalid", component: "repertoire",
+            message: "MCP requires an explicit owner", meta: { reason: "agent name and absolute root are required" },
+        });
+        return null;
+    }
+    const manager = _sharedManager ??= new McpManager();
+    return manager.reconcile(options, options.runtimeServers);
+}
+async function releaseRuntimeMcpServers(owner) {
+    if (_sharedManager)
+        await _sharedManager.reconcile(owner);
+}
+async function shutdownSharedMcpManager() {
+    const manager = _sharedManager;
+    if (!manager)
+        return;
+    await manager.shutdown();
+    if (_sharedManager === manager)
+        _sharedManager = null;
+}
+/** Reset for testing only. */
+async function resetSharedMcpManager() {
+    await shutdownSharedMcpManager();
+}

package/dist/repertoire/mcp-tools.js

@@ -0,0 +1,132 @@
+"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.McpToolExecutionError = exports.McpCallRejectedError = void 0;
+exports.mcpToolSchema = mcpToolSchema;
+exports.mcpToolsAsDefinitions = mcpToolsAsDefinitions;
+const runtime_1 = require("../nerves/runtime");
+const tool_arguments_1 = require("./tool-arguments");
+const mcp_write_guard_1 = require("./mcp-write-guard");
+class McpCallRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpCallRejectedError";
+    }
+}
+exports.McpCallRejectedError = McpCallRejectedError;
+class McpToolExecutionError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "McpToolExecutionError";
+    }
+}
+exports.McpToolExecutionError = McpToolExecutionError;
+function mcpToolSchema(entry, tool) {
+    return {
+        type: "function",
+        function: {
+            name: entry.pluginId
+                ? `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: {} },
+        },
+    };
+}
+/**
+ * Convert an owned frozen MCP view 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 carries the exact frozen binding to the manager's client fence.
+ */
+function mcpToolsAsDefinitions(view) {
+    if (!view)
+        return [];
+    return view.entries.flatMap((entry) => entry.tools.map((tool) => {
+        const schema = mcpToolSchema(entry, tool);
+        const binding = Object.freeze({
+            manager: view.manager, ...view.owner, server: entry.server,
+            rawName: tool.name, surfacedName: schema.function.name,
+            source: entry.source, pluginId: entry.pluginId,
+            configDigest: entry.configDigest, generation: entry.generation,
+            schemaDigest: (0, tool_arguments_1.digestJson)(schema),
+        });
+        return {
+            tool: schema,
+            // A read-only hint is trusted only from the agent's own bundle (agent.json mcpServers),
+            // so an orientation hold still lets the agent inspect through those tools.
+            riskProfile: entry.source === "builtin" && tool.annotations?.readOnlyHint === true
+                ? { mutates: "none", risk: "low", reason: "read-only tool from the agent's own MCP server" }
+                : {
+                    mutates: "external_side_effect",
+                    risk: "high",
+                    reason: "MCP tools may mutate external systems",
+                },
+            handler: async (args, ctx) => {
+                if (ctx?.agentName !== binding.agentName || ctx.agentRoot !== binding.agentRoot) {
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn", event: "mcp.tool_rejected", component: "repertoire",
+                        message: "MCP tool owner does not match its caller", meta: { reason: "owner mismatch" },
+                    });
+                    throw new McpCallRejectedError("MCP tool owner does not match its caller");
+                }
+                (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 },
+                });
+                const guarded = (0, mcp_write_guard_1.guardMcpArgs)({ toolName: tool.name, declaresDryRun: Object.hasOwn((tool.inputSchema?.properties ?? {}), "dry_run"), args, ctx });
+                if (guarded.rejected !== undefined)
+                    throw new McpCallRejectedError(guarded.rejected);
+                try {
+                    const result = await view.manager.callTool(binding, guarded.args, { agentName: ctx.agentName, agentRoot: ctx.agentRoot });
+                    const text = result.content
+                        .filter((c) => c.type === "text" && c.text)
+                        .map((c) => c.text)
+                        .join("");
+                    if (result.isError === true) {
+                        throw new McpToolExecutionError("handler_failed", `[mcp error] ${entry.server}/${tool.name}: ${text}`);
+                    }
+                    (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 },
+                    });
+                    if (error instanceof McpCallRejectedError || error instanceof McpToolExecutionError)
+                        throw error;
+                    throw new McpToolExecutionError("handler_indeterminate", `[mcp error] ${entry.server}/${tool.name}: ${reason}`);
+                }
+            },
+            mcpServer: entry.server,
+            mcpBinding: binding,
+        };
+    }));
+}

package/dist/repertoire/mcp-write-guard.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPLAY_REFUSED_WRITE_TOOLS = exports.OWNER_ONLY_WRITE_TOOLS = void 0;
+exports.guardMcpArgs = guardMcpArgs;
+/**
+ * Runtime guards on MCP tool arguments that the MCP server itself cannot enforce, because only the runtime knows who is calling.
+ *
+ *  - A replay identity (the host's replay gate, src/a2a/replay-harness.ts) never applies a change: every tool that declares a
+ *    `dry_run` argument is forced to a dry run for it, so a gate case can never alter the live house.
+ *  - A replay identity may not call a write tool that has no dry run at all (see REPLAY_REFUSED_WRITE_TOOLS).
+ *  - Some tools change settings only the owner may change: applying (dry_run false) is refused for any other caller, and the
+ *    caller is stamped into the arguments so the tool's audit line names who asked.
+ */
+const replay_harness_1 = require("../a2a/replay-harness");
+const runtime_1 = require("../nerves/runtime");
+/** MCP tools whose applied writes are owner-only. */
+exports.OWNER_ONLY_WRITE_TOOLS = new Set(["media_quality_profile"]);
+/** MCP tools that change the house and have no dry run: a replay identity may not call them at all. media_manual_import is a write only in `import` mode. */
+exports.REPLAY_REFUSED_WRITE_TOOLS = new Set(["media_request", "media_search_now", "media_blocklist", "media_blocklist_stalled", "media_fill_missing", "media_release_grab", "media_manual_import"]);
+const isWrite = (args) => (args.dry_run === false || args.dry_run === "false") && args.action !== "read";
+function callerFriend(ctx) {
+    const friend = ctx?.context?.friend;
+    return { id: friend?.id ?? ctx?.relationshipAuthorization?.actor?.friendId, name: friend?.name };
+}
+function guardMcpArgs(input) {
+    const { toolName, declaresDryRun, ctx } = input;
+    let args = input.args;
+    const caller = callerFriend(ctx);
+    if (exports.OWNER_ONLY_WRITE_TOOLS.has(toolName)) {
+        if (isWrite(args) && ctx?.relationshipAuthorization?.profileId !== "sanctuary-owner") {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "mcp.write_refused_non_owner", message: "an owner-only MCP write was refused", meta: { tool: toolName } });
+            return { rejected: `${toolName} changes settings only the owner may change. Show the owner the dry run and ask them to confirm; do not apply it for anyone else.` };
+        }
+        args = { ...args, caller: caller.id ? `${caller.id}${caller.name ? ` (${caller.name})` : ""}` : "unknown" };
+    }
+    const replay = Boolean(caller.id && ctx?.agentRoot && (0, replay_harness_1.isReplayIdentity)(ctx.agentRoot, caller.id));
+    if (replay && !declaresDryRun && exports.REPLAY_REFUSED_WRITE_TOOLS.has(toolName) && (toolName !== "media_manual_import" || args.mode === "import")) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "mcp.replay_write_refused", message: "a replay identity's MCP write with no dry run was refused", meta: { tool: toolName } });
+        return { rejected: `${toolName} changes the live house and has no dry run, so a replay identity may not call it. Describe what you would do instead.` };
+    }
+    if (replay && declaresDryRun && args.dry_run !== true) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "mcp.replay_forced_dry_run", message: "a replay identity's MCP call was forced to a dry run", meta: { tool: toolName } });
+        args = { ...args, dry_run: true };
+    }
+    return { args };
+}