pi-roundtable 0.1.0

package/examples/channels.test.ts

@@ -0,0 +1,13 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { echo } from "./channels.ts";
+
+test("the claim owns channels of its surface and admits their messages as turns", async () => {
+	const harness = await testPlugin(echo);
+	const [claim] = harness.contribution.channels ?? [];
+	expect(claim?.owns("echo:1")).toBe(true);
+	expect(claim?.owns("discord:1")).toBe(false);
+	const admitted = claim?.admit({ text: "hi" } as never);
+	expect(admitted?.kind).toBe("turn");
+	await harness.stop();
+});

package/examples/channels.ts

@@ -0,0 +1,27 @@
+import { definePlugin } from "pi-roundtable";
+
+/**
+ * A channel claim makes a plugin the owner of the conversations in some channels. The router
+ * asks claims by descending priority; the first that owns a channel decides everything there,
+ * and a message its `admit` returns nothing for is dropped.
+ */
+export const echo = definePlugin({
+	name: "echo",
+	setup: () => ({
+		channels: [
+			{
+				name: "echo-channels",
+				priority: 10,
+				owns: (channel) => channel.startsWith("echo:"),
+				admit: (message) => ({
+					kind: "turn",
+					run: async () => {
+						console.log(`echo: ${message.text}`);
+					},
+					failure: "an echo turn failed",
+				}),
+				startFresh: async () => "The echo channel has nothing to start over.",
+			},
+		],
+	}),
+});

package/examples/dashboard.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { links } from "./dashboard.ts";
+
+test("the plugin adds one line to the dashboard", async () => {
+	const harness = await testPlugin(links);
+	expect(harness.contribution.dashboard).toEqual([
+		"Docs: https://example.com/docs",
+	]);
+	await harness.stop();
+});

package/examples/dashboard.ts

@@ -0,0 +1,9 @@
+import { definePlugin } from "pi-roundtable";
+
+/** Dashboard lines are shown under the title of the agent server's dashboard message, in plugin order. */
+export const links = definePlugin({
+	name: "links",
+	setup: () => ({
+		dashboard: ["Docs: https://example.com/docs"],
+	}),
+});

package/examples/events.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { turnLog } from "./events.ts";
+
+test("the handlers record a turn, a team change, and the shutdown", async () => {
+	const lines: string[] = [];
+	const harness = await testPlugin(turnLog(lines));
+	const { events } = harness.contribution;
+	// The harness does not deliver the core's events: call the handlers with the payload the core sends.
+	const turn = {
+		agent: "guide",
+		channel: "discord:1",
+		speaker: undefined,
+	} as const;
+	await events?.turnStarted?.(turn);
+	await events?.turnEnded?.({ ...turn, result: "ok" });
+	await events?.changed?.();
+	// stop() delivers shutdown(left) with an empty list, then stops the services.
+	await harness.stop();
+	expect(lines).toEqual([
+		"guide started",
+		"guide ok",
+		"team changed",
+		"shutdown, 0 unfinished",
+	]);
+});

package/examples/events.ts

@@ -0,0 +1,25 @@
+import { definePlugin } from "pi-roundtable";
+
+/** Handlers hear what the core does. One that throws is logged and never stops the others. */
+export function turnLog(lines: string[]) {
+	return definePlugin({
+		name: "turn-log",
+		setup: () => ({
+			events: {
+				turnStarted: (turn) => {
+					lines.push(`${turn.agent} started`);
+				},
+				turnEnded: (turn) => {
+					lines.push(`${turn.agent} ${turn.result}`);
+				},
+				changed: () => {
+					lines.push("team changed");
+				},
+				// The drain is over, and no service has stopped yet.
+				shutdown: (left) => {
+					lines.push(`shutdown, ${left.length} unfinished`);
+				},
+			},
+		}),
+	});
+}

package/examples/guide.test.ts

