message-cp 0.1.1 → 0.2.0

package/README.md

@@ -8,18 +8,19 @@ message-cp does not sign people in. Over HTTP it accepts only bearer tokens it i
 
 ## Quick start
 
-Needs Node 22.14 or later and git.
+Needs Node 22.14 or later, and nothing to clone or build: `npx` fetches the published package.
 
 ```sh
-git clone https://github.com/colinhallett/message-cp.git
-cd message-cp
-npm ci --ignore-scripts
-npm run build
-npm test
-npm install -g .
+npx -y message-cp init
 ```
 
-`--ignore-scripts` skips compiling the SQLite driver, `better-sqlite3`, which ships prebuilt binaries for Linux, macOS and Windows on x64 and arm64; without it, `npm ci` needs `make` and a C++ compiler. That gives you `dist/index.js`, the stdio server, and `dist/cli.js`, the `message-cp` command for everything else (`message-cp serve`, `wait`, `account`, `token`; `message-cp help` lists them all). `npm install -g .` links that command onto your `PATH` from the clone, compiling and downloading nothing. On Linux or macOS, if npm's global folder needs root, that step fails with `EACCES`; `npm install -g . --prefix ~/.local` puts the command in `~/.local/bin` instead, which must be on your `PATH`. Without either, `node dist/cli.js` in the clone does the same, for example `node dist/cli.js account list`. Add the stdio server to an MCP client as [Add it to an MCP client](https://message-cp.vercel.app/clients.html#add-it-to-an-mcp-client) in the reference says (the agents are the client's sessions; there is no separate chat command), open two sessions, and ask one to "register as alice" and the other to "register as bob and send alice a message".
+`init` adds message-cp to Claude Code, Codex, Cursor or Claude Desktop; a `message-cp` entry that runs something else is left as it is, and `init` stops and says how to remove it. Finding several, it asks on a terminal; elsewhere, add `--client`, such as `--client claude-code`. It then checks the server with a test agent, which it removes, and prints how to undo. By hand, for Claude Code:
+
+```sh
+claude mcp add message-cp -- npx -y message-cp
+```
+
+Each of the client's sessions registers as its own agent, and all share one database; there is no separate chat command. Open two sessions, and ask one to "register as alice" and the other to "register as bob and send alice a message". `npx -y message-cp help` lists the other commands. For a team server or Docker, see [Getting started](https://message-cp.vercel.app/getting-started.html); for Cursor by hand or Claude Code over HTTP, [Add it to an MCP client](https://message-cp.vercel.app/clients.html#add-it-to-an-mcp-client). To build from a clone, see [CONTRIBUTING.md](CONTRIBUTING.md#building-and-testing).
 
 ## Documentation
 

package/dist/cli.js

