pi-roundtable 0.1.0

package/src/core/builtin/modules.ts

@@ -0,0 +1,176 @@
+import { join } from "node:path";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { scheduleCommands } from "../discord/schedule-commands.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { OwnerIdentity } from "../identity.ts";
+import type { ModelRef, ThinkingLevel } from "../models.ts";
+import { BackgroundTurns } from "../modules/background/background-turns.ts";
+import { delegateExtension } from "../modules/delegation/delegate.ts";
+import {
+	type DelegationWorker,
+	Delegator,
+} from "../modules/delegation/delegator.ts";
+import { SolWorker } from "../modules/delegation/sol-worker.ts";
+import { discordAdminExtension } from "../modules/discord-admin/discord-admin.ts";
+import { ownerMemoryExtension } from "../modules/memory/owner-memory.ts";
+import { notifyExtension } from "../modules/notify/notify.ts";
+import { Scheduler } from "../modules/schedules/scheduler.ts";
+import {
+	type AgentChannelLookup,
+	schedulesExtension,
+} from "../modules/schedules/schedules.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import type {
+	SessionContext,
+	SessionTool,
+	SessionToolSnapshot,
+} from "../sessions.ts";
+import { THE_SPEAKER } from "../speakers.ts";
+
+export interface ModulesOptions {
+	/** Who the tools serve in the owner's own sessions. */
+	owner: OwnerIdentity & { id: string };
+	/** The name a turn the process itself starts is written by. */
+	assistant: string;
+	/** Shared with the rest of the host, so logins refresh in one place. */
+	modelRuntime: ModelRuntime;
+	agentDir: string;
+	dataDir: string;
+	/** The model that runs delegated tasks, or a worker of your own that replaces it. */
+	delegation: {
+		model: ModelRef;
+		thinking: ThinkingLevel;
+		worker?: DelegationWorker;
+	};
+	/** Another agent's channel, for reading its schedules; throws ScheduleError when unknown. */
+	agentChannelOf?: AgentChannelLookup;
+}
+
+/** A session tool whose extension never changes. */
+function fixed(
+	name: string,
+	factory: SessionToolSnapshot["factory"],
+): SessionTool {
+	return { name, phase: "tools", snapshot: () => ({ revision: 0, factory }) };
+}
+
+/**
+ * The owner's modules: memory, notifications, schedules, delegated tasks, and Discord reading
+ * and management, each a session tool, and the turns nobody wrote. The delegator's running jobs
+ * join the shutdown drain.
+ */
+export function modulesPlugin(options: ModulesOptions): RoundtablePlugin {
+	const { owner, agentChannelOf } = options;
+	// Outside the agent server a conversation has no channel of its own to post a run in.
+	const channelFor = async (
+		channel: ChannelKey,
+		surfaceOwnerChannel: () => Promise<ChannelKey>,
+	) => (channel.startsWith("discord:") ? channel : surfaceOwnerChannel());
+	return {
+		name: "modules",
+		setup: ({ conversations, core, logger }) => {
+			const { stores, discord } = core;
+			const { surface } = discord;
+			const ownerChannelFor = (channel: ChannelKey) =>
+				channelFor(channel, () => surface.ownerChannel());
+			const background = new BackgroundTurns({
+				conversations,
+				system: { id: "assistant", name: options.assistant },
+				logger,
+			});
+			const delegator = new Delegator({
+				worker:
+					options.delegation.worker ??
+					new SolWorker({
+						modelRuntime: options.modelRuntime,
+						agentDir: options.agentDir,
+						workDir: join(options.dataDir, "delegate"),
+						model: options.delegation.model,
+						thinking: options.delegation.thinking,
+					}),
+				deliver: (job, outcome) => background.runDelegated(job, outcome),
+				threads: discord.threads,
+				logger,
+			});
+			core.provide("background", background);
+			core.provide("delegator", delegator);
+			// An agent session serves every speaker, so its tools name none.
+			const served = (session: SessionContext) =>
+				session.agent ? THE_SPEAKER : owner;
+			return {
+				services: [
+					{ name: "delegator", busy: () => delegator.runningChannels() },
+				],
+				sessionTools: [
+					fixed("owner-memory", (session) =>
+						ownerMemoryExtension(
+							stores.memory,
+							served(session),
+							// The owner's own chats have one speaker; the agent server's have several.
+							session.agent ? session.speaker : undefined,
+						),
+					),
+					fixed("notify", () => notifyExtension(surface, owner)),
+					fixed("schedules", (session) =>
+						schedulesExtension(
+							{
+								store: stores.schedules,
+								owner: { id: owner.id, name: owner.name },
+								channelFor: ownerChannelFor,
+							},
+							session.homeChannel,
+							served(session),
+							session.agent ? agentChannelOf : undefined,
+							session.speaker,
+						),
+					),
+					fixed("delegate", (session) =>
+						delegateExtension(
+							{
+								delegator,
+								owner: { id: owner.id, name: owner.name },
+								channelFor: ownerChannelFor,
+							},
+							session.homeChannel,
+							served(session),
+							session.turnChannel,
+							session.speaker,
+						),
+					),
+					fixed("discord-admin", () =>
+						discordAdminExtension(surface.ownerDiscord(), owner),
+					),
+				],
+			};
+		},
+	};
+}
+
+/**
+ * Fires the schedules that fall due, and adds their slash commands. Registered apart from the
+ * modules so a plugin list can start the scheduler after everything a fired schedule reaches.
+ */
+export function schedulerPlugin(): RoundtablePlugin {
+	return {
+		name: "schedules",
+		setup: ({ core, logger }) => {
+			const scheduler = new Scheduler({
+				store: core.stores.schedules,
+				runner: core.background,
+				logger,
+			});
+			return {
+				services: [
+					{
+						name: "scheduler",
+						start: () => scheduler.start(),
+						stop: () => scheduler.stop(),
+					},
+				],
+				interactions: [
+					scheduleCommands(core.discord.guard, core.stores.schedules),
+				],
+			};
+		},
+	};
+}

