message-cp 0.1.0 → 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 " +
@@ -702,6 +702,9 @@ let peopleRowsKey = "";
 let inviteClosings = 0;
 // The id of the invite whose link the view shows, or undefined, so cancelling that invite takes its link away.
 let shownInvite;
+// How many times showInvite has shown a link, so a write with no answer hides only a link shown before it started, never
+// one another request showed meanwhile.
+let invitesShown = 0;
 // The invite the "People" view asks before cancelling ({ id, person, createdAt }), or undefined.
 let cancelTarget;
 // The list the people view's invites and the "New link" select were last built from, so a poll rebuilds them only when it
@@ -1545,12 +1548,22 @@ function showInvite(body) {
     "It works once and lasts " + INVITE_DAYS + " days, until " + when(invite.expiresAt) + ". It shows only here, until you leave this view.";
   inviteLink.value = link;
   shownInvite = invite.id;
+  invitesShown++;
   copyNote.textContent = "";
   inviteMade.hidden = false;
   inviteLink.focus();
   return true;
 }
 
+// Hides the invite link showInvite showed, with its line and its copy note.
+function hideInvite() {
+  inviteMade.hidden = true;
+  inviteFor.textContent = "";
+  inviteLink.value = "";
+  copyNote.textContent = "";
+  shownInvite = undefined;
+}
+
 // Reads the people and the invites again at once, after a write that may have changed them.
 function refresh() {
   cancel();
@@ -1573,6 +1586,7 @@ async function addInvitedPerson() {
   }
   adding = tokenGen;
   const closings = inviteClosings;
+  const shown = invitesShown;
   personAdd.disabled = true;
   personNote.textContent = "Adding…";
   const ac = new AbortController();
@@ -1598,7 +1612,10 @@ async function addInvitedPerson() {
     return;
   }
   if (answer.error) {
-    personNote.textContent = answer.error + ", so " + name + " may have been added: the agents panel and the invites below show whether.";
+    // A link may have been made, so the one shown before may be taken for it. A link another request showed meanwhile
+    // stays: it is that request's own result.
+    if (shown === invitesShown) hideInvite();
+    personNote.textContent = answer.error + ", so " + name + " may or may not have been added: the agents panel and the invites below show which once they have been read again.";
     refresh();
     return;
   }
@@ -1618,6 +1635,7 @@ async function makeInvite() {
   }
   linking = tokenGen;
   const closings = inviteClosings;
+  const shown = invitesShown;
   linkMake.disabled = true;
   linkNote.textContent = "Making a link…";
   const ac = new AbortController();
@@ -1640,7 +1658,10 @@ async function makeInvite() {
     return;
   }
   if (answer.error) {
-    linkNote.textContent = answer.error + ", so a link for " + person + " may have been made: the invites below show whether.";
+    // A link may have been made, so the one shown before may be taken for it. A link another request showed meanwhile
+    // stays: it is that request's own result.
+    if (shown === invitesShown) hideInvite();
+    linkNote.textContent = answer.error + ", so a link for " + person + " may or may not have been made: the invites below show which once they have been read again.";
     refresh();
     return;
   }
@@ -1714,17 +1735,12 @@ async function cancelInvite() {
   if (answer.status === 403) return unmarked();
   // A confirmation opened for another invite meanwhile stays.
   if (cancelTarget === invite) closeCancelInvite(true);
-  // Once the server says this invite is gone (200, or 404: used, cancelled or expired), its link, if shown, goes too.
-  if ((answer.status === 200 || answer.status === 404) && shownInvite === invite.id) {
-    inviteMade.hidden = true;
-    inviteFor.textContent = "";
-    inviteLink.value = "";
-    copyNote.textContent = "";
-    shownInvite = undefined;
-  }
+  // Once the server says this invite is gone (200, or 404: used, cancelled or expired), or may be (no answer), its link,
+  // if shown, goes too.
+  if ((answer.status === 200 || answer.status === 404 || answer.error) && shownInvite === invite.id) hideInvite();
   if (answer.status === 200) cancelNote.textContent = "Cancelled " + invite.person + "'s invite.";
   else if (answer.status === 404) cancelNote.textContent = invite.person + "'s invite was already used, cancelled or expired (404).";
-  else if (answer.error) cancelNote.textContent = answer.error + ", so " + invite.person + "'s invite may have been cancelled: the list below shows whether.";
+  else if (answer.error) cancelNote.textContent = answer.error + ", so " + invite.person + "'s invite may or may not have been cancelled: the list below shows which once it has been read again.";
   else cancelNote.textContent = refusal(answer);
   if (answer.status === 200 || answer.status === 404 || answer.error) refresh();
 }
@@ -1755,7 +1771,7 @@ async function markPerson(name, admin) {
   if (answer.status === 403) return unmarked();
   if (answer.status === 200) peopleNote.textContent = admin ? name + " is now an admin." : name + " is no longer an admin.";
   else if (answer.status === 404) peopleNote.textContent = name + " is already gone (404).";
-  else if (answer.error) peopleNote.textContent = answer.error + ", so " + name + " may have been changed: the list below shows whether.";
+  else if (answer.error) peopleNote.textContent = answer.error + ", so " + name + " may or may not have been changed: the list below shows which once it has been read again.";
   else peopleNote.textContent = refusal(answer);
   if (answer.status === 200 || answer.status === 404 || answer.error) refresh();
 }
@@ -1868,7 +1884,7 @@ async function removeAccountPerson() {
         ? "Removed " + name + ": " + counted(body.messages, "message") + " and " + counted(body.mentions, "mention") + " deleted."
         : "Removed " + name + ".") + stopped;
   } else if (answer.status === 404) peopleNote.textContent = name + " is already gone (404).";
