pi-roundtable 0.1.0

package/src/core/agents/agent-schema.ts

@@ -0,0 +1,115 @@
+import { scopeToGuild } from "../db/guild-scope.ts";
+import type { Migration } from "../db/migrations.ts";
+import type { ThinkingLevel } from "../models.ts";
+import type { Agent, AgentGroup, AgentStatus } from "./agent-rules.ts";
+
+export interface AgentRow {
+	name: string;
+	display_name: string;
+	prompt: string;
+	avatar_prompt: string;
+	avatar_hash: string | null;
+	channel_id: string | null;
+	model: string | null;
+	thinking: ThinkingLevel | null;
+	status: AgentStatus;
+}
+
+export interface GroupRow {
+	name: string;
+	display_name: string;
+	channel_id: string;
+	members: string;
+	host: string;
+	status: AgentStatus;
+}
+
+export const toAgent = (row: AgentRow): Agent => ({
+	name: row.name,
+	displayName: row.display_name,
+	prompt: row.prompt,
+	avatarPrompt: row.avatar_prompt,
+	...(row.avatar_hash ? { avatarHash: row.avatar_hash } : {}),
+	...(row.channel_id ? { channelId: row.channel_id } : {}),
+	...(row.model ? { model: row.model } : {}),
+	...(row.thinking ? { thinking: row.thinking } : {}),
+	status: row.status,
+});
+
+export const toGroup = (row: GroupRow): AgentGroup => ({
+	name: row.name,
+	displayName: row.display_name,
+	channelId: row.channel_id,
+	members: row.members.split(",").filter(Boolean),
+	host: row.host,
+	status: row.status,
+});
+
+/** The store's tables; the host runs this before any store attaches. */
+export const agentsMigration: Migration = {
+	name: "agents",
+	up: async (sql) => {
+		await sql`
+			CREATE TABLE IF NOT EXISTS agents (
+				name text PRIMARY KEY,
+				display_name text NOT NULL,
+				prompt text NOT NULL,
+				avatar_prompt text NOT NULL,
+				avatar_hash text,
+				channel_id text UNIQUE,
+				status text NOT NULL DEFAULT 'active',
+				created_at timestamptz NOT NULL DEFAULT now(),
+				updated_at timestamptz NOT NULL DEFAULT now()
+			)`;
+		await sql`ALTER TABLE agents ADD COLUMN IF NOT EXISTS model text`;
+		await sql`ALTER TABLE agents ADD COLUMN IF NOT EXISTS thinking text`;
+		await sql`
+			CREATE TABLE IF NOT EXISTS agent_groups (
+				name text PRIMARY KEY,
+				display_name text NOT NULL,
+				channel_id text NOT NULL UNIQUE,
+				-- Comma-separated agent names, which never contain a comma.
+				members text NOT NULL,
+				host text NOT NULL,
+				status text NOT NULL DEFAULT 'active',
+				created_at timestamptz NOT NULL DEFAULT now()
+			)`;
+		await sql`
+			CREATE TABLE IF NOT EXISTS agent_group_messages (
+				id bigserial PRIMARY KEY,
+				group_name text NOT NULL,
+				author text NOT NULL,
+				author_name text NOT NULL,
+				text text NOT NULL,
+				created_at timestamptz NOT NULL DEFAULT now()
+			)`;
+		await sql`CREATE INDEX IF NOT EXISTS agent_group_messages_group ON agent_group_messages (group_name, id)`;
+		await sql`
+			CREATE TABLE IF NOT EXISTS agent_group_cursors (
+				group_name text NOT NULL,
+				agent_name text NOT NULL,
+				last_id bigint NOT NULL,
+				PRIMARY KEY (group_name, agent_name)
+			)`;
+	},
+};
+
+/**
+ * The migrations of the store's tables for the guild the process serves: the tables, then
+ * each row's guild, with existing rows given `guildId`.
+ */
+export function agentMigrations(guildId: string): Migration[] {
+	return [
+		agentsMigration,
+		{
+			name: "agents-guild",
+			up: (sql) =>
+				scopeToGuild(sql, guildId, [
+					{ table: "agents", key: ["name"] },
+					{ table: "agent_groups", key: ["name"] },
+					{ table: "agent_group_messages", key: ["id"] },
+					{ table: "agent_group_cursors", key: ["group_name", "agent_name"] },
+				]),
+		},
+	];
+}

package/src/core/agents/agent-settings.ts