package/src/core/builtin/seeds.ts

@@ -0,0 +1,10 @@
+import type { AgentSeed } from "../agents/agent-rules.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+
+/** The configured first team, created on the first start; an agent already stored is never overwritten. */
+export function seedsPlugin(agents: readonly AgentSeed[]): RoundtablePlugin {
+	return {
+		name: "seeds",
+		setup: () => ({ seeds: agents }),
+	};
+}

package/src/core/builtin/stores.ts

@@ -0,0 +1,42 @@
+import { AgentStore } from "../agents/agent-store.ts";
+import { OwnerMemoryStore } from "../modules/memory/owner-memory-store.ts";
+import { ScheduleStore } from "../modules/schedules/schedule-store.ts";
+import { SkillStore } from "../modules/skills/skill-store.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import { PendingConfirmationStore } from "../runtime/pending-confirmation-store.ts";
+
+export interface StoresOptions {
+	/** The owner's Discord id: the speaker whose memory the first rows belong to. */
+	ownerId: string;
+	/** The agent server's guild; every agent-server row carries it. */
+	guildId: string;
+}
+
+/**
+ * The core's own tables and the stores over them. The host migrates them over its one pool
+ * before any setup, in this order, and closes the pool after every service has stopped.
+ */
+export function storesPlugin(options: StoresOptions): RoundtablePlugin {
+	const { ownerId, guildId } = options;
+	return {
+		name: "stores",
+		migrations: [
+			...OwnerMemoryStore.migrations(ownerId),
+			ScheduleStore.migration,
+			PendingConfirmationStore.migration,
+			...AgentStore.migrations(guildId),
+			...SkillStore.migrations(guildId),
+		],
+		setup: async ({ database, core }) => {
+			const sql = database();
+			core.provide("stores", {
+				memory: OwnerMemoryStore.attach(sql, ownerId),
+				schedules: await ScheduleStore.attach(sql),
+				confirmations: await PendingConfirmationStore.attach(sql),
+				agents: await AgentStore.attach(sql, guildId),
+				skills: await SkillStore.attach(sql, guildId),
+			});
+			return {};
+		},
+	};
+}

