pi-roundtable 0.1.0

package/examples/session-tools.ts

@@ -0,0 +1,34 @@
+import { definePlugin } from "pi-roundtable";
+import { Type } from "typebox";
+
+/**
+ * A session tool is a Pi extension added to every conversation session: the raw form of `tools`,
+ * for what defineTool cannot express. The factory returns null for a session it does not apply
+ * to, and a new `revision` rebuilds open sessions on their next turn.
+ */
+export const clock = definePlugin({
+	name: "clock",
+	setup: () => ({
+		sessionTools: [
+			{
+				name: "clock",
+				phase: "tools",
+				snapshot: () => ({
+					revision: 0,
+					factory: () => (pi) => {
+						pi.registerTool({
+							name: "clock_now",
+							label: "clock_now",
+							description: "Tell the current UTC time.",
+							parameters: Type.Object({}),
+							execute: async () => ({
+								content: [{ type: "text", text: new Date().toISOString() }],
+								details: undefined,
+							}),
+						});
+					},
+				}),
+			},
+		],
+	}),
+});

package/examples/tools.test.ts

@@ -0,0 +1,18 @@
+import { expect, test } from "bun:test";
+import type { Speaker } from "pi-roundtable";
+import { testPlugin } from "pi-roundtable/testing";
+import { notes } from "./tools.ts";
+
+test("note_add saves a note for the speaker and refuses an empty one", async () => {
+	const harness = await testPlugin(notes);
+	const ada: Speaker = { id: "1", name: "Ada", tier: "member" };
+	expect(harness.tools).toEqual(["note_add"]);
+	expect(harness.tiers.minTier("note_add")).toBe("member");
+	expect(
+		await harness.runTool("note_add", { text: "milk" }, { speaker: ada }),
+	).toBe("Saved note 1 for Ada.");
+	expect(await harness.runTool("note_add", { text: " " })).toBe(
+		"The note is empty. Ask what to save.",
+	);
+	await harness.stop();
+});

package/examples/tools.ts

@@ -0,0 +1,28 @@
+import { definePlugin, defineTool, ToolRefusal } from "pi-roundtable";
+import { Type } from "typebox";
+
+/** Tools are what agents can call; each names the lowest tier of speaker whose turns may call it. */
+export const notes = definePlugin({
+	name: "notes",
+	setup: () => {
+		const saved: string[] = [];
+		return {
+			tools: [
+				defineTool({
+					name: "note_add",
+					description:
+						"Save a short note. Call it when asked to remember something.",
+					parameters: Type.Object({ text: Type.String() }),
+					minTier: "member",
+					run: ({ text }, turn) => {
+						// A refusal is read by the model, which can correct the call.
+						if (text.trim() === "")
+							throw new ToolRefusal("The note is empty. Ask what to save.");
+						saved.push(text);
+						return `Saved note ${saved.length} for ${turn.speaker?.name ?? "nobody"}.`;
+					},
+				}),
+			],
+		};
+	},
+});

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "pi-roundtable",
+	"version": "0.1.0",
+	"description": "A plugin-driven Pi agent server for Discord",
+	"type": "module",
+	"license": "MIT",
+	"engines": {
+		"bun": ">=1.3.0"
+	},
+	"exports": {
+		".": "./src/index.ts",
+		"./testing": "./src/testing.ts"
+	},
+	"bin": {
+		"roundtable": "./src/cli/roundtable.mjs"
+	},
+	"files": [
+		"src",
+		"templates",
+		"docs",
+		"examples",
+		"LICENSE",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wayne930242/pi-roundtable.git"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@babel/parser": "7.29.9",
+		"@earendil-works/pi-ai": "0.87.1",
+		"@earendil-works/pi-coding-agent": "0.87.1",
+		"canvas": "3.2.3",
+		"discord.js": "14.27.0",
+		"pi-mcp-adapter": "2.37.0",
+		"pino": "10.3.1",
+		"typebox": "1.3.34",
+		"unpdf": "1.8.1"
+	},
+	"devDependencies": {
+		"typescript": "7.0.2",
+		"@biomejs/biome": "2.5.14",
+		"@types/bun": "1.4.2"
+	}
+}

