message-cp 0.0.0-stage → 0.1.0

package/dist/server.js

@@ -0,0 +1,420 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, MAX_STATUS_LENGTH, NOT_REGISTERED, STATUS_TTL_MS, ToolError, getAgent, listAgents, markWaiting, nameOfIdentity, registerWithIdentity, removeAgent, setStatus, touchAgent, } from "./agents.js";
+import { OWNER_ACCOUNT } from "./db.js";
+import { issueListenToken } from "./accounts.js";
+import { DEFAULT_WAIT_HOLD_MS, formatUnread, httpWaitCommand, instructions, listenWaitCommand, saveListenToken, waitCommand } from "./wait.js";
+import { DEFAULT_INBOX_LIMIT, MAX_BODY_LENGTH, MAX_INBOX_LIMIT, MAX_SEARCH_LENGTH, hasUnread, messageStatus, readConversation, readInbox, search, sendMessage, sendQuestion, takeReply, unreadSummary, } from "./messages.js";
+import { DEFAULT_CHANNEL_LIMIT, MAX_CHANNEL_LIMIT, joinChannel, leaveChannel, listChannels, post, readChannel, } from "./channels.js";
+/**
+ * Who this server process is acting as. Over HTTP, `serve` also records a registered session's registration in the
+ * database under a hash of its session id, so that a restarted server can restore it; over stdio it lives only in
+ * memory. Every use is checked against the registration it was made for: once that is removed the session is
+ * unregistered again.
+ * A session belongs to one account for its whole life, and every tool reads and writes only that account's agents
+ * and messages: the owner's for stdio, the account of the token that started it over HTTP.
+ */
+export class Session {
+    account;
+    onBind;
+    identity;
+    db;
+    /**
+     * No default, so a caller has to say which account a session acts as. `onBind` is told each registration the
+     * session is bound to.
+     */
+    constructor(account, onBind) {
+        this.account = account;
+        this.onBind = onBind;
+    }
+    /** The database the identity is checked against. `createServer` calls this. */
+    attach(db) {
+        this.db = db;
+    }
+    bind(identity) {
+        this.identity = identity;
+        this.onBind?.(identity);
+    }
+    /** Binds the session to a registration that is already recorded, as a restore does, without telling `onBind`. */
+    restore(identity) {
+        this.identity = identity;
+    }
+    /** The registration this session belongs to, as last checked by `current`/`require`. */
+    get registration() {
+        return this.identity;
+    }
+    /** The agent's name, or undefined if unregistered or the registration was removed. */
+    current() {
+        if (!this.identity || !this.db)
+            return undefined;
+        const name = nameOfIdentity(this.db, this.account, this.identity);
+        if (name === undefined)
+            this.identity = undefined;
+        return name;
+    }
+    /** For tools that need the caller's row as well as its name: channel read positions belong to the registration. */
+    requireAgent() {
+        const name = this.require();
+        return { ...this.identity, name };
+    }
+    /** For tools that need to know the caller. */
+    require() {
+        const name = this.current();
+        if (!name)
+            throw new ToolError(NOT_REGISTERED);
+        return name;
+    }
+}
+/** Most held calls at once: sessions, waiting GET /wait requests and held `wait_for_mail` and `ask` calls each have this cap. */
+export const DEFAULT_MAX_SESSIONS = 256;
+/** How long `wait_for_mail` holds a call with no mail by default, and at most, in seconds. */
+export const DEFAULT_WAIT_FOR_MAIL_SECONDS = 50;
+export const MAX_WAIT_FOR_MAIL_SECONDS = DEFAULT_WAIT_HOLD_MS / 1000;
+export const WAIT_FOR_MAIL_FULL = "Too many calls are waiting for mail on this server. Try again shortly.";
+export const ASK_FULL = "Too many calls are waiting on this server. Try again shortly; nothing was sent.";
+// The held `wait_for_mail` and `ask` calls of every server in this process that was not given a `hold`, as over stdio.
+let held = 0;
+const holdInProcess = () => {
+    if (held >= DEFAULT_MAX_SESSIONS)
+        return undefined;
+    held++;
+    return () => void held--;
+};
+/** Runs one check; a lock held past the busy timeout counts as finding nothing this time, as in `message-cp wait`. */
+function check(run, nothing) {
+    try {
+        return run();
+    }
+    catch (err) {
+        const code = err?.code;
+        if (typeof code !== "string" || !code.startsWith("SQLITE_BUSY"))
+            throw err;
+        return nothing;
+    }
+}
+const NOTHING_UNREAD = { count: 0, senders: [], posts: 0, channels: [], mentions: 0, mentionChannels: [] };
+/** Waits `ms`, or less if `signal` aborts first; the timer and listener are removed either way. */
+const sleep = (ms, signal) => new Promise((resolve) => {
+    if (signal.aborted)
+        return resolve();
+    const done = () => {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", done);
+        resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done);
+});
+/**
+ * Runs `answer` about once a second until it returns something, which `poll` returns, or until `deadline` passes or
+ * `signal` aborts, when it returns undefined. Whatever `answer` throws ends the poll.
+ */
+async function poll(deadline, signal, answer) {
+    for (;;) {
+        const left = deadline - Date.now();
+        if (left <= 0)
+            return undefined;
+        // Sleep a second, or until the call is cancelled or its client goes away; nobody is listening then.
+        await sleep(Math.min(1000, left), signal);
+        if (signal.aborted)
+            return undefined;
+        const found = answer();
+        if (found !== undefined)
+            return found;
+    }
+}
+/** One server per session. */
+export function createServer(db, session = new Session(OWNER_ACCOUNT), options = {}) {
+    const remote = options.remote ?? false;
+    const hold = options.hold ?? holdInProcess;
+    session.attach(db);
+    const account = session.account;
+    const server = new McpServer({ name: "message-cp", version: "0.1.0" }, { instructions: instructions(process.env, remote, options.publicUrl, options.agent, options.approval, session.account) });
+    // Aborts when the call is cancelled or, where the transport knows it, the response that would carry its answer closes.
+    const ended = (extra) => {
+        const closed = options.closed?.(extra.requestId);
+        return closed ? AbortSignal.any([extra.signal, closed]) : extra.signal;
+    };
+    // Over HTTP, a request whose token is bound to an agent carries that agent's name; such a token is that agent already.
+    const refuseBound = (extra) => {
+        const agent = extra.authInfo?.extra?.agent;
+        if (typeof agent === "string")
+            throw new ToolError(`This token is already agent '${agent}'; it cannot register or remove another name.`);
+    };
+    // Over HTTP, a request whose token registers its own agents carries that token's row id, which `register` and
+    // `unregister` check each agent against.
+    const registering = (extra) => {
+        const token = extra.authInfo?.extra?.registers;
+        return typeof token === "number" ? token : undefined;
+    };
+    // Over HTTP, a request whose token came from an approval carries that token's row id, which a listen token is issued through.
+    const approvalOf = (extra) => {
+        const token = extra.authInfo?.extra?.approval;
+        return typeof token === "number" ? token : undefined;
+    };
+    /** A listen token for the session's registration through approval `approval`, with how to save it and its wait command. */
+    const listen = (approval, identity, name) => {
+        const token = options.publicUrl ? issueListenToken(db, account, identity, approval) : undefined;
+        // The registration was checked just before, so a refusal means the approval was revoked or the agent removed since.
+        if (token === undefined)
+            throw new ToolError("No listen token: this session's approval was revoked or its agent removed.");
+        return { listenToken: token, saveListenToken: saveListenToken(options.publicUrl, account, name), waitCommand: listenWaitCommand(options.publicUrl, account, name) };
+    };
+    // Wraps a tool: bumps last-seen for a registered session and turns ToolError into an error result.
+    const tool = (run) => async (args, extra) => {
+        // Touch first so a failing call still counts. `register` sets last-seen itself.
+        const name = session.current();
+        if (name)
+            touchAgent(db, account, name);
+        try {
+            const result = await run(args, extra);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            if (err instanceof ToolError) {
+                return { isError: true, content: [{ type: "text", text: err.message }] };
+            }
+            throw err;
+        }
+    };
+    server.registerTool("register", {
+        description: "Register this session as an agent with a name and short bio. A new name without a key you pass returns a generated key, once: keep it (if you pass your own key, nothing is returned). If the name exists (any case), this session takes that agent over and its bio is updated, but only with the agent's key; an agent registered before keys existed is claimed by the first call and gets a key. When the server can offer one, it returns waitCommand: run it in the background to be woken by unread messages, by unread posts in the channels you have joined and by unread @mentions of you; when it fires, call read_inbox if it names messages or mentions and read_channel for each channel it names posts in, and only then start it again. Over HTTP, a session connected by approval also gets listenToken, once, and saveListenToken, which says how to save it privately to the file for this agent that its waitCommand reads (see listen_token). When it returns no waitCommand, or your client cannot run a background command, call wait_for_mail instead, and call it again whenever it returns unread null. A session whose token is bound to one agent is that agent already, and register fails there. A session whose token was approved to register its own agents registers a name no agent or person of the account has, or takes back an agent that same token registered and that is still registered; it is refused any other agent, takes no key and returns none, since the token is that agent's credential.",
+        inputSchema: {
+            name: z.string().describe("1-32 characters: letters, digits, '-' and '_'. 'all' is reserved."),
+            bio: z.string().describe("A short description of who you are and what you work on."),
+            key: z.string().optional().describe("The agent's key, required to take over an existing agent that has one."),
+        },
+    }, tool(({ name, bio, key }, extra) => {
+        refuseBound(extra);
+        const { result, identity } = registerWithIdentity(db, account, name, bio, key, registering(extra));
+        session.bind(identity);
+        if (!remote)
+            return { ...result, waitCommand: waitCommand(result.name) };
+        const approval = approvalOf(extra);
+        if (approval !== undefined && options.publicUrl)
+            return { ...result, ...listen(approval, identity, result.name) };
+        return options.publicUrl ? { ...result, waitCommand: httpWaitCommand(options.publicUrl, result.name) } : result;
+    }));
+    if (options.approval && options.publicUrl) {
+        server.registerTool("listen_token", {
+            description: "Get a new listen token for the agent this session is, connected by approval: a token that can only wait for this agent's mail on GET /wait, which the waitCommand returned here reads from its own file for this agent. Returns listenToken, once, saveListenToken (how to save it privately to that file) and waitCommand. A new one replaces the agent's earlier listen token, which stops working. It stops working too when the agent is removed or unregistered or the approval is revoked; then the command exits with a 401 or 404 error. Requires register first, unless the approval was for this one agent.",
+            inputSchema: {},
+        }, tool((_args, extra) => {
+            const own = session.requireAgent();
+            const approval = approvalOf(extra);
+            if (approval === undefined)
+                throw new ToolError("Only a session connected by approval gets a listen token.");
+            return listen(approval, own, own.name);
+        }));
+    }
+    server.registerTool("unregister", {
+        description: "Remove an agent from the directory and free its name. The messages addressed to it are kept in the database, until a full token deletes their conversation over HTTP, but no tool shows them again, not even to a new agent that registers the same name; keptMessages says how many. With no arguments it removes you, and this session is unregistered until it calls `register` again (with a token bound to one agent, that token stops working). With name and key it removes that agent, only if the key matches (an agent that has no key can be removed by name alone); name and key work even from a session that has not registered, but not with a token bound to one agent. With a token approved to register its own agents, a name removes only an agent that token registered, without a key, and a key is refused. Any other session still acting as the removed agent is unregistered too. A process started with MESSAGE_CP_AGENT registers that agent again when it starts.",
+        inputSchema: {
+            name: z.string().optional().describe("The agent to remove. Omit to remove yourself."),
+            key: z.string().optional().describe("That agent's key, required if it has one."),
+        },
+    }, tool(({ name, key }, extra) => {
+        if (name !== undefined)
+            refuseBound(extra);
+        if (name === undefined) {
+            if (key !== undefined)
+                throw new ToolError("Pass the name of the agent the key belongs to.");
+            const self = session.require();
+            return removeAgent(db, account, self, undefined, session.registration);
+        }
+        // A token that registers its own agents is its agents' proof, and removes no other.
+        const token = registering(extra);
+        if (token !== undefined)
+            return removeAgent(db, account, name, key, undefined, token);
+        // A name with its key carries its own proof; anything else needs to know who is asking.
+        if (key === undefined)
+            session.require();
+        return removeAgent(db, account, name, key);
+    }));
+    server.registerTool("set_status", {
+        description: `Set your own status line: a short note on what you are doing, such as "reading Linear", which the dashboard shows next to your name in its agents panel and in the header bar of an open direct conversation with you. It replaces any line you set before. It stops showing ${STATUS_TTL_MS / 60000} minutes after it was set, and is cleared when a send_message or post of yours succeeds and when you are unregistered or removed. Empty text, or only spaces, clears it now. Returns status (the line as stored, or null) and expiresAt (null with no line). Sends nothing and marks nothing read. Requires register first.`,
+        inputSchema: {
+            text: z.string().describe(`The line, at most ${MAX_STATUS_LENGTH} characters, or empty or only spaces to clear it. A newline, other control character or bidirectional formatting character is refused.`),
+        },
+    }, tool(({ text }) => setStatus(db, account, session.requireAgent(), text)));
+    server.registerTool("list_agents", {
+        description: `List registered agents, and the people the operator added, by name with their bio, lastSeen (for an agent, when it was last active; for a person, when they were added) and person (true for a person). Returns one page (default ${DEFAULT_LIST_LIMIT}, max ${MAX_LIST_LIMIT}); a full page means there may be more, so call again with a higher offset.`,
+        inputSchema: {
+            limit: z.number().int().min(1).max(MAX_LIST_LIMIT).optional(),
+            offset: z.number().int().min(0).optional(),
+        },
+    }, tool(({ limit, offset }) => listAgents(db, account, limit, offset)));
+    server.registerTool("get_agent", {
+        description: "Get one registered agent, or person, by name (case-insensitive).",
+        inputSchema: { name: z.string() },
+    }, tool(({ name }) => {
+        const agent = getAgent(db, account, name);
+        if (!agent)
+            throw new ToolError(`No agent named '${name}'.`);
+        return agent;
+    }));
+    server.registerTool("send_message", {
+        description: `Send a message to one registered agent or person by name, or to every other registered agent and person with to: 'all'. A broadcast only reaches agents registered, and people added, when it is sent. With in_reply_to, each copy stored records the id of the message it answers, which read_inbox, read_conversation and search return as inReplyTo. Returns delivered (how many copies were stored), recipients (their names) and messages: the id and recipient (to) of each copy stored, one per recipient of a broadcast, which message_status takes. Requires register first.`,
+        inputSchema: {
+            to: z.string().describe("An agent name, or 'all'."),
+            body: z.string().describe(`The message, at most ${MAX_BODY_LENGTH} characters.`),
+            in_reply_to: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("The id of a direct message sent to you, as read_inbox, read_conversation or search returns it, that this one answers. Any other id fails, and nothing is sent."),
+        },
+    }, tool(({ to, body, in_reply_to }) => {
+        const own = session.requireAgent();
+        return sendMessage(db, account, own.name, to, body, own, in_reply_to);
+    }));
+    server.registerTool("message_status", {
+        description: `Say whether messages you sent have been read: takes the ids send_message returned (1 to ${MAX_INBOX_LIMIT}) and returns, for each id once, in the order given, id, to (the recipient, by the name it had if it has since been removed), read and readAt (when its recipient's read_inbox first returned it, or null; a message to a person stays unread, since a person has no read_inbox). Only messages sent under your name since you registered it, to an agent or person of your account, can be asked about; if any id is another (one you did not send, one a removed agent with your name sent, or one that does not exist), the whole call fails with one error that does not say which. Marks nothing read. Requires register first.`,
+        inputSchema: {
+            ids: z.array(z.number().int().positive()).min(1).max(MAX_INBOX_LIMIT).describe("Message ids, as send_message returns them in messages."),
+        },
+    }, tool(({ ids }) => messageStatus(db, account, session.requireAgent(), ids)));
+    server.registerTool("read_inbox", {
+        description: `Read your messages and your mentions (channel posts that name you as @<your-name>), oldest first, one page at a time (default ${DEFAULT_INBOX_LIMIT}, max ${MAX_INBOX_LIMIT}). A message has id (its own), inReplyTo (the id of the message it answers, or null), from, sentAt, body and broadcast; to answer a message, call send_message with in_reply_to set to its id, so that an ask waiting for the answer sees it. A mention has channel, id (the post's), from, sentAt and body. By default only unread ones; everything returned is marked read, so a full page means there may be more: call again. With unread_only false, use offset to page through history. To be woken when mail arrives instead of polling, run the wait command that register returns in the background; when it fires, call read_inbox if it names messages or mentions and read_channel for each channel it names posts in, and only then start it again. Requires register first.`,
+        inputSchema: {
+            unread_only: z.boolean().optional().describe("Default true."),
+            limit: z.number().int().min(1).max(MAX_INBOX_LIMIT).optional(),
+            offset: z.number().int().min(0).optional(),
+        },
+    }, tool(({ unread_only, limit, offset }) => readInbox(db, account, session.requireAgent(), unread_only, limit, offset)));
+    server.registerTool("wait_for_mail", {
+        description: `Wait until you have mail, for a client that cannot run the wait command in the background. Returns { unread } as soon as you have an unread message, an unread post by another agent in a channel you joined or an unread @mention of you, with unread the one line the wait command prints (how many, from whom and in which channels, never the bodies); returns at once if you already have any. Otherwise it checks about once a second, and returns { unread: null } after timeout_seconds without any; a check that finds the database busy counts as nothing unread that second. Reads and marks nothing, so call read_inbox if the line names messages or mentions and read_channel for each channel it names posts in, and only then wait again. When it returns { unread: null }, call it again. Calls held at once are capped, over HTTP together with the server's GET /wait requests and over stdio for the whole process; past the cap it fails at once, so try again shortly. If your agent is removed while you wait, it fails as not registered. Requires register first.`,
+        inputSchema: {
+            timeout_seconds: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_WAIT_FOR_MAIL_SECONDS)
+                .optional()
+                .describe(`How long to wait with no mail, in seconds: default ${DEFAULT_WAIT_FOR_MAIL_SECONDS}, at most ${MAX_WAIT_FOR_MAIL_SECONDS}.`),
+        },
+    }, tool(async ({ timeout_seconds }, extra) => {
+        const own = session.requireAgent();
+        const deadline = Date.now() + (timeout_seconds ?? DEFAULT_WAIT_FOR_MAIL_SECONDS) * 1000;
+        // Each check finds the caller by its registration, so a removed agent, or another that took its name, ends the call.
+        // Once the call holds a slot, a check that finds nothing marks the caller waiting, so a message or mention stored
+        // until the mark ends holds its webhook; one that finds mail does not, so mail left unread is not held by it.
+        let holding = false;
+        const answer = () => {
+            const unread = check(() => unreadSummary(db, account, own), NOTHING_UNREAD);
+            if (!unread)
+                throw new ToolError(NOT_REGISTERED);
+            if (hasUnread(unread))
+                return { unread: formatUnread(unread) };
+            if (holding)
+                markWaiting(db, account, own);
+            return undefined;
+        };
+        // Mail that is already there is answered at once, whatever the cap.
+        const first = answer();
+        if (first)
+            return first;
+        const release = hold();
+        if (!release)
+            throw new ToolError(WAIT_FOR_MAIL_FULL);
+        holding = true;
+        try {
+            markWaiting(db, account, own);
+            return (await poll(deadline, ended(extra), answer)) ?? { unread: null };
+        }
+        finally {
+            release();
+        }
+    }));
+    server.registerTool("ask", {
+        description: `Ask one agent a question and wait for its answer in one call: sends body to the agent to, as send_message does, and holds the call until that agent answers it with send_message and in_reply_to set to the question's id. Returns id (the question's message id) and reply: the earliest such reply, shaped as read_inbox returns a message and marked read, or null if none came within timeout_seconds or the call was cancelled. With reply null, a later answer arrives as an ordinary message: find it with read_inbox or read_conversation by its inReplyTo, the question's id; message_status with the id says only whether the question was read. It checks about once a second; a check that finds the database busy counts as no reply that time. To answer a question someone asks you, call send_message with in_reply_to set to the question's id, so that their ask sees it. 'all' and a person are refused, and nothing is sent. Calls held at once are capped together with wait_for_mail, over HTTP also with the server's GET /wait requests and over stdio for the whole process; past the cap it fails at once and sends nothing, so try again shortly. If your agent is removed while you wait, it fails as not registered. Requires register first.`,
+        inputSchema: {
+            to: z.string().describe("The agent to ask, by name. Not 'all' or a person."),
+            body: z.string().describe(`The question, at most ${MAX_BODY_LENGTH} characters.`),
+            timeout_seconds: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_WAIT_FOR_MAIL_SECONDS)
+                .optional()
+                .describe(`How long to wait for the reply, in seconds: default ${DEFAULT_WAIT_FOR_MAIL_SECONDS}, at most ${MAX_WAIT_FOR_MAIL_SECONDS}.`),
+        },
+    }, tool(async ({ to, body, timeout_seconds }, extra) => {
+        const own = session.requireAgent();
+        // The slot comes first: no reply can exist before the question is sent, so nothing is answered without one.
+        const release = hold();
+        if (!release)
+            throw new ToolError(ASK_FULL);
+        try {
+            const [{ id, to: asked }] = sendQuestion(db, account, own, to, body).messages;
+            // Counted from once the question is stored, so time spent waiting for the write lock to send it is not taken
+            // from the time the other agent has to answer.
+            const deadline = Date.now() + (timeout_seconds ?? DEFAULT_WAIT_FOR_MAIL_SECONDS) * 1000;
+            // Each check finds the caller by its registration, so a removed agent, or another that took its name, ends the call.
+            const answer = () => {
+                const reply = check(() => takeReply(db, account, own, id, asked), null);
+                if (reply === undefined)
+                    throw new ToolError(NOT_REGISTERED);
+                // poll goes on while this returns undefined: no reply yet.
+                return reply ?? undefined;
+            };
+            return { id, reply: (await poll(deadline, ended(extra), answer)) ?? null };
+        }
+        finally {
+            release();
+        }
+    }));
+    server.registerTool("read_conversation", {
+        description: `Read your direct messages with one agent or person: those they sent you and those you sent them, newest first, one page at a time (default ${DEFAULT_INBOX_LIMIT}, max ${MAX_INBOX_LIMIT}); a full page means there may be more, so call again with a higher offset. Each has id (its own), inReplyTo (the id of the message it answers, or null), from, to, sentAt, body and broadcast; a broadcast either of you sent appears as the copy the other received, and a conversation with yourself has no broadcasts. Messages a removed agent with your name sent or received are not included; if the name once belonged to a removed agent, what it sent you is included, but what you sent it is not. Marks nothing read. Requires register first.`,
+        inputSchema: {
+            name: z.string().describe("The other agent or person, in any case."),
+            limit: z.number().int().min(1).max(MAX_INBOX_LIMIT).optional(),
+            offset: z.number().int().min(0).optional(),
+        },
+    }, tool(({ name, limit, offset }) => readConversation(db, account, session.requireAgent(), name, limit, offset)));
+    server.registerTool("search", {
+        description: `Search the messages you have received and your account's channel posts for text, newest first, one page at a time (default ${DEFAULT_INBOX_LIMIT}, max ${MAX_INBOX_LIMIT}); a full page means there may be more, so call again with a higher offset. A message has kind "message", id (its own), inReplyTo (the id of the message it answers, or null), from, sentAt, body and broadcast; a post has kind "post", channel, id (the post's), from, sentAt and body. Marks nothing read and does not move your read position in any channel. Requires register first.`,
+        inputSchema: {
+            text: z.string().describe(`1-${MAX_SEARCH_LENGTH} characters, found anywhere in the body; ASCII letters match in any case, and % and _ are literal.`),
+            channel: z.string().optional().describe("Only this channel's posts, and no messages."),
+            from: z.string().optional().describe("Only what the agent with this name sent, in any case."),
+            since: z.string().optional().describe("A date (2026-10-20) or date and time (2026-10-20T12:00:00Z, seconds, milliseconds and offset optional; UTC when it has no offset): sent at or after it."),
+            until: z.string().optional().describe("A date or date and time, as since: sent before it."),
+            limit: z.number().int().min(1).max(MAX_INBOX_LIMIT).optional(),
+            offset: z.number().int().min(0).optional(),
+        },
+    }, tool(({ text, channel, from, since, until, limit, offset }) => search(db, account, session.requireAgent(), text, { channel, from, since, until }, limit, offset)));
+    server.registerTool("post", {
+        description: `Post to one of your account's channels by name; the channel is created by its first post (or by join_channel). Posting does not join the channel. Every agent in the account can read it, including agents that register later. Naming an agent of your account as @<name> gives it a mention, which wakes it and appears in its read_inbox, whether or not it has joined the channel. Posts are never edited or deleted. Requires register first.`,
+        inputSchema: {
+            channel: z.string().describe("1-32 characters: letters, digits, '-' and '_', compared case-insensitively."),
+            body: z.string().describe(`The post, at most ${MAX_BODY_LENGTH} characters.`),
+        },
+    }, tool(({ channel, body }) => post(db, account, session.requireAgent(), channel, body)));
+    server.registerTool("read_channel", {
+        description: `Read a channel, oldest first, one page at a time (default ${DEFAULT_CHANNEL_LIMIT}, max ${MAX_CHANNEL_LIMIT}). By default the posts after your read position in it (from its first post if you have never read it; your own posts are included, though never counted as unread), and your read position moves past what is returned, so a full page means call again. With unread_only false, use offset to page through the whole history without moving your read position. Requires register first.`,
+        inputSchema: {
+            channel: z.string().describe("The channel's name, in any case."),
+            unread_only: z.boolean().optional().describe("Default true."),
+            limit: z.number().int().min(1).max(MAX_CHANNEL_LIMIT).optional(),
+            offset: z.number().int().min(0).optional().describe("Only with unread_only false; passing it otherwise is an error."),
+        },
+    }, tool(({ channel, unread_only, limit, offset }) => readChannel(db, account, session.requireAgent(), channel, unread_only, limit, offset)));
+    server.registerTool("list_channels", {
+        description: `List your account's channels by name with their post count, last post time (null if nobody has posted yet), how many posts you have not read (your own posts never count) and whether you have joined it. Returns one page (default ${DEFAULT_CHANNEL_LIMIT}, max ${MAX_CHANNEL_LIMIT}); a full page means there may be more, so call again with a higher offset. Requires register first.`,
+        inputSchema: {
+            limit: z.number().int().min(1).max(MAX_CHANNEL_LIMIT).optional(),
+            offset: z.number().int().min(0).optional(),
+        },
+    }, tool(({ limit, offset }) => listChannels(db, account, session.requireAgent(), limit, offset)));
+    server.registerTool("join_channel", {
+        description: `Join one of your account's channels, so the wait command that register returns also wakes you for new posts there. A channel nobody has posted to yet is created. Joining a channel you have never read starts you at its latest post, so its history does not wake you (read_channel with unread_only false still pages through it); joining one you have read before keeps your read position. Requires register first.`,
+        inputSchema: { channel: z.string().describe("1-32 characters: letters, digits, '-' and '_', compared case-insensitively.") },
+    }, tool(({ channel }) => joinChannel(db, account, session.requireAgent(), channel)));
+    server.registerTool("leave_channel", {
+        description: `Leave one of your account's channels, so its posts no longer wake you. Your read position in it stays where it is, and you can still post to it and read it. Requires register first.`,
+        inputSchema: { channel: z.string().describe("The channel's name, in any case.") },
+    }, tool(({ channel }) => leaveChannel(db, account, session.requireAgent(), channel)));
+    return server;
+}

