pi-roundtable 0.7.19 → 0.8.0

package/docs/plugins.md

@@ -139,7 +139,10 @@ Use `QueuePort` from the main entry for `context.queue`; the kit's `ChannelQueue
 `context.logger` is a child of the host's logger and adds `plugin: <your plugin's name>` to each line in the journal.
 `Logger` has five levels and `child(fields)`; you can pass an existing pino logger as `DefineOverrides.logger`.
 
-With `defineRoundtable`, the host's logger sends every `error` and `fatal` line to the ops agent named by `config.ops.agent`, which reports it in its channel.
+With `defineRoundtable`, the host's logger sends every `error` and `fatal` line to the ops agent named by `config.ops.agent`, which reports it in its channel, or, with `config.ops.conversation`, to that conversation as a visible message and a report turn its claim answers.
+The report turn is a background turn of the `owner` target, so the host does not start, with a `ConfigError` naming `config ops.conversation` and the reason, when no chat surface serves the key, no plugin's claim owns it, no plugin contributes the `owner` background target, or the claim that owns it takes no background turns (has no `background`); a report is then never only logged.
+On a host without Discord no plugin contributes `owner` unless one of yours does, so `ops.conversation` needs such a plugin there.
+The web chat takes no error reports in 0.8: it posts only to a conversation a signed-in person opened, and its claim takes no background turns, so `web:<id>` fails at startup; name a conversation of another surface, or an agent with Discord.
 It then calls `DefineOverrides.errorSink(entry)` if you supply one; this function must not throw.
 A logger you supply reaches the ops agent and `errorSink` only if it forwards its error lines there.
 The report names the plugin next to `app` and `module`; the same error is reported at most once an hour, regardless of which plugin wrote it.
@@ -172,7 +175,9 @@ The built-in plugins provide these, from the main entry:
 
 | Key | Port | Provided by | What it is |
 |---|---|---|---|
-| `AGENTS` | `AgentServer` | `agent-server` | The `team` (`AgentTeam`), the read-only `directory` (`AgentDirectory`), the `runtime` every agent turn runs on, `approvals` (whether the owner's reply approves held actions), and `avatars` (`AvatarStudio`) |
+| `CONVERSATIONS` | `ConversationRegistry` | `conversations` | The conversations run through `context.turns`: `register`, `get(key)`, `list({ principal }?)`, `setTitle(key, title)`; each a `ConversationRecord` of `key`, `surface`, `kind`, `visibility` (`"private"` or `"shared"`), `principalId?`, `title?`, `createdAt`, `lastActiveAt` |
+| `RUNTIME` | `AgentRuntime` | `runtime` | The runtime every conversation turn runs on, the agent server's and `context.turns`': the `runtime` slot's when a plugin fills it, Pi's otherwise |
+| `AGENTS` | `AgentServer` | `agent-server` | The `team` (`AgentTeam`), the read-only `directory` (`AgentDirectory`), the `runtime` every agent turn runs on (the same one `RUNTIME` provides), `approvals` (whether the owner's reply approves held actions), and `avatars` (`AvatarStudio`) |
 | `SKILLS` | `SkillRegistry` | `skills` (an addon) | What agents carry: `carried`, `carriedNames`, `describeCarried`, `catalog`, `list`, `linkedFrom`, `checkRegistered`, `link`, `attach` |
 | `SCHEDULES` | `ScheduleStore` | `schedule-store` | The stored schedules: `create`, `get`, `forChannel`, `all`, `update`, `remove`, `due`, `claim`, `recordStatus` |
 | `PRECHECKS` | `PrecheckRegistry` | `prechecks` | The host's named [prechecks](#prechecks-wake-a-schedule-only-when-it-has-work): `register`, `get`, `list`; and the runner of agents' precheck scripts: `useScriptRunner`, `scriptRunner` |
@@ -511,7 +516,7 @@ export const cleanup = definePlugin({
 
 A rule whose verdict depends on the input, such as one that holds only a `delete` action, can also answer `mayHold(tool)`: whether it may hold some call of that tool.
 It is asked when the input is not known yet, as for a [precheck script](#precheck-scripts-prechecks-the-agent-writes)'s call whose arguments are computed when it runs; a rule without it is judged by `describe` with an empty input.
-A rule whose held call stands for others can answer `approvalTier(tool, input, context)`: the lowest tier that may approve it when higher than the tool's own. The held call keeps it as `minTier`, and both its card and a confirming message require it.
+A rule whose held call stands for others can answer `approvalTier(tool, input, context)`: the lowest tier that may approve it when higher than the tool's own. The held call keeps it as `minTier`, and both its card and a confirming message require it. A card is answered, and a confirming message accepted, from the speaker whose turn held the call, when their tier is at least `minTier`, and from the owner; nobody else in the channel may approve it. The held call records that speaker as `PendingConfirmation.speakerId`; a call held without one is the owner's to approve.
 
 #### The shell rule
 
@@ -642,6 +647,7 @@ export const library = definePlugin({
 | `serviceStarted(event)` | A service's `startInBackground` ended: `event` is `{ plugin, service, outcome }`, and `outcome` is `"ready"` or `"failed"`; the rest of the process runs either way |
 | `turnStarted(turn)` | An agent's turn began, or a turn run through `context.turns` |
 | `turnEnded(turn)` | The turn ended; `turn.result` is `"ok"`, `"failed"`, or `"stopped"` |
+| `turnProgress(event)` | A turn run through `context.turns` wrote text or ran a tool, between its start and its end: `event` is the turn's fields and `progress`, a `TurnProgress` (see the surface's `progress` below); a runtime without live progress reports none |
 | `changed()` | The team changed: an agent or group was created, edited, arranged, archived, or started over |
 | `shutdown(left)` | The shutdown drain ended, before any service stops; `left` lists the work it gave up on |
 
@@ -996,7 +1002,7 @@ An unknown or misspelled slot stops startup with an error listing the valid name
 |---|---|---|
 | `judge` | Asks the configured model small questions: does this reply approve the held actions, how hard is this turn, which agents does this group message concern | An object with `askYesNo`, `askChoice`, and `askScore` |
 | `images` | No drawing; each agent gets an avatar generated from its display name | `async (prompt, references) => bytes` returning PNG bytes |
-| `runtime` | None: the agent server builds the Pi runtime itself | `(deps) => runtime`, an [`AgentRuntime`](#the-runtime-slot-replace-pi) that runs every conversation |
+| `runtime` | None: the runtime plugin builds the Pi runtime itself | `(deps) => runtime`, an [`AgentRuntime`](#the-runtime-slot-replace-pi) that runs every conversation |
 
 When no `images` provider is configured, `agent_create` has no `avatar_prompt` parameter and `agent_avatar` is unavailable.
 The owner's profile panel reports the missing provider and offers no redraw option.
@@ -1030,16 +1036,16 @@ export const pixelAvatars = definePlugin({
 
 The runtime handles the agent server's conversations and those of every claim that runs turns through `context.turns`.
 It keeps one persistent conversation per channel key, with its turns, held actions, and history.
-By default, the agent server builds the Pi runtime.
+By default, the host's `runtime` plugin builds the Pi runtime and provides it as `RUNTIME`; the agent server and `context.turns` both run on it, and a host without the agent server has it too.
 Filling the `runtime` slot replaces it for agent turns, the owner's conversations, steering, held actions, and transcripts; the host skips building Pi.
-The slot's default factory refuses calls, so check `providers.filled.has("runtime")` before calling `providers.runtime`.
-The agent server does this for you.
+The slot's default factory refuses calls: read the running runtime with `services.get(RUNTIME)` instead of calling `providers.runtime`.
 
-The slot is a `RuntimeFactory`: `(deps: RuntimeDeps) => AgentRuntime`, called once when the agent server sets up.
+The slot is a `RuntimeFactory`: `(deps: RuntimeDeps) => AgentRuntime`, called once when the runtime plugin sets up, before the agent server.
 `deps` provides `logger`, `env`, `owner`, `toolTiers`, and the host's `judge`.
 Its `sessions()` gives you linked hold rules, packages, session tools, and personas from preflight onwards; call it in a turn, when those parts are available.
 `prompts(conversation, speaker)` gives you the owner's approval and question cards on the conversation's surface, or `undefined`.
 `agents` holds the agent server's per-agent settings: `workDir`, `scratchDir` (the agents' shell's `TMPDIR`), `skills(name)`, `modelOf(name)`, and `turnChannel(scope)`.
+The agent server sets up after the runtime is built, so read `agents` when a turn runs; it is `undefined` on a host without the agent server, where no agent turn runs.
 `confirmations` stores held actions across restarts.
 
 An `AgentRuntime` has these methods:
@@ -1054,7 +1060,7 @@ An `AgentRuntime` has these methods:
 | `recentTranscript(conversation, limit)` | The latest messages, for the owner's and the dashboard's views of a conversation |
 | `contextUsage?(conversation)` | How full the conversation's context is, `{ tokens, contextWindow }`; leave it out and the team status shows no context bar |
 | `preflight?()` | Runs in the host's preflight, before anything starts; a throw stops the boot |
-| `dispose?()` | Runs when the host stops the agent server's runtime service |
+| `dispose?()` | Runs when the host stops the runtime plugin's `runtime` service |
 
 A request has the turn's `channel`, `selection` (its tools), `text`, `attachments`, `speaker`, flags (`steerable`, `interactive`, `confirmed`), and `interim`, where the turn may post the text it writes before its final answer ([interim text](#interim-text-what-a-turn-writes-before-its-final-answer)).
 An agent's turn also has `agent`, the agent's scope, whose `session` is the conversation's key.
@@ -1162,7 +1168,7 @@ export const createEchoRuntime: RuntimeFactory = (deps) => {
 
 /**
  * A plugin fills the `runtime` slot to replace the whole conversation runtime; without one the
- * agent server builds the Pi runtime. One plugin may fill it.
+ * runtime plugin builds the Pi runtime. One plugin may fill it.
  */
 export const echoRuntime = definePlugin({
 	name: "echo-runtime",
@@ -1391,7 +1397,7 @@ A test gives the plugin `fakeDiscord()` from `pi-roundtable/testing`: `testPlugi
 ### `http`: routes on the bot's listener
 
 The configuration's `http` block opens a listener named `public`, which serves the agents' avatars.
