pi-roundtable 0.1.0

package/src/core/db/migrations.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, test } from "bun:test";
+import type { SQL } from "bun";
+import { MigrationError, PluginError } from "../errors.ts";
+import { Roundtable } from "../host.ts";
+import { silentLogger } from "../log.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import { type Migration, migrate, openPool } from "./migrations.ts";
+
+// The core cannot import a consumer's test helpers, so it reads the test database itself.
+const url = process.env.ROUNDTABLE_TEST_DATABASE_URL;
+const describeDb = url ? describe : describe.skip;
+
+/** What the promise rejected with; undefined when it resolved. */
+async function rejection(
+	promise: Promise<unknown> | undefined,
+): Promise<unknown> {
+	try {
+		await promise;
+	} catch (error) {
+		return error;
+	}
+	return undefined;
+}
+
+function recording(name: string, log: string[], fails = false): Migration {
+	return {
+		name,
+		up: async () => {
+			log.push(name);
+			if (fails) throw new Error("boom");
+		},
+	};
+}
+
+function roundtable(
+	plugins: RoundtablePlugin[],
+	database?: { url: string },
+): { host: Roundtable; exits: number[] } {
+	const exits: number[] = [];
+	const host = new Roundtable(
+		{
+			logger: silentLogger(),
+			drain: { intervalMs: 1, limitMs: 50 },
+			exit: (code) => exits.push(code),
+			...(database ? { database } : {}),
+		},
+		plugins,
+	);
+	return { host, exits };
+}
+
+describe("migrate", () => {
+	// A pool connects on its first query, so these never reach a server.
+	const unreachable = () => openPool("postgres://nobody@127.0.0.1:1/none");
+
+	test("runs the migrations in order", async () => {
+		const log: string[] = [];
+		const sql = unreachable();
+		await migrate(sql, [recording("a", log), recording("b", log)]);
+		await sql.close();
+		expect(log).toEqual(["a", "b"]);
+	});
+
+	test("refuses a name declared twice before running any", async () => {
+		const log: string[] = [];
+		const sql = unreachable();
+		const error = await rejection(
+			migrate(sql, [recording("a", log), recording("a", log)]),
+		);
+		await sql.close();
+		expect(error).toBeInstanceOf(PluginError);
+		expect(log).toEqual([]);
+	});
+
+	test("stops at a failing migration and names it", async () => {
+		const log: string[] = [];
+		const sql = unreachable();
+		const error = await rejection(
+			migrate(sql, [recording("a", log, true), recording("b", log)]),
+		);
+		await sql.close();
+		expect(error).toBeInstanceOf(MigrationError);
+		expect(String(error)).toContain("migration a failed");
+		expect(log).toEqual(["a"]);
+	});
+});
+
+describe("Roundtable migrations", () => {
+	test("refuses migrations without a configured database, before any setup", async () => {
+		const log: string[] = [];
+		const { host } = roundtable([
+			{
+				name: "stores",
+				migrations: [recording("a", log)],
+				setup: () => {
+					log.push("setup");
+					return {};
+				},
+			},
+		]);
+		expect(await rejection(host.run())).toBeInstanceOf(PluginError);
+		expect(log).toEqual([]);
+	});
+
+	test("without a database, reading it during setup is a plugin error", async () => {
+		let error: unknown;
+		const { host } = roundtable([
+			{
+				name: "reader",
+				setup: ({ database }) => {
+					try {
+						database();
+					} catch (e) {
+						error = e;
+					}
+					return { events: {} };
+				},
+			},
+		]);
+		await host.run();
+		expect(error).toBeInstanceOf(PluginError);
+	});
+});
+
+describeDb("PostgreSQL", () => {
+	const table = "roundtable_migration_test";
+	const tableMigration: Migration = {
+		name: "test-table",
+		up: async (sql) => {
+			await sql.unsafe(
+				`CREATE TABLE IF NOT EXISTS ${table} (id int PRIMARY KEY, note text NOT NULL)`,
+			);
+			await sql.unsafe(
+				`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS added text NOT NULL DEFAULT 'x'`,
+			);
+		},
+	};
+
+	async function reset(): Promise<void> {
+		const admin = openPool(url ?? "");
+		await admin.unsafe(`DROP TABLE IF EXISTS ${table}`);
+		await admin.close();
+	}
+
+	test("migrates every plugin in order before any setup, then closes the pool last", async () => {
+		await reset();
+		const log: string[] = [];
+		let pool: SQL | undefined;
+		const { host, exits } = roundtable(
+			[
+				{
+					name: "first",
+					migrations: [recording("first", log), tableMigration],
+					setup: ({ database }) => {
+						log.push("setup first");
+						pool = database();
+						return {
+							services: [{ name: "uses", stop: () => void log.push("stop") }],
+						};
+					},
+				},
+				{
+					name: "second",
+					migrations: [recording("second", log)],
+					setup: () => {
+						log.push("setup second");
+						return {};
+					},
+				},
+			],
+			{ url: url ?? "" },
+		);
+		await host.run();
+		expect(log).toEqual(["first", "second", "setup first", "setup second"]);
+		await pool?.unsafe(`INSERT INTO ${table} (id, note) VALUES (1, 'kept')`);
+		await host.shutdown("SIGTERM");
+		expect(log.at(-1)).toBe("stop");
+		expect(exits).toEqual([0]);
+		// The pool closed after the services stopped.
+		expect(await rejection(pool?.unsafe("SELECT 1"))).toBeInstanceOf(Error);
+	});
+
+	test("a second boot over the existing schema keeps its rows", async () => {
+		const read: { id: number; note: string; added: string }[][] = [];
+		for (let boot = 0; boot < 2; boot++) {
+			const { host } = roundtable(
+				[
+					{
+						name: "stores",
+						migrations: [tableMigration],
+						setup: async ({ database }) => {
+							read.push(
+								await database().unsafe(
+									`SELECT id, note, added FROM ${table} ORDER BY id`,
+								),
+							);
+							return {};
+						},
+					},
+				],
+				{ url: url ?? "" },
+			);
+			await host.run();
+			await host.shutdown("SIGTERM");
+		}
+		expect(read).toEqual([
+			[{ id: 1, note: "kept", added: "x" }],
+			[{ id: 1, note: "kept", added: "x" }],
+		]);
+		await reset();
+	});
+
+	test("a failing migration stops the boot before any setup", async () => {
+		const log: string[] = [];
+		const { host } = roundtable(
+			[
+				{
+					name: "broken",
+					migrations: [recording("broken", log, true)],
+					setup: () => {
+						log.push("setup");
+						return {};
+					},
+				},
+			],
+			{ url: url ?? "" },
+		);
+		const error = await rejection(host.run());
+		expect(error).toBeInstanceOf(PluginError);
+		expect(String(error)).toContain("plugin broken: migration broken failed: ");
+		expect(String(error)).toContain(
+			"Fix the migration or restore the database, then start again.",
+		);
+		expect((error as Error).cause).toBeInstanceOf(MigrationError);
+		expect(log).toEqual(["broken"]);
+	});
+});

