message-cp 0.0.0-stage → 0.1.0

package/dist/agents.js

@@ -0,0 +1,507 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { setting } from "./settings.js";
+export class ToolError extends Error {
+}
+export const NOT_REGISTERED = "This session is not registered. Call `register` first.";
+export const NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
+const MAX_BIO_LENGTH = 500;
+function toAgent(row) {
+    return {
+        name: row.name,
+        bio: row.bio,
+        registeredAt: new Date(row.registered_at).toISOString(),
+        lastSeen: new Date(row.last_seen).toISOString(),
+        person: row.person === 1,
+    };
+}
+/** The refusal for `register` and `unregister` on a person's name. */
+const personRefusal = (name) => `The name '${name}' belongs to a person, not an agent. No agent can register or remove it.`;
+export function validateName(name) {
+    if (!NAME_PATTERN.test(name)) {
+        throw new ToolError("Invalid name: use 1-32 characters from letters, digits, '-' and '_'.");
+    }
+    if (name.toLowerCase() === "all") {
+        throw new ToolError("The name 'all' is reserved.");
+    }
+}
+const MAX_KEY_LENGTH = 256;
+const hashKey = (key) => createHash("sha256").update(key).digest("hex");
+const sameHash = (a, b) => {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+};
+const toIdentity = (row) => ({
+    id: row.id,
+    registeredAt: row.registered_at,
+    instance: row.instance,
+});
+function validateKey(key) {
+    if (key.length < 1 || key.length > MAX_KEY_LENGTH) {
+        throw new ToolError(`Invalid key: use 1-${MAX_KEY_LENGTH} characters.`);
+    }
+}
+/**
+ * Creates the agent, or takes over an existing one with the same name (any case).
+ * An agent that has a key can only be taken over with that key; one without a key (registered
+ * before keys existed) is claimed by this call. With no `key` given a new one is generated and
+ * returned, this once; only its hash is stored. `bio` undefined keeps an existing agent's bio.
+ */
+export const registerAgent = (db, account, name, bio, key) => registerWithIdentity(db, account, name, bio, key).result;
+/** The refusal for a token that registers its own agents, given a key: such a token's agents have none. */
+export const REGISTERS_NO_KEY = "This token registers its own agents, which have no key: the token is their credential. Call register without a key.";
+/**
+ * `registerAgent`, also returning the identity of the registration the caller now holds. With `token`, the row id of a
+ * token that registers its own agents, it takes no key and returns none: a name no live agent or person of the account
+ * has makes a new agent recorded as that token's, and a live agent that token registered is taken back as it is; any
+ * other agent is refused, whatever key it has. The new agent's key hash is still set, from a key nobody is given, so no
+ * call without the token can claim it.
+ */
+export const registerWithIdentity = (db, account, name, bio, key, token) => db.transaction(() => {
+    validateName(name);
+    if (bio !== undefined && bio.length > MAX_BIO_LENGTH) {
+        throw new ToolError(`Bio is too long: at most ${MAX_BIO_LENGTH} characters.`);
+    }
+    if (token !== undefined && key !== undefined)
+        throw new ToolError(REGISTERS_NO_KEY);
+    if (key !== undefined)
+        validateKey(key);
+    const existing = db
+        .prepare("SELECT name, key_hash, person, token_id FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+        .get(account, name);
+    // Before the key check: no key, not even a right one, makes a person's name an agent's.
+    if (existing?.person === 1)
+        throw new ToolError(personRefusal(existing.name));
+    if (token !== undefined) {
+        if (existing && existing.token_id !== token) {
+            throw new ToolError(`Agent '${existing.name}' is already registered. This token registers only new names and takes back only agents it registered.`);
+        }
+    }
+    else if (existing && existing.key_hash !== null && (key === undefined || !sameHash(hashKey(key), existing.key_hash))) {
+        throw new ToolError(`Agent '${name}' is already registered and has a key. Pass its key to take it over.`);
+    }
+    const issued = key === undefined && token === undefined;
+    const effectiveKey = key ?? randomBytes(32).toString("hex");
+    const keyHash = hashKey(effectiveKey);
+    const now = Date.now();
+    const row = db
+        .prepare(`INSERT INTO agents (account_id, name, bio, registered_at, last_seen, key_hash, instance, token_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+         -- Reached on a conflict only after the key or token check above passed. Another account's agent of the same name
+         -- never conflicts. A token's own agent keeps its key hash and token, so taking it back changes neither.
+         ON CONFLICT(account_id, name) DO UPDATE SET bio = COALESCE(?, bio), last_seen = excluded.last_seen,
+           key_hash = CASE WHEN excluded.token_id IS NULL THEN excluded.key_hash ELSE key_hash END
+         RETURNING id, name, bio, registered_at, last_seen, person, instance`)
+        .get(account, name, bio ?? "", now, now, keyHash, randomBytes(16).toString("hex"), token ?? null, bio ?? null);
+    // A caller that supplied its own key already has it.
+    return { result: issued ? { ...toAgent(row), key: effectiveKey } : toAgent(row), identity: toIdentity(row) };
+}).immediate();
+/**
+ * The agent a supervisor chose for this process through MESSAGE_CP_AGENT and MESSAGE_CP_AGENT_KEY:
+ * created or claimed with that key. Throws ToolError if the agent has a different key.
+ */
+export function agentFromEnv(db, account, env = process.env) {
+    return registerFromEnv(db, account, env)?.name;
+}
+/** `agentFromEnv`, also returning the identity of the registration it made, so a session binds to exactly that one. */
+export function registerFromEnv(db, account, env = process.env) {
+    const name = setting("AGENT", env);
+    const key = setting("AGENT_KEY", env);
+    if (name === undefined && key === undefined)
+        return undefined;
+    if (!name || !key) {
+        throw new ToolError("MESSAGE_CP_AGENT and MESSAGE_CP_AGENT_KEY must be set together.");
+    }
+    const { result, identity } = registerWithIdentity(db, account, name, undefined, key);
+    return { name: result.name, identity };
+}
+export const DEFAULT_LIST_LIMIT = 50;
+export const MAX_LIST_LIMIT = 200;
+/** One page of the account's agents ordered by name; pass `offset` to read the rest. */
+export function listAgents(db, account, limit = DEFAULT_LIST_LIMIT, offset = 0) {
+    const rows = db
+        .prepare("SELECT name, bio, registered_at, last_seen, person FROM agents WHERE account_id = ? AND removed_at IS NULL ORDER BY name LIMIT ? OFFSET ?")
+        .all(account, Math.min(limit, MAX_LIST_LIMIT), offset);
+    return rows.map(toAgent);
+}
+export function getAgent(db, account, name) {
+    const row = db
+        .prepare("SELECT name, bio, registered_at, last_seen, person FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+        .get(account, name);
+    return row && toAgent(row);
+}
+/** The identity of the agent registered under `name` right now, if any. A person has none: nothing acts as one. */
+export function identityOf(db, account, name) {
+    const row = db
+        .prepare("SELECT id, registered_at, instance FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL AND person = 0")
+        .get(account, name);
+    return row && toIdentity(row);
+}
+/**
+ * Whether `identity` is a live agent of `account` that the token of row id `token` registered (`registerWithIdentity`
+ * with that token). Found by row, so an agent removed and its name registered again by someone else is not the token's.
+ */
+export function registeredBy(db, account, identity, token) {
+    return (db
+        .prepare("SELECT 1 FROM agents WHERE account_id = ? AND id = ? AND registered_at = ? AND instance IS ? AND removed_at IS NULL AND person = 0 AND token_id = ?")
+        .get(account, identity.id, identity.registeredAt, identity.instance, token) !== undefined);
+}
+/** The identity and stored name of the live agent `name` (any case) of `account` that the token of row id `token` registered. */
+export function ownAgentOf(db, account, name, token) {
+    const row = db
+        .prepare("SELECT id, registered_at, instance, name FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL AND person = 0 AND token_id = ?")
+        .get(account, name, token);
+    return row && { ...toIdentity(row), name: row.name };
+}
+/** Thrown, with nothing stored, when a person token sends or posts as anyone but its own person. */
+export class WrongPersonError extends Error {
+}
+/**
+ * The account's live person `name`, as `personOf` finds them. With `only`, the row id of a person token's person, any
+ * other row, or none, throws `WrongPersonError`: compared by row, so a removed person's name taken again is not theirs.
+ * A person removed after their token was checked, during the request, is refused the same way.
+ */
+export function actingPerson(db, account, name, only) {
+    const person = personOf(db, account, name);
+    if (only !== undefined && person?.id !== only)
+        throw new WrongPersonError("This token sends and posts only as its own person");
+    return person;
+}
+/**
+ * The row id and stored name of the account's live person `name` (any case), or undefined for an agent, a removed row
+ * or no row at all. Only the HTTP routes that send and post as a person use it.
+ */
+export function personOf(db, account, name) {
+    return db
+        .prepare("SELECT id, name FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL AND person = 1")
+        .get(account, name);
+}
+/**
+ * The name of the agent `identity` still belongs to, or undefined once that registration was removed. Undefined for a
+ * person's row too, so no session or channel member can act as a person.
+ */
+export function nameOfIdentity(db, account, identity) {
+    const row = db
+        .prepare("SELECT name FROM agents WHERE account_id = ? AND id = ? AND registered_at = ? AND instance IS ? AND removed_at IS NULL AND person = 0")
+        .get(account, identity.id, identity.registeredAt, identity.instance);
+    return row?.name;
+}
+/** How long a wait's mark lasts after the check that last renewed it, so a waiter that crashed holds no delivery longer. */
+export const WAIT_MARK_MS = 30_000;
+/** A check renews the mark only once less than this is left, so a held wait writes about every 10 seconds, not every check. */
+const WAIT_MARK_RENEW_MS = 20_000;
+/**
+ * Marks `reader` (a name, or one registration) as waiting for mail until `WAIT_MARK_MS` from now, for `sendPending` in
+ * webhooks.ts, which holds the deliveries queued for its messages and mentions meanwhile. Each check of a held wait that
+ * finds nothing unread calls it, never one that finds mail, so an agent that keeps waiting without reading holds nothing.
+ * A person is never marked. It reads first and writes only when the mark needs renewing, so most checks take no write
+ * lock. Best effort: a lock held past the busy timeout leaves the mark as it was, and the next check tries again.
+ */
+export function markWaiting(db, account, reader, now = Date.now()) {
+    const which = typeof reader === "string" ? "name = ?" : "id = ? AND registered_at = ? AND instance IS ?";
+    const args = typeof reader === "string" ? [reader] : [reader.id, reader.registeredAt, reader.instance];
+    const live = `account_id = ? AND ${which} AND removed_at IS NULL AND person = 0 AND (waiting_until IS NULL OR waiting_until < ?)`;
+    try {
+        if (!db.prepare(`SELECT 1 FROM agents WHERE ${live}`).get(account, ...args, now + WAIT_MARK_RENEW_MS))
+            return;
+        db.prepare(`UPDATE agents SET waiting_until = ? WHERE ${live}`).run(now + WAIT_MARK_MS, account, ...args, now + WAIT_MARK_RENEW_MS);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (typeof code !== "string" || !code.startsWith("SQLITE_BUSY"))
+            throw err;
+    }
+}
+export function touchAgent(db, account, name) {
+    db.prepare("UPDATE agents SET last_seen = ? WHERE account_id = ? AND name = ? AND removed_at IS NULL").run(Date.now(), account, name);
+}
+/** How long a status line stays current after `set_status` set it. */
+export const STATUS_TTL_MS = 5 * 60 * 1000;
+export const MAX_STATUS_LENGTH = 100;
+// A newline, any other control character, or a line or paragraph separator: the line has to stay one line.
+const NOT_ONE_LINE = /[\p{Cc}\p{Zl}\p{Zp}]/u;
+// Bidirectional marks, embeddings, overrides and isolates, which could reorder the text shown around the line. Other
+// format characters, such as the zero-width joiner in emoji sequences, are allowed.
+const BIDI_CONTROL = /\p{Bidi_Control}/u;
+/**
+ * Sets the status line of the caller's own registration, `own`, replacing any earlier one, or clears it when `text` is
+ * empty or only spaces. Throws, changing nothing, for a line that is too long, not one line or holds a bidirectional
+ * formatting character, or NOT_REGISTERED once that registration was removed. A person's row never matches.
+ */
+export const setStatus = (db, account, own, text, now = Date.now()) => {
+    // Before the blank check, so a lone newline or tab is refused rather than taken as clearing the line.
+    if (NOT_ONE_LINE.test(text))
+        throw new ToolError("Status must be one line, with no newline or other control character.");
+    if (BIDI_CONTROL.test(text))
+        throw new ToolError("Status must not contain bidirectional formatting characters.");
+    const clear = text.trim().length === 0;
+    if (!clear) {
+        // Count characters (code points), as validateBody does.
+        let n = 0;
+        for (const _ of text)
+            if (++n > MAX_STATUS_LENGTH)
+                break;
+        if (n > MAX_STATUS_LENGTH)
+            throw new ToolError(`Status is too long: at most ${MAX_STATUS_LENGTH} characters.`);
+    }
+    return db
+        .transaction(() => {
+        const changed = db
+            .prepare("UPDATE agents SET status = ?, status_at = ? WHERE account_id = ? AND id = ? AND registered_at = ? AND instance IS ? AND removed_at IS NULL AND person = 0")
+            .run(clear ? null : text, clear ? null : now, account, own.id, own.registeredAt, own.instance).changes;
+        if (changed === 0)
+            throw new ToolError(NOT_REGISTERED);
+        return clear ? { status: null, expiresAt: null } : { status: text, expiresAt: new Date(now + STATUS_TTL_MS).toISOString() };
+    })
+        .immediate();
+};
+/**
+ * The name a removed agent's row is given, so the real name is free again. `:` is outside the name pattern, so no
+ * one can register it, and the id makes it unique.
+ */
+const removedName = (id) => `removed:${id}`;
+// Match no key and no session's instance, so a release from before removals were kept, run on this database, can
+// neither take over or remove a removed agent's row by name nor act as it from a session that was registered as it,
+// and so cannot read or delete the messages kept with it.
+const REMOVED_KEY_HASH = "removed";
+const REMOVED_INSTANCE = "removed";
+/**
+ * Removes the agent `name` from the directory and frees its name. The row stays, marked removed, with its real name
+ * in `removed_name`, so the messages addressed to it are kept and its id is never given to a new agent. An agent
+ * with a key is removed only with that key, unless `own` is the identity of the caller's session: then that exact
+ * registration is removed, or nothing if it is already gone, so a name registered by someone else in the meantime is
+ * never touched. With `token` instead, the row id of a token that registers its own agents, only a live agent that token
+ * registered is removed, with no key (a key is refused); any other name is refused.
+ */
+export const removeAgent = (db, account, name, key, own, token) => db.transaction(() => {
+    if (token !== undefined && !own && key !== undefined)
+        throw new ToolError(REGISTERS_NO_KEY);
+    const row = (own
+        ? db
+            .prepare("SELECT id, name, key_hash, person FROM agents WHERE account_id = ? AND id = ? AND registered_at = ? AND instance IS ? AND removed_at IS NULL")
+            .get(account, own.id, own.registeredAt, own.instance)
+        : db
+            .prepare("SELECT id, name, key_hash, person, token_id FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+            .get(account, name));
+    if (!row)
+        throw new ToolError(own ? NOT_REGISTERED : `No agent named '${name}'.`);
+    if (row.person === 1)
+        throw new ToolError(personRefusal(row.name));
+    if (token !== undefined && !own) {
+        if (row.token_id !== token)
+            throw new ToolError(`Agent '${row.name}' was not registered by this token, which removes only agents it registered.`);
+    }
+    else if (row.key_hash !== null && !own) {
+        if (key === undefined)
+            throw new ToolError(`Agent '${row.name}' has a key. Pass its key to remove it.`);
+        if (!sameHash(hashKey(key), row.key_hash))
+            throw new ToolError(`Wrong key for agent '${row.name}'.`);
+    }
+    db.prepare("UPDATE agents SET name = ?, removed_name = name, removed_at = ?, key_hash = ?, instance = ?, status = NULL, status_at = NULL WHERE id = ?").run(removedName(row.id), Date.now(), REMOVED_KEY_HASH, REMOVED_INSTANCE, row.id);
+    const keptMessages = db.prepare("SELECT COUNT(*) AS n FROM messages WHERE recipient_id = ?").get(row.id).n;
+    return { removed: row.name, keptMessages };
+}).immediate();
+/**
+ * Ends every live agent the token of row id `token`, one that registers its own agents, registered in the account
+ * `account`, as `removeAgent` ends one: its name is freed, its row kept, marked removed, with its messages. Returns
+ * their names, in name order; none for any other token, as only a token that registers its own agents is ever stored
+ * on an agent (`registerWithIdentity`). Run inside the transaction that revokes the token, so no reader sees one
+ * without the other.
+ */
+export function endTokenAgents(db, account, token) {
+    // The new name is the one removedName gives. Every expression in SET reads the row as it was, so removed_name takes
+    // the live name. The unary + keeps SQLite finding the rows through agents_by_token, as listApprovals does.
+    const ended = db
+        .prepare(`UPDATE agents SET name = 'removed:' || id, removed_name = name, removed_at = ?, key_hash = ?, instance = ?, status = NULL, status_at = NULL
+       WHERE token_id = ? AND +account_id = ? AND removed_at IS NULL AND person = 0 RETURNING removed_name`)
+        .pluck()
+        .all(Date.now(), REMOVED_KEY_HASH, REMOVED_INSTANCE, token, account);
+    // In the order listApprovals lists them: names are ASCII and agents.name is COLLATE NOCASE, so case is ignored, and
+    // no two live names of an account differ only in case.
+    const key = (n) => n.toLowerCase();
+    return ended.sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+}
+export class PurgeError extends Error {
+}
+/**
+ * For `message-cp agent remove`: removes the agent `name` (any case) of the account named `account`, live or only
+ * left as removed rows, with every direct message to or from it and its mentions, and frees its name as `removeAgent`
+ * does. Channels, posts and read positions stay. The rows stay too, marked removed: posts and read positions point
+ * at them. Refuses, changing nothing, a live person's name, a name no agent of the account has had, or an unknown
+ * account.
+ */
+export const purgeAgent = (db, account, name) => db.transaction(() => {
+    const acct = db.prepare("SELECT id, name FROM accounts WHERE name = ?").get(account);
+    if (!acct)
+        throw new PurgeError(`No account named '${account}'.`);
+    const live = db
+        .prepare("SELECT id, name, person FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+        .get(acct.id, name);
+    // Before anything is deleted, so a person's messages, and any sent under the name they now have, are never touched.
+    if (live?.person === 1)
+        throw new PurgeError(`The name '${live.name}' belongs to a person, not an agent.`);
+    const removed = db
+        .prepare("SELECT id, removed_name FROM agents WHERE account_id = ? AND person = 0 AND removed_at IS NOT NULL AND removed_name = ? COLLATE NOCASE ORDER BY id")
+        .all(acct.id, name);
+    const ids = [...(live ? [live.id] : []), ...removed.map((r) => r.id)];
+    if (ids.length === 0)
+        throw new PurgeError(`No agent named '${name}' in account '${acct.name}'.`);
+    // The same rows as `ids`, as a subquery, so no statement needs one bound variable per registration. A person
+    // removed with `person remove` is not one of them.
+    const rows = `SELECT id FROM agents WHERE account_id = ? AND (id = ? OR (person = 0 AND removed_at IS NOT NULL AND removed_name = ? COLLATE NOCASE))`;
+    const rowArgs = [acct.id, live?.id ?? null, name];
+    // Two deletes, each searched by its own index (messages_history, then messages_by_sender), where one with OR scans
+    // every message. A message both match goes with the first, so the sum counts each once.
+    const messages = db.prepare(`DELETE FROM messages WHERE recipient_id IN (${rows})`).run(...rowArgs).changes +
+        db
+            .prepare("DELETE FROM messages WHERE sender = ? COLLATE NOCASE AND recipient_id IN (SELECT id FROM agents WHERE account_id = ?)")
+            .run(name, acct.id).changes;
+    const mentions = db.prepare(`DELETE FROM mentions WHERE agent_id IN (${rows})`).run(...rowArgs).changes;
+    if (live) {
+        db.prepare("UPDATE agents SET name = ?, removed_name = name, removed_at = ?, key_hash = ?, instance = ?, status = NULL, status_at = NULL WHERE id = ?").run(removedName(live.id), Date.now(), REMOVED_KEY_HASH, REMOVED_INSTANCE, live.id);
+    }
+    return { name: live?.name ?? removed[removed.length - 1].removed_name, account: acct.name, messages, mentions };
+}).immediate();
+export class KeyResetError extends Error {
+}
+/**
+ * For `message-cp agent key reset`: gives the live agent `name` (any case) of the account named `account` a new random
+ * key, returned this once; only its hash is stored. The row stays, so its id, bio, messages, mentions, channels and
+ * webhooks stay too. A new `instance` ends every session registered as the agent, as `nameOfIdentity` no longer matches
+ * their identity; `registered_at` is kept. Refuses, changing nothing, a person's name, a name with no live agent in the
+ * account, or an unknown account.
+ */
+export const resetAgentKey = (db, account, name) => db.transaction(() => {
+    const acct = db.prepare("SELECT id, name FROM accounts WHERE name = ?").get(account);
+    if (!acct)
+        throw new KeyResetError(`No account named '${account}'.`);
+    const live = db
+        .prepare("SELECT id, name, person FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+        .get(acct.id, name);
+    if (live?.person === 1)
+        throw new KeyResetError(`The name '${live.name}' belongs to a person, not an agent.`);
+    if (!live)
+        throw new KeyResetError(`No agent named '${name}' in account '${acct.name}'.`);
+    const key = randomBytes(32).toString("hex");
+    db.prepare("UPDATE agents SET key_hash = ?, instance = ? WHERE id = ?").run(hashKey(key), randomBytes(16).toString("hex"), live.id);
+    return { name: live.name, account: acct.name, key };
+}).immediate();
+export class PersonError extends Error {
+}
+// Matches no key and no session's instance, like REMOVED_KEY_HASH, so nothing can act as a person. The `person`
+// checks in registerWithIdentity and removeAgent are what refuse; this only keeps an older release from claiming it.
+const PERSON_KEY_HASH = "person";
+const PERSON_INSTANCE = "person";
+/**
+ * Adds the person `name` to the account named `account`, as a row of `agents` marked `person`, and `admin` with
+ * `admin`, so messages, mentions and webhooks reach it as they reach an agent. Refuses a name a live agent or person of
+ * that account has (any case).
+ */
+export const addPerson = (db, account, name, admin = false) => db.transaction(() => {
+    try {
+        validateName(name);
+    }
+    catch (err) {
+        if (err instanceof ToolError)
+            throw new PersonError(err.message);
+        throw err;
+    }
+    const acct = db.prepare("SELECT id, name FROM accounts WHERE name = ?").get(account);
+    if (!acct)
+        throw new PersonError(`No account named '${account}'.`);
+    const taken = db
+        .prepare("SELECT name, person FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+        .get(acct.id, name);
+    if (taken)
+        throw new PersonError(`The name '${taken.name}' is already used by ${taken.person === 1 ? "a person" : "an agent"} in account '${acct.name}'.`);
+    const now = Date.now();
+    db.prepare("INSERT INTO agents (account_id, name, bio, registered_at, last_seen, key_hash, instance, person, admin) VALUES (?, ?, '', ?, ?, ?, ?, 1, ?)").run(acct.id, name, now, now, PERSON_KEY_HASH, PERSON_INSTANCE, admin ? 1 : 0);
+    return { name, account: acct.name, addedAt: new Date(now).toISOString(), admin };
+}).immediate();
+/**
+ * For `message-cp person admin`: marks the live person `name` (any case) of the account named `account` an admin, or
+ * unmarks them with `admin` false. Their person tokens follow the mark from their next request, as `accountForToken`
+ * reads it each time. Refuses, changing nothing, an agent's name, a name no live person of the account has, or an
+ * unknown account.
+ */
+export const setPersonAdmin = (db, account, name, admin) => db.transaction(() => {
+    const acct = db.prepare("SELECT id, name FROM accounts WHERE name = ?").get(account);
+    if (!acct)
+        throw new PersonError(`No account named '${account}'.`);
+    const live = db
+        .prepare("SELECT id, name, person FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+        .get(acct.id, name);
+    if (live?.person === 0)
+        throw new PersonError(`The name '${live.name}' belongs to an agent, not a person.`);
+    if (!live)
+        throw new PersonError(`No person named '${name}' in account '${acct.name}'.`);
+    db.prepare("UPDATE agents SET admin = ? WHERE account_id = ? AND id = ? AND removed_at IS NULL AND person = 1").run(admin ? 1 : 0, acct.id, live.id);
+    return { name: live.name, account: acct.name, admin };
+}).immediate();
+/**
+ * For `message-cp person remove`: removes the live person `name` (any case) of the account named `account`, with every
+ * direct message to them or sent from the name since they were added, and their mentions, and frees the name, as
+ * `purgeAgent` does for an agent. Channels, posts and read positions stay, and so does the row, marked removed.
+ * Removed rows of earlier agents with that name, and the messages they sent, are left to `agent remove`. Refuses,
+ * changing nothing, an agent's name, a name no live person of the account has, or an unknown account.
+ */
+export const removePerson = (db, account, name) => db.transaction(() => {
+    const acct = db.prepare("SELECT id, name FROM accounts WHERE name = ?").get(account);
+    if (!acct)
+        throw new PersonError(`No account named '${account}'.`);
+    const live = db
+        .prepare("SELECT id, name, person, registered_at FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+        .get(acct.id, name);
+    // Before anything is deleted, so an agent's messages are never touched.
+    if (live?.person === 0)
+        throw new PersonError(`The name '${live.name}' belongs to an agent, not a person. Remove it with \`agent remove\`.`);
+    if (!live)
+        throw new PersonError(`No person named '${name}' in account '${acct.name}'.`);
+    // Only the person sends under the name while it is theirs, so messages from it since they were added, by the
+    // server's clock, are theirs; older ones are an earlier agent's, which keeps them until `agent remove`.
+    // Two deletes rather than one with OR, so each searches an index (messages_history, messages_by_pair) rather than
+    // scanning every message under the write lock. A message to themselves goes with the first.
+    const messages = db.prepare("DELETE FROM messages WHERE recipient_id = ?").run(live.id).changes +
+        db
+            .prepare(`DELETE FROM messages WHERE sender = ? COLLATE NOCASE AND created_at >= ?
+           AND recipient_id IN (SELECT id FROM agents WHERE account_id = ?)`)
+            .run(live.name, live.registered_at, acct.id).changes;
+    const mentions = db.prepare("DELETE FROM mentions WHERE agent_id = ?").run(live.id).changes;
+    db.prepare("UPDATE agents SET name = ?, removed_name = name, removed_at = ?, key_hash = ?, instance = ?, status = NULL, status_at = NULL WHERE id = ?").run(removedName(live.id), Date.now(), REMOVED_KEY_HASH, REMOVED_INSTANCE, live.id);
+    return { name: live.name, account: acct.name, messages, mentions };
+}).immediate();
+/** The live people of the account named `account`, or of every account without it, by account then name. */
+export function listPeople(db, account) {
+    if (account !== undefined && !db.prepare("SELECT 1 FROM accounts WHERE name = ?").get(account)) {
+        throw new PersonError(`No account named '${account}'.`);
+    }
+    const rows = db
+        .prepare(`SELECT agents.name, accounts.name AS account, agents.registered_at, agents.admin
+       FROM agents JOIN accounts ON accounts.id = agents.account_id
+       WHERE agents.person = 1 AND agents.removed_at IS NULL AND (? IS NULL OR accounts.name = ?)
+       ORDER BY accounts.name, agents.name`)
+        .all(account ?? null, account ?? null);
+    return rows.map((r) => ({ name: r.name, account: r.account, addedAt: new Date(r.registered_at).toISOString(), admin: r.admin === 1 }));
+}
+export class AgentListError extends Error {
+}
+/**
+ * For `message-cp agent list`: the live agents (not people) of the account named `account`, or of every account
+ * without it, by account then name. Returns no key or hash.
+ */
+export function listServerAgents(db, account) {
+    if (account !== undefined && !db.prepare("SELECT 1 FROM accounts WHERE name = ?").get(account)) {
+        throw new AgentListError(`No account named '${account}'.`);
+    }
+    const rows = db
+        .prepare(`SELECT agents.name, accounts.name AS account, agents.registered_at, agents.last_seen
+       FROM agents JOIN accounts ON accounts.id = agents.account_id
+       WHERE agents.person = 0 AND agents.removed_at IS NULL AND (? IS NULL OR accounts.name = ?)
+       ORDER BY accounts.name, agents.name`)
+        .all(account ?? null, account ?? null);
+    return rows.map((r) => ({
+        name: r.name,
+        account: r.account,
+        registeredAt: new Date(r.registered_at).toISOString(),
+        lastSeen: new Date(r.last_seen).toISOString(),
+    }));
+}