pi-roundtable 0.2.1 → 0.3.0

package/CHANGELOG.md

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

@@ -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

@@ -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.
@@ -127,10 +127,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 +153,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 +201,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 +1221,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";
@@ -1724,6 +1764,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 +1806,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, { ... })`.
 
@@ -1827,7 +1872,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 +1946,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 +2019,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 +2225,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 +2273,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.3.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/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/host.ts

@@ -278,6 +278,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(

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(

package/src/core/modules/delegation/web-research-worker.ts

@@ -6,6 +6,7 @@ import {
 	SessionManager,
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
+import { PluginError } from "../../errors.ts";
 import {
 	formatModelRef,
 	type ModelRef,
@@ -20,6 +21,18 @@ const WEB_TOOLS = ["web_search", "fetch_content", "get_search_content"];
 const WORKER_PROMPT =
 	"You are a research worker. Another agent handed you the task below and will pass your report on. Do it with web search and page reading, preferring primary sources. Report in the task's language, self-contained, with a source link for each claim, and say what you could not verify.";
 
+/** The folder of `pi-web-access`, a peer dependency the host installs, or a PluginError that says how. */
+function webAccessDir(): string {
+	try {
+		return packageDir("pi-web-access");
+	} catch (error) {
+		throw new PluginError(
+			"the delegation worker loads pi-web-access, which this project does not have installed. It is a peer dependency of pi-roundtable: run `bun add pi-web-access@0.35.0` (or your own build of it, which the worker then uses too).",
+			{ cause: error },
+		);
+	}
+}
+
 export interface WebResearchWorkerOptions {
 	/** Shared with the rest of the host, so the Codex login refreshes in one place. */
 	modelRuntime: ModelRuntime;
@@ -36,7 +49,7 @@ export class WebResearchWorker {
 
 	constructor(options: WebResearchWorkerOptions) {
 		this.#options = options;
-		this.#webAccessPath = packageDir("pi-web-access");
+		this.#webAccessPath = webAccessDir();
 		mkdirSync(options.workDir, { recursive: true });
 	}
 

package/src/core/plugin.ts

@@ -281,6 +281,14 @@ export interface RoundtablePlugin {
 	 * list before any setup, and refuses the plugin when setup returns without providing one.
 	 */
 	provides?: readonly ServiceKey<unknown>[];
+	/**
+	 * The services this plugin's setup reads with `get`, so the host can check them before any
+	 * setup and any migration: a key no registered plugin provides, or one provided by a plugin
+	 * registered after this one, is a PluginError that names both plugins and the fix. A service
+	 * read only after startup, from a callback, is `services.lazy` instead, which does not depend
+	 * on order. Leave out a service read with `find`, since that one may be absent.
+	 */
+	requires?: readonly ServiceKey<unknown>[];
 	/**
 	 * Services this plugin replaces. The host drops the plugin that provides them and sets this one
 	 * up where it stood, so it may read what the plugins before that place provide and nothing

package/src/core/registry/contributions.ts

@@ -385,6 +385,7 @@ export async function collectContributions(
 		registry.prompt.push(...prompt);
 		registry.requiredTools.push(...requiredTools);
 	}
+	services.settle();
 	return registry;
 }
 

package/src/core/registry/services.ts

@@ -1,5 +1,5 @@
 import type { ServiceKey, Services } from "../contract/services.ts";
-import { PluginError } from "../errors.ts";
+import { NotLinkedError, PluginError } from "../errors.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
 
 /** The host's words for reading a service no plugin declares; `testPlugin` says how to give one instead. */
@@ -29,6 +29,22 @@ function declaredBy(plugin: RoundtablePlugin): readonly ServiceKey<unknown>[] {
 	return provides;
 }
 
+/** The services a plugin requires, checked to be a list of keys; empty when it requires none. */
+function requiredBy(plugin: RoundtablePlugin): readonly ServiceKey<unknown>[] {
+	const { requires } = plugin;
+	if (requires === undefined) return [];
+	if (!Array.isArray(requires))
+		throw new PluginError(
+			`plugin ${plugin.name}: requires must be a list of service keys made with serviceKey().`,
+		);
+	for (const key of requires)
+		if (typeof key?.id !== "string" || key.id === "")
+			throw new PluginError(
+				`plugin ${plugin.name}: requires has an entry that is not a service key; make each with serviceKey("<id>").`,
+			);
+	return requires;
+}
+
 /** The services a plugin replaces, checked to be a list of keys; empty when it replaces none. */
 function replacedBy(plugin: RoundtablePlugin): readonly ServiceKey<unknown>[] {
 	const { replaces } = plugin;
@@ -127,10 +143,16 @@ export class ServiceRegistry {
 	#setting: RoundtablePlugin | undefined;
 	/** The plugins that have read a service, such as one that adds its commands through it. */
 	readonly #readers = new Set<RoundtablePlugin>();
+	readonly #plugins: readonly RoundtablePlugin[];
+	/** What each plugin asked `lazy` for, to refuse a key nobody provides once every plugin is set up. */
+	readonly #lazy: { plugin: RoundtablePlugin; key: ServiceKey<unknown> }[] = [];
+	/** Whether every plugin is set up, from which a `lazy` reader returns its service. */
+	#settled = false;
 
 	/** `advice` says how to get a service no plugin declares; the host's is to register one that does. */
 	constructor(plugins: readonly RoundtablePlugin[], advice = HOST_ADVICE) {
 		this.#advice = advice;
+		this.#plugins = plugins;
 		for (const plugin of plugins)
 			for (const key of declaredBy(plugin)) {
 				const other = this.#declaredBy.get(key.id);
@@ -147,6 +169,45 @@ export class ServiceRegistry {
 		this.#values.set(key.id, value);
 	}
 
+	/**
+	 * Refuses a plugin whose `requires` names a service no registered plugin or test provides, or
+	 * one a plugin registered after it provides. It runs before any migration or setup, so a wrong
+	 * order fails at the start with both plugins named.
+	 */
+	checkRequires(): void {
+		this.#plugins.forEach((plugin, index) => {
+			for (const key of requiredBy(plugin)) {
+				if (this.#values.has(key.id)) continue;
+				const provider = this.#declaredBy.get(key.id);
+				if (!provider)
+					throw new PluginError(
+						`plugin ${plugin.name}: requires service ${key.id}, which no registered plugin provides. ${key.absent ?? this.#advice}`,
+					);
+				if (provider === plugin)
+					throw new PluginError(
+						`plugin ${plugin.name}: requires service ${key.id}, which it provides itself. A plugin cannot require what it provides.`,
+					);
+				if (this.#plugins.indexOf(provider) > index)
+					throw new PluginError(
+						`plugin ${plugin.name}: requires service ${key.id}, which plugin ${provider.name} provides after it. Register plugin ${provider.name} before plugin ${plugin.name}, or read the service with services.lazy(KEY) from a callback that runs after startup.`,
+					);
+			}
+		});
+	}
+
+	/**
+	 * Called once every plugin is set up: `lazy` readers start answering, and a key a plugin asked
+	 * for that nobody provides is refused with the plugin named.
+	 */
+	settle(): void {
+		for (const { plugin, key } of this.#lazy)
+			if (!this.#values.has(key.id))
+				throw new PluginError(
+					`plugin ${plugin.name}: services.lazy reads service ${key.id}, which no registered plugin provides. ${key.absent ?? this.#advice}`,
+				);
+		this.#settled = true;
+	}
+
 	/** The service, for the host's own reads; throws like a plugin's `get`. */
 	get<T>(key: ServiceKey<T>): T {
 		return this.#read(key, undefined, true) as T;
@@ -185,6 +246,17 @@ export class ServiceRegistry {
 				this.#readers.add(plugin);
 				return this.#read(key, plugin, false);
 			},
+			lazy: <T>(key: ServiceKey<T>) => {
+				this.#readers.add(plugin);
+				this.#lazy.push({ plugin, key });
+				return () => {
+					if (!this.#settled)
+						throw new NotLinkedError(
+							`service ${key.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.`,
+						);
+					return this.#values.get(key.id) as T;
+				};
+			},
 			provide: (key, value) => {
 				if (this.#setting !== plugin)
 					throw new PluginError(

package/src/core/runtime/session-factory.ts

@@ -77,7 +77,7 @@ export class SessionFactory {
 			const linked = this.#options.sessions();
 			this.#linked = {
 				...linked,
-				extensionPaths: linked.piPackages.map(packageDir),
+				extensionPaths: linked.piPackages.map((name) => packageDir(name)),
 			};
 		}
 		return this.#linked;

package/src/core/shared/package-dir.ts

@@ -1,9 +1,12 @@
 import { createRequire } from "node:module";
 import { dirname } from "node:path";
 
-const require = createRequire(import.meta.url);
-
-/** The installed package's folder, as Pi's `additionalExtensionPaths` takes it. */
-export function packageDir(name: string): string {
-	return dirname(require.resolve(`${name}/package.json`));
+/**
+ * The installed package's folder, as Pi's `additionalExtensionPaths` takes it. The package is
+ * looked up from `from`, which is `import.meta.url` of the module that asks, so a host finds its
+ * own dependencies even when `pi-roundtable` is linked or installed apart from them; without it
+ * the lookup starts at the core's own files.
+ */
+export function packageDir(name: string, from: string | URL = import.meta.url) {
+	return dirname(createRequire(from).resolve(`${name}/package.json`));
 }

package/src/core/shared/unix-server.ts

@@ -0,0 +1,26 @@
+import { rmSync } from "node:fs";
+import type { Server } from "bun";
+
+/**
+ * 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.
+ * `error` answers a failure raised outside the fetch handler; without it Bun's own page is sent.
+ */
+export function serveUnix(
+	socketPath: string,
+	fetch: (request: Request) => Response | Promise<Response>,
+	options: { error?: (error: Error) => Response | Promise<Response> } = {},
+): Server<undefined> {
+	rmSync(socketPath, { force: true });
+	const serveOptions = {
+		unix: socketPath,
+		idleTimeout: 0,
+		fetch,
+		...(options.error ? { error: options.error } : {}),
+	};
+	// SAFETY: these are Bun's unix-socket options; only `idleTimeout` is missing from its types.
+	return Bun.serve(
+		serveOptions as unknown as Parameters<typeof Bun.serve>[0],
+	) as Server<undefined>;
+}

package/src/core/testing/partial.ts

@@ -0,0 +1,21 @@
+/** Members a probe may ask of any object: a test's stand-in is not refused for them. */
+const PROBED = new Set(["then", "toJSON", "asymmetricMatch"]);
+
+/**
+ * A stand-in for a port the code under test takes, made of only the members the test gives.
+ * Reading any other member throws an error that names it, so a test learns at once which member
+ * the code reaches for, instead of meeting `undefined is not a function` or a hidden cast.
+ * `partial<AgentTeam>({ announce })` is an `AgentTeam` to the type checker.
+ */
+export function partial<T extends object>(given: Partial<T>): T {
+	// SAFETY: the stand-in answers only the members given; any other read throws before it is used.
+	return new Proxy(given, {
+		get(target, member, receiver) {
+			if (member in target || typeof member === "symbol" || PROBED.has(member))
+				return Reflect.get(target, member, receiver);
+			throw new Error(
+				`partial() was given no "${member}". Give it where the stand-in is made: partial({ ${member}: ... }).`,
+			);
+		},
+	}) as T;
+}

package/src/core/testing/recording-logger.ts

@@ -0,0 +1,44 @@
+import type { Logger } from "../log.ts";
+
+/** One line a recording logger kept. */
+export interface RecordedLog {
+	level: "debug" | "info" | "warn" | "error" | "fatal";
+	/** The fields of the call, with those of every `child` the logger came from. */
+	fields: Record<string, unknown>;
+	message: string;
+}
+
+/** A logger that keeps what it is asked to write, and the lines it kept. */
+export interface RecordingLogger {
+	readonly logger: Logger;
+	/** Every line written through the logger or a child of it, in order. */
+	readonly lines: RecordedLog[];
+}
+
+/**
+ * A logger for a test that checks what the code logs: it writes nowhere, and `lines` holds each
+ * call with its level, fields (a child's included), and message.
+ */
+export function recordingLogger(): RecordingLogger {
+	const lines: RecordedLog[] = [];
+	const make = (bound: Record<string, unknown>): Logger => {
+		const write =
+			(level: RecordedLog["level"]) =>
+			(first: object | string, message?: string): void => {
+				lines.push(
+					typeof first === "string"
+						? { level, fields: { ...bound }, message: first }
+						: { level, fields: { ...bound, ...first }, message: message ?? "" },
+				);
+			};
+		return {
+			debug: write("debug"),
+			info: write("info"),
+			warn: write("warn"),
+			error: write("error"),
+			fatal: write("fatal"),
+			child: (fields) => make({ ...bound, ...fields }),
+		};
+	};
+	return { logger: make({}), lines };
+}

package/src/discord/index.ts

@@ -1,5 +1,5 @@
 // The Discord entry: everything that names a discord.js type, apart from the main and kit entries.
-// Unstable before 1.0; not covered by semver.
+// Versioned like the main entry: a breaking change comes in a minor release before 1.0 and is listed in the changelog.
 
 export type { DiscordServices } from "../core/builtin/discord.ts";
 export { DISCORD } from "../core/builtin/discord.ts";

package/src/kit/channels.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export { discordKey } from "../core/agents/team-keys.ts";
 

package/src/kit/domain.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export { AgentError } from "../core/domain/errors.ts";
 export type {

package/src/kit/holds.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 // The chain a host links from every plugin's hold rules, to test a rule set as the host runs it.
 
 export { holdChain } from "../core/holds.ts";

package/src/kit/index.ts

@@ -1,4 +1,4 @@
-// Unstable before 1.0; not covered by semver. Helpers for owner commands, claims, and naming existing core parts.
+// Helpers for owner commands, claims, and naming existing core parts; versioned like the main entry.
 
 export type { ChannelQueue } from "./channels.ts";
 export {
@@ -62,6 +62,7 @@ export {
 	thinkingLine,
 	zonedStamp,
 } from "./presentation.ts";
+export { packageDir, serveUnix } from "./process.ts";
 export {
 	SHELL_TOOLS,
 	shellHoldRule,

package/src/kit/judging.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export type {
 	EffortBrief,

package/src/kit/memory.ts

@@ -1,3 +1,3 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export { searchTerms } from "../core/modules/memory/owner-memory-store.ts";

package/src/kit/mirror.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 // Mirror a built-in tool in a worker that cannot reach the host: the specs and the dispatcher.
 
 export type { ScheduleToolContext } from "../core/modules/schedules/schedule-tools.ts";

package/src/kit/presentation.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export { headline } from "../core/presentation/headline.ts";
 export { quietLinks } from "../core/presentation/quiet-links.ts";

package/src/kit/process.ts

@@ -0,0 +1,5 @@
+// Plugin helpers, versioned like the main entry; see the plugin guide.
+// Running a worker process of your own: where an installed package lives, and a unix-socket HTTP server.
+
+export { packageDir } from "../core/shared/package-dir.ts";
+export { serveUnix } from "../core/shared/unix-server.ts";

package/src/kit/shell.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 // The host-shell tools and the hold rule that keeps risky commands behind the owner's approval.
 
 export {

package/src/kit/skills.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 // Skills and repositories: the names a repository shelf accepts, and the tool that lists skills.
 
 export { checkRepoName } from "../core/modules/skills/repo-name.ts";

package/src/kit/support.ts

@@ -1,4 +1,4 @@
-// Supporting data types for the unstable service and helper contracts.
+// Supporting data types for the service and helper contracts.
 
 export type {
 	AgentCategory,

package/src/kit/threads.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export type {
 	DispatchThread,

package/src/kit/tools.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export type {
 	TextToolDef,

package/src/kit/worker.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 // Running a Pi session of your own: MCP servers for it, its work timeout, its held-action cards.
 
 export {

package/src/testing.ts

@@ -63,7 +63,6 @@ import { type ToolTierTable, toolTiers } from "./core/tool-tiers.ts";
 // Fixtures for plugin tests.
 
 export { silentLogger } from "./core/log.ts";
-
 export type { TestStore } from "./core/testing/database.ts";
 export {
 	describeDb,
@@ -74,8 +73,13 @@ export {
 export { eagerText, useEagerCatalog } from "./core/testing/eager-catalog.ts";
 export type { TestLocale } from "./core/testing/locale.ts";
 export { useTestLocale } from "./core/testing/locale.ts";
-
 export { OWNER_SPEAKER } from "./core/testing/owner.ts";
+export { partial } from "./core/testing/partial.ts";
+export type {
+	RecordedLog,
+	RecordingLogger,
+} from "./core/testing/recording-logger.ts";
+export { recordingLogger } from "./core/testing/recording-logger.ts";
 export type { TestHost, TestHostOptions } from "./core/testing/test-host.ts";
 export { testHost } from "./core/testing/test-host.ts";
 export type { FakeThreadHost } from "./core/testing/thread-host.ts";
@@ -393,6 +397,7 @@ export async function testPlugin(
 				logger,
 			}),
 		);
+	services.checkRequires();
 	const context: Omit<PluginContext, "services"> = {
 		logger,
 		env,