Skip to content

Write a plugin

  1. Create the plugin. This writes plugins/<name>.ts and its test, and lists the plugin in roundtable.config.ts.

    Terminal window
    bunx roundtable add plugin hello
  2. Edit it. A plugin is an object with a name and a setup function that returns what it adds. This one gives every agent a tool:

    import { definePlugin, defineTool } from "pi-roundtable";
    import { Type } from "typebox";
    export const hello = definePlugin({
    name: "hello",
    setup: () => ({
    tools: [
    defineTool({
    name: "hello_greet",
    description: "Greet someone by name. Call it when asked to say hello.",
    parameters: Type.Object({ who: Type.String() }),
    minTier: "member",
    run: ({ who }) => `Hello, ${who}!`,
    }),
    ],
    }),
    });
  3. Test it. testPlugin runs the plugin without Discord or PostgreSQL.

    import { expect, test } from "bun:test";
    import { testPlugin } from "pi-roundtable/testing";
    import { hello } from "./hello.ts";
    test("hello greets", async () => {
    const harness = await testPlugin(hello);
    expect(await harness.runTool("hello_greet", { who: "Ada" })).toBe("Hello, Ada!");
    await harness.stop();
    });
    Terminal window
    bun test
  4. Restart the bot. Every agent can now call hello_greet.

    Terminal window
    bunx roundtable start

Ask an agent to use it, and it calls the tool:

In the guide channel, a user asks Guide to say hello to a team. Guide calls the hello_greet tool and answers Hello, Ada's team!

A tool still returns text for the model, but may also call turn.attachFile({ name, data }) to attach an image or another file to the agent’s final reply. data is a non-empty Uint8Array of raw bytes; the core copies it immediately. For example, inside an image tool’s run:

turn.attachFile({ name: "drawing.png", data: pngBytes });
return "The drawing is attached to this turn's reply.";

Do not call context.surfaces.sendReply from the tool just to send its output: that posts ahead of the agent and may use the bot’s identity. The core delivers accepted files with the successful reply; Discord posts them after the text, one per message, using the same agent webhook name and avatar. A successful final answer with files needs no text. Stopped, timed-out, and failed turns discard their files. If a tool fails but the model recovers and completes the turn, files already accepted remain queued.

The main entry exports ReplyFile, attachReplyFile(file): void, ReplyFileError, and REPLY_FILE_LIMITS. Raw session tools and Pi package tools can import attachReplyFile and call it in their awaited tool execution. A Pi package should share the host’s pi-roundtable peer dependency rather than bundle its own copy. Calls outside a conversation turn, after its end, or inside a transient runTask fail with ReplyFileError. A standalone worker can collect files with the public withReplyFiles(supported, run) around its entire awaited turn; run returns Promise<TurnResult> and the caller delivers the returned files. For admitted raster bytes, /kit exports prepareImageBytes without reopening a guest-writable path. It checks the 25 MiB encoded-byte and 64 MP decoded-header/aggregate-frame budgets before native decoding, rejecting with ImagePreparationError for a refused image. Ordinary 48 MP images remain accepted; thin 9000×1 images still downscale to a 2,000 px long side. The collector applies the same validation and discards attachments on failure or throw; do not create a separate collector per tool to bypass turn-wide limits. The limits are 10 files per turn, 10 MiB (10,485,760 bytes) per file, and 50 MiB (52,428,800 bytes) total across all tools. Empty data, non-Uint8Array data, invalid names (empty, ., .., paths, control characters, or over 255 characters), and calls exceeding limits are refused instead of dropped.

A custom ChatSurface opts in with supportsFiles: true and must deliver every OutboundReply.files entry with the reply’s identity or reject; absent or false makes attachment calls fail clearly. Network limits may be stricter; delivery failures are logged, may leave a partial message group, and are not retried. A custom ConversationTurnInput.reply callback receives successful TurnResult.files and owns their delivery. The runnable reply-files example and its test show the full plugin and testPlugin’s harness.files fixture. See the attachment contract for replacement runtime behavior and every edge case. For a complete local image tool that attaches its output, see the drawing package guide and source directory.

The plugin guide 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/, and the test suite runs each of them.

pi-roundtable/kit supplies claim, tool and presentation helpers. pi-roundtable/discord supplies the slash-command registrar, owner-command and panel helpers, and the agent panel. Both are versioned like the main entry: before 1.0 a breaking change comes in a minor release and is listed in the changelog.