kritya 0.8.2-beta

package/dist/mcp/client.js

@@ -0,0 +1,945 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { VERSION } from "../version.js";
+import { NOOP_TRACER } from "../telemetry/tracer.js";
+import { McpAuthRequiredError } from "./oauth.js";
+import { missingVars } from "./servers.js";
+import { HttpTransport, StdioTransport } from "./transport.js";
+import { isPrivateOrLoopbackHost } from "../net/urlSafety.js";
+/**
+ * Model Context Protocol client with two transports and no SDK dependency
+ * (to keep the install lean):
+ *
+ *  - stdio: the server is a child process speaking newline-delimited JSON-RPC
+ *    2.0 (config: `command` + `args`).
+ *  - Streamable HTTP: the server is a remote endpoint (config: `url` +
+ *    `headers`); each JSON-RPC message is POSTed, and the response is either
+ *    a plain JSON body or a text/event-stream carrying one or more messages.
+ *    The `Mcp-Session-Id` response header is captured on initialize and sent
+ *    on every subsequent request, per the spec.
+ *
+ * Each configured server is launched/connected, initialized, and its tools
+ * are wrapped as kritya ToolDefs. Tool output is treated as external
+ * (untrusted) content.
+ */
+export const PROTOCOL_VERSION = "2026-07-28";
+const CONNECT_TIMEOUT_MS = 15_000;
+const CALL_TIMEOUT_MS = 120_000;
+/**
+ * Provider function-name ceiling. OpenAI-compatible endpoints reject the whole
+ * request — every tool, not just the offending one — when any name exceeds
+ * this, which surfaces as an inexplicable model failure rather than an MCP one.
+ */
+const MAX_TOOL_NAME_LEN = 64;
+/** Rough size of a base64 payload, for the placeholder that stands in for it. */
+function base64Bytes(data) {
+    return Math.floor((data.length * 3) / 4);
+}
+/**
+ * Flatten a tool result into the text the model sees.
+ *
+ * Everything that wasn't a text block used to become the literal string
+ * `[image content]`, which threw away three things that carry real payload
+ * today: `structuredContent` (the machine-readable result), resources the
+ * server inlined into the response, and links to resources it can serve. Text
+ * is still the only channel a tool result has, so binary blobs stay
+ * placeholders — but they now say what they are and how big, instead of
+ * pretending nothing was there.
+ */
+function renderToolResult(result) {
+    const parts = [];
+    for (const block of result.content ?? []) {
+        switch (block.type) {
+            case "text":
+                parts.push(block.text ?? "");
+                break;
+            case "image":
+            case "audio": {
+                const size = block.data ? `, ~${base64Bytes(block.data)} bytes` : "";
+                parts.push(`[${block.type}: ${block.mimeType ?? "unknown type"}${size}]`);
+                break;
+            }
+            case "resource_link":
+                parts.push(`[resource: ${block.uri ?? "unknown"}${block.name ? ` — ${block.name}` : ""}` +
+                    `${block.description ? ` (${block.description})` : ""}]`);
+                break;
+            case "resource": {
+                // Embedded, so the payload is already here — no second round trip.
+                const r = block.resource;
+                if (r?.text !== undefined) {
+                    parts.push(`[resource: ${r.uri ?? "inline"}]\n${r.text}`);
+                }
+                else if (r?.blob) {
+                    parts.push(`[resource: ${r.uri ?? "inline"} — ${r.mimeType ?? "binary"}, ` +
+                        `~${base64Bytes(r.blob)} bytes]`);
+                }
+                break;
+            }
+            default:
+                parts.push(`[${block.type} content]`);
+        }
+    }
+    // Servers that declare an outputSchema SHOULD send the same data as both
+    // structuredContent and a serialized text block, so only fall back to it
+    // when the content blocks gave us nothing — otherwise every such call would
+    // pay for the payload twice.
+    const text = parts.filter((p) => p !== "").join("\n");
+    if (text)
+        return text;
+    if (result.structuredContent !== undefined)
+        return JSON.stringify(result.structuredContent);
+    return "";
+}
+/** `_meta` block a task-enabled server's `tools/call` request carries, per the extension's negotiation mechanism. */
+export const TASKS_EXTENSION_META = {
+    "io.modelcontextprotocol/clientCapabilities": {
+        extensions: { "io.modelcontextprotocol/tasks": {} },
+    },
+};
+export const DEFAULT_POLL_INTERVAL_MS = 2000;
+/** Floor and ceiling for a server-reported `pollIntervalMs` — never trust
+ *  untrusted server data to schedule a busy-loop or an effectively-infinite sleep. */
+const MIN_POLL_INTERVAL_MS = 250;
+const MAX_POLL_INTERVAL_MS = 60_000;
+/** Clamp a server-reported poll interval into a sane range, falling back to the
+ *  default for anything non-finite (missing, zero, negative, NaN). */
+function sanitizePollInterval(ms) {
+    if (typeof ms !== "number" || !Number.isFinite(ms))
+        return DEFAULT_POLL_INTERVAL_MS;
+    return Math.min(Math.max(ms, MIN_POLL_INTERVAL_MS), MAX_POLL_INTERVAL_MS);
+}
+/** Sleep that rejects promptly on abort instead of running the full duration,
+ *  and `unref`s its timer so it never holds the event loop open. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("aborted"));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        timer.unref?.();
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Race an arbitrary promise (e.g. a UI callback we can't otherwise interrupt)
+ *  against abort, so a hung callback can't stall a cancellation. */
+function raceAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(new Error("aborted"));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new Error("aborted"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((v) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(v);
+        }, (e) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(e);
+        });
+    });
+}
+class McpConnection {
+    name;
+    transport;
+    workspace;
+    options;
+    nextId = 1;
+    pending = new Map();
+    closed = false;
+    constructor(name, transport, 
+    /** The workspace this session is working on — what `roots/list` reports. */
+    workspace, options = {}) {
+        this.name = name;
+        this.transport = transport;
+        this.workspace = workspace;
+        this.options = options;
+        transport.onMessage = (msg) => this.onMessage(msg);
+        transport.onError = (err) => this.fail(new Error(`MCP server "${name}": ${err.message}`));
+    }
+    /** Remove a pending request and release everything attached to it. */
+    take(id) {
+        const p = this.pending.get(id);
+        if (!p)
+            return undefined;
+        this.pending.delete(id);
+        clearTimeout(p.timer);
+        p.cleanup();
+        return p;
+    }
+    onMessage(msg) {
+        if (msg.method) {
+            // A request from the server (it has an id) or a notification (it doesn't).
+            if (typeof msg.id === "number")
+                this.onServerRequest(msg.id, msg.method, msg.params);
+            return;
+        }
+        if (typeof msg.id !== "number")
+            return;
+        const p = this.take(msg.id);
+        if (!p)
+            return;
+        if (msg.error)
+            p.reject(new Error(msg.error.message ?? "MCP error"));
+        else
+            p.resolve(msg.result);
+    }
+    /**
+     * Answer a request the server made of us.
+     *
+     * Only `roots/list` for now. Without it a filesystem-style server has no way
+     * to learn where the user's project is and falls back to whatever its own
+     * config guessed; with it, one workspace root is all most servers need. Every
+     * other method gets a proper "method not found" rather than silence, so a
+     * server can tell the difference between an unsupported client and a hung one.
+     */
+    onServerRequest(id, method, params) {
+        const reply = (body) => this.transport.send({ jsonrpc: "2.0", id, ...body }, CONNECT_TIMEOUT_MS).catch(() => { });
+        if (method === "roots/list") {
+            reply({
+                result: {
+                    roots: [{ uri: pathToFileURL(this.workspace).href, name: path.basename(this.workspace) }],
+                },
+            });
+            return;
+        }
+        if (method === "sampling/createMessage") {
+            if (!this.options.onSampling) {
+                reply({
+                    error: { code: -32601, message: `method "${method}" is not supported by kritya` },
+                });
+                return;
+            }
+            const p = params;
+            const req = {
+                server: this.name,
+                messages: (p?.messages ?? []).map((m) => ({
+                    role: m.role === "assistant" ? "assistant" : "user",
+                    content: m.content?.text ?? "",
+                })),
+                systemPrompt: p?.systemPrompt,
+                maxTokens: p?.maxTokens,
+            };
+            this.options
+                .onSampling(this.name, req)
+                .then((result) => {
+                if (!result.ok) {
+                    reply({ error: { code: -32603, message: result.reason } });
+                    return;
+                }
+                reply({
+                    result: {
+                        role: "assistant",
+                        content: { type: "text", text: result.content },
+                        model: result.model,
+                        stopReason: result.stopReason,
+                    },
+                });
+            })
+                .catch((err) => reply({ error: { code: -32603, message: err.message } }));
+            return;
+        }
+        if (method === "elicitation/create") {
+            if (!this.options.onElicitation) {
+                reply({
+                    error: { code: -32601, message: `method "${method}" is not supported by kritya` },
+                });
+                return;
+            }
+            const p = params;
+            let fields;
+            try {
+                fields = toElicitationFields(p?.requestedSchema ?? {});
+            }
+            catch (err) {
+                reply({
+                    error: { code: -32602, message: err instanceof Error ? err.message : String(err) },
+                });
+                return;
+            }
+            this.options
+                .onElicitation(this.name, p?.message ?? "", fields)
+                .then((result) => reply({ result }))
+                .catch((err) => reply({ error: { code: -32603, message: err.message } }));
+            return;
+        }
+        reply({ error: { code: -32601, message: `method "${method}" is not supported by kritya` } });
+    }
+    fail(err) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.cleanup();
+            p.reject(err);
+        }
+        this.pending.clear();
+    }
+    request(method, params, timeoutMs, signal) {
+        if (this.closed)
+            return Promise.reject(new Error(`MCP server "${this.name}" is not running`));
+        if (signal?.aborted) {
+            return Promise.reject(new Error(`MCP request "${method}" was cancelled`));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const p = this.take(id);
+                if (!p)
+                    return;
+                // Tell the server to stop: without this it runs the request to
+                // completion on the far side long after the user has moved on. This is
+                // what notifications/cancelled is for.
+                this.notify("notifications/cancelled", { requestId: id, reason: "cancelled by user" });
+                p.reject(new Error(`MCP request "${method}" was cancelled`));
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            const timer = setTimeout(() => {
+                const p = this.take(id);
+                p?.reject(new Error(`MCP request "${method}" timed out`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve,
+                reject,
+                timer,
+                cleanup: () => signal?.removeEventListener("abort", onAbort),
+            });
+            this.transport
+                .send({ jsonrpc: "2.0", id, method, params }, timeoutMs, signal)
+                .catch((err) => {
+                // Transport-level failure for this request (HTTP error, closed pipe):
+                // reject it directly rather than waiting for the timeout.
+                const p = this.take(id);
+                p?.reject(err);
+            });
+        });
+    }
+    notify(method, params) {
+        this.transport.send({ jsonrpc: "2.0", method, params }, CONNECT_TIMEOUT_MS).catch(() => { });
+    }
+    async initialize() {
+        const init = (await this.request("initialize", {
+            protocolVersion: PROTOCOL_VERSION,
+            // Declaring roots is what lets a server scope itself to the user's
+            // project instead of whatever its own config guessed.
+            capabilities: { roots: {}, sampling: {}, elicitation: {} },
+            clientInfo: { name: "kritya", version: VERSION },
+        }, CONNECT_TIMEOUT_MS));
+        if (this.transport instanceof HttpTransport) {
+            this.transport.protocolVersion = init.protocolVersion ?? PROTOCOL_VERSION;
+        }
+        this.notify("notifications/initialized");
+        const caps = init.capabilities ?? {};
+        // Tools are always asked for, declared or not: servers in the wild are
+        // sloppy about announcing capabilities, and a missing `tools` key is far
+        // more often an oversight than a server with no tools. Prompts and
+        // resources are gated, because there asking costs a round trip (and an
+        // error on strict servers) for something most servers genuinely lack.
+        const [tools, prompts, resources] = await Promise.all([
+            this.listTools(),
+            caps.prompts ? this.listPrompts() : Promise.resolve([]),
+            caps.resources ? this.listResources() : Promise.resolve([]),
+        ]);
+        return { tools, prompts, resources };
+    }
+    async listTools() {
+        const listed = (await this.request("tools/list", {}, CONNECT_TIMEOUT_MS));
+        return listed.tools ?? [];
+    }
+    /** Prompts and resources are extras: a server that fails to list them still connects. */
+    async listPrompts() {
+        try {
+            const listed = (await this.request("prompts/list", {}, CONNECT_TIMEOUT_MS));
+            return listed.prompts ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async listResources() {
+        try {
+            const listed = (await this.request("resources/list", {}, CONNECT_TIMEOUT_MS));
+            return listed.resources ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async getPrompt(name, args) {
+        const result = (await this.request("prompts/get", { name, arguments: args }, CALL_TIMEOUT_MS));
+        const messages = result.messages ?? [];
+        // A prompt is normally a single user message; when it isn't, keep the roles
+        // visible rather than silently flattening a scripted exchange into one voice.
+        const multiRole = new Set(messages.map((m) => m.role ?? "user")).size > 1;
+        return messages
+            .map((m) => {
+            const body = m.content ? renderToolResult({ content: [m.content] }) : "";
+            return multiRole ? `[${m.role ?? "user"}] ${body}` : body;
+        })
+            .filter(Boolean)
+            .join("\n\n");
+    }
+    async readResource(uri) {
+        const result = (await this.request("resources/read", { uri }, CALL_TIMEOUT_MS));
+        return (result.contents ?? [])
+            .map((c) => c.text !== undefined
+            ? c.text
+            : `[binary resource: ${c.mimeType ?? "unknown"}, ~${base64Bytes(c.blob ?? "")} bytes]`)
+            .join("\n");
+    }
+    async callTool(toolName, args, signal, tasksEnabled, onProgress) {
+        const params = { name: toolName, arguments: args };
+        if (tasksEnabled) {
+            params._meta = TASKS_EXTENSION_META;
+        }
+        const result = (await this.request("tools/call", params, CALL_TIMEOUT_MS, signal));
+        if (result.resultType === "task") {
+            if (!tasksEnabled) {
+                throw new Error("MCP server returned a task, but this server has not declared tasks support — refusing to poll it");
+            }
+            return this.pollTask(result, signal, onProgress);
+        }
+        const text = renderToolResult(result);
+        if (result.isError)
+            throw new Error(text || "MCP tool reported an error");
+        return text || "(no output)";
+    }
+    /** Poll `tasks/get` until a task reaches a terminal status, answering
+     *  elicitation-shaped `input_required` requests along the way. */
+    async pollTask(initial, signal, onProgress) {
+        const taskId = initial.taskId;
+        onProgress?.(initial.statusMessage ?? "task created — waiting…");
+        let pollIntervalMs = sanitizePollInterval(initial.pollIntervalMs);
+        // `ttlMs: null` means the server explicitly declared no expiry — leave
+        // it unbounded. Any other non-positive/non-finite value is nonsense, not
+        // an instruction, so it's likewise treated as no deadline.
+        const deadline = typeof initial.ttlMs === "number" && Number.isFinite(initial.ttlMs) && initial.ttlMs > 0
+            ? Date.now() + initial.ttlMs
+            : null;
+        try {
+            for (;;) {
+                if (deadline !== null && Date.now() >= deadline) {
+                    this.notify("tasks/cancel", { taskId });
+                    throw new Error("MCP task exceeded its ttlMs");
+                }
+                await sleep(pollIntervalMs, signal);
+                if (deadline !== null && Date.now() >= deadline) {
+                    this.notify("tasks/cancel", { taskId });
+                    throw new Error("MCP task exceeded its ttlMs");
+                }
+                const detailed = (await this.request("tasks/get", { taskId }, CALL_TIMEOUT_MS, signal));
+                pollIntervalMs = sanitizePollInterval(detailed.pollIntervalMs ?? pollIntervalMs);
+                switch (detailed.status) {
+                    case "working":
+                        onProgress?.(detailed.statusMessage ?? "working…");
+                        continue;
+                    case "input_required": {
+                        onProgress?.(detailed.statusMessage ?? "waiting for input…");
+                        await this.answerInputRequired(taskId, detailed.inputRequests ?? {}, signal);
+                        continue;
+                    }
+                    case "completed": {
+                        onProgress?.(detailed.statusMessage ?? "completed");
+                        const text = renderToolResult(detailed.result ?? {});
+                        if (detailed.result?.isError)
+                            throw new Error(text || "MCP tool reported an error");
+                        return text || "(no output)";
+                    }
+                    case "failed":
+                        throw new Error(detailed.error?.message ?? "MCP task failed");
+                    case "cancelled":
+                        throw new Error("MCP task was cancelled");
+                    default:
+                        throw new Error(`MCP task entered unrecognized status "${String(detailed.status)}"`);
+                }
+            }
+        }
+        catch (err) {
+            // Whatever went wrong — the sleep was interrupted, a request was cut
+            // short, an elicitation callback never returned — if it's because the
+            // caller aborted, make sure the server hears about it (best-effort,
+            // fire-and-forget) and surface one clear, consistent message rather
+            // than whichever request happened to be in flight at the time.
+            if (signal?.aborted) {
+                this.notify("tasks/cancel", { taskId });
+                throw new Error("MCP task cancelled by user", { cause: err });
+            }
+            throw err;
+        }
+    }
+    /** Answer every `input_required` entry via elicitation, or cancel the task
+     *  and throw if any entry isn't elicitation-shaped. */
+    async answerInputRequired(taskId, inputRequests, signal) {
+        const entries = Object.entries(inputRequests);
+        const unsupported = entries.find(([, req]) => req.method !== "elicitation/create");
+        if (unsupported) {
+            this.notify("tasks/cancel", { taskId });
+            throw new Error(`MCP task requires unsupported input method "${unsupported[1].method}" — cancelled`);
+        }
+        if (!this.options.onElicitation) {
+            this.notify("tasks/cancel", { taskId });
+            throw new Error("MCP task requires elicitation, but elicitation is not supported here");
+        }
+        const inputResponses = {};
+        try {
+            for (const [key, req] of entries) {
+                const p = req.params;
+                const fields = toElicitationFields(p?.requestedSchema ?? {});
+                inputResponses[key] = await raceAbort(this.options.onElicitation(this.name, p?.message ?? "", fields), signal);
+            }
+        }
+        catch (err) {
+            this.notify("tasks/cancel", { taskId });
+            throw err;
+        }
+        await this.request("tasks/update", { taskId, inputResponses }, CALL_TIMEOUT_MS, signal);
+    }
+    close() {
+        this.closed = true;
+        this.transport.close();
+    }
+}
+/**
+ * Match a tool name against one `*`-wildcard pattern, e.g. `github_*`.
+ * Everything else is literal — these are tool names, not paths.
+ */
+function matchesPattern(name, pattern) {
+    const rx = pattern
+        .split("*")
+        .map((literal) => literal.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*");
+    return new RegExp(`^${rx}$`).test(name);
+}
+/**
+ * Whether a server's tool passes its configured allow/deny lists. Deny wins,
+ * so a broad allow can be trimmed without rewriting it; an absent or empty
+ * allow means everything.
+ */
+export function toolAllowed(name, filter) {
+    if (!filter)
+        return true;
+    if (filter.deny?.some((p) => matchesPattern(name, p)))
+        return false;
+    if (!filter.allow?.length)
+        return true;
+    return filter.allow.some((p) => matchesPattern(name, p));
+}
+/** Loopback is exempt from the https requirement: there's no network to sniff. */
+function isLoopback(hostname) {
+    const h = hostname.replace(/^\[|\]$/g, "");
+    return h === "localhost" || h === "127.0.0.1" || h === "::1" || h.endsWith(".localhost");
+}
+/**
+ * Reject a remote server reachable only over plaintext. `/mcp add` already
+ * refuses these, but that guards one entrance: a server hand-written into
+ * ~/.kritya/config.json or a repo's .mcp.json never passes through it and
+ * would happily POST a bearer token in the clear. This is the choke point all
+ * three sources share.
+ */
+export function assertSafeUrl(name, url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`server "${name}" has an invalid url: ${url}`);
+    }
+    // https alone doesn't mean the traffic (incl. any bearer token in headers)
+    // stays where the user intends — a config pointing at 169.254.169.254 or
+    // another private/internal address would still ship credentials there.
+    // Loopback is exempt: that's this app talking to itself, nothing to leak to.
+    if (!isLoopback(parsed.hostname) && isPrivateOrLoopbackHost(parsed.hostname)) {
+        throw new Error(`server "${name}" points at a private/internal address (${parsed.hostname}) — refusing to connect.`);
+    }
+    if (parsed.protocol === "https:")
+        return parsed;
+    if (parsed.protocol === "http:" && isLoopback(parsed.hostname))
+        return parsed;
+    if (parsed.protocol !== "http:") {
+        throw new Error(`server "${name}" uses unsupported scheme "${parsed.protocol}" — use https://`);
+    }
+    throw new Error(`server "${name}" uses plain http:// (${parsed.host}) — an MCP session carries ` +
+        `your credentials in cleartext over it. Use https:// (localhost is exempt).`);
+}
+function makeTransport(name, cfg, workspace) {
+    if (cfg.url) {
+        if (cfg.command) {
+            throw new Error(`server "${name}" sets both "command" and "url"; pick one`);
+        }
+        assertSafeUrl(name, cfg.url);
+        return new HttpTransport(cfg.url, cfg.headers ?? {});
+    }
+    if (!cfg.command) {
+        throw new Error(`server "${name}" needs either "command" (stdio) or "url" (HTTP)`);
+    }
+    // Relative to the workspace, so a checked-in .mcp.json stays portable.
+    const cwd = cfg.cwd ? path.resolve(workspace, cfg.cwd) : workspace;
+    return new StdioTransport(cfg.command, cfg.args ?? [], cfg.env, cwd);
+}
+const connections = [];
+let statuses = [];
+/**
+ * Exposed tool name -> the identity that claimed it, so a second tool whose
+ * sanitized form lands on the same string doesn't silently shadow the first.
+ */
+const registeredNames = new Map();
+/** Server -> the exposed tool names it currently owns, for withdrawal and reuse. */
+const serverToolNames = new Map();
+const prompts = [];
+const resources = [];
+/** Slash commands contributed by connected MCP servers. */
+export function mcpPrompts() {
+    return prompts;
+}
+/** Attachable documents contributed by connected MCP servers. */
+export function mcpResources() {
+    return resources;
+}
+function forgetContributions(server) {
+    for (const list of [prompts, resources]) {
+        for (let i = list.length - 1; i >= 0; i--) {
+            if (list[i].server === server)
+                list.splice(i, 1);
+        }
+    }
+}
+function toolIdentity(server, toolName) {
+    return `${server}\u0000${toolName}`;
+}
+/** Status of every configured MCP server from the last loadMcpTools call. */
+export function mcpStatus() {
+    return statuses;
+}
+function sanitize(s) {
+    return s.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function shortHash(s) {
+    return crypto.createHash("sha256").update(s).digest("hex").slice(0, 8);
+}
+/**
+ * The name a tool is exposed to the model under.
+ *
+ * Two things can go wrong with the obvious `mcp_<server>_<tool>`. sanitize is
+ * lossy — `my.tool` and `my-tool` both become `my_tool`, so one tool shadows
+ * the other and calls silently go to the wrong place. And the result can
+ * exceed the provider's 64-character function-name limit, which fails the
+ * entire request rather than the one tool, looking like a broken model.
+ *
+ * Both are resolved by folding a hash of the true identity into the name:
+ * deterministic across runs (so allow-rules and transcripts stay valid), and
+ * distinct wherever the sanitized forms are not.
+ */
+function exposedToolName(server, toolName) {
+    const base = `mcp_${sanitize(server)}_${sanitize(toolName)}`;
+    const identity = toolIdentity(server, toolName);
+    const claimed = registeredNames.get(base);
+    const needsHash = base.length > MAX_TOOL_NAME_LEN || (claimed !== undefined && claimed !== identity);
+    if (!needsHash)
+        return base;
+    const suffix = `_${shortHash(identity)}`;
+    return base.slice(0, MAX_TOOL_NAME_LEN - suffix.length) + suffix;
+}
+/**
+ * Connect to all configured MCP servers and return their tools as ToolDefs.
+ * Resilient: a server that fails to start is skipped with a warning (and shows
+ * as failed in /mcp), never crashing kritya. Returns an empty list when
+ * nothing is configured.
+ *
+ * `trace` is optional so callers that don't care (tests, tools that load MCP
+ * servers ad hoc) can omit it; when given, each connect attempt gets a span
+ * and a failure is also written to the audit log — otherwise a failed server
+ * was only ever a single stderr line that nothing else recorded.
+ */
+export async function loadMcpTools(servers, trace) {
+    statuses = [];
+    registeredNames.clear();
+    serverToolNames.clear();
+    prompts.length = 0;
+    resources.length = 0;
+    if (!servers || Object.keys(servers).length === 0)
+        return [];
+    const tools = [];
+    const results = await Promise.all(Object.entries(servers).map(([name, cfg]) => connectServer(name, cfg, trace)));
+    for (const { tools: t, status } of results) {
+        tools.push(...t);
+        statuses.push(status);
+    }
+    return tools;
+}
+/**
+ * Connect one server and wrap its tools. Split out of loadMcpTools so a login
+ * can bring a server up mid-session without restarting kritya (and without
+ * disturbing the servers that are already connected).
+ *
+ * A server that needs OAuth is *not* an error: it reports `needsAuth` and no
+ * tools, so startup stays quiet and `/mcp` can tell the user what to run. The
+ * alternative — opening a browser during `kritya` startup — would hijack the
+ * terminal before the user has typed anything.
+ */
+export async function connectServer(name, cfg, trace) {
+    const tracer = trace?.tracer ?? NOOP_TRACER;
+    const workspace = trace?.workspace ?? process.cwd();
+    const tools = [];
+    const status = {
+        name,
+        transport: cfg.url ? "http" : "stdio",
+        target: cfg.url ?? [cfg.command, ...(cfg.args ?? [])].filter(Boolean).join(" "),
+        ok: false,
+        tools: [],
+        prompts: [],
+        resources: [],
+    };
+    const span = tracer.startSpan("mcp.connect", {
+        attributes: { "kritya.mcp_server": name, "kritya.mcp_transport": status.transport },
+    });
+    let conn;
+    try {
+        // Checked here rather than at expansion time: this is where a per-server
+        // failure has somewhere to go (`status.error`, and the /mcp table).
+        const missing = missingVars(cfg);
+        if (missing.length) {
+            throw new Error(`missing env var${missing.length > 1 ? "s" : ""} ${missing.join(", ")}`);
+        }
+        conn = new McpConnection(name, makeTransport(name, cfg, workspace), workspace, {
+            onSampling: trace?.onSampling,
+            onElicitation: trace?.onElicitation,
+        });
+        const listed = await conn.initialize();
+        const specs = listed.tools;
+        connections.push(conn);
+        // Reconnects re-derive names from scratch; releasing the old claims first
+        // keeps a server from colliding with its own previous incarnation.
+        releaseToolNames(name);
+        forgetContributions(name);
+        registerPrompts(conn, name, listed.prompts, status);
+        registerResources(conn, name, listed.resources, status);
+        const owned = new Set();
+        const exposed = specs.filter((s) => toolAllowed(s.name, cfg.tools));
+        status.hiddenTools = specs.length - exposed.length;
+        for (const spec of exposed) {
+            const def = mcpToolDef(conn, name, spec, cfg);
+            registeredNames.set(def.name, toolIdentity(name, spec.name));
+            owned.add(def.name);
+            tools.push(def);
+            status.tools.push(spec.name);
+        }
+        serverToolNames.set(name, owned);
+        status.ok = true;
+        span.setAttribute("kritya.mcp_tool_count", status.tools.length);
+        span.setStatus("OK");
+    }
+    catch (err) {
+        conn?.close();
+        if (err instanceof McpAuthRequiredError) {
+            status.needsAuth = true;
+            status.authMetadataUrl = err.resourceMetadataUrl;
+            status.error = `needs login — run /mcp login ${name}`;
+            span.setAttribute("kritya.mcp_needs_auth", true);
+            span.setStatus("OK");
+        }
+        else {
+            status.error = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`kritya: MCP server "${name}" failed to start: ${status.error}\n`);
+            span.setStatus("ERROR", status.error);
+            trace?.audit?.logTool({
+                tool: "mcp_connect",
+                summary: `server "${name}" failed to start: ${status.error}`,
+                outcome: "error",
+            });
+        }
+    }
+    finally {
+        span.end();
+    }
+    return { tools, status };
+}
+/**
+ * Expose a server's prompts as slash commands.
+ *
+ * Named `/<server>-<prompt>` so two servers offering "triage" don't fight over
+ * one command, and so it's obvious where a command came from. A server's
+ * prompt never displaces a built-in or a user's own command file: those are
+ * matched first, and a server that names a prompt "plan" shouldn't be able to
+ * quietly redefine /plan.
+ */
+function registerPrompts(conn, server, specs, status) {
+    for (const spec of specs) {
+        const command = `/${sanitizeCommand(server)}-${sanitizeCommand(spec.name)}`;
+        const args = spec.arguments ?? [];
+        prompts.push({
+            server,
+            name: spec.name,
+            command,
+            description: `[MCP: ${server}] ${spec.description ?? spec.name}`,
+            args,
+            expand: (argText) => conn.getPrompt(spec.name, splitPromptArgs(argText, args)),
+        });
+        status.prompts.push(spec.name);
+    }
+}
+/**
+ * Map what the user typed after the command onto the prompt's named arguments.
+ *
+ * Positional by whitespace, with the last declared argument soaking up the
+ * remainder — so a single-argument prompt gets the whole line, which is how
+ * every slash command in kritya already behaves.
+ */
+function splitPromptArgs(argText, args) {
+    const out = {};
+    if (!args.length)
+        return out;
+    const rest = argText.trim();
+    if (args.length === 1) {
+        if (rest)
+            out[args[0].name] = rest;
+        return out;
+    }
+    const parts = rest.split(/\s+/).filter(Boolean);
+    args.forEach((arg, i) => {
+        const value = i === args.length - 1 ? parts.slice(i).join(" ") : parts[i];
+        if (value)
+            out[arg.name] = value;
+    });
+    return out;
+}
+/** Expose a server's resources as `@mcp:<server>/<name>` attachments. */
+function registerResources(conn, server, specs, status) {
+    for (const spec of specs) {
+        const label = spec.name ?? spec.uri;
+        resources.push({
+            server,
+            uri: spec.uri,
+            mention: `mcp:${sanitizeCommand(server)}/${sanitizeCommand(label)}`,
+            description: spec.description ?? spec.mimeType ?? spec.uri,
+            read: () => conn.readResource(spec.uri),
+        });
+        status.resources.push(label);
+    }
+}
+/** Command/mention-safe form of a name: no spaces, no leading slash confusion. */
+function sanitizeCommand(s) {
+    return s.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+/** Replace one server's entry in the /mcp status table after a reconnect. */
+export function replaceStatus(status) {
+    const idx = statuses.findIndex((s) => s.name === status.name);
+    if (idx >= 0)
+        statuses[idx] = status;
+    else
+        statuses.push(status);
+}
+/**
+ * Whether a tool can run without asking the user first.
+ *
+ * Marking every MCP tool as permission-requiring costs more than it looks. It
+ * prompts on pure lookups (a docs fetch, an issue search), and approval fatigue
+ * is exactly what trains people to accept without reading — so the blanket
+ * prompt makes the prompts that matter *less* effective. It also silently
+ * excluded MCP from subagents, which are only handed tools that don't prompt.
+ *
+ * We take readOnlyHint at face value, but only that one: it is a claim by a
+ * server the user has already trusted (workspace trust + per-server trust) that
+ * a tool doesn't change anything. destructiveHint being set overrides it, since
+ * a server contradicting itself should get the cautious reading.
+ */
+/**
+ * A flat requestedSchema (object of string/boolean/enum properties) becomes
+ * ElicitationFields the UI can render. Anything with nesting or an
+ * unrecognized type is rejected outright, rather than guessed at.
+ */
+function toElicitationFields(schema) {
+    const props = schema.properties ?? {};
+    return Object.entries(props).map(([name, prop]) => {
+        const label = prop.title ?? name;
+        if (prop.enum)
+            return { name, kind: "enum", label, options: prop.enum };
+        if (prop.type === "boolean")
+            return { name, kind: "boolean", label };
+        if (prop.type === "string")
+            return { name, kind: "string", label };
+        throw new Error(`elicitation field "${name}" has an unsupported schema (type: ${prop.type ?? "nested/unknown"})`);
+    });
+}
+function isReadOnly(spec) {
+    const a = spec.annotations;
+    return a?.readOnlyHint === true && a.destructiveHint !== true;
+}
+export function mcpToolDef(conn, server, spec, cfg = {}) {
+    return {
+        name: exposedToolName(server, spec.name),
+        description: `[MCP: ${server}] ${spec.description ?? spec.name}`,
+        parameters: spec.inputSchema ?? { type: "object", properties: {} },
+        requiresPermission: cfg.consent === "always-confirm" ? true : !isReadOnly(spec),
+        // Self-managed: every request already carries CALL_TIMEOUT_MS, and the
+        // connection rejects in-flight calls when the transport dies.
+        timeoutMs: 0,
+        // Read-only or not, the output came from outside the workspace and is
+        // wrapped as untrusted — a lookup tool is a prime injection vector.
+        external: true,
+        summarize: (args) => `${server}/${spec.name}(${JSON.stringify(args).slice(0, 80)})`,
+        execute: (args, _ctx, signal, onProgress) => conn.callTool(spec.name, args, signal, cfg.tasks, onProgress),
+    };
+}
+/** The tool-name prefix every tool from a given server shares. */
+export function toolPrefix(server) {
+    return `mcp_${sanitize(server)}_`;
+}
+/**
+ * Predicate matching the tools a server currently contributes. Prefer this to
+ * a bare prefix test: a name that had to be hash-shortened is a truncation of
+ * `mcp_<server>_...` and can lose the prefix outright.
+ */
+export function isToolOf(server) {
+    const owned = serverToolNames.get(server);
+    if (!owned)
+        return (t) => t.startsWith(toolPrefix(server));
+    return (t) => owned.has(t);
+}
+/** Release a server's claimed tool names so they can be reused. */
+function releaseToolNames(server) {
+    for (const n of serverToolNames.get(server) ?? [])
+        registeredNames.delete(n);
+    serverToolNames.delete(server);
+}
+/**
+ * Close one server's connection and forget it. Used by `/mcp remove`,
+ * `/mcp logout`, and before a reconnect — leaving the old connection open
+ * would keep a stdio child process alive and, after a logout, keep a
+ * now-revoked session warm on the remote side.
+ */
+export function disconnectServer(name) {
+    for (let i = connections.length - 1; i >= 0; i--) {
+        if (connections[i].name === name) {
+            connections[i].close();
+            connections.splice(i, 1);
+        }
+    }
+}
+/** Drop a server from the /mcp status table entirely. */
+export function forgetStatus(name) {
+    statuses = statuses.filter((s) => s.name !== name);
+    // Callers withdraw the tools first (they need isToolOf while it still
+    // resolves), so this is the right point to give the names back.
+    releaseToolNames(name);
+    forgetContributions(name);
+}
+/** Kill all MCP servers (call on exit). */
+export function shutdownMcp() {
+    for (const conn of connections)
+        conn.close();
+    connections.length = 0;
+    registeredNames.clear();
+    serverToolNames.clear();
+    prompts.length = 0;
+    resources.length = 0;
+}