pi-roundtable 0.17.3 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-10-17
+
+### Added
+
+- `OpsAlerts`, `OpsAlertsOptions`, `OpsRaiseOptions` and `OpsAlertKind` (`pi-roundtable/kit`): short alerts for the people who run a host, for a plugin's own faults. `new OpsAlerts({ sink?, logger, kinds?, windowMs?, kindCap?, now? })` posts through `sink(text)`, a function that resolves `true` when it posted and `false` when it chose not to, so the kit names no discord.js type. `raise(key, text, { code?, info? })` posts at once, never queued, a key at most once per window (one hour) and a kind (the key's word before the first colon) at most `kindCap` times per window (8), whatever the keys; what is held back is only counted. A sink that throws or answers `false` gives the key and the slot back, so the next raise tries again; a throw is logged by the error's name and `raise` never throws. `info: true` is news, posted once per key, outside the cap and outside `faults()`. `faults()` lists the last fault of each kind, newest first, with `name` (from `kinds`), `code`, `raised` and `suppressed`, in memory. With no `sink` the alerts are recorded, the key stays held, and the log has one line per window (`an ops alert was raised and there is no sink to post it to`). No summary of the held-back alerts is posted, so there is no new text to translate.
+- `DISCORD.poster` (`pi-roundtable/discord`): Discord's REST API for a plugin's own posts, as one new required member of `DiscordServices`, over the Discord plugin's own gateway client, so a host has one REST queue and one set of rate limits. It posts, edits and deletes through webhooks under names the plugin chooses, posts the bot's own messages and Components V2 cards, pins, sends direct messages, starts and archives threads, reads who closed one from the audit log, and makes, lists, renames and deletes text channels. A call never pings anyone it does not name, and a failure is a `DiscordPosterError` whose message holds no URL, webhook token or bot token. Making it sends nothing, so `Roundtable.check()` still never reaches Discord. The interface is `DiscordPoster`; its types are `WebhookPost`, `PosterFile`, `PostedMessage`, `DiscordMessage`, `RecentMessage`, `DiscordCard`, `CardButton`, `CardLink`, `CardSelect`, `ThreadState`, `ThreadCloser` and `CategoryChannel`; its failures are `DiscordPosterError` with `DiscordFailure` and `DiscordReason`; and `DISCORD_LIMITS` is the frozen table of the limits it checks. The guide has a new section, "Posting through `DISCORD.poster`".
+- `fakeDiscordPoster`, `FakeDiscordPoster`, `FakePosterChannel` and `FakePosterMessage` (`pi-roundtable/testing`): `fakeDiscordPoster({ idOffset?, now? })` is a `DiscordPoster` in memory with its state open to the test. It and the real poster run the same 14 scenarios (the fake, and the real poster over a local emulation of Discord's HTTP API, which is not published), so they answer alike: webhook names, `allowed_mentions`, edits through the named webhooks, pins across pages, Components V2 cards, threads and their audit-log closers, channels and their limits, the rename limit, `canView` and `memberName`.
+- `fakeDiscord({ poster })` and `testHost({ discord: { poster, channelInfo } })` (`pi-roundtable/testing`) take the poster and the channel lookup the test wants; by default `DISCORD.poster` is a new `fakeDiscordPoster()`, and `fakeDiscord()` exposes it as `poster`.
+- Where `fakeDiscordPoster` differs from a bare in-memory list, as the real poster does: `failNext` fails the next call of an operation after its arguments pass the checks (a `channelGuild` read the fake has already kept does not consume it); `edit` succeeds only for a message that one of the listed webhooks posted; `setAvatar` makes the webhook (and announces it) when it does not exist; `textChannels` lists a category's text channels, not threads.
+
+### Changed
+
+- `ErrorReporter` takes its once-an-hour and five-reports-an-hour limits from internal throttle code that `OpsAlerts` also uses, each with its own limits and state. What it reports, when, and the summary of the suppressed errors are unchanged.
+- The `pi-web-access` peer dependency range is `>=0.35.0 <0.41.0` (was `>=0.35.0 <0.36.0`), the range the package is tested against: 0.35.0 and the 0.40.0 its checks now run on both keep `"pi": { "extensions": ["./dist"] }`, which is how the delegation worker loads it, and nothing in 0.36 to 0.40 changes that. The error a project without it gets now says `bun add pi-web-access@0.40.0` (was 0.35.0).
+- **Breaking for hand-made stand-ins of `DISCORD`:** `DiscordServices` has a new required member, `poster`. A test double written as `as unknown as DiscordServices` compiles unchanged, and fails at run time with `poster` undefined only when the code under test posts through it. Give it `fakeDiscordPoster()`, or use `fakeDiscord()` or `testHost`, which do. The host's own Discord plugin and `testHost` provide it.
+- The Discord plugin sets its bot token on its client's REST queue when it sets up, not at login, so the poster works before the gateway is up. Nothing else about the connection changes.
+- The packages depend on `typebox` 1.3.37 (was 1.3.34), and a project made by `roundtable init` pins `typebox` 1.3.37 and `@types/bun` 1.4.3 (were 1.3.34 and 1.4.2), so a new project matches the package's own tools. The packages depend on `pi-mcp-adapter` 5.3.0 (was 5.2.0), and the `pi-web-access` used for the package's own checks is 0.40.0. The pi range the package accepts is unchanged; it is built and tested against pi 1.3.0.
+
 ## [0.17.3] - 2026-10-16
 
 ### Fixed

package/docs/plugins.md

@@ -164,6 +164,12 @@ It then calls `DefineOverrides.errorSink(entry)` if you supply one; this functio
 A logger you supply reaches the ops agent and `errorSink` only if it forwards its error lines there.
 The report names the plugin next to `app` and `module`; the same error is reported at most once an hour, regardless of which plugin wrote it.
 
+`OpsAlerts` in `pi-roundtable/kit` is for a plugin's own alerts, such as a failed push, that the people who run the host should read; it is not the error report above, and a host that wants both uses both.
+`new OpsAlerts({ sink?, logger, kinds?, windowMs?, kindCap?, now? })` takes `sink(text) => Promise<boolean>`, which posts the text where those people read it: resolve `true` when it was posted, `false` when you chose not to (log why yourself, for example a channel outside the one guild alerts may go to), or throw. The kit names no discord.js type, so the sink is the only place a transport appears.
+`raise(key, text, { code?, info? })` resolves whether the alert was posted. The kind is the key's word before the first colon (`push:group-7` is `push`).
+A key is posted at most once per window (one hour by default) and a kind at most `kindCap` times per window (8 by default), whatever the keys, so a fault that touches everything cannot flood the sink. An alert is posted when it is raised, not queued, and what is held back is only counted: `faults()` lists the last fault of each kind, newest first, with its `name` (from `kinds`, else the kind itself), `code`, `raised` and `suppressed`, in memory only, for a status command. `info: true` marks news, not a fault: it posts at most once per key, does not count against the kind's cap and is not listed in `faults()`.
+A sink that throws or answers `false` gives the key and the kind's slot back, so the next raise tries again, and a throw is logged by the error's name only. `raise` never throws. With no `sink`, alerts are only recorded, the key stays held and the log has one line per window (`an ops alert was raised and there is no sink to post it to`); `posts` tells which. `ErrorReporter` and `OpsAlerts` each keep their own limits, so alerts never count against the error reports' five an hour.
+
 ### Services: what plugins provide to each other
 
 A service is something one plugin builds and others read, such as the schedule store or the agent team.
@@ -206,7 +212,7 @@ The built-in plugins provide these, from the main entry:
 
 The data types the ports use (`Schedule`, `NewSchedule`, `Agent`, `AgentGroup`, `TeamStatus`, `Memory`, `SkillSet`, `DelegationJob`, and so on) are in the main entry too.
 Your plugins run after the built-ins, so they can read every key above.
-The Discord connection's key, `DISCORD`, is in the Discord entry, because its port names discord.js types: `DiscordServices` has `connection`, `commands`, `guard`, and `threads` (see [`commands.add`](#slash-commands-commandsadd)).
+The Discord connection's key, `DISCORD`, is in the Discord entry, because its port names discord.js types: `DiscordServices` has `connection`, `commands`, `guard`, `threads`, `poster` (see [Posting through `DISCORD.poster`](#posting-through-discordposter)) and `channelContext`; commands are in [`commands.add`](#slash-commands-commandsadd). A plugin's own stand-in for `DISCORD` (such as one written with `as unknown as DiscordServices`) needs a `poster` too before code that posts runs under it; `fakeDiscord()` and `testHost` give one.
 
 To share your own service, export its key as a constant and its port as an interface.
 Plugins registered after yours can read it during setup.
@@ -2429,6 +2435,38 @@ export function tavern(channelIds: readonly string[]) {
 ```
 <!-- /example -->
 
+### Posting through `DISCORD.poster`
+
+`DISCORD.poster` (`DiscordPoster`, from `pi-roundtable/discord`) is Discord's REST API for a plugin's own posts, over the Discord plugin's own client.
+A host has one REST queue for the whole process, so the poster and the gateway client share Discord's rate-limit state, which Discord keeps per bot token.
+It is usable from a service's `start` on; do not call it from `setup`, which `Roundtable.check()` also runs. Making it sends nothing, so the check never reaches Discord.
+There is no factory: a host that has no Discord has no poster.
+
+```ts
+import { DISCORD } from "pi-roundtable/discord";
+
+const { poster } = services.get(DISCORD);
+const posted = await poster.post(channelId, { webhook: "relay", username: "Ann", content: "Hello" });
+await poster.edit(channelId, posted.messageId, { content: "Hello again" }, ["relay"]);
+await poster.remove(channelId, posted.messageId, ["relay"]);
+```
+
+What it covers: webhook posts under names you choose (`post`, `edit`, `remove`, `webhookIds`, `setAvatar`, `onWebhookMade`), the bot's own messages and cards (`say`, `sayCard`, `editCard`, `deleteAsBot`), direct messages (`sendDirect`), pins, reading (`message`, `recentMessages`, `botUserId`, `channelGuild`, `canView`, `memberName`), text channels (`createTextChannel`, `textChannels`, `deleteChannel`, `renameChannel`) and threads (`startThread`, `setThreadArchived`, `threadState`, `threadCloser`).
+Use `DISCORD.connection.channelInfo(channelId)` to read what a channel is called now: it comes from the gateway's cache.
+
+The rules the poster keeps, so a plugin does not rediscover them:
+
+- **Webhooks are named by the plugin.** `post` finds the bot's webhook of that name in the channel, or makes it on first use; a same-named webhook someone else made is never used. A plugin that needs several voices keeps one name per voice, so the `webhookId` on a message tells them apart. A webhook name, and a post's `username`, are 1 to 80 characters without "discord" or "clyde" in any case (full-width letters too); a username is not "everyone" or "here" either. Anything else is refused as `invalid` before a request is sent. `edit` and `remove` take the names to ask, in order, since a webhook changes only its own messages; they make no webhook. `remove` falls back to deleting as the bot (Manage Messages) for a message an earlier webhook of the same name posted.
+- **Nothing pings by accident.** Every post, edit, card and direct message sends `allowed_mentions` with `parse: []` and, for a post, the `mentions` users you list (at most 20). `@everyone`, roles and users merely named in the text never ping.
+- **Cards are Components V2 messages.** A card carries no `content`. Three lessons: every `editCard` re-sends the Components V2 flag (without it Discord answers a 400); a message posted by `say` cannot be edited into a card (`rejected`: delete it and post a card, which changes the message id); and a pin makes Discord post a system notice (type 6) as the bot, which `recentMessages` lists, `deleteAsBot` deletes, and nothing can edit (`rejected`, Discord's 50021), so skip it when looking for your own message.
+- **A channel is renamed twice in ten minutes.** Discord answers a third with a wait of minutes. `renameChannel` does not queue it: after ten seconds it fails as `unavailable`, and the held request is aborted, never sent later.
+- **Threads.** `startThread` makes a public thread on a message that archives itself after a week and wakes on the next post. The bot needs no Manage Threads to archive or open a thread it started; a locked thread needs it to open again (`forbidden`). `threadCloser` reads the guild's audit log (View Audit Log, else `forbidden`): a person's id, the bot, or `unknown` for Discord's own auto-archive. An archive counts only if its entry is within two minutes of the thread's `archive_timestamp`. It reads the newest 50 `THREAD_UPDATE` entries, so on a busy guild an old close may have left the log and read as `unknown`.
+- **Errors.** Every failure is a `DiscordPosterError` with a `kind`: `invalid` (refused before sending), `channel_gone`, `message_gone`, `forbidden` (a missing permission), `rejected` (Discord refused; asking again fails again) and `unavailable` (Discord or the network failed, or a rate limit held the call; `retryable`). `reason` says more for a full category (`category_full`), a channel that is no category (`not_category`) and one in no guild (`wrong_guild`). A webhook deleted by hand is found or made again once. A person who takes no direct messages is the answer `"closed"`, and a user who is not a member is `false` from `canView` and `undefined` from `memberName`, not failures. A message never holds a URL, a webhook token or the bot token.
+
+`DISCORD_LIMITS` (frozen) holds the limits the poster checks: 2,000 characters a post, 80 for a username, 10 files and 10 MiB a post, 1 MiB for an avatar, 20 mentions, 250 pins, 100 characters for a channel name, 3,800 characters of card text, 5 card buttons and 25 menu choices.
+
+In a test, `fakeDiscordPoster()` is a `DiscordPoster` in memory and `fakeDiscord({ poster })` or `testHost({ discord: { poster } })` gives it to the plugin; see [Testing a plugin](#testing-a-plugin). The real poster and the fake run the same scenarios, the real one over a local emulation of Discord's HTTP API.
+
 ### `backgroundTargets`: whose turn a schedule or delegated task is
 
 Schedules and delegated tasks return later as turns without a new message in the channel.
@@ -3272,8 +3310,9 @@ Use `partial<Port>({ ... })` to stand in for a port your code takes as an argume
 It provides the members you give it and throws an error naming any missing member you read, so the test needs no `as unknown as Port` cast.
 `fakePrecheck(name, answer, { description?, timeoutMs? })` is a precheck that answers `answer` (a `PrecheckResult`, an `Error` it throws, or a function of its context) and records each context in `calls`; `fakePrechecks(...prechecks)` is a real in-memory `PrecheckRegistry` with them registered, which a test gives a plugin as `servicePair(PRECHECKS, registry)` and reads back with `registry.get(name)`.
 `fakeScriptRunner(answer, { describe?, timeoutMs? })` is a `PrecheckScriptRunner` that runs nothing and answers `answer` (a result, an `Error` it throws, or a function of the script and its context), recording each call in `calls`; give it to `registry.useScriptRunner`.
-`fakeDiscord({ ownerId?, rootCommand?, channelContext? })` is the `DISCORD` service for a plugin that adds slash commands or reads channel context: give it as `services: [discord.service]`, read what the plugin added with `discord.added()`, and compose the tree Discord would get with `discord.compose()`; `channelContext` answers `DISCORD.channelContext`, by default with no context.
-Only `commands` and `guard` are given; a plugin that reads another member of `DISCORD` in a test gives its own with `servicePair(DISCORD, { ... })`.
+`fakeDiscord({ ownerId?, rootCommand?, channelContext?, poster? })` is the `DISCORD` service for a plugin that adds slash commands, reads channel context or posts through `DISCORD.poster`: give it as `services: [discord.service]`, read what the plugin added with `discord.added()`, and compose the tree Discord would get with `discord.compose()`; `channelContext` answers `DISCORD.channelContext`, by default with no context.
+Only `commands`, `guard`, `poster` and `channelContext` are given; `discord.poster` is the poster the test passed, else a new `fakeDiscordPoster()`. A plugin that reads another member of `DISCORD` in a test gives its own with `servicePair(DISCORD, { ... })`.
+`fakeDiscordPoster({ idOffset?, now? })` is a `DiscordPoster` in memory: `channels` with their messages, pins and webhook pictures, `directs`, and the knobs a test turns (`closedDirects`, `goneChannels`, `categories`, `memberNames`, `hiddenFrom`, `nonMembers`, `pinNotices`, `canReadAuditLog`, `failNext(operation, error)`, `speak`, `personCloses`, `autoArchives`, `personOpens`, `deleteWebhook`, `recreateWebhook`). `messagesIn(channelId)` lists what a channel holds. It keeps the real poster's argument checks and error kinds, a channel's two renames in ten minutes (by `now`) and the 250 pins. `idOffset` moves every id it makes, so test files that share a database never meet the same id.
 
 ### `testHost`: the built-in plugins and yours, over PostgreSQL
 
@@ -3287,7 +3326,7 @@ It boots `defineRoundtable` over `ROUNDTABLE_TEST_DATABASE_URL`, with stand-ins
 | `plugins` | Your plugins, placed after the built-in ones as `defineRoundtable` places them |
 | `runtime` | The runtime every turn runs on; by default one that answers `""` and builds no Pi session |
 | `apiKeys` | The credentials `context.apiKey(provider)` returns, by provider name; a provider not listed reads as having none, whatever login the machine holds |
-| `discord` | What the stand-in Discord hands out: `agentChannels(guildId)` and `ownerChannel()`; `false` boots a [host without Discord](#a-host-without-discord), with no `discord`, `http`, or `agents` in the test configuration |
+| `discord` | What the stand-in Discord hands out: `agentChannels(guildId)`, `ownerChannel()`, `channelInfo(channelId)` and `poster` (what `DISCORD.poster` is; by default a `fakeDiscordPoster()`); `false` boots a [host without Discord](#a-host-without-discord), with no `discord`, `http`, or `agents` in the test configuration |
 
 It returns:
 
@@ -3871,6 +3910,10 @@ Import from the entries listed below; source area files are internal.
 | `SurfaceObservation` | `pi-roundtable/testing` | type |
 | `eagerText` | `pi-roundtable/testing` | value |
 | `fakeDiscord` | `pi-roundtable/testing` | value |
+| `fakeDiscordPoster` | `pi-roundtable/testing` | value |
+| `FakeDiscordPoster` | `pi-roundtable/testing` | type |
+| `FakePosterChannel` | `pi-roundtable/testing` | type |
+| `FakePosterMessage` | `pi-roundtable/testing` | type |
 | `fakePrecheck` | `pi-roundtable/testing` | value |
 | `fakePrechecks` | `pi-roundtable/testing` | value |
 | `FakePrecheck` | `pi-roundtable/testing` | type |
@@ -3989,6 +4032,10 @@ Import from the entries listed below; source area files are internal.
 | `isRuleLoad` | `pi-roundtable/kit` | value |
 | `InterimPoster` | `pi-roundtable/kit` | value |
 | `InterimPosterOptions` | `pi-roundtable/kit` | type |
+| `OpsAlerts` | `pi-roundtable/kit` | value |
+| `OpsAlertsOptions` | `pi-roundtable/kit` | type |
+| `OpsRaiseOptions` | `pi-roundtable/kit` | type |
+| `OpsAlertKind` | `pi-roundtable/kit` | type |
 | `JEV_COMPACTION_ENGINE` | `pi-roundtable/kit` | value |
 | `JEV_GOAL` | `pi-roundtable/kit` | value |
 | `JEV_PREVIOUS_SUMMARY_LIMIT_TOKENS` | `pi-roundtable/kit` | value |
@@ -4060,6 +4107,23 @@ Import from the entries listed below; source area files are internal.
 | `DiscordAdapterConfig` | `pi-roundtable/discord` | type |
 | `DiscordConnection` | `pi-roundtable/discord` | type |
 | `DiscordServices` | `pi-roundtable/discord` | type |
+| `DISCORD_LIMITS` | `pi-roundtable/discord` | value |
+| `DiscordPosterError` | `pi-roundtable/discord` | value |
+| `CardButton` | `pi-roundtable/discord` | type |
+| `CardLink` | `pi-roundtable/discord` | type |
+| `CardSelect` | `pi-roundtable/discord` | type |
+| `CategoryChannel` | `pi-roundtable/discord` | type |
+| `DiscordCard` | `pi-roundtable/discord` | type |
+| `DiscordFailure` | `pi-roundtable/discord` | type |
+| `DiscordMessage` | `pi-roundtable/discord` | type |
+| `DiscordPoster` | `pi-roundtable/discord` | type |
+| `DiscordReason` | `pi-roundtable/discord` | type |
+| `PostedMessage` | `pi-roundtable/discord` | type |
+| `PosterFile` | `pi-roundtable/discord` | type |
+| `RecentMessage` | `pi-roundtable/discord` | type |
+| `ThreadCloser` | `pi-roundtable/discord` | type |
+| `ThreadState` | `pi-roundtable/discord` | type |
+| `WebhookPost` | `pi-roundtable/discord` | type |
 | `InteractionContribution` | `pi-roundtable/discord` | type |
 | `InteractionModule` | `pi-roundtable/discord` | type |
 | `ManagedChannel` | `pi-roundtable/discord` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.17.3",
+	"version": "0.18.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",
@@ -27,6 +27,8 @@
 		"!src/**/*.test.ts",
 		"!src/core/testing/file-size.ts",
 		"!src/core/testing/prompt-capture*.ts",
+		"!src/core/testing/discord-api-emulator*.ts",
+		"!src/core/discord/poster/poster-contract*.ts",
 		"!src/core/testing/fixtures",
 		"!src/prompt-text.snapshot.json",
 		"!src/cli/testing",
@@ -65,19 +67,19 @@
 		"canvas": "3.2.3",
 		"discord.js": "14.27.0",
 		"pi-jev-compaction": "1.0.0",
-		"pi-mcp-adapter": "5.2.0",
+		"pi-mcp-adapter": "5.3.0",
 		"pino": "10.4.0",
-		"typebox": "1.3.34",
+		"typebox": "1.3.37",
 		"unpdf": "1.8.1"
 	},
 	"peerDependencies": {
-		"pi-web-access": ">=0.35.0 <0.36.0"
+		"pi-web-access": ">=0.35.0 <0.41.0"
 	},
 	"devDependencies": {
 		"typescript": "7.0.2",
 		"@biomejs/biome": "2.5.15",
-		"@types/bun": "1.4.2",
+		"@types/bun": "1.4.3",
 		"pi-self-compact": "0.2.0",
-		"pi-web-access": "0.39.0"
+		"pi-web-access": "0.40.0"
 	}
 }

package/src/core/builtin/discord.ts

@@ -18,6 +18,8 @@ import type {
 } from "../discord/interaction-module.ts";
 import { OwnerCards } from "../discord/owner-cards.ts";
 import { commandGuard, ownerRootCommand } from "../discord/owner-command.ts";
+import type { DiscordPoster } from "../discord/poster/poster.ts";
+import { restOf, restPoster } from "../discord/poster/rest-poster.ts";
 import { stopButtonModule } from "../discord/stop-button.ts";
 import type { InboundMessage } from "../domain/conversation.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
@@ -32,6 +34,13 @@ export interface DiscordServices {
 	guard: CommandGuard;
 	/** The threads that carry background reports. */
 	threads: DispatchThreads;
+	/**
+	 * Discord's REST API for a plugin's own posts, over the Discord plugin's own client and its rate
+	 * limits: webhook posts under names the plugin chooses, the bot's own messages and cards, pins,
+	 * direct messages, threads and channels. Usable from a service's `start` on; a call never pings
+	 * anyone it does not name. See `DiscordPoster`.
+	 */
+	poster: DiscordPoster;
 	/**
 	 * What was said in a server channel since the assistant last posted there, before `message`:
 	 * for a claim that answers it, to append to its turn's text with `withChannelContext`. Call it
@@ -189,6 +198,8 @@ export function discordPlugin(options: DiscordOptions): RoundtablePlugin {
 				commands: collection.registrar,
 				guard,
 				threads,
+				// Built over the client's REST queue and sends nothing until a plugin calls it.
+				poster: restPoster(restOf(connected.rest())),
 				channelContext: (message, given) => context.of(message, given),
 			});
 			return {

package/src/core/discord/discord-surface.ts

@@ -9,6 +9,7 @@ import {
 	type Message,
 	MessageFlags,
 	Partials,
+	type REST,
 } from "discord.js";
 import type { AgentChannels, DashboardBoard } from "../agents/agent-ports.ts";
 import type { ChatSurface } from "../contract/surface.ts";
@@ -94,6 +95,13 @@ export class DiscordSurface
 	constructor(options: DiscordSurfaceOptions) {
 		this.#options = options;
 		this.formatting = pickFormatting(options.formatting, DISCORD_FORMATTING);
+		// REST works before the gateway logs in; `login` sets the same token again.
+		this.#client.rest.setToken(options.token);
+	}
+
+	/** The client's REST queue, whose rate limits every request of this process shares. */
+	rest(): REST {
+		return this.#client.rest;
 	}
 
 	/** Slash commands and the modules that answer them; the commands are registered globally at startup. */

package/src/core/discord/poster/poster-checks.ts

@@ -0,0 +1,272 @@
+import {
+	DISCORD_LIMITS,
+	type DiscordCard,
+	type WebhookPost,
+} from "./poster.ts";
+import { DiscordPosterError } from "./poster-errors.ts";
+
+/** The flag that makes a message a Components V2 message. */
+export const COMPONENTS_V2_FLAG = 1 << 15;
+
+/** The longest picture address a post carries. */
+const AVATAR_URL_MAX = 2_048;
+
+/** The longest address Discord accepts on a link button. */
+const LINK_BUTTON_URL_MAX = 512;
+
+/** Discord's style number for a button that opens an address. */
+const LINK_BUTTON_STYLE = 5;
+
+const BUTTON_STYLES = {
+	primary: 1,
+	secondary: 2,
+	success: 3,
+	danger: 4,
+} as const;
+
+const SNOWFLAKE = /^[0-9]{17,20}$/;
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+export function invalid(message: string): DiscordPosterError {
+	return new DiscordPosterError("invalid", message);
+}
+
+/** Refuses an id that is not a Discord id before it is put in a route. */
+export function checkSnowflake(label: string, value: string): string {
+	if (!SNOWFLAKE.test(value))
+		throw invalid(`${label} is not a Discord id (17 to 20 digits)`);
+	return value;
+}
+
+function checkMentions(mentions: readonly string[] | undefined): string[] {
+	const list = [...new Set(mentions ?? [])];
+	if (list.length > DISCORD_LIMITS.mentions)
+		throw invalid(`a post may ping at most ${DISCORD_LIMITS.mentions} people`);
+	return list.map((id) => checkSnowflake("a mention", id));
+}
+
+/** Whether Discord would refuse the name: "discord" or "clyde" in it (any case, full-width too). */
+function forbiddenWord(name: string): boolean {
+	return /clyde|discord/i.test(name.normalize("NFKC"));
+}
+
+/** A webhook's name: 1 to 80 characters, without the words Discord refuses. */
+export function checkWebhookName(name: string): string {
+	const { min, max } = DISCORD_LIMITS.usernameChars;
+	const chars = [...name].length;
+	if (chars < min || chars > max)
+		throw invalid(`a webhook name is ${min} to ${max} characters`);
+	if (forbiddenWord(name))
+		throw invalid('a webhook name has no "discord" or "clyde" in it');
+	return name;
+}
+
+/** The username a post shows: the same rule, and not "everyone" or "here". */
+function checkUsername(raw: string): string {
+	const username = raw.trim();
+	const { min, max } = DISCORD_LIMITS.usernameChars;
+	if (username.length < min || username.length > max)
+		throw invalid(`a username is ${min} to ${max} characters`);
+	if (
+		forbiddenWord(username) ||
+		["everyone", "here"].includes(username.normalize("NFKC").toLowerCase())
+	)
+		throw invalid(
+			'a username is not "everyone" or "here" and has no "discord" or "clyde" in it',
+		);
+	return username;
+}
+
+/** The body fields every post and edit carries: the text, and the only people it may ping. */
+export function checkedText(
+	content: string | undefined,
+	mentions: readonly string[] | undefined,
+): { content?: string; allowed_mentions: { parse: []; users: string[] } } {
+	if (content !== undefined && content.length > DISCORD_LIMITS.contentChars)
+		throw invalid(
+			`a message is at most ${DISCORD_LIMITS.contentChars} characters; split it first`,
+		);
+	return {
+		...(content === undefined ? {} : { content }),
+		// parse is empty: no @everyone, role or user is pinged from the text; users names them.
+		allowed_mentions: { parse: [], users: checkMentions(mentions) },
+	};
+}
+
+/** The checked body of a webhook post, its webhook name, and the files to send with it. */
+export function checkedPost(post: WebhookPost) {
+	const webhook = checkWebhookName(post.webhook);
+	const username = checkUsername(post.username);
+	const files = post.files ?? [];
+	if (files.length > DISCORD_LIMITS.filesPerPost)
+		throw invalid(
+			`a post carries at most ${DISCORD_LIMITS.filesPerPost} files`,
+		);
+	const bytes = files.reduce((sum, file) => sum + file.data.byteLength, 0);
+	if (bytes > DISCORD_LIMITS.postBytes)
+		throw invalid(
+			`the files of a post total at most ${DISCORD_LIMITS.postBytes} bytes`,
+		);
+	if (!post.content && files.length === 0)
+		throw invalid("a post needs text or a file");
+	return {
+		webhook,
+		body: {
+			username,
+			...(isHttps(post.avatarUrl) ? { avatar_url: post.avatarUrl } : {}),
+			...checkedText(post.content, post.mentions),
+		},
+		files,
+	};
+}
+
+function isHttps(url: string | undefined): url is string {
+	if (url === undefined || url.length > AVATAR_URL_MAX) return false;
+	try {
+		return new URL(url).protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+
+/** Whether the bytes are a PNG no larger than a webhook avatar may be. */
+export function checkAvatar(png: Uint8Array): void {
+	if (png.byteLength > DISCORD_LIMITS.avatarBytes)
+		throw invalid(
+			`an avatar is at most ${DISCORD_LIMITS.avatarBytes} bytes, this one is ${png.byteLength}`,
+		);
+	if (!PNG_SIGNATURE.every((byte, index) => png[index] === byte))
+		throw invalid("an avatar is a PNG");
+}
+
+/** A channel or thread name: 1 to 100 characters. */
+export function checkChannelName(label: string, name: string): void {
+	const chars = [...name].length;
+	if (chars < 1 || chars > DISCORD_LIMITS.channelNameChars)
+		throw invalid(
+			`${label} is 1 to ${DISCORD_LIMITS.channelNameChars} characters`,
+		);
+}
+
+/**
+ * The body of a card: a container (with a colour bar when `accent` is set) holding the heading, a
+ * divider, one text block per section and a quiet line at the end. It refuses a card whose text
+ * would not fit one message, so a caller shortens it first. No mention in it pings.
+ */
+export function cardBody(card: DiscordCard) {
+	const heading = `### ${card.title}`;
+	const texts = [
+		heading,
+		...card.sections.filter((section) => section !== ""),
+		...(card.footer ? [`-# ${card.footer}`] : []),
+	];
+	const size = texts.reduce((sum, text) => sum + [...text].length, 0);
+	if (size > DISCORD_LIMITS.cardTextChars)
+		throw invalid(
+			`a card holds at most ${DISCORD_LIMITS.cardTextChars} characters of text; shorten it first`,
+		);
+	if (texts.some((text) => text.trim() === ""))
+		throw invalid("a card has no empty text");
+	const [first, ...rest] = texts;
+	const buttons = card.buttons ?? [];
+	const links = card.links ?? [];
+	if (buttons.length + links.length > DISCORD_LIMITS.cardButtons)
+		throw invalid(`a card holds at most ${DISCORD_LIMITS.cardButtons} buttons`);
+	for (const link of links) {
+		if (link.label === "" || [...link.label].length > 80)
+			throw invalid("a link button has a label of 1 to 80 characters");
+		if (
+			!link.url.startsWith("https://") ||
+			[...link.url].length > LINK_BUTTON_URL_MAX
+		)
+			throw invalid(
+				`a link button has an https address of at most ${LINK_BUTTON_URL_MAX} characters`,
+			);
+	}
+	const selects = card.selects ?? [];
+	for (const select of selects) {
+		if (
+			select.customId === "" ||
+			[...select.customId].length > 100 ||
+			select.placeholder === "" ||
+			[...select.placeholder].length > 150 ||
+			select.options.length < 1 ||
+			select.options.length > DISCORD_LIMITS.selectOptions ||
+			select.options.some(
+				(option) =>
+					option.label === "" ||
+					[...option.label].length > 100 ||
+					option.value === "" ||
+					[...option.value].length > 100,
+			)
+		)
+			throw invalid(
+				"a menu has an id of 1 to 100 characters, a placeholder of 1 to 150 and 1 to 25 choices of 1 to 100 characters",
+			);
+	}
+	for (const button of buttons) {
+		if (
+			button.customId === "" ||
+			[...button.customId].length > 100 ||
+			button.label === "" ||
+			[...button.label].length > 80
+		)
+			throw invalid(
+				"a button has an id of 1 to 100 characters and a label of 1 to 80",
+			);
+	}
+	return {
+		flags: COMPONENTS_V2_FLAG,
+		components: [
+			{
+				type: 17,
+				...(card.accent === undefined ? {} : { accent_color: card.accent }),
+				components: [
+					{ type: 10, content: first },
+					...(rest.length > 0 ? [{ type: 14, divider: true, spacing: 1 }] : []),
+					...rest.map((content) => ({ type: 10, content })),
+					...selects.map((select) => ({
+						type: 1,
+						components: [
+							{
+								type: 3,
+								custom_id: select.customId,
+								placeholder: select.placeholder,
+								min_values: 1,
+								max_values: 1,
+								options: select.options.map((option) => ({
+									label: option.label,
+									value: option.value,
+									...(option.selected ? { default: true } : {}),
+								})),
+							},
+						],
+					})),
+					...(buttons.length + links.length > 0
+						? [
+								{
+									type: 1,
+									components: [
+										...buttons.map((button) => ({
+											type: 2,
+											style: BUTTON_STYLES[button.style],
+											label: button.label,
+											custom_id: button.customId,
+											...(button.disabled ? { disabled: true } : {}),
+										})),
+										...links.map((link) => ({
+											type: 2,
+											style: LINK_BUTTON_STYLE,
+											label: link.label,
+											url: link.url,
+										})),
+									],
+								},
+							]
+						: []),
+				],
+			},
+		],
+		allowed_mentions: { parse: [] as never[] },
+	};
+}

package/src/core/discord/poster/poster-errors.ts

@@ -0,0 +1,106 @@
+import { DiscordAPIError, HTTPError, RESTJSONErrorCodes } from "discord.js";
+
+/** Why a call to Discord failed. */
+export type DiscordFailure =
+	| "invalid" // the call was refused before it was sent (a bad argument)
+	| "channel_gone" // the channel does not exist (any more)
+	| "message_gone" // the message does not exist (any more)
+	| "forbidden" // the bot lacks a permission
+	| "rejected" // Discord refused it for another reason; asking again fails again
+	| "unavailable"; // Discord or the network failed, or a rate limit held it back; asking again may work
+
+/**
+ * More about why Discord refused, where its code alone does not say: a category that is full (a
+ * 400 with a form-body error) and a channel that is no category or in no right guild.
+ */
+export type DiscordReason = "category_full" | "not_category" | "wrong_guild";
+
+/**
+ * A failed Discord call. The message names the operation and Discord's own reason, never a URL,
+ * a webhook token or the bot token.
+ */
+export class DiscordPosterError extends Error {
+	override name = "DiscordPosterError";
+	readonly kind: DiscordFailure;
+	/** Discord's JSON error code, when it sent one. */
+	readonly discordCode: number | undefined;
+	readonly status: number | undefined;
+	readonly reason: DiscordReason | undefined;
+	constructor(
+		kind: DiscordFailure,
+		message: string,
+		detail: {
+			discordCode?: number;
+			status?: number;
+			reason?: DiscordReason;
+		} = {},
+	) {
+		super(message);
+		this.kind = kind;
+		this.discordCode = detail.discordCode;
+		this.status = detail.status;
+		this.reason = detail.reason;
+	}
+	/** Whether the same call may work later. */
+	get retryable(): boolean {
+		return this.kind === "unavailable";
+	}
+}
+
+/**
+ * Turns whatever the REST client threw into a `DiscordPosterError`. Discord's error carries the
+ * request URL, which for a webhook holds its token, so only the operation and Discord's own words
+ * are kept.
+ */
+export function failure(operation: string, error: unknown): DiscordPosterError {
+	if (error instanceof DiscordPosterError) return error;
+	if (error instanceof DiscordAPIError) {
+		const detail: {
+			discordCode: number;
+			status: number;
+			reason?: "category_full";
+		} = { discordCode: Number(error.code), status: error.status };
+		// A full category comes back as a form-body error naming the parent, not as a code of its own.
+		if (
+			Number(error.code) === RESTJSONErrorCodes.InvalidFormBodyOrContentType &&
+			JSON.stringify(error.rawError).includes("CHANNEL_PARENT_MAX_CHANNELS")
+		)
+			detail.reason = "category_full";
+		const said = `${operation} failed (${error.status}, code ${error.code}): ${error.message}`;
+		switch (error.code) {
+			case RESTJSONErrorCodes.UnknownChannel:
+				return new DiscordPosterError("channel_gone", said, detail);
+			case RESTJSONErrorCodes.UnknownMessage:
+				return new DiscordPosterError("message_gone", said, detail);
+			case RESTJSONErrorCodes.UnknownWebhook:
+			case RESTJSONErrorCodes.InvalidWebhookToken:
+				return new DiscordPosterError("rejected", said, detail);
+			case RESTJSONErrorCodes.MissingPermissions:
+			case RESTJSONErrorCodes.MissingAccess:
+				return new DiscordPosterError("forbidden", said, detail);
+			default:
+				return new DiscordPosterError(
+					error.status >= 500 ? "unavailable" : "rejected",
+					said,
+					detail,
+				);
+		}
+	}
+	if (error instanceof HTTPError)
+		return new DiscordPosterError(
+			"unavailable",
+			`${operation} failed (${error.status})`,
+			{ status: error.status },
+		);
+	// A network failure or a timeout: the reason without the request.
+	const reason = error instanceof Error ? error.name : "unknown error";
+	return new DiscordPosterError(
+		"unavailable",
+		`${operation} failed (${reason})`,
+	);
+}
+
+/** Whether the REST client threw Discord's error with one of these JSON codes. */
+export function isCode(error: unknown, ...codes: number[]): boolean {
+	return error instanceof DiscordAPIError && codes.includes(Number(error.code));
+}