@@ -17,7 +17,7 @@ const USAGE = {
     serve: "message-cp serve [--host <address>] [--port <port>] [--public-url <url>]",
     wait: "message-cp wait <name>",
     account: "message-cp account add <name> | message-cp account list | message-cp token add <account> [--read-only | --agent-only | --person <name>] | message-cp token list | message-cp token revoke <token id>",
-    webhook: "message-cp webhook add --url <url> --on <#channel | mention:<agent> | agent:<agent>> [--account <name>] [--no-text] [--header-stdin] [--max-per-hour <n>] [--body <json>] | message-cp webhook list [--account <name>] | message-cp webhook remove <webhook id>",
+    webhook: "message-cp webhook add --url <url> --on <#channel | mention:<agent> | agent:<agent> | agent:*> [--account <name>] [--no-text] [--header-stdin] [--max-per-hour <n>] [--body <json>] | message-cp webhook list [--account <name>] | message-cp webhook remove <webhook id>",
     person: "message-cp person add <name> [--account <name>] [--admin] | message-cp person admin <name> [--off] [--account <name>] | message-cp person remove <name> [--account <name>] | message-cp person list [--account <name>]",
     agent: "message-cp agent list [--account <name>] | message-cp agent remove <name> [--account <name>] | message-cp agent key reset <name> [--account <name>]",
     connect: "message-cp connect <agent> --url <public url> [--account <name>] [--new-key]",
@@ -352,8 +352,9 @@ else if (command === "agent") {
     db.close();
 }
 else if (command === "connect") {
-    // Run on the server, like `agent`. The token and the agent's key are printed this once, to stdout, inside the client
-    // setup; stderr says what was made and how to revoke the token, and never carries a token, a key or a hash.
+    // Run on the server, like `agent`. The token is printed this once, to stdout, inside the client setup, and the agent's
+    // key never is, since the token is bound to the agent; stderr says what was made and how to revoke the token, and
+    // never carries a token, a key or a hash.
     const usage = () => {
         console.error(`usage: ${USAGE.connect}`);
         process.exit(2);
@@ -385,7 +386,7 @@ else if (command === "connect") {
         console.error(c.reset
             ? `message-cp: new key for agent '${c.name}' of account '${c.account}'; its old key no longer works and its current sessions have ended.`
             : `message-cp: agent '${c.name}' in account '${c.account}'.`);
-        console.error(`message-cp: agent token ${c.tokenId} for account '${c.account}'. The output holds this token and the agent's key, shown only now; keep them. To revoke the token: message-cp token list, then message-cp token revoke ${c.tokenId}.`);
+        console.error(`message-cp: agent token ${c.tokenId} for account '${c.account}'. The output holds this token, shown only now; keep it. To revoke the token: message-cp token list, then message-cp token revoke ${c.tokenId}.`);
         console.log(clientSetup(endpoint, c).replace(/\n$/, ""));
     }
     catch (err) {
@@ -505,7 +506,7 @@ else if (command === "init") {
         run: realRunner,
         interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
         ask: askOnTerminal,
-        prove: () => (remote === undefined ? proveServer(ownServer()) : proveRemote(remote)),
+        prove: (checked) => (checked === undefined ? proveServer(ownServer()) : proveRemote(checked)),
         out: (line) => console.log(line),
         err: (line) => console.error(line),
     });

package/dist/connect.js

@@ -2,7 +2,8 @@ import { addToken } from "./accounts.js";
 import { registerWithIdentity, resetAgentKey, validateName } from "./agents.js";
 import { shellQuote } from "./wait.js";
 // `message-cp connect`: what a client needs to act as one agent of an account over HTTP, made in one step on the
-// server. The token and key are returned for the CLI to print once, to stdout; only their hashes are stored.
+// server. The token is returned for the CLI to print once, to stdout; only its hash is stored, and the agent's key,
+// also returned, is not printed, since the token is bound to the agent.
 export class ConnectError extends Error {
 }
 /**
@@ -68,13 +69,12 @@ export const connectAgent = (db, account, name, newKey) => db.transaction(() =>
     const token = addToken(db, acct.name, false, true, agent.id);
     return { name: agent.name, account: acct.name, reset: live !== undefined, key: agent.key, tokenId: token.id, token: token.token };
 }).immediate();
-/** The two things `connect` prints: a `claude mcp add` command, then the same server as a JSON `mcpServers` entry. */
+/**
+ * The two things `connect` prints: a `claude mcp add` command, then the same server as a JSON `mcpServers` entry. Both
+ * send only the token: it is bound to the agent, so it alone acts as it, and the agent's key is never printed.
+ */
 export function clientSetup(endpoint, c) {
-    const headers = {
-        Authorization: `Bearer ${c.token}`,
-        "X-Message-CP-Agent": c.name,
-        "X-Message-CP-Agent-Key": c.key,
-    };
+    const headers = { Authorization: `Bearer ${c.token}` };
     const command = [
         "claude mcp add --transport http message-cp",
         shellQuote(endpoint.href),

package/dist/dashboard.js

@@ -672,7 +672,7 @@ const NO_CHANNELS_FULL = ' You can also start one from "New channel" above.';
 const NO_MESSAGES = "No direct messages yet: they appear here when an agent sends one with the send_message tool.";
 const NO_MESSAGES_FULL = ' You can also start one from "New message" above.';
 const NO_DELIVERIES =
-  "No webhook deliveries yet: add a webhook on the server with message-cp webhook add --url <url> --on <#channel | mention:<agent> | agent:<agent>>, and its deliveries show here once it fires.";
+  "No webhook deliveries yet: add a webhook on the server with message-cp webhook add --url <url> --on <#channel | mention:<agent> | agent:<agent> | agent:*>, and its deliveries show here once it fires.";
 const NO_APPROVALS =
   "No approved clients yet: a client approved as one named agent, or as one that registers its own agents, appears here " +
   "once it connects through the server's authorization flow (serve --public-url), and its token is revoked on the server " +
@@ -4854,7 +4854,7 @@ export const DASHBOARD_HTML = `<!doctype html>
 <input id="hook-url" type="text" inputmode="url" autocomplete="off" spellcheck="false" placeholder="https://example.com/hook"></div>
 <div class="field"><label for="hook-on">Fires on</label>
 <input id="hook-on" type="text" autocomplete="off" spellcheck="false" placeholder="#general" aria-describedby="hook-on-hint">
-<span id="hook-on-hint" class="note">#&lt;channel&gt;, mention:&lt;agent&gt; or agent:&lt;agent&gt;</span></div>
+<span id="hook-on-hint" class="note">#&lt;channel&gt;, mention:&lt;agent&gt;, agent:&lt;agent&gt; or agent:* (every agent, not people)</span></div>
 <label class="check"><input id="hook-text" type="checkbox" checked> Send the message text</label>
 <div class="field"><label for="hook-header-name">Header name (optional)</label>
 <input id="hook-header-name" type="text" autocomplete="off" spellcheck="false" placeholder="Authorization"></div>
@@ -4864,7 +4864,7 @@ export const DASHBOARD_HTML = `<!doctype html>
 <input id="hook-max" type="number" min="1" step="1" inputmode="numeric" autocomplete="off"></div>
 <div class="field wide"><label for="hook-body">Fixed body (optional)</label>
 <textarea id="hook-body" rows="2" autocomplete="off" spellcheck="false" placeholder='{"requestId":"{{delivery}}"}' aria-describedby="hook-body-hint"></textarea>
-<span id="hook-body-hint" class="note">A JSON object sent in place of the event, with {{delivery}} once in a string value; it never carries the text.</span></div>
+<span id="hook-body-hint" class="note">A JSON object sent in place of the event, with {{delivery}} once in a string value, and for agent: any {{agent}} in one; it never carries the text.</span></div>
 <div class="actions"><button id="hook-add" type="submit">Add webhook</button></div>
 </form>
 <div id="webhook-made" hidden>

package/dist/db.js

@@ -62,7 +62,7 @@ CREATE INDEX IF NOT EXISTS messages_by_reply ON messages (in_reply_to);
 CREATE INDEX IF NOT EXISTS messages_by_question ON messages (in_reply_to, recipient_id);`;
 // Outgoing webhooks, added only with `message-cp webhook`; an admin person token also lists and removes them over
 // /api/webhooks. `event` is 'channel', 'mention' or 'agent' and `name` the channel or agent in the same account,
-// which need not exist yet. The secret is stored as is: deliveries sign with it.
+// which need not exist yet, or '*' with 'agent' for every agent of the account (`agent:*`), a name no agent can have. The secret is stored as is: deliveries sign with it.
 // So is the value of the one header a webhook may carry (`header_name`, `header_value`), since deliveries send it.
 // `max_per_hour` (null for none) caps its delivery requests in a fixed window: `window_started_at` is when the first
 // request after the last window ended was claimed, and `window_count` how many requests have been claimed since; the

package/dist/init.js

@@ -18,8 +18,8 @@ import { shellQuote } from "./wait.js";
 // 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
+// nothing it prints holds the token or key. With `--from` it reads the URL and token from the file `message-cp connect`
+// wrote instead (and the agent's name and key, from a file an earlier `connect` wrote with them), and once the check passes also writes the token to ~/.message-cp/http-token for
 // the wake-up command.
 export class InitError extends Error {
 }
@@ -176,10 +176,12 @@ export const cliCommands = {
 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.
+ * must name exactly one server with a `url` and the `Authorization` header `clientSetup` in `src/connect.ts` writes. A
+ * file an earlier `connect` wrote also has the agent's name and key headers, and then both must be usable; without
+ * them the agent is left out, for `checkRemote` to find from the token. 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 and token. No
+ * message holds the file's contents.
  */
 export function readConnectFile(file, platform = process.platform) {
     const refuse = (why) => new InitError(`${file} ${why}. Nothing was changed.`);
@@ -233,9 +235,11 @@ export function readConnectFile(file, platform = process.platform) {
     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")
+    // A file a later `connect` wrote has neither: its token is bound to the agent.
+    const named = agent !== undefined || key !== undefined;
+    if (named && (typeof agent !== "string" || !NAME_PATTERN.test(agent) || agent.toLowerCase() === "all"))
         throw notConnect("has no usable agent name");
-    if (!word(key))
+    if (named && !word(key))
         throw notConnect("has no agent key");
     let endpoint;
     try {
@@ -246,7 +250,7 @@ export function readConnectFile(file, platform = process.platform) {
             throw err;
         throw refuse(`has a server URL init refuses: ${err.message.replace(/^--url /, "it ")}`);
     }
-    return { endpoint, agent, token, key, from: file };
+    return named ? { endpoint, agent: agent, token, key: key, from: file } : { endpoint, token, 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
@@ -423,7 +427,7 @@ export function remoteRefusal(client, m, endpoint) {
         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.`;
+        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 header Authorization: Bearer <token> (for a token not bound to the agent, also X-Message-CP-Agent and X-Message-CP-Agent-Key).`;
     }
     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.";
@@ -643,6 +647,10 @@ async function callTool(client, tool, args) {
  * 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.
+ *
+ * Without `r.agent`, as from the file a later `connect` wrote, `list_channels` (which marks nothing read) on that
+ * session fails as not registered for an unbound token, which is refused, since nothing names its agent; for a bound
+ * one, the refused `register` names the agent, and `checkRemote` sets `r.agent` to it.
  */
 export async function checkRemote(r) {
     const tokenIn = r.from === undefined ? "the token in MESSAGE_CP_HTTP_TOKEN" : `the token in ${r.from}`;
@@ -661,6 +669,23 @@ export async function checkRemote(r) {
     };
     const said = (err) => redact(err instanceof Error ? err.message : String(err), r);
     const plain = remoteClient(r, { Authorization: `Bearer ${r.token}` });
+    // The agent a bound token is: `register` with a random name is refused before it does anything, so nothing is
+    // registered, and its message names the token's agent.
+    const tokenAgent = async () => {
+        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}`);
+        return refused[1];
+    };
     let bound = false;
     try {
         try {
@@ -669,6 +694,19 @@ export async function checkRemote(r) {
         catch (err) {
             throw refusal(err, false);
         }
+        if (r.agent === undefined) {
+            try {
+                await callTool(plain.client, "list_channels", { limit: 1 });
+            }
+            catch (err) {
+                const message = said(err);
+                if (message.includes(NOT_REGISTERED))
+                    throw new InitError(`${tokenIn} is not bound to an agent, and the file names none; give the file message-cp connect wrote, unchanged`);
+                throw new InitError(`list_channels: ${message.slice(0, 300)}`);
+            }
+            r.agent = await tokenAgent();
+            return true;
+        }
         let agent;
         try {
             agent = await callTool(plain.client, "get_agent", { name: r.agent });
@@ -692,22 +730,9 @@ export async function checkRemote(r) {
                 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}'`);
-            }
+            const actual = await tokenAgent();
+            if (actual.toLowerCase() !== r.agent.toLowerCase())
+                throw new InitError(`${tokenIn} is bound to agent '${actual}', not '${r.agent}'`);
         }
     }
     finally {
@@ -861,22 +886,27 @@ export async function runInit(o) {
         }
         client = found[n - 1];
     }
-    const remote = o.remote === undefined ? undefined : { ...o.remote };
-    if (remote !== undefined) {
-        const refused = remoteRefusal(client, o.machine, remote.endpoint);
+    let remote;
+    if (o.remote !== undefined) {
+        const refused = remoteRefusal(client, o.machine, o.remote.endpoint);
         if (refused !== undefined) {
             o.err(`message-cp init: ${refused} Nothing was changed.`);
             return 1;
         }
+        const unchecked = { ...o.remote };
+        let bound;
         try {
-            remote.bound = (await (o.check ?? checkRemote)(remote)) === true;
+            bound = (await (o.check ?? checkRemote)(unchecked)) === true;
+            if (unchecked.agent === undefined)
+                throw new InitError("the check did not find which agent the token is");
         }
         catch (err) {
             if (!(err instanceof InitError))
                 throw err;
-            o.err(`message-cp init: ${redact(err.message, remote)}. Nothing was changed.`);
+            o.err(`message-cp init: ${redact(err.message, unchecked)}. Nothing was changed.`);
             return 1;
         }
+        remote = { ...unchecked, agent: unchecked.agent, bound };
         o.out(remote.key === undefined
             ? `Server: ${remote.endpoint.href} accepted the token, which is agent '${remote.agent}'.`
             : remote.bound
@@ -899,7 +929,9 @@ export async function runInit(o) {
             ? `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(remote.from === undefined
+                ? "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."
+                : "If it is an earlier init's entry, for this token with the agent's name and key or for another token, remove it so init writes this token alone.");
         }
         o.err(`To remove it, then run message-cp init again: ${setUp.undo}`);
         return 1;
@@ -907,7 +939,7 @@ export async function runInit(o) {
     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();
+        proved = await o.prove(remote);
     }
     catch (err) {
         o.err(`Check failed: ${redact(err instanceof Error ? err.message : String(err), remote)}`);

package/dist/messages.js

@@ -18,6 +18,16 @@ export function validateBody(body, kind = "Message") {
         throw new ToolError(`${kind} is too long: at most ${MAX_BODY_LENGTH} characters.`);
     }
 }
+/**
+ * Queues a stored message for every `agent:<recipient>` webhook of the account and, unless the recipient is a person,
+ * every `agent:*` one (stored with the name `*`), held for the recipient while it is waiting for mail (`markWaiting`),
+ * so `sendPending` leaves it to the waiting agent. Both are found through `webhooks_by_name`. Parameters: the message id,
+ * the time now, the recipient's id, the time now again, the account, the recipient's name and its `person` flag.
+ */
+export const QUEUE_MESSAGE_SQL = `INSERT INTO webhook_deliveries (webhook_id, message_id, created_at, held_for)
+  SELECT id, ?, ?, (SELECT a.id FROM agents a WHERE a.id = ? AND a.waiting_until > ?)
+  FROM webhooks WHERE account_id = ? AND event = 'agent' AND name COLLATE NOCASE IN (?, CASE WHEN ? = 0 THEN '*' END)
+  ORDER BY id`;
 /**
  * Stores one delivery per recipient: the named agent, or for `all` every agent of the account registered right now
  * except the sender. Read state therefore belongs to each recipient. A message belongs to its recipient's account,
@@ -45,7 +55,7 @@ export function sendMessage(db, account, from, to, body, own, inReplyTo) {
         let recipients;
         if (broadcast) {
             recipients = db
-                .prepare("SELECT id, name FROM agents WHERE account_id = ? AND name <> ? AND removed_at IS NULL ORDER BY name")
+                .prepare("SELECT id, name, person FROM agents WHERE account_id = ? AND name <> ? AND removed_at IS NULL ORDER BY name")
                 .all(account, from);
         }
         else {
@@ -53,20 +63,16 @@ export function sendMessage(db, account, from, to, body, own, inReplyTo) {
             if (!agent)
                 throw new ToolError(`No agent named '${to}'.`);
             recipients = db
-                .prepare("SELECT id, name FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+                .prepare("SELECT id, name, person FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
                 .all(account, agent.name);
         }
         const insert = db.prepare("INSERT INTO messages (recipient_id, sender, body, broadcast, created_at, in_reply_to) VALUES (?, ?, ?, ?, ?, ?)");
-        // Each recipient's row is owed to every `agent:<recipient>` webhook of the account, held for the recipient while
-        // it is waiting for mail (`markWaiting`), so `sendPending` leaves it to the waiting agent.
-        const queue = db.prepare(`INSERT INTO webhook_deliveries (webhook_id, message_id, created_at, held_for)
-         SELECT id, ?, ?, (SELECT a.id FROM agents a WHERE a.id = ? AND a.waiting_until > ?)
-         FROM webhooks WHERE account_id = ? AND event = 'agent' AND name = ? COLLATE NOCASE ORDER BY id`);
+        const queue = db.prepare(QUEUE_MESSAGE_SQL);
         const now = Date.now();
         const stored = [];
         for (const r of recipients) {
             const id = insert.run(r.id, from, body, broadcast ? 1 : 0, now, inReplyTo ?? null).lastInsertRowid;
-            queue.run(id, now, r.id, now, account, r.name);
+            queue.run(id, now, r.id, now, account, r.name, r.person);
             stored.push({ id: Number(id), to: r.name });
         }
         // Sending clears the sender's status line, on its own registration only, so a send from a session whose agent was

package/dist/webhooks.js

@@ -11,7 +11,9 @@ import { MAX_INBOX_LIMIT } from "./messages.js";
 // of its deliveries; its value is stored as is too, and never printed, logged or returned. And it may carry a limit on
 // how many delivery requests it gets per window of 60 minutes; deliveries past it wait in the queue for a later window.
 // And it may carry a fixed JSON body the owner sets, sent in place of the event body, signed the same way, with its one
-// `{{delivery}}` replaced by an id of that delivery that every retry repeats; the body is never printed or logged.
+// `{{delivery}}` replaced by an id of that delivery that every retry repeats, and, for direct messages, each `{{agent}}`
+// replaced by the name of the agent the message went to; the body is never printed or logged. `agent:*` is for direct
+// messages to every agent of the account, stored with the name `*`, which no agent can have.
 export class WebhookError extends Error {
 }
 /**
@@ -38,14 +40,18 @@ export function webhookUrl(raw) {
     url.hash = "";
     return url.href;
 }
+/** The name an `agent:*` webhook is stored with: it fires for a direct message to any agent of its account. */
+export const EVERY_AGENT = "*";
 /**
- * Parses `--on`: `#<channel>`, `mention:<agent>` or `agent:<agent>`, each name following the agent-name rules. An agent
- * cannot be named `all`, so `mention:all` and `agent:all` are refused; `#all` is an ordinary channel.
+ * Parses `--on`: `#<channel>`, `mention:<agent>`, `agent:<agent>` or `agent:*`, each name following the agent-name
+ * rules. An agent cannot be named `all`, so `mention:all` and `agent:all` are refused; `#all` is an ordinary channel.
  */
 export function webhookOn(on) {
+    if (on === `agent:${EVERY_AGENT}`)
+        return { event: "agent", name: EVERY_AGENT };
     const [, prefix, name] = /^(#|mention:|agent:)(.*)$/s.exec(on) ?? [];
     if (prefix === undefined || !NAME_PATTERN.test(name)) {
-        throw new WebhookError("Invalid --on: use #<channel>, mention:<agent> or agent:<agent>, names of 1-32 letters, digits, '-' and '_'.");
+        throw new WebhookError("Invalid --on: use #<channel>, mention:<agent>, agent:<agent> or agent:*, names of 1-32 letters, digits, '-' and '_'.");
     }
     if (prefix !== "#" && name.toLowerCase() === "all") {
         throw new WebhookError("Invalid --on: 'all' is reserved and names no agent.");
@@ -106,17 +112,21 @@ export function webhookMaxPerHour(raw) {
 }
 /** What a fixed body's placeholder is replaced with: the delivery's id, the same on every attempt of it. */
 export const WEBHOOK_PLACEHOLDER = "{{delivery}}";
+/** What a fixed body's optional agent placeholder is replaced with, each time: the name of the message's recipient. */
+export const WEBHOOK_AGENT_PLACEHOLDER = "{{agent}}";
 /** The longest `--body`, in UTF-8 bytes. */
 export const WEBHOOK_MAX_BODY_BYTES = 4096;
-/** How many times `text` contains the placeholder. */
-const placeholders = (text) => text.split(WEBHOOK_PLACEHOLDER).length - 1;
+/** How many times `text` contains `placeholder`. */
+const count = (text, placeholder) => text.split(placeholder).length - 1;
 /**
  * Checks `--body`: a JSON object of at most `WEBHOOK_MAX_BODY_BYTES`, with `WEBHOOK_PLACEHOLDER` written as is exactly
  * once in the text, inside a string value that parsing keeps (not in a key, and not dropped by a later duplicate key),
- * and nowhere else in any parsed string or key, `\u` escapes included. Returns it unchanged, so a delivery sends the
- * owner's own bytes with only the placeholder replaced. Errors never repeat the body.
+ * and nowhere else in any parsed string or key, `\u` escapes included. With `agent`, for an `agent:` webhook,
+ * `WEBHOOK_AGENT_PLACEHOLDER` may also be written as is, any number of times, each inside a string value parsing keeps;
+ * without it, it may not appear at all. Returns it unchanged, so a delivery sends the owner's own bytes with only the
+ * placeholders replaced. Errors never repeat the body.
  */
-export function webhookBody(raw) {
+export function webhookBody(raw, agent = false) {
     if (Buffer.byteLength(raw, "utf8") > WEBHOOK_MAX_BODY_BYTES) {
         throw new WebhookError(`Invalid --body: it is over ${WEBHOOK_MAX_BODY_BYTES} bytes.`);
     }
@@ -131,32 +141,57 @@ export function webhookBody(raw) {
         throw new WebhookError("Invalid --body: give a JSON object.");
     }
     const misplaced = new WebhookError(`Invalid --body: put ${WEBHOOK_PLACEHOLDER} exactly once, inside a JSON string value.`);
-    if (placeholders(raw) !== 1)
+    if (count(raw, WEBHOOK_PLACEHOLDER) !== 1)
         throw misplaced;
-    // Parsed again with the literal placeholder swapped for a value found nowhere else, as a delivery swaps it, so the
-    // count is of what a receiver parses: one sentinel in a string value, and no placeholder left in any string or key.
+    const agents = count(raw, WEBHOOK_AGENT_PLACEHOLDER);
+    const agentMisplaced = agent
+        ? new WebhookError(`Invalid --body: put each ${WEBHOOK_AGENT_PLACEHOLDER} inside a JSON string value.`)
+        : new WebhookError(`Invalid --body: ${WEBHOOK_AGENT_PLACEHOLDER} is only for --on agent:<agent> or agent:*.`);
+    if (agents > 0 && !agent)
+        throw agentMisplaced;
+    // Parsed again with each literal placeholder swapped for a value found nowhere else, as a delivery swaps it, so the
+    // count is of what a receiver parses: one sentinel in a string value, each agent sentinel in a string value, and no
+    // placeholder left in any string or key.
     const sentinel = randomUUID();
+    const agentSentinel = randomUUID();
     let sentinels = 0;
+    let agentSentinels = 0;
     let others = 0;
+    let agentOthers = 0;
     const walk = (v) => {
         if (typeof v === "string") {
-            sentinels += v.split(sentinel).length - 1;
-            others += placeholders(v);
+            sentinels += count(v, sentinel);
+            agentSentinels += count(v, agentSentinel);
+            others += count(v, WEBHOOK_PLACEHOLDER);
+            agentOthers += count(v, WEBHOOK_AGENT_PLACEHOLDER);
         }
         else if (Array.isArray(v))
             v.forEach(walk);
         else if (typeof v === "object" && v !== null) {
             for (const [k, x] of Object.entries(v)) {
-                others += placeholders(k) + k.split(sentinel).length - 1;
+                others += count(k, WEBHOOK_PLACEHOLDER) + count(k, sentinel);
+                agentOthers += count(k, WEBHOOK_AGENT_PLACEHOLDER) + count(k, agentSentinel);
                 walk(x);
             }
         }
     };
-    walk(JSON.parse(raw.replace(WEBHOOK_PLACEHOLDER, () => sentinel)));
+    walk(JSON.parse(raw.replace(WEBHOOK_PLACEHOLDER, () => sentinel).replaceAll(WEBHOOK_AGENT_PLACEHOLDER, () => agentSentinel)));
     if (sentinels !== 1 || others !== 0)
         throw misplaced;
+    if (agentOthers !== 0 || agentSentinels !== agents)
+        throw agentMisplaced;
     return raw;
 }
+/** True when `webhookBody` would take `raw` for an `agent:` webhook, so each `{{agent}}` in it is in a string value. */
+function agentPlaceable(raw) {
+    try {
+        webhookBody(raw, true);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** How `--on` names a webhook's event, for printing. */
 export const formatOn = (w) => (w.event === "channel" ? `#${w.name}` : `${w.event}:${w.name}`);
 /**
@@ -173,7 +208,7 @@ export const addWebhook = (db, account, url, on, includeText, header, maxPerHour
     // A fixed body never carries the text, so --no-text with it would mean nothing.
     if (body !== undefined && !includeText)
         throw new WebhookError("--body and --no-text cannot go together: a fixed body never carries the text.");
-    const fixed = body === undefined ? null : webhookBody(body);
+    const fixed = body === undefined ? null : webhookBody(body, event === "agent");
     const row = db.prepare("SELECT id, name FROM accounts WHERE name = ?").get(account);
     if (!row)
         throw new WebhookError(`No account named '${account}'.`);
@@ -419,6 +454,13 @@ export async function sendPending(db, options = {}) {
                 return;
             // `webhookBody` checked that the placeholder is there once, inside a string, and a UUID needs no escaping.
             text = row.fixed_body.replace(WEBHOOK_PLACEHOLDER, () => id.delivery_uuid);
+            // Each agent placeholder of an `agent:` webhook's body is inside a string too, and gets the name escaped as one.
+            // Only there, and only when the stored body passes today's check: a body stored before `{{agent}}` existed, for a
+            // `#channel` or `mention:` webhook or with the text in a key, keeps any such text as it is.
+            if (body.event === "agent" && agentPlaceable(row.fixed_body)) {
+                const agent = JSON.stringify(body.recipient).slice(1, -1);
+                text = text.replaceAll(WEBHOOK_AGENT_PLACEHOLDER, () => agent);
+            }
         }
         let ok = false;
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "message-cp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A messaging service for AI agents: register a name, find each other, send messages and be woken when mail arrives",
   "license": "MIT",
   "mcpName": "io.github.colinhallett/message-cp",