package/src/core/db/migrations.ts

@@ -0,0 +1,37 @@
+import { SQL } from "bun";
+import { MigrationError, PluginError } from "../errors.ts";
+
+/** Idempotent DDL a plugin's tables need; every boot runs it again over the existing schema. */
+export interface Migration {
+	name: string;
+	up(sql: SQL): Promise<void>;
+}
+
+/**
+ * The host's one connection pool. PostgreSQL's 100 connections are shared with the other services on the same server,
+ * so the pool stays small and closes idle connections; Bun's defaults (10, never closed)
+ * exhausted the server when every store kept its own.
+ */
+export function openPool(databaseUrl: string): SQL {
+	return new SQL(databaseUrl, { max: 10, idleTimeout: 60 });
+}
+
+/** Runs the migrations in order; a repeated name is a plugin bug, a failing one stops the boot. */
+export async function migrate(
+	sql: SQL,
+	migrations: readonly Migration[],
+): Promise<void> {
+	const names = new Set<string>();
+	for (const { name } of migrations) {
+		if (names.has(name))
+			throw new PluginError(`migration ${name} is declared twice`);
+		names.add(name);
+	}
+	for (const migration of migrations) {
+		try {
+			await migration.up(sql);
+		} catch (error) {
+			throw new MigrationError(migration.name, error);
+		}
+	}
+}