package/dist/sessions.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { nameOfIdentity } from "./agents.js";
+// The registered HTTP sessions `serve` can restore after a restart. Only a hash of each session id is stored, as with
+// tokens and keys: anyone holding the id and the account's token could act as the session's agent.
+const hashSessionId = (id) => createHash("sha256").update(id).digest("hex");
+/** Records that session `id` of `account` is `identity`, replacing what it was before, unless it has ended. */
+export function saveSession(db, id, account, identity, now = Date.now()) {
+    db.prepare(`INSERT INTO http_sessions (hash, account_id, agent_id, registered_at, instance, last_used) VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT (hash) DO UPDATE SET account_id = excluded.account_id, agent_id = excluded.agent_id,
+       registered_at = excluded.registered_at, instance = excluded.instance, last_used = excluded.last_used
+     WHERE http_sessions.ended = 0`).run(hashSessionId(id), account, identity.id, identity.registeredAt, identity.instance, now);
+}
+export function touchSession(db, id, now = Date.now()) {
+    db.prepare("UPDATE http_sessions SET last_used = ? WHERE hash = ? AND ended = 0").run(now, hashSessionId(id));
+}
+/**
+ * Marks session `id` ended for good. The row stays until the idle sweep, so that a server still holding the session,
+ * or a `register` on it there, cannot make it restorable again.
+ */
+export function endSession(db, id, now = Date.now()) {
+    db.prepare("UPDATE http_sessions SET ended = 1, last_used = ? WHERE hash = ?").run(now, hashSessionId(id));
+}
+/** Whether session `id` has been ended by a DELETE, on this server or another one sharing the database. */
+export function sessionEnded(db, id) {
+    return db.prepare("SELECT 1 FROM http_sessions WHERE hash = ? AND ended = 1").get(hashSessionId(id)) !== undefined;
+}
+/**
+ * Forgets every session last used before `cutoff`, and every ended one last used before `endedCutoff`: an ended row is
+ * kept longer, until every server's live copy of the session has met it on a request or been swept as idle.
+ */
+export function forgetIdleSessions(db, cutoff, endedCutoff) {
+    db.prepare("DELETE FROM http_sessions WHERE last_used < ? AND (ended = 0 OR last_used < ?)").run(cutoff, endedCutoff);
+}
+/**
+ * The identity session `id` was registered as, if it belongs to `account`, has not ended, was used at or after `cutoff`
+ * and its registration is still the agent's current one. A session whose agent was removed is forgotten, so it is never
+ * restored, not even as a later agent with the same name. Another account's session is left alone and looks like none,
+ * and an ended one keeps its row.
+ */
+export function restorableSession(db, id, account, cutoff) {
+    const hash = hashSessionId(id);
+    const row = db
+        .prepare("SELECT account_id, agent_id, registered_at, instance, last_used, ended FROM http_sessions WHERE hash = ?")
+        .get(hash);
+    if (!row || row.account_id !== account || row.ended)
+        return undefined;
+    const identity = { id: row.agent_id, registeredAt: row.registered_at, instance: row.instance };
+    if (row.last_used < cutoff || nameOfIdentity(db, account, identity) === undefined) {
+        db.prepare("DELETE FROM http_sessions WHERE hash = ?").run(hash);
+        return undefined;
+    }
+    return identity;
+}