@@ -0,0 +1,52 @@
+import { expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const root = join(import.meta.dir, "..");
+const guide = readFileSync(join(root, "docs/plugins.md"), "utf8");
+const files = readdirSync(import.meta.dir).filter((name) =>
+	name.endsWith(".ts"),
+);
+const examples = files.filter(
+	(name) => !name.endsWith(".test.ts") && name !== "guide.test.ts",
+);
+
+/** The guide embeds a file as a `ts` block between these two markers. */
+const MARKER = /<!-- example: (\S+) -->/g;
+const BLOCK =
+	/<!-- example: (\S+) -->\n```ts\n([\s\S]*?)\n```\n<!-- \/example -->/g;
+
+test("every marker in the guide wraps one ts block", () => {
+	expect([...guide.matchAll(BLOCK)].length).toBe(
+		[...guide.matchAll(MARKER)].length,
+	);
+	expect([...guide.matchAll(MARKER)].length).toBeGreaterThan(0);
+});
+
+test("every block in the guide is exactly the file it names", () => {
+	for (const [, path, embedded] of guide.matchAll(BLOCK)) {
+		const file = readFileSync(join(root, path as string), "utf8");
+		expect({ path, code: embedded }).toEqual({ path, code: file.trimEnd() });
+	}
+});
+
+test("every example is embedded in the guide and has a test beside it", () => {
+	const embedded = [...guide.matchAll(MARKER)].map((match) => match[1]);
+	for (const name of examples) {
+		expect(embedded).toContain(`examples/${name}`);
+		expect(files).toContain(name.replace(/\.ts$/, ".test.ts"));
+	}
+});
+
+test("examples import only the public entries, typebox, bun, and their neighbors", () => {
+	for (const name of files.filter((file) => file !== "guide.test.ts")) {
+		const source = readFileSync(join(import.meta.dir, name), "utf8");
+		for (const [, specifier] of source.matchAll(/from "([^"]+)"/g))
+			expect({ name, specifier }).toEqual({
+				name,
+				specifier: expect.stringMatching(
+					/^(pi-roundtable|pi-roundtable\/testing|typebox|bun|bun:test|\.\/[a-z-]+\.ts)$/,
+				),
+			});
+	}
+});

package/examples/holds.test.ts

@@ -0,0 +1,16 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { cleanup } from "./holds.ts";
+
+test("a tool's hold and a hold rule each describe the call that must wait", async () => {
+	const harness = await testPlugin(cleanup);
+	const rules = harness.contribution.holdRules ?? [];
+	const describe = (tool: string, input: Record<string, unknown>) =>
+		rules.flatMap((rule) => rule.describe(tool, input, {}) ?? []);
+	expect(describe("file_delete", { path: "a.txt" })).toEqual(["Delete a.txt"]);
+	expect(describe("bash", { command: "restart production" })).toEqual([
+		"bash touches production",
+	]);
+	expect(describe("bash", { command: "ls" })).toEqual([]);
+	await harness.stop();
+});

package/examples/holds.ts

@@ -0,0 +1,30 @@
+import { definePlugin, defineTool } from "pi-roundtable";
+import { Type } from "typebox";
+
+/** Holds make a call wait for the owner's approval; the description is what the owner is asked to approve. */
+export const cleanup = definePlugin({
+	name: "cleanup",
+	setup: () => ({
+		tools: [
+			defineTool({
+				name: "file_delete",
+				description: "Delete a file in the shared workspace.",
+				parameters: Type.Object({ path: Type.String() }),
+				minTier: "admin",
+				// Returning text holds this call; returning undefined lets it run.
+				hold: ({ path }) => `Delete ${path}`,
+				run: ({ path }) => `Deleted ${path}.`,
+			}),
+		],
+		// A rule sees every tool call, whoever defined the tool.
+		holdRules: [
+			{
+				name: "cleanup-production",
+				describe: (tool, input) =>
+					JSON.stringify(input).includes("production")
+						? `${tool} touches production`
+						: undefined,
+			},
+		],
+	}),
+});

package/examples/http.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { health } from "./http.ts";
+
+test("the route answers GET /healthz", async () => {
+	const harness = await testPlugin(health);
+	const route = harness.contribution.http?.[0];
+	expect(route?.listener).toBe("public");
+	const response = await route?.handle(new Request("http://localhost/healthz"));
+	expect(await response?.text()).toBe("ok");
+	await harness.stop();
+});

package/examples/http.ts

@@ -0,0 +1,17 @@
+import { definePlugin } from "pi-roundtable";
+
+/** A route answers requests on a listener the host runs; "public" is the one the configuration's `http` block opens. */
+export const health = definePlugin({
+	name: "health",
+	setup: () => ({
+		http: [
+			{
+				name: "health-check",
+				listener: "public",
+				path: { exact: "/healthz" },
+				methods: ["GET"],
+				handle: () => new Response("ok"),
+			},
+		],
+	}),
+});

package/examples/interactions.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { ping } from "./interactions.ts";
+
+/** The parts of a Discord interaction the module reads. */
+function fake(subcommand: string, replies: string[]) {
+	return {
+		isChatInputCommand: () => true,
+		options: { getSubcommand: () => subcommand },
+		reply: async (text: string) => {
+			replies.push(text);
+		},
+	} as never;
+}
+
+test("the module answers /roundtable ping and ignores other subcommands", async () => {
+	const harness = await testPlugin(ping);
+	const [added] = harness.contribution.interactions ?? [];
+	expect(added?.rootOptions?.map((option) => option.name)).toEqual(["ping"]);
+	const replies: string[] = [];
+	expect(await added?.module.handle(fake("ping", replies))).toBe(true);
+	expect(await added?.module.handle(fake("other", replies))).toBe(false);
+	expect(replies).toEqual(["pong"]);
+	await harness.stop();
+});

package/examples/interactions.ts

@@ -0,0 +1,28 @@
+import { definePlugin } from "pi-roundtable";
+
+/**
+ * Interactions add slash commands. A subcommand goes under the one root command (`/roundtable`
+ * by default); the module answers the interactions Discord sends and returns true for the ones it handled.
+ */
+export const ping = definePlugin({
+	name: "ping",
+	setup: () => ({
+		interactions: [
+			{
+				rootOptions: [
+					{ type: 1, name: "ping", description: "Check that the bot answers" },
+				],
+				module: {
+					commands: () => [],
+					handle: async (interaction) => {
+						if (!interaction.isChatInputCommand()) return false;
+						if (interaction.options.getSubcommand(false) !== "ping")
+							return false;
+						await interaction.reply("pong");
+						return true;
+					},
+				},
+			},
+		],
+	}),
+});

package/examples/migrations.test.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "bun:test";
+import { SQL } from "bun";
+import { testPlugin } from "pi-roundtable/testing";
+import { visitCounter } from "./migrations.ts";
+
+const url = process.env.ROUNDTABLE_TEST_DATABASE_URL;
+
+// The harness gives the plugin your database but does not migrate it: run the migrations first.
+test.skipIf(!url)(
+	"the tool counts visits in the plugin's own table",
+	async () => {
+		const sql = new SQL(url as string);
+		try {
+			for (const migration of visitCounter.migrations ?? []) {
+				await migration.up(sql);
+				await migration.up(sql); // Idempotent: the host runs it on every start.
+			}
+			const harness = await testPlugin(visitCounter, { database: sql });
+			expect(await harness.runTool("visit_count", { place: "lab" })).toBe(
+				"Visit 1 to lab.",
+			);
+			expect(await harness.runTool("visit_count", { place: "lab" })).toBe(
+				"Visit 2 to lab.",
+			);
+			await harness.stop();
+		} finally {
+			await sql`DROP TABLE IF EXISTS visit_counter`;
+			await sql.close();
+		}
+	},
+);

package/examples/migrations.ts

@@ -0,0 +1,42 @@
+import { definePlugin, defineTool } from "pi-roundtable";
+import { Type } from "typebox";
+
+/**
+ * Migrations create the plugin's tables before any setup runs, on every start, so they must be
+ * idempotent. Their names and the tables are shared with every other plugin: prefix them.
+ */
+export const visitCounter = definePlugin({
+	name: "visit-counter",
+	migrations: [
+		{
+			name: "visit-counter-1-create",
+			up: async (sql) => {
+				await sql`CREATE TABLE IF NOT EXISTS visit_counter (
+					channel text PRIMARY KEY,
+					visits integer NOT NULL DEFAULT 0
+				)`;
+			},
+		},
+	],
+	setup: (context) => {
+		// The host's one connection pool, already migrated.
+		const sql = context.database();
+		return {
+			tools: [
+				defineTool({
+					name: "visit_count",
+					description: "Count a visit to a place and say which visit it is.",
+					parameters: Type.Object({ place: Type.String() }),
+					minTier: "member",
+					run: async ({ place }) => {
+						const [row] = await sql`
+							INSERT INTO visit_counter (channel, visits) VALUES (${place}, 1)
+							ON CONFLICT (channel) DO UPDATE SET visits = visit_counter.visits + 1
+							RETURNING visits`;
+						return `Visit ${row?.visits} to ${place}.`;
+					},
+				}),
+			],
+		};
+	},
+});

package/examples/packages.test.ts

@@ -0,0 +1,9 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { webSearch } from "./packages.ts";
+
+test("the plugin asks every session to load pi-web-access", async () => {
+	const harness = await testPlugin(webSearch);
+	expect(harness.contribution.piPackages).toEqual(["pi-web-access"]);
+	await harness.stop();
+});

package/examples/packages.ts

@@ -0,0 +1,9 @@
+import { definePlugin } from "pi-roundtable";
+
+/** Pi packages are npm packages whose Pi extensions every session loads; install each one in your project first. */
+export const webSearch = definePlugin({
+	name: "web-search",
+	setup: () => ({
+		piPackages: ["pi-web-access"],
+	}),
+});

package/examples/preflight.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test";
+import { needsKey } from "./preflight.ts";
+
+test("the preflight passes with the key and throws without it", () => {
+	expect(() =>
+		needsKey("API_KEY", { API_KEY: "x" }).preflight?.(),
+	).not.toThrow();
+	expect(() => needsKey("API_KEY", {}).preflight?.()).toThrow(
+		"API_KEY is empty. Set it in .env.",
+	);
+});

package/examples/preflight.ts

@@ -0,0 +1,19 @@
+import { definePlugin } from "pi-roundtable";
+
+/**
+ * A preflight runs once every plugin is set up and linked, before any command is registered or
+ * service starts. A throw stops the boot, so a bad setting is caught before Discord connects.
+ */
+export function needsKey(
+	name: string,
+	env: Record<string, string | undefined>,
+) {
+	return definePlugin({
+		name: "needs-key",
+		preflight: () => {
+			if (!env[name]?.trim())
+				throw new Error(`${name} is empty. Set it in .env.`);
+		},
+		setup: () => ({ dashboard: [`Uses ${name}`] }),
+	});
+}

package/examples/prompt.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { houseRules } from "./prompt.ts";
+
+test("the section names the agent, and the speaker when there is one", async () => {
+	const harness = await testPlugin(houseRules);
+	const section = harness.contribution.prompt?.[0];
+	const scope = {
+		name: "guide",
+		session: "discord:1",
+		home: "discord:1",
+	} as const;
+	const agent = { name: "guide", displayName: "Guide" };
+	expect(section?.build({ agent, speaker: undefined, scope })).toBe(
+		"House rules for Guide: answer in the language you were asked in.",
+	);
+	expect(
+		section?.build({
+			agent,
+			speaker: { id: "1", name: "Ada", tier: "member" },
+			scope,
+		}),
+	).toContain("You are talking with Ada.");
+	await harness.stop();
+});

package/examples/prompt.ts

@@ -0,0 +1,20 @@
+import { definePlugin } from "pi-roundtable";
+
+/** A prompt section is text added after the core's prompt in every agent turn; return undefined to add nothing. */
+export const houseRules = definePlugin({
+	name: "house-rules",
+	setup: () => ({
+		prompt: [
+			{
+				name: "house-rules",
+				build: ({ agent, speaker }) =>
+					[
+						`House rules for ${agent.displayName}: answer in the language you were asked in.`,
+						speaker ? `You are talking with ${speaker.name}.` : undefined,
+					]
+						.filter((line) => line !== undefined)
+						.join(" "),
+			},
+		],
+	}),
+});

package/examples/providers.test.ts

@@ -0,0 +1,10 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { pixelAvatars } from "./providers.ts";
+
+test("the plugin fills the images slot with PNG bytes", async () => {
+	const harness = await testPlugin(pixelAvatars);
+	const drawn = await pixelAvatars.providers?.images?.("a fox", []);
+	expect([...(drawn?.slice(1, 4) ?? [])]).toEqual([0x50, 0x4e, 0x47]);
+	await harness.stop();
+});

package/examples/providers.ts

@@ -0,0 +1,17 @@
+import { definePlugin } from "pi-roundtable";
+
+// A one-pixel PNG standing in for a real image service.
+const PIXEL = Buffer.from(
+	"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+	"base64",
+);
+
+/** A provider fills a slot the core otherwise runs on its default; one plugin may fill each slot. */
+export const pixelAvatars = definePlugin({
+	name: "pixel-avatars",
+	providers: {
+		// The images slot draws an agent's avatar from a prompt and reference pictures.
+		images: async (_prompt, _references) => new Uint8Array(PIXEL),
+	},
+	setup: () => ({}),
+});

package/examples/seeds.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { library } from "./seeds.ts";
+
+test("the plugin seeds one agent with a name, a prompt, and an avatar prompt", async () => {
+	const harness = await testPlugin(library);
+	expect(harness.contribution.seeds?.map((seed) => seed.name)).toEqual([
+		"librarian",
+	]);
+	expect(harness.contribution.seeds?.[0]?.avatarPrompt).toContain("librarian");
+	await harness.stop();
+});

package/examples/seeds.ts

@@ -0,0 +1,18 @@
+import { definePlugin } from "pi-roundtable";
+
+/** Seeds are agents created on the first start; an agent already stored is never overwritten, so edit it in Discord afterwards. */
+export const library = definePlugin({
+	name: "library",
+	setup: () => ({
+		seeds: [
+			{
+				name: "librarian",
+				displayName: "Librarian",
+				prompt:
+					"You keep the team's reading list. Answer briefly and cite what you were given.",
+				avatarPrompt:
+					"A calm librarian with round glasses and a stack of books",
+			},
+		],
+	}),
+});

package/examples/selection.test.ts

@@ -0,0 +1,13 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { alwaysOn } from "./selection.ts";
+
+test("every read of the selection sees the current tools", async () => {
+	let tools = ["note_add"];
+	const harness = await testPlugin(alwaysOn(() => tools));
+	const { agentSelection } = harness.contribution;
+	expect(agentSelection?.().tools).toEqual(["note_add"]);
+	tools = ["note_add", "file_delete"];
+	expect(agentSelection?.().tools).toEqual(["note_add", "file_delete"]);
+	await harness.stop();
+});

package/examples/selection.ts

@@ -0,0 +1,14 @@
+import { definePlugin } from "pi-roundtable";
+
+/**
+ * The selection names tools every agent turn carries besides its own, read before each turn so
+ * a set that changes while the process runs stays current.
+ */
+export function alwaysOn(tools: () => string[]) {
+	return definePlugin({
+		name: "always-on",
+		setup: () => ({
+			agentSelection: () => ({ tools: tools(), groups: [] }),
+		}),
+	});
+}

package/examples/services.test.ts

@@ -0,0 +1,20 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { heartbeat } from "./services.ts";
+
+test("the timer starts with the harness and stops with it", async () => {
+	const first = Promise.withResolvers<void>();
+	let beats = 0;
+	const harness = await testPlugin(
+		heartbeat(1, () => {
+			beats++;
+			first.resolve();
+		}),
+	);
+	await first.promise;
+	await harness.stop();
+	const stoppedAt = beats;
+	await Bun.sleep(20);
+	expect(beats).toBe(stoppedAt);
+	expect(harness.contribution.services?.[0]?.busy?.()).toEqual([]);
+});

package/examples/services.ts

@@ -0,0 +1,30 @@
+import { definePlugin } from "pi-roundtable";
+
+/** A service is a long-lived part: it starts once everything is set up and stops in reverse order at shutdown. */
+export function heartbeat(everyMs: number, beat: () => Promise<void> | void) {
+	let timer: ReturnType<typeof setInterval> | undefined;
+	let running = 0;
+	return definePlugin({
+		name: "heartbeat",
+		setup: () => ({
+			services: [
+				{
+					name: "heartbeat-timer",
+					start: () => {
+						timer = setInterval(async () => {
+							running++;
+							try {
+								await beat();
+							} finally {
+								running--;
+							}
+						}, everyMs);
+					},
+					stop: () => clearInterval(timer),
+					// Shutdown waits until this list is empty, so a beat is never cut off.
+					busy: () => (running > 0 ? ["a heartbeat is running"] : []),
+				},
+			],
+		}),
+	});
+}

package/examples/session-tools.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { clock } from "./session-tools.ts";
+
+test("the factory registers clock_now in a session", async () => {
+	const harness = await testPlugin(clock);
+	const [tool] = harness.contribution.sessionTools ?? [];
+	const registered: string[] = [];
+	const session = {
+		kind: "agent",
+		homeChannel: "test:1",
+		turnChannel: "test:1",
+		compaction: { wrap: (factory: unknown) => factory },
+		speaker: () => undefined,
+		runTask: async () => "",
+	} as never;
+	// A stand-in for Pi's extension API: it keeps the names registered.
+	const pi = {
+		registerTool: ({ name }: { name: string }) => registered.push(name),
+	};
+	tool?.snapshot().factory(session)?.(pi as never);
+	expect(registered).toEqual(["clock_now"]);
+	await harness.stop();
+});