Skip to content

Services and addons

A service is something one plugin builds and others read, such as the schedule store or the agent team. Each service has a key made with serviceKey<T>(id). T is an interface, called a port. Any object with the same methods can provide the service or stand in for it in a test.

A plugin lists the keys it provides in provides, and provides each one from setup with services.provide(KEY, value). Give your key’s id a prefix of your own, because two keys with one id are one service.

export const NOTE_INDEX = serviceKey<NoteIndex>("my-notes.index");
export const notes = definePlugin({
name: "my-notes",
provides: [NOTE_INDEX],
setup: ({ services }) => {
services.provide(NOTE_INDEX, { add, all });
return { services: [{ name: "notes-ready" }] };
},
});

The full version is shared-services.ts.

Call What it does
services.get(KEY) Returns the service, or throws a PluginError that names the key and the plugin to register first.
services.find(KEY) Returns the service, or undefined when no registered plugin declares it. It still throws when a plugin declares the key but has not set up yet, because that is an ordering mistake.
services.lazy(KEY) Returns a function that gives the service once every plugin is set up. Use it when the providing plugin comes after yours, and call it from a service’s start, a handler, or another callback that runs after startup. Calling it during setup throws NotLinkedError.
services.provide(KEY, value) Only from setup, only for a key in your provides, once per key.

If you read a service with get during setup, list its key in requires. The host rejects a wrong order before any migration or setup, naming both plugins. The key must be provided by a plugin registered before yours. A service you read with find stays out of requires.

When setup returns, the host rejects the plugin if it hasn’t provided every key it declared. It rejects two plugins declaring the same key before any setup.

The built-in plugins provide these keys, all exported from pi-roundtable:

Key Provided by What it holds
AGENTS agent-server The agent team, a read-only directory, the runtime every agent turn runs on, approvals, and avatars
SKILLS skills (addon) The skills agents carry, and the registry to list, link and attach them
SCHEDULES schedule-store The stored schedules: create, get, update, remove, due, claim
PRECHECKS prechecks The host’s named prechecks: register, get, list
MEMORY memory (addon) Each speaker’s memory: list, add, search, update, remove
BACKGROUND_TURNS modules Turns nobody wrote: scheduled, delegated, and error-report turns
DELEGATION modules Starting a background task, and which channels have one running

Your plugins run after the built-ins, so they can read every key above. The Discord connection’s key, DISCORD, comes from pi-roundtable/discord, because its port names discord.js types.

DISCORD (from pi-roundtable/discord) has a poster: Discord’s REST API for your plugin’s own posts, over the Discord plugin’s own client and its rate limits. Use it from a service’s start on, not from setup (which Roundtable.check() also runs); making it sends nothing.

const { poster } = services.get(DISCORD);
const posted = await poster.post(channelId, { webhook: "relay", username: "Ann", content: "Hello" });
await poster.edit(channelId, posted.messageId, { content: "Hello again" }, ["relay"]);
  • Webhooks are yours to name: post finds the bot’s webhook of that name in the channel, or makes it. A webhook name and a username are 1 to 80 characters without “discord” or “clyde”; anything else fails as invalid before a request is sent.
  • A post, edit, card or direct message never pings anyone it does not name: allowed_mentions is sent with parse: [], and only the mentions you list can ping.
  • A card is a Components V2 message. editCard keeps it one; a message posted with say cannot become a card (rejected), and the notice Discord posts when something is pinned is the bot’s message that no one can edit.
  • A card can carry a thumbnail (a small picture beside the heading) and an image (under the text sections), each { url, description? } with an https address; editCard keeps them. postCard posts a card through a webhook of yours, under its name and picture, and editWebhookCard edits it; the webhook is the bot’s own, so the card’s buttons reach your interaction handler.
  • A card with a preview (one line of plain text) is sent as a legacy message instead: the preview is the message’s content, which is what a push or desktop notification shows, and the card is one embed with ordinary buttons and menus. Without preview a card makes a blank notification. The poster cannot change a message’s kind: a Components V2 card cannot be edited into a preview card, nor the other way round (rejected).
  • channelKind(channelId) says whether a channel is a text channel, category, thread, forum, forum_post or other, and InboundMessage.thread ({ parentId, parentKind }) says the same for a message written in a thread; answer a mention inside a thread or a forum post in place instead of starting a thread.
  • forumTags and setForumTags read and replace a forum’s tags (send a tag’s id to keep it); createForumPost(forumId, { name, card | content, appliedTags?, autoArchive? }) makes a post with its first message, a card or text, whose id is the thread’s own, so editCard(threadId, messageId, card) edits it; setPostTags changes a post’s tags, and renameChannel renames a post. An archived post is opened again by both (in the same request), and by editCard on its first message; editCard on any other message of an archived thread is rejected (Discord’s 50083), so call setThreadArchived(threadId, false) first.
  • Discord lets a channel be renamed twice in ten minutes. renameChannel does not queue a third: it fails as unavailable after ten seconds and is never sent later.
  • threadCloser reads the audit log (View Audit Log, else forbidden) among the newest 50 thread updates; Discord’s own auto-archive reads as unknown.
  • A failure is a DiscordPosterError with a kind (invalid, channel_gone, message_gone, forbidden, rejected, unavailable); its message never holds a URL or a token.

The full list of calls and rules is in Posting through DISCORD.poster in the guide. A hand-made DISCORD stand-in needs a poster too; fakeDiscord() and testHost give a fakeDiscordPoster().

A precheck decides, before a schedule’s turn, whether the agent is woken at all. Register one during setup; the agent attaches it to a schedule by name.

