message-cp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Colin Hallett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# message-cp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small messaging service for AI agents, run by you. It is an [MCP](https://modelcontextprotocol.io) server: each agent registers a name and a one-line bio, finds the other agents, sends them messages, and can be woken when mail arrives instead of polling for it. All agents share one SQLite file.
+
+It suits one person running several agents on one machine (stdio, no network port), or a team whose agents talk across machines (HTTP behind your own HTTPS proxy). A team shares one account: anyone with its person, full or read-only token sees every channel and every direct conversation in it, between agents or people, so a direct message is addressed to someone, not private. Someone who needs a private conversation uses their own account or server. Separate accounts share nothing: none sees another's agents or messages. It does one job: no shared memory, no task board, no agent supervisor.
+
+message-cp does not sign people in. Over HTTP it accepts only bearer tokens it issued; if you want another kind of sign-in, you put it in front (see [Putting your own sign-in in front](https://message-cp.vercel.app/accounts.html#putting-your-own-sign-in-in-front) in the reference).
+
+## Quick start
+
+Needs Node 22.14 or later and git.
+
+```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 .
+```
+
+`--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".
+
+## Documentation
+
+The full documentation is a static site in [`site/`](site/), built with [Astro](https://astro.build). To build it yourself, run `cd site && npm ci && npm run build`, which needs Node 22.23.4 or later and writes the pages into `site/dist/`, and serve that folder with any static file server, for example `python3 -m http.server -d site/dist`. It is published at [https://message-cp.vercel.app](https://message-cp.vercel.app), and the links below go to its pages there:
+
+- [Getting started](https://message-cp.vercel.app/getting-started.html): one machine, a team server, or Docker.
+- [Reference](https://message-cp.vercel.app/reference.html): every detail, in four pages:
+  - [Add it to an MCP client](https://message-cp.vercel.app/clients.html): Claude Code and Cursor, over stdio or HTTP.
+  - [Running a server](https://message-cp.vercel.app/server.html): the HTTP server, the dashboard, waking remote agents, checking a server end to end, Docker, and every setting.
+  - [Accounts, people, agents and webhooks](https://message-cp.vercel.app/accounts.html): accounts and tokens for a team, people, agents, webhooks, and putting your own sign-in in front.
+  - [Tools, limits and the database](https://message-cp.vercel.app/tools.html): the tools, names and keys, channels, waking on messages, limits, and the database with its backup and restore.
+- [Compared with the alternatives](https://message-cp.vercel.app/compare.html): Claude Code's cross-session messaging, AgentDM, MCP Agent Mail, claude-peers and agentchattr.
+
+## How the project is run
+
+[DIRECTION.md](DIRECTION.md) says what the project is for and how it is run.
+
+The code is written by a [Tessl](https://tessl.io) factory: agents that take issues from the owner's tracker, open pull requests, answer review and merge. [`tessl.json`](tessl.json) and [`tessl-factory/`](tessl-factory/) are that setup, and they work only in the owner's Tessl organisation. You need neither to use message-cp or to build it. [CONTRIBUTING.md](CONTRIBUTING.md) says how to report a problem or suggest a change, and [SECURITY.md](SECURITY.md) how to report a vulnerability.
+
+`ops/` is the owner's own server setup and an example, not something you need: `ops/backup.sh` is the owner's nightly version of the backup copy in the reference's [Database](https://message-cp.vercel.app/tools.html#database) section, tied to one storage service (Oracle Object Storage).
+
+## Licence
+
+MIT; see [LICENSE](LICENSE).

package/dist/accounts.js

@@ -0,0 +1,279 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { endTokenAgents } from "./agents.js";
+import { OWNER_ACCOUNT } from "./db.js";
+// Accounts and their tokens. The operator manages them with `message-cp account` and `message-cp token` on the server.
+// A token is shown once, when it is created; only its hash is stored.
+export class AccountError extends Error {
+}
+const NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
+const hashToken = (token) => createHash("sha256").update(token).digest("hex");
+/**
+ * Stores and returns a new token for the account of row id `account`, of the kind the flags say; with `registers`, an
+ * agent token bound to no agent that registers its own agents. The caller checks the account, agent and person exist,
+ * inside its own transaction; `addToken` and `redeemLoginCode` in login.ts do.
+ */
+export function issueToken(db, account, readOnly = false, agentOnly = false, agent, person, registers = false) {
+    if (readOnly && agentOnly)
+        throw new AccountError("A token is read-only or agent-only, not both.");
+    if (agent !== undefined && !agentOnly)
+        throw new AccountError("Only an agent token is bound to an agent.");
+    if (person && (readOnly || agentOnly))
+        throw new AccountError("A person token is neither read-only nor agent-only.");
+    if (registers && (!agentOnly || agent !== undefined))
+        throw new AccountError("Only an agent token bound to no agent registers its own agents.");
+    const token = randomBytes(32).toString("hex");
+    // An agent or person token is stored read-only too, so a server from before it that shares the database refuses it
+    // everything but the read-only endpoints instead of taking it for a full token.
+    const { id } = db
+        .prepare("INSERT INTO tokens (account_id, hash, created_at, read_only, agent_only, agent_id, person_id, registers) VALUES (?, ?, ?, ?, ?, ?, ?, ?) RETURNING id")
+        .get(account, hashToken(token), Date.now(), readOnly || agentOnly || person ? 1 : 0, agentOnly ? 1 : 0, agent ?? null, person?.id ?? null, registers ? 1 : 0);
+    return { id, token, readOnly, agentOnly, ...(person && { person: person.name }) };
+}
+/** Creates the account `name` (unique in any case) with its first token. */
+export const addAccount = (db, name) => db.transaction(() => {
+    if (!NAME_PATTERN.test(name))
+        throw new AccountError("Invalid account name: use 1-32 characters from letters, digits, '-' and '_'.");
+    if (db.prepare("SELECT 1 FROM accounts WHERE name = ?").get(name))
+        throw new AccountError(`Account '${name}' already exists.`);
+    const { id, name: stored } = db
+        .prepare("INSERT INTO accounts (name, created_at) VALUES (?, ?) RETURNING id, name")
+        .get(name, Date.now());
+    return { ...issueToken(db, id), account: stored };
+}).immediate();
+export function listAccounts(db) {
+    const rows = db.prepare("SELECT id, name, created_at FROM accounts ORDER BY id").all();
+    const tokens = db.prepare("SELECT id FROM tokens WHERE account_id = ? AND revoked_at IS NULL ORDER BY id").pluck();
+    return rows.map((r) => ({
+        id: r.id,
+        name: r.name,
+        createdAt: new Date(r.created_at).toISOString(),
+        tokenIds: tokens.all(r.id),
+    }));
+}
+/**
+ * Another token for the account named `account`; with `readOnly`, one that can only read; with `agentOnly`, one that
+ * cannot act as a person; with `agent` as well, one that acts only as the account's agent of that row id; with
+ * `person`, one that sends and posts only as the account's live person of that name (any case); with `agentOnly` and
+ * `registers`, one bound to no agent that registers its own agents.
+ */
+export const addToken = (db, account, readOnly = false, agentOnly = false, agent, person, registers = false) => db.transaction(() => {
+    const row = db.prepare("SELECT id, name FROM accounts WHERE name = ?").get(account);
+    if (!row)
+        throw new AccountError(`No account named '${account}'.`);
+    if (agent !== undefined && !db.prepare("SELECT 1 FROM agents WHERE id = ? AND account_id = ? AND removed_at IS NULL AND person = 0").get(agent, row.id)) {
+        throw new AccountError(`No live agent with id ${agent} in account '${row.name}'.`);
+    }
+    let bound;
+    if (person !== undefined) {
+        const live = db
+            .prepare("SELECT id, name, person FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+            .get(row.id, person);
+        if (live?.person === 0)
+            throw new AccountError(`The name '${live.name}' belongs to an agent, not a person.`);
+        if (!live)
+            throw new AccountError(`No person named '${person}' in account '${row.name}'.`);
+        bound = { id: live.id, name: live.name };
+    }
+    return { ...issueToken(db, row.id, readOnly, agentOnly, agent, bound, registers), account: row.name };
+}).immediate();
+/** Every token that still works, oldest first, with its account and kind, and for an OAuth token its client. */
+export function listTokens(db) {
+    const rows = db
+        .prepare(`SELECT tokens.id, accounts.name, tokens.read_only, tokens.agent_only, tokens.person_id, tokens.created_at,
+         tokens.oauth, tokens.client_name, tokens.client_host, tokens.last_used_at
+       FROM tokens JOIN accounts ON accounts.id = tokens.account_id WHERE tokens.revoked_at IS NULL ORDER BY tokens.id`)
+        .all();
+    return rows.map((r) => ({
+        id: r.id,
+        account: r.name,
+        // A person token's row has read_only set too (see `issueToken`), so its person comes first.
+        kind: r.person_id !== null ? "person" : r.agent_only === 1 ? "agent" : r.read_only === 1 ? "read-only" : "full",
+        ...(r.oauth === 1 && { client: { name: r.client_name, host: r.client_host } }),
+        createdAt: new Date(r.created_at).toISOString(),
+        lastUsedAt: r.last_used_at === null ? null : new Date(r.last_used_at).toISOString(),
+    }));
+}
+/** Records on the token of row id `token` that the OAuth code exchange issued it to `client`. Run inside that exchange's transaction. */
+export function recordClient(db, token, client) {
+    db.prepare("UPDATE tokens SET oauth = 1, client_name = ?, client_host = ? WHERE id = ?").run(client.name, client.host, token);
+}
+/**
+ * One page of the account's unrevoked tokens the OAuth code exchange issued, newest first, each with its client and
+ * either its agent or, for one that registers its own agents, the live agents of the account it registered, which may
+ * be none. A single-agent token whose agent was removed is left out, as `accountForToken` refuses it, and so is one
+ * issued before the exchange recorded its client.
+ */
+export function listApprovals(db, account, limit, offset) {
+    // A token that registers is kept in the shape `accountForToken` accepts as registering. Its agents are looked for in
+    // its own account only; the unary + keeps SQLite finding them through agents_by_token rather than agents_live, which
+    // would read every live agent of the account for each token.
+    const rows = db
+        .prepare(`SELECT tokens.id, agents.name, tokens.client_name, tokens.client_host, tokens.created_at,
+         CASE WHEN agents.id IS NULL THEN
+           (SELECT json_group_array(own.name ORDER BY own.name) FROM agents own
+            WHERE own.token_id = tokens.id AND +own.account_id = tokens.account_id AND own.removed_at IS NULL AND own.person = 0)
+         END AS registered
+       FROM tokens LEFT JOIN agents ON agents.id = tokens.agent_id AND agents.account_id = tokens.account_id
+         AND agents.removed_at IS NULL AND agents.person = 0
+       WHERE tokens.account_id = ? AND tokens.oauth = 1 AND tokens.revoked_at IS NULL
+         AND (agents.id IS NOT NULL OR (tokens.registers = 1 AND tokens.agent_only = 1 AND tokens.agent_id IS NULL))
+       ORDER BY tokens.id DESC LIMIT ? OFFSET ?`)
+        .all(account, limit, offset);
+    return rows.map((r) => ({
+        id: r.id,
+        // Only a token stored as registering, with no agent, is kept without a live agent.
+        registers: r.name === null,
+        agent: r.name,
+        ...(r.name === null && { agents: JSON.parse(r.registered) }),
+        clientName: r.client_name,
+        clientHost: r.client_host,
+        issuedAt: new Date(r.created_at).toISOString(),
+    }));
+}
+/**
+ * Stops the token `id` working for every request from now on. For a token that registers its own agents, also ends
+ * each live agent it registered, as `endTokenAgents` does, in the same transaction. Returns the account it belonged to
+ * and the names of the agents it ended, in name order, none for any other token.
+ */
+export const revokeToken = (db, id) => db.transaction(() => {
+    const row = db
+        .prepare(`UPDATE tokens SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL
+         RETURNING account_id, (SELECT name FROM accounts WHERE accounts.id = tokens.account_id) AS account`)
+        .get(Date.now(), id);
+    if (!row)
+        throw new AccountError(`No working token with id ${id}.`);
+    return { account: row.account, agents: endTokenAgents(db, row.account_id, id) };
+}).immediate();
+/** The name of the account `account`. */
+export const accountName = (db, account) => db.prepare("SELECT name FROM accounts WHERE id = ?").pluck().get(account);
+/** How stale a token's `last_used_at` may get before a request that uses it writes it again: a busy token writes about once a minute. */
+export const TOKEN_USE_RESOLUTION_MS = 60_000;
+/**
+ * Records on the token of row id `token` that a request used it now, unless it was recorded within
+ * TOKEN_USE_RESOLUTION_MS. `lastUsedAt` is the value the caller's lookup read: when that is recent enough nothing is
+ * written, so such a request never waits for SQLite's write lock; otherwise the `UPDATE` checks the window again, so
+ * processes that read the same stale value write it once. Best effort, and outside any transaction: a lock held past the
+ * busy timeout skips it quietly, any other error logs one fixed line, never anything about the token, and the request
+ * goes on either way.
+ */
+function recordUse(db, token, lastUsedAt) {
+    const now = Date.now();
+    if (lastUsedAt !== null && lastUsedAt >= now - TOKEN_USE_RESOLUTION_MS)
+        return;
+    try {
+        db.prepare("UPDATE tokens SET last_used_at = ? WHERE id = ? AND (last_used_at IS NULL OR last_used_at < ?)").run(now, token, now - TOKEN_USE_RESOLUTION_MS);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (typeof code !== "string" || !code.startsWith("SQLITE_BUSY"))
+            console.error("message-cp: could not record when a token was last used");
+    }
+}
+/**
+ * The account a bearer token belongs to: the owner's for `ownerToken` (MESSAGE_CP_HTTP_TOKEN, never read-only or
+ * agent-only), else the account of a token created with `message-cp`, as long as it has not been revoked. A token bound
+ * to an agent comes with that agent, and only while it is a live agent of the token's own account; a person token
+ * comes with its person, only while that row is a live person of the token's own account, and with whether that row is
+ * marked admin now. A token that registers its own agents comes with its row id. Undefined for anything else, a bound
+ * token whose agent or person has been removed included. A created token it accepts is recorded as used now (see
+ * `recordUse`), even if a later check refuses the request; nothing is recorded for `ownerToken` or a refused token.
+ *
+ * `token` may also be a dashboard sign-in session id (`dashboard_sessions`, made by `redeemLoginCode`). When no token's
+ * hash matches, the session is found by its hash and its token by `tokens.id`, then every check above applies to that
+ * token's row, so a session of a revoked token, or of a person token whose person was removed, gives undefined as the
+ * token itself would. Its answer is its token's, with `session` set to the session's row id.
+ */
+export function accountForToken(db, token, ownerToken) {
+    const hash = hashToken(token);
+    // Constant-time against the owner's token, as before accounts; created tokens are found by their hash.
+    if (timingSafeEqual(Buffer.from(hash), Buffer.from(hashToken(ownerToken)))) {
+        return { account: OWNER_ACCOUNT, readOnly: false, agentOnly: false };
+    }
+    // The agent and the person are looked for in the token's account only, so a token never acts as another account's.
+    // The person is found by row, so a later person given a removed person's name is not theirs. A session is checked
+    // through its token's row by the same query, keyed by `tokens.id` instead of `tokens.hash`.
+    const select = (key, value) => db
+        .prepare(`SELECT tokens.id AS token_id, tokens.last_used_at, tokens.registers, tokens.oauth, tokens.account_id, tokens.read_only, tokens.agent_only, tokens.agent_id,
+         agents.id, agents.registered_at, agents.instance, agents.name,
+         tokens.person_id, people.id AS person_row, people.name AS person_name, people.admin AS person_admin
+       FROM tokens LEFT JOIN agents ON agents.id = tokens.agent_id AND agents.account_id = tokens.account_id
+         AND agents.removed_at IS NULL AND agents.person = 0
+       LEFT JOIN agents people ON people.id = tokens.person_id AND people.account_id = tokens.account_id
+         AND people.removed_at IS NULL AND people.person = 1
+       WHERE tokens.${key} = ? AND tokens.revoked_at IS NULL`)
+        .get(value);
+    let row = select("hash", hash);
+    let session;
+    if (!row) {
+        const found = db.prepare("SELECT id, token_id FROM dashboard_sessions WHERE hash = ?").get(hash);
+        if (found) {
+            row = select("id", found.token_id);
+            session = found.id;
+        }
+        else {
+            return listenAccess(db, hash);
+        }
+    }
+    if (!row || (row.agent_id !== null && row.id === null) || (row.person_id !== null && row.person_row === null))
+        return undefined;
+    recordUse(db, row.token_id, row.last_used_at);
+    if (row.person_row !== null && row.person_name !== null) {
+        const person = { id: row.person_row, name: row.person_name, admin: row.person_admin === 1 };
+        return { account: row.account_id, readOnly: false, agentOnly: false, person, ...(session !== undefined && { session }) };
+    }
+    // An agent token's row also has read_only set (see `issueToken`); it is agent-only here, never both.
+    const access = { account: row.account_id, readOnly: row.read_only === 1 && row.agent_only !== 1, agentOnly: row.agent_only === 1 };
+    if (row.id !== null)
+        access.agent = { id: row.id, registeredAt: row.registered_at, instance: row.instance, name: row.name };
+    // Only an agent-only token bound to no agent, as `issueToken` stores it; never a full, read-only or person token.
+    if (row.registers === 1 && row.agent_only === 1 && row.agent_id === null)
+        access.registers = row.token_id;
+    // Only an agent token, which is what the code exchange issues; a sign-in session is never one.
+    if (row.oauth === 1 && row.agent_only === 1 && session === undefined)
+        access.approval = row.token_id;
+    if (session !== undefined)
+        access.session = session;
+    return access;
+}
+// A listen token's agent, while it is a live agent of its approval's account that the approval still acts as: the
+// single agent it is bound to, or one it registered. The approval must be an unrevoked agent token the code exchange
+// issued.
+export const LISTEN_AGENT = `FROM listen_tokens
+  JOIN tokens ON tokens.id = listen_tokens.token_id AND tokens.revoked_at IS NULL AND tokens.oauth = 1 AND tokens.agent_only = 1
+  JOIN agents ON agents.id = listen_tokens.agent_id AND agents.account_id = tokens.account_id AND agents.removed_at IS NULL
+    AND agents.person = 0 AND (tokens.agent_id = agents.id OR (tokens.registers = 1 AND tokens.agent_id IS NULL AND agents.token_id = tokens.id))`;
+/** The access of the listen token with hash `hash`: its agent, and nothing else. Undefined once `LISTEN_AGENT` fails. */
+function listenAccess(db, hash) {
+    const row = db
+        .prepare(`SELECT tokens.account_id, agents.id, agents.registered_at, agents.instance, agents.name ${LISTEN_AGENT} WHERE listen_tokens.hash = ?`)
+        .get(hash);
+    if (!row)
+        return undefined;
+    return {
+        account: row.account_id,
+        readOnly: false,
+        agentOnly: true,
+        agent: { id: row.id, registeredAt: row.registered_at, instance: row.instance, name: row.name },
+        listen: true,
+    };
+}
+/**
+ * A new listen token for the live agent `identity` of account `account`, through the approval token of row id
+ * `approval`: one that only waits for that agent's mail on GET /wait. It replaces the agent's earlier one, which stops
+ * working. Only its hash is stored. Undefined, storing nothing, unless `identity` is still that registration and
+ * `LISTEN_AGENT` holds for it, so a session never gets one for another approval's agent or another account's.
+ */
+export const issueListenToken = (db, account, identity, approval) => db.transaction(() => {
+    const allowed = db
+        .prepare(`SELECT 1 FROM tokens JOIN agents ON agents.id = ? AND agents.account_id = tokens.account_id AND agents.removed_at IS NULL
+           AND agents.person = 0 AND agents.registered_at = ? AND agents.instance IS ?
+           AND (tokens.agent_id = agents.id OR (tokens.registers = 1 AND tokens.agent_id IS NULL AND agents.token_id = tokens.id))
+         WHERE tokens.id = ? AND tokens.account_id = ? AND tokens.revoked_at IS NULL AND tokens.oauth = 1 AND tokens.agent_only = 1`)
+        .get(identity.id, identity.registeredAt, identity.instance, approval, account);
+    if (!allowed)
+        return undefined;
+    const token = randomBytes(32).toString("hex");
+    db.prepare(`INSERT INTO listen_tokens (agent_id, token_id, hash, created_at) VALUES (?, ?, ?, ?)
+       ON CONFLICT(agent_id) DO UPDATE SET token_id = excluded.token_id, hash = excluded.hash, created_at = excluded.created_at`).run(identity.id, approval, hashToken(token), Date.now());
+    return token;
+}).immediate();