package/dist/settings.js

@@ -0,0 +1,13 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * A setting from the environment: `MESSAGE_CP_<name>`. An empty value is returned as set: `serve` and
+ * MESSAGE_CP_AGENT refuse it, and an empty MESSAGE_CP_DB means the default path.
+ */
+export function setting(name, env = process.env) {
+    return env[`MESSAGE_CP_${name}`];
+}
+/** `~/.message-cp/<file>`. */
+export function homeFile(file, home = homedir()) {
+    return join(home, ".message-cp", file);
+}

package/dist/wait.js

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { OWNER_ACCOUNT } from "./db.js";
+import { setting } from "./settings.js";
+/** The CLI that sits next to the running server: `dist/cli.js` for a built checkout. */
+const cliPath = fileURLToPath(new URL("./cli.js", import.meta.url));
+export const NAME_PLACEHOLDER = "<your-name>";
+export const shellQuote = (s) => (/^[A-Za-z0-9_\/.:@%+=,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`);
+/** The shell command that exits once `name` has unread mail, reading the same database as this server. */
+export function waitCommand(name, env = process.env) {
+    // Carries this server's database path, so a different MESSAGE_CP_DB in the caller's shell cannot point the command elsewhere.
+    const path = setting("DB", env);
+    const db = path ? `MESSAGE_CP_DB=${shellQuote(resolve(path))} ` : "";
+    return `${db}node ${shellQuote(cliPath)} wait ${shellQuote(name)}`;
+}
+/**
+ * The one line `wait` prints, here and over HTTP: how many unread messages and from whom, then how many unread posts
+ * in joined channels and in which, then how many unread mentions and in which channels, never the bodies. With no
+ * unread posts or mentions it is the messages part alone, as it was before channels, so scripts that parse it keep
+ * working.
+ */
+export function formatUnread(unread) {
+    const parts = [];
+    if (unread.count > 0) {
+        parts.push(`${unread.count} unread ${unread.count === 1 ? "message" : "messages"} from ${unread.senders.join(", ")}`);
+    }
+    if (unread.posts > 0) {
+        parts.push(`${unread.posts} unread ${unread.posts === 1 ? "post" : "posts"} in ${unread.channels.map((c) => `#${c}`).join(", ")}`);
+    }
+    if (unread.mentions > 0) {
+        parts.push(`${unread.mentions} unread ${unread.mentions === 1 ? "mention" : "mentions"} in ${unread.mentionChannels.map((c) => `#${c}`).join(", ")}`);
+    }
+    return parts.join("; ");
+}
+/** How long the server holds a /wait request with no mail before answering 204. */
+export const DEFAULT_WAIT_HOLD_MS = 4 * 60 * 1000;
+// curl gives up a little after the server would have answered, so a dead connection cannot hang the loop.
+const CURL_MAX_TIME_S = DEFAULT_WAIT_HOLD_MS / 1000 + 60;
+// Plain POSIX sh and curl, nothing to install. The token comes from MESSAGE_CP_HTTP_TOKEN (an empty variable counts
+// as unset), else ~/.message-cp/http-token, and reaches curl on
+// stdin (`-H @-`), so it is never in an argument list. $1 is the /wait URL, $2 the agent name.
+// A 204 (no mail yet) or a failed request asks again; 401 and 404 end it, since asking again cannot help.
+const CURL_LOOP = `t="\${MESSAGE_CP_HTTP_TOKEN:-$(cat ~/.message-cp/http-token 2>/dev/null)}"
+[ -n "$t" ] || { echo "message-cp wait: set MESSAGE_CP_HTTP_TOKEN or write the token to ~/.message-cp/http-token" >&2; exit 1; }
+while :; do
+r=$(printf "Authorization: Bearer %s\\n" "$t" | curl -sS -m ${CURL_MAX_TIME_S} -H @- -g -G --data-urlencode "agent=$2" -w "%{http_code}" "$1")
+b=\${r%???}; c=\${r#"$b"}
+case $c in
+200) printf "%s" "$b"; exit 0;;
+401) echo "message-cp wait: the server refused the token (401)" >&2; exit 1;;
+404) echo "message-cp wait: 404: no agent named $2, or the server URL is wrong" >&2; exit 1;;
+204) ;;
+*) sleep 5;;
+esac
+done`;
+// The same loop for a session connected by approval, whose MCP client holds its token: the token is the agent's listen
+// token, read only from ~/.message-cp/wait/<name>@<server>, never from MESSAGE_CP_HTTP_TOKEN or
+// ~/.message-cp/http-token, so agents on one machine never share or overwrite one file. $3 is the <server> part.
+const CURL_401 = "the server refused the token (401)";
+if (!CURL_LOOP.includes(CURL_401))
+    throw new Error("CURL_LOOP's 401 line changed: update LISTEN_LOOP");
+const LISTEN_LOOP = `f="$HOME/.message-cp/wait/$2@$3"
+t=$(cat "$f" 2>/dev/null)
+[ -n "$t" ] || { echo "message-cp wait: no listen token in $f; call the listen_token tool and save its token there as it says" >&2; exit 1; }
+${CURL_LOOP.slice(CURL_LOOP.indexOf("while :; do")).replace(CURL_401, "the server refused the listen token (401): a newer one replaced it, its agent was removed or its approval revoked")}`;
+/** The `/wait` URL on the server at `publicUrl`, built from the parsed URL. */
+function waitUrl(publicUrl) {
+    const url = new URL(publicUrl);
+    // Set as the path, never resolved as a reference, so no path can change the host.
+    url.pathname = `${url.pathname.replace(/\/+$/, "")}/wait`;
+    return url;
+}
+/**
+ * The shell command that exits once `name` has unread mail on the server at `publicUrl`, over HTTP. `publicUrl` is one
+ * `serve` checked with `publicUrl` in connect.ts; `/wait` is built from the parsed URL.
+ */
+export function httpWaitCommand(publicUrl, name) {
+    return `sh -c '${CURL_LOOP}' sh ${shellQuote(waitUrl(publicUrl).href)} ${shellQuote(name)}`;
+}
+/**
+ * The <server> part of a listen token's file name for the account `account`: the public URL's host and port, with
+ * anything but [A-Za-z0-9.-] as `_`, then `-` and 16 hex digits of a sha256 of the account and the `/wait` URL. Agent
+ * names are unique only within an account, and two servers may share a host under different paths, so both are in it.
+ */
+const listenServer = (publicUrl, account) => `${new URL(publicUrl).host.replace(/[^A-Za-z0-9.-]/g, "_")}-${createHash("sha256").update(`${account} ${waitUrl(publicUrl).href}`).digest("hex").slice(0, 16)}`;
+/** The file, under `~`, that the listen command for `name` of the account `account` on the server at `publicUrl` reads its listen token from. */
+export const listenTokenFile = (publicUrl, account, name) => `~/.message-cp/wait/${name}@${listenServer(publicUrl, account)}`;
+/**
+ * How an agent saves its listen token to `listenTokenFile`, privately: the directories 0700 and the file 0600. The file
+ * is removed first, so one already there with a wider mode is made again under the umask. The token is never in it;
+ * `<listen token>` is a placeholder the agent replaces.
+ */
+export const saveListenToken = (publicUrl, account, name) => {
+    const file = `~/.message-cp/wait/${shellQuote(`${name}@${listenServer(publicUrl, account)}`)}`;
+    return `Save listenToken, and nothing else, to ${listenTokenFile(publicUrl, account, name)}, privately: mkdir -p ~/.message-cp/wait && chmod 700 ~/.message-cp ~/.message-cp/wait, then rm -f ${file} && (umask 077 && printf '%s\\n' '<listen token>' > ${file}), with the token in place of <listen token>. Never put it in a URL, a message or a log.`;
+};
+/**
+ * The shell command that exits once `name` of the account `account` has unread mail on the server at `publicUrl`, for
+ * a session connected by approval: like `httpWaitCommand`, but with the agent's listen token from `listenTokenFile`.
+ */
+export function listenWaitCommand(publicUrl, account, name) {
+    return `sh -c '${LISTEN_LOOP}' sh ${shellQuote(waitUrl(publicUrl).href)} ${shellQuote(name)} ${shellQuote(listenServer(publicUrl, account))}`;
+}
+/**
+ * What a connecting session is told about being woken by messages. `agent` is the agent an HTTP session already is,
+ * because its token is bound to it: its command names that agent, and it is not told to register. `approval` is set for
+ * a session connected by approval, whose command reads a listen token (`listenWaitCommand`) that it is told how to get;
+ * `account` is the session's account, which names that token's file.
+ */
+export function instructions(env = process.env, remote = false, publicUrl, agent, approval = false, account = OWNER_ACCOUNT) {
+    // A remote agent cannot run `wait`, which reads the database file on the server's machine; it can ask /wait if
+    // the server knows the URL clients reach it at.
+    if (remote && !publicUrl) {
+        return "message-cp does not push messages; an agent has to ask for them. Call read_inbox to check for mail, and list_channels for unread posts. To wait for mail in one call instead, call wait_for_mail. It reads and marks nothing: when it returns a line, call read_inbox if the line names messages or mentions and read_channel for each channel it names posts in, and only then wait again, since a call made before reading returns at once on the same mail. When it returns { unread: null }, its timeout passed without finding mail: call it again.";
+    }
+    const command = !remote
+        ? waitCommand(setting("AGENT", env) || NAME_PLACEHOLDER, env)
+        : approval
+            ? listenWaitCommand(publicUrl, account, agent ?? NAME_PLACEHOLDER)
+            : httpWaitCommand(publicUrl, agent ?? NAME_PLACEHOLDER);
+    // A session connected by approval has no token its shell can read: it gets a listen token for its agent first.
+    const first = !approval
+        ? remote && agent
+            ? `as agent '${agent}', which this session already is,`
+            : "register and then"
+        : agent
+            ? `as agent '${agent}', which this session already is, call listen_token, save the listen token it returns as it says, and then`
+            : "register, save the listen token it returns as it says, and then";
+    return [
+        "message-cp does not push messages; an agent has to ask for them.",
+        `To be woken when a message arrives, ${first} run this as a background command (in Claude Code, a Bash call with run_in_background): ${command}`,
+        "It exits as soon as you have unread mail, unread posts in a channel you joined with join_channel, or an unread @mention of you, and prints how many, from whom and in which channels, without reading them.",
+        "When it fires, call read_inbox if it names messages or mentions and read_channel for each channel it names posts in, and only then start the command again; starting it before reading fires at once on the same mail.",
+        "A client that cannot run a background command can call wait_for_mail instead: it holds the call until the same mail arrives or its timeout passes, and returns the same line. Read what it names the same way before calling it again. When it returns { unread: null }, its timeout passed without finding mail: call it again.",
+    ].join("\n");
+}