package/src/cli/add-plugin.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { addPlugin } from "./add-plugin.ts";
+import { init } from "./init.ts";
+import { tempDir } from "./testing/fixtures.ts";
+
+const dirs: ReturnType<typeof tempDir>[] = [];
+afterEach(() => {
+	for (const dir of dirs.splice(0)) dir.done();
+});
+const project = () => {
+	const dir = tempDir();
+	dirs.push(dir);
+	init({
+		cwd: dir.path,
+		bun: { version: "1.3.10", required: ">=1.3.0" },
+		version: "1.2.3",
+	});
+	return dir;
+};
+const read = (dir: string, file: string) =>
+	readFileSync(join(dir, file), "utf8");
+
+test("add plugin renders the plugin and its test from the hello template and lists it", () => {
+	const dir = project();
+	const report = addPlugin({ cwd: dir.path, name: "my-notes" });
+	expect(report.ok).toBe(true);
+	expect(report.changed).toEqual([
+		"plugins/my-notes.ts",
+		"plugins/my-notes.test.ts",
+		"roundtable.config.ts",
+	]);
+	const plugin = read(dir.path, "plugins/my-notes.ts");
+	expect(plugin).toContain("export const myNotes = definePlugin(");
+	expect(plugin).toContain('name: "my-notes"');
+	expect(plugin).toContain("my_notes_greet");
+	expect(read(dir.path, "plugins/my-notes.test.ts")).toContain(
+		'import { myNotes } from "./my-notes.ts"',
+	);
+	const config = read(dir.path, "roundtable.config.ts");
+	expect(config).toContain('import { myNotes } from "./plugins/my-notes.ts";');
+	expect(config).toContain("plugins: [hello, myNotes]");
+});
+
+test("a second plugin joins the first", () => {
+	const dir = project();
+	addPlugin({ cwd: dir.path, name: "alpha" });
+	addPlugin({ cwd: dir.path, name: "beta" });
+	expect(read(dir.path, "roundtable.config.ts")).toContain(
+		"plugins: [hello, alpha, beta]",
+	);
+});
+
+test("add plugin refuses a name that is not lowercase kebab-case, changing nothing", () => {
+	const dir = project();
+	const before = read(dir.path, "roundtable.config.ts");
+	for (const name of [
+		"MyNotes",
+		"my_notes",
+		"-a",
+		"a--b",
+		"1a",
+		"",
+		"a b",
+		"../x",
+	]) {
+		const report = addPlugin({ cwd: dir.path, name });
+		expect(report.ok).toBe(false);
+		expect(report.problems.join(" ")).toContain("is not a plugin name");
+	}
+	expect(read(dir.path, "roundtable.config.ts")).toBe(before);
+});
+
+test("add plugin refuses an existing file and leaves the config alone", () => {
+	const dir = project();
+	const before = read(dir.path, "roundtable.config.ts");
+	const report = addPlugin({ cwd: dir.path, name: "hello" });
+	expect(report.ok).toBe(false);
+	expect(report.problems.join(" ")).toContain("plugins/hello.ts");
+	expect(report.problems.join(" ")).toContain("already");
+	expect(read(dir.path, "roundtable.config.ts")).toBe(before);
+	dir.write("plugins/mine.test.ts", "// mine");
+	expect(addPlugin({ cwd: dir.path, name: "mine" }).ok).toBe(false);
+	expect(existsSync(join(dir.path, "plugins/mine.ts"))).toBe(false);
+});
+
+test("add plugin refuses a config whose plugin list it cannot find, writing no plugin file", () => {
+	const dir = project();
+	dir.write("roundtable.config.ts", "export default buildConfig();\n");
+	const report = addPlugin({ cwd: dir.path, name: "extra" });
+	expect(report.ok).toBe(false);
+	expect(report.problems.join(" ")).toContain("cannot find the plugin list");
+	expect(existsSync(join(dir.path, "plugins/extra.ts"))).toBe(false);
+	expect(existsSync(join(dir.path, "plugins/extra.test.ts"))).toBe(false);
+	expect(read(dir.path, "roundtable.config.ts")).toBe(
+		"export default buildConfig();\n",
+	);
+});
+
+test("add plugin outside a project says where it looked", () => {
+	const dir = tempDir();
+	dirs.push(dir);
+	const report = addPlugin({ cwd: dir.path, name: "extra" });
+	expect(report.ok).toBe(false);
+	expect(report.problems.join(" ")).toContain("roundtable.config.ts is not in");
+});