-`http.publicUrl` is its internet address.
+`http.publicUrl` is its internet address, required with Discord; a host without Discord may leave `http` out and opens no listener.
 A route names the listener, a path (`{ exact }` or `{ prefix }`), optionally the methods, and a handler that gets a `Request` and returns a `Response`.
 Two routes that could take the same request are refused, so a route cannot shadow the avatars.
 This listener is reachable from the internet, so check a secret in the handler before taking action.
@@ -1404,6 +1410,20 @@ The socket file's permission bits are `http.socketMode`, `0o660` by default: onl
 Widen it (`0o666`) only when the proxy runs as a user outside that group.
 More listeners than `public` come from `defineRoundtable`'s `listeners` override, each `{ id, socketPath, mode? }` or `{ id, port, hostname? }`, and a route attaches to one by its `id`.
 
+A route that also declares `websocket` takes WebSocket upgrades on its path; every other request still reaches `handle`, and its `methods`, when listed, must include `GET`.
+An upgrade is a `GET` with `Upgrade: websocket`; one without `Sec-WebSocket-Key` or with a `Sec-WebSocket-Version` other than `13` gets `400`, and any other method goes to `handle` as usual.
+An upgrade request first passes the Origin check: `origins` lists the `scheme://host[:port]` values a browser may connect from, exactly as a browser sends them, such as `https://chat.example.com` or `chrome-extension://<id>` (a lowercase scheme and no path, trailing slash, query, fragment, or user; another form, and `"null"`, is refused at startup), and a request with another Origin, or none, gets `403` without reaching the route. `"any"` skips the check, for clients that are not browsers.
+A route holds at most `maxConnections` sockets at once (256 by default), counting upgrades still in `accept`; one more gets `503` before `accept` runs.
+Then `accept` authenticates and authorizes the request before any socket opens: it returns `{ data }`, which every handler reads as `socket.data`, or a `Response` such as `401` or `403` that refuses the upgrade. An `accept` that throws answers `500` like a failing `handle`.
+Browsers cannot set headers on a WebSocket, so a browser client proves itself with a ticket: one-time and short-lived in the query, so a ticket that leaks from a log or the history opens nothing, or carried in `Sec-WebSocket-Protocol`, which `accept` answers by returning the chosen protocol in `headers`.
+Never combine `origins: "any"` with cookie authentication: the browser sends the cookie from any site, so any page its user opens could take over their socket (cross-site WebSocket hijacking).
+Each message reaches `message` as it arrives. A message over `maxMessageBytes` (64 KiB by default) closes the socket with `1009`, and more than `rate.messages` in `rate.perMs` (120 a minute by default) closes it with `1008`.
+`socket.send` answers `"sent"`, `"queued"` when the client reads slower than the route sends, or `"dropped"`. `maxBufferedBytes` (1 MiB by default) is checked before each `send`: once that many bytes wait for a client that stopped reading, the next `send` answers `"dropped"` and the host cuts the socket without a close frame, so the client and the route's `close` both see `1006`. A `send` that finds fewer waiting goes out whole, so a single message larger than the limit still reaches a client that reads, and the bytes waiting can reach the limit plus one message. A `send` on a closed socket answers `"dropped"` too, and an empty message is `"sent"`.
+Every limit (`maxMessageBytes`, `maxBufferedBytes`, `maxConnections`, `rate.messages`, `rate.perMs`) must be a positive integer; another value is refused at startup with an error naming the route and field.
+The handlers' return values are ignored and a returned promise is awaited, so `message: (socket, message) => socket.send(message)` is a complete echo.
+A handler that throws or rejects closes only its own socket, with `1011`, and logs the route and listener like a failing `handle`.
+When the host shuts down, every open socket is closed with `1001`, and the shutdown waits up to five seconds for the routes' `close` handlers before it stops the services.
+
 <!-- example: examples/http.ts -->
 ```ts
 import { definePlugin } from "pi-roundtable";
@@ -1423,6 +1443,45 @@ export const health = definePlugin({
 		],
 	}),
 });
+
+/**
+ * A route with `websocket` also takes upgrades. The Origin check and `accept` run before any
+ * socket opens, so a browser on another site, or a client without a ticket, never connects.
+ * A ticket opens one socket: `accept` spends it, so one that leaks from a log or the browser's
+ * history opens nothing. Whoever issues the tickets should also let them expire within seconds.
+ */
+export const echo = (tickets: Set<string>) =>
+	definePlugin({
+		name: "echo",
+		setup: () => ({
+			http: [
+				{
+					name: "echo",
+					listener: "public",
+					path: { exact: "/echo" },
+					methods: ["GET"],
+					handle: () => new Response("Upgrade Required", { status: 426 }),
+					websocket: {
+						origins: ["https://chat.example.com"],
+						accept: (request) => {
+							const ticket = URL.parse(request.url)?.searchParams.get("ticket");
+							return ticket && tickets.delete(ticket)
+								? { data: { since: Date.now() } }
+								: new Response("Unauthorized", { status: 401 });
+						},
+						maxMessageBytes: 4096,
+						rate: { messages: 20, perMs: 10_000 },
+						maxBufferedBytes: 64 * 1024,
+						maxConnections: 50,
+						message: (socket, message) => {
+							// "dropped" means the client stopped reading and the host cut it; an echo has nothing to resend.
+							socket.send(message);
+						},
+					},
+				},
+			],
+		}),
+	});
 ```
 <!-- /example -->
 