definePlugin({
name: "recovery-precheck",
setup: ({ services }) => {
services.get(PRECHECKS).register({
name: "health.recovery",
description: "Reads last night's HRV; wakes you when it is a fifth or more under its baseline.",
timeoutMs: 15_000,
run: async ({ schedule, firedAt, signal }) => {
const { hrv, baseline } = await readRecovery(signal);
return hrv >= baseline * 0.8
? { wake: false, note: `HRV ${hrv} ms, as usual.` }
: { wake: true, context: `HRV ${hrv} ms against ${baseline} ms.` };
},
});
return {};
},
});

{ wake: false, note? } skips the turn and posts the note as the bot’s own small message, which starts no turn. { wake: true, context } runs the turn with context under a “Precheck found” heading. A throw or a timeout (60 seconds unless timeoutMs says otherwise) runs the turn with the error. Test it with fakePrechecks() from pi-roundtable/testing, given as servicePair(PRECHECKS, registry).

To let agents write their own prechecks, register a script runner once: services.get(PRECHECKS).useScriptRunner(precheckScriptRunner({ image, runRoot, uid, gid, grant })) from pi-roundtable-sandbox. grant({ channel, target }) returns the MCP servers and tools a script for that schedule may call, never more than its agent has; the script runs in a sealed container and reaches only those.

A plugin that lists a key in both provides and replaces takes over that service. The host drops the built-in plugin that provided it and sets yours up where that plugin stood. The dropped plugin’s migrations and setup do not run. Your replacement can read services provided by plugins before it.

definePlugin({
name: "my-schedules",
provides: [SCHEDULES],
replaces: [SCHEDULES],
setup: ({ services }) => {
services.provide(SCHEDULES, myStore);
return {};
},
});

A replacement must provide all the services of the built-in plugin it replaces. For example, BACKGROUND_TURNS and DELEGATION come from the same modules plugin, so you replace them together. The guide lists each refusal message with its fix under Replacing a built-in service.

OpsAlerts from pi-roundtable/kit is not a service: a plugin builds one for the alerts of its own faults, such as a push that failed, and passes it where they are raised. It posts a short text through a sink you give it, a function that sends the text where the people who run the host read it, so it names no Discord type.

const alerts = new OpsAlerts({ sink, logger, kinds: { push: "LINE push" } });
await alerts.raise("push:group-7", "A push to a group failed.", { code: "429" });
alerts.faults(); // the last fault of each kind, for a status command

Every alert has a key, and its kind is the key’s word before the first colon. A key posts once an hour and a kind at most eight times an hour (windowMs and kindCap change both), so a fault that touches everything cannot flood the sink. What is held back is counted in faults(), never summed up in a post. An alert is posted when it is raised, a failed post (the sink throws or answers false) gives the key back so the next raise tries again, and raise never throws. info: true marks news: it posts once per key, outside the kind’s cap and outside faults().

The sink also gets what it needs to choose a picture or a route: sink(text, { kind, key, code?, info?, severity? }), where severity is "info", "warning" or "critical" as raise was given it. A sink that takes only the text still works. When the fault is over, alerts.resolve("push:group-7") gives the key back and calls the sink’s optional resolved({ kind, key }), so it can mark the posted alert as recovered, for example by editing its message; faults() then shows clearedAt for the kind. Resolving a key twice, or a key that was never posted, does nothing.

drawCodexImage and createCodexImages from pi-roundtable/kit are the client and the plugin behind the official codex-images plugin, for a project that wants to draw images itself or to build its own images provider on them. drawCodexImage takes the openai-codex login’s token, a prompt and optional reference pictures, and returns the PNG bytes with the prompt Codex says it drew:

const { data, revisedPrompt } = await drawCodexImage({ token, prompt, signal });

It aborts with signal, stops after five minutes, and refuses a response over 32 MiB. When Codex refuses a prompt it throws ImageNotGeneratedError, and the same prompt fails again. createCodexImages({ fetch?, model?, onMissingLogin? }) is the plugin: it reads the login for each drawing and passes the drawing’s signal on. It uses ChatGPT’s Codex backend, which OpenAI does not document for this use, so it can stop working without notice.

Memory, skills, and Discord administration are built-in plugins that the host adds unless the configuration switches them off. All three are on by default.

Addon Switch in roundtable.config.ts What it adds When it is off
Memory memory: false The memory table, the memory_add, memory_search and memory_remove tools, and the memory block of every system prompt No memory tools and no block
Skills skills: false The skill tables, the skill tools of agent sessions (skill_link, skill_create, agent_skills, and others), and the skills every agent carries No skill tools and no skills in any session. agent_create leaves out its skills parameter and refuses a call that passes some
Discord administration discord: { admin: false } The discord_* tools that read and manage the server, for the owner No discord_* tools

Switching an addon off leaves its tables and rows untouched. Turning it on again finds them as they were. When it is on, skills also takes the two directories and the skill packages: skills: { builtinDir, reposDir, packages }. packages names installed npm packages; every skill in their pi.skills folders is offered read-only, as { kind: "package", package } in the catalog, and startup fails with a PluginError naming the fix when a package is missing, ships no skills, or holds a name another skill already has.

A plugin of yours that can work without an addon reads its service with find, which is undefined while the addon is off. A plugin that cannot work without it uses get, which fails with a message that names the switch:

service roundtable.memory is not provided. The memory addon is switched off (config memory: false). Switch it on, or provide the service from a plugin of your own.

Switching an addon off and adding a plugin of yours that provides the same key is equivalent to replaces.

For the full text, see Services and Addons in the plugin guide.