pi-roundtable 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.
+
+### Added
+
+- `RoundtablePlugin.requires`: the services a plugin reads with `get` in its setup. The host checks the list before any migration or setup and refuses a key no registered plugin provides, one a plugin registered after it provides, and one the plugin provides itself, naming the plugins and the fix.
+- `Services.lazy(KEY)`: a function that returns the service once every plugin is set up, for a plugin that needs a service of one registered after it. Calling it during setup throws a `NotLinkedError`; the host refuses to boot, naming the plugin, when no registered plugin provides the key. A plugin no longer has to keep a shared object that the later plugin fills in. `testPlugin` checks `requires` against the `services` option and answers `lazy` readers after setup.
+- `pi-roundtable/kit`: `packageDir`, the installed package's folder as Pi's `additionalExtensionPaths` takes it (`packageDir(name, import.meta.url)`; the second argument is the file the package is looked up from, so a host finds its own dependencies even when `pi-roundtable` is linked apart from them), and `serveUnix`, an HTTP server on a unix socket without Bun's idle timeout (`serveUnix(socketPath, fetch, { error? })`). They are the core's own, so a worker process of a host no longer copies them.
+- `pi-roundtable/testing`: `partial`, a typed stand-in (`partial<Port>({ ... })`) with only the members the test gives, which names any other member it is asked for; `recordingLogger` with `RecordingLogger` and `RecordedLog`, a logger whose `lines` keep each call's level, fields, and message. Neither needs an `as unknown as` cast.
+- A guide section on developing the core and a host together with `bun link`.
+
+### Changed
+
+- `pi-web-access` is a peer dependency (`>=0.35.0 <0.36.0`) instead of a dependency, and a development dependency at 0.35.0. `bun add pi-roundtable` still installs it; a host that depends on its own build of it now has one copy, with no `overrides` entry. A project without it fails at the `modules` plugin's setup with a `PluginError` that names the command to run.
+- `pi-roundtable/kit` and `pi-roundtable/discord` are versioned like the main entry: before 1.0, a breaking change to an exported name comes in a minor release and is listed in the changelog. The signature report already guarded every name; the "unstable, not covered by semver" label is gone.
+- `Services` has a new member, `lazy`; a hand-written `Services` (only the core's own and tests') needs it.
+- The guide's mention of the first consumer by name is gone.
+
 ## [0.2.1] - 2026-10-01
 
 ### Added

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
@@ -111,7 +111,7 @@ test("hello greets", async () => {
 
 The [plugin guide](docs/plugins.md) explains every part a plugin can add (tools, prompt sections, agents, events, services, migrations, providers, slash commands, HTTP routes, and more), the order things start and stop in, and every startup error with its fix.
 Its examples live in [`examples/`](examples), and the test suite runs each of them.
-`pi-roundtable/kit` supplies claim, tool and presentation helpers and type-only names for the context’s existing services, and `pi-roundtable/discord` supplies the slash-command registrar, owner-command and panel helpers, and the agent panel, and is the entry that names discord.js types (`pi-roundtable/testing` names a few, through `testHost`'s composed commands); both are unstable before 1.0 and not covered by semver.
+`pi-roundtable/kit` supplies claim, tool and presentation helpers and type-only names for the context’s existing services, and `pi-roundtable/discord` supplies the slash-command registrar, owner-command and panel helpers, and the agent panel, and is the entry that names discord.js types (`pi-roundtable/testing` names a few, through `testHost`'s composed commands); both are versioned like the main entry: before 1.0 a breaking change comes in a minor release and is listed in the changelog.
 
 ## Settings
 

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` 時，它會先讓進行中的工作完成再停止。
 
 ## 外掛
@@ -111,7 +111,7 @@ test("hello greets", async () => {
 
 [外掛指南](docs/plugins.md)（英文）說明外掛能新增的每個部分（工具、提示詞區段、智慧體、事件、服務、migration、provider、斜線指令、HTTP 路由等等）、啟動與停止的順序，以及每一種啟動錯誤和它的修正方式。
 指南裡的範例放在 [`examples/`](examples)，測試套件會執行每一個範例。
-`pi-roundtable/kit` 提供頻道認領（claim）、工具與呈現用的輔助函式，以及 context 現有服務的純型別名稱；`pi-roundtable/discord` 提供斜線指令註冊器、擁有者指令與面板的輔助函式，以及智慧體面板，是會用到 discord.js 型別的入口（`pi-roundtable/testing` 也透過 `testHost` 組合出的指令用到少數幾個）。這兩個入口在 1.0 之前都不穩定，不受語意化版本（semver）保證。
+`pi-roundtable/kit` 提供頻道認領（claim）、工具與呈現用的輔助函式，以及 context 現有服務的純型別名稱；`pi-roundtable/discord` 提供斜線指令註冊器、擁有者指令與面板的輔助函式，以及智慧體面板，是會用到 discord.js 型別的入口（`pi-roundtable/testing` 也透過 `testHost` 組合出的指令用到少數幾個）。這兩個入口的版本規則與主入口相同：1.0 之前，不相容的變更會放在次版本（minor）發佈，並列在變更記錄中。
 
 ## 設定
 

package/docs/plugins.md

@@ -33,13 +33,13 @@ Everything a plugin author needs comes from four entries, and nothing else can b
 |---|---|
 | `pi-roundtable` | `definePlugin`, `defineTool`, `defineRoundtable`, `ToolRefusal`, `PluginError`, `NotLinkedError`, `Roundtable`, and the types (`Tier`, `Speaker`, `Contribution`, `PluginContext`, and so on) |
 | `pi-roundtable/testing` | Fixtures for testing plugins, without Discord or a database unless the test explicitly opens one; `testHost` names a few discord.js types (`ComposedCommands`, `CommandGuard`, `InteractionModule`, `RootOption`) so a test can drive the composed slash commands |
-| `pi-roundtable/kit` | Unstable helpers for channel claims, tools, presentation, and naming existing core parts |
-| `pi-roundtable/discord` | Unstable, and the entry built on discord.js types: the `DISCORD` service (slash commands, the owner guard), owner-command and panel helpers, the agent panel, and the channel-operation tables |
+| `pi-roundtable/kit` | Helpers for channel claims, tools, presentation, worker processes, and naming existing core parts |
+| `pi-roundtable/discord` | The entry built on discord.js types: the `DISCORD` service (slash commands, the owner guard), owner-command and panel helpers, the agent panel, and the channel-operation tables |
 
 ### Advanced building blocks
 
 Start with the main entry and the context's built-in services.
-The kit is unstable before 1.0 and is not covered by semver.
+The kit and Discord entries are versioned like the main entry: before 1.0 a breaking change to any exported name comes in a minor release and is listed in the changelog, and a test compares every exported signature with a recorded report.
 Use `pi-roundtable/kit` for channel claims, tool and presentation helpers, and the types of the core's existing parts.
 Use `pi-roundtable/discord` for everything that touches Discord: slash commands, owner-command modules and panels, the agent panel, and the channel-operation tables.
 The main and kit entries name no discord.js type (a test checks their declarations), so a plugin that does not talk to Discord never depends on it.
@@ -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` |
@@ -127,10 +129,16 @@ A plugin lists the keys it provides in `provides` and provides each from `setup`
 |---|---|
 | `services.get(KEY)` | The service, or a `PluginError` that names the key and the plugin to register first when it is not provided yet |
 | `services.find(KEY)` | The service, or `undefined` when no registered plugin declares it, such as an addon that is off; it throws like `get` when a plugin declares it but has not set up yet, because that is order, not absence |
+| `services.lazy(KEY)` | A function that returns the service once every plugin is set up, for a service whose plugin is registered after this one; call it from a service's `start`, a handler, or another callback that runs after startup, since calling it during setup throws a `NotLinkedError`. The host refuses to boot, naming your plugin, when no registered plugin provides the key |
 | `services.provide(KEY, value)` | Only from setup, only for a key the plugin declares in `provides`, once per key |
 
 A plugin that declares a key and does not provide it is refused when its `setup` returns, and two plugins that declare one key are refused before any setup.
 
+A plugin that reads a service with `get` during its setup lists the key in `requires`, so a wrong order is refused before any migration or setup, with both plugins named, and the plugin states what it needs in one place (`noteCounter` below).
+A key in `requires` must be provided by a plugin registered before this one.
+A service you read with `find` (an addon that may be off) stays out of `requires`.
+When the other plugin has to come after yours, because it reads what yours provides, read its service with `services.lazy` instead of keeping the object in a variable that the later plugin fills in (`earlyNoteReader` below).
+
 The built-in plugins provide these, from the main entry:
 
 | Key | Port | Provided by | What it is |
@@ -147,7 +155,7 @@ 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)).
 
 A plugin of yours shares a service the same way: the key is a constant you export, the port is an interface you export, and plugins registered after yours read it.
-A plugin registered before yours cannot, and says so: `service <id> is not provided yet; plugin <yours> provides it. Register plugin <yours> before plugin <reader>.`
+A plugin registered before yours cannot read it during its setup, and says so (it reads the service with `services.lazy` instead, from a callback that runs after startup): `service <id> is not provided yet; plugin <yours> provides it. Register plugin <yours> before plugin <reader>.`
 
 <!-- example: examples/shared-services.ts -->
 ```ts
@@ -195,6 +203,37 @@ export function noteReader(
 	});
 }
 
+/** A plugin that reads the service in `setup` lists it in `requires`: a wrong order stops the start, naming both plugins. */
+export function noteCounter(onCount: (count: number) => void) {
+	return definePlugin({
+		name: "note-counter",
+		requires: [NOTE_INDEX],
+		setup: ({ services }) => {
+			const index = services.get(NOTE_INDEX);
+			return {
+				services: [
+					{ name: "note-counter", start: () => onCount(index.all().length) },
+				],
+			};
+		},
+	});
+}
+
+/** A plugin registered before the notes reads them with `lazy`, from a callback that runs after startup. */
+export function earlyNoteReader(onNotes: (notes: readonly string[]) => void) {
+	return definePlugin({
+		name: "early-note-reader",
+		setup: ({ services }) => {
+			const index = services.lazy(NOTE_INDEX);
+			return {
+				services: [
+					{ name: "early-note-reader", start: () => onNotes(index().all()) },
+				],
+			};
+		},
+	});
+}
+
 /** A plugin that provides the same key and lists it in `replaces` takes the place of the one before it. */
 export function shoutingNotes() {
 	const stored: string[] = [];
@@ -1184,6 +1223,9 @@ export function alwaysOn(tools: () => string[]) {
 Names of npm packages, installed in your project (`bun add pi-web-access`), whose Pi extensions every conversation session loads.
 Two plugins that name the same package load it once.
 
+`pi-web-access` is also what the built-in delegation worker loads to search and read the web, so `pi-roundtable` lists it as a peer dependency (`>=0.35.0 <0.36.0`): `bun add pi-roundtable` installs it for you, and a project that depends on its own build of it, such as a fork, gets that one copy for both the worker and `piPackages`, with no `overrides` entry.
+A project that has none installed stops at the `modules` plugin's setup with a `PluginError` that names the command to run.
+
 <!-- example: examples/packages.ts -->
 ```ts
 import { definePlugin } from "pi-roundtable";
@@ -1682,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.
@@ -1716,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:
@@ -1724,6 +1787,9 @@ The harness supplies what the host would, so a claim or a background turn behave
 - Once `AGENTS` is given, its `approvals` is the real confirmation judge over `providers.judge` when you pass a judge, so a held action is approved or declined as the agent server decides.
 - Giving `AGENTS` a `team` puts the agent server's own claim in the router, for the `owner`, so the plugin's claims are tested against the agent channels as on a host; its `owner` background target comes with it.
 
+A plugin under test that lists a key in `requires` is refused unless the `services` option gives it (or the plugin provides it), the way the host refuses a key no plugin provides.
+A `services.lazy` reader answers once `testPlugin` returns, from the services you gave.
+
 A plugin that fills the `runtime` slot needs none of these for its own runtime: the harness builds it from the slot (with a silent logger, a one-owner identity, in-memory held actions, and one stand-in agent setting) and puts it under `AGENTS`'s `runtime`.
 
 A test for the tools example:
@@ -1763,6 +1829,8 @@ Use it only with your own store class in a gated database test and always close
 `useTestLocale()` resets the process-wide locale to English and time zone to UTC; call it after a test that changes either, not from a running plugin.
 `testPlugin`'s options take `env` (a partial `HostEnv`) for the `context.env` the plugin sees; it defaults to `en` and `UTC`.
 `OWNER_SPEAKER`, `fakeThreads`, and `silentLogger` supply neutral stand-ins for owner turns, dispatch threads, and logging.
+`recordingLogger()` is a logger that keeps what it is asked to write: its `lines` hold each call's `level`, `fields` (those of a `child` included), and `message`, for a test of what the code logs.
+`partial<Port>({ ... })` is a stand-in for a port that your code takes as an argument rather than reads from a service: it has the members you give and nothing else, and reading another member throws an error that names it, so the test needs no `as unknown as Port` cast.
 `fakeDiscord({ ownerId?, rootCommand? })` is the `DISCORD` service for a plugin that adds slash commands: give it as `services: [discord.service]`, read what the plugin added with `discord.added()`, and compose the tree Discord would get with `discord.compose()`.
 Only `commands` and `guard` are given; a plugin that reads another member of `DISCORD` in a test gives its own with `servicePair(DISCORD, { ... })`.
 
@@ -1775,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:
@@ -1827,7 +1896,7 @@ On `SIGTERM` or `SIGINT` the bot stops serving new work last:
 4. Services stop in the reverse of the order they started.
 5. The database pool closes.
 
-`shutdown()` returns the exit code, `0` or `1` when a listener, a service, or the pool failed to stop, and every call shares the one shutdown; only `listen()`, which the command line and Merlin call, exits the process with it.
+`shutdown()` returns the exit code, `0` or `1` when a listener, a service, or the pool failed to stop, and every call shares the one shutdown; only `listen()`, which the command line and a host's own entry point call, exits the process with it.
 
 ## Errors and their fixes
 
@@ -1901,6 +1970,10 @@ Your plugins always run after the built-ins, so the built-in keys show this only
 Pass what you need in the harness's `services` option, or test that part elsewhere.
 `find(KEY)` is `undefined` for a service nobody declares, in the host and in the harness.
 
+A key in `requires` is checked before any migration or setup, and a wrong order stops the start with `plugin <yours>: requires service <id>, which plugin <name> provides after it. Register plugin <name> before plugin <yours>, or read the service with services.lazy(KEY) from a callback that runs after startup.`
+Calling the function `services.lazy(KEY)` returned during setup throws `service <id> is read through lazy() once every plugin is set up. Call it from a service's start or from a handler, not during setup.`
+A `lazy` key that no registered plugin provides stops the start once every plugin is set up: `plugin <yours>: services.lazy reads service <id>, which no registered plugin provides.`
+
 ### A setup or a migration that throws
 
 ```text
@@ -1970,6 +2043,22 @@ These are existing compatibility limits, not flags the package overrides in your
 With `skipLibCheck: false`, the example consumer instead reports 97 dependency-declaration errors, so keep it enabled for this configuration.
 Discord-facing signatures, which are in `pi-roundtable/discord` and, for the composed slash commands, in `pi-roundtable/testing`, use the package's pinned `discord.js` types; use those compatible types for panel rows and interaction handlers. `discord.js` is a regular dependency of the package, so a project that imports either entry installs it with `pi-roundtable`.
 
+## Developing the core and a host together
+
+A host pins an exact `pi-roundtable` version, so a change to the core reaches it only after a release.
+To try a core change in a host first, link the checkout:
+
+```sh
+# in the pi-roundtable checkout
+bun link
+# in the host
+bun link pi-roundtable
+```
+
+The host then imports the checkout's source, so the core's edits show at once and the host's `bun run typecheck` and `bun test` run against them.
+A linked checkout resolves its own dependencies from its own `node_modules`, so a host's `overrides` do not reach it: a host that depends on its own build of `pi-web-access` has two copies while linked.
+When the change is done, release the core, set the host's `pi-roundtable` to the new exact version, and run `bun install` to replace the link with the published package; the host's checks run once more against what was published.
+
 ## Name-to-entry index
 
 Type-only exports require `import type` when `verbatimModuleSyntax` is enabled.
@@ -2160,6 +2249,10 @@ The source area files are not package subpaths.
 | `fakeThreads` | `pi-roundtable/testing` | value |
 | `openTestStore` | `pi-roundtable/testing` | value |
 | `servicePair` | `pi-roundtable/testing` | value |
+| `partial` | `pi-roundtable/testing` | value |
+| `recordingLogger` | `pi-roundtable/testing` | value |
+| `RecordingLogger` | `pi-roundtable/testing` | type |
+| `RecordedLog` | `pi-roundtable/testing` | type |
 | `silentLogger` | `pi-roundtable/testing` | value |
 | `testDatabaseUrl` | `pi-roundtable/testing` | value |
 | `testHost` | `pi-roundtable/testing` | value |
@@ -2204,6 +2297,8 @@ The source area files are not package subpaths.
 | `SCHEDULE_TOOLS` | `pi-roundtable/kit` | value |
 | `SHELL_TOOLS` | `pi-roundtable/kit` | value |
 | `SKILL_LIST_TOOL` | `pi-roundtable/kit` | value |
+| `packageDir` | `pi-roundtable/kit` | value |
+| `serveUnix` | `pi-roundtable/kit` | value |
 | `ScheduleToolContext` | `pi-roundtable/kit` | type |
 | `ScheduleToolName` | `pi-roundtable/kit` | type |
 | `ScheduleToolSpec` | `pi-roundtable/kit` | type |

package/examples/shared-services.test.ts

@@ -2,8 +2,10 @@ import { expect, test } from "bun:test";
 import { definePlugin, PluginError, Roundtable } from "pi-roundtable";
 import { servicePair, silentLogger, testPlugin } from "pi-roundtable/testing";
 import {
+	earlyNoteReader,
 	NOTE_INDEX,
 	type NoteIndex,
+	noteCounter,
 	noteReader,
 	notes,
 	shoutingNotes,
@@ -72,3 +74,29 @@ test("a provider that does not provide what it lists is refused after setup", as
 		}),
 	).rejects.toBeInstanceOf(PluginError);
 });
+
+test("a plugin that requires the service is refused when the notes come after it, before any setup", async () => {
+	const roundtable = new Roundtable({ logger: silentLogger() }, [
+		noteCounter(() => undefined),
+		notes(),
+	]);
+	await expect(roundtable.run()).rejects.toThrow(
+		"plugin note-counter: requires service my-notes.index, which plugin my-notes provides after it.",
+	);
+	await roundtable.shutdown("test");
+});
+
+test("a plugin that requires the service counts the notes written before startup", async () => {
+	const counts: number[] = [];
+	await withHost(
+		[notes(), writer, noteCounter((count) => counts.push(count))],
+		() => expect(counts).toEqual([1]),
+	);
+});
+
+test("a plugin registered before the notes reads them lazily, once the host started", async () => {
+	const seen: (readonly string[])[] = [];
+	await withHost([earlyNoteReader((list) => seen.push(list)), notes()], () =>
+		expect(seen).toEqual([[]]),
+	);
+});

package/examples/shared-services.ts

@@ -42,6 +42,37 @@ export function noteReader(
 	});
 }
 
+/** A plugin that reads the service in `setup` lists it in `requires`: a wrong order stops the start, naming both plugins. */
+export function noteCounter(onCount: (count: number) => void) {
+	return definePlugin({
+		name: "note-counter",
+		requires: [NOTE_INDEX],
+		setup: ({ services }) => {
+			const index = services.get(NOTE_INDEX);
+			return {
+				services: [
+					{ name: "note-counter", start: () => onCount(index.all().length) },
+				],
+			};
+		},
+	});
+}
+
+/** A plugin registered before the notes reads them with `lazy`, from a callback that runs after startup. */
+export function earlyNoteReader(onNotes: (notes: readonly string[]) => void) {
+	return definePlugin({
+		name: "early-note-reader",
+		setup: ({ services }) => {
+			const index = services.lazy(NOTE_INDEX);
+			return {
+				services: [
+					{ name: "early-note-reader", start: () => onNotes(index().all()) },
+				],
+			};
+		},
+	});
+}
+
 /** A plugin that provides the same key and lists it in `replaces` takes the place of the one before it. */
 export function shoutingNotes() {
 	const stored: string[] = [];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.2.1",
+	"version": "0.4.0",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",
@@ -50,14 +50,17 @@
 		"canvas": "3.2.3",
 		"discord.js": "14.27.0",
 		"pi-mcp-adapter": "2.37.0",
-		"pi-web-access": "0.35.0",
 		"pino": "10.3.1",
 		"typebox": "1.3.34",
 		"unpdf": "1.8.1"
 	},
+	"peerDependencies": {
+		"pi-web-access": ">=0.35.0 <0.36.0"
+	},
 	"devDependencies": {
 		"typescript": "7.0.2",
 		"@biomejs/biome": "2.5.14",
-		"@types/bun": "1.4.2"
+		"@types/bun": "1.4.2",
+		"pi-web-access": "0.35.0"
 	}
 }

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/contract/services.ts

@@ -37,6 +37,13 @@ export interface Services {
 	 * Throws like `get` when a plugin declares it but has not been set up yet: that is order, not absence.
 	 */
 	find<T>(key: ServiceKey<T>): T | undefined;
+	/**
+	 * A reader for a service whose plugin may be set up after this one: call it from a service's
+	 * `start`, a handler, or any callback that runs after startup, not during setup, where it throws
+	 * a NotLinkedError. The host checks before startup that a registered plugin provides the key and
+	 * refuses to boot with a PluginError naming this plugin when none does.
+	 */
+	lazy<T>(key: ServiceKey<T>): () => T;
 	/**
 	 * Provides a service the plugin declares in `provides`; only while the plugin's setup runs, and
 	 * once per key.

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. */
@@ -278,6 +283,7 @@ export class Roundtable {
 		// A plugin that replaces a service takes the place of the one that provided it.
 		this.#active = replaceServices(this.#plugins);
 		this.#services = new ServiceRegistry(this.#active);
+		this.#services.checkRequires();
 		const providers = resolveProviders(this.#active, this.#options.judgeModel);
 		await this.#migrate();
 		this.#registry = await collectContributions(
@@ -310,6 +316,7 @@ export class Roundtable {
 						);
 					return this.#registry.dashboard;
 				},
+				apiKey: async (provider) => this.#options.apiKey?.(provider),
 			},
 			this.#tiers,
 			this.#services,

package/src/core/http/listeners.ts

@@ -1,7 +1,8 @@
-import { chmodSync, rmSync } from "node:fs";
+import { chmodSync } from "node:fs";
 import type { Server } from "bun";
 import { PluginError } from "../errors.ts";
 import type { Logger } from "../log.ts";
+import { serveUnix } from "../shared/unix-server.ts";
 
 /** A handler a plugin attaches to one of the host's configured listeners. */
 export interface HttpRoute {
@@ -96,29 +97,6 @@ export async function routeRequest(
 	}
 }
 
-/**
- * Serves HTTP on a unix socket without Bun's 10-second idle timeout, which would cut long
- * turns and quiet model streams. Bun 1.4.2 honors `idleTimeout` on unix sockets, but its
- * types reject the option there, hence the cast. A stale socket file is removed first.
- * (`shared/unix-server.ts` keeps its own copy for standalone worker images.)
- */
-function serveUnix(
-	socketPath: string,
-	fetch: (request: Request) => Response | Promise<Response>,
-): Server<undefined> {
-	rmSync(socketPath, { force: true });
-	const options = {
-		unix: socketPath,
-		idleTimeout: 0,
-		fetch,
-		error: serverError,
-	};
-	// SAFETY: these are Bun's unix-socket options; only `idleTimeout` is missing from its types.
-	return Bun.serve(
-		options as unknown as Parameters<typeof Bun.serve>[0],
-	) as Server<undefined>;
-}
-
 /** Serves HTTP on a TCP port with the same idle setting as the unix sockets. */
 function serveTcp(
 	port: number,
@@ -164,7 +142,9 @@ export class HttpListeners {
 				const handle = (request: Request) =>
 					routeRequest(routes, request, listener.id, this.#logger);
 				if ("socketPath" in listener) {
-					this.#servers.push(serveUnix(listener.socketPath, handle));
+					this.#servers.push(
+						serveUnix(listener.socketPath, handle, { error: serverError }),
+					);
 					chmodSync(listener.socketPath, listener.mode ?? 0o660);
 				} else {
 					this.#servers.push(