@@ -1664,8 +1723,16 @@ Call `context.turns.run(input)` inside your claim's queue task to run a turn in
 It shows typing and the stop control on the channel's surface, runs the turn, and emits `turnStarted` and `turnEnded` with the turn's `kind`.
 It catches runtime errors as failed results and posts the answer, failure notice, or stopped notice through the surface.
 Supply `reply(result)` to handle the reply yourself.
-`input` has `channel`, `kind`, `text`, `speaker`, and optionally `attachments`, `selection` (by default the plugins' `agentSelection`), `steerable`, `interactive`, `confirmed`, and `reply`.
-It rejects with `NotLinkedError` during `setup`, and with a `PluginError` on a host whose agent server has not provided a runtime.
+`input` has `channel`, `kind`, `text`, `speaker`, and optionally `attachments`, `selection` (by default the plugins' `agentSelection`), `steerable`, `interactive`, `confirmed`, `reply`, and `conversation`.
+It rejects with `NotLinkedError` during `setup`, and with a `PluginError` on a host whose runtime plugin has not provided a runtime.
+
+Before each turn runs, `context.turns.run` records its conversation in the host's registry, `CONVERSATIONS`: at the first turn its key, surface, kind, visibility, owner, and title, and at every later turn only that it was active.
+`conversation: { visibility: "private" }` records it as the speaker's own (`principalId` is `speaker.id`); without it the conversation is `shared`.
+`conversation.title` names it at its first turn; `setTitle(key, title)` renames it later.
+A turn whose conversation cannot be recorded does not run, and the call rejects.
+The registry records and never refuses: who may speak in a conversation stays your claim's decision, which may read `get(key)` to check the owner.
+`list({ principal })` gives one principal's conversations and `list()` every one, the most recently active first; the web console lists them too.
+No session file moves, and a conversation from before the registry is recorded at its next turn.
 
 <!-- example: examples/study-room.ts -->
 ```ts
@@ -1884,6 +1951,7 @@ The agent server claims only `discord:` keys, so claims on your surface's channe
 | `react`, `unreact` | Adds or removes the bot's reaction on a message | no marks on queued or steered messages |
 | `prompts(channel, speaker?)` | The owner's way to approve a held action or answer `ask_user` inside a running turn, as `OwnerPrompts`: `confirm` and `ask` | the action is held until the owner's next message |
 | `interim(channel)` | Where a running turn posts the text it writes before its final answer, as `InterimPosts`: `post(text)` sends one message of at most 2000 characters and resolves to an `InterimMessage` whose `edit(text)` changes it in place | only the final reply is posted |
+| `progress(channel, event)` | Shows a turn run through `context.turns` as it goes, such as a live preview in a web chat. `event` is a `TurnProgress`: `{ type: "text", delta }` (the reply's text, joined over 250 ms and always sent before a tool event, never the thinking), `{ type: "tool_start", id, tool, preview? }` (a one-line preview of the arguments, at most 80 characters, never their full text), or `{ type: "tool_end", id, tool, ok }`. The final reply still comes through `sendReply`; a rejection is logged and the turn goes on | only the final reply is shown |
 
 The host starts each surface as `surface:<prefix>` at the contributing plugin's place in the order, before that plugin's own services.
 It stops surfaces in reverse order, like other services.
@@ -2032,6 +2100,148 @@ export function fakeChat(surface: FakeSurface) {
 
 A test boots a host with the plugin, writes through the surface, and reads what came out (`examples/fake-surface.test.ts` does this with `Roundtable` and `silentLogger`, and also covers the refusals above).
 
+### `adapters`: the chat networks the host talks through
+
+`adapters` lists the chat networks the host talks through, each made by its adapter's factory.
+In 0.8 the one adapter is Discord: `discord()` from `pi-roundtable/discord` takes the same settings as the top-level `discord`, and a host configured either way assembles the same plugins in the same order.
+The top-level `discord` stays the form `roundtable init` writes; configure Discord once, in one place or the other.
+A chat network that comes as a plugin, such as pi-roundtable-webchat's `webChat()`, stays in `plugins`.
+
+<!-- example: examples/discord-adapter.ts -->
+```ts
+import type { RoundtableConfig } from "pi-roundtable";
+import { discord } from "pi-roundtable/discord";
+
+/**
+ * Discord as an adapter: `discord()` takes the same settings as the top-level `discord`, and the
+ * host assembles the same plugins in the same order. Configure Discord in one place, not both.
+ */
+export function withDiscordAdapter(
+	env: (name: string) => string,
+	dataDir: string,
+): RoundtableConfig {
+	return {
+		owner: { id: env("OWNER_ID"), name: env("OWNER_NAME") },
+		adapters: [
+			discord({
+				token: env("DISCORD_TOKEN"),
+				guild: env("DISCORD_GUILD_ID"),
+				entryChannel: env("DISCORD_ENTRY_CHANNEL_ID"),
+			}),
+		],
+		database: { url: env("DATABASE_URL") },
+		dataDir,
+		model: env("MODEL"),
+		http: { publicUrl: env("PUBLIC_URL") },
+	};
+}
+```
+<!-- /example -->
+
+`examples/discord-adapter.test.ts` checks that both forms assemble the same plugins.
+`roundtable doctor` reads a Discord adapter's settings as it reads the top-level `discord`.
+The types are `AdapterConfig` and `DiscordConfig` from `pi-roundtable`, and `DiscordAdapterConfig` from `pi-roundtable/discord`.
+
+### A host without Discord
+
+Leave `discord` out of `roundtable.config.ts` and the host runs without it: no Discord plugin, no agent server, no agents, and no skills.
+The runtime plugin still builds the runtime, so every claim that runs turns through `context.turns` works, over the surfaces your plugins bring.
+`http` is optional too; without it the host opens no listener, and a route then names a listener that is not configured.
+
+What needs Discord is refused or left out rather than failing later:
+
+- `agents`, `skills` (anything but `false`), and `ops.agent` are configuration errors. `ops: { conversation: "<surface>:<id>" }` needs a chat surface that serves it, a claim that owns it and takes background turns, and a plugin that contributes the `owner` background target, or the host does not start; without Discord nothing contributes `owner` unless a plugin of yours does. The web chat takes no error reports in 0.8.
+- `notify_owner` is not registered, since there are no owner's messages to send to.
+- `schedule_*` and `delegate_task` are not registered: their runs are turns of the [background target](#backgroundtargets-whose-turn-a-schedule-or-delegated-task-is) named `owner`, which the agent server contributes, so without it none could start.
+  A plugin that contributes `owner`, and a claim that takes its background turns, bring them back; they then work in a conversation a chat surface carries, posting their runs there, and refuse elsewhere.
+- `roundtable doctor` skips the Discord checks.
+
+Pi's runtime still needs the `compact_session` tool in every session, from the Pi package pi-self-compact: load it from a plugin with `piPackages: ["pi-self-compact"]`, as the `plugins/self-compact.ts` of a project `roundtable init` creates does, or the preflight stops the start and says so.
+`roundtable init --adapter web` creates a host without Discord around the [web chat](#web-chat-pi-roundtable-webchat).
+A host that keeps Discord may write it as an adapter instead, as [`adapters`](#adapters-the-chat-networks-the-host-talks-through) describes.
+
+<!-- example: examples/headless.ts -->
+```ts
+import { definePlugin, type RoundtableConfig } from "pi-roundtable";
+import type { FakeSurface } from "./fake-surface.ts";
+import { studyRoom } from "./study-room.ts";
+
+/** A plugin that brings a chat network and nothing else; the study room's claim answers its rooms. */
+export function chatNetwork(surface: FakeSurface) {
+	return definePlugin({
+		name: "chat-network",
+		setup: () => ({ surfaces: [surface] }),
+	});
+}
+
+/**
+ * A host without Discord: no `discord` key, so no Discord plugin, no agent server, no agents and
+ * no skills; and no `http`, so no listener opens until a plugin needs one. Conversations come
+ * through the plugins' own chat surfaces, and `context.turns` runs them on the host's runtime,
+ * Pi's unless a plugin fills the `runtime` slot.
+ */
+export function studyHall(
+	surface: FakeSurface,
+	where: { databaseUrl: string; dataDir: string },
+): RoundtableConfig {
+	return {
+		name: "Study Hall",
+		owner: { id: "owner", name: "Ada" },
+		database: { url: where.databaseUrl },
+		dataDir: where.dataDir,
+		model: "anthropic/claude-sonnet-5-5",
+		plugins: [chatNetwork(surface), studyRoom],
+	};
+}
+```
+<!-- /example -->
+
+`examples/headless.test.ts` boots this configuration over PostgreSQL with the echo runtime in place of Pi, and a study room answers through the fake surface.
+`testHost({ discord: false })` boots the same kind of host for a plugin's tests.
+
+### Web chat: pi-roundtable-webchat
+
+[pi-roundtable-webchat][webchat-package] is a chat network that comes as a plugin.
+`webChat({ verifier, access, personas, origins })` adds a chat surface whose conversations have keys `web:<conversation>`, the claim that runs each message as a turn of its conversation's persona through `context.turns`, and a REST API and a WebSocket under `/chat` on the host's `public` listener.
+People an OpenID Connect provider signs in open private conversations, see each turn's text and tools as it runs, and answer its approval cards.
+It needs no Discord: a host whose configuration has no `discord` and lists `webChat(...)` in `plugins` is a web-only assistant.
+
+#### `roundtable init --adapter web`
+
+`roundtable init --adapter web` writes a project without Discord around it: no `agents.ts` and no shared persona, a `roundtable.config.ts` that lists `webChat(...)` with an `oidcJwtVerifier`, an access map whose members and admins come from the token's roles, and one persona, `assistant`, whose prompt is `persona/assistant.md`.
+The persona's `selection` names its tools (the hello plugin's), so tools a later plugin adds, such as pi-web-access's, stay out until you add them by name.
+`package.json` pins pi-roundtable-webchat at the core's version and pi-self-compact, and `.env.example` asks for `OWNER_NAME`, `DATABASE_URL`, `MODEL`, `OIDC_ISSUER`, `OIDC_AUDIENCE`, `OIDC_JWKS_URL`, `CHAT_MEMBER_ROLES`, and `CHAT_ORIGINS`, with no Discord variable.
+The host listens on `127.0.0.1:3000`; serve it over HTTPS through a reverse proxy.
+`--adapter discord` is the default and writes the Discord project.
+
+#### Protocol
+
+A browser asks for a one-time ticket with `POST /chat/tickets` and `Authorization: Bearer <token>`, then opens `/chat/socket` offering the subprotocols `roundtable.webchat.v1` and `ticket.<ticket>`; another client sends the bearer token on the upgrade.
+The token never travels in a URL.
+Each WebSocket message is one JSON object with a `type`: the client sends `send`, `stop`, `approval`, `answer`, and `auth`; the server answers with `ready`, `accepted`, `typing`, `stoppable`, `progress`, `reply`, `failed`, `prompt`, `prompt_closed`, `reauth`, and `error`.
+`progress` carries the turn's [`TurnProgress`](#surfaces-a-chat-network-of-your-own) events, never the thinking and never a tool's full arguments; `reply` carries the answer in full markdown.
+The REST API lists a person's conversations, opens one, and reads its messages.
+The package README documents every frame, error code, close code, and limit.
+
+#### Security model
+
+- A conversation belongs to the person who opened it: the claim checks the [conversation registry](#services-what-plugins-provide-to-each-other) inside the conversation's queue before every turn, and only that person may list, read, write in, stop, or answer it.
+- Tokens are checked on every REST call, every upgrade, and every `auth` frame. By default only a person's access token passes: a token without a scope or app roles, or an app-only token, is refused. A socket closes when its token expires.
+- `origins` is required, and checked on every upgrade and every browser request.
+- Each person has bounded sockets, tickets, conversations opened per hour, and turns running or queued at once; frames are bounded in size and rate.
+- An approval card goes to the conversation's person only, at the tier the held call needs.
+- No token claim makes anyone the owner; owners are listed by speaker id, `oidc:<base64url(issuer)>:<subject>`.
+
+#### Provider settings
+
+The verifier is generic; what makes it safe is how it is pointed at your provider.
+The README's [provider settings][webchat-provider-settings] explain, with Microsoft Entra ID as the example, why to name people by a claim that stays the same across app registrations (`subjectClaim`), pin the tenant in `check`, accept access tokens only, refuse app-only tokens, merge issuers of one tenant only (`speakerIssuer`), and mind the guests `everyone` admits.
+
+The web chat takes no attachments and no background turns yet: leave `schedule_*` and `delegate_task` out of a web persona's `selection`, and `web_search` and `fetch_content` unless people may make the host fetch any address, internal ones included.
+
+[webchat-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/webchat/README.md
+[webchat-provider-settings]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/webchat/README.md#provider-settings
+
 ### What plugins do not extend
 
 A plugin adds slash commands through the Discord plugin's registrar and never receives the composed commands (see [slash commands](#slash-commands-commandsadd)).
@@ -2058,10 +2268,9 @@ Inspect the ready-made implementations in the [codex-images][codex-images-templa
 
 The [pi-roundtable-mcp][mcp-package] workspace, published separately on npm, adds two more plugins, `mcpConnectors` and `remoteMcp`.
 The first lets the owner add MCP servers such as Notion or a calendar from Discord and gives your code the list; the second lets an agent outside Discord reach your agent.
-Install it with `bun add pi-roundtable-mcp` after the next lockstep release publishes the migrated package.
-Until then, npm's MCP 0.4.1 requires core below 0.6.0 and is not compatible with core 0.7.x.
+Install it with `bun add pi-roundtable-mcp`.
 
-Five official packages live in this repository as Bun workspaces and publish as separate npm packages, versioned in lockstep with the core.
+Six official packages live in this repository as Bun workspaces and publish as separate npm packages, versioned in lockstep with the core.
 The [site guide source files][package-guides] describe installation, requirements, configuration, and security considerations:
 
 - [pi-roundtable-drawing][drawing-package]: [site guide source][drawing-guide] · local relationship maps, magic circles, sigils, sacred geometry, and card spreads.
@@ -2069,6 +2278,7 @@ The [site guide source files][package-guides] describe installation, requirement
 - [pi-roundtable-web][web-package]: [site guide source][web-guide] · an owner-only console for conversations, transcripts, and memory notes with live updates.
 - [pi-roundtable-sandbox][sandbox-package]: [site guide source][sandbox-guide] · sealed guest channels on native Linux Docker with a host-only credential broker and allow-listed tools.
 - [pi-roundtable-mcp][mcp-package]: [site guide source][mcp-guide] · MCP connectors through a gateway and remote MCP endpoints for agent turns and owner-granted Discord channel tools.
+- [pi-roundtable-webchat][webchat-package]: [site guide source][webchat-guide] · a WebSocket chat for people an OpenID Connect provider signs in, with private conversations, live progress, and approval cards; see [web chat](#web-chat-pi-roundtable-webchat).
 
 [drawing-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/drawing/README.md
 [coding-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/coding/README.md
@@ -2081,6 +2291,7 @@ The [site guide source files][package-guides] describe installation, requirement
 [web-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/web-package.mdx
 [sandbox-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/sandbox-package.mdx
 [mcp-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/mcp-package.mdx
+[webchat-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/webchat-package.mdx
 [coding-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/coding
 [sandbox-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/sandbox
 [web-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/web
@@ -2170,7 +2381,7 @@ After setup, `conversations` routes to the plugin's claims, `surfaces` contains
 | `database` | A Bun `SQL` for `context.database()`; without one it throws `no database is configured` |
 | `providers` | Provider slots filled as if another plugin filled them |
 | `surfaces` | Chat surfaces besides the plugin's own, such as the fake surface of `examples/fake-surface.ts`: they are in `context.surfaces`, start after the plugin's services with the harness routing their messages to `conversations`, and stop with `stop()` |
-| `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 |
+| `services` | What the plugin reads from `context.services`: one `servicePair(KEY, { ... })` for each service, with the members you give it. `servicePair(RUNTIME, runtime)` is the runtime `context.turns` runs on, given whole; `servicePair(AGENTS, { runtime })` also works when no `RUNTIME` is given. 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 |
@@ -2239,7 +2450,7 @@ Only `commands` and `guard` are given; a plugin that reads another member of `DI
 
 `testPlugin` sets up your plugin alone.
 For tests that need the agent server, modules, stores, or the host's session-tool setup order, use `testHost(options?)`.
-It boots `defineRoundtable` over `ROUNDTABLE_TEST_DATABASE_URL`, with stand-ins for Discord and the runtime; gate the suite with `describeDb`:
+It boots `defineRoundtable` over `ROUNDTABLE_TEST_DATABASE_URL`, with stand-ins for Discord and the runtime, or without Discord; gate the suite with `describeDb`:
 
 | Option | What it gives the host |
 |---|---|
@@ -2247,7 +2458,7 @@ It boots `defineRoundtable` over `ROUNDTABLE_TEST_DATABASE_URL`, with stand-ins
 | `plugins` | Your plugins, placed after the built-in ones as `defineRoundtable` places them |
 | `runtime` | The runtime every turn runs on; by default one that answers `""` and builds no Pi session |
 | `apiKeys` | The credentials `context.apiKey(provider)` returns, by provider name; a provider not listed reads as having none, whatever login the machine holds |
-| `discord` | What the stand-in Discord hands out: `agentChannels(guildId)` and `ownerChannel()` |
+| `discord` | What the stand-in Discord hands out: `agentChannels(guildId)` and `ownerChannel()`; `false` boots a [host without Discord](#a-host-without-discord), with no `discord`, `http`, or `agents` in the test configuration |
 
 It returns:
 
@@ -2266,6 +2477,15 @@ It returns:
 
 `holdChain(rules)` is in `pi-roundtable/kit`: the chain the host links from every plugin's hold rules, to test a rule set without a harness.
 
+### `describeSurfaceContract`: what every chat surface keeps
+
+A plugin that contributes a `ChatSurface` can test it against the contract every surface keeps.
+`describeSurfaceContract(name, make)` registers one test per check, each on a fresh `SurfaceContractSubject` from `make`: the `surface`, a `channel` of it, and one person on its network, who can `write(text)`, whose `observations()` list what they have seen (`SurfaceObservation`: a reply's text and file names, typing and stop controls going on and off, progress, and prompts opening and closing), and who may `answer(prompt, approved)` an approval; `speaker` is who they are to `surface.prompts`, an owner by default, and every approval the contract asks for needs exactly their tier. `stranger`, when given, is someone else on the network, not the owner, who knows the id of the person's open approval and may `join()` and `answer(prompt, approved)` it.
+The contract starts the surface, calls the subject's `join()`, and stops the surface after the subject's `close()`.
+It checks that the surface names a prefix and owns its channel, delivers what the person writes, and shows every chunk of a reply; and, for the parts the surface offers, that it delivers files when `supportsFiles` is set, ends typing and stop controls idempotently, shows progress, and resolves an approval as the person approves or declines it, or `cancelled` when the turn stops, and, with a `stranger`, that the stranger's answer leaves the person's approval open.
+A check for a part the surface does not offer passes.
+`checkSurfaceContract(make)` runs the same checks and returns the ones that failed, as `SurfaceContractFailure`s.
+
 ## What happens when the bot starts and stops
 
 `roundtable start` checks Bun, `.env`, the configuration, the plugins, the model login, and the public URL without using the network.
@@ -2274,10 +2494,10 @@ The host's `run()` handles startup:
 
 1. Each plugin's `replaces` is applied: the plugin that provided a replaced service is dropped, and the replacement stands where it stood.
    Providers are then resolved: each slot from the plugin that fills it, or the core's default.
-   The agent server builds its runtime later, in its own setup: from the `runtime` slot when a plugin fills it, else the Pi runtime.
+   The runtime plugin builds the runtime later, in its own setup: from the `runtime` slot when a plugin fills it, else the Pi runtime.
 2. The database is opened and every plugin's migrations run, in plugin order.
 3. Every plugin's `setup` runs, in plugin order.
-   The order is the built-ins (`memory`, `schedule-store`, `discord`, `modules`, `discord-admin`, `skills`, `agent-server`, `seeds`; an addon that is switched off is not there), then yours in the order of `plugins` in `roundtable.config.ts`, then the built-in `schedules`, so a due schedule fires only once everything it can reach is running.
+   The order is the built-ins (`memory`, `schedule-store`, `prechecks`, `discord`, `modules`, `discord-admin`, `skills`, `conversations`, `runtime`, `agent-server`, `seeds`; an addon that is switched off is not there, and without Discord neither are `discord`, `discord-admin`, `skills`, `agent-server`, or `seeds`), then yours in the order of `plugins` in `roundtable.config.ts`, then the built-in `schedules`, so a due schedule fires only once everything it can reach is running.
 4. The contributions are linked: tool tiers, hold rules, the session plan, the channel router, and the events.
    From here `sessions()`, `conversations`, `surfaces`, `turns`, and `dashboard()` work.
 5. Every plugin's `preflight` runs, in plugin order.
@@ -2357,9 +2577,9 @@ These are the messages as the code writes them, with `<...>` where your names go
 | `plugin <b>: background target "<name>" is already registered by plugin <a>. Keep one target per name.` | Give each background target one plugin, or rename one of them |
 | `no plugin contributes the background target "<name>"` (a schedule's last status, or a skipped turn) | Contribute the target from the plugin whose claim serves it, or cancel the schedule |
 | `no persona is registered for the conversation kind "<kind>". A plugin adds one with personas: [...], or its claim must start conversations of a kind that has one.` (a failed turn) | Contribute a persona of that kind, or run the turn with a kind that has one |
-| `no runtime provider is configured: the agent server builds the Pi runtime when no plugin fills the runtime slot` | Only a plugin that calls `providers.runtime` without `providers.filled.has("runtime")` sees it; check `filled` first |
+| `no runtime provider is configured: the runtime plugin builds the Pi runtime when no plugin fills the runtime slot; read the running one from services.get(RUNTIME)` | Only a plugin that calls `providers.runtime` without `providers.filled.has("runtime")` sees it; read `services.get(RUNTIME)` instead |
 | `session tool <name> takes a core extension name. Rename it.` | Pick a name other than the core's |
-| `two plugins are named <name>.` (from `roundtable doctor`) | Rename yours; the built-in plugins are `memory`, `schedule-store`, `discord`, `modules`, `discord-admin`, `skills`, `agent-server`, `seeds`, and `schedules` |
+| `two plugins are named <name>.` (from `roundtable doctor`) | Rename yours; the built-in plugins are `memory`, `schedule-store`, `prechecks`, `discord`, `modules`, `discord-admin`, `skills`, `conversations`, `runtime`, `agent-server`, `seeds`, and `schedules` |
 | `migration <plugin>/<name> is declared twice` | A plugin declares two migrations with one name: rename one (the same name in two plugins is fine) |
 | `/<root> <name> is added twice`, `/<name> is registered twice` | Give each slash command and subcommand its own name |
 | `route <name> is registered twice`, `routes <a> and <b> overlap on listener <id>` | Give each route its own name and a path no other route can take |
@@ -2405,6 +2625,9 @@ Migrations are idempotent, so start again once the cause is fixed.
 | `config model: expected <provider>/<id>, got "<value>". Write it like anthropic/claude-sonnet-5-5.` | Write the model as `<provider>/<id>` |
 | `config locale: expected a locale, en or zh-TW, got "<value>". Fix the value in roundtable.config.ts.` | Use `en` or `zh-TW` |
 | `config <key>: cannot read <path>: <reason>. Create the file or fix the path.` | Create the prompt file, or fix the path in `prompts` |
+| `config adapters[<n>]: unknown adapter "<name>". The adapters are discord; …` | Use `discord()` from `pi-roundtable/discord`; a chat network that comes as a plugin, such as `webChat()`, belongs in `plugins` |
+| `config adapters[<n>]: Discord is configured twice, …` | Keep the top-level `discord` or the Discord adapter, not both |
+| `required tools are not registered: compact_session. compact_session comes from the Pi package pi-self-compact: …` | `bun add pi-self-compact`, and load it from a plugin with `piPackages: ["pi-self-compact"]`, as a project `roundtable init` creates does in `plugins/self-compact.ts` |
 
 ### Missing settings
 
@@ -2488,6 +2711,7 @@ Import from the entries listed below; source area files are internal.
 | `AGENT_SERVER_PLUGIN` | `pi-roundtable` | value |
 | `AGENT_SERVER_PRIORITY` | `pi-roundtable` | value |
 | `AGENT_TEAM_SERVICE` | `pi-roundtable` | value |
+| `AdapterConfig` | `pi-roundtable` | type |
 | `Admission` | `pi-roundtable` | type |
 | `Agent` | `pi-roundtable` | type |
 | `AgentChange` | `pi-roundtable` | type |
@@ -2508,6 +2732,7 @@ Import from the entries listed below; source area files are internal.
 | `AvatarMode` | `pi-roundtable` | type |
 | `AvatarStudio` | `pi-roundtable` | type |
 | `BACKGROUND_TURNS` | `pi-roundtable` | value |
+| `CONVERSATIONS` | `pi-roundtable` | value |
 | `BackgroundTarget` | `pi-roundtable` | type |
 | `BackgroundTurn` | `pi-roundtable` | type |
 | `BackgroundTurns` | `pi-roundtable` | type |
@@ -2519,6 +2744,10 @@ Import from the entries listed below; source area files are internal.
 | `Contribution` | `pi-roundtable` | type |
 | `ConversationKind` | `pi-roundtable` | type |
 | `ConversationPort` | `pi-roundtable` | type |
+| `ConversationRecord` | `pi-roundtable` | type |
+| `ConversationRegistration` | `pi-roundtable` | type |
+| `ConversationRegistry` | `pi-roundtable` | type |
+| `ConversationVisibility` | `pi-roundtable` | type |
 | `ConversationTurnInput` | `pi-roundtable` | type |
 | `ConversationTurns` | `pi-roundtable` | type |
 | `DELEGATION` | `pi-roundtable` | value |
@@ -2529,6 +2758,7 @@ Import from the entries listed below; source area files are internal.
 | `DelegationOutcome` | `pi-roundtable` | type |
 | `DelegationRequest` | `pi-roundtable` | type |
 | `Delegator` | `pi-roundtable` | type |
+| `DiscordConfig` | `pi-roundtable` | type |
 | `DrainOptions` | `pi-roundtable` | type |
 | `EventHandlers` | `pi-roundtable` | type |
 | `EventSink` | `pi-roundtable` | type |
@@ -2597,10 +2827,12 @@ Import from the entries listed below; source area files are internal.
 | `RoundtableConfig` | `pi-roundtable` | type |
 | `RoundtableOptions` | `pi-roundtable` | type |
 | `RoundtablePlugin` | `pi-roundtable` | type |
+| `RouteSocket` | `pi-roundtable` | type |
 | `RuntimeDeps` | `pi-roundtable` | type |
 | `RuntimeFactory` | `pi-roundtable` | type |
 | `SCHEDULES` | `pi-roundtable` | value |
 | `PRECHECKS` | `pi-roundtable` | value |
+| `RUNTIME` | `pi-roundtable` | value |
 | `PRECHECK_TIMEOUT_MS` | `pi-roundtable` | value |
 | `Precheck` | `pi-roundtable` | type |
 | `PrecheckContext` | `pi-roundtable` | type |
@@ -2654,10 +2886,15 @@ Import from the entries listed below; source area files are internal.
 | `TransientTask` | `pi-roundtable` | type |
 | `TurnAttachments` | `pi-roundtable` | type |
 | `TurnEndEvent` | `pi-roundtable` | type |
+| `TurnProgress` | `pi-roundtable` | type |
+| `TurnProgressEvent` | `pi-roundtable` | type |
 | `TurnEvent` | `pi-roundtable` | type |
 | `TurnRequest` | `pi-roundtable` | type |
 | `TurnResult` | `pi-roundtable` | type |
 | `TurnSelection` | `pi-roundtable` | type |
+| `WebSocketAccept` | `pi-roundtable` | type |
+| `WebSocketRoute` | `pi-roundtable` | type |
+| `WebSocketSendResult` | `pi-roundtable` | type |
 | `Weekday` | `pi-roundtable` | type |
 | `attachReplyFile` | `pi-roundtable` | value |
 | `withReplyFiles` | `pi-roundtable` | value |
@@ -2684,6 +2921,11 @@ Import from the entries listed below; source area files are internal.
 | `TestPluginResult` | `pi-roundtable/testing` | type |
 | `TestStore` | `pi-roundtable/testing` | type |
 | `describeDb` | `pi-roundtable/testing` | value |
+| `describeSurfaceContract` | `pi-roundtable/testing` | value |
+| `checkSurfaceContract` | `pi-roundtable/testing` | value |
+| `SurfaceContractFailure` | `pi-roundtable/testing` | type |
+| `SurfaceContractSubject` | `pi-roundtable/testing` | type |
+| `SurfaceObservation` | `pi-roundtable/testing` | type |
 | `eagerText` | `pi-roundtable/testing` | value |
 | `fakeDiscord` | `pi-roundtable/testing` | value |
 | `fakePrecheck` | `pi-roundtable/testing` | value |
@@ -2844,6 +3086,7 @@ Import from the entries listed below; source area files are internal.
 | `ComposedCommands` | `pi-roundtable/discord` | type |
 | `DISCORD` | `pi-roundtable/discord` | value |
 | `DISCORD_ADMIN_TOOLS` | `pi-roundtable/discord` | value |
+| `DiscordAdapterConfig` | `pi-roundtable/discord` | type |
 | `DiscordConnection` | `pi-roundtable/discord` | type |
 | `DiscordServices` | `pi-roundtable/discord` | type |
 | `InteractionContribution` | `pi-roundtable/discord` | type |
@@ -2858,6 +3101,7 @@ Import from the entries listed below; source area files are internal.
 | `agentPanel` | `pi-roundtable/discord` | value |
 | `commandGuard` | `pi-roundtable/discord` | value |
 | `composeCommands` | `pi-roundtable/discord` | value |
+| `discord` | `pi-roundtable/discord` | value |
 | `ephemeralPanel` | `pi-roundtable/discord` | value |
 | `fetchManagedChannel` | `pi-roundtable/discord` | value |
 | `groupOption` | `pi-roundtable/discord` | value |

package/examples/discord-adapter.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from "bun:test";
+import { $ } from "bun";
+import { defineRoundtable, type RoundtableConfig } from "pi-roundtable";
+import { silentLogger } from "pi-roundtable/testing";
+import { withDiscordAdapter } from "./discord-adapter.ts";
+
+const ENV: Record<string, string> = {
+	OWNER_ID: "100000000000000001",
+	OWNER_NAME: "Ada",
+	DISCORD_TOKEN: "token",
+	DISCORD_GUILD_ID: "900000000000000001",
+	DISCORD_ENTRY_CHANNEL_ID: "900000000000000002",
+	DATABASE_URL: "postgres://localhost/roundtable",
+	MODEL: "anthropic/claude-sonnet-5-5",
+	PUBLIC_URL: "https://bot.example.com",
+};
+
+test("a Discord adapter assembles the plugins the top-level discord does, in the same order", async () => {
+	const dataDir = `${Bun.env.TMPDIR ?? "/tmp"}/discord-adapter-${crypto.randomUUID()}`;
+	const adapted = withDiscordAdapter((name) => ENV[name] ?? "", dataDir);
+	const { adapters: _adapters, ...rest } = adapted;
+	const topLevel: RoundtableConfig = {
+		...rest,
+		discord: {
+			token: "token",
+			guild: "900000000000000001",
+			entryChannel: "900000000000000002",
+		},
+	};
+	const names = async (config: RoundtableConfig) =>
+		(await defineRoundtable(config, { logger: silentLogger() })).plugins.map(
+			(plugin) => plugin.name,
+		);
+	try {
+		const plugins = await names(adapted);
+		expect(plugins).toContain("discord");
+		expect(plugins).toContain("agent-server");
+		expect(plugins).toEqual(await names(topLevel));
+	} finally {
+		await $`rm -rf ${dataDir}`;
+	}
+});

package/examples/discord-adapter.ts

@@ -0,0 +1,26 @@
+import type { RoundtableConfig } from "pi-roundtable";
+import { discord } from "pi-roundtable/discord";
+
+/**
+ * Discord as an adapter: `discord()` takes the same settings as the top-level `discord`, and the
+ * host assembles the same plugins in the same order. Configure Discord in one place, not both.
+ */
+export function withDiscordAdapter(
+	env: (name: string) => string,
+	dataDir: string,
+): RoundtableConfig {
+	return {
+		owner: { id: env("OWNER_ID"), name: env("OWNER_NAME") },
+		adapters: [
+			discord({
+				token: env("DISCORD_TOKEN"),
+				guild: env("DISCORD_GUILD_ID"),
+				entryChannel: env("DISCORD_ENTRY_CHANNEL_ID"),
+			}),
+		],
+		database: { url: env("DATABASE_URL") },
+		dataDir,
+		model: env("MODEL"),
+		http: { publicUrl: env("PUBLIC_URL") },
+	};
+}

package/examples/echo-runtime.ts

@@ -98,7 +98,7 @@ export const createEchoRuntime: RuntimeFactory = (deps) => {
 
 /**
  * A plugin fills the `runtime` slot to replace the whole conversation runtime; without one the
- * agent server builds the Pi runtime. One plugin may fill it.
+ * runtime plugin builds the Pi runtime. One plugin may fill it.
  */
 export const echoRuntime = definePlugin({
 	name: "echo-runtime",