pi-roundtable 0.1.0

package/src/testing.ts

@@ -0,0 +1,182 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { SQL } from "bun";
+import type { ConversationPort } from "./core/contract/channels.ts";
+import type { Providers } from "./core/contract/providers.ts";
+import { NotLinkedError, PluginError } from "./core/errors.ts";
+import { EventBus } from "./core/events.ts";
+import { silentLogger } from "./core/log.ts";
+import type {
+	Contribution,
+	LinkedSessions,
+	PluginContext,
+	RoundtablePlugin,
+	TurnEndEvent,
+	TurnEvent,
+} from "./core/plugin.ts";
+import {
+	collectContributions,
+	linkSessions,
+} from "./core/registry/contributions.ts";
+import { resolveProviders } from "./core/registry/providers.ts";
+import { ChannelQueue } from "./core/routing/channel-queue.ts";
+import { CoreRegistry } from "./core/services.ts";
+import type { SessionContext } from "./core/sessions.ts";
+import type { Speaker } from "./core/speakers.ts";
+import { type ToolTierTable, toolTiers } from "./core/tool-tiers.ts";
+
+export interface TestPluginOptions {
+	database?: SQL;
+	providers?: Partial<Providers>;
+}
+
+export interface RecordedEvent {
+	name: "turnStarted" | "turnEnded" | "changed";
+	turn?: TurnEvent | TurnEndEvent;
+}
+
+export interface TestPluginResult {
+	contribution: Contribution;
+	tools: readonly string[];
+	tiers: ToolTierTable;
+	events: RecordedEvent[];
+	runTool(
+		name: string,
+		args: Record<string, unknown>,
+		options?: { speaker?: Speaker },
+	): Promise<string>;
+	stop(): Promise<void>;
+}
+
+/** The same pre-link failures and wording the host exposes during setup. */
+const NOT_LINKED = {
+	conversations:
+		"conversations are linked once every plugin is set up. Use them from a service's start or from a handler, not during setup.",
+	sessions:
+		"session parts are linked once every plugin is set up. Call sessions() from a service's start or from a handler, not during setup.",
+	dashboard:
+		"dashboard lines are linked once every plugin is set up. Call dashboard() from a service's start or from a handler, not during setup.",
+};
+
+function unlinked(part: keyof typeof NOT_LINKED): never {
+	throw new NotLinkedError(NOT_LINKED[part]);
+}
+
+/** Build one plugin without Discord or PostgreSQL, retaining the host's validation and tier logic. */
+export async function testPlugin(
+	plugin: RoundtablePlugin,
+	options: TestPluginOptions = {},
+): Promise<TestPluginResult> {
+	const logger = silentLogger();
+	const tiers = toolTiers();
+	const bus = new EventBus(logger);
+	const events: RecordedEvent[] = [];
+	const core = new CoreRegistry();
+	let linked: LinkedSessions | undefined;
+	const conversations: ConversationPort = {
+		handle: async () => unlinked("conversations"),
+		background: async () => unlinked("conversations"),
+		startFresh: async () => unlinked("conversations"),
+		deleteConversation: async () => unlinked("conversations"),
+		stop: () => unlinked("conversations"),
+		postsInPlace: () => unlinked("conversations"),
+	};
+	const context: PluginContext = {
+		logger,
+		sessions: () => linked ?? unlinked("sessions"),
+		queue: new ChannelQueue(),
+		toolTiers: tiers,
+		events: {
+			turnStarted: (turn) => {
+				events.push({ name: "turnStarted", turn });
+				bus.sink.turnStarted(turn);
+			},
+			turnEnded: (turn) => {
+				events.push({ name: "turnEnded", turn });
+				bus.sink.turnEnded(turn);
+			},
+			changed: () => {
+				events.push({ name: "changed" });
+				bus.sink.changed();
+			},
+		},
+		conversations,
+		database: () => {
+			if (!options.database) throw new PluginError("no database is configured");
+			return options.database;
+		},
+		core,
+		providers: { ...resolveProviders([plugin]), ...options.providers },
+		dashboard: () => (linked ? registry.dashboard : unlinked("dashboard")),
+	};
+	const registry = await collectContributions([plugin], context, tiers);
+	linked = linkSessions(registry);
+	bus.link(registry.handlers);
+	const contribution: Contribution = {
+		services: registry.services,
+		events: registry.handlers[0]?.events,
+		interactions: registry.interactions,
+		http: registry.routes,
+		holdRules: registry.holdRules,
+		piPackages: registry.piPackages,
+		sessionTools: registry.sessionTools,
+		channels: registry.channels,
+		dashboard: registry.dashboard,
+		tools: registry.tools,
+		seeds: registry.seeds,
+		prompt: registry.prompt,
+		...(registry.agentSelections.length > 0
+			? { agentSelection: linked.agentSelection }
+			: {}),
+	};
+	for (const service of registry.services) await service.start?.();
+	let stopped = false;
+	return {
+		contribution,
+		tools: registry.tools.map((tool) => tool.name),
+		tiers,
+		events,
+		async runTool(name, args, runOptions) {
+			const tool = registry.tools.find((item) => item.name === name);
+			if (!tool) throw new PluginError(`tool ${name} is not registered`);
+			const registered: {
+				execute(
+					id: string,
+					params: Record<string, unknown>,
+					signal?: AbortSignal,
+				): Promise<{
+					content: readonly { type: string; text?: string }[];
+					isError?: boolean;
+				}>;
+			}[] = [];
+			const session = {
+				kind: "agent",
+				homeChannel: "test:1",
+				turnChannel: "test:1",
+				compaction: { wrap: (factory) => factory },
+				speaker: () => runOptions?.speaker,
+				runTask: async () => {
+					throw new Error("test session cannot run tasks");
+				},
+			} satisfies SessionContext;
+			const factory = tool.session.snapshot().factory(session);
+			// SAFETY: defineTool's session factory only calls registerTool; the fake captures its definition.
+			factory?.({
+				registerTool: (definition: (typeof registered)[number]) => {
+					registered.push(definition);
+				},
+			} as unknown as ExtensionAPI);
+			const execute = registered[0]?.execute;
+			if (!execute)
+				throw new PluginError(`tool ${name} did not register in the session`);
+			const result = await execute("test-call", args);
+			return result.content.map((item) => item.text ?? "").join("\n");
+		},
+		async stop() {
+			if (stopped) return;
+			stopped = true;
+			await bus.deliver("shutdown", []);
+			for (const service of registry.services.toReversed())
+				await service.stop?.();
+		},
+	};
+}

