Services and addons
Services
Section titled “Services”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.
Reading a service
Section titled “Reading a service”| 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.
Built-in services
Section titled “Built-in services”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.
Posting to Discord: DISCORD.poster
Section titled “Posting to Discord: DISCORD.poster”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:
postfinds the bot’s webhook of that name in the channel, or makes it. A webhook name and ausernameare 1 to 80 characters without “discord” or “clyde”; anything else fails asinvalidbefore a request is sent. - A post, edit, card or direct message never pings anyone it does not name:
allowed_mentionsis sent withparse: [], and only thementionsyou list can ping. - A card is a Components V2 message.
editCardkeeps it one; a message posted withsaycannot 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 animage(under the text sections), each{ url, description? }with anhttpsaddress;editCardkeeps them.postCardposts a card through a webhook of yours, under its name and picture, andeditWebhookCardedits 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’scontent, which is what a push or desktop notification shows, and the card is one embed with ordinary buttons and menus. Withoutpreviewa 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 atextchannel,category,thread,forum,forum_postorother, andInboundMessage.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.forumTagsandsetForumTagsread and replace a forum’s tags (send a tag’sidto 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, soeditCard(threadId, messageId, card)edits it;setPostTagschanges a post’s tags, andrenameChannelrenames a post. An archived post is opened again by both (in the same request), and byeditCardon its first message;editCardon any other message of an archived thread isrejected(Discord’s 50083), so callsetThreadArchived(threadId, false)first.- Discord lets a channel be renamed twice in ten minutes.
renameChanneldoes not queue a third: it fails asunavailableafter ten seconds and is never sent later. threadCloserreads the audit log (View Audit Log, elseforbidden) among the newest 50 thread updates; Discord’s own auto-archive reads asunknown.- A failure is a
DiscordPosterErrorwith akind(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().
Prechecks
Section titled “Prechecks”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.
Replacing a built-in service
Section titled “Replacing a built-in service”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.
Ops alerts
Section titled “Ops alerts”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 commandEvery 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.
Codex images
Section titled “Codex images”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.
Addons
Section titled “Addons”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.