message-cp 0.0.0-stage → 0.1.0

package/dist/messages.js

@@ -0,0 +1,513 @@
+import { NAME_PATTERN, STATUS_TTL_MS, ToolError, actingPerson, getAgent } from "./agents.js";
+export const MAX_BODY_LENGTH = 4000;
+export const DEFAULT_INBOX_LIMIT = 50;
+export const MAX_INBOX_LIMIT = 200;
+function countCodePoints(s) {
+    let n = 0;
+    for (const _ of s)
+        n++;
+    return n;
+}
+/** Throws unless `body` is a valid message: not empty or only whitespace, at most MAX_BODY_LENGTH characters. */
+export function validateBody(body, kind = "Message") {
+    if (body.trim().length === 0)
+        throw new ToolError(`${kind} body is empty.`);
+    // Count characters (code points), not UTF-16 code units, to match what the tool advertises.
+    // A code point is at most 2 code units, so anything over twice the limit is too long without iterating.
+    if (body.length > 2 * MAX_BODY_LENGTH || countCodePoints(body) > MAX_BODY_LENGTH) {
+        throw new ToolError(`${kind} is too long: at most ${MAX_BODY_LENGTH} characters.`);
+    }
+}
+/**
+ * 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,
+ * which is always the sender's. `own` is the sending agent's registration, whose status line the send clears; a
+ * person sends without one. `inReplyTo`, which needs `own`, is the id of a message stored for that registration, which
+ * each stored row records; any other id throws the same error, so it does not tell whether the id exists.
+ */
+export function sendMessage(db, account, from, to, body, own, inReplyTo) {
+    validateBody(body);
+    const broadcast = to.toLowerCase() === "all";
+    // IMMEDIATE takes the write lock up front, so the recipient list cannot change under us.
+    return db
+        .transaction(() => {
+        // Checked against the caller's own live row, so another account's or agent's message, or a removed agent's that
+        // had the caller's name, fails as an unknown id does.
+        if (inReplyTo !== undefined) {
+            const answered = own &&
+                db
+                    .prepare(`SELECT 1 FROM messages WHERE id = ? AND recipient_id = (SELECT id FROM agents WHERE account_id = ? AND id = ?
+                 AND registered_at = ? AND instance IS ? AND removed_at IS NULL)`)
+                    .get(inReplyTo, account, own.id, own.registeredAt, own.instance);
+            if (!answered)
+                throw new ToolError(`No message ${inReplyTo} was sent to you.`);
+        }
+        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")
+                .all(account, from);
+        }
+        else {
+            const agent = getAgent(db, account, to);
+            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")
+                .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 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);
+            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
+        // removed meanwhile never clears the line of a later agent with the same name.
+        if (own) {
+            db.prepare("UPDATE agents SET status = NULL, status_at = NULL WHERE account_id = ? AND id = ? AND registered_at = ? AND instance IS ? AND removed_at IS NULL AND person = 0 AND status IS NOT NULL").run(account, own.id, own.registeredAt, own.instance);
+        }
+        return { delivered: recipients.length, recipients: recipients.map((r) => r.name), messages: stored };
+    })
+        .immediate();
+}
+/**
+ * `sendMessage` from the account's live person `as`, under the person's stored name. Undefined, with nothing stored,
+ * if `as` is not a live person of the account, so an agent's name, a removed one and an unknown one are alike. With
+ * `only`, a person token's person's row id, throws `WrongPersonError`, storing nothing, unless `as` is that row.
+ */
+export function sendAsPerson(db, account, as, to, body, only) {
+    validateBody(body);
+    // One transaction, so the person cannot be removed between the check and the send.
+    return db
+        .transaction(() => {
+        const person = actingPerson(db, account, as, only);
+        return person && sendMessage(db, account, person.name, to, body);
+    })
+        .immediate();
+}
+/**
+ * `sendMessage` from the agent `own` to the one live agent `to`, as `ask` sends its question: `all` and a person are
+ * refused, as a person cannot reply with an id, and an unknown name fails as in `sendMessage`. One transaction, so `to`
+ * cannot become a person between the check and the send.
+ */
+export function sendQuestion(db, account, own, to, body) {
+    validateBody(body);
+    if (to.toLowerCase() === "all")
+        throw new ToolError("ask goes to one agent, so to cannot be 'all'.");
+    return db
+        .transaction(() => {
+        const agent = getAgent(db, account, to);
+        if (agent?.person)
+            throw new ToolError(`'${agent.name}' is a person, who cannot answer ask; use send_message.`);
+        return sendMessage(db, account, own.name, to, body, own);
+    })
+        .immediate();
+}
+/**
+ * The earliest message from `from`, the agent asked, to `own`'s live row that answers message `questionId`, marked read
+ * as `readInbox` would mark it. Null when there is none yet, undefined when `own` is no longer registered, even if
+ * another agent now has its name. Found through the caller's row, so another account's or agent's reply never matches,
+ * and by its sender, so an answer from anyone but the agent asked never matches either.
+ */
+export function takeReply(db, account, own, questionId, from) {
+    const find = () => {
+        const agent = db
+            .prepare("SELECT id 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);
+        if (!agent)
+            return undefined;
+        return db.prepare(TAKE_REPLY_SQL).get(questionId, agent.id, from) ?? null;
+    };
+    // A plain read first, which never waits for the write lock, so a poll with no reply yet takes no lock; the lock is
+    // taken only to mark a reply read, and the caller's row and the reply are found again under it.
+    const seen = db.transaction(find)();
+    if (!seen)
+        return seen;
+    return db
+        .transaction(() => {
+        const r = find();
+        if (!r)
+            return r;
+        db.prepare("UPDATE messages SET read_at = ? WHERE id = ? AND read_at IS NULL").run(Date.now(), r.id);
+        return {
+            id: r.id,
+            inReplyTo: r.in_reply_to,
+            from: r.sender,
+            sentAt: new Date(r.created_at).toISOString(),
+            body: r.body,
+            broadcast: r.broadcast === 1,
+        };
+    })
+        .immediate();
+}
+// Found through messages_by_question, whose rows for one recipient and question are already in id order, so replies
+// to the question sent to other agents are never read. The sender is checked on those rows only.
+export const TAKE_REPLY_SQL = `SELECT id, sender, body, broadcast, created_at, in_reply_to FROM messages
+  WHERE in_reply_to = ? AND recipient_id = ? AND sender = ? COLLATE NOCASE ORDER BY id LIMIT 1`;
+/**
+ * One page of the caller's messages and mentions together, oldest first. Everything returned is marked read. Unread
+ * ones beyond the page stay unread for the next call; with `unreadOnly` false, use `offset`. Reading a mention does
+ * not move the caller's read position in its channel. `reader` is the caller's name, or its registration.
+ */
+export function readInbox(db, account, reader, unreadOnly = true, limit = DEFAULT_INBOX_LIMIT, offset = 0) {
+    return db
+        .transaction(() => {
+        // A session passes its registration, so a name taken over since the session checked it reads nothing.
+        const agent = (typeof reader === "string"
+            ? db.prepare("SELECT id FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL").get(account, reader)
+            : db
+                .prepare("SELECT id FROM agents WHERE account_id = ? AND id = ? AND registered_at = ? AND instance IS ? AND removed_at IS NULL")
+                .get(account, reader.id, reader.registeredAt, reader.instance));
+        if (!agent)
+            return [];
+        // Oldest first; a message before a mention of the same millisecond, and each kind in id order.
+        const rows = db
+            .prepare(`SELECT 0 AS mention, id, sender, body, broadcast, created_at, NULL AS channel, in_reply_to
+           FROM messages WHERE recipient_id = ? ${unreadOnly ? "AND read_at IS NULL" : ""}
+           UNION ALL
+           SELECT 1, p.id, p.sender, p.body, 0, p.created_at, c.name, NULL
+           FROM mentions x JOIN channel_posts p ON p.id = x.post_id
+           JOIN channels c ON c.id = p.channel_id AND c.account_id = ?
+           WHERE x.agent_id = ? ${unreadOnly ? "AND x.read_at IS NULL" : ""}
+           ORDER BY created_at, mention, id LIMIT ? OFFSET ?`)
+            .all(agent.id, account, agent.id, Math.min(limit, MAX_INBOX_LIMIT), offset);
+        const markMessage = db.prepare("UPDATE messages SET read_at = ? WHERE id = ? AND read_at IS NULL");
+        const markMention = db.prepare("UPDATE mentions SET read_at = ? WHERE agent_id = ? AND post_id = ? AND read_at IS NULL");
+        const now = Date.now();
+        for (const r of rows) {
+            if (r.mention === 1)
+                markMention.run(now, agent.id, r.id);
+            else
+                markMessage.run(now, r.id);
+        }
+        return rows.map((r) => r.mention === 1
+            ? { channel: r.channel, id: r.id, from: r.sender, sentAt: new Date(r.created_at).toISOString(), body: r.body }
+            : {
+                id: r.id,
+                inReplyTo: r.in_reply_to,
+                from: r.sender,
+                sentAt: new Date(r.created_at).toISOString(),
+                body: r.body,
+                broadcast: r.broadcast === 1,
+            });
+    })
+        .immediate();
+}
+export const NOT_YOUR_MESSAGES = "Not every id is a message you sent.";
+// The ids are one bound JSON array; CROSS JOIN keeps them first, so each row is found by its primary key.
+export const MESSAGE_STATUS_SQL = `SELECT m.id, CASE WHEN a.removed_at IS NULL THEN a.name ELSE a.removed_name END AS recipient, m.read_at
+  FROM json_each(?) j CROSS JOIN messages m ON m.id = j.value JOIN agents a ON a.id = m.recipient_id AND a.account_id = ?
+  WHERE m.sender = ? COLLATE NOCASE AND m.created_at >= ?`;
+/**
+ * The recipient and read state of each of `ids`, in the order asked, a repeated id once. `sender` is only a name, so
+ * sent means sent under the caller's name since its row was registered, as `readConversation` matches it, to a
+ * recipient of the caller's account; a removed recipient is named by the name it had. Any other id, or a caller removed
+ * since the session checked it, throws one error, so it does not tell whether an id exists. Reads only.
+ */
+export function messageStatus(db, account, caller, ids) {
+    const wanted = [...new Set(ids)];
+    // One read transaction, so the caller's row and the messages are read at the same moment.
+    return db.transaction(() => {
+        const me = db
+            .prepare("SELECT name, registered_at FROM agents WHERE account_id = ? AND id = ? AND registered_at = ? AND instance IS ? AND removed_at IS NULL")
+            .get(account, caller.id, caller.registeredAt, caller.instance);
+        if (!me)
+            throw new ToolError(NOT_YOUR_MESSAGES);
+        const rows = db
+            .prepare(MESSAGE_STATUS_SQL)
+            .all(JSON.stringify(wanted), account, me.name, me.registered_at);
+        if (rows.length !== wanted.length)
+            throw new ToolError(NOT_YOUR_MESSAGES);
+        const byId = new Map(rows.map((r) => [r.id, r]));
+        return wanted.map((id) => {
+            const r = byId.get(id);
+            return { id, to: r.recipient, read: r.read_at !== null, readAt: r.read_at === null ? null : new Date(r.read_at).toISOString() };
+        });
+    })();
+}
+/**
+ * One page of the direct messages between `reader` and the live agent or person `other` (any case), both directions,
+ * newest first. Received means addressed to the reader's own row, so a removed agent's mail never shows. `sender` is
+ * only a name, so sent means sent under the reader's name since its row was registered: a removed agent that once had
+ * the name sent the rest. Reads only: nothing is marked read. Throws send_message's error for an unknown or removed
+ * `other`; returns nothing if the reader's registration is no longer live.
+ */
+export function readConversation(db, account, reader, other, limit = DEFAULT_INBOX_LIMIT, offset = 0) {
+    // One read transaction, so both directions and the rows they name are read at the same moment.
+    return db.transaction(() => {
+        const them = getAgent(db, account, other);
+        if (!them)
+            throw new ToolError(`No agent named '${other}'.`);
+        const me = db
+            .prepare("SELECT id, name, registered_at FROM agents WHERE account_id = ? AND id = ? AND registered_at = ? AND instance IS ? AND removed_at IS NULL")
+            .get(account, reader.id, reader.registeredAt, reader.instance);
+        if (!me)
+            return [];
+        const self = me.name.toLowerCase() === them.name.toLowerCase();
+        // Each direction reads the pair's messages_by_pair rows already in page order, so the page stops after
+        // limit + offset rows. With oneself the two directions are the same rows, so only the received one runs, and
+        // each message appears once.
+        const rows = db
+            .prepare(`SELECT id, sender, ? AS recipient, body, broadcast, created_at, in_reply_to FROM messages
+         WHERE recipient_id = ? AND sender = ? COLLATE NOCASE
+         ${self ? "" : `UNION ALL
+         SELECT id, sender, ?, body, broadcast, created_at, in_reply_to FROM messages
+         WHERE recipient_id = (SELECT id FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL)
+           AND sender = ? COLLATE NOCASE AND created_at >= ?`}
+         ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?`)
+            .all(me.name, me.id, them.name, ...(self ? [] : [them.name, account, them.name, me.name, me.registered_at]), Math.min(limit, MAX_INBOX_LIMIT), offset);
+        return rows.map((r) => ({
+            id: r.id,
+            inReplyTo: r.in_reply_to,
+            from: r.sender,
+            to: r.recipient,
+            sentAt: new Date(r.created_at).toISOString(),
+            body: r.body,
+            broadcast: r.broadcast === 1,
+        }));
+    })();
+}
+/** Whether `unread` is anything to wake for: an unread message, an unread post in a joined channel or a mention. */
+export const hasUnread = (unread) => unread.count > 0 || unread.posts > 0 || unread.mentions > 0;
+/**
+ * How many unread messages `reader` has and who sent them, how many unread posts are in the channels it has joined and
+ * where, and how many unread mentions it has and where, without reading or marking anything. `reader` is a name, as
+ * `wait` and GET /wait pass it, or a registration, as `wait_for_mail` passes it, so a registration that has been
+ * removed, or whose key was reset, counts nothing even if another agent now has its name; a takeover with the key keeps
+ * the same row and counts as before. Undefined if there is no such agent.
+ */
+export function unreadSummary(db, account, reader) {
+    // One read transaction, so the messages and the posts are counted at the same moment.
+    return db.transaction(() => {
+        const agent = (typeof reader === "string"
+            ? db.prepare("SELECT id FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL").get(account, reader)
+            : db
+                .prepare("SELECT id FROM agents WHERE account_id = ? AND id = ? AND registered_at = ? AND instance IS ? AND removed_at IS NULL")
+                .get(account, reader.id, reader.registeredAt, reader.instance));
+        if (!agent)
+            return undefined;
+        // One query each, so a count and its names always describe the same rows.
+        const messages = db
+            .prepare(`SELECT m.sender, COUNT(*) AS n FROM messages m JOIN agents a ON a.id = m.recipient_id
+         WHERE a.account_id = ? AND a.id = ? AND a.removed_at IS NULL AND m.read_at IS NULL GROUP BY m.sender ORDER BY MIN(m.id)`)
+            .all(account, agent.id);
+        // The agent's own posts never count as unread, as in list_channels.
+        const posts = db
+            .prepare(`SELECT c.name, COUNT(*) AS n FROM agents a
+         JOIN channel_reads r ON r.agent_id = a.id AND r.joined = 1
+         JOIN channels c ON c.id = r.channel_id AND c.account_id = a.account_id
+         JOIN channel_posts p ON p.channel_id = c.id AND p.id > r.last_read_id AND p.sender_id <> a.id
+         WHERE a.account_id = ? AND a.id = ? AND a.removed_at IS NULL GROUP BY c.id ORDER BY MIN(p.id)`)
+            .all(account, agent.id);
+        const mentions = db
+            .prepare(`SELECT c.name, COUNT(*) AS n FROM agents a
+         JOIN mentions x ON x.agent_id = a.id AND x.read_at IS NULL
+         JOIN channel_posts p ON p.id = x.post_id
+         JOIN channels c ON c.id = p.channel_id AND c.account_id = a.account_id
+         WHERE a.account_id = ? AND a.id = ? AND a.removed_at IS NULL GROUP BY c.id ORDER BY MIN(p.id)`)
+            .all(account, agent.id);
+        return {
+            count: messages.reduce((sum, r) => sum + r.n, 0),
+            senders: messages.map((r) => r.sender),
+            posts: posts.reduce((sum, r) => sum + r.n, 0),
+            channels: posts.map((r) => r.name),
+            mentions: mentions.reduce((sum, r) => sum + r.n, 0),
+            mentionChannels: mentions.map((r) => r.name),
+        };
+    })();
+}
+/**
+ * One page of the account's live agents in name order, as `list_agents` pages them, each with its unread message, post
+ * and mention totals counted as `unreadSummary` counts them, and its status line while it is current at `now`. One
+ * query for the page, totals only: no senders or channels.
+ */
+export function listAgentsUnread(db, account, limit, offset, now = Date.now()) {
+    const rows = db
+        .prepare(`SELECT a.name, a.bio, a.last_seen, a.person,
+         CASE WHEN a.person = 0 AND a.status_at > ? THEN a.status END AS status,
+         (SELECT COUNT(*) FROM messages m WHERE m.recipient_id = a.id AND m.read_at IS NULL) AS messages,
+         (SELECT COUNT(*) FROM channel_reads r
+            JOIN channels c ON c.id = r.channel_id AND c.account_id = a.account_id
+            JOIN channel_posts p ON p.channel_id = c.id AND p.id > r.last_read_id AND p.sender_id <> a.id
+          WHERE r.agent_id = a.id AND r.joined = 1) AS posts,
+         (SELECT COUNT(*) FROM mentions x
+            JOIN channel_posts p ON p.id = x.post_id
+            JOIN channels c ON c.id = p.channel_id AND c.account_id = a.account_id
+          WHERE x.agent_id = a.id AND x.read_at IS NULL) AS mentions
+       FROM agents a WHERE a.account_id = ? AND a.removed_at IS NULL ORDER BY a.name LIMIT ? OFFSET ?`)
+        .all(now - STATUS_TTL_MS, account, limit, offset);
+    return rows.map((r) => ({
+        name: r.name,
+        bio: r.bio,
+        lastSeen: new Date(r.last_seen).toISOString(),
+        person: r.person === 1,
+        status: r.status,
+        unreadMessages: r.messages,
+        unreadPosts: r.posts,
+        unreadMentions: r.mentions,
+    }));
+}
+/**
+ * One page of the account's messages, oldest first, for the account rather than for one agent. A broadcast is one row
+ * per recipient, so it appears once per recipient. A message to a removed agent shows the name it had. With `unreadOnly`,
+ * only the messages to an agent, not to a person, whose recipient has not read them: a person has no `read_inbox`, so
+ * every message to one would stay among them for good. `starting` is read from the message's own webhook deliveries,
+ * found through `webhook_deliveries_delivered_by_message`. Reads only, so nothing is marked read and no delivery is touched.
+ */
+export function listAccountMessages(db, account, limit, offset, unreadOnly = false) {
+    const rows = db
+        .prepare(`SELECT m.id, m.sender, CASE WHEN a.removed_at IS NULL THEN a.name ELSE a.removed_name END AS recipient,
+              m.body, m.broadcast, m.created_at, m.read_at, a.person,
+              EXISTS (SELECT 1 FROM webhook_deliveries d
+                      WHERE d.message_id = m.id AND d.delivered_at IS NOT NULL) AS delivered
+       FROM messages m JOIN agents a ON a.id = m.recipient_id
+       WHERE a.account_id = ?${unreadOnly ? " AND a.person = 0 AND m.read_at IS NULL" : ""} ORDER BY m.id LIMIT ? OFFSET ?`)
+        .all(account, Math.min(limit, MAX_INBOX_LIMIT), offset);
+    return rows.map((r) => ({
+        id: r.id,
+        from: r.sender,
+        to: r.recipient,
+        sentAt: new Date(r.created_at).toISOString(),
+        body: r.body,
+        broadcast: r.broadcast === 1,
+        read: r.read_at !== null,
+        starting: r.read_at === null && r.person === 0 && r.delivered === 1,
+    }));
+}
+/**
+ * Deletes the account's messages between `first` and `second`, either way and in any case: exactly the rows
+ * `listAccountMessages` lists with that `from` and `to`, broadcasts and messages to a removed agent's old name included.
+ * Their webhook deliveries go with them. Returns how many were deleted.
+ */
+export function deleteConversation(db, account, first, second) {
+    // One statement per direction, so each reads only the messages_by_sender rows for that pair, not the account's history.
+    const fromTo = db.prepare(`DELETE FROM messages
+     WHERE recipient_id IN (SELECT id FROM agents WHERE account_id = ?
+                              AND (CASE WHEN removed_at IS NULL THEN name ELSE removed_name END) = ? COLLATE NOCASE)
+       AND sender = ? COLLATE NOCASE`);
+    return db.transaction(() => {
+        const there = fromTo.run(account, second, first).changes;
+        // A conversation with oneself is one direction; running it twice would only find nothing the second time.
+        return there + fromTo.run(account, first, second).changes;
+    }).immediate();
+}
+export const MAX_SEARCH_LENGTH = 200;
+// A date, or a date and time (to the millisecond) with an optional offset; a time with no offset is UTC, like a date
+// alone.
+const ISO_TIME = /^(\d{4})-(\d{2})-(\d{2})(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+function parseTime(value, field) {
+    const m = ISO_TIME.exec(value);
+    const ms = m ? Date.parse(value.includes("T") && !m[4] ? `${value}Z` : value) : NaN;
+    // Date.parse rolls 2026-02-30 over to March, so the date has to come back unchanged. setUTCFullYear keeps years 0-99,
+    // which Date.UTC would read as 1900-1999.
+    const day = m && new Date(new Date(0).setUTCFullYear(+m[1], +m[2] - 1, +m[3]));
+    if (!m || Number.isNaN(ms) || day.getUTCMonth() !== +m[2] - 1 || day.getUTCDate() !== +m[3]) {
+        throw new ToolError(`Invalid ${field}: use an ISO 8601 time such as 2026-10-20 or 2026-10-20T12:00:00Z.`);
+    }
+    return ms;
+}
+/** Throws a ToolError unless `text` and `filters` are valid search arguments; otherwise the SQL filter they make. */
+function searchQuery(text, filters) {
+    if (text.length === 0 || text.length > 2 * MAX_SEARCH_LENGTH || countCodePoints(text) > MAX_SEARCH_LENGTH) {
+        throw new ToolError(`Search text must be 1 to ${MAX_SEARCH_LENGTH} characters.`);
+    }
+    const { channel, from } = filters;
+    if (channel !== undefined && !NAME_PATTERN.test(channel)) {
+        throw new ToolError("Invalid channel name: use 1-32 characters from letters, digits, '-' and '_'.");
+    }
+    const since = filters.since === undefined ? null : parseTime(filters.since, "since");
+    const until = filters.until === undefined ? null : parseTime(filters.until, "until");
+    const pattern = `%${text.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+    const where = (t) => `${t}.body LIKE ? ESCAPE '\\' AND (? IS NULL OR ${t}.sender = ? COLLATE NOCASE)
+    AND (? IS NULL OR ${t}.created_at >= ?) AND (? IS NULL OR ${t}.created_at < ?)`;
+    return { channel, where, params: [pattern, from ?? null, from ?? null, since, since, until, until] };
+}
+/** The posts half of a search, newest first, scoped to the account's channels; its first placeholder is the account. */
+const searchPosts = ({ channel, where }) => `SELECT 1 AS is_post, p.id, p.sender, p.body, 0 AS broadcast, p.created_at, c.name AS channel, NULL AS recipient, NULL AS read_at,
+     NULL AS in_reply_to
+   FROM channel_posts p JOIN channels c ON c.id = p.channel_id AND c.account_id = ?
+   WHERE ${channel === undefined ? "" : "c.name = ? AND "}${where("p")}`;
+// Newest first; at the same millisecond a post before a message, and each kind newest id first.
+const SEARCH_ORDER = "ORDER BY created_at DESC, is_post DESC, id DESC LIMIT ? OFFSET ?";
+/** A post row of a search page, as both searches return it. */
+const toPost = (r) => ({
+    kind: "post",
+    channel: r.channel,
+    id: r.id,
+    from: r.sender,
+    sentAt: new Date(r.created_at).toISOString(),
+    body: r.body,
+});
+/**
+ * One page of what the caller could already read whose body contains `text` (ASCII letters in any case), newest
+ * first: the messages it received and the posts in its account's channels. `reader` is the caller's registration, so
+ * a later agent with a removed agent's name finds none of its messages. Reads only: nothing is marked read and no
+ * channel read position moves.
+ */
+export function search(db, account, reader, text, filters = {}, limit = DEFAULT_INBOX_LIMIT, offset = 0) {
+    const query = searchQuery(text, filters);
+    const { channel, where, params } = query;
+    return db.transaction(() => {
+        const agent = db
+            .prepare("SELECT id FROM agents WHERE account_id = ? AND id = ? AND registered_at = ? AND instance IS ? AND removed_at IS NULL")
+            .get(account, reader.id, reader.registeredAt, reader.instance);
+        if (!agent)
+            return [];
+        const rows = db
+            .prepare(`SELECT * FROM (
+           ${channel === undefined ? `SELECT 0 AS is_post, m.id, m.sender, m.body, m.broadcast, m.created_at, NULL AS channel, NULL AS recipient, NULL AS read_at, m.in_reply_to FROM messages m WHERE m.recipient_id = ? AND ${where("m")} UNION ALL` : ""}
+           ${searchPosts(query)})
+         ${SEARCH_ORDER}`)
+            .all(...(channel === undefined ? [agent.id, ...params] : []), account, ...(channel === undefined ? [] : [channel]), ...params, Math.min(limit, MAX_INBOX_LIMIT), offset);
+        return rows.map((r) => r.is_post === 1
+            ? toPost(r)
+            : {
+                kind: "message",
+                id: r.id,
+                inReplyTo: r.in_reply_to,
+                from: r.sender,
+                sentAt: new Date(r.created_at).toISOString(),
+                body: r.body,
+                broadcast: r.broadcast === 1,
+            });
+    })();
+}
+/**
+ * `search` for the account rather than for one agent: one page of the account's messages, to any of its agents, and
+ * its channels' posts whose body contains `text`, newest first, with the same arguments and errors. A message is
+ * scoped through its recipient's account, as in `listAccountMessages`, and a broadcast appears once per recipient.
+ * Reads only: nothing is marked read and no channel read position moves.
+ */
+export function searchAccount(db, account, text, filters = {}, limit = DEFAULT_INBOX_LIMIT, offset = 0) {
+    const query = searchQuery(text, filters);
+    const { channel, where, params } = query;
+    // The messages half selects in_reply_to only to match searchPosts' columns; GET /api/search does not return it.
+    const rows = db
+        .prepare(`SELECT * FROM (
+         ${channel === undefined ? `SELECT 0 AS is_post, m.id, m.sender, m.body, m.broadcast, m.created_at, NULL AS channel,
+             CASE WHEN a.removed_at IS NULL THEN a.name ELSE a.removed_name END AS recipient, m.read_at, m.in_reply_to
+           FROM messages m JOIN agents a ON a.id = m.recipient_id AND a.account_id = ? WHERE ${where("m")} UNION ALL` : ""}
+         ${searchPosts(query)})
+       ${SEARCH_ORDER}`)
+        .all(...(channel === undefined ? [account, ...params] : []), account, ...(channel === undefined ? [] : [channel]), ...params, Math.min(limit, MAX_INBOX_LIMIT), offset);
+    return rows.map((r) => r.is_post === 1
+        ? toPost(r)
+        : {
+            kind: "message",
+            id: r.id,
+            from: r.sender,
+            to: r.recipient,
+            sentAt: new Date(r.created_at).toISOString(),
+            body: r.body,
+            broadcast: r.broadcast === 1,
+            read: r.read_at !== null,
+        });
+}