package/src/cli/add-plugin.ts

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { addPluginToConfig, ConfigEditError } from "./config-edit.ts";
+import {
+	isPluginName,
+	pluginNames,
+	renderPlugin,
+	writeRendered,
+} from "./templates.ts";
+
+const CONFIG = "roundtable.config.ts";
+
+export interface AddPluginInputs {
+	cwd: string;
+	name: string;
+	/** Where the templates are; default the package's own. */
+	templates?: string;
+}
+
+export interface AddPluginReport {
+	ok: boolean;
+	problems: string[];
+	/** Paths written or changed, relative to `cwd`. */
+	changed: string[];
+}
+
+const refused = (...problems: string[]): AddPluginReport => ({
+	ok: false,
+	problems,
+	changed: [],
+});
+
+/**
+ * Creates `plugins/<name>.ts` and its test from the `hello` template and lists the plugin in
+ * `roundtable.config.ts`. Everything is checked and rendered before the first write, so a refusal
+ * leaves the project untouched.
+ */
+export function addPlugin(inputs: AddPluginInputs): AddPluginReport {
+	const { cwd, name } = inputs;
+	if (!isPluginName(name))
+		return refused(
+			`${JSON.stringify(name)} is not a plugin name. Use lowercase words joined by dashes, such as my-notes.`,
+		);
+	const configPath = join(cwd, CONFIG);
+	if (!existsSync(configPath))
+		return refused(
+			`${CONFIG} is not in ${cwd}. Run this in the project directory, or create the project with \`roundtable init\`.`,
+		);
+	const files = renderPlugin(pluginNames(name), inputs.templates);
+	const existing = files
+		.map((file) => file.path)
+		.filter((path) => existsSync(join(cwd, path)));
+	if (existing.length > 0)
+		return refused(
+			`${existing.join(" and ")} already ${existing.length === 1 ? "exists" : "exist"}. Choose another name or remove the file.`,
+		);
+	let edited: string;
+	try {
+		edited = addPluginToConfig(
+			readFileSync(configPath, "utf8"),
+			pluginNames(name),
+			CONFIG,
+		);
+	} catch (error) {
+		if (error instanceof ConfigEditError) return refused(error.message);
+		throw error;
+	}
+	writeRendered(cwd, files);
+	writeFileSync(configPath, edited);
+	return {
+		ok: true,
+		problems: [],
+		changed: [...files.map((file) => file.path), CONFIG],
+	};
+}

package/src/cli/checks/basic.test.ts