package/templates/.env.example

@@ -0,0 +1,22 @@
+# Copy this file to .env and fill it in. Bun loads .env by itself; never commit it.
+
+# Discord: https://discord.com/developers/applications (create an application, add a bot).
+# The bot needs the Message Content intent (Bot page) and an invite to your server.
+DISCORD_TOKEN=
+# Turn on Developer Mode in Discord, then right-click the server and the channel to copy their ids.
+DISCORD_GUILD_ID=
+DISCORD_ENTRY_CHANNEL_ID=
+
+# You: the one owner who can change everything (right-click your name, Copy User ID).
+OWNER_ID=
+OWNER_NAME=
+
+# PostgreSQL. This matches docker-compose.yml: run `docker compose up -d`.
+DATABASE_URL=postgres://roundtable:roundtable@localhost:5432/roundtable
+
+# The agents' model as <provider>/<id>, and the provider's API key (or log in with Pi and leave the key out).
+MODEL=anthropic/claude-sonnet-5-5
+# ANTHROPIC_API_KEY=
+
+# The address that reaches this process from the internet; it serves the agents' avatars.
+PUBLIC_URL=

package/templates/README.md

@@ -0,0 +1,11 @@
+# __PROJECT__
+
+A Discord agent server built on [pi-roundtable](https://www.npmjs.com/package/pi-roundtable).
+
+1. Install: `bun install`, then copy `.env.example` to `.env` and fill it in.
+2. Check: `bunx roundtable doctor` says what is still missing and how to fix it.
+3. Run: `bunx roundtable start`.
+
+`roundtable.config.ts` holds the settings and lists the plugins; `plugins/` holds yours.
+Add another with `bunx roundtable add plugin <name>`, and test it with `bun test`.
+The plugin guide is in `node_modules/pi-roundtable/docs/plugins.md` and on the package's page.

package/templates/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+.env
+data

package/templates/agents.ts

@@ -0,0 +1,12 @@
+import type { AgentSeed } from "pi-roundtable";
+
+// The first team. An agent that is already stored is never overwritten, so edit agents in Discord afterwards.
+export const agents: AgentSeed[] = [
+	{
+		name: "guide",
+		displayName: "Guide",
+		prompt:
+			"You are Guide, a friendly assistant. Answer briefly and ask when a request is unclear.",
+		avatarPrompt: "A friendly lighthouse keeper with a warm lantern",
+	},
+];

package/templates/biome.json.tmpl

@@ -0,0 +1,7 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.5.14/schema.json",
+	"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+	"formatter": { "indentStyle": "tab" },
+	"linter": { "rules": { "preset": "recommended" } },
+	"javascript": { "formatter": { "quoteStyle": "double" } }
+}

