message-cp 0.0.0-stage → 0.1.0

package/dist/approve.js

@@ -0,0 +1,260 @@
+import { createHash } from "node:crypto";
+import { STYLE } from "./dashboard.js";
+import { agentNameBase, isLoopback, isMetadataUrl } from "./oauth.js";
+// The page a person approves an MCP client on, served at the authorization endpoint of `serve --public-url` without a
+// token, in the dashboard's look. It first asks GET /oauth/signin whether this browser is signed in to the dashboard
+// (the sign-in cookie, which no page script can read). Signed in, it says who approves ("Approving as maria"), hides the
+// token field and offers an agent name no live agent of the account has, made from the client's name, so one click
+// approves; POST /oauth/approve then carries no token, the server signs it in by the cookie, and refuses it (409) if the
+// cookie now signs in as someone other than the page showed. Only under an https public URL; elsewhere GET /oauth/signin
+// is 404 and the page stays signed out. Not signed in, it links
+// to the dashboard in a new tab, checks again when the page regains focus or on "Check again", and meanwhile asks for a
+// full or person token of the account, sent once in the Authorization header and kept only in the form field, never in
+// storage. On approval it goes to the address the server answers with, the client's redirect URI with a code; refusing
+// goes to the redirect URI with error=access_denied. "This client registers its own agents", when ticked, sends
+// `registers: true` in place of the agent name, which is then neither required nor sent. Client-supplied text is put on
+// the page HTML-escaped by the server, never as markup, and the server's answers with textContent.
+const PAGE_STYLE = `${STYLE}
+main { margin: 10vh auto var(--s4); width: min(32rem, 100% - 2 * var(--s4)); display: flex; flex-direction: column; gap: var(--s3); }
+main h1 { display: flex; align-items: center; gap: var(--s2); }
+main h2, main p { margin: 0; }
+.client { font-family: var(--font-mono); font-weight: 600; overflow-wrap: anywhere; }
+.warn { padding: var(--s2) var(--s3); background: var(--error-bg); color: var(--error); border-radius: var(--radius); }
+#approve { display: flex; flex-direction: column; gap: var(--s1); }
+#approve input:not([type="checkbox"]) { width: 100%; padding: var(--s2); margin-bottom: var(--s2); background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius); }
+.actions { display: flex; gap: var(--s2); }
+#approve-yes { background: var(--accent); border-color: var(--accent); color: var(--bg); font-weight: 600; }
+#approve-yes:hover:enabled { background: color-mix(in srgb, var(--accent) 85%, var(--text)); }
+#approve-note.error { color: var(--error); }
+#signed-in { font-weight: 600; }
+.choice { display: flex; align-items: center; gap: var(--s2); margin-bottom: var(--s2); }
+`;
+const SCRIPT = `
+"use strict";
+const TIMEOUT_MS = 15000;
+const form = document.getElementById("approve");
+const token = document.getElementById("approve-token");
+const tokenField = document.getElementById("token-field");
+const signedIn = document.getElementById("signed-in");
+const signedOut = document.getElementById("signed-out");
+const again = document.getElementById("signin-again");
+const agent = document.getElementById("approve-agent");
+const agentField = document.getElementById("agent-field");
+const registers = document.getElementById("approve-registers");
+const yes = document.getElementById("approve-yes");
+const no = document.getElementById("approve-no");
+const note = document.getElementById("approve-note");
+let busy = false;
+// Whether the last GET /oauth/signin found a sign-in, who it signs in as ({ account, person? }, sent back with an approval
+// so the server refuses one whose sign-in changed since), and the agent name it offered, if the field still holds it as
+// offered: any edit by the person clears it, so a name they type, even the same one, is theirs.
+let cookie = false;
+let who;
+let suggested;
+// Bumped by each check, so only the newest check's answer changes the page.
+let checks = 0;
+function say(text, error) {
+  note.textContent = text;
+  note.classList.toggle("error", error);
+}
+// Shows the page signed in, saying \`text\`, or, for undefined, signed out with the token field.
+function show(text) {
+  cookie = text !== undefined;
+  if (!cookie) who = undefined;
+  signedIn.textContent = cookie ? text : "";
+  signedIn.hidden = !cookie;
+  signedOut.hidden = cookie;
+  tokenField.hidden = cookie;
+  token.required = !cookie;
+  if (cookie) token.value = "";
+}
+// Asks GET /oauth/signin, relative to this page as approve is, who this browser is signed in to the dashboard as. An
+// answer that comes after a newer check, or while an approval is in flight, is dropped; no answer leaves the page as it is.
+async function check() {
+  const n = ++checks;
+  const ac = new AbortController();
+  const deadline = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  let res;
+  let answer;
+  try {
+    res = await fetch("signin?" + new URLSearchParams({ base: form.dataset.base }), {
+      cache: "no-store",
+      credentials: "same-origin",
+      referrerPolicy: "no-referrer",
+      signal: ac.signal,
+    });
+    answer = await res.json().catch(() => undefined);
+  } catch {
+    res = undefined;
+  } finally {
+    clearTimeout(deadline);
+  }
+  if (n !== checks || busy || !res) return;
+  if (res.ok && answer && typeof answer.account === "string") {
+    who = typeof answer.person === "string" ? { account: answer.account, person: answer.person } : { account: answer.account };
+    show(who.person !== undefined ? "Approving as " + who.person : "Approving with a full token of account " + who.account);
+    if (typeof answer.name === "string" && (agent.value.trim() === "" || agent.value.trim() === suggested)) {
+      agent.value = answer.name;
+      suggested = answer.name;
+    }
+  } else if (res.status === 401 || res.status === 403) {
+    show(undefined);
+  }
+}
+form.addEventListener("submit", async (event) => {
+  event.preventDefault();
+  if (busy) return;
+  busy = true;
+  checks++;
+  yes.disabled = true;
+  say("Approving…", false);
+  const ac = new AbortController();
+  const deadline = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  const signed = cookie;
+  const as = who;
+  const own = registers.checked;
+  const name = agent.value.trim();
+  let res;
+  let answer;
+  try {
+    // Relative to this page, /oauth/authorize under the public URL, so it stays under the public URL's path. Signed in,
+    // it sends no token, and the server reads the sign-in cookie; otherwise only the typed token, and no cookie.
+    res = await fetch("approve", {
+      method: "POST",
+      headers: signed ? { "Content-Type": "application/json" } : { Authorization: "Bearer " + token.value.trim(), "Content-Type": "application/json" },
+      body: JSON.stringify({
+        request: form.dataset.request,
+        state: form.dataset.state === undefined ? null : form.dataset.state,
+        ...(own ? { registers: true } : { agent: name, fresh: suggested !== undefined && name === suggested }),
+        ...(signed && { as }),
+      }),
+      cache: "no-store",
+      credentials: signed ? "same-origin" : "omit",
+      referrerPolicy: "no-referrer",
+      signal: ac.signal,
+    });
+    answer = await res.json().catch(() => undefined);
+  } catch {
+    res = undefined;
+  } finally {
+    clearTimeout(deadline);
+  }
+  busy = false;
+  yes.disabled = false;
+  if (res && res.ok && answer && typeof answer.location === "string") {
+    token.value = "";
+    say("Approved. Returning to the client…", false);
+    return location.assign(answer.location);
+  }
+  if (!res) return say("The server did not answer. Try again.", true);
+  if (signed && (res.status === 401 || res.status === 403)) {
+    show(undefined);
+    return say("This browser is no longer signed in. Sign in on the dashboard and check again, or enter a full or person token of the account.", true);
+  }
+  // The browser's sign-in changed since the page showed it: show who it is now before anyone approves.
+  if (signed && res.status === 409) {
+    say(answer && typeof answer.message === "string" ? answer.message : "This browser is now signed in as someone else.", true);
+    return check();
+  }
+  if (res.status === 401) return say("The server refused that token. Enter a full or person token of the account.", true);
+  if (res.status === 403) return say("Only a full or person token can approve a client; agent and read-only tokens cannot.", true);
+  say(answer && typeof answer.message === "string" ? answer.message : "The server could not approve this (" + res.status + "). Try again.", true);
+});
+no.addEventListener("click", () => location.assign(no.dataset.location));
+agent.addEventListener("input", () => {
+  suggested = undefined;
+});
+// Ticked, the client names its own agents, so the agent name is hidden, not required and not sent.
+registers.addEventListener("change", () => {
+  agentField.hidden = registers.checked;
+  agent.required = !registers.checked;
+});
+// Without the sign-in (no https public URL) the page only takes a typed token.
+if (form.dataset.signin !== undefined) {
+  again.addEventListener("click", () => check());
+  // Coming back from signing in on the dashboard in another tab checks again.
+  addEventListener("focus", () => check());
+  check();
+}
+`;
+const hash = (text) => `'sha256-${createHash("sha256").update(text, "utf8").digest("base64")}'`;
+/** Headers for the approval and error pages: the inline style and script run by hash, and nothing frames them. */
+export const APPROVE_HEADERS = {
+    "Content-Type": "text/html; charset=utf-8",
+    "Content-Security-Policy": [
+        "default-src 'none'",
+        `script-src ${hash(SCRIPT)}`,
+        `style-src ${hash(PAGE_STYLE)}`,
+        "connect-src 'self'",
+        "font-src 'self'",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "frame-ancestors 'none'",
+    ].join("; "),
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+    "Cache-Control": "no-store",
+};
+const escape = (text) => text.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const MARK = '<svg class="mark" viewBox="0 0 32 32" aria-hidden="true" focusable="false"><path class="bubble" d="M8 4h16a6 6 0 0 1 6 6v8a6 6 0 0 1-6 6H14l-7 5v-5.2A6 6 0 0 1 2 18v-8a6 6 0 0 1 6-6z"/><path class="lines" d="M9 12.5h14v2.5H9zm0 5h9v2.5H9z"/></svg>';
+const page = (body) => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Connect a client · message-cp</title>
+<style>${PAGE_STYLE}</style>
+</head>
+<body>
+<main>
+<h1>${MARK}message-cp</h1>
+${body}
+</main>
+</body>
+</html>
+`;
+/** The page shown instead of the approval page for a request that cannot be sent back to its client. */
+export const errorPage = (message) => page(`<p role="alert">${escape(message)}</p>`);
+/**
+ * The approval page for `a`. `deny` is where refusing goes: the redirect URI with error=access_denied and the state.
+ * It shows the client's name as it registered it, or as its metadata document gives it with the host of that document's
+ * URL, and the redirect URI's host, and warns when that host is this machine.
+ */
+export function approvePage(a, deny, signin) {
+    const host = new URL(a.redirectUri).host;
+    const loopback = isLoopback(new URL(a.redirectUri));
+    const name = a.client.clientName ? escape(a.client.clientName) : "An unnamed client";
+    // A client known by its metadata document's URL is named with that URL's host, which this server fetched it from.
+    const from = isMetadataUrl(a.client.clientId) ? new URL(a.client.clientId).host : undefined;
+    const who = `<span class="client">${name}</span>${from === undefined ? "" : `, from <span class="client">${escape(from)}</span>,`}`;
+    const state = a.state === null ? "" : ` data-state="${escape(a.state)}"`;
+    return page(`<h2>Connect a client</h2>
+<p>${who} asks to act as an agent of your account. Once you approve, it is sent to <span class="client">${escape(host)}</span> with a code it exchanges for an agent token.</p>
+${loopback
+        ? `<p class="warn">That address is on the machine the client runs on. Approve only if you just started connecting from a client on this machine: any program running there could have asked.</p>`
+        : ""}
+<p class="dim">${from === undefined ? "The name is the client's own; this server has not checked it." : `The name is the client's own; this server has checked only that its description is at ${escape(from)}.`}</p>
+<form id="approve" data-request="${escape(a.request)}"${state} data-base="${escape(agentNameBase(a.client.clientName))}"${signin ? " data-signin" : ""}>
+<p id="signed-in" role="status" hidden></p>
+<div id="signed-out"${signin ? "" : " hidden"}>
+<p>This browser is not signed in to message-cp. <a href="../" target="_blank" rel="noopener">Sign in on the dashboard</a> in a new tab, which leaves this page open, then come back here or <button id="signin-again" type="button">Check again</button>. Or enter a token below.</p>
+</div>
+<div id="token-field">
+<label for="approve-token">Full or person token of the account</label>
+<input id="approve-token" type="password" autocomplete="off" required>
+</div>
+<div id="agent-field">
+<label for="approve-agent">Agent name</label>
+<input id="approve-agent" type="text" autocomplete="off" required maxlength="32" pattern="[A-Za-z0-9_\\-]{1,32}" placeholder="for example claude-desktop">
+<p class="dim">A new name makes that agent; an existing agent's name, typed in, connects the client as it, leaving its key and sessions alone. A suggested name is never an existing agent's.</p>
+</div>
+<label class="choice"><input id="approve-registers" type="checkbox"> This client registers its own agents</label>
+<p class="dim">Ticked, each session of the client registers its own new name, and acts again only as the agents it registered, never as another agent or a person.</p>
+<div class="actions">
+<button id="approve-yes" type="submit">Approve</button>
+<button id="approve-no" type="button" data-location="${escape(deny)}">Refuse</button>
+</div>
+<p id="approve-note" class="note" role="status"></p>
+</form>
+<script>${SCRIPT}</script>`);
+}

package/dist/channels.js

@@ -0,0 +1,262 @@
+import { NAME_PATTERN, NOT_REGISTERED, ToolError, actingPerson, nameOfIdentity } from "./agents.js";
+import { DEFAULT_INBOX_LIMIT, MAX_INBOX_LIMIT, validateBody } from "./messages.js";
+export const DEFAULT_CHANNEL_LIMIT = DEFAULT_INBOX_LIMIT;
+export const MAX_CHANNEL_LIMIT = MAX_INBOX_LIMIT;
+const toPost = (r) => ({
+    id: r.id,
+    from: r.sender,
+    sentAt: new Date(r.created_at).toISOString(),
+    body: r.body,
+});
+// The agent-name pattern; unlike agent names, `all` is an ordinary channel name.
+function validateChannelName(name) {
+    if (!NAME_PATTERN.test(name)) {
+        throw new ToolError("Invalid channel name: use 1-32 characters from letters, digits, '-' and '_'.");
+    }
+}
+function findChannel(db, account, name) {
+    validateChannelName(name);
+    const row = db.prepare("SELECT id, name FROM channels WHERE account_id = ? AND name = ?").get(account, name);
+    if (!row)
+        throw new ToolError(`No channel named '${name}'.`);
+    return row;
+}
+/**
+ * Throws unless `member`'s registration is still live. Called inside each tool's transaction, so an agent removed by
+ * another process after the session last checked can neither post nor read.
+ */
+function checkLive(db, account, member) {
+    if (nameOfIdentity(db, account, member) === undefined)
+        throw new ToolError(NOT_REGISTERED);
+}
+/** Moves `agent`'s read position in `channel` forward to `postId`; never back. */
+function advance(db, agent, channel, postId) {
+    db.prepare(`INSERT INTO channel_reads (agent_id, channel_id, last_read_id) VALUES (?, ?, ?)
+     ON CONFLICT(agent_id, channel_id) DO UPDATE SET last_read_id = MAX(last_read_id, excluded.last_read_id)`).run(agent, channel, postId);
+}
+/** Creates the account's channel `channel` if it does not exist yet, and returns it. */
+function ensureChannel(db, account, channel, now) {
+    db.prepare("INSERT INTO channels (account_id, name, created_at) VALUES (?, ?, ?) ON CONFLICT(account_id, name) DO NOTHING")
+        .run(account, channel, now);
+    return findChannel(db, account, channel);
+}
+// `@` and a name, not inside a longer word (`a@bob`) and not cut from a longer name.
+const MENTION = /(?<![A-Za-z0-9_-])@([A-Za-z0-9_-]{1,32})(?![A-Za-z0-9_-])/g;
+/** The distinct names `body` mentions as `@<name>`, lower-cased since names compare without case, `all` left out. */
+export function mentionedNames(body) {
+    const names = new Set();
+    for (const [, name] of body.matchAll(MENTION))
+        names.add(name.toLowerCase());
+    names.delete("all");
+    return [...names];
+}
+/**
+ * Appends a post to the account's channel `channel`, creating the channel if this is its first post. If the member had
+ * read everything before it, its read position moves past its own post, so the channel stays read for it. Each live
+ * agent of the account the post names as `@<name>`, but the member, gets a mention, whether or not it has joined.
+ */
+export function post(db, account, member, channel, body) {
+    validateChannelName(channel);
+    validateBody(body, "Post");
+    return db
+        .transaction(() => {
+        checkLive(db, account, member);
+        // Posting clears the poster's status line; checkLive has just found its row live.
+        db.prepare("UPDATE agents SET status = NULL, status_at = NULL WHERE id = ? AND status IS NOT NULL").run(member.id);
+        return append(db, account, member, channel, body);
+    })
+        .immediate();
+}
+/**
+ * `post` 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 postAsPerson(db, account, as, channel, body, only) {
+    validateChannelName(channel);
+    validateBody(body, "Post");
+    return db
+        .transaction(() => {
+        const person = actingPerson(db, account, as, only);
+        return person && append(db, account, person, channel, body);
+    })
+        .immediate();
+}
+/** The body of `post` once the sender is known to be live: `member` is its row in `agents` and its stored name. */
+function append(db, account, member, channel, body) {
+    const now = Date.now();
+    const found = ensureChannel(db, account, channel, now);
+    const last = db.prepare("SELECT MAX(id) AS id FROM channel_posts WHERE channel_id = ?").get(found.id);
+    const read = db
+        .prepare("SELECT last_read_id FROM channel_reads WHERE agent_id = ? AND channel_id = ?")
+        .get(member.id, found.id);
+    const id = Number(db
+        .prepare("INSERT INTO channel_posts (channel_id, sender_id, sender, body, created_at) VALUES (?, ?, ?, ?, ?)")
+        .run(found.id, member.id, member.name, body, now).lastInsertRowid);
+    if (last.id === null || (read !== undefined && read.last_read_id >= last.id))
+        advance(db, member.id, found.id, id);
+    const names = body.includes("@") ? mentionedNames(body) : [];
+    if (names.length > 0) {
+        const mention = db.prepare(`INSERT INTO mentions (agent_id, post_id)
+       SELECT id, ? FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL AND id <> ?`);
+        for (const name of names)
+            mention.run(id, account, name, member.id);
+    }
+    // Owed to every `#<channel>` webhook of the account, and to every `mention:<agent>` webhook of an agent it mentioned,
+    // held for that agent while it is waiting for mail (`markWaiting`), as a direct message is.
+    // Mention rows only ever name agents of this account; the account check on `webhooks` says so where it matters.
+    db.prepare(`INSERT INTO webhook_deliveries (webhook_id, post_id, created_at)
+     SELECT id, ?, ? FROM webhooks WHERE account_id = ? AND event = 'channel' AND name = ? COLLATE NOCASE ORDER BY id`).run(id, now, account, found.name);
+    if (names.length > 0) {
+        db.prepare(`INSERT INTO webhook_deliveries (webhook_id, post_id, created_at, held_for)
+       SELECT webhooks.id, ?, ?, CASE WHEN agents.waiting_until > ? THEN agents.id END FROM mentions
+       JOIN agents ON agents.id = mentions.agent_id
+       JOIN webhooks ON webhooks.account_id = agents.account_id AND webhooks.event = 'mention' AND webhooks.name = agents.name COLLATE NOCASE
+       WHERE mentions.post_id = ? AND webhooks.account_id = ? ORDER BY webhooks.id`).run(id, now, now, id, account);
+    }
+    return { channel: found.name, id, sentAt: new Date(now).toISOString() };
+}
+/**
+ * Joins `member` to the account's channel `channel`, creating the channel if nobody has posted to it yet, so that its
+ * unread posts wake the member. A channel the member has never read is joined at its latest post, so its history
+ * does not wake it; one it has read before keeps its read position.
+ */
+export function joinChannel(db, account, member, channel) {
+    validateChannelName(channel);
+    return db
+        .transaction(() => {
+        checkLive(db, account, member);
+        const found = ensureChannel(db, account, channel, Date.now());
+        db.prepare(`INSERT INTO channel_reads (agent_id, channel_id, last_read_id, joined)
+         SELECT ?, ?, COALESCE(MAX(id), 0), 1 FROM channel_posts WHERE channel_id = ?
+         ON CONFLICT(agent_id, channel_id) DO UPDATE SET joined = 1`).run(member.id, found.id, found.id);
+        return { channel: found.name, joined: true };
+    })
+        .immediate();
+}
+/** Leaves the account's channel `channel`, so its posts no longer wake `member`. The read position stays where it was. */
+export function leaveChannel(db, account, member, channel) {
+    return db
+        .transaction(() => {
+        checkLive(db, account, member);
+        const found = findChannel(db, account, channel);
+        db.prepare("UPDATE channel_reads SET joined = 0 WHERE agent_id = ? AND channel_id = ?").run(member.id, found.id);
+        return { channel: found.name, joined: false };
+    })
+        .immediate();
+}
+/**
+ * One page of `channel`, oldest first. By default the posts after the reader's read position, which then moves past
+ * the last one returned; an agent that has never read the channel starts at its first post. The reader's own posts are
+ * included, so a page reads in order, though they never count as unread. With `unreadOnly` false,
+ * the whole history paged by `offset`, leaving the read position where it was.
+ */
+export function readChannel(db, account, reader, channel, unreadOnly = true, limit = DEFAULT_CHANNEL_LIMIT, offset) {
+    if (unreadOnly && offset !== undefined)
+        throw new ToolError("offset pages through history: pass unread_only false with it.");
+    const read = db.transaction(() => {
+        checkLive(db, account, reader);
+        const found = findChannel(db, account, channel);
+        const pageSize = Math.min(limit, MAX_CHANNEL_LIMIT);
+        let rows;
+        if (unreadOnly) {
+            rows = db
+                .prepare(`SELECT p.id, p.sender, p.body, p.created_at FROM channel_posts p
+           LEFT JOIN channel_reads r ON r.channel_id = p.channel_id AND r.agent_id = ?
+           WHERE p.channel_id = ? AND p.id > COALESCE(r.last_read_id, 0) ORDER BY p.id LIMIT ?`)
+                .all(reader.id, found.id, pageSize);
+            if (rows.length > 0)
+                advance(db, reader.id, found.id, rows[rows.length - 1].id);
+        }
+        else {
+            rows = db
+                .prepare("SELECT id, sender, body, created_at FROM channel_posts WHERE channel_id = ? ORDER BY id LIMIT ? OFFSET ?")
+                .all(found.id, pageSize, offset ?? 0);
+        }
+        return { channel: found.name, posts: rows.map(toPost) };
+    });
+    // Only reading unread posts writes, by moving the read position; history needs no write lock.
+    return unreadOnly ? read.immediate() : read();
+}
+/**
+ * One page of the account's channels by name, each with its post count, last post time, how many posts `reader`
+ * has not read and whether `reader` has joined it. The reader's own posts never count as unread.
+ */
+export function listChannels(db, account, reader, limit = DEFAULT_CHANNEL_LIMIT, offset = 0) {
+    // The page of channels is chosen first, so only its channels' posts are counted.
+    const rows = db.transaction(() => {
+        checkLive(db, account, reader);
+        return db
+            .prepare(`SELECT c.name, COUNT(p.id) AS posts, MAX(p.created_at) AS last_post_at,
+                COALESCE(SUM(p.id > COALESCE(r.last_read_id, 0) AND p.sender_id <> ?), 0) AS unread,
+                COALESCE(r.joined, 0) AS joined
+         FROM (SELECT id, name FROM channels WHERE account_id = ? ORDER BY name LIMIT ? OFFSET ?) c
+         LEFT JOIN channel_posts p ON p.channel_id = c.id
+         LEFT JOIN channel_reads r ON r.channel_id = c.id AND r.agent_id = ?
+         GROUP BY c.id ORDER BY c.name`)
+            .all(reader.id, account, Math.min(limit, MAX_CHANNEL_LIMIT), offset, reader.id);
+    })();
+    return rows.map((r) => ({
+        name: r.name,
+        posts: r.posts,
+        lastPostAt: r.last_post_at === null ? null : new Date(r.last_post_at).toISOString(),
+        unread: r.unread,
+        joined: r.joined === 1,
+    }));
+}
+/**
+ * One page of the account's channels by name, each with its post count, last post time and joined live agents, for
+ * the account rather than for one agent. Reads only, so nothing is marked read.
+ */
+export function listAccountChannels(db, account, limit = DEFAULT_CHANNEL_LIMIT, offset = 0) {
+    // One read transaction, so the page and its members describe the same moment.
+    return db.transaction(() => {
+        const rows = db
+            .prepare(`SELECT c.id, c.name, COUNT(p.id) AS posts, MAX(p.created_at) AS last_post_at
+         FROM (SELECT id, name FROM channels WHERE account_id = ? ORDER BY name LIMIT ? OFFSET ?) c
+         LEFT JOIN channel_posts p ON p.channel_id = c.id
+         GROUP BY c.id ORDER BY c.name`)
+            .all(account, Math.min(limit, MAX_CHANNEL_LIMIT), offset);
+        const members = db.prepare(`SELECT a.name FROM channel_reads r JOIN agents a ON a.id = r.agent_id
+       WHERE r.channel_id = ? AND r.joined = 1 AND a.account_id = ? AND a.removed_at IS NULL ORDER BY a.name`);
+        return rows.map((r) => ({
+            name: r.name,
+            posts: r.posts,
+            lastPostAt: r.last_post_at === null ? null : new Date(r.last_post_at).toISOString(),
+            members: members.pluck().all(r.id, account),
+        }));
+    })();
+}
+/**
+ * One page of the account's channel `channel`, oldest first, paged by `limit` and `offset`, for the account rather than for one
+ * agent, each post with whether each agent of the account it mentions has read the mention with `read_inbox`. With
+ * `unreadOnly`, only the posts with at least one unread mention of an agent. Reads only, so no read position moves and
+ * nothing is marked read.
+ */
+export function readAccountChannel(db, account, channel, limit = DEFAULT_CHANNEL_LIMIT, offset = 0, unreadOnly = false) {
+    // With unreadOnly, the posts are found from the account's agents and their unread mentions (mentions_unread), so only
+    // unread rows are read, never the channel's whole history; a post with several unread mentions is listed once.
+    const page = unreadOnly
+        ? `SELECT DISTINCT p.id, p.sender, p.body, p.created_at
+       FROM agents a CROSS JOIN mentions x ON x.agent_id = a.id AND x.read_at IS NULL CROSS JOIN channel_posts p ON p.id = x.post_id
+       WHERE p.channel_id = ? AND a.account_id = ? AND a.person = 0 ORDER BY p.id LIMIT ? OFFSET ?`
+        : "SELECT id, sender, body, created_at FROM channel_posts WHERE channel_id = ? ORDER BY id LIMIT ? OFFSET ?";
+    return db.transaction(() => {
+        const found = findChannel(db, account, channel);
+        const params = [found.id, ...(unreadOnly ? [account] : []), Math.min(limit, MAX_CHANNEL_LIMIT), offset];
+        const rows = db.prepare(page).all(...params);
+        // The page's mentions in one statement, with the page as a subquery rather than a list of ids.
+        const mentions = db
+            .prepare(`SELECT x.post_id, CASE WHEN a.removed_at IS NULL THEN a.name ELSE a.removed_name END AS name, x.read_at
+         FROM (${page}) pg JOIN mentions x ON x.post_id = pg.id JOIN agents a ON a.id = x.agent_id
+         WHERE a.account_id = ? AND a.person = 0 ORDER BY x.post_id, name COLLATE NOCASE, a.id`)
+            .all(...params, account);
+        const byPost = new Map();
+        for (const m of mentions) {
+            const list = byPost.get(m.post_id) ?? [];
+            list.push({ name: m.name, read: m.read_at !== null });
+            byPost.set(m.post_id, list);
+        }
+        return { channel: found.name, posts: rows.map((r) => ({ ...toPost(r), mentions: byPost.get(r.id) ?? [] })) };
+    })();
+}