pi-roundtable 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-01
+
+### Changed
+
+- `@earendil-works/pi-ai` and `@earendil-works/pi-coding-agent` are no longer pinned to one version: they take `>=0.99.2 <1`, so a host picks up a newer model table with `bun update @earendil-works/pi-ai @earendil-works/pi-coding-agent`, or its own direct dependency, without waiting for a pi-roundtable release. Pinned to 0.87.1 before, the host's model list stopped at the models that version knew. 0.99.2 is the lowest version the tests run against, and the lockfile keeps CI on it, so a host that updates further runs on versions this package was not tested with.
+- `pi-mcp-adapter` is 4.0.0 (was 2.37.0). Version 2.37.0 declared support for pi-ai up to 0.87 only; 4.0.0 declares 0.99. It stays pinned. Checked by connecting a session built the way the core builds one to a local MCP server that requires a bearer token: the tool registered and a call returned its result.
+- A judge or agent model that the newer table lists but the host has no login for fails with the provider's "Provider is not configured" error, where an unlisted model fails with "is not available".
+
+### Fixed
+
+- Agents had no `skill_list` tool, although the `agent_create` description, the built-in `writing-skills` skill and the skill errors all tell them to call it. The `skills` addon now mounts it for agent sessions, at the member tier like its entry in the tool tiers. A host that mounted `skillListExtension` itself for agents (the kit still exports it) now offers the tool twice and should drop its own copy.
+
+## [0.4.0] - 2026-10-01
+
+### Added
+
+- `PluginContext.apiKey(provider)`: the credential the host's model login holds for a provider, such as `openai-codex`, or `undefined` when it holds none. It resolves through the same login the agents use, so a plugin that calls a provider's API needs no login of its own. The value is a secret; keep it out of logs and error messages.
+- `testPlugin` and `testHost` take `apiKeys`, the credentials `context.apiKey` returns by provider. Without it every provider reads as having none, whatever login the machine holds.
+- `roundtable add plugin codex-images` and `roundtable add plugin dice` copy an official plugin into the project and list it in `roundtable.config.ts`, the way `add plugin` copies the `hello` template. `codex-images` fills the `images` slot through the owner's ChatGPT login and the Codex backend, which OpenAI does not document for this use, so it can stop working without notice. `dice` adds a `roll_dice` tool for dice expressions such as `4d6k3`.
+- A documentation site at pi-roundtable.wayneh.tw, in English and Traditional Chinese.
+
+### Changed
+
+- `codex-images` and `dice` are reserved names for `add plugin`: it copies the official plugin for them and keeps the `hello` template for every other name.
+- The project `init` writes seeds Guide into the entry channel, so Guide is the coordinator on the first start. Agents that are already stored keep the channel they have.
+- `PluginContext` has a new member, `apiKey`; a hand-written `PluginContext` (only the core's own and tests') needs it.
+- The READMEs no longer say `/roundtable help` opens a control panel. The core registers `/roundtable schedule list` and `/roundtable schedule cancel` only.
+
 ## [0.3.0] - 2026-10-01
 
 Found by running the first consuming host on the published 0.2.1; each item answers one finding of its friction log.

package/README.md

@@ -67,7 +67,7 @@ A fresh project fails only on the credentials you have not entered yet, and says
 ### `start`
 
 `bunx roundtable start` runs the checks that need no network, stops with the same message `doctor` prints when one fails, and otherwise starts the bot.
-Once it runs, the agents in `agents.ts` have their channels, and `/roundtable help` opens the control panel.
+Once it runs, the agents in `agents.ts` have their channels, and `/roundtable schedule list` shows their schedules.
 On `SIGTERM` or `SIGINT` it finishes running work before it stops.
 
 ## A plugin

package/README.zh-TW.md

@@ -1,6 +1,6 @@
 # pi-roundtable
 