@@ -0,0 +1,276 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { Project } from "../project.ts";
+import type { Result } from "../report.ts";
+import {
+	fakeHttp,
+	fakePorts,
+	tempDir,
+	validConfig,
+} from "../testing/fixtures.ts";
+import { checkBun } from "./bun.ts";
+import { checkConfiguration, checkPlugins } from "./configuration.ts";
+import { checkEnvironment } from "./environment.ts";
+import { checkModelLogin } from "./model.ts";
+import { checkPublicUrl } from "./public-url.ts";
+
+const dirs: ReturnType<typeof tempDir>[] = [];
+afterEach(() => {
+	for (const dir of dirs.splice(0)) dir.done();
+});
+
+/** The failure's problem and fix text, or an assertion failure when the check passed or skipped. */
+function failure(result: Result): string {
+	if (result.status !== "fail")
+		throw new Error(`expected a failure, got ${JSON.stringify(result)}`);
+	return `${result.problem}\n${result.fix}`;
+}
+
+describe("Bun", () => {
+	test("passes on a version in range", () => {
+		expect(checkBun({ version: "1.3.10", required: ">=1.3.0" }).status).toBe(
+			"ok",
+		);
+	});
+	test("fails when missing, with the install page as the fix", () => {
+		const text = failure(checkBun({ version: undefined, required: ">=1.3.0" }));
+		expect(text).toContain("not installed");
+		expect(text).toContain("https://bun.sh/docs/installation");
+	});
+	test("fails when too old, saying to upgrade", () => {
+		const text = failure(checkBun({ version: "1.2.0", required: ">=1.3.0" }));
+		expect(text).toContain("1.2.0");
+		expect(text).toContain("bun upgrade");
+	});
+});
+
+describe("environment", () => {
+	const example =
+		"# comment\nDISCORD_TOKEN=\nDATABASE_URL=postgres://x\n# OPTIONAL=\nOWNER_ID=\n";
+	test("passes when every listed variable has a value", () => {
+		const dir = tempDir();
+		dirs.push(dir);
+		dir.write(".env.example", example);
+		expect(
+			checkEnvironment(dir.path, {
+				DISCORD_TOKEN: "t",
+				DATABASE_URL: "d",
+				OWNER_ID: "1",
+			}).status,
+		).toBe("ok");
+	});
+	test("names every variable without a value, but not commented ones, and says to copy the example", () => {
+		const dir = tempDir();
+		dirs.push(dir);
+		dir.write(".env.example", example);
+		const text = failure(
+			checkEnvironment(dir.path, { DATABASE_URL: "d", OWNER_ID: "  " }),
+		);
+		expect(text).toContain("DISCORD_TOKEN, OWNER_ID");
+		expect(text).not.toContain("OPTIONAL");
+		expect(text).not.toContain("DATABASE_URL");
+		expect(text).toContain("Copy .env.example to .env");
+	});
+	test("says to fill .env when it exists", () => {
+		const dir = tempDir();
+		dirs.push(dir);
+		dir.write(".env.example", example);
+		dir.write(".env", "");
+		expect(failure(checkEnvironment(dir.path, {}))).toContain(
+			"Fill them in .env",
+		);
+	});
+	test("skips a project without an example", () => {
+		const dir = tempDir();
+		dirs.push(dir);
+		expect(checkEnvironment(dir.path, {}).status).toBe("skipped");
+	});
+});
+
+describe("configuration", () => {
+	const project = (config: unknown) => new Project("/x", fakePorts(config));
+	test("passes a configuration the schema accepts", async () => {
+		expect((await checkConfiguration(project(validConfig))).status).toBe("ok");
+	});
+	test("names the failing key, and says where to fix it", async () => {
+		const text = failure(
+			await checkConfiguration(
+				project({
+					...validConfig,
+					discord: { ...validConfig.discord, token: "" },
+				}),
+			),
+		);
+		expect(text).toContain("config discord.token");
+		expect(text).toContain("roundtable.config.ts");
+	});
+	test("names the closest known key for one it does not know", async () => {
+		const text = failure(
+			await checkConfiguration(project({ ...validConfig, modle: "x" })),
+		);
+		expect(text).toContain('Did you mean "model"');
+	});
+	test("fails with the loader's message when the file cannot be loaded", async () => {
+		const failing = new Project(
+			"/x",
+			fakePorts(undefined, {
+				loadConfig: async () => {
+					throw new Error("roundtable.config.ts is not in /x");
+				},
+			}),
+		);
+		expect(failure(await checkConfiguration(failing))).toContain(
+			"is not in /x",
+		);
+	});
+	test("fails with the assembly's own message", async () => {
+		const failing = new Project(
+			"/x",
+			fakePorts(validConfig, {
+				define: async () => {
+					throw new Error(
+						"config prompts.shared: cannot read ./persona/shared.md",
+					);
+				},
+			}),
+		);
+		expect(failure(await checkConfiguration(failing))).toContain(
+			"prompts.shared",
+		);
+	});
+});
+
+describe("plugins", () => {
+	const plugin = (name: string) => ({ name, setup: () => ({}) });
+	const withPlugins = (names: string[]) =>
+		new Project(
+			"/x",
+			fakePorts(
+				{ ...validConfig, plugins: [plugin("hello")] },
+				{
+					define: async () => ({
+						options: { logger: {} as never },
+						plugins: names.map(plugin),
+					}),
+				},
+			),
+		);
+	test("passes when every name is its own and lists the operator's", async () => {
+		const result = await checkPlugins(withPlugins(["database", "hello"]));
+		expect(result).toEqual({ status: "ok", detail: "yours: hello" });
+	});
+	test("fails on a repeated name and says to rename", async () => {
+		const text = failure(
+			await checkPlugins(withPlugins(["database", "hello", "hello"])),
+		);
+		expect(text).toContain("two plugins are named hello");
+		expect(text).toContain("Rename");
+	});
+	test("is skipped while the configuration is invalid", async () => {
+		const result = await checkPlugins(new Project("/x", fakePorts({})));
+		expect(result.status).toBe("skipped");
+	});
+});
+
+describe("model login", () => {
+	const login = (source: string | undefined, seen: string[] = []) =>
+		fakePorts(validConfig, {
+			login: async (dir, provider) => {
+				seen.push(`${dir} ${provider}`);
+				return source;
+			},
+		});
+	test("passes when the provider has a login and says where it comes from", async () => {
+		const seen: string[] = [];
+		const result = await checkModelLogin(
+			new Project("/x", login("ANTHROPIC_API_KEY", seen)),
+			login("ANTHROPIC_API_KEY", seen),
+		);
+		expect(result).toEqual({
+			status: "ok",
+			detail: "anthropic login from ANTHROPIC_API_KEY",
+		});
+		expect(seen).toEqual(["/data/pi anthropic"]);
+	});
+	test("fails when there is none, naming the provider, the model, and the ways to log in", async () => {
+		const ports = login(undefined);
+		const text = failure(
+			await checkModelLogin(new Project("/x", ports), ports),
+		);
+		expect(text).toContain("no login for anthropic");
+		expect(text).toContain("anthropic/claude-sonnet-5-5");
+		expect(text).toContain("ANTHROPIC_API_KEY");
+		expect(text).toContain("/data/pi/auth.json");
+	});
+	test("fails on a model that is not <provider>/<id>", async () => {
+		const ports = fakePorts({ ...validConfig, model: "sonnet" });
+		expect(
+			failure(await checkModelLogin(new Project("/x", ports), ports)),
+		).toContain("<provider>/<id>");
+	});
+	test("uses the configured agent directory", async () => {
+		const seen: string[] = [];
+		const ports = fakePorts(
+			{ ...validConfig, agentDir: "/agents" },
+			{
+				login: async (dir) => {
+					seen.push(dir);
+					return "x";
+				},
+			},
+		);
+		await checkModelLogin(new Project("/x", ports), ports);
+		expect(seen).toEqual(["/agents"]);
+	});
+});
+
+describe("public URL", () => {
+	const project = (url: unknown) =>
+		new Project("/x", fakePorts({ ...validConfig, http: { publicUrl: url } }));
+	test("passes a well-formed address without asking the network", async () => {
+		const http = fakeHttp({});
+		const result = await checkPublicUrl(
+			project("https://bot.example.test"),
+			http,
+			false,
+		);
+		expect(result.status).toBe("ok");
+		expect(http.requests).toEqual([]);
+	});
+	test("fails on something that is not a URL, showing an example", async () => {
+		const text = failure(
+			await checkPublicUrl(project("bot.example.test"), fakeHttp({}), false),
+		);
+		expect(text).toContain("not a URL");
+		expect(text).toContain("https://bot.example.com");
+	});
+	test("fails on a scheme Discord cannot fetch from", async () => {
+		expect(
+			failure(
+				await checkPublicUrl(
+					project("ftp://bot.example.test"),
+					fakeHttp({}),
+					false,
+				),
+			),
+		).toContain("http(s)");
+	});
+	test("with reachable, passes on any answer and fails when nothing answers", async () => {
+		const answering = fakeHttp({ "/": { status: 404, body: undefined } });
+		expect(
+			await checkPublicUrl(
+				project("https://bot.example.test"),
+				answering,
+				true,
+			),
+		).toEqual({
+			status: "ok",
+			detail: "https://bot.example.test answered 404",
+		});
+		const down = fakeHttp({ "/": new Error("connection refused") });
+		const text = failure(
+			await checkPublicUrl(project("https://bot.example.test"), down, true),
+		);
+		expect(text).toContain("connection refused");
+		expect(text).toContain("roundtable start");
+	});
+});

