pi-roundtable 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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
+
+- The 0.17.1 entry and the plugin guide called `turnTimeoutMs` and `turnMaxMs` options of the built-in runtime that a host can set. Nothing public sets them: the runtime plugin passes neither, and the runtime class is not exported. Every host runs a turn with 10 minutes of work, renewed by each steer up to 30 minutes in all. The guide now says the two limits are fixed, and its startup order lists the runtime's own `preflight`, which 0.17.2 moved after every plugin's.
+- `testPlugin` runs the runtime's `preflight` where the host does, right after the plugin's own and before the plugin's services and surfaces start, not after they have. A runtime whose `preflight` throws fails `testPlugin` with that error, with nothing started and the runtime disposed.
+- A time limit on a turn, or on a coding worker (`workTimeout`), that comes due while an owner's card is open looks at the turn again no oftener than once a second, not once a millisecond for as long as the card waits. The limit still fires once; a limit that waiting on a card pushed back can fire up to a second late.
+
+### Changed
+
+- 0.17.2 was tagged but never published: its release run stopped on a LINE plugin test that raced its own frozen clock. 0.17.3 carries 0.17.2's fix, the runtime's startup probe after every plugin's `preflight`; the LINE tests that raced now step their clock, and no shipped LINE code changed.
+
+## [0.17.2] - 2026-10-16
+
+### Fixed
+
+- The runtime's startup probe of the model and the required tools runs after every plugin's `preflight`, not in the runtime plugin's own preflight, which ran first. Since 0.17.0 a plugin that resolves its MCP servers does so in its preflight, so the probe no longer saw the tools they yield, and a required tool that was missing failed only the first session instead of the start. The host now runs the `RUNTIME` service's `preflight` once every plugin's preflight has finished, still before any service starts or any listener opens; a failure stops the start, and the same host may try again. A custom runtime provider's `preflight` moves to the same place. The runtime plugin's claude-bridge memory warning stays in its own preflight. `Roundtable.check()` still runs no preflight.
+
 ## [0.17.1] - 2026-10-16
 
 ### Changed

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.
@@ -1443,7 +1449,7 @@ An `AgentRuntime` has these methods:
 | `pendingConfirmation(conversation)`, `heldActions(conversation)` | The held actions known in memory, and those restored from the store after a restart: the agent server reads `heldActions` to show an approval card again after a restart. After a restart `pendingConfirmation` knows a conversation's held actions only once `heldActions` or `recentTranscript` has restored them, so a host that decides an approval asks one of them first. A `PendingConfirmation` carries the `selectionId` of the `TurnSelection` whose turn held the calls, an opaque string that the caller resolves again when the owner confirms; the core stores it and never reads it |
 | `recentTranscript(conversation, limit)` | The latest messages, for the owner's and the dashboard's views of a conversation; the built-in runtime gives none of a history recorded, or a session opened, for someone else than the conversation serves now |
 | `contextUsage?(conversation)` | How full the conversation's context is, `{ tokens, contextWindow }`; leave it out and the team status shows no context bar |
