Startup and project setup
How the bot starts
Section titled “How the bot starts”roundtable start runs the checks that need no network: Bun, .env, the configuration, the plugins, the image provider, the characters, the model login, and the public URL.
A failed check stops startup with the same message as roundtable doctor.
The host proceeds in this order:
-
Replacements and providers. The host applies each plugin’s
replaces, putting the replacement in the original plugin’s place. It resolves each provider slot from the plugin that fills it or the core’s default. -
Database and migrations. The host opens the database and runs every plugin’s migrations in plugin order.
-
Setup. Every plugin’s
setupruns, in plugin order. -
Linking. The host links tool tiers, hold rules, the session plan, the channel router, and the events. From here
sessions(),conversations,surfaces,turnsanddashboard()work. -
Preflight. Every plugin’s
preflightruns, in plugin order, and then the runtime’s own, so its check of the model and the required tools sees the tools other plugins filled in. The Discord plugin composes the slash commands here, so a clash stops startup at this step. -
Services. Every service starts, plugin by plugin in plugin order. A plugin’s chat surfaces start before its own services.
-
HTTP. The listeners open.
-
Background starts. Every service’s
startInBackgroundruns without holding up the boot, and every plugin hearsserviceStartedas each ends.
Discord connects and the listener opens after steps 1 to 5 succeed.
Plugin order
Section titled “Plugin order”Setup order is the built-in plugins first: identity, memory, schedule-store, prechecks, discord, modules, worker-sessions, discord-admin, skills, conversations, runtime, agent-server, seeds.
An addon that is switched off is not in the list, and without Discord neither are discord, discord-admin, skills, agent-server or seeds.
Your plugins follow in the order of plugins in roundtable.config.ts.
The built-in schedules plugin comes last, so a due schedule fires only once everything it can reach is running.
Text that depends on the language
Section titled “Text that depends on the language”run() applies the host’s environment to the process before anything else: the locale, the time zone, and the assistant’s name.
Build command and tool descriptions in setup or later, when those settings are available.
One host runs per process, because the message catalog and the time zone are process-wide.
A second run() while one host is running is refused.
If a step fails, the host stops what it had started, closes the database pool, and rethrows. The process exits non-zero.
How the bot stops
Section titled “How the bot stops”On SIGTERM or SIGINT the bot stops serving new work last:
-
It takes no new work at once: the channel queue closes, and a message that arrives gets one short “restarting, try again shortly” reply. It then waits until the queue is empty and no service reports
busy()work, for at most three minutes by default (drainSecondsin the configuration). Whatever is left is stopped, given ten seconds to end, logged and given up on. -
Every plugin hears
shutdown(left), while every service is still running. -
The HTTP listener closes, so no request reaches a service that has stopped.
-
Services stop in the reverse of the order they started.
-
The database pool closes.
TypeScript configuration
Section titled “TypeScript configuration”The package ships .ts source, so your compiler checks it with your project’s options.
The guide’s full tsconfig.json was tested against an installed tarball.
Use these settings:
- Set
moduleResolutiontobundler,moduletoPreserve, andtypesto["bun"]. - Turn on
strict,verbatimModuleSyntax,allowImportingTsExtensions, andnoEmit. - Keep
skipLibCheckon. Without it the tested example reports 97 dependency-declaration errors. - Keep
exactOptionalPropertyTypesandnoPropertyAccessFromIndexSignatureoff. Turning either on produces package-source errors even withskipLibCheck. - Install TypeScript and
@types/bunas development dependencies, as the generated project does.
Type-only exports need import type when verbatimModuleSyntax is on.
Copy the whole file from Consumer TypeScript configuration.
Develop the core and a host together
Section titled “Develop 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 change first, link your checkout:
# in the pi-roundtable checkoutbun link# in the hostbun link pi-roundtableThe host now imports the checkout’s source, so 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.
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.
Run the host’s checks again against the published package.
For the full text, see What happens when the bot starts and stops and Developing the core and a host together.