package/src/core/define-roundtable.test.ts

@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { RoundtableConfig } from "./config/config.ts";
+import { defineRoundtable } from "./define-roundtable.ts";
+import { ConfigError } from "./domain/errors.ts";
+import { messages } from "./i18n/index.ts";
+import { createZhTW } from "./i18n/zh-tw.ts";
+import type { RoundtablePlugin } from "./plugin.ts";
+import { useTestLocale } from "./testing/locale.ts";
+
+const dataDir = mkdtempSync(join(tmpdir(), "roundtable-define-"));
+
+const config: RoundtableConfig = {
+	owner: { id: "100000000000000001", name: "Ada" },
+	discord: {
+		token: "token",
+		guild: "900000000000000001",
+		entryChannel: "900000000000000002",
+	},
+	database: { url: "postgres://localhost/roundtable" },
+	dataDir,
+	model: "anthropic/claude-sonnet-5-5",
+	http: { publicUrl: "https://bot.example.com", port: 3456 },
+};
+
+const mine: RoundtablePlugin = {
+	name: "mine",
+	setup: () => ({ dashboard: ["a line"] }),
+};
+
+afterEach(() => {
+	// Other suites read the text through the catalog; leave it as the tests expect.
+	useTestLocale();
+});
+
+describe("defineRoundtable", () => {
+	test("returns the built-in plugins in their fixed order, the operator's, then the scheduler", async () => {
+		const { plugins } = await defineRoundtable({ ...config, plugins: [mine] });
+		expect(plugins.map((plugin) => plugin.name)).toEqual([
+			"stores",
+			"discord",
+			"modules",
+			"agent-server",
+			"seeds",
+			"mine",
+			"schedules",
+		]);
+	});
+
+	test("migrates the core's tables first, in a fixed order", async () => {
+		const { plugins } = await defineRoundtable(config);
+		expect(
+			plugins.flatMap((plugin) => (plugin.migrations ?? []).map((m) => m.name)),
+		).toEqual([
+			"owner-memory",
+			"owner-memory-speaker",
+			"schedules",
+			"pending-confirmations",
+			"agents",
+			"agents-guild",
+			"skills",
+			"skills-guild",
+			"skills-written-kind",
+		]);
+	});
+
+	test("the host options carry the database, the root command, the tool tiers, and one listener", async () => {
+		const { options } = await defineRoundtable({
+			...config,
+			name: "Robin",
+			toolTiers: { shell: "admin" },
+		});
+		expect(options.database).toEqual({ url: config.database.url });
+		expect(options.commands?.root.name).toBe("robin");
+		expect(options.listeners).toEqual([{ id: "public", port: 3456 }]);
+		expect(options.toolTiers?.minTier("shell")).toBe("admin");
+	});
+
+	test("the locale and the assistant's name reach the text the bot shows", async () => {
+		await defineRoundtable({ ...config, name: "Robin", locale: "zh-TW" });
+		expect(messages().ownerRootDescription).toContain("Robin");
+		expect(messages().stopLabel).toBe(
+			createZhTW({ assistant: "Robin", root: "robin" }).stopLabel,
+		);
+	});
+
+	test("a mistake in the configuration stops before anything is built, naming the key", async () => {
+		await expect(
+			defineRoundtable({
+				...config,
+				discord: { ...config.discord, guilld: "1" },
+			} as RoundtableConfig),
+		).rejects.toThrow(
+			'config discord.guilld: unknown key. Did you mean "guild"?',
+		);
+		await expect(
+			defineRoundtable({ ...config, model: "sonnet" }),
+		).rejects.toBeInstanceOf(ConfigError);
+	});
+
+	test("reads the prompt files named in the configuration, and refuses a missing or empty one", async () => {
+		const dir = join(dataDir, "prompts");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "shared.md"), "You are Robin.\n");
+		writeFileSync(join(dir, "empty.md"), "  \n");
+		await defineRoundtable({
+			...config,
+			prompts: { shared: join(dir, "shared.md") },
+		});
+		await expect(
+			defineRoundtable({
+				...config,
+				prompts: { shared: join(dir, "missing.md") },
+			}),
+		).rejects.toThrow("config prompts.shared: cannot read");
+		await expect(
+			defineRoundtable({
+				...config,
+				prompts: { shared: join(dir, "empty.md") },
+			}),
+		).rejects.toThrow(
+			`config prompts.shared: ${join(dir, "empty.md")} is empty`,
+		);
+	});
+
+	test("the judge answers with a clear error until the model is available", async () => {
+		const { options } = await defineRoundtable(config);
+		await expect(options.judgeModel?.("system", "question")).rejects.toThrow(
+			"the judge's model anthropic/claude-sonnet-5-5 is not available",
+		);
+	});
+});