package/src/core/config/config.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+import { ConfigError } from "../domain/errors.ts";
+import { type RoundtableConfig, resolveConfig } from "./config.ts";
+
+const minimal: RoundtableConfig = {
+	owner: { id: "100000000000000001", name: "Ada" },
+	discord: {
+		token: "token",
+		guild: "900000000000000001",
+		entryChannel: "900000000000000002",
+	},
+	database: { url: "postgres://localhost/roundtable" },
+	dataDir: "/data",
+	model: "anthropic/claude-sonnet-5-5",
+	http: { publicUrl: "https://bot.example.com" },
+};
+
+const refused = (input: unknown): string => {
+	try {
+		resolveConfig(input);
+	} catch (error) {
+		if (error instanceof ConfigError) return error.message;
+		throw error;
+	}
+	return "";
+};
+
+describe("resolveConfig", () => {
+	test("fills every default from a minimal configuration", () => {
+		const config = resolveConfig(minimal);
+		expect(config.name).toBe("Roundtable");
+		expect(config.owner).toEqual({
+			id: "100000000000000001",
+			name: "Ada",
+			pronouns: { subject: "they", object: "them", possessive: "their" },
+		});
+		expect(config.discord.rootCommand).toBe("roundtable");
+		expect(config.agentDir).toBe("/data/pi");
+		expect(config.model).toEqual({
+			provider: "anthropic",
+			id: "claude-sonnet-5-5",
+		});
+		expect(config.thinking).toBe("medium");
+		expect(config.judge).toEqual({ model: config.model, threshold: 0.6 });
+		expect(config.delegation).toEqual({
+			model: config.model,
+			thinking: "medium",
+		});
+		expect(config.locale).toBe("en");
+		expect(config.timeZone).toBe("UTC");
+		expect(config.http.port).toBe(3000);
+		expect(config.agents).toEqual([]);
+		expect(config.plugins).toEqual([]);
+	});
+
+	test("the root command follows the assistant's name unless one is given", () => {
+		expect(
+			resolveConfig({ ...minimal, name: "Robin Hood" }).discord.rootCommand,
+		).toBe("robin-hood");
+		expect(
+			resolveConfig({
+				...minimal,
+				discord: { ...minimal.discord, rootCommand: "rh" },
+			}).discord.rootCommand,
+		).toBe("rh");
+	});
+
+	test("pronouns become the words prompts use", () => {
+		const owner = { ...minimal.owner, pronouns: "she" as const };
+		expect(resolveConfig({ ...minimal, owner }).owner.pronouns).toEqual({
+			subject: "she",
+			object: "her",
+			possessive: "her",
+		});
+	});
+
+	test("an unknown key names the nearest known key, at any depth", () => {
+		expect(refused({ ...minimal, discrod: {} })).toStartWith(
+			'config discrod: unknown key. Did you mean "discord"? The keys here are name, owner, discord,',
+		);
+		expect(
+			refused({ ...minimal, discord: { ...minimal.discord, tokn: "x" } }),
+		).toContain('config discord.tokn: unknown key. Did you mean "token"?');
+	});
+
+	test("a missing required key names it and the fix", () => {
+		const { model: _model, ...without } = minimal;
+		expect(refused(without)).toBe(
+			"config model: required, expected a non-empty string. Add it to roundtable.config.ts.",
+		);
+		expect(refused({ ...minimal, owner: { name: "Ada" } })).toBe(
+			"config owner.id: required, expected a non-empty string. Add it to roundtable.config.ts.",
+		);
+	});
+
+	test("a wrong value says what was expected and what it got", () => {
+		expect(refused({ ...minimal, thinking: "loud" })).toBe(
+			'config thinking: expected one of off, minimal, low, medium, high, xhigh, got "loud". Fix the value in roundtable.config.ts.',
+		);
+		expect(
+			refused({ ...minimal, http: { publicUrl: "https://x", port: 70000 } }),
+		).toContain(
+			"config http.port: expected an integer from 1 to 65535, got 70000.",
+		);
+		expect(refused({ ...minimal, model: "sonnet" })).toBe(
+			'config model: expected <provider>/<id>, got "sonnet". Write it like anthropic/claude-sonnet-5-5.',
+		);
+		expect(refused({ ...minimal, locale: "fr" })).toContain(
+			"config locale: expected a locale, en or zh-TW",
+		);
+		expect(refused({ ...minimal, toolTiers: { shell: "root" } })).toContain(
+			"config toolTiers.shell: expected one of owner, admin, member",
+		);
+		expect(refused({ ...minimal, plugins: [{ name: "x" }] })).toContain(
+			"config plugins[0]: expected a plugin, an object with a name and a setup function",
+		);
+		expect(refused("nope")).toContain("expected an object");
+	});
+
+	test("agents are seeds with their four texts", () => {
+		const seed = {
+			name: "coordinator",
+			displayName: "Coordinator",
+			prompt: "You coordinate.",
+			avatarPrompt: "A calm coordinator.",
+			channelId: "900000000000000002",
+		};
+		expect(resolveConfig({ ...minimal, agents: [seed] }).agents).toEqual([
+			seed,
+		]);
+		expect(refused({ ...minimal, agents: [{ name: "x" }] })).toContain(
+			"config agents[0].displayName: required",
+		);
+	});
+});

