message-cp 0.0.0-stage → 0.1.0

package/dist/init.js

@@ -0,0 +1,960 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { accessSync, chmodSync, closeSync, constants, existsSync, fstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { NAME_PATTERN, NOT_REGISTERED, PurgeError, purgeAgent } from "./agents.js";
+import { ConnectError, mcpEndpoint } from "./connect.js";
+import { dbPath, openDb } from "./db.js";
+import { shellQuote } from "./wait.js";
+// `message-cp init`: adds the stdio server `npx -y message-cp` to one coding agent's user-level MCP configuration on
+// this machine, then proves the server works by registering a test agent, sending it a message and reading it back.
+// It never prints a token or key: the test agent's key is made here, stays in memory, and the agent is purged after.
+// With `--url` and `--agent` it adds a team server over HTTP instead, carrying the token from MESSAGE_CP_HTTP_TOKEN in
+// its headers, with the agent's name and its key from MESSAGE_CP_AGENT_KEY unless the token is bound to the agent, and
+// nothing it prints holds the token or key. With `--from` it reads the URL, agent, token and key from the file
+// `message-cp connect` wrote instead, and once the check passes also writes the token to ~/.message-cp/http-token for
+// the wake-up command.
+export class InitError extends Error {
+}
+export const CLIENT_IDS = ["claude-code", "codex", "cursor", "claude-desktop"];
+export const CLIENT_NAMES = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    cursor: "Cursor",
+    "claude-desktop": "Claude Desktop",
+};
+const SERVER_NAME = "message-cp";
+const SERVER_COMMAND = "npx";
+const SERVER_ARGS = ["-y", "message-cp"];
+/** What to run by hand when no client is found, or to add the server to Claude Code yourself. */
+export const MANUAL_ADD = "claude mcp add message-cp -- npx -y message-cp";
+/** Whether an executable named `command` is in one of `path`'s directories (on Windows, also with .exe, .cmd or .bat). */
+export function onPath(command, path, platform = process.platform) {
+    const exts = platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
+    return path
+        .split(platform === "win32" ? ";" : delimiter)
+        .filter(Boolean)
+        .some((dir) => exts.some((ext) => {
+        try {
+            const file = join(dir, command + ext);
+            accessSync(file, platform === "win32" ? constants.F_OK : constants.X_OK);
+            return statSync(file).isFile();
+        }
+        catch {
+            return false;
+        }
+    }));
+}
+/**
+ * Claude Desktop's configuration directory, where its docs put `claude_desktop_config.json`: `~/Library/Application
+ * Support/Claude` on macOS and `%APPDATA%\Claude` on Windows. Its docs give none for Linux, so there it is undefined.
+ */
+export function claudeDesktopDir(m) {
+    if (m.platform === "darwin")
+        return join(m.home, "Library", "Application Support", "Claude");
+    if (m.platform === "win32")
+        return join(m.appData ?? join(m.home, "AppData", "Roaming"), "Claude");
+    return undefined;
+}
+/** The JSON file `init` edits for Cursor or Claude Desktop. */
+export function configFile(client, m) {
+    return client === "cursor" ? join(m.home, ".cursor", "mcp.json") : join(claudeDesktopDir(m), "claude_desktop_config.json");
+}
+/** The clients installed for this user, in `CLIENT_IDS` order. */
+export function detectClients(m) {
+    const desktop = claudeDesktopDir(m);
+    const found = {
+        "claude-code": onPath("claude", m.path, m.platform),
+        codex: onPath("codex", m.path, m.platform),
+        cursor: existsSync(join(m.home, ".cursor")),
+        "claude-desktop": desktop !== undefined && existsSync(desktop),
+    };
+    return CLIENT_IDS.filter((c) => found[c]);
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const STDIO_SERVER = {
+    entry: { command: SERVER_COMMAND, args: SERVER_ARGS },
+    same: (e) => isObject(e) && e.command === SERVER_COMMAND && JSON.stringify(e.args) === JSON.stringify(SERVER_ARGS),
+};
+/**
+ * Adds `server.entry` as `message-cp` to the `mcpServers` of the JSON file `file`, keeping every other key and server.
+ * The new JSON is written to a temporary file beside the real one (through a symlink, beside its target) and renamed
+ * over it, so a failed write leaves the old file whole; an existing file keeps its mode, and a new one is 0600. If the
+ * file changed between the read and the rename, nothing is written and `init` says to run it again. A `message-cp`
+ * entry already there is left as it is: "present" if `server.same` holds for it (by default, if it runs
+ * `npx -y message-cp`), "differs" otherwise. Refuses, changing nothing, a file that is not a JSON object or whose
+ * `mcpServers` is not one, or, for a `secret` entry, a file group or others can read, and turns a file it cannot read
+ * or write into an InitError giving the reason.
+ */
+export function mergeServer(file, server = STDIO_SERVER) {
+    const reason = (err) => err.code ?? (err instanceof Error ? err.message : String(err));
+    let config = {};
+    let text;
+    const current = () => (existsSync(file) ? readFileSync(file, "utf8") : undefined);
+    if (existsSync(file)) {
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch (err) {
+            throw new InitError(`could not read ${file} (${reason(err)}); nothing was changed.`);
+        }
+        try {
+            config = JSON.parse(text);
+        }
+        catch {
+            throw new InitError(`${file} is not valid JSON; it was left unchanged. Fix or move it, then run message-cp init again.`);
+        }
+    }
+    if (!isObject(config))
+        throw new InitError(`${file} does not hold a JSON object; it was left unchanged.`);
+    const servers = config.mcpServers ?? {};
+    if (!isObject(servers))
+        throw new InitError(`${file} has an mcpServers that is not a JSON object; it was left unchanged.`);
+    const readable = (mode) => server.secret === true && process.platform !== "win32" && (mode & 0o044) !== 0;
+    const entry = servers[SERVER_NAME];
+    if (entry !== undefined) {
+        // A secret entry already there is "present" only while no other user can read it.
+        if (server.same(entry) && readable(existsSync(file) ? statSync(file).mode : 0)) {
+            throw new InitError(`${file} holds the token, and other users of this machine can read it; it was left as it is. To make it private, run: chmod 600 ${shellQuote(file)}, then run message-cp init again.`);
+        }
+        return server.same(entry) ? "present" : "differs";
+    }
+    config.mcpServers = { ...servers, [SERVER_NAME]: server.entry };
+    let tmp;
+    try {
+        const target = text === undefined ? file : realpathSync(file);
+        tmp = join(dirname(target), `.${SERVER_NAME}-init-${randomBytes(6).toString("hex")}.tmp`);
+        writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        if (text !== undefined) {
+            // The mode the new file is given, checked here as well as in remoteRefusal, since it may have changed since.
+            const mode = statSync(target).mode & 0o777;
+            if (readable(mode)) {
+                throw new InitError(`${file} became readable by other users of this machine while message-cp init was running; it was left as it is. To make it private, run: chmod 600 ${shellQuote(file)}, then run message-cp init again.`);
+            }
+            chmodSync(tmp, mode);
+        }
+        if (current() !== text) {
+            throw new InitError(`${file} changed while message-cp init was running; it was left as it is. Run message-cp init again.`);
+        }
+        renameSync(tmp, target);
+        tmp = undefined;
+    }
+    catch (err) {
+        if (err instanceof InitError)
+            throw err;
+        throw new InitError(`could not write ${file} (${reason(err)}); it was left as it was.`);
+    }
+    finally {
+        if (tmp !== undefined)
+            rmSync(tmp, { force: true });
+    }
+    return "added";
+}
+/** The `claude` or `codex` command that adds, shows or removes the user-level server. */
+export const cliCommands = {
+    "claude-code": {
+        command: "claude",
+        add: ["mcp", "add", "--scope", "user", SERVER_NAME, "--", SERVER_COMMAND, ...SERVER_ARGS],
+        get: ["mcp", "get", SERVER_NAME],
+        remove: ["mcp", "remove", "--scope", "user", SERVER_NAME],
+    },
+    codex: {
+        command: "codex",
+        add: ["mcp", "add", SERVER_NAME, "--", SERVER_COMMAND, ...SERVER_ARGS],
+        get: ["mcp", "get", SERVER_NAME, "--json"],
+        remove: ["mcp", "remove", SERVER_NAME],
+    },
+};
+/** The most `readConnectFile` reads: `connect` writes well under 2 KiB. */
+const MAX_CONNECT_FILE = 64 * 1024;
+/**
+ * The team server in the file `message-cp connect` wrote: the `mcpServers` JSON after its `claude mcp add` line, which
+ * must name exactly one server with a `url` and the three headers `clientSetup` in `src/connect.ts` writes. The URL goes
+ * through `mcpEndpoint`, the check `init --url` uses. Refuses a file it cannot read, one that is not a regular file or
+ * is over 64 KiB, one whose mode is wider than 0600 (except on Windows, which has no such modes), and one without
+ * exactly one usable URL, agent, token and key. No message holds the file's contents.
+ */
+export function readConnectFile(file, platform = process.platform) {
+    const refuse = (why) => new InitError(`${file} ${why}. Nothing was changed.`);
+    let text;
+    let fd;
+    try {
+        // Non-blocking, so a FIFO named by mistake is refused below instead of waiting for a writer.
+        fd = openSync(file, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+        const st = fstatSync(fd);
+        if (!st.isFile())
+            throw refuse("is not a file");
+        if (platform !== "win32" && (st.mode & 0o177) !== 0) {
+            throw refuse(`holds a token and key, and its mode ${(st.mode & 0o777).toString(8).padStart(4, "0")} is wider than 0600; make it private with: chmod 600 ${shellQuote(file)}, then run message-cp init again`);
+        }
+        if (st.size > MAX_CONNECT_FILE)
+            throw refuse("is too large to be what message-cp connect wrote");
+        text = readFileSync(fd, "utf8");
+    }
+    catch (err) {
+        if (err instanceof InitError)
+            throw err;
+        throw new InitError(`could not read ${file} (${err.code ?? (err instanceof Error ? err.message : String(err))}). Nothing was changed.`);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+    const notConnect = (what) => refuse(`${what}; give the file message-cp connect wrote, unchanged`);
+    // The JSON starts at the first line that is only "{"; a parse error is never quoted, since it may quote the token.
+    const start = /^\{[ \t\r]*$/m.exec(text)?.index;
+    let config;
+    try {
+        config = start === undefined ? undefined : JSON.parse(text.slice(start));
+    }
+    catch { }
+    if (!isObject(config) || !isObject(config.mcpServers))
+        throw notConnect("holds no mcpServers JSON");
+    const servers = Object.values(config.mcpServers);
+    if (servers.length !== 1)
+        throw notConnect(`names ${servers.length} servers, not one`);
+    const entry = servers[0];
+    const headers = isObject(entry) && isObject(entry.headers) ? entry.headers : {};
+    const url = isObject(entry) ? entry.url : undefined;
+    const auth = headers.Authorization;
+    const token = typeof auth === "string" ? /^Bearer (.*)$/.exec(auth)?.[1] : undefined;
+    const agent = headers["X-Message-CP-Agent"];
+    const key = headers["X-Message-CP-Agent-Key"];
+    if (typeof url !== "string")
+        throw notConnect("has no server URL");
+    // Printable ASCII with no spaces, so each is a valid header value.
+    const word = (v) => typeof v === "string" && /^[\x21-\x7e]+$/.test(v);
+    if (!word(token))
+        throw notConnect("has no token");
+    if (typeof agent !== "string" || !NAME_PATTERN.test(agent) || agent.toLowerCase() === "all")
+        throw notConnect("has no usable agent name");
+    if (!word(key))
+        throw notConnect("has no agent key");
+    let endpoint;
+    try {
+        endpoint = mcpEndpoint(url);
+    }
+    catch (err) {
+        if (!(err instanceof ConnectError))
+            throw err;
+        throw refuse(`has a server URL init refuses: ${err.message.replace(/^--url /, "it ")}`);
+    }
+    return { endpoint, agent, token, key, from: file };
+}
+/**
+ * Writes `token` to `~/.message-cp/http-token` under `home`, where the wake-up command reads it, as a new 0600 file in a
+ * directory made 0700 if missing; an existing directory keeps its mode. A file already there is never replaced:
+ * "present" if it holds `token` as the wake-up command reads it (`$(cat ...)`, which drops only trailing newlines),
+ * "differs" if it holds anything else, even nothing. Throws an InitError, without the token, if it cannot write the file
+ * (removing what it created), or if the one already there is not a regular file or cannot be read.
+ */
+export function writeTokenFile(home, token) {
+    const dir = join(home, ".message-cp");
+    const file = join(dir, "http-token");
+    const reason = (err) => err.code ?? (err instanceof Error ? err.message : String(err));
+    let fd;
+    try {
+        mkdirSync(dir, { mode: 0o700, recursive: true });
+        // "wx": never through an existing file or symlink, so one made meanwhile is compared below, not overwritten.
+        fd = openSync(file, "wx", 0o600);
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw new InitError(`could not write ${file} (${reason(err)})`);
+    }
+    if (fd !== undefined) {
+        let failed;
+        try {
+            writeFileSync(fd, `${token}\n`);
+        }
+        catch (err) {
+            failed = err;
+        }
+        try {
+            closeSync(fd);
+        }
+        catch (err) {
+            failed ??= err;
+        }
+        if (failed === undefined)
+            return "written";
+        // This run made the file, so a partial one is removed: a rerun then writes it instead of finding it "differs".
+        try {
+            rmSync(file, { force: true });
+        }
+        catch (err) {
+            throw new InitError(`could not write ${file} (${reason(failed)}), nor remove what was written (${reason(err)}); delete it, then run message-cp init again`);
+        }
+        throw new InitError(`could not write ${file} (${reason(failed)})`);
+    }
+    try {
+        // Non-blocking, so a FIFO there (or a symlink to one) is refused below instead of waiting for a writer.
+        fd = openSync(file, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+        if (!fstatSync(fd).isFile())
+            throw new InitError(`${file} is already there but is not a file; it was left as it is`);
+        return readFileSync(fd, "utf8").replace(/\n+$/, "") === token ? "present" : "differs";
+    }
+    catch (err) {
+        if (err instanceof InitError)
+            throw err;
+        throw new InitError(`${file} is already there but could not be read (${reason(err)}); it was left as it is`);
+    }
+    finally {
+        try {
+            if (fd !== undefined)
+                closeSync(fd);
+        }
+        catch {
+            // Only read, so a failed close loses nothing.
+        }
+    }
+}
+/**
+ * The headers a client sends to act as the agent: only `Authorization` for a token bound to it, otherwise the same three
+ * `clientSetup` in `src/connect.ts` prints.
+ */
+export const remoteHeaders = (r) => r.bound
+    ? { Authorization: `Bearer ${r.token}` }
+    : { Authorization: `Bearer ${r.token}`, "X-Message-CP-Agent": r.agent, "X-Message-CP-Agent-Key": r.key ?? "" };
+/**
+ * Whether the header values `get` reads from an existing entry are the ones `r` sends. `get` returns every value under
+ * the name in any case, since header names are case-insensitive and the server reads them in lowercase; a header given
+ * twice is not the same, since the client may send either. For a bound token, the entry an earlier `init` wrote with the
+ * agent's name and key as well is the same too, since the server accepts a bound token with headers naming its own
+ * agent (in any case) and its key, but only when `r` has the key to compare: without it, a key reset since would leave
+ * the client refused while `init` called it set up.
+ */
+function sameHeaders(r, get) {
+    const one = (name) => {
+        const values = get(name);
+        return values.length === 1 ? values[0] : undefined;
+    };
+    if (one("Authorization") !== `Bearer ${r.token}`)
+        return false;
+    if (!r.bound)
+        return Object.entries(remoteHeaders(r)).every(([k, v]) => one(k) === v);
+    if (get("X-Message-CP-Agent").length === 0 && get("X-Message-CP-Agent-Key").length === 0)
+        return true;
+    const agent = one("X-Message-CP-Agent");
+    return typeof agent === "string" && agent.toLowerCase() === r.agent.toLowerCase() && r.key !== undefined && one("X-Message-CP-Agent-Key") === r.key;
+}
+/** `text` with the token and key replaced by `<redacted>`, so no line `init` passes on holds either. */
+export function redact(text, r) {
+    if (r === undefined)
+        return text;
+    for (const secret of [r.token, r.key])
+        if (secret)
+            text = text.replaceAll(secret, "<redacted>");
+    return text;
+}
+/** The `claude mcp add` arguments for the team server, at user scope; the token and key are only in this array. */
+export const claudeRemoteAdd = (r) => [
+    "mcp",
+    "add",
+    "--scope",
+    "user",
+    "--transport",
+    "http",
+    SERVER_NAME,
+    r.endpoint.href,
+    ...Object.entries(remoteHeaders(r)).flatMap(([k, v]) => ["--header", `${k}: ${v}`]),
+];
+/**
+ * The Cursor entry for the team server: `url` and `headers`, with no `type`, as Cursor documents a remote server. An
+ * entry is the same only with the same URL and headers (`sameHeaders`), so one holding an old token or key is not.
+ */
+export const cursorRemote = (r) => ({
+    entry: { url: r.endpoint.href, headers: remoteHeaders(r) },
+    secret: true,
+    same: (e) => isObject(e) &&
+        e.url === r.endpoint.href &&
+        isObject(e.headers) &&
+        sameHeaders(r, (name) => Object.entries(e.headers)
+            .filter(([k]) => k.toLowerCase() === name.toLowerCase())
+            .map(([, v]) => v)),
+});
+/**
+ * Whether `claude mcp get`'s output describes the team server `r` acts as: `Type: http`, its `URL:` and the header
+ * lines (`sameHeaders`), so an entry holding an old token or key is not the same. The output holds the token and key, so
+ * it is only matched, never printed.
+ */
+function sameRemote(stdout, r) {
+    const field = (name) => new RegExp(`^\\s*${name}: (.*)$`, "m").exec(stdout)?.[1]?.trim();
+    const header = (name) => [...stdout.matchAll(new RegExp(`^\\s*${name}: (.*)$`, "gim"))].map((m) => m[1].trim());
+    return field("Type") === "http" && field("URL") === r.endpoint.href && sameHeaders(r, header);
+}
+/** Whether `get`'s output describes a stdio server that runs `npx -y message-cp`. */
+function runsPackage(client, stdout) {
+    if (client === "codex") {
+        try {
+            const t = JSON.parse(stdout).transport;
+            return t?.type === "stdio" && t.command === SERVER_COMMAND && JSON.stringify(t.args) === JSON.stringify(SERVER_ARGS);
+        }
+        catch {
+            return false;
+        }
+    }
+    const field = (name) => new RegExp(`^\\s*${name}: (.*)$`, "m").exec(stdout)?.[1]?.trim();
+    return field("Type") === "stdio" && field("Command") === SERVER_COMMAND && field("Args") === SERVER_ARGS.join(" ");
+}
+const failed = (r, what, remote) => {
+    const detail = redact((r.stderr || r.stdout).trim().split("\n").pop() ?? "", remote);
+    return new InitError(`${what} failed (${r.status === null ? "no exit status" : `exit ${r.status}`})${detail ? `: ${detail}` : ""}.`);
+};
+/**
+ * Why `client` cannot be set up for the team server at `endpoint` on this machine, with what to do by hand, or
+ * undefined if it can. `codex mcp add` takes `--url` but no custom headers and no literal bearer token, so Codex joins
+ * through the server's OAuth flow instead, which init does not run: `codex mcp login`, approved in a browser by a
+ * person with a full or person token of the account; the endpoint is shell-quoted, since a path may hold `&` or `;`.
+ * Claude Desktop takes a team server only as a custom connector in its app. On Windows `claude` is a `.cmd` file that
+ * only a shell can start, and the token must not pass through a shell string. An existing Cursor file that group or
+ * others can read is refused, so the token and key are never written where other users can read them; its mode is left
+ * as it is.
+ */
+export function remoteRefusal(client, m, endpoint) {
+    if (client === "codex") {
+        return `Codex joins a team server through the server's OAuth flow (\`serve --public-url\`), which init does not run: run \`codex mcp add message-cp --url ${shellQuote(endpoint.href)}\`, then \`codex mcp login message-cp\` if add did not start the login, and have a person with a full or person token of the account approve it at the address Codex prints.`;
+    }
+    if (client === "claude-desktop") {
+        return `Claude Desktop takes a team server as a custom connector in its app: in Customize, Connectors, choose Add, then Add custom connector, give it a name and the URL ${endpoint.href}, choose No sign in, and add the three request headers.`;
+    }
+    if (client === "claude-code" && m.platform === "win32") {
+        return "on Windows, message-cp init cannot run `claude mcp add` without passing the token through a shell; run the `claude mcp add` command `message-cp connect` printed instead, or use --client cursor.";
+    }
+    if (client === "cursor" && m.platform !== "win32") {
+        // Checked before the token is written, not after: its mode is the user's to change, not init's.
+        const file = configFile("cursor", m);
+        let mode = 0;
+        try {
+            mode = statSync(file).mode;
+        }
+        catch {
+            // Not there yet: mergeServer makes it 0600.
+        }
+        if ((mode & 0o044) !== 0) {
+            return `${file} would hold the token, and other users of this machine can read it; to make it private, run: chmod 600 ${shellQuote(file)}, then run message-cp init again.`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Adds the server to `client`'s user-level configuration, unless a `message-cp` entry is already there. Claude Code and
+ * Codex go through their own `mcp get` (exit 1 when there is no such server) and `mcp add`; Cursor and Claude Desktop
+ * through `mergeServer`. With `remote`, the entry is the team server over HTTP instead, for Claude Code or Cursor only.
+ */
+export function setUpClient(client, m, run, remote) {
+    const refused = remote === undefined ? undefined : remoteRefusal(client, m, remote.endpoint);
+    if (refused !== undefined)
+        throw new InitError(`${refused} Nothing was changed.`);
+    if (client === "cursor" || client === "claude-desktop") {
+        const file = configFile(client, m);
+        const state = remote === undefined ? mergeServer(file) : mergeServer(file, cursorRemote(remote));
+        return { client, state, changed: `in ${file}`, undo: `delete the "${SERVER_NAME}" entry under "mcpServers" in ${file}` };
+    }
+    const c = cliCommands[client];
+    const undo = [c.command, ...c.remove].join(" ");
+    // With `remote`, what is shown leaves out the headers, which hold the token (and key).
+    const add = remote === undefined ? c.add : claudeRemoteAdd(remote);
+    const target = remote === undefined ? [c.command, ...c.add].join(" ") : `${c.command} mcp add --scope user --transport http ${SERVER_NAME} ${shellQuote(remote.endpoint.href)}`;
+    const got = run(c.command, c.get);
+    const headers = remote?.bound ? "the token's Authorization header" : "the agent's three headers";
+    const changed = remote === undefined ? `with \`${target}\`` : `with \`${target}\` and ${headers}`;
+    if (got.status === 0) {
+        const same = remote === undefined ? runsPackage(client, got.stdout) : sameRemote(got.stdout, remote);
+        return { client, state: same ? "present" : "differs", changed, undo };
+    }
+    if (got.status !== 1)
+        throw failed(got, [c.command, ...c.get].join(" "), remote);
+    const added = run(c.command, add);
+    if (added.status !== 0)
+        throw failed(added, target, remote);
+    return { client, state: "added", changed, undo };
+}
+/**
+ * Runs `claude` and `codex` from an empty temporary directory, so `mcp get` sees the user-level server and not a
+ * project's `.mcp.json` or local entry for the directory `init` happens to run in.
+ */
+export const realRunner = (command, args) => {
+    const cwd = mkdtempSync(join(tmpdir(), "message-cp-init-"));
+    try {
+        // `claude` and `codex` are `.cmd` files on Windows, which only a shell can start; the arguments are fixed words.
+        const r = spawnSync(command, args, { cwd, encoding: "utf8", shell: process.platform === "win32", timeout: 60_000 });
+        // Not started, timed out or killed: no exit status, and the reason in place of empty stderr.
+        const why = r.error?.message ?? (r.signal ? `killed by ${r.signal}` : "");
+        return { status: r.error ? null : r.status, stdout: r.stdout ?? "", stderr: r.stderr || why };
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+};
+/**
+ * The stdio server of the package running `init`: `npx -y message-cp` resolves only once the package is published.
+ * This is the built `dist/index.js` next to `dist/init.js`; run from `src/` with tsx, there is no `src/index.js`.
+ */
+export const ownServer = () => ({
+    command: process.execPath,
+    args: [fileURLToPath(new URL("./index.js", import.meta.url))],
+});
+const CALL_TIMEOUT_MS = 15_000;
+/**
+ * Starts `server` over stdio with `env` and the database `dbPath(env)`, registers a test agent with a random name in the
+ * owner account, sends it a message from itself and reads it back. The test agent and its messages are then purged with
+ * `purgeAgent` from the same database, even when a step failed. Throws an InitError that names the step that failed
+ * (with the last line the server wrote to stderr, if it wrote any) and any failed clean-up; no message carries the
+ * agent's key.
+ */
+export async function proveServer(server, env = process.env) {
+    const db = dbPath(env);
+    const name = `init-check-${randomBytes(10).toString("hex")}`;
+    // Made here, so register returns no key, and the agent can be removed even if register's reply was lost.
+    const key = randomBytes(24).toString("hex");
+    const body = `message-cp init check ${name}`;
+    // The child acts only as the test agent: an agent named in the environment would be registered by the server first.
+    const childEnv = {};
+    for (const [k, v] of Object.entries(env))
+        if (v !== undefined && k !== "MESSAGE_CP_AGENT" && k !== "MESSAGE_CP_AGENT_KEY")
+            childEnv[k] = v;
+    childEnv.MESSAGE_CP_DB = db;
+    const client = new Client({ name: "message-cp-init", version: "1.0.0" });
+    let failure;
+    let step = "starting the server";
+    let stderr = "";
+    try {
+        const transport = new StdioClientTransport({ ...server, env: childEnv, stderr: "pipe" });
+        transport.stderr?.on("data", (chunk) => {
+            stderr = (stderr + chunk.toString("utf8")).slice(-4000);
+        });
+        await client.connect(transport, { timeout: CALL_TIMEOUT_MS });
+        const call = async (tool, args) => {
+            step = tool;
+            const result = (await client.callTool({ name: tool, arguments: args }, undefined, { timeout: CALL_TIMEOUT_MS }));
+            const text = result.content?.[0]?.text ?? "";
+            if (result.isError)
+                throw new Error(`${tool} returned an error: ${text.slice(0, 200)}`);
+            return JSON.parse(text);
+        };
+        await call("register", { name, bio: "message-cp init check; removed when the check ends", key });
+        await call("send_message", { to: name, body });
+        const inbox = (await call("read_inbox", {}));
+        if (!inbox.some((m) => m.from === name && m.body === body))
+            throw new Error("read_inbox did not return the message just sent");
+    }
+    catch (err) {
+        failure = err;
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+    let cleanup;
+    try {
+        const conn = openDb(db);
+        try {
+            // Only the registration this check made, the live agent holding its key: if register met an agent that already
+            // had the name, or the name has since been taken over, that agent is not this check's to remove.
+            const keyHash = createHash("sha256").update(key).digest("hex");
+            conn
+                .transaction(() => {
+                const live = conn
+                    .prepare("SELECT key_hash FROM agents WHERE account_id = (SELECT id FROM accounts WHERE name = 'owner') AND name = ? AND removed_at IS NULL")
+                    .get(name);
+                if (live?.key_hash === keyHash)
+                    purgeAgent(conn, "owner", name);
+            })
+                .immediate();
+        }
+        catch (err) {
+            // Not registered: there is nothing to remove.
+            if (!(err instanceof PurgeError))
+                throw err;
+        }
+        finally {
+            conn.close();
+        }
+    }
+    catch (err) {
+        cleanup = err;
+    }
+    const say = (err) => (err instanceof Error ? err.message : String(err)).replaceAll(key, "<redacted>");
+    if (failure !== undefined || cleanup !== undefined) {
+        const parts = [];
+        if (failure !== undefined) {
+            const last = stderr.trim().split("\n").pop()?.trim();
+            parts.push(`${step}: ${say(failure)}${last ? ` (server: ${say(last).slice(0, 300)})` : ""}`);
+        }
+        if (cleanup !== undefined)
+            parts.push(`could not remove the test agent '${name}' (${say(cleanup)}); remove it with: message-cp agent remove ${name}`);
+        throw new InitError(parts.join("; "));
+    }
+}
+/** A client of the team server `r`, sending `headers` on every request. */
+function remoteClient(r, headers) {
+    const client = new Client({ name: "message-cp-init", version: "1.0.0" });
+    const transport = new StreamableHTTPClientTransport(r.endpoint, { requestInit: { headers } });
+    return { client, transport };
+}
+/**
+ * Ends the session `transport` holds with DELETE /mcp, waiting at most `ms` for it, then closes the client, which
+ * aborts a DELETE still pending; neither failure matters, since the server ends an idle session itself.
+ */
+export async function endSession(client, transport, ms = CALL_TIMEOUT_MS) {
+    if (transport.sessionId !== undefined) {
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(resolve, ms);
+        });
+        await Promise.race([transport.terminateSession().catch(() => { }), timeout]);
+        clearTimeout(timer);
+    }
+    await client.close().catch(() => { });
+}
+/** The server's own message from a refusal: the `error.message` of the JSON body the SDK quotes, if there is one. */
+function serverMessage(err) {
+    const json = /\{.*\}/s.exec(err.message)?.[0];
+    try {
+        const message = JSON.parse(json ?? "").error?.message;
+        if (typeof message === "string")
+            return message.replace(/\.$/, "");
+    }
+    catch { }
+    return err.message;
+}
+/** Calls `tool` and returns its parsed JSON result, throwing an Error with the tool's own text when it fails. */
+async function callTool(client, tool, args) {
+    const result = (await client.callTool({ name: tool, arguments: args }, undefined, { timeout: CALL_TIMEOUT_MS }));
+    const text = result.content?.[0]?.text ?? "";
+    if (result.isError)
+        throw new Error(`${tool} returned an error: ${text.slice(0, 200)}`);
+    return JSON.parse(text);
+}
+/**
+ * Checks the token, and the agent's key if there is one, before anything is written, and returns whether the token is
+ * bound to the agent. A session that sends only the token finds the agent with `get_agent`, since a session that names
+ * an agent registers it, and `init` makes no agent. On that session `read_conversation` (which marks nothing read) fails
+ * as not registered for an unbound token; for a bound one it succeeds, and `register` with a random name, refused before
+ * it does anything, says which agent the token is: one bound to another agent is refused. Then, with a key, a session
+ * with the three headers an unbound token's client sends, which acts as the agent from its first request. Every session
+ * is ended. Throws an InitError that says which was refused: the token (401, or 403 for a read-only one), the agent's
+ * name (not on the server, or not the bound token's agent) or its key (403, or none for an unbound token), or that the
+ * server could not be reached. No message holds the token or key.
+ */
+export async function checkRemote(r) {
+    const tokenIn = r.from === undefined ? "the token in MESSAGE_CP_HTTP_TOKEN" : `the token in ${r.from}`;
+    const keyIn = r.from === undefined ? "the key in MESSAGE_CP_AGENT_KEY" : `the key in ${r.from}`;
+    const refusal = (err, named) => {
+        const why = err instanceof Error ? err : new Error(String(err));
+        const code = why instanceof StreamableHTTPError ? why.code : undefined;
+        const message = redact(serverMessage(why), r).slice(0, 300);
+        if (code === 401)
+            return new InitError(`the server refused ${tokenIn} (401)`);
+        if (code === 403 && !named)
+            return new InitError(`the server refused ${tokenIn} (403): ${message}`);
+        if (code === 403)
+            return new InitError(`the server refused agent '${r.agent}' with ${keyIn} (403): ${message}`);
+        return new InitError(`could not open a session at ${r.endpoint.href}: ${message}`);
+    };
+    const said = (err) => redact(err instanceof Error ? err.message : String(err), r);
+    const plain = remoteClient(r, { Authorization: `Bearer ${r.token}` });
+    let bound = false;
+    try {
+        try {
+            await plain.client.connect(plain.transport, { timeout: CALL_TIMEOUT_MS });
+        }
+        catch (err) {
+            throw refusal(err, false);
+        }
+        let agent;
+        try {
+            agent = await callTool(plain.client, "get_agent", { name: r.agent });
+        }
+        catch (err) {
+            const message = said(err);
+            if (/No agent named/.test(message)) {
+                throw new InitError(`the server has no agent named '${r.agent}'; make it on the server with: message-cp connect ${shellQuote(r.agent)} --url <public url>`);
+            }
+            throw new InitError(`get_agent: ${message.slice(0, 300)}`);
+        }
+        if (agent.person)
+            throw new InitError(`'${r.agent}' is a person on the server, not an agent`);
+        try {
+            await callTool(plain.client, "read_conversation", { name: r.agent, limit: 1 });
+            bound = true;
+        }
+        catch (err) {
+            const message = said(err);
+            if (!message.includes(NOT_REGISTERED))
+                throw new InitError(`read_conversation: ${message.slice(0, 300)}`);
+        }
+        if (bound) {
+            // Refused before it does anything, so nothing is registered: its message names the token's agent.
+            const name = `init-check-${randomBytes(10).toString("hex")}`;
+            let refused = null;
+            try {
+                await callTool(plain.client, "register", { name, bio: "message-cp init check", key: randomBytes(24).toString("hex") });
+            }
+            catch (err) {
+                refused = /This token is already agent '([^']*)'/.exec(err instanceof Error ? err.message : "");
+                if (!refused)
+                    throw new InitError(`register: ${said(err).slice(0, 300)}`);
+            }
+            if (!refused)
+                throw new InitError(`register: the token could read as an agent but could also register '${name}'; remove it on the server with: message-cp agent remove ${name}`);
+            if (refused[1].toLowerCase() !== r.agent.toLowerCase()) {
+                throw new InitError(`${tokenIn} is bound to agent '${refused[1]}', not '${r.agent}'`);
+            }
+        }
+    }
+    finally {
+        await endSession(plain.client, plain.transport);
+    }
+    if (r.key === undefined) {
+        if (bound)
+            return true;
+        throw new InitError(r.from === undefined
+            ? `${tokenIn} is not bound to agent '${r.agent}', so it needs the agent's key: set MESSAGE_CP_AGENT_KEY, or use the token message-cp connect printed`
+            : `${tokenIn} is not bound to agent '${r.agent}', and there is no key to go with it`);
+    }
+    const named = remoteClient(r, { Authorization: `Bearer ${r.token}`, "X-Message-CP-Agent": r.agent, "X-Message-CP-Agent-Key": r.key });
+    try {
+        await named.client.connect(named.transport, { timeout: CALL_TIMEOUT_MS });
+    }
+    catch (err) {
+        throw refusal(err, true);
+    }
+    finally {
+        await endSession(named.client, named.transport);
+    }
+    return bound;
+}
+/**
+ * Proves the team server works as `proveServer` does over stdio, without touching the configured agent (except with a
+ * bound token, below): on a session
+ * that sends only the token, registers a test agent with a random name and a key made here, sends it a message from
+ * itself, reads it back and unregisters it, then ends the session. If a step failed after `register`, it still tries to
+ * remove the test agent by name and key. A token `connect` made is bound to its agent and cannot register another name,
+ * so with one the agent sends itself a message instead and finds it with `read_conversation`, which marks nothing read:
+ * the agent's own unread mail stays unread, and so does the check's message. A bound token whose agent is not `r.agent`
+ * fails at `register` before anything is sent.
+ * Returns what the check did, for `runInit` to print. Throws an InitError naming the failed step and any failed
+ * clean-up; no message holds the token or either key.
+ */
+export async function proveRemote(r) {
+    const name = `init-check-${randomBytes(10).toString("hex")}`;
+    const key = randomBytes(24).toString("hex");
+    const body = `message-cp init check ${name}`;
+    const { client, transport } = remoteClient(r, { Authorization: `Bearer ${r.token}` });
+    const say = (err) => redact(err instanceof Error ? err.message : String(err), r).replaceAll(key, "<redacted>").slice(0, 300);
+    let step = "opening a session";
+    let registered = false;
+    let failure;
+    let cleanup;
+    let bound = false;
+    const call = (tool, args) => callTool(client, tool, args);
+    try {
+        await client.connect(transport, { timeout: CALL_TIMEOUT_MS });
+        step = "register";
+        // Counted as registered before the reply, which may be lost after the server has acted on it.
+        registered = true;
+        try {
+            await call("register", { name, bio: "message-cp init check; removed when the check ends", key });
+        }
+        catch (err) {
+            const refused = /This token is already agent '([^']*)'/.exec(err instanceof Error ? err.message : "");
+            if (!refused)
+                throw err;
+            // Refused, so nothing was registered: the token is the agent, which proves the server by itself, but only when it
+            // is the agent this setup names, so the check never messages another agent.
+            registered = false;
+            if (refused[1].toLowerCase() !== r.agent.toLowerCase())
+                throw new Error(`the token is agent '${refused[1]}', not '${r.agent}'`);
+            bound = true;
+        }
+        if (bound) {
+            step = "send_message";
+            const self = `message-cp init check ${randomBytes(10).toString("hex")}`;
+            await call("send_message", { to: r.agent, body: self });
+            step = "read_conversation";
+            const sent = (await call("read_conversation", { name: r.agent, limit: 5 }));
+            if (!sent.some((m) => m.body === self))
+                throw new Error("read_conversation did not return the message just sent");
+            await endSession(client, transport);
+            return `as agent '${r.agent}' on the server, sent itself a message and found it with read_conversation; it stays unread in the agent's inbox.`;
+        }
+        step = "send_message";
+        await call("send_message", { to: name, body });
+        step = "read_inbox";
+        const inbox = (await call("read_inbox", {}));
+        if (!inbox.some((m) => m.from === name && m.body === body))
+            throw new Error("read_inbox did not return the message just sent");
+        step = "unregister";
+        await call("unregister", {});
+        registered = false;
+    }
+    catch (err) {
+        failure = err;
+    }
+    if (registered) {
+        try {
+            await call("unregister", { name, key });
+        }
+        catch (err) {
+            // Never registered: nothing to remove.
+            if (!/No agent named/i.test(err instanceof Error ? err.message : ""))
+                cleanup = err;
+        }
+    }
+    await endSession(client, transport);
+    if (failure !== undefined || cleanup !== undefined) {
+        const parts = [];
+        if (failure !== undefined)
+            parts.push(`${step}: ${say(failure)}`);
+        if (cleanup !== undefined)
+            parts.push(`could not remove the test agent '${name}' (${say(cleanup)}); remove it on the server with: message-cp agent remove ${name}`);
+        throw new InitError(parts.join("; "));
+    }
+    return "registered a test agent on the server, sent it a message, read it back and removed it.";
+}
+/** `message-cp init`: returns the exit code, 0 only when the client is set up and the check passed. */
+export async function runInit(o) {
+    const found = detectClients(o.machine);
+    const names = (ids) => ids.map((c) => CLIENT_NAMES[c]).join(", ");
+    if (found.length === 0) {
+        o.err("message-cp init: found none of Claude Code, Codex, Cursor or Claude Desktop. Nothing was changed.");
+        o.err(`To add message-cp to Claude Code by hand: ${MANUAL_ADD}`);
+        return 1;
+    }
+    o.out(`message-cp init: found ${names(found)}.`);
+    let client = o.client;
+    if (client !== undefined) {
+        if (!found.includes(client)) {
+            o.err(`message-cp init: ${CLIENT_NAMES[client]} was not found on this machine. Nothing was changed.`);
+            return 1;
+        }
+    }
+    else if (found.length === 1) {
+        client = found[0];
+    }
+    else if (!o.interactive) {
+        o.err("message-cp init: more than one client was found, so choose one with --client:");
+        for (const c of found)
+            o.err(`  message-cp init --client ${c}`);
+        o.err("Nothing was changed.");
+        return 1;
+    }
+    else {
+        found.forEach((c, i) => o.out(`  ${i + 1}) ${CLIENT_NAMES[c]}`));
+        const answer = (await o.ask(`Set up which? [1-${found.length}] `)).trim();
+        if (answer === "") {
+            o.err("message-cp init: no client was chosen. Nothing was changed.");
+            return 1;
+        }
+        const n = Number(answer);
+        if (!/^[0-9]+$/.test(answer) || n < 1 || n > found.length) {
+            o.err(`message-cp init: '${answer}' is not one of 1-${found.length}. Nothing was changed.`);
+            return 1;
+        }
+        client = found[n - 1];
+    }
+    const remote = o.remote === undefined ? undefined : { ...o.remote };
+    if (remote !== undefined) {
+        const refused = remoteRefusal(client, o.machine, remote.endpoint);
+        if (refused !== undefined) {
+            o.err(`message-cp init: ${refused} Nothing was changed.`);
+            return 1;
+        }
+        try {
+            remote.bound = (await (o.check ?? checkRemote)(remote)) === true;
+        }
+        catch (err) {
+            if (!(err instanceof InitError))
+                throw err;
+            o.err(`message-cp init: ${redact(err.message, remote)}. Nothing was changed.`);
+            return 1;
+        }
+        o.out(remote.key === undefined
+            ? `Server: ${remote.endpoint.href} accepted the token, which is agent '${remote.agent}'.`
+            : remote.bound
+                ? `Server: ${remote.endpoint.href} accepted the token, which is agent '${remote.agent}', and its key.`
+                : `Server: ${remote.endpoint.href} accepted the token, and agent '${remote.agent}' with its key.`);
+    }
+    let setUp;
+    try {
+        setUp = setUpClient(client, o.machine, o.run, remote);
+    }
+    catch (err) {
+        if (!(err instanceof InitError))
+            throw err;
+        o.err(`message-cp init: ${redact(err.message, remote)}`);
+        return 1;
+    }
+    const label = CLIENT_NAMES[client];
+    if (setUp.state === "differs") {
+        o.err(remote === undefined
+            ? `message-cp init: ${label} already has a server named message-cp that does not run \`npx -y message-cp\`; it was left as it is.`
+            : `message-cp init: ${label} already has a server named message-cp that is not ${remote.endpoint.href} as agent '${remote.agent}' with this ${remote.key === undefined ? "token" : "token and key"}; it was left as it is.`);
+        if (remote?.bound && remote.key === undefined) {
+            o.err("If it is an earlier init's entry with the agent's name and key, set MESSAGE_CP_AGENT_KEY so init can check that key, or remove it so init writes the token alone.");
+        }
+        o.err(`To remove it, then run message-cp init again: ${setUp.undo}`);
+        return 1;
+    }
+    o.out(setUp.state === "added" ? `${label}: added message-cp ${setUp.changed}.` : `${label}: already set up; nothing was changed.`);
+    let proved;
+    try {
+        proved = await o.prove();
+    }
+    catch (err) {
+        o.err(`Check failed: ${redact(err instanceof Error ? err.message : String(err), remote)}`);
+        o.err(`The ${label} configuration was kept. To undo it: ${setUp.undo}`);
+        return 1;
+    }
+    o.out(proved
+        ? `Check passed: ${proved}`
+        : remote === undefined
+            ? "Check passed: started the stdio server, registered a test agent, sent it a message, read it back and removed it."
+            : "Check passed: registered a test agent on the server, sent it a message, read it back and removed it.");
+    o.out(`To undo: ${setUp.undo}`);
+    if (remote?.from === undefined)
+        return 0;
+    const tokenFile = join(o.machine.home, ".message-cp", "http-token");
+    let state;
+    try {
+        state = writeTokenFile(o.machine.home, remote.token);
+    }
+    catch (err) {
+        if (!(err instanceof InitError))
+            throw err;
+        o.err(`message-cp init: ${label} was set up and the check passed, but ${redact(err.message, remote)}; the wake-up command reads the token from that file when MESSAGE_CP_HTTP_TOKEN is not set.`);
+        return 1;
+    }
+    if (state === "differs") {
+        // Any token of the account wakes the agent, so a different one is not an error, but it is never replaced unasked.
+        o.err(`message-cp init: ${tokenFile} is already there and does not hold this token, so it was left as it is; the wake-up command reads the token from it when MESSAGE_CP_HTTP_TOKEN is not set.`);
+        o.err(`To use this agent's token there instead, delete ${tokenFile}, then run message-cp init --from ${shellQuote(remote.from)} again.`);
+        // The rerun needs the file, so it is not called deletable yet.
+        o.err(`Once that is done, or you keep the token already there, ${remote.from} can be deleted, and its copy on the server.`);
+        return 0;
+    }
+    o.out(state === "written" ? `Wake-up token: wrote ${tokenFile}.` : `Wake-up token: ${tokenFile} already holds this token.`);
+    o.out(`${remote.from} can now be deleted, and its copy on the server.`);
+    return 0;
+}
+/** Asks one question on the terminal and returns the answer ("" at end of input). */
+export async function askOnTerminal(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        // Ctrl-C or the end of input closes the interface without answering the question: no answer.
+        return await new Promise((resolve) => {
+            rl.once("close", () => resolve(""));
+            rl.question(question).then(resolve, () => resolve(""));
+        });
+    }
+    finally {
+        rl.close();
+    }
+}