package/src/core/define-roundtable.ts

@@ -0,0 +1,195 @@
+import { readFileSync } from "node:fs";
+import { userInfo } from "node:os";
+import { join } from "node:path";
+import { ModelRegistry, ModelRuntime } from "@earendil-works/pi-coding-agent";
+import {
+	type AgentServerOptions,
+	agentServerPlugin,
+} from "./builtin/agent-server.ts";
+import { discordPlugin } from "./builtin/discord.ts";
+import {
+	type ModulesOptions,
+	modulesPlugin,
+	schedulerPlugin,
+} from "./builtin/modules.ts";
+import { seedsPlugin } from "./builtin/seeds.ts";
+import { storesPlugin } from "./builtin/stores.ts";
+import { type RoundtableConfig, resolveConfig } from "./config/config.ts";
+import { ownerRootCommand } from "./discord/owner-command.ts";
+import { ConfigError } from "./domain/errors.ts";
+import { JudgeError } from "./errors.ts";
+import type { RoundtableOptions } from "./host.ts";
+import { setLocale } from "./i18n/index.ts";
+import { type JudgeModel, piJudgeModel } from "./judging/model-judge.ts";
+import { createLogger, type Logger } from "./log.ts";
+import { formatModelRef, type ModelRef } from "./models.ts";
+import { ErrorReporter } from "./ops/error-reporter.ts";
+import type { RoundtablePlugin } from "./plugin.ts";
+import { speakerPolicy } from "./speakers.ts";
+import { setTimeZone } from "./time.ts";
+import { toolTiers } from "./tool-tiers.ts";
+
+/** What `defineRoundtable` returns: give both to `new Roundtable(options, plugins)`. */
+export interface DefinedRoundtable {
+	options: RoundtableOptions;
+	plugins: RoundtablePlugin[];
+}
+
+/** Replaceable parts of the assembly, for a host that shares them with its own plugins. */
+export interface DefineOverrides {
+	/** The model login the process shares; by default one is opened in the agent directory. */
+	modelRuntime?: ModelRuntime;
+	/** Your own logger and error reporter, when the process already has them. */
+	logger?: Logger;
+	errorReporter?: ErrorReporter;
+	/** Host options merged over the built ones, such as more listeners or the record of aborted work. */
+	options?: Partial<RoundtableOptions>;
+	/** What only the plugins after the built-ins can know. */
+	modules?: Pick<ModulesOptions, "agentChannelOf">;
+	agentServer?: Pick<AgentServerOptions, "ownerSessions">;
+}
+
+const ASSETS = join(import.meta.dir, "assets");
+
+function readPrompt(path: string, key: string): string {
+	let text: string;
+	try {
+		text = readFileSync(path, "utf8").trim();
+	} catch (error) {
+		throw new ConfigError(
+			`config ${key}: cannot read ${path}: ${error instanceof Error ? error.message : String(error)}. Create the file or fix the path.`,
+		);
+	}
+	if (text === "")
+		throw new ConfigError(
+			`config ${key}: ${path} is empty. Write the prompt in it.`,
+		);
+	return text;
+}
+
+/** The judge's completion through the shared login, resolving the model when first asked. */
+function judgeThrough(modelRuntime: ModelRuntime, ref: ModelRef): JudgeModel {
+	const registry = new ModelRegistry(modelRuntime);
+	return async (system, prompt) => {
+		const model = registry.find(ref.provider, ref.id);
+		if (!model)
+			throw new JudgeError(
+				`the judge's model ${formatModelRef(ref)} is not available; log in to its provider or change judge.model`,
+			);
+		return await piJudgeModel(modelRuntime, model)(system, prompt);
+	};
+}
+
+/**
+ * The host's options and the plugin list of a configured bot: the built-in plugins in their
+ * fixed order, then the operator's, then the scheduler, so a due schedule fires only once
+ * everything it reaches runs. Configuration mistakes stop here, naming the key and the fix.
+ */
+export async function defineRoundtable(
+	input: RoundtableConfig,
+	overrides: DefineOverrides = {},
+): Promise<DefinedRoundtable> {
+	const config = resolveConfig(input);
+	const { name, owner, discord } = config;
+	setLocale(config.locale, { assistant: name, root: discord.rootCommand });
+	setTimeZone(config.timeZone);
+	// Pi packages such as pi-web-access read their config from the Pi agent directory.
+	process.env.PI_CODING_AGENT_DIR = config.agentDir;
+	const modelRuntime =
+		overrides.modelRuntime ??
+		(await ModelRuntime.create({
+			authPath: join(config.agentDir, "auth.json"),
+		}));
+	const errorReporter =
+		overrides.errorReporter ??
+		(config.ops
+			? new ErrorReporter({ opsAgent: config.ops.agent, app: name })
+			: undefined);
+	const logger =
+		overrides.logger ??
+		createLogger(
+			discord.rootCommand,
+			errorReporter ? (entry) => errorReporter.record(entry) : undefined,
+		);
+	const speakers = speakerPolicy({
+		owners: [owner.id],
+		...(config.speakers.admins ? { admins: config.speakers.admins } : {}),
+		...(config.speakers.members ? { members: config.speakers.members } : {}),
+	});
+	const shared = config.prompts.shared
+		? readPrompt(config.prompts.shared, "prompts.shared")
+		: readPrompt(join(ASSETS, "prompts", "shared.md"), "prompts.shared");
+	const guest = config.prompts.guest
+		? readPrompt(config.prompts.guest, "prompts.guest")
+		: readPrompt(join(ASSETS, "prompts", "shared-guest.md"), "prompts.guest");
+	return {
+		options: {
+			logger,
+			database: { url: config.databaseUrl },
+			toolTiers: toolTiers(config.toolTiers),
+			commands: { root: ownerRootCommand(discord.rootCommand) },
+			listeners: [
+				config.http.socketPath
+					? { id: "public", socketPath: config.http.socketPath }
+					: {
+							id: "public",
+							port: config.http.port,
+							...(config.http.hostname
+								? { hostname: config.http.hostname }
+								: {}),
+						},
+			],
+			judgeModel: judgeThrough(modelRuntime, config.judge.model),
+			...overrides.options,
+		},
+		plugins: [
+			storesPlugin({ ownerId: owner.id, guildId: discord.guild }),
+			discordPlugin({
+				token: discord.token,
+				ownerId: owner.id,
+				ownerName: owner.name,
+				speakers,
+				rootCommand: discord.rootCommand,
+				dataDir: config.dataDir,
+				avatarUrl: config.http.publicUrl,
+				avatarReference: config.avatar ?? join(ASSETS, "neutral.png"),
+			}),
+			modulesPlugin({
+				owner,
+				assistant: name,
+				modelRuntime,
+				agentDir: config.agentDir,
+				dataDir: config.dataDir,
+				delegation: config.delegation,
+				...overrides.modules,
+			}),
+			agentServerPlugin({
+				guildId: discord.guild,
+				entryChannelId: discord.entryChannel,
+				owner,
+				assistant: name,
+				speakers,
+				modelRuntime,
+				agentDir: config.agentDir,
+				dataDir: config.dataDir,
+				model: config.model,
+				thinking: config.thinking,
+				judgeThreshold: config.judge.threshold,
+				workDir: config.workDir,
+				shellUser: userInfo().username,
+				prompts: { shared, guest },
+				skills: {
+					reposDir: config.skills.reposDir ?? join(config.dataDir, "repos"),
+					writtenDir: join(config.dataDir, "skills"),
+					builtinDir: config.skills.builtinDir ?? join(ASSETS, "skills"),
+				},
+				avatarListener: "public",
+				...(errorReporter ? { errorReporter } : {}),
+				...overrides.agentServer,
+			}),
+			seedsPlugin(config.agents),
+			...config.plugins,
+			schedulerPlugin(),
+		],
+	};
+}