@@ -0,0 +1,49 @@
+import { AgentError } from "../domain/errors.ts";
+import { assistantName } from "../i18n/index.ts";
+import {
+	AUTO_THINKING,
+	type ThinkingLevel,
+	type ThinkingSetting,
+} from "../models.ts";
+import { checkModelRef, checkThinking } from "./agent-store.ts";
+
+/** Resets a model or thinking setting to the assistant's. */
+const DEFAULT_SETTING = "default";
+
+/** A thinking setting in words, for agents reading one. */
+export function describeThinking(setting: ThinkingSetting): string {
+	return setting === AUTO_THINKING
+		? "auto, the judge picks each turn's level"
+		: setting;
+}
+
+/**
+ * The model an update sets: unchanged when absent, null for the assistant's, otherwise one the host
+ * runs.
+ */
+export async function modelSetting(
+	model: string | undefined,
+	usable: () => Promise<string[]>,
+): Promise<string | null | undefined> {
+	if (model === undefined) return undefined;
+	const value = model.trim();
+	if (value === DEFAULT_SETTING) return null;
+	checkModelRef(value);
+	const models = await usable();
+	if (!models.includes(value))
+		throw new AgentError(
+			`${assistantName()} cannot run ${value}. Usable models: ${models.join(", ")}; or "default" for ${assistantName()}'s.`,
+		);
+	return value;
+}
+
+/** The thinking level an update sets: unchanged when absent, null for the assistant's. */
+export function thinkingSetting(
+	level: string | undefined,
+): ThinkingLevel | null | undefined {
+	if (level === undefined) return undefined;
+	const value = level.trim();
+	if (value === DEFAULT_SETTING) return null;
+	checkThinking(value);
+	return value;
+}

package/src/core/agents/agent-store.test.ts