-  else if (answer.error) peopleNote.textContent = answer.error + ", so " + name + " may have been removed: the list below shows whether.";
+  else if (answer.error) peopleNote.textContent = answer.error + ", so " + name + " may or may not have been removed: the list below shows which once it has been read again.";
   else peopleNote.textContent = refusal(answer);
   if (answer.status === 200 || answer.status === 404 || answer.error) refresh();
 }
@@ -1932,7 +1948,7 @@ async function removeWebhook() {
         ? "Removed webhook " + hook.id + " and its " + (body.deliveries === 1 ? "1 delivery" : body.deliveries + " deliveries") + "."
         : "Removed webhook " + hook.id + ".";
   } else if (answer.status === 404) webhookNote.textContent = "Webhook " + hook.id + " was already gone (404).";
-  else if (answer.error) webhookNote.textContent = answer.error + ", so webhook " + hook.id + " may have been removed: the list below shows whether.";
+  else if (answer.error) webhookNote.textContent = answer.error + ", so webhook " + hook.id + " may or may not have been removed: the list below shows which once it has been read again.";
   else webhookNote.textContent = refusal(answer);
   if (answer.status === 200 || answer.status === 404 || answer.error) refresh();
 }
@@ -2012,8 +2028,8 @@ async function addAccountWebhook() {
     // Another webhook may have been added, so the secret shown before may no longer be the newest.
     hideWebhookSecret();
     hookNote.textContent =
-      answer.error + ", so the webhook may or may not have been added: the list below shows whether. " +
-      "No secret can be shown for it, so if it is listed, remove it and add it again.";
+      answer.error + ", so the webhook may or may not have been added: the list below shows which once it has been read again. " +
+      "No secret can be shown for it, and the list cannot show which webhook this attempt added, so remove one there only if you know it is that one, then add it again.";
     refresh();
     return;
   }
@@ -2109,7 +2125,7 @@ async function revokeApproval() {
   const named = "token " + target.id + " (" + target.client + ")";
   if (answer.status === 200) approvalNote.textContent = "Revoked " + named + "." + endedAgents(answer.body);
   else if (answer.status === 404) approvalNote.textContent = "Token " + target.id + " (" + target.client + ") was already revoked or gone (404).";
-  else if (answer.error) approvalNote.textContent = answer.error + ", so " + named + " may have been revoked: the list below shows whether.";
+  else if (answer.error) approvalNote.textContent = answer.error + ", so " + named + " may or may not have been revoked: the list below shows which once it has been read again.";
   else approvalNote.textContent = refusal(answer);
   if (answer.status === 200 || answer.status === 404 || answer.error) refresh();
 }
@@ -2184,7 +2200,7 @@ async function revokeToken() {
     tokenNote.textContent = "Revoked token " + target.id + " (" + target.label + ")." + ended + endedAgents(answer.body);
   }
   else if (answer.status === 404) tokenNote.textContent = "Token " + target.id + " was already revoked or gone (404).";
-  else if (answer.error) tokenNote.textContent = answer.error + ", so token " + target.id + " may or may not have been revoked: the list below shows which.";
+  else if (answer.error) tokenNote.textContent = answer.error + ", so token " + target.id + " may or may not have been revoked: the list below shows which once it has been read again.";
   else tokenNote.textContent = refusal(answer);
   if (answer.status === 200 || answer.status === 404 || answer.error) refresh();
 }
@@ -2449,7 +2465,7 @@ async function removeAgent() {
         ? "Removed " + name + ": " + counted(body.messages, "message") + " and " + counted(body.mentions, "mention") + " deleted."
         : "Removed " + name + ".") + stopped;
   } else if (answer.status === 404) agentNote.textContent = name + " is already gone (404).";