package/src/core/config/config.ts

@@ -0,0 +1,285 @@
+import type { AgentSeed } from "../agents/agent-rules.ts";
+import { ConfigError } from "../domain/errors.ts";
+import { isLocale, type Locale } from "../i18n/index.ts";
+import type { OwnerIdentity } from "../identity.ts";
+import {
+	type ModelRef,
+	parseModelRef,
+	THINKING_LEVELS,
+	type ThinkingLevel,
+} from "../models.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import type { Tier, TierMembers } from "../speakers.ts";
+import {
+	bool,
+	guarded,
+	integer,
+	list,
+	number,
+	oneOf,
+	optional,
+	record,
+	shape,
+	text,
+} from "./schema.ts";
+
+/** How prompts refer back to the owner. */
+export type Pronouns = "he" | "she" | "they";
+
+/** Who holds a tier besides the owner: user ids, role ids, and for members everyone. */
+export interface TierConfig {
+	users?: readonly string[];
+	roles?: readonly string[];
+	everyone?: boolean;
+}
+
+/** What `roundtable.config.ts` gives `defineRoundtable`. */
+export interface RoundtableConfig {
+	/** The assistant's display name; default "Roundtable". */
+	name?: string;
+	/** The one owner: the only person who can change everything. */
+	owner: { id: string; name: string; pronouns?: Pronouns };
+	discord: {
+		/** The bot token; keep it in `.env`, not in this file. */
+		token: string;
+		/** The agent server's guild id. */
+		guild: string;
+		/** The channel the coordinator lives in. */
+		entryChannel: string;
+		/** The root slash command, without the slash; default the lowercase assistant name. */
+		rootCommand?: string;
+	};
+	database: { url: string };
+	/** Where the process keeps its files, such as pictures, attachments, and skills. */
+	dataDir: string;
+	/** Pi's agent directory, holding the model logins; default `<dataDir>/pi`. */
+	agentDir?: string;
+	/** The model of the agents, written `<provider>/<id>`. */
+	model: string;
+	/** The level a turn thinks at when its judge cannot pick; default "medium". */
+	thinking?: ThinkingLevel;
+	/** The model that judges small questions and the delegated tasks' model; default the agents' model. */
+	judge?: { model?: string; threshold?: number };
+	delegation?: { model?: string; thinking?: ThinkingLevel };
+	/** The language of what the bot shows in Discord; default "en". */
+	locale?: Locale;
+	/** The IANA time zone schedules and stamps use; default "UTC". */
+	timeZone?: string;
+	/** Who may talk to the agents besides the owner, and what each tier may use. */
+	speakers?: { admins?: TierConfig; members?: TierConfig };
+	toolTiers?: Record<string, Tier>;
+	/** Prompt files, read once at start; `shared` starts every agent's prompt. */
+	prompts?: { shared: string; guest?: string };
+	/** The first team, created once; an agent already stored is never overwritten. */
+	agents?: AgentSeed[];
+	/**
+	 * Where the agents' avatars are served: the public address that reaches it, and the TCP port
+	 * (default 3000) or unix socket the process listens on.
+	 */
+	http: {
+		publicUrl: string;
+		port?: number;
+		hostname?: string;
+		socketPath?: string;
+	};
+	/** A picture of your own for agents without one, and the style reference for drawing them; default a plain bot. */
+	avatar?: string;
+	/** The agents' shared working directory; default `<dataDir>/work`. */
+	workDir?: string;
+	skills?: { builtinDir?: string; reposDir?: string };
+	/** The agent that investigates the process's own errors, by name. */
+	ops?: { agent: string };
+	plugins?: RoundtablePlugin[];
+}
+
+const tierMembers = shape({
+	users: optional(list(text)),
+	roles: optional(list(text)),
+	everyone: optional(bool),
+});
+
+const isPlugin = (value: unknown): value is RoundtablePlugin =>
+	typeof value === "object" &&
+	value !== null &&
+	typeof (value as { name?: unknown }).name === "string" &&
+	typeof (value as { setup?: unknown }).setup === "function";
+
+const schema = shape({
+	name: optional(text),
+	owner: shape({
+		id: text,
+		name: text,
+		pronouns: optional(oneOf<Pronouns>("he", "she", "they")),
+	}),
+	discord: shape({
+		token: text,
+		guild: text,
+		entryChannel: text,
+		rootCommand: optional(text),
+	}),
+	database: shape({ url: text }),
+	dataDir: text,
+	agentDir: optional(text),
+	model: text,
+	thinking: optional(oneOf(...THINKING_LEVELS)),
+	judge: optional(
+		shape({ model: optional(text), threshold: optional(number(0, 1)) }),
+	),
+	delegation: optional(
+		shape({
+			model: optional(text),
+			thinking: optional(oneOf(...THINKING_LEVELS)),
+		}),
+	),
+	locale: optional(
+		guarded("a locale, en or zh-TW", (value): value is Locale =>
+			isLocale(value),
+		),
+	),
+	timeZone: optional(text),
+	speakers: optional(
+		shape({ admins: optional(tierMembers), members: optional(tierMembers) }),
+	),
+	toolTiers: optional(record(oneOf<Tier>("owner", "admin", "member"))),
+	prompts: optional(shape({ shared: text, guest: optional(text) })),
+	agents: optional(
+		list(
+			shape({
+				name: text,
+				displayName: text,
+				prompt: text,
+				avatarPrompt: text,
+				channelId: optional(text),
+			}),
+		),
+	),
+	http: shape({
+		publicUrl: text,
+		port: optional(integer(1, 65535)),
+		hostname: optional(text),
+		socketPath: optional(text),
+	}),
+	avatar: optional(text),
+	workDir: optional(text),
+	skills: optional(
+		shape({ builtinDir: optional(text), reposDir: optional(text) }),
+	),
+	ops: optional(shape({ agent: text })),
+	plugins: optional(
+		list(
+			guarded("a plugin, an object with a name and a setup function", isPlugin),
+		),
+	),
+});
+
+const PRONOUNS: Record<Pronouns, OwnerIdentity["pronouns"]> = {
+	he: { subject: "he", object: "him", possessive: "his" },
+	she: { subject: "she", object: "her", possessive: "her" },
+	they: { subject: "they", object: "them", possessive: "their" },
+};
+
+/** The configuration with every default filled in. */
+export interface ResolvedConfig {
+	name: string;
+	owner: OwnerIdentity & { id: string };
+	discord: {
+		token: string;
+		guild: string;
+		entryChannel: string;
+		rootCommand: string;
+	};
+	databaseUrl: string;
+	dataDir: string;
+	agentDir: string;
+	model: ModelRef;
+	thinking: ThinkingLevel;
+	judge: { model: ModelRef; threshold: number };
+	delegation: { model: ModelRef; thinking: ThinkingLevel };
+	locale: Locale;
+	timeZone: string;
+	speakers: { admins?: TierMembers; members?: TierMembers };
+	toolTiers: Record<string, Tier>;
+	prompts: { shared?: string; guest?: string };
+	agents: AgentSeed[];
+	http: {
+		publicUrl: string;
+		port: number;
+		hostname?: string;
+		socketPath?: string;
+	};
+	avatar?: string;
+	workDir: string;
+	skills: { builtinDir?: string; reposDir?: string };
+	ops?: { agent: string };
+	plugins: RoundtablePlugin[];
+}
+
+function modelOf(value: string, path: string): ModelRef {
+	const parsed = parseModelRef(value);
+	if (!parsed)
+		throw new ConfigError(
+			`config ${path}: expected <provider>/<id>, got ${JSON.stringify(value)}. Write it like anthropic/claude-sonnet-5-5.`,
+		);
+	return parsed;
+}
+
+/** The configuration checked against its schema, defaults filled; throws a ConfigError naming the key and the fix. */
+export function resolveConfig(input: unknown): ResolvedConfig {
+	const config = schema.check(input, "") as RoundtableConfig;
+	const name = config.name ?? "Roundtable";
+	const model = modelOf(config.model, "model");
+	const thinking = config.thinking ?? "medium";
+	return {
+		name,
+		owner: {
+			id: config.owner.id,
+			name: config.owner.name,
+			pronouns: PRONOUNS[config.owner.pronouns ?? "they"],
+		},
+		discord: {
+			token: config.discord.token,
+			guild: config.discord.guild,
+			entryChannel: config.discord.entryChannel,
+			rootCommand:
+				config.discord.rootCommand ??
+				name.toLowerCase().replace(/[^a-z0-9-]+/g, "-"),
+		},
+		databaseUrl: config.database.url,
+		dataDir: config.dataDir,
+		agentDir: config.agentDir ?? `${config.dataDir}/pi`,
+		model,
+		thinking,
+		judge: {
+			model: config.judge?.model
+				? modelOf(config.judge.model, "judge.model")
+				: model,
+			threshold: config.judge?.threshold ?? 0.6,
+		},
+		delegation: {
+			model: config.delegation?.model
+				? modelOf(config.delegation.model, "delegation.model")
+				: model,
+			thinking: config.delegation?.thinking ?? "medium",
+		},
+		locale: config.locale ?? "en",
+		timeZone: config.timeZone ?? "UTC",
+		speakers: {
+			...(config.speakers?.admins ? { admins: config.speakers.admins } : {}),
+			...(config.speakers?.members ? { members: config.speakers.members } : {}),
+		},
+		toolTiers: config.toolTiers ?? {},
+		prompts: config.prompts ?? {},
+		agents: config.agents ?? [],
+		http: {
+			publicUrl: config.http.publicUrl,
+			port: config.http.port ?? 3000,
+			...(config.http.hostname ? { hostname: config.http.hostname } : {}),
+			...(config.http.socketPath ? { socketPath: config.http.socketPath } : {}),
+		},
+		...(config.avatar ? { avatar: config.avatar } : {}),
+		workDir: config.workDir ?? `${config.dataDir}/work`,
+		skills: config.skills ?? {},
+		...(config.ops ? { ops: config.ops } : {}),
+		plugins: config.plugins ?? [],
+	};
+}