pi-roundtable 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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

@@ -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` |
@@ -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.4.0",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",

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/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/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/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,215 @@
+// 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(".")[1];
+	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>)
+		: {};
+}
+
+/** Reads the server-sent 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;
+	let completed = false;
+	const take = (value: unknown) => {
+		const item = object(value);
+		if (item.type !== "image_generation_call" || image) return;
+		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");
+		image = new Uint8Array(Buffer.from(item.result, "base64"));
+	};
+	const handle = (frame: string) => {
+		const data = frame
+			.split(/\r?\n/)
+			.filter((line) => line.startsWith("data:"))
+			.map((line) => line.slice(5).trim())
+			.join("\n");
+		if (!data || data === "[DONE]") return;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(data);
+		} catch {
+			throw new Error(`Codex sent a malformed event: ${data.slice(0, 200)}`);
+		}
+		const event = object(parsed);
+		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":
+				take(event.item);
+				break;
+			case "response.completed": {
+				const output = object(event.response).output;
+				if (!image && Array.isArray(output))
+					for (const item of output) take(item);
+				completed = true;
+				break;
+			}
+		}
+	};
+	const decoder = new TextDecoder();
+	let buffer = "";
+	for await (const chunk of response.body) {
+		buffer += decoder.decode(chunk, { stream: true });
+		let match = /\r?\n\r?\n/.exec(buffer);
+		while (match && !completed) {
+			handle(buffer.slice(0, match.index));
+			buffer = buffer.slice(match.index + match[0].length);
+			match = /\r?\n\r?\n/.exec(buffer);
+		}
+		if (completed) break;
+	}
+	if (!completed && buffer.trim()) handle(buffer);
+	if (!completed) throw new Error("the Codex stream ended before completion");
+	if (!image)
+		throw new ImageNotGeneratedError("Codex answered without an image");
+	return image;
+}
+
+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,166 @@
+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);
+	}
+}
+
+/** One term rolled: what it shows, and what it adds before its sign applies. */
+interface Rolled {
+	shown: string;
+	value: number;
+	dice: number;
+}
+
+function rollTerm(term: string, random: Random): Rolled {
+	if (/^\d+$/.test(term)) {
+		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 };
+	}
+	const match = TERM.exec(term);
+	if (!match) return refuse(`"${term}" is not a dice term.`);
+	const [, countText, fate, sidesText, rule, nText] = match;
+	const count = countText ? Number(countText) : fate ? FATE_DEFAULT : 1;
+	if (count < 1) return refuse(`"${term}" rolls no dice.`);
+	if (count > MAX_DICE)
+		return refuse(`"${term}" rolls more than ${MAX_DICE} dice.`);
+	if (fate) {
+		const faces = Array.from(
+			{ length: count },
+			() => Math.floor(random() * 3) - 1,
+		);
+		const symbols = faces.map((face) =>
+			face > 0 ? "+" : face < 0 ? "-" : "0",
+		);
+		return {
+			shown: `[${symbols.join(", ")}]`,
+			value: faces.reduce((sum, face) => sum + face, 0),
+			dice: count,
+		};
+	}
+	const sides = Number(sidesText);
+	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,
+	);
+	const dropped = new Set<number>();
+	if (rule) {
+		const n = Number(nText);
+		if (n < 1 || n >= count)
+			return refuse(
+				`"${term}" must keep or drop at least 1 and fewer than ${count} dice.`,
+			);
+		for (const index of removed(rolls, rule as KeepDrop, n)) dropped.add(index);
+	}
+	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,
+	};
+}
+
+/**
+ * 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;
+		line +=
+			index === 0
+				? `${sign === "-" ? "-" : ""}${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();