-| `preflight?()` | Runs in the host's preflight, before anything starts; a throw stops the boot |
+| `preflight?()` | Runs after every plugin's preflight, before anything starts; a throw stops the boot |
 | `dispose?()` | Runs when the host stops the runtime plugin's `runtime` service |
 
 A request has the turn's `channel`, `selection` (its tools), `text`, `attachments`, `speaker` (required: the person the turn is for, at whose tier it runs; the built-in runtime refuses a request without one with an `AgentRunError` before asking the model, and a plugin that starts a turn on someone's behalf gets theirs from `IDENTITY.speakerFor`), `conversation` (`TurnConversation`: `private` to a `principalId`, or `shared`, as `context.turns` records it; shared when absent), flags (`steerable`, `interactive`, `confirmed`: the speaker's message approved the conversation's held calls, which the runtime releases for the speaker, except those that [name approvers](#a-hold-that-names-its-approvers) the speaker is neither among nor an owner of, which stay held), and `interim`, where the turn may post the text it writes before its final answer ([interim text](#interim-text-what-a-turn-writes-before-its-final-answer)).
@@ -1698,6 +1704,10 @@ test("only one plugin may fill the runtime slot", async () => {
 `preflight` also sits on the plugin.
 It runs once every plugin is set up and linked, before any command is registered or any service starts.
 A throw stops the boot, so a missing setting is caught before Discord connects.
+Plugins' preflights run in plugin order.
+Once every one has finished, the host runs the runtime's own `preflight` (the `RUNTIME` service's), which for Pi's runtime builds throwaway sessions and checks the model and the required tools.
+So tools a plugin fills in during its preflight, such as MCP servers it resolves there, are in those sessions, and a required tool still missing stops the start before any service starts or any listener opens.
+`Roundtable.check()` runs no preflight.
 
 <!-- example: examples/preflight.ts -->
 ```ts
@@ -2425,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.
@@ -3268,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
 
@@ -3283,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:
 
@@ -3367,6 +3410,7 @@ The host's `run()` handles startup:
    From here `sessions()`, `conversations`, `surfaces`, `turns`, and `dashboard()` work.
 5. Every plugin's `preflight` runs, in plugin order.
    The Discord plugin's preflight is where it composes the slash commands every plugin added in `setup`; a clash stops the start here.
+   Once every one has finished, the runtime's own `preflight` (the `RUNTIME` service's) runs, so its check of the model and the required tools sees the tools that other plugins filled in during theirs.
 6. Every service starts: the plugins' in plugin order, and each plugin's own in the order it listed them, after the plugin's chat surfaces (the `surface:<prefix>` services).
 7. The HTTP listeners open.
 8. Every service's `startInBackground` runs, at once and without holding up the boot, and every plugin hears `serviceStarted` as each ends; the agent server's `team` service starts the agents' channels and the dashboard there.
@@ -3395,7 +3439,7 @@ On `SIGTERM` or `SIGINT` the bot takes no new work at once, finishes what runs,
 `shutdown()` returns exit code `0`, or `1` if a listener, service, or pool failed to stop.
 Every call shares the same shutdown.
 Give the service manager a stop timeout longer than the drain limit plus about a minute for the steps after it, such as systemd's `TimeoutStopSec=5min` with the default three-minute drain; a shorter one has the manager kill the process in the middle of the drain.
-The built-in runtime aborts a turn that works 10 minutes (`turnTimeoutMs`), not counting time spent waiting on the owner's cards. Each message steered into the running turn gives it the full 10 minutes again from that moment, up to a cap of 30 minutes of work for the whole turn (`turnMaxMs`, three times `turnTimeoutMs` by default); once the cap is reached the turn takes no more steering, so a message waits for the next turn, and the turn is aborted as on its timeout. The log says `steer renewed the turn's time budget` with `deadlineMs`, the work time left, and the timeout warning names the limit that fired (`limit: "turn"` or `"turnMax"`). Task workers (`task.timeoutMs`), coding workers (`workTimeout`) and sandbox guests (their own `turnTimeoutMs`) keep their own limits, which steering does not renew.
+The built-in runtime aborts a turn that works 10 minutes, not counting time spent waiting on the owner's cards. Each message steered into the running turn gives it the full 10 minutes again from that moment, up to a cap of 30 minutes of work for the whole turn; once the cap is reached the turn takes no more steering, so a message waits for the next turn, and the turn is aborted as on its timeout. Both limits are fixed: the runtime plugin passes no option for them, so a host cannot change them, and a limit that waiting on an owner's card pushed back can fire up to a second late. The log says `steer renewed the turn's time budget` with `deadlineMs`, the work time left, and the timeout warning names the limit that fired (`limit: "turn"` or `"turnMax"`). Task workers (`task.timeoutMs`), coding workers (`workTimeout`) and sandbox guests (their own `turnTimeoutMs`) keep their own limits, which steering does not renew.
 A turn whose model ignores its abort (a subprocess that does not exit) is given up on too: a turn that outlives its timeout, or is stopped, gets `turnAbortGraceMs` (15 seconds by default) to end, and then its session is disposed of and the turn is reported failed, so it cannot hold the queue.
 `listen()`, called by the command line and a host's own entry point, exits the process with that code.
 
@@ -3866,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 |
@@ -3984,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 |
@@ -4055,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.1",
+	"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/contract/runtime.ts

@@ -72,7 +72,7 @@ export interface AgentRuntime {
 	): Promise<TranscriptEntry[]>;
 	/** Undefined when unknown; the team status shows no context bar for the conversation then. */
 	contextUsage?(conversation: ChannelKey): ContextUse | undefined;
-	/** Runs in the host's preflight, before anything starts; a throw stops the boot. */
+	/** Runs after every plugin's preflight, before anything starts; a throw stops the boot. */
 	preflight?(): Promise<void>;
 	/** Runs when the host stops the agent server's runtime service. */
 	dispose?(): Promise<void> | void;

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[] },
+	};
+}