package/src/cli/checks/bun.ts

@@ -0,0 +1,26 @@
+import { fail, ok, type Result } from "../report.ts";
+
+export const BUN_INSTALL_PAGE = "https://bun.sh/docs/installation";
+
+/** What the command line knows about the Bun it runs on and the one the package needs. */
+export interface BunFacts {
+	/** The running Bun's version; undefined when there is none. */
+	version: string | undefined;
+	/** The package's `engines.bun` range. */
+	required: string;
+}
+
+/** Bun's version against the package's range; both `init` and `doctor` refuse on the same words. */
+export function checkBun({ version, required }: BunFacts): Result {
+	if (version === undefined)
+		return fail(
+			"Bun is not installed.",
+			`pi-roundtable runs on Bun ${required}. Install it from ${BUN_INSTALL_PAGE} and run the command again.`,
+		);
+	if (!Bun.semver.satisfies(version, required))
+		return fail(
+			`Bun ${version} is older than the ${required} this package needs.`,
+			`Upgrade with \`bun upgrade\` (see ${BUN_INSTALL_PAGE}) and run the command again.`,
+		);
+	return ok(`Bun ${version}`);
+}

package/src/cli/checks/configuration.ts

@@ -0,0 +1,28 @@
+import { CONFIG_FILE, type Project } from "../project.ts";
+import { fail, ok, type Result } from "../report.ts";
+
+/** The configuration against its schema: the failing key is named by the schema's own message. */
+export async function checkConfiguration(project: Project): Promise<Result> {
+	const assembled = await project.assembled();
+	return assembled.ok ? ok(`${CONFIG_FILE} is valid`) : assembled.failure;
+}
+
+/** Every plugin has its own name, the operator's and the built-ins' together. */
+export async function checkPlugins(project: Project): Promise<Result> {
+	const assembled = await project.assembled();
+	if (!assembled.ok)
+		return { status: "skipped", reason: "the configuration is not valid yet" };
+	const seen = new Set<string>();
+	for (const { name } of assembled.value.defined.plugins) {
+		if (seen.has(name))
+			return fail(
+				`two plugins are named ${name}.`,
+				"Rename yours: a plugin's name is in its definePlugin call, and the built-in plugins already use theirs.",
+			);
+		seen.add(name);
+	}
+	const own = assembled.value.config.plugins.map((plugin) => plugin.name);
+	return ok(
+		own.length === 0 ? "no plugins of your own" : `yours: ${own.join(", ")}`,
+	);
+}