-  else if (answer.error) agentNote.textContent = answer.error + ", so " + name + " may have been removed: the list shows whether.";
+  else if (answer.error) agentNote.textContent = answer.error + ", so " + name + " may or may not have been removed: the list shows which once it has been read again.";
   else agentNote.textContent = refusal(answer);
   if (forgot) refresh();
 }
@@ -4838,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>
@@ -4848,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

@@ -60,6 +60,37 @@ const MESSAGES_REPLY_INDEXES = `
 CREATE INDEX IF NOT EXISTS messages_by_reply ON messages (in_reply_to);
 -- \`ask\` finds the replies to one question sent to the asker through this, in id order, not by walking every reply to it.
 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, 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
+// window lasts 60 minutes. `fixed_body` is the JSON body the owner set with `webhook add --body`, sent in place of the
+// event body, or null to send the event body. AUTOINCREMENT so a webhook's id, which GET and DELETE /api/webhooks and
+// `webhook list` hand out, never names a later webhook once the highest one is removed. A table from before it is
+// rebuilt by rebuildWebhooks(), which creates the same table; the columns after `created_at` are added to it in
+// migrate first.
+const webhooksTable = (table) => `
+CREATE TABLE IF NOT EXISTS ${table} (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  account_id INTEGER NOT NULL REFERENCES accounts(id),
+  url TEXT NOT NULL,
+  event TEXT NOT NULL CHECK (event IN ('channel', 'mention', 'agent')),
+  name TEXT NOT NULL,
+  include_text INTEGER NOT NULL,
+  secret TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  header_name TEXT,
+  header_value TEXT,
+  max_per_hour INTEGER,
+  window_started_at INTEGER,
+  window_count INTEGER NOT NULL DEFAULT 0,
+  fixed_body TEXT
+);`;
+// Dropping a table drops its indexes, so rebuildWebhooks() creates this again.
+const WEBHOOKS_INDEXES = `
+CREATE INDEX IF NOT EXISTS webhooks_by_name ON webhooks (account_id, event, name COLLATE NOCASE);`;
 // One-time dashboard sign-in codes from `message-cp login-link`, and invites an admin person made (src/login.ts). Only
 // the code's hash is kept. `person_id` is set for a link that signs in as that person; `used_at` once it has given its
 // token or, for an invite, was cancelled. AUTOINCREMENT so an invite's id, which GET and DELETE /api/invites hand out,
@@ -166,25 +197,8 @@ CREATE INDEX IF NOT EXISTS mentions_unread ON mentions (agent_id, read_at, post_
 -- GET /api/channel-posts reads a page of posts' mentions through this, not by scanning every mention.
 CREATE INDEX IF NOT EXISTS mentions_by_post ON mentions (post_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.
--- So is the value of the one header a webhook may carry (\`header_name\`, \`header_value\`, added in \`migrate\`), since
--- deliveries send it. \`max_per_hour\` (also added in \`migrate\`, 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 window lasts 60 minutes. \`fixed_body\` (also added in \`migrate\`) is the
--- JSON body the owner set with \`webhook add --body\`, sent in place of the event body, or null to send the event body.
-CREATE TABLE IF NOT EXISTS webhooks (
-  id INTEGER PRIMARY KEY,
-  account_id INTEGER NOT NULL REFERENCES accounts(id),
-  url TEXT NOT NULL,
-  event TEXT NOT NULL CHECK (event IN ('channel', 'mention', 'agent')),
-  name TEXT NOT NULL,
-  include_text INTEGER NOT NULL,
-  secret TEXT NOT NULL,
-  created_at INTEGER NOT NULL
-);
-CREATE INDEX IF NOT EXISTS webhooks_by_name ON webhooks (account_id, event, name COLLATE NOCASE);
+${webhooksTable("webhooks")}
+${WEBHOOKS_INDEXES}
 
 -- What a webhook is owed: one row per webhook per message or post it is for, queued in the transaction that stores the
 -- message or post. Only ids are kept, so the body is built when it is sent. \`serve\` sends them: \`attempts\` is counted
@@ -460,6 +474,43 @@ function rebuildDashboardSessions(db) {
         db.exec(DASHBOARD_SESSIONS_INDEXES);
     }).immediate();
 }
+/** 1 when rebuildWebhooks() has copied every webhook into its new table. Both tables hold only webhooks, not history. */
+export const COUNT_WEBHOOKS_COPIED = "SELECT (SELECT count(*) FROM webhooks) = (SELECT count(*) FROM webhooks_autoincrement)";
+const webhooksAutoincrement = (db) => /\bAUTOINCREMENT\b/i.test(db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'webhooks'").get().sql);
+/**
+ * Rebuilds a `webhooks` table from before AUTOINCREMENT as `webhooksTable`, keeping every row, its id and every column,
+ * as rebuildLoginCodes() does for `login_codes`, so that no webhook id is handed out again once the highest webhook is
+ * removed. Under the write lock, so exactly one process rebuilds. `webhook_deliveries` refers to `webhooks`, so as in
+ * rebuildMessages() foreign keys are off around it. Ids are copied as they are, so every delivery still finds its webhook
+ * once every row is copied; it checks that by counting webhooks rather than with foreign_key_check, which would read every
+ * table's history under the write lock.
+ */
+function rebuildWebhooks(db) {
+    if (webhooksAutoincrement(db))
+        return;
+    // Dropping the old table must not cascade to the deliveries that reference it.
+    const foreignKeys = db.pragma("foreign_keys", { simple: true });
+    db.pragma("foreign_keys = OFF");
+    try {
+        db.transaction(() => {
+            if (webhooksAutoincrement(db))
+                return;
+            db.exec(webhooksTable("webhooks_autoincrement"));
+            db.exec(`INSERT INTO webhooks_autoincrement (id, account_id, url, event, name, include_text, secret, created_at, header_name, header_value,
+                                             max_per_hour, window_started_at, window_count, fixed_body)
+         SELECT id, account_id, url, event, name, include_text, secret, created_at, header_name, header_value,
+                max_per_hour, window_started_at, window_count, fixed_body FROM webhooks ORDER BY id`);
+            if (db.prepare(COUNT_WEBHOOKS_COPIED).pluck().get() !== 1)
+                throw new Error("webhooks migration lost a webhook");
+            db.exec("DROP TABLE webhooks");
+            db.exec("ALTER TABLE webhooks_autoincrement RENAME TO webhooks");
+            db.exec(WEBHOOKS_INDEXES);
+        }).immediate();
+    }
+    finally {
+        db.pragma(`foreign_keys = ${foreignKeys ? "ON" : "OFF"}`);
+    }
+}
 function migrate(db, path) {
     addColumn(db, "key_hash", "TEXT");
     // A random token per registration, so a session can tell its agent from a later one that reuses the id or name.
@@ -522,6 +573,8 @@ function migrate(db, path) {
     addColumn(db, "window_count", "INTEGER NOT NULL DEFAULT 0", "webhooks");
     // The JSON body a webhook sends in place of the event body (`webhook add --body`); null, so the event body, for one without.
     addColumn(db, "fixed_body", "TEXT", "webhooks");
+    // Every webhooks column above is added before rebuildWebhooks() copies it.
+    rebuildWebhooks(db);
     addColumn(db, "delivery_uuid", "TEXT", "webhook_deliveries");
     // Set once a DELETE ends an HTTP session, so no server restores it or records it again.
     addColumn(db, "ended", "INTEGER NOT NULL DEFAULT 0", "http_sessions");

package/dist/init.js

@@ -11,14 +11,15 @@ 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 { VERSION } from "./server.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
+// 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 {
 }
@@ -175,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.`);
@@ -232,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 {
@@ -245,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
@@ -422,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.";
@@ -521,7 +526,7 @@ export async function proveServer(server, env = process.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" });
+    const client = new Client({ name: "message-cp-init", version: VERSION });
     let failure;
     let step = "starting the server";
     let stderr = "";
@@ -594,7 +599,7 @@ export async function proveServer(server, env = process.env) {
 }
 /** 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 client = new Client({ name: "message-cp-init", version: VERSION });
     const transport = new StreamableHTTPClientTransport(r.endpoint, { requestInit: { headers } });
     return { client, transport };
 }
@@ -642,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}`;
@@ -660,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 {
@@ -668,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 });
@@ -691,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 {
@@ -860,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
@@ -898,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;
@@ -906,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/server.js

@@ -1,4 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createRequire } from "node:module";
 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";
@@ -123,13 +124,15 @@ async function poll(deadline, signal, answer) {
             return found;
     }
 }
+/** The version in package.json, one directory up from this file whether it runs from src/ (tsx) or dist/ (a build or the npm package). */
+export const VERSION = createRequire(import.meta.url)("../package.json").version;
 /** 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) });
+    const server = new McpServer({ name: "message-cp", version: VERSION }, { 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);

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,8 +1,9 @@
 {
   "name": "message-cp",
-  "version": "0.1.0",
+  "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",
   "main": "dist/index.js",
   "files": [
     "dist"