package/templates/docker-compose.yml

@@ -0,0 +1,16 @@
+---
+# PostgreSQL for local use; `docker compose up -d` matches DATABASE_URL in .env.example.
+services:
+  postgres:
+    image: postgres:17
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: roundtable
+      POSTGRES_PASSWORD: roundtable
+      POSTGRES_DB: roundtable
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres:/var/lib/postgresql/data
+volumes:
+  postgres:

package/templates/package.json.tmpl

@@ -0,0 +1,24 @@
+{
+	"name": "__PROJECT__",
+	"private": true,
+	"type": "module",
+	"engines": {
+		"bun": ">=1.3.0"
+	},
+	"scripts": {
+		"doctor": "roundtable doctor",
+		"start": "roundtable start",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"pi-roundtable": "__VERSION__",
+		"typebox": "1.3.34"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.14",
+		"@types/bun": "1.4.2",
+		"typescript": "7.0.2"
+	}
+}

package/templates/persona/shared.md

@@ -0,0 +1,2 @@
+You are part of a small team of assistants that lives in a Discord server.
+Be helpful, be honest about what you do not know, and keep replies short unless asked for detail.

package/templates/plugin/plugin.test.ts.tmpl

@@ -0,0 +1,13 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { __IDENT__ } from "./__NAME__.ts";
+
+test("__NAME__ adds a greeting tool for members", async () => {
+	const harness = await testPlugin(__IDENT__);
+	expect(harness.tools).toEqual(["__TOOL___greet"]);
+	expect(harness.tiers.minTier("__TOOL___greet")).toBe("member");
+	expect(await harness.runTool("__TOOL___greet", { who: "Ada" })).toBe(
+		"Hello, Ada!",
+	);
+	await harness.stop();
+});

package/templates/plugin/plugin.ts

@@ -0,0 +1,18 @@
+import { definePlugin, defineTool } from "pi-roundtable";
+import { Type } from "typebox";
+
+/** A plugin adds parts to the bot; this one adds a single tool the agents can call. */
+export const __IDENT__ = definePlugin({
+	name: "__NAME__",
+	setup: () => ({
+		tools: [
+			defineTool({
+				name: "__TOOL___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}!`,
+			}),
+		],
+	}),
+});

package/templates/roundtable.config.ts

@@ -0,0 +1,24 @@
+import type { RoundtableConfig } from "pi-roundtable";
+import { agents } from "./agents.ts";
+import { hello } from "./plugins/hello.ts";
+
+// Credentials and ids come from .env, which Bun loads on its own; nothing secret belongs in this file.
+const env = (name: string): string => process.env[name] ?? "";
+
+export default {
+	name: "Roundtable",
+	owner: { id: env("OWNER_ID"), name: env("OWNER_NAME") },
+	discord: {
+		token: env("DISCORD_TOKEN"),
+		guild: env("DISCORD_GUILD_ID"),
+		entryChannel: env("DISCORD_ENTRY_CHANNEL_ID"),
+	},
+	database: { url: env("DATABASE_URL") },
+	// Paths are relative to the project directory, where the roundtable command runs.
+	dataDir: "./data",
+	model: env("MODEL"),
+	http: { publicUrl: env("PUBLIC_URL") },
+	prompts: { shared: "./persona/shared.md" },
+	agents,
+	plugins: [hello],
+} satisfies RoundtableConfig;

package/templates/tsconfig.json.tmpl

@@ -0,0 +1,16 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleResolution": "bundler",
+		"lib": ["ESNext"],
+		"types": ["bun"],
+		"strict": true,
+		"noUncheckedIndexedAccess": true,
+		"verbatimModuleSyntax": true,
+		"allowImportingTsExtensions": true,
+		"skipLibCheck": true,
+		"noEmit": true
+	},
+	"include": ["*.ts", "plugins"]
+}