@@ -0,0 +1,205 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { SQL } from "bun";
+import { AgentError } from "../domain/errors.ts";
+import {
+	describeDb,
+	openTestStore,
+	TEST_GUILD,
+	type TestStore,
+	testDatabaseUrl,
+} from "../testing/database.ts";
+import { AgentStore } from "./agent-store.ts";
+
+// Runs against a real PostgreSQL, only when ROUNDTABLE_TEST_DATABASE_URL is set.
+describeDb("PostgreSQL", () => {
+	let store: TestStore<AgentStore>;
+
+	const seed = (name: string, channelId?: string) => ({
+		name,
+		displayName: name.toUpperCase(),
+		prompt: `You are ${name}.`,
+		avatarPrompt: `A portrait of ${name}.`,
+		...(channelId ? { channelId } : {}),
+	});
+
+	beforeEach(async () => {
+		await store?.close();
+		const admin = new SQL(testDatabaseUrl);
+		for (const table of [
+			"agents",
+			"agent_groups",
+			"agent_group_messages",
+			"agent_group_cursors",
+		])
+			await admin.unsafe(`DROP TABLE IF EXISTS ${table}`);
+		await admin.close();
+		store = await openTestStore(AgentStore, TEST_GUILD);
+		await store.seed([
+			seed("coordinator", "100"),
+			seed("infra"),
+			seed("doctor"),
+		]);
+	});
+
+	afterAll(async () => {
+		await store.close();
+	});
+
+	describe("agents", () => {
+		test("seeding never overwrites an existing agent", async () => {
+			await store.updateAgent("infra", { prompt: "Edited." });
+			const added = await store.seed([seed("infra"), seed("new-one")]);
+			expect(added).toEqual(["new-one"]);
+			expect(store.agent("infra")?.prompt).toBe("Edited.");
+			const reopened = await openTestStore(AgentStore, TEST_GUILD);
+			expect(reopened.agent("infra")?.prompt).toBe("Edited.");
+			await reopened.close();
+		});
+
+		test("finds an active agent by its channel", async () => {
+			expect(store.agentByChannel("100")?.name).toBe("coordinator");
+			await store.archiveAgent("coordinator");
+			expect(store.agentByChannel("100")).toBeUndefined();
+		});
+
+		test("display names change; names are checked and never reused", async () => {
+			const agent = await store.updateAgent("infra", {
+				displayName: "  Ops  ",
+			});
+			expect(agent.displayName).toBe("Ops");
+			expect(agent.name).toBe("infra");
+			await expect(
+				store.updateAgent("infra", { displayName: "discord bot" }),
+			).rejects.toBeInstanceOf(AgentError);
+			expect(() => store.checkNewName("Bad Name")).toThrow(AgentError);
+			await store.archiveAgent("doctor");
+			expect(() => store.checkNewName("doctor")).toThrow(/taken/);
+			expect(() => store.activeAgent("doctor")).toThrow(/archived/);
+		});
+
+		test("prompts are limited to 4,000 characters", async () => {
+			await expect(
+				store.updateAgent("infra", { prompt: "x".repeat(4001) }),
+			).rejects.toThrow(/4000/);
+		});
+	});
+
+	describe("model settings", () => {
+		test("model and thinking are kept, survive a reopen, and reset with null", async () => {
+			await store.updateAgent("infra", {
+				model: "openai-codex/gpt-6-sol",
+				thinking: "high",
+			});
+			const reopened = await openTestStore(AgentStore, TEST_GUILD);
+			expect(reopened.agent("infra")).toMatchObject({
+				model: "openai-codex/gpt-6-sol",
+				thinking: "high",
+			});
+			await reopened.close();
+			await store.updateAgent("infra", { prompt: "Other." });
+			expect(store.agent("infra")?.model).toBe("openai-codex/gpt-6-sol");
+			const reset = await store.updateAgent("infra", {
+				model: null,
+				thinking: null,
+			});
+			expect(reset.model).toBeUndefined();
+			expect(reset.thinking).toBeUndefined();
+		});
+
+		test("a malformed model or unknown thinking level is refused", async () => {
+			await expect(
+				store.updateAgent("infra", { model: "gpt-6-sol" }),
+			).rejects.toThrow(AgentError);
+			await expect(
+				// @ts-expect-error: an unknown level from outside the type system
+				store.updateAgent("infra", { thinking: "extreme" }),
+			).rejects.toThrow(/thinking level/);
+		});
+	});
+
+	describe("groups", () => {
+		const makeGroup = () =>
+			store.createGroup({
+				name: "ops",
+				displayName: "Ops",
+				channelId: "200",
+				members: ["coordinator", "infra", "doctor"],
+				host: "coordinator",
+			});
+
+		test("a group needs 2 to 6 distinct active members and a member host", async () => {
+			expect(() => store.checkNewGroup("g", ["infra"], "infra")).toThrow(
+				AgentError,
+			);
+			expect(() =>
+				store.checkNewGroup("g", ["infra", "doctor"], "coordinator"),
+			).toThrow(/host/);
+			expect(() =>
+				store.checkNewGroup("infra", ["infra", "doctor"], "infra"),
+			).toThrow(/taken/);
+			const group = await makeGroup();
+			expect(store.groupByChannel("200")?.members).toEqual(group.members);
+		});
+
+		test("an archived agent leaves its groups, which hand over hosting or archive", async () => {
+			await makeGroup();
+			await store.archiveAgent("coordinator");
+			const group = store.group("ops");
+			expect(group?.members).toEqual(["infra", "doctor"]);
+			expect(group?.host).toBe("infra");
+			await store.archiveAgent("doctor");
+			expect(store.group("ops")?.status).toBe("archived");
+		});
+
+		test("each message reaches each member once, its own excluded", async () => {
+			await makeGroup();
+			const owner = await store.appendGroupMessage("ops", {
+				author: "owner",
+				authorName: "Riley",
+				text: "hi",
+			});
+			await store.appendGroupMessage("ops", {
+				author: "infra",
+				authorName: "INFRA",
+				text: "disk ok",
+			});
+			const first = await store.backlog("ops", "doctor", 40);
+			expect(first.messages.map((m) => m.text)).toEqual(["hi", "disk ok"]);
+			await store.advanceCursor("ops", "doctor", first.lastId ?? 0);
+			expect((await store.backlog("ops", "doctor", 40)).messages).toEqual([]);
+
+			const infra = await store.backlog("ops", "infra", 40);
+			expect(infra.messages.map((m) => m.id)).toEqual([owner]);
+			await store.advanceCursor("ops", "infra", infra.lastId ?? 0);
+
+			// A cursor never moves back, so a message is never delivered twice.
+			await store.advanceCursor("ops", "infra", owner - 1);
+			expect((await store.backlog("ops", "infra", 40)).messages).toEqual([]);
+		});
+
+		test("a long backlog carries the newest messages and counts the rest", async () => {
+			await makeGroup();
+			for (let i = 0; i < 5; i++)
+				await store.appendGroupMessage("ops", {
+					author: "owner",
+					authorName: "Riley",
+					text: `m${i}`,
+				});
+			const backlog = await store.backlog("ops", "doctor", 2);
+			expect(backlog.messages.map((m) => m.text)).toEqual(["m3", "m4"]);
+			expect(backlog.skipped).toBe(3);
+		});
+
+		test("catching up marks everything as received", async () => {
+			const group = await makeGroup();
+			await store.appendGroupMessage("ops", {
+				author: "owner",
+				authorName: "Riley",
+				text: "old",
+			});
+			await store.catchUp(group);
+			for (const member of group.members)
+				expect((await store.backlog("ops", member, 40)).messages).toEqual([]);
+		});
+	});
+});