@haikit/mcp 0.0.0-stage → 0.33.0

package/dist/index.js

@@ -0,0 +1,722 @@
+/**
+ * @haikit/mcp — call MCP servers' tools from inside your own tools.
+ *
+ * The model never sees an MCP tool. An app declares the server tools it calls,
+ * typed by schemas it owns, and calls them from a HaiKIT tool's `run` or an
+ * action handler, the way it would call a database: that code decides what the
+ * model hears of a result and what the browser shows. So nothing a third-party
+ * server says — its tools' names and descriptions, its instructions, its
+ * results — reaches the model unless app code puts it there.
+ *
+ * There is no way to make a HaiKIT `Tool` from an MCP tool here, on purpose:
+ * an `McpTool` has no `run`, so `createHai({ tools })` won't take one.
+ *
+ * Imports only @haikit/core, like the model adapters.
+ */
+import { createRequire } from "node:module";
+import { Client, InsufficientScopeError, ProtocolError, ProtocolErrorCode, SdkError, SdkErrorCode, SdkHttpError, UnauthorizedError, } from "@modelcontextprotocol/client";
+import { BearerCredential, LookupFailed, NeedsAuth, configOf } from "./auth.js";
+import { McpError, McpToolError, isMcpError } from "./errors.js";
+import { madeByHttp } from "./transports.js";
+export { createMcpAuth } from "./auth.js";
+export { McpError, McpToolError, isMcpError, isMcpToolError } from "./errors.js";
+export { textOf } from "./text.js";
+export { http, stdio } from "./transports.js";
+const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+const TIMEOUT_MS = 30_000;
+/** Under the 120 s turn lease the stores default to, which isn't renewed while a tool runs. */
+const MAX_TOTAL_MS = 90_000;
+/** Past the longest timer Node keeps, it fires after about a millisecond. */
+const MAX_TIMER_MS = 2_147_483_647;
+const MAX_CONNECTIONS = 100;
+const IDLE_MS = 300_000;
+/**
+ * The SDK's own checks of a tool's result against the output schema the
+ * server declared, as of @modelcontextprotocol/client 2.4: `callTool` throws
+ * these, with these codes and words, once the server has answered. A
+ * server's own error reads as one only if it has the same code and words.
+ */
+const OUTPUT_CHECKS = [
+    [ProtocolErrorCode.InvalidRequest, /^Tool .+ has an output schema but did not return structured content$/],
+    [ProtocolErrorCode.InvalidParams, /^Structured content does not match the tool's output schema: /],
+    [ProtocolErrorCode.InvalidParams, /^Failed to validate structured content: /],
+];
+/** The connection to an MCP server. Nothing connects until `connect()` or the first call. */
+export function mcpServer(options) {
+    return new Server(options);
+}
+const NO_USER = {
+    none: "there is no user to call it as",
+    lookup: "the user it runs for could not be looked up",
+    other: "its userId is not the conversation's owner",
+};
+const MESSAGES = {
+    args: (who) => `${who} was not called: its args do not match the schema`,
+    result: (who) => `${who} returned a result that does not match the schema`,
+    timeout: (who) => `${who} did not answer in time`,
+    connection: (who) => `${who} could not be reached`,
+    protocol: (who) => `${who} was refused by the server`,
+    closed: (who) => `${who}: the connection was closed`,
+    user: (who, { user = "none" }) => `${who} was not called: ${NO_USER[user]}`,
+    auth: (who, { auth }) => auth?.kind === "connect"
+        ? `${who}: the user has not connected an account`
+        : auth?.kind === "scope"
+            ? `${who}: the user's account needs more access`
+            : `${who}: the server refused the user's credential`,
+};
+class Server {
+    name;
+    options;
+    timeoutMs;
+    maxTotalMs;
+    /** With `auth`: whose calls are made as whom, and with what. */
+    auth;
+    maxConnections;
+    idleMs;
+    /** Without `auth`: the one connection every call shares. */
+    shared;
+    /** With `auth`: each user's connection, the least recently used first. */
+    links = new Map();
+    closed = false;
+    /** Aborted by `close()`: a call waiting on anything stops with reason `closed`. */
+    shutdown = new AbortController();
+    /** The first `close()`, which the others wait for. */
+    closing = null;
+    /** The tools `tool()` declared: the only ones that can be called. */
+    declared = new Set();
+    constructor(options) {
+        if (typeof options.name !== "string" || options.name === "") {
+            throw new TypeError("name must be a non-empty string");
+        }
+        if (typeof options.transport !== "function") {
+            throw new TypeError("transport must be a function that makes a Transport, such as http(url) or stdio({ command })");
+        }
+        this.name = options.name;
+        this.options = options;
+        this.timeoutMs = checkMs("timeoutMs", options.timeoutMs ?? TIMEOUT_MS);
+        this.maxTotalMs = checkMs("maxTotalMs", options.maxTotalMs ?? MAX_TOTAL_MS);
+        if (options.auth === undefined) {
+            if (options.maxConnections !== undefined || options.idleMs !== undefined) {
+                throw new TypeError("maxConnections and idleMs are for a server with auth: without it, every call shares one connection");
+            }
+            this.auth = null;
+            this.maxConnections = 1;
+            this.idleMs = IDLE_MS;
+            this.shared = new Link(this, undefined, null);
+            return;
+        }
+        const auth = configOf(options.auth);
+        if (!auth)
+            throw new TypeError("auth must come from createMcpAuth(), such as mcpAuth.bearer(token)");
+        const made = madeByHttp.get(options.transport);
+        if (!made) {
+            throw new TypeError("auth needs a transport made by http(url): stdio() and other transports can't carry each user's credential");
+        }
+        if (made.authProvider)
+            throw new TypeError("auth gives the transport each user's credential: http() can't be given an authProvider as well");
+        if (made.authorization)
+            throw new TypeError("auth sets each user's Authorization header: http() can't send one of its own as well");
+        const max = options.maxConnections ?? MAX_CONNECTIONS;
+        if (typeof max !== "number" || !Number.isSafeInteger(max) || max < 1) {
+            throw new RangeError(`maxConnections must be a whole number, 1 or more (got ${String(max)})`);
+        }
+        this.idleMs = checkMs("idleMs", options.idleMs ?? IDLE_MS);
+        this.maxConnections = max;
+        // last, so a server refused above leaves its name free
+        if (auth.names.has(this.name))
+            throw new TypeError(`another server from the same createMcpAuth is named "${this.name}"`);
+        auth.names.add(this.name);
+        this.auth = auth;
+        this.shared = null;
+    }
+    tool(name, def) {
+        if (typeof name !== "string" || name === "")
+            throw new TypeError("a tool's name must be a non-empty string");
+        if (typeof def?.args?.parse !== "function") {
+            throw new TypeError(`tool "${name}" needs an args schema: anything with a parse method`);
+        }
+        if (def.result !== undefined && typeof def.result.parse !== "function") {
+            throw new TypeError(`tool "${name}" has a result schema with no parse method`);
+        }
+        if (def.timeoutMs !== undefined)
+            checkMs("timeoutMs", def.timeoutMs);
+        if (def.maxTotalMs !== undefined)
+            checkMs("maxTotalMs", def.maxTotalMs);
+        // checked against the latest tools, even if declared before; each user's
+        // connection checks a tool declared late on its first call to it
+        this.shared?.verify(name, true);
+        this.declared.add(name);
+        return Object.freeze({
+            server: this.name,
+            name,
+            call: (args, ctx) => this.call(name, def, args, ctx),
+        });
+    }
+    async connect(userId) {
+        if (this.shared) {
+            if (userId !== undefined)
+                throw new TypeError("connect() takes a user only for a server with auth");
+            await this.shared.open();
+            return;
+        }
+        if (typeof userId !== "string" || userId === "") {
+            throw new TypeError("connect() needs a userId for a server with auth: each user's connection is checked as it's made");
+        }
+        if (this.closed)
+            throw this.error("closed", undefined);
+        const link = this.take(userId);
+        try {
+            await link.ready();
+        }
+        finally {
+            link.release();
+        }
+    }
+    async forget(userId) {
+        if (!this.auth)
+            throw new TypeError("forget() is for a server with auth: without it, every call shares one connection");
+        if (typeof userId !== "string" || userId === "")
+            throw new TypeError("forget() needs a userId");
+        const link = this.links.get(userId);
+        if (!link)
+            return;
+        this.links.delete(userId);
+        await link.close();
+    }
+    close() {
+        // every close() resolves once the first has closed everything
+        this.closing ??= this.shut();
+        return this.closing;
+    }
+    async shut() {
+        this.closed = true;
+        this.shutdown.abort();
+        this.auth?.names.delete(this.name);
+        const links = this.shared ? [this.shared] : [...this.links.values()];
+        this.links.clear();
+        await Promise.all(links.map((link) => link.close()));
+    }
+    /** The user's connection, made if need be, marked most recently used, and held for a call. */
+    take(user) {
+        let link = this.links.get(user);
+        if (link) {
+            this.links.delete(user);
+        }
+        else {
+            this.trim(this.maxConnections - 1);
+            link = new Link(this, user, new BearerCredential(this.auth.token, user, this.timeoutMs));
+        }
+        this.links.set(user, link);
+        link.hold();
+        return link;
+    }
+    /** Closes the least recently used connections with no call in flight, down to `limit`. */
+    trim(limit = this.maxConnections) {
+        for (const [user, link] of this.links) {
+            if (this.links.size <= limit)
+                return;
+            // when every link is busy, the pool grows past the cap until one is free
+            if (link.busy === 0)
+                this.drop(user, link);
+        }
+    }
+    /** Closes a user's connection, unless another has replaced it. */
+    drop(user, link) {
+        if (this.links.get(user) !== link)
+            return;
+        this.links.delete(user);
+        link.close().catch(() => { });
+    }
+    /**
+     * Who a call on a server with `auth` runs as: the conversation's owner, or
+     * the `userId` of a call made outside any conversation. Never anyone else.
+     */
+    async userFor(ctx, tool) {
+        const conversationId = nonEmpty(ctx?.conversationId);
+        const given = nonEmpty(ctx?.userId);
+        if (conversationId === undefined) {
+            if (given === undefined)
+                throw this.error("user", tool);
+            return given;
+        }
+        let owner;
+        try {
+            owner = await this.auth.userOf(conversationId);
+        }
+        catch (err) {
+            throw this.error("user", tool, { cause: err, user: "lookup" });
+        }
+        if (typeof owner !== "string" || owner === "")
+            throw this.error("user", tool);
+        if (given !== undefined && given !== owner)
+            throw this.error("user", tool, { user: "other" });
+        return owner;
+    }
+    async call(tool, def, args, ctx) {
+        let input;
+        try {
+            input = def.args.parse(args);
+        }
+        catch (err) {
+            throw this.error("args", tool, { cause: err });
+        }
+        if (typeof input !== "object" || input === null || Array.isArray(input)) {
+            throw new McpError("args", `${this.name}/${tool} was not called: its args must be an object`, {
+                server: this.name,
+                tool,
+            });
+        }
+        // maxTotalMs bounds the whole call, connecting included, and is ours to
+        // keep: the SDK checks its own maxTotalTimeout only when progress comes
+        const deadline = new AbortController();
+        const timer = setTimeout(() => deadline.abort(), def.maxTotalMs ?? this.maxTotalMs);
+        let link;
+        let result;
+        try {
+            if (this.shared) {
+                link = this.shared;
+            }
+            else {
+                if (this.closed)
+                    throw this.error("closed", tool);
+                const user = await this.until(deadline.signal, tool, this.userFor(ctx, tool));
+                if (this.closed)
+                    throw this.error("closed", tool);
+                link = this.take(user);
+            }
+            let client;
+            try {
+                client = await this.until(deadline.signal, tool, link.ready());
+            }
+            catch (err) {
+                // named again for this call, with what the server said; the
+                // declared-tool check throws as it is
+                if (!isMcpError(err) || err.tool === tool)
+                    throw err;
+                throw this.error(err.reason, tool, { cause: err.cause ?? err, text: err.text, code: err.code, auth: err.auth });
+            }
+            link.verify(tool);
+            try {
+                result = await client.callTool({ name: tool, arguments: input }, {
+                    timeout: def.timeoutMs ?? this.timeoutMs,
+                    // cancels the request, and rejects it as a timeout
+                    signal: deadline.signal,
+                    // asked for whether or not anyone hears it, so progress always
+                    // keeps a long call alive
+                    resetTimeoutOnProgress: true,
+                    onprogress: (p) => {
+                        ctx?.progress?.({
+                            done: p.progress,
+                            ...(p.total === undefined ? {} : { total: p.total }),
+                            ...(p.message === undefined ? {} : { message: p.message }),
+                        });
+                    },
+                });
+            }
+            catch (err) {
+                throw link.failure(err, tool, client);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            if (link !== this.shared)
+                link?.release();
+        }
+        const content = result.content ?? [];
+        if (result.isError)
+            throw new McpToolError(this.name, tool, content);
+        if (!def.result) {
+            return result.structuredContent === undefined ? { content } : { content, structuredContent: result.structuredContent };
+        }
+        let value;
+        if (result.structuredContent !== undefined) {
+            value = result.structuredContent;
+        }
+        else {
+            const only = content.length === 1 ? content[0] : undefined;
+            if (only?.type !== "text") {
+                throw this.error("result", tool, {
+                    cause: new Error("the result has no structured content, and isn't one text block"),
+                });
+            }
+            try {
+                value = JSON.parse(only.text);
+            }
+            catch (err) {
+                throw this.error("result", tool, { cause: err });
+            }
+        }
+        try {
+            return def.result.parse(value);
+        }
+        catch (err) {
+            throw this.error("result", tool, { cause: err });
+        }
+    }
+    /** What `promise` resolves to, unless `close()` comes first (`closed`), or `deadline` aborts (`timeout`). */
+    until(deadline, tool, promise) {
+        return unless(promise, [
+            [this.shutdown.signal, () => this.error("closed", tool)],
+            [deadline, () => this.error("timeout", tool)],
+        ]);
+    }
+    error(reason, tool, detail = {}) {
+        const who = tool === undefined ? this.name : `${this.name}/${tool}`;
+        const { user, ...kept } = detail;
+        return new McpError(reason, MESSAGES[reason](who, detail), { server: this.name, tool, ...kept });
+    }
+}
+/**
+ * One SDK client over one transport, for one identity: the server's own, or
+ * one user's. It connects when first needed, and again after it drops.
+ */
+class Link {
+    server;
+    user;
+    credential;
+    /** The connected client, or null between connections. */
+    client = null;
+    dialing = null;
+    /** While a connection is being made: its client, once there is one, so `close()` can stop it. */
+    connecting = null;
+    /** While `transport()` is pending: gives up on it, for `close()`. */
+    abandon = null;
+    closed = false;
+    /** Aborted by `close()`: stops a wait for the credential, which no transport is there to stop. */
+    ending = new AbortController();
+    /** The first `close()`, which the others wait for. */
+    closing = null;
+    /** Clients whose connection has gone. */
+    dropped = new WeakSet();
+    /** The server's tools at the last listing, by name. Null until a first connect passes the check. */
+    listed = null;
+    /** The declared tools checked against this connection's tools. */
+    checked = new Set();
+    /** Calls and `connect()`s using it now: a busy link is never closed for room or for idling. */
+    busy = 0;
+    idle = null;
+    constructor(server, 
+    /** The user it calls as; undefined for the server's own identity. */
+    user, credential) {
+        this.server = server;
+        this.user = user;
+        this.credential = credential;
+    }
+    hold() {
+        this.busy++;
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.idle = null;
+    }
+    release() {
+        if (--this.busy > 0 || this.user === undefined || this.closed)
+            return;
+        const user = this.user;
+        this.idle = setTimeout(() => this.server.drop(user, this), this.server.idleMs);
+        this.idle.unref?.();
+        // a pool grown past its cap shrinks as soon as a connection is free
+        this.server.trim();
+    }
+    /** Connected, with a credential if it needs one. */
+    async ready() {
+        if (this.credential && !this.closed) {
+            try {
+                await unless(this.credential.ensure(), [[this.ending.signal, () => this.server.error("closed", undefined)]]);
+            }
+            catch (err) {
+                // closed, whatever the lookup did meanwhile
+                if (this.closed)
+                    throw isMcpError(err) ? err : this.server.error("closed", undefined, { cause: err });
+                throw this.authFailure(err, undefined) ?? err;
+            }
+        }
+        return this.open();
+    }
+    /**
+     * A tool declared after this connection's first check is checked on its
+     * first call, and throws as `connect` would. `again` checks it against the
+     * latest tools even if it was checked before.
+     */
+    verify(tool, again = false) {
+        if (!this.listed || (!again && this.checked.has(tool)))
+            return;
+        const problem = problemWith(tool, this.listed);
+        if (problem)
+            throw new Error(`${this.server.name}: ${problem}`);
+        this.checked.add(tool);
+    }
+    open() {
+        if (this.closed)
+            return Promise.reject(this.server.error("closed", undefined));
+        if (this.client)
+            return Promise.resolve(this.client);
+        // one connection at a time: calls that arrive meanwhile share it
+        this.dialing ??= this.dial().finally(() => {
+            this.dialing = null;
+            this.connecting = null;
+        });
+        return this.dialing;
+    }
+    close() {
+        // every close() resolves once the first has closed everything
+        this.closing ??= this.shut();
+        return this.closing;
+    }
+    async shut() {
+        this.closed = true;
+        this.ending.abort();
+        // a lookup that never answers would keep its timer, and the process, going
+        this.credential?.close();
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.idle = null;
+        const client = this.client;
+        this.client = null;
+        // a connection still being made is stopped where it is, and sees `closed`
+        this.abandon?.();
+        await this.connecting?.close().catch(() => { });
+        await this.dialing?.catch(() => { });
+        await client?.close();
+    }
+    /**
+     * What `transport()` makes, within `timeoutMs` and unless `close()` comes
+     * first. A transport made after that is closed when it comes.
+     */
+    async made() {
+        const { options, timeoutMs } = this.server;
+        const authProvider = this.credential?.provider;
+        const making = Promise.resolve().then(() => (authProvider ? options.transport(authProvider) : options.transport()));
+        let timer;
+        const cut = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`no transport within ${timeoutMs} ms`)), timeoutMs);
+            this.abandon = () => reject(new Error("closed while the transport was being made"));
+        });
+        try {
+            return await Promise.race([making, cut]);
+        }
+        catch (err) {
+            making.then((transport) => transport.close()).catch(() => { });
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+            this.abandon = null;
+        }
+    }
+    async dial() {
+        const { server } = this;
+        let client;
+        try {
+            const transport = await this.made();
+            // close() may have come as it was made, with nothing yet to stop
+            if (this.closed) {
+                await transport.close().catch(() => { });
+                throw new Error("closed as the transport was made");
+            }
+            const self = new Client({ name: "haikit", version: VERSION }, {
+                // No capabilities are advertised, so a server has no reason to ask
+                // this client for input; one that does gets the call refused,
+                // rather than a reply nobody wrote.
+                inputRequired: { autoFulfill: false },
+                ...(server.options.versionNegotiation === undefined
+                    ? {}
+                    : { versionNegotiation: { mode: server.options.versionNegotiation } }),
+                listChanged: {
+                    tools: {
+                        onChanged: (error, tools) => {
+                            if (!error && tools && this.client === self)
+                                this.compare(tools);
+                        },
+                    },
+                },
+            });
+            client = self;
+            this.connecting = self;
+            self.onclose = () => {
+                this.dropped.add(self);
+                if (this.client === self)
+                    this.client = null;
+            };
+            await self.connect(transport, { timeout: server.timeoutMs });
+        }
+        catch (err) {
+            await client?.close().catch(() => { });
+            if (this.closed)
+                throw server.error("closed", undefined, { cause: err });
+            throw this.authFailure(err, undefined) ?? server.error("connection", undefined, { cause: err });
+        }
+        let tools;
+        try {
+            ({ tools } = await client.listTools(undefined, { timeout: server.timeoutMs }));
+        }
+        catch (err) {
+            await client.close().catch(() => { });
+            throw this.failure(err, undefined, client);
+        }
+        if (this.listed === null) {
+            const listing = new Map(tools.map((t) => [t.name, t]));
+            const problems = [...server.declared].flatMap((name) => problemWith(name, listing) ?? []);
+            if (problems.length) {
+                await client.close().catch(() => { });
+                throw new Error(`${server.name}: ${problems.join("; ")}`);
+            }
+            this.listed = listing;
+            for (const name of server.declared)
+                this.checked.add(name);
+        }
+        else {
+            this.compare(tools);
+        }
+        if (this.closed) {
+            await client.close().catch(() => { });
+            throw server.error("closed", undefined);
+        }
+        if (this.dropped.has(client))
+            throw server.error("connection", undefined);
+        this.client = client;
+        return client;
+    }
+    /** Report what changed about the declared tools since the last listing, and keep this one. */
+    compare(tools) {
+        const before = this.listed ?? new Map();
+        const next = new Map(tools.map((t) => [t.name, t]));
+        this.listed = next;
+        const removed = [];
+        const changed = [];
+        for (const name of this.server.declared) {
+            const was = before.get(name);
+            const now = next.get(name);
+            if (!was)
+                continue;
+            if (!now)
+                removed.push(name);
+            else if (shape(was) !== shape(now))
+                changed.push(name);
+        }
+        if (!removed.length && !changed.length)
+            return;
+        const change = this.user === undefined ? { server: this.server.name, removed, changed } : { server: this.server.name, user: this.user, removed, changed };
+        try {
+            (this.server.options.onChange ?? warn)(change);
+        }
+        catch (err) {
+            console.error(err);
+        }
+    }
+    /**
+     * An error about the user's credential, as one of ours, or null for any
+     * other. A server without `auth` has none: its SDK errors read as in
+     * `failure`.
+     */
+    authFailure(err, tool) {
+        const { server } = this;
+        if (err instanceof NeedsAuth)
+            return server.error("auth", tool, { auth: { kind: err.kind } });
+        if (err instanceof LookupFailed)
+            return server.error("connection", tool, { cause: err.cause });
+        if (!this.credential)
+            return null;
+        if (err instanceof InsufficientScopeError) {
+            const auth = err.requiredScope ? { kind: "scope", scope: err.requiredScope } : { kind: "scope" };
+            return server.error("auth", tool, { cause: err, text: err.message, auth });
+        }
+        // a 401 again on the transport's one retry, after onUnauthorized found a token
+        if (err instanceof UnauthorizedError || (err instanceof SdkHttpError && err.code === SdkErrorCode.ClientHttpAuthentication)) {
+            return server.error("auth", tool, { cause: err, text: err.message, auth: { kind: "reconnect" } });
+        }
+        return null;
+    }
+    /** An SDK error, as one of ours. */
+    failure(err, tool, client) {
+        const { server } = this;
+        if (isMcpError(err))
+            return err;
+        if (this.closed)
+            return server.error("closed", tool, { cause: err });
+        const auth = this.authFailure(err, tool);
+        if (auth)
+            return auth;
+        if (err instanceof ProtocolError) {
+            // The SDK's own check of a call's result throws one too: the server's
+            // result is at fault there, not the call. Only a call has a result.
+            const checked = tool !== undefined && OUTPUT_CHECKS.some(([code, words]) => err.code === code && words.test(err.message));
+            return server.error(checked ? "result" : "protocol", tool, { cause: err, text: err.message, code: err.code });
+        }
+        if (err instanceof SdkError) {
+            switch (err.code) {
+                case SdkErrorCode.RequestTimeout:
+                    return server.error("timeout", tool, { cause: err });
+                case SdkErrorCode.NotConnected:
+                case SdkErrorCode.ConnectionClosed:
+                case SdkErrorCode.SendFailed:
+                case SdkErrorCode.ClientHttpFailedToOpenStream:
+                    return server.error("connection", tool, { cause: err });
+                case SdkErrorCode.InvalidResult:
+                    // only a call has a result; a listing the SDK can't read is the server's fault
+                    if (tool !== undefined)
+                        return server.error("result", tool, { cause: err });
+                    return server.error("protocol", tool, { cause: err, text: err.message });
+                default:
+                    return server.error("protocol", tool, { cause: err, text: err.message });
+            }
+        }
+        // the SDK throws a plain Error for a call on a connection that has gone
+        return server.error(this.dropped.has(client) ? "connection" : "protocol", tool, { cause: err });
+    }
+}
+/**
+ * What `promise` resolves to, unless one of `stops` aborts first: then it
+ * rejects with what that stop's `error()` makes, the first in the list if
+ * more than one has. `promise` is left to settle on its own, and holds
+ * nothing of this wait: every listener goes as soon as it ends, however it
+ * ends, so one that never settles leaves none on a long-lived signal.
+ */
+function unless(promise, stops) {
+    return new Promise((resolve, reject) => {
+        const offs = [];
+        const end = (settle) => (value) => {
+            for (const off of offs)
+                off();
+            settle(value);
+        };
+        const fulfil = end(resolve);
+        const fail = end(reject);
+        for (const [signal, error] of stops) {
+            const stop = () => fail(error());
+            signal.addEventListener("abort", stop, { once: true });
+            offs.push(() => signal.removeEventListener("abort", stop));
+        }
+        promise.then(fulfil, fail);
+        // an abort that came before is never heard as an event
+        const done = stops.find(([signal]) => signal.aborted);
+        if (done)
+            fail(done[1]());
+    });
+}
+const nonEmpty = (value) => (typeof value === "string" && value !== "" ? value : undefined);
+function checkMs(label, ms) {
+    if (typeof ms !== "number" || !Number.isInteger(ms) || ms <= 0 || ms > MAX_TIMER_MS) {
+        throw new RangeError(`${label} must be a whole number of milliseconds, from 1 to ${MAX_TIMER_MS} (got ${String(ms)})`);
+    }
+    return ms;
+}
+function problemWith(name, listing) {
+    const tool = listing.get(name);
+    if (!tool)
+        return `the server has no tool named "${name}"`;
+    if (tool.execution?.taskSupport === "required") {
+        return `tool "${name}" can only run as an MCP task, which @haikit/mcp does not support`;
+    }
+    return null;
+}
+/** What a change to a tool can break: its schemas, and whether it must run as a task. */
+const shape = (tool) => JSON.stringify([tool.inputSchema, tool.outputSchema ?? null, tool.execution?.taskSupport ?? null]);
+function warn(change) {
+    const parts = [
+        ...change.removed.map((name) => `tool "${name}" was removed`),
+        ...change.changed.map((name) => `tool "${name}" changed its schema`),
+    ];
+    const whose = change.user === undefined ? "" : ` (for user ${change.user})`;
+    console.warn(`@haikit/mcp: ${change.server}${whose}: ${parts.join("; ")}`);
+}
+//# sourceMappingURL=index.js.map