-[English](README.md) | 繁體中文
+[English](./README.md) | 繁體中文
 
 一個建立在 [Pi](https://github.com/earendil-works/pi) 上的 Discord 智慧體（agent）伺服器。
 你會在一個 Discord 伺服器裡得到一組 AI 智慧體：每個智慧體擁有一個頻道和一段對話，彼此共用工具與記憶，你用 TypeScript 寫外掛（plugin）來擴充這個 bot。
@@ -67,7 +67,7 @@ Bun 會自行載入 `.env`，`.gitignore` 也已讓它不進 Git。
 ### `start`
 
 `bunx roundtable start` 先執行不需要網路的檢查，其中任何一項失敗就停下來，並印出與 `doctor` 相同的訊息；全部通過則啟動 bot。
-啟動後，`agents.ts` 裡的智慧體都有了自己的頻道，`/roundtable help` 會開啟控制面板。
+啟動後，`agents.ts` 裡的智慧體都有了自己的頻道，`/roundtable schedule list` 可以列出它們的排程。
 收到 `SIGTERM` 或 `SIGINT` 時，它會先讓進行中的工作完成再停止。
 
 ## 外掛

package/docs/plugins.md

@@ -62,6 +62,7 @@ A plugin that runs Pi itself, a coding worker or a container with no network, ta
 
 `roundtable add plugin <name>` creates `plugins/<name>.ts` and its test from a small template and lists it in `roundtable.config.ts`.
 The name is lowercase words joined by dashes, such as `my-notes`.
+Two names are reserved for the [official plugins](#official-plugins): `codex-images` and `dice` copy a ready-made plugin into the project instead of the template.
 
 ## The plugin object
 
@@ -96,6 +97,7 @@ A plugin whose `setup` returns `{}` and that has no migrations, providers, or ho
 | `toolTiers` | What each tool needs; ask it when a tool is used, not during setup |
 | `events` | Where the core reports turns and team changes to every plugin's handlers |
 | `providers` | Each provider slot, from the plugin that fills it or the core's default; `providers.filled` is the set of slots a plugin fills |
+| `apiKey(provider)` | The credential the host's model login holds for a provider such as `openai-codex`, the same login the agents use. It resolves to `undefined` when the host has none for that provider and never throws for that. The value is a secret: keep it out of logs and error messages. Read it when you use it rather than keeping it, since a login may refresh its token |
 | `queue` | The one channel queue that every conversation and channel operation shares |
 | `services` | The services plugins provide to each other, read by key: `services.get(SCHEDULES)`; see [services](#services-what-plugins-provide-to-each-other) |
 | `surfaces` | Every contributed [chat surface](#surfaces-a-chat-network-of-your-own), chosen by the prefix of a channel key: `of`, `sendReply`, `startTyping`, `showStop`, `react`, `unreact`, `prompts` |
@@ -287,7 +289,7 @@ They are on by default, so a bot that says nothing about them has all three.
 | Addon | Plugin | Switch in `roundtable.config.ts` | What it adds | When it is off |
 |---|---|---|---|---|
 | Memory | `memory` (provides `MEMORY`) | `memory: false` | The memory table, the `memory_add`, `memory_search` and `memory_remove` tools, and the memory block of every system prompt | No memory tools and no block; the table is left as it is |
-| Skills | `skills` (provides `SKILLS`) | `skills: false` | The skill tables, the skill tools of agent sessions (`skill_link`, `skill_create`, `agent_skills`, and the rest), and the skills every agent carries, `writing-skills` included | No skill tools and no skills in any session; `agent_get` has no skills line; `agent_create` leaves out its `skills` parameter and refuses a call that passes some with `Skills are off on this host`; the tables are left as they are |
+| Skills | `skills` (provides `SKILLS`) | `skills: false` | The skill tables, the skill tools of agent sessions (`skill_list`, `skill_link`, `skill_create`, `agent_skills`, and the rest), and the skills every agent carries, `writing-skills` included | No skill tools and no skills in any session; `agent_get` has no skills line; `agent_create` leaves out its `skills` parameter and refuses a call that passes some with `Skills are off on this host`; the tables are left as they are |
 | Discord administration | `discord-admin` | `discord: { admin: false }` | The `discord_*` tools that read and manage the server, for the owner | No `discord_*` tools; the channel executor that remote MCP uses is the connection's, so it stays |
 
 A switched-off addon's tables and rows are never touched: turning it on again finds them as they were.
@@ -1722,6 +1724,26 @@ A plugin that still has one is refused where it is written (`definePlugin`) or w
 | `RoundtablePlugin.agentServer()` and the `agentServer(outcome)` event | A service with `startInBackground`, and the `serviceStarted` event handler |
 | `RoundtablePlugin.stopTurn(channel)` | `stop(channel)` on the `ChannelClaim` that owns the channel |
 
+## Official plugins
+
+The package ships two plugins you can copy into a project and change.
+`roundtable add plugin codex-images` and `roundtable add plugin dice` write `plugins/<name>.ts` and `plugins/<name>.test.ts`, import the plugin in `roundtable.config.ts`, and list it in `plugins`, the way any `add plugin` does.
+The copy is yours: edit it freely, and `add plugin` refuses to overwrite it when the file already exists.
+Both names are reserved, so `add plugin codex-images` never makes a template plugin of that name.
+
+| Plugin | What it does | What it needs |
+|---|---|---|
+| `codex-images` | Fills the [`images` slot](#providers-replace-a-part-the-core-runs-on), so agents can draw avatars from a prompt and reference pictures | A login to the `openai-codex` provider; setup throws a `PluginError` that says so when the host has none |
+| `dice` | Adds the `roll_dice` tool for members: `2d6+3`, `4d6k3` (keep or drop the highest or lowest dice), several groups, and fate dice `dF`, answered as text such as `2d6+3: [3, 5] + 3 = 11` | Nothing; it takes at most 100 dice in all and 1000 sides per die |
+
+`codex-images` takes the login through [`context.apiKey("openai-codex")`](#the-context).
+It sends the request to ChatGPT's Codex backend, which OpenAI does not document for this use, with the owner's own ChatGPT subscription login.
+It can stop working without notice, and OpenAI's terms for the subscription apply.
+Use it only where you accept that risk; the file begins with the same warning.
+
+Each copy has a test that runs offline: `codex-images` with a fake `fetch`, `dice` with a fake random source.
+Both files export a `create...` function (`createCodexImages`, `createDice`) that takes the part a test replaces, and the plugin you list in the config, built from it.
+
 ## Testing a plugin
 
 Two harnesses, by what the test needs: `testPlugin(plugin, options?)` sets one plugin up alone, against a fake context, and is the default; [`testHost`](#testhost-the-built-in-plugins-and-yours-over-postgresql) boots the built-in plugins and yours together over PostgreSQL, for a test that depends on them or on the order the host sets things up in.
@@ -1756,6 +1778,7 @@ It does not run migrations (see [`migrations`](#migrations-and-contextdatabase-t
 | `services` | What the plugin reads from `context.services`: one `servicePair(KEY, { ... })` for each service, with the members you give it. `servicePair(AGENTS, { runtime })` is the runtime `context.turns` runs on. Reading a member you did not give throws a `PluginError` that names the option to add; a service you did not give reads as absent to `find`, and `get` says to give it, except for the ones below |
 | `conversations` | Methods that replace the router's, such as `stop`, for a plugin that calls them |
 | `turns` | A `ConversationTurns` that replaces the default one |
+| `apiKeys` | The credentials `context.apiKey(provider)` returns, by provider name: `{ "openai-codex": "key" }`. A provider not listed reads as having none, as on a host that is not logged in |
 | `forwardJoinMs` | How long the router holds a bare forward for the message that follows it (the host option `conversations.forwardJoinMs`) |
 
 The harness supplies what the host would, so a claim or a background turn behaves as it does there:
@@ -1820,6 +1843,7 @@ Only `commands` and `guard` are given; a plugin that reads another member of `DI
 | `config` | Over a test configuration (an owner, a guild, a temporary `dataDir`, the test database, one agent): any of the `RoundtableConfig` keys, such as `skills: false` |
 | `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()` |
 
 It returns:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",
@@ -45,11 +45,11 @@
 	},
 	"dependencies": {
 		"@babel/parser": "7.29.9",
-		"@earendil-works/pi-ai": "0.87.1",
-		"@earendil-works/pi-coding-agent": "0.87.1",
+		"@earendil-works/pi-ai": ">=0.99.2 <1",
+		"@earendil-works/pi-coding-agent": ">=0.99.2 <1",
 		"canvas": "3.2.3",
 		"discord.js": "14.27.0",
-		"pi-mcp-adapter": "2.37.0",
+		"pi-mcp-adapter": "4.0.0",
 		"pino": "10.3.1",
 		"typebox": "1.3.34",
 		"unpdf": "1.8.1"

package/src/cli/add-plugin.ts

@@ -31,9 +31,10 @@ const refused = (...problems: string[]): AddPluginReport => ({
 });
 
 /**
- * Creates `plugins/<name>.ts` and its test from the `hello` template and lists the plugin in
- * `roundtable.config.ts`. Everything is checked and rendered before the first write, so a refusal
- * leaves the project untouched.
+ * Creates `plugins/<name>.ts` and its test and lists the plugin in `roundtable.config.ts`: the
+ * copy of an official plugin when `name` is one, else a plugin made from the `hello` template.
+ * Everything is checked and rendered before the first write, so a refusal leaves the project
+ * untouched.
  */
 export function addPlugin(inputs: AddPluginInputs): AddPluginReport {
 	const { cwd, name } = inputs;

package/src/cli/cli.ts

@@ -12,6 +12,7 @@ import { loadConfigFile, type Ports } from "./project.ts";
 import { formatOutcomes } from "./report.ts";
 import { assemble, providerLogin } from "./runtime.ts";
 import { start } from "./start.ts";
+import { OFFICIAL_PLUGINS } from "./templates.ts";
 
 /** What the command line reads from its surroundings; tests replace every part. */
 export interface CliEnvironment {
@@ -31,6 +32,8 @@ const USAGE = `roundtable: a Discord agent server on Pi
   roundtable doctor [--reachable]  check the setup and say how to fix what is wrong
   roundtable start              run the checks that need no network, then the bot
   roundtable add plugin <name>  add plugins/<name>.ts and its test, and list it in the config
+                                the names ${OFFICIAL_PLUGINS.join(" and ")} are reserved for the official plugins,
+                                which are copied in ready to run instead of the template
 `;
 
 /** The package's own version and the Bun range it needs, from the package.json beside the source. */

package/src/cli/templates.ts

@@ -13,6 +13,16 @@ export const TEMPLATES_DIR = join(import.meta.dir, "../../templates");
 /** The directory of the plugin template, rendered once for `hello` and again for every `add plugin`. */
 const PLUGIN_DIR = "plugin";
 
+/** The directory of the official plugins, one directory each, named as `add plugin` names them. */
+const OFFICIAL_DIR = "official";
+
+/** The plugins the package ships ready-made: `add plugin <name>` copies these instead of the `hello` template, so the names are reserved. */
+export const OFFICIAL_PLUGINS = ["codex-images", "dice"] as const;
+
+/** Whether `name` is one of the official plugins. */
+export const isOfficialPlugin = (name: string): boolean =>
+	(OFFICIAL_PLUGINS as readonly string[]).includes(name);
+
 /** What a template file may say, replaced when it is rendered. */
 export interface Substitutions {
 	/** The project's package name. */
@@ -71,19 +81,22 @@ function fill(text: string, values: Record<string, string>): string {
 	});
 }
 
-/** The plugin and its test, written for `names`. */
+/** The plugin and its test, written for `names`: the official plugin of that name, or else the `hello` template. */
 export function renderPlugin(
 	names: PluginNames,
 	dir = TEMPLATES_DIR,
 ): Rendered[] {
 	const values = { NAME: names.name, IDENT: names.ident, TOOL: names.tool };
+	const source = isOfficialPlugin(names.name)
+		? join(OFFICIAL_DIR, names.name)
+		: PLUGIN_DIR;
 	return [
 		["plugin.ts", `plugins/${names.name}.ts`],
 		["plugin.test.ts.tmpl", `plugins/${names.name}.test.ts`],
-	].map(([source, path]) => ({
+	].map(([file, path]) => ({
 		path: path as string,
 		content: fill(
-			readFileSync(join(dir, PLUGIN_DIR, source as string), "utf8"),
+			readFileSync(join(dir, source, file as string), "utf8"),
 			values,
 		),
 	}));
@@ -101,7 +114,11 @@ export function renderProject(
 	};
 	const skeleton = filesUnder(dir)
 		.map((file) => relative(dir, file))
-		.filter((path) => !path.startsWith(`${PLUGIN_DIR}/`))
+		.filter(
+			(path) =>
+				!path.startsWith(`${PLUGIN_DIR}/`) &&
+				!path.startsWith(`${OFFICIAL_DIR}/`),
+		)
 		.map((path) => ({
 			path: targetOf(path),
 			content: fill(readFileSync(join(dir, path), "utf8"), values),

package/src/core/builtin/skills.ts

@@ -4,6 +4,7 @@ import { SkillStore } from "../modules/skills/skill-store.ts";
 import {
 	SKILL_LIST_TOOL,
 	SKILL_TOOLS,
+	skillListExtension,
 	skillToolsExtension,
 } from "../modules/skills/skill-tools.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
@@ -57,6 +58,7 @@ export function skillsPlugin(
 			services.provide(SKILLS, built);
 			return {
 				sessionTools: [
+					agentOnly("skill-list", () => skillListExtension(built)),
 					agentOnly("skill-tools", () =>
 						skillToolsExtension(built, (name) => {
 							// The agent server is set up after this plugin and read when a session is built.
@@ -64,7 +66,10 @@ export function skillsPlugin(
 						}),
 					),
 				],
-				agentSelection: () => ({ tools: SKILL_TOOLS, groups: [] }),
+				agentSelection: () => ({
+					tools: [SKILL_LIST_TOOL, ...SKILL_TOOLS],
+					groups: [],
+				}),
 				toolTiers: SKILL_TIERS,
 			};
 		},

package/src/core/config/config.ts

@@ -27,7 +27,10 @@ import {
 /** How prompts refer back to the owner. */
 export type Pronouns = "he" | "she" | "they";
 
-/** Who holds a tier besides the owner: user ids, role ids, and for members everyone. */
+/**
+ * Who holds a tier besides the owner: user ids, role ids, or everyone. `everyone` works under any
+ * tier it is written in, so under `admins` it makes every author an admin.
+ */
 export interface TierConfig {
 	users?: readonly string[];
 	roles?: readonly string[];

package/src/core/define-roundtable.ts

@@ -99,6 +99,7 @@ export async function defineRoundtable(
 			authPath: join(config.agentDir, "auth.json"),
 			modelsPath: join(config.agentDir, "models.json"),
 		}));
+	const registry = new ModelRegistry(modelRuntime);
 	const errorReporter = config.ops
 		? new ErrorReporter({ opsAgent: config.ops.agent, app: name })
 		: undefined;
@@ -156,6 +157,7 @@ export async function defineRoundtable(
 				...(overrides.listeners ?? []),
 			],
 			judgeModel: judgeThrough(modelRuntime, config.judge.model),
+			apiKey: (provider) => registry.getApiKeyForProvider(provider),
 			...(overrides.aborted ? { aborted: overrides.aborted } : {}),
 		},
 		plugins: [

package/src/core/host.ts

@@ -66,6 +66,11 @@ export interface RoundtableOptions {
 	};
 	/** The model the default judge asks, when no plugin provides a judge. */
 	judgeModel?: JudgeModel;
+	/**
+	 * The credential the model login holds for a provider, or undefined when it holds none; behind
+	 * `PluginContext.apiKey`. Without it every provider reads as having no credential.
+	 */
+	apiKey?: (provider: string) => Promise<string | undefined>;
 	/** What each tool needs: the operator's settings, with the plugins' tools added when the host links. */
 	toolTiers?: ToolTierTable;
 	/** The database the plugins' migrations and stores use; the host owns its one pool. */
@@ -311,6 +316,7 @@ export class Roundtable {
 						);
 					return this.#registry.dashboard;
 				},
+				apiKey: async (provider) => this.#options.apiKey?.(provider),
 			},
 			this.#tiers,
 			this.#services,

package/src/core/plugin.ts

@@ -268,6 +268,12 @@ export interface PluginContext {
 	providers: ResolvedProviders;
 	/** Every plugin's dashboard lines, in contribution order; throws NotLinkedError during setup. */
 	dashboard(): readonly string[];
+	/**
+	 * The credential the host's model login holds for a provider, such as `openai-codex`: the same
+	 * login the agents use. Resolves to `undefined` when the host has none for that provider, and
+	 * never throws for that. The value is a secret: keep it out of logs and error messages.
+	 */
+	apiKey(provider: string): Promise<string | undefined>;
 }
 
 export interface RoundtablePlugin {

package/src/core/speakers.ts

@@ -75,7 +75,10 @@ export interface SpeakerPolicy {
 	resolve(author: SpeakerFacts): Speaker | undefined;
 }
 
-/** Who holds one tier: user ids, role ids, and (for members) everyone. */
+/**
+ * Who holds one tier: user ids, role ids, or everyone. `everyone` works under any tier it is
+ * written in, so under `admins` it makes every author an admin.
+ */
 export interface TierMembers {
 	users?: readonly string[];
 	roles?: readonly string[];

package/src/core/testing/test-host.ts

@@ -38,6 +38,11 @@ export interface TestHostOptions {
 	plugins?: readonly RoundtablePlugin[];
 	/** The runtime every turn runs on; by default one that answers "" and builds no Pi session. */
 	runtime?: AgentRuntime;
+	/**
+	 * The credentials `context.apiKey` returns, by provider name; a provider not listed reads as
+	 * having none, whatever login the machine holds.
+	 */
+	apiKeys?: Readonly<Record<string, string>>;
 	/** What the stand-in Discord hands out. */
 	discord?: Partial<Pick<DiscordConnection, "agentChannels" | "ownerChannel">>;
 }
@@ -210,7 +215,15 @@ export async function testHost(
 		],
 	};
 	const defined = await defineRoundtable(config, { logger: silentLogger() });
-	const roundtable = new Roundtable(defined.options, defined.plugins);
+	const apiKeys = options.apiKeys ?? {};
+	const roundtable = new Roundtable(
+		{
+			...defined.options,
+			apiKey: async (provider) =>
+				Object.hasOwn(apiKeys, provider) ? apiKeys[provider] : undefined,
+		},
+		defined.plugins,
+	);
 	await roundtable.run();
 	if (!captured) throw new Error("the probe was not set up");
 	const context = captured;

package/src/core/tool-set.snapshot.json

@@ -102,6 +102,7 @@
 				"skill_group_delete",
 				"skill_group_set",
 				"skill_link",
+				"skill_list",
 				"skill_unlink",
 				"skill_update"
 			],
@@ -125,6 +126,7 @@
 				"skill_group_delete",
 				"skill_group_set",
 				"skill_link",
+				"skill_list",
 				"skill_unlink",
 				"skill_update",
 				"write"
@@ -187,6 +189,7 @@
 				"skill_group_delete",
 				"skill_group_set",
 				"skill_link",
+				"skill_list",
 				"skill_unlink",
 				"skill_update"
 			],
@@ -209,6 +212,7 @@
 				"skill_group_delete",
 				"skill_group_set",
 				"skill_link",
+				"skill_list",
 				"skill_unlink",
 				"skill_update",
 				"write"
@@ -280,6 +284,7 @@
 		"skill_group_delete": "admin",
 		"skill_group_set": "admin",
 		"skill_link": "admin",
+		"skill_list": "member",
 		"skill_unlink": "admin",
 		"skill_update": "admin",
 		"web_search": "member",

package/src/testing.ts

@@ -174,6 +174,11 @@ export interface TestPluginOptions {
 	conversations?: Partial<ConversationPort>;
 	/** Replaces `context.turns`, which by default runs turns over the runtime and the surfaces. */
 	turns?: ConversationTurns;
+	/**
+	 * The credentials `context.apiKey` returns, by provider name; a provider not listed reads as
+	 * having none, as on a host that is not logged in to it.
+	 */
+	apiKeys?: Readonly<Record<string, string>>;
 	/** How long the router holds a bare forward for the message that follows it; the host option `conversations.forwardJoinMs`. */
 	forwardJoinMs?: number;
 }
@@ -414,6 +419,10 @@ export async function testPlugin(
 		},
 		providers,
 		dashboard: () => (linked ? registry.dashboard : unlinked("dashboard")),
+		apiKey: async (provider) =>
+			Object.hasOwn(options.apiKeys ?? {}, provider)
+				? options.apiKeys?.[provider]
+				: undefined,
 	};
 	const registry = await collectContributions(
 		[plugin],

package/templates/agents.ts

@@ -1,5 +1,8 @@
 import type { AgentSeed } from "pi-roundtable";
 
+// Ids come from .env, which Bun loads on its own.
+const env = (name: string): string => process.env[name] ?? "";
+
 // The first team. An agent that is already stored is never overwritten, so edit agents in Discord afterwards.
 export const agents: AgentSeed[] = [
 	{
@@ -8,5 +11,7 @@ export const agents: AgentSeed[] = [
 		prompt:
 			"You are Guide, a friendly assistant. Answer briefly and ask when a request is unclear.",
 		avatarPrompt: "A friendly lighthouse keeper with a warm lantern",
+		// The agent in the entry channel is the coordinator: it answers there and can create the others.
+		channelId: env("DISCORD_ENTRY_CHANNEL_ID"),
 	},
 ];

package/templates/official/codex-images/plugin.test.ts.tmpl

@@ -0,0 +1,118 @@
+import { expect, test } from "bun:test";
+import { PluginError } from "pi-roundtable";
+import { testPlugin } from "pi-roundtable/testing";
+import {
+	type CodexFetch,
+	codexImages,
+	createCodexImages,
+	ImageNotGeneratedError,
+} from "./codex-images.ts";
+
+/** A login token shaped like the real one: a JWT whose claims name the ChatGPT account. */
+function token(account: string): string {
+	const claims = {
+		"https://api.openai.com/auth": { chatgpt_account_id: account },
+	};
+	return `header.${Buffer.from(JSON.stringify(claims)).toString("base64url")}.signature`;
+}
+
+const PNG = Uint8Array.from([0x89, 0x50, 0x4e, 0x47]);
+
+/** A server-sent event stream of the given events. */
+function stream(...events: unknown[]): Response {
+	const text = events
+		.map((event) => `data: ${JSON.stringify(event)}\n\n`)
+		.join("");
+	return new Response(text, {
+		headers: { "content-type": "text/event-stream" },
+	});
+}
+
+const drawn = (result: string, status = "completed") => ({
+	type: "response.output_item.done",
+	item: { type: "image_generation_call", status, result },
+});
+
+const completed = { type: "response.completed", response: { output: [] } };
+
+/** The plugin over a fake network that answers every request with `answer`, recording the requests. */
+function over(answer: () => Response) {
+	const requests: { url: string; init: RequestInit }[] = [];
+	const fetch: CodexFetch = async (url, init) => {
+		requests.push({ url, init });
+		return answer();
+	};
+	return { plugin: createCodexImages({ fetch }), requests };
+}
+
+test("codex-images fills the images slot with the image Codex returns", async () => {
+	const secret = token("acct-1");
+	const { plugin, requests } = over(() =>
+		stream(drawn(Buffer.from(PNG).toString("base64")), completed),
+	);
+	const harness = await testPlugin(plugin, {
+		apiKeys: { "openai-codex": secret },
+	});
+	const image = await plugin.providers?.images?.("a fox", [
+		{ data: "AAAA", mimeType: "image/png" },
+	]);
+	expect([...(image ?? [])]).toEqual([...PNG]);
+	const [request] = requests;
+	expect(request?.url).toBe("https://chatgpt.com/backend-api/codex/responses");
+	const headers = request?.init.headers as Record<string, string>;
+	expect(headers.authorization).toBe(`Bearer ${secret}`);
+	expect(headers["chatgpt-account-id"]).toBe("acct-1");
+	const body = JSON.parse(String(request?.init.body));
+	expect(body.tools).toEqual([
+		{ type: "image_generation", output_format: "png" },
+	]);
+	expect(body.input[0].content).toEqual([
+		{ type: "input_text", text: "a fox" },
+		{ type: "input_image", image_url: "data:image/png;base64,AAAA" },
+	]);
+	await harness.stop();
+});
+
+test("codex-images says so when Codex runs the tool and returns no image", async () => {
+	const refused = over(() => stream(drawn("", "failed"), completed));
+	const harness = await testPlugin(refused.plugin, {
+		apiKeys: { "openai-codex": token("acct-1") },
+	});
+	await expect(refused.plugin.providers?.images?.("a fox", [])).rejects.toThrow(
+		ImageNotGeneratedError,
+	);
+	await harness.stop();
+	const silent = over(() => stream(completed));
+	const quiet = await testPlugin(silent.plugin, {
+		apiKeys: { "openai-codex": token("acct-1") },
+	});
+	await expect(silent.plugin.providers?.images?.("a fox", [])).rejects.toThrow(
+		"Codex answered without an image",
+	);
+	await quiet.stop();
+});
+
+test("codex-images reports an HTTP error with its status, and never the token", async () => {
+	const secret = token("acct-1");
+	const { plugin } = over(() => new Response("rate limited", { status: 429 }));
+	const harness = await testPlugin(plugin, {
+		apiKeys: { "openai-codex": secret },
+	});
+	const failure = await plugin.providers?.images?.("a fox", []).then(
+		() => undefined,
+		(error: Error) => error,
+	);
+	expect(failure?.message).toBe("Codex answered 429: rate limited");
+	expect(failure?.message).not.toContain(secret);
+	await harness.stop();
+});
+
+test("codex-images refuses to start without an openai-codex login", async () => {
+	const failure = await testPlugin(codexImages).then(
+		() => undefined,
+		(error: unknown) => error,
+	);
+	expect(failure).toBeInstanceOf(PluginError);
+	expect((failure as PluginError).message).toContain("openai-codex");
+	expect((failure as PluginError).message).toContain("Log in");
+});

package/templates/official/codex-images/plugin.ts

@@ -0,0 +1,223 @@
+// Warning: this plugin uses ChatGPT's undocumented Codex backend, signed in with the owner's own
+// ChatGPT subscription (the `openai-codex` login), to draw images. OpenAI has not published it
+// as an API, so it can stop working without notice, and OpenAI's terms for the subscription
+// apply to it. Use it only where you accept that risk.
+
+import { definePlugin, PluginError, type ReferenceImage } from "pi-roundtable";
+
+const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
+/** The Pi provider whose login pays for the images. */
+const CODEX_PROVIDER = "openai-codex";
+/** Routes the Codex request; the backend picks the image model itself. */
+const CODEX_MODEL = "gpt-6-sol";
+const JWT_CLAIM_PATH = "https://api.openai.com/auth";
+const REQUEST_TIMEOUT_MS = 5 * 60_000;
+const MAX_IMAGE_BYTES = 32 * 1024 * 1024;
+const MAX_IMAGE_BASE64 = Math.ceil(MAX_IMAGE_BYTES / 3) * 4;
+
+/**
+ * Codex ran the image tool but returned no image, usually because it refused the prompt.
+ * Asking again with the same prompt fails again.
+ */
+export class ImageNotGeneratedError extends Error {
+	override name = "ImageNotGeneratedError";
+}
+
+/** The part of `fetch` the plugin uses, so a test can stand in for the network. */
+export type CodexFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+export interface CodexImagesOptions {
+	/** The request function; default the global `fetch`. */
+	fetch?: CodexFetch;
+	/** The model that routes the request; default `gpt-6-sol`. */
+	model?: string;
+}
+
+/** The ChatGPT account the login token belongs to, from the token's claims. */
+function chatGptAccountId(token: string): string {
+	const [, payload] = token.split(".");
+	if (!payload) throw new Error("the Codex token is not a JWT");
+	let claims: Record<string, unknown>;
+	try {
+		claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+	} catch {
+		throw new Error("the Codex token's claims are not JSON");
+	}
+	const auth = claims[JWT_CLAIM_PATH] as
+		| { chatgpt_account_id?: unknown }
+		| undefined;
+	const id = auth?.chatgpt_account_id;
+	if (typeof id !== "string" || !id)
+		throw new Error("the Codex token has no ChatGPT account");
+	return id;
+}
+
+function object(value: unknown): Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
+
+/** The one image an `image_generation_call` item carries; anything else is not an image. */
+function imageOf(value: unknown): Uint8Array | undefined {
+	const item = object(value);
+	if (item.type !== "image_generation_call") return undefined;
+	if (
+		item.status !== "completed" ||
+		typeof item.result !== "string" ||
+		!item.result
+	) {
+		const { result: _result, ...detail } = item;
+		throw new ImageNotGeneratedError(
+			`Codex image generation did not complete (status ${String(item.status)}): ${JSON.stringify(detail).slice(0, 300)}`,
+		);
+	}
+	if (item.result.length > MAX_IMAGE_BASE64)
+		throw new Error("the image exceeds 32 MiB");
+	return new Uint8Array(Buffer.from(item.result, "base64"));
+}
+
+/** The frames of a server-sent event stream: the text between blank lines. */
+async function* frames(
+	body: ReadableStream<Uint8Array>,
+): AsyncGenerator<string> {
+	const decoder = new TextDecoder();
+	let buffer = "";
+	for await (const chunk of body) {
+		buffer += decoder.decode(chunk, { stream: true });
+		let match = /\r?\n\r?\n/.exec(buffer);
+		while (match) {
+			yield buffer.slice(0, match.index);
+			buffer = buffer.slice(match.index + match[0].length);
+			match = /\r?\n\r?\n/.exec(buffer);
+		}
+	}
+	if (buffer.trim()) yield buffer;
+}
+
+/** The event a frame carries, or undefined for a frame without data. */
+function eventOf(frame: string): Record<string, unknown> | undefined {
+	const data = frame
+		.split(/\r?\n/)
+		.flatMap((line) => (line.startsWith("data:") ? [line.slice(5).trim()] : []))
+		.join("\n");
+	if (!data || data === "[DONE]") return undefined;
+	try {
+		return object(JSON.parse(data));
+	} catch {
+		throw new Error(`Codex sent a malformed event: ${data.slice(0, 200)}`);
+	}
+}
+
+/** Reads the events until the response completes, and returns its one image. */
+async function parseImageStream(response: Response): Promise<Uint8Array> {
+	if (!response.body) throw new Error("Codex returned no body");
+	let image: Uint8Array | undefined;
+	for await (const frame of frames(response.body)) {
+		const event = eventOf(frame);
+		switch (event?.type) {
+			case "error":
+			case "response.failed": {
+				const error = object(object(event.response).error ?? event.error);
+				throw new Error(
+					`Codex failed: ${String(error.message ?? error.code ?? "unknown error")}`,
+				);
+			}
+			case "response.incomplete":
+				throw new Error("the Codex response was incomplete");
+			case "response.output_item.done":
+				image ??= imageOf(event.item);
+				break;
+			case "response.completed": {
+				const output = object(event.response).output;
+				if (Array.isArray(output))
+					for (const item of output) image ??= imageOf(item);
+				if (!image)
+					throw new ImageNotGeneratedError("Codex answered without an image");
+				return image;
+			}
+			default:
+				break;
+		}
+	}
+	throw new Error("the Codex stream ended before completion");
+}
+
+async function generateImage(
+	prompt: string,
+	references: readonly ReferenceImage[],
+	token: string,
+	model: string,
+	fetchImpl: CodexFetch,
+): Promise<Uint8Array> {
+	const response = await fetchImpl(CODEX_RESPONSES_URL, {
+		method: "POST",
+		redirect: "error",
+		signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+		headers: {
+			authorization: `Bearer ${token}`,
+			"chatgpt-account-id": chatGptAccountId(token),
+			originator: "pi",
+			"openai-beta": "responses=experimental",
+			accept: "text/event-stream",
+			"content-type": "application/json",
+		},
+		body: JSON.stringify({
+			model,
+			store: false,
+			stream: true,
+			instructions:
+				"You are generating bitmap image assets. For this request, call the image_generation tool exactly once. Do not answer with only text unless image generation is unavailable.",
+			input: [
+				{
+					role: "user",
+					content: [
+						{ type: "input_text", text: prompt },
+						...references.map((image) => ({
+							type: "input_image",
+							image_url: `data:${image.mimeType};base64,${image.data}`,
+						})),
+					],
+				},
+			],
+			tools: [{ type: "image_generation", output_format: "png" }],
+			tool_choice: "auto",
+			parallel_tool_calls: false,
+			text: { verbosity: "low" },
+		}),
+	});
+	if (!response.ok) {
+		const detail = (await response.text()).slice(0, 300);
+		throw new Error(`Codex answered ${response.status}: ${detail}`);
+	}
+	return parseImageStream(response);
+}
+
+const NO_LOGIN = `the host has no login for ${CODEX_PROVIDER}, the provider that pays for the images. Log in to the ${CODEX_PROVIDER} provider with Pi so the agent directory's auth.json holds it, or remove this plugin.`;
+
+/** The plugin, with its request function and model replaceable for a test. */
+export function createCodexImages(options: CodexImagesOptions = {}) {
+	const { fetch: fetchImpl = fetch, model = CODEX_MODEL } = options;
+	let apiKey: ((provider: string) => Promise<string | undefined>) | undefined;
+	// The login refreshes its token, so each image reads it again instead of keeping the first.
+	const token = async (): Promise<string> => {
+		const value = await apiKey?.(CODEX_PROVIDER);
+		if (!value) throw new PluginError(`plugin codex-images: ${NO_LOGIN}`);
+		return value;
+	};
+	return definePlugin({
+		name: "codex-images",
+		providers: {
+			// The images slot draws an agent's avatar from a prompt and reference pictures.
+			images: async (prompt, references) =>
+				generateImage(prompt, references, await token(), model, fetchImpl),
+		},
+		async setup(context) {
+			apiKey = context.apiKey;
+			await token();
+			return {};
+		},
+	});
+}
+
+export const codexImages = createCodexImages();

package/templates/official/dice/plugin.test.ts.tmpl

@@ -0,0 +1,105 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { createDice, dice, type Random, roll } from "./dice.ts";
+
+/** A random source that answers with the faces given, as `[face, sides]` for each die in turn. */
+function dieFaces(...rolled: [face: number, sides: number][]): Random {
+	const queue = rolled.map(([face, sides]) => (face - 1) / sides + 0.0001);
+	return () => {
+		const next = queue.shift();
+		if (next === undefined)
+			throw new Error("the test rolled more dice than it gave");
+		return next;
+	};
+}
+
+/** The faces given, for dice that all have `sides` sides. */
+const faces = (sides: number, ...rolled: number[]): Random =>
+	dieFaces(...rolled.map((face): [number, number] => [face, sides]));
+
+test("a die rolls from 1 to its sides, and a number adds itself", () => {
+	expect(roll("2d6+3", faces(6, 3, 5))).toBe("2d6+3: [3, 5] + 3 = 11");
+	expect(roll("d20", faces(20, 20))).toBe("d20: [20] = 20");
+	expect(roll(" 1D4 ", faces(4, 1))).toBe("1D4: [1] = 1");
+});
+
+test("several groups add and subtract in order", () => {
+	expect(roll("2d6-1d4+2", dieFaces([4, 6], [2, 6], [1, 4]))).toBe(
+		"2d6-1d4+2: [4, 2] - [1] + 2 = 7",
+	);
+	expect(roll("-d6", faces(6, 2))).toBe("-d6: -[2] = -2");
+});
+
+test("keep and drop rules remove dice and show them in parentheses", () => {
+	const six = (...rolled: number[]) => faces(6, ...rolled);
+	expect(roll("4d6k3", six(5, 1, 6, 3))).toBe("4d6k3: [5, (1), 6, 3] = 14");
+	expect(roll("4d6kh3", six(5, 1, 6, 3))).toBe("4d6kh3: [5, (1), 6, 3] = 14");
+	expect(roll("4d6kl1", six(5, 1, 6, 3))).toBe(
+		"4d6kl1: [(5), 1, (6), (3)] = 1",
+	);
+	expect(roll("4d6d1", six(5, 1, 6, 3))).toBe("4d6d1: [5, (1), 6, 3] = 14");
+	expect(roll("4d6dl1", six(5, 1, 6, 3))).toBe("4d6dl1: [5, (1), 6, 3] = 14");
+	expect(roll("4d6dh1", six(5, 1, 6, 3))).toBe("4d6dh1: [5, 1, (6), 3] = 9");
+});
+
+test("fate dice add -1, 0, and +1 and default to four", () => {
+	const random = (() => {
+		const queue = [0.1, 0.5, 0.9, 0.9];
+		return () => queue.shift() ?? 0;
+	})();
+	expect(roll("dF", random)).toBe("dF: [-, 0, +, +] = 1");
+});
+
+test("a bad expression is refused with what to fix", () => {
+	for (const bad of [
+		"",
+		"   ",
+		"abc",
+		"2d",
+		"d1",
+		"0d6",
+		"2d6+",
+		"2d6++1",
+		"2d6 d4",
+		"4d6k4",
+		"4d6k0",
+		"4d6d9",
+		"1d6x",
+	])
+		expect(() => roll(bad, () => 0.5)).toThrow("Write an expression such as");
+});
+
+test("the caps on dice, sides, and length are refused", () => {
+	expect(() => roll("101d6", () => 0.5)).toThrow("more than 100 dice");
+	expect(() => roll("60d6+60d6", () => 0.5)).toThrow(
+		"more than 100 dice in all",
+	);
+	expect(() => roll("1d1001", () => 0.5)).toThrow("between 2 and 1000 sides");
+	expect(() => roll("d6+1000001", () => 0.5)).toThrow("is over 1000000");
+	expect(() => roll(`1+${"1+".repeat(120)}1`, () => 0.5)).toThrow(
+		"over 200 characters",
+	);
+	expect(roll("100d2", () => 0.99)).toContain("= 200");
+	expect(roll("1d1000", () => 0.9999)).toBe("1d1000: [1000] = 1000");
+});
+
+test("the roll_dice tool is for members and answers a bad expression as text", async () => {
+	const harness = await testPlugin(createDice(faces(6, 3, 5)));
+	expect(harness.tools).toEqual(["roll_dice"]);
+	expect(harness.tiers.minTier("roll_dice")).toBe("member");
+	expect(await harness.runTool("roll_dice", { expression: "2d6+3" })).toBe(
+		"2d6+3: [3, 5] + 3 = 11",
+	);
+	expect(await harness.runTool("roll_dice", { expression: "nope" })).toContain(
+		"is not a dice term",
+	);
+	await harness.stop();
+});
+
+test("the ready-made plugin rolls with a real random source", async () => {
+	const harness = await testPlugin(dice);
+	expect(await harness.runTool("roll_dice", { expression: "d6" })).toMatch(
+		/^d6: \[[1-6]\] = [1-6]$/,
+	);
+	await harness.stop();
+});

package/templates/official/dice/plugin.ts

@@ -0,0 +1,195 @@
+import { definePlugin, defineTool, ToolRefusal } from "pi-roundtable";
+import { Type } from "typebox";
+
+/** Returns a number from 0 up to, not including, 1, like `Math.random`. */
+export type Random = () => number;
+
+const MAX_DICE = 100;
+const MAX_SIDES = 1000;
+const MAX_LENGTH = 200;
+const MAX_MODIFIER = 1_000_000;
+const FATE_DEFAULT = 4;
+
+type KeepDrop = "k" | "kh" | "kl" | "d" | "dh" | "dl";
+
+const TERM = /^(\d*)d(?:(f)|(\d+)(?:(kh|kl|dh|dl|k|d)(\d+))?)$/;
+
+const refuse = (problem: string): never => {
+	throw new ToolRefusal(
+		`${problem} Write an expression such as 2d6+3, d20, 4d6k3, or 4dF.`,
+	);
+};
+
+/** The indexes a keep or drop rule removes; `rolls` has more than `n` dice. */
+function removed(
+	rolls: readonly number[],
+	rule: KeepDrop,
+	n: number,
+): number[] {
+	const ascending = rolls
+		.map((value, index) => ({ value, index }))
+		.sort((a, b) => a.value - b.value || a.index - b.index)
+		.map((die) => die.index);
+	switch (rule) {
+		case "k":
+		case "kh":
+			return ascending.slice(0, rolls.length - n);
+		case "kl":
+			return ascending.slice(n);
+		case "d":
+		case "dl":
+			return ascending.slice(0, n);
+		case "dh":
+			return ascending.slice(rolls.length - n);
+		default:
+			return rule satisfies never;
+	}
+}
+
+/** One term rolled: what it shows, and what it adds before its sign applies. */
+interface Rolled {
+	shown: string;
+	value: number;
+	dice: number;
+}
+
+/** A plain number term. */
+function rollNumber(term: string): Rolled {
+	if (term.length > 7 || Number(term) > MAX_MODIFIER)
+		return refuse(`The number ${term} is over ${MAX_MODIFIER}.`);
+	return { shown: String(Number(term)), value: Number(term), dice: 0 };
+}
+
+/** How a fate die shows: + for 1, - for -1, and 0. */
+function fateSymbol(face: number): string {
+	if (face > 0) return "+";
+	if (face < 0) return "-";
+	return "0";
+}
+
+/** `count` fate dice, each one of -1, 0, or +1. */
+function rollFate(count: number, random: Random): Rolled {
+	const faces = Array.from(
+		{ length: count },
+		() => Math.floor(random() * 3) - 1,
+	);
+	const symbols = faces.map(fateSymbol);
+	return {
+		shown: `[${symbols.join(", ")}]`,
+		value: faces.reduce((sum, face) => sum + face, 0),
+		dice: count,
+	};
+}
+
+/** `count` dice of `sides` sides, with an optional keep or drop rule that removes some of them. */
+function rollPool(
+	term: string,
+	count: number,
+	sides: number,
+	rule: { kind: KeepDrop; n: number } | undefined,
+	random: Random,
+): Rolled {
+	if (sides < 2 || sides > MAX_SIDES)
+		return refuse(`"${term}" needs between 2 and ${MAX_SIDES} sides.`);
+	const rolls = Array.from(
+		{ length: count },
+		() => Math.floor(random() * sides) + 1,
+	);
+	if (rule && (rule.n < 1 || rule.n >= count))
+		return refuse(
+			`"${term}" must keep or drop at least 1 and fewer than ${count} dice.`,
+		);
+	const dropped = new Set(rule ? removed(rolls, rule.kind, rule.n) : []);
+	const shown = rolls.map((value, index) =>
+		dropped.has(index) ? `(${value})` : String(value),
+	);
+	return {
+		shown: `[${shown.join(", ")}]`,
+		value: rolls.reduce(
+			(sum, value, index) => sum + (dropped.has(index) ? 0 : value),
+			0,
+		),
+		dice: count,
+	};
+}
+
+/** How many dice a term rolls: the count it writes, else 4 for fate dice and 1 for the rest. */
+function diceCount(countText: string | undefined, fate: string | undefined) {
+	if (countText) return Number(countText);
+	return fate ? FATE_DEFAULT : 1;
+}
+
+function rollTerm(term: string, random: Random): Rolled {
+	if (/^\d+$/.test(term)) return rollNumber(term);
+	const match = TERM.exec(term);
+	if (!match) return refuse(`"${term}" is not a dice term.`);
+	const [, countText, fate, sidesText, rule, nText] = match;
+	const count = diceCount(countText, fate);
+	if (count < 1) return refuse(`"${term}" rolls no dice.`);
+	if (count > MAX_DICE)
+		return refuse(`"${term}" rolls more than ${MAX_DICE} dice.`);
+	if (fate) return rollFate(count, random);
+	return rollPool(
+		term,
+		count,
+		Number(sidesText),
+		rule ? { kind: rule as KeepDrop, n: Number(nText) } : undefined,
+		random,
+	);
+}
+
+/**
+ * Rolls an expression of dice terms and numbers joined by `+` and `-`, and writes the result as
+ * text such as `2d6+3: [3, 5] + 3 = 11`. A term is `NdS`, an optional keep or drop rule
+ * (`k`/`kh` keep the highest, `kl` the lowest, `d`/`dl` drop the lowest, `dh` the highest, each
+ * with a count), `NdF` fate dice (default 4), or a whole number. Dropped dice show in parentheses.
+ * An invalid or oversized expression throws a `ToolRefusal` that says what to fix.
+ */
+export function roll(expression: string, random: Random = Math.random): string {
+	const compact = expression.replace(/\s+/g, "");
+	if (!compact) return refuse("The expression is empty.");
+	if (compact.length > MAX_LENGTH)
+		return refuse(`The expression is over ${MAX_LENGTH} characters.`);
+	const parts = [...compact.toLowerCase().matchAll(/([+-]?)([^+-]+)/g)];
+	if (parts.map((part) => part[0]).join("") !== compact.toLowerCase())
+		return refuse(`"${compact}" is not a sum of dice and numbers.`);
+	let total = 0;
+	let dice = 0;
+	let line = "";
+	for (const [index, [, sign = "", term = ""]] of parts.entries()) {
+		if (index > 0 && !sign)
+			return refuse(`"${compact}" is not a sum of dice and numbers.`);
+		const rolled = rollTerm(term, random);
+		dice += rolled.dice;
+		if (dice > MAX_DICE)
+			return refuse(`The expression rolls more than ${MAX_DICE} dice in all.`);
+		total += sign === "-" ? -rolled.value : rolled.value;
+		const lead = sign === "-" ? "-" : "";
+		line += index === 0 ? `${lead}${rolled.shown}` : ` ${sign} ${rolled.shown}`;
+	}
+	return `${compact}: ${line} = ${total}`;
+}
+
+/** The plugin, with the random source replaceable for a test. */
+export function createDice(random: Random = Math.random) {
+	return definePlugin({
+		name: "dice",
+		setup: () => ({
+			tools: [
+				defineTool({
+					name: "roll_dice",
+					description: `Roll dice and report each die and the total. The expression joins terms with + and -: NdS rolls N dice of S sides (2d6, d20), a count after k/kh keeps the highest dice (4d6k3), kl keeps the lowest, d/dl drops the lowest, dh drops the highest, NdF rolls N fate dice (default 4), and a plain number adds itself (2d6+1d4-1). At most ${MAX_DICE} dice in all and ${MAX_SIDES} sides per die. Dropped dice show in parentheses.`,
+					parameters: Type.Object({
+						expression: Type.String({
+							description: "For example 2d6+3 or 4d6k3",
+						}),
+					}),
+					minTier: "member",
+					run: ({ expression }) => roll(expression, random),
+				}),
+			],
+		}),
+	});
+}
+
+export const dice = createDice();