pi-roundtable 0.1.0

package/src/core/registry/contributions.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, test } from "bun:test";
+import { Type } from "typebox";
+import { defineTool } from "../define.ts";
+import { NotLinkedError, PluginError } from "../errors.ts";
+import { silentLogger } from "../log.ts";
+import type {
+	Contribution,
+	PluginContext,
+	RoundtablePlugin,
+} from "../plugin.ts";
+import { toolTiers } from "../tool-tiers.ts";
+import {
+	collectContributions,
+	linkSessions,
+	nearest,
+} from "./contributions.ts";
+
+/** A context the plugins under test never read. */
+const context = { logger: silentLogger() } as unknown as PluginContext;
+
+const plugin = (
+	name: string,
+	contribution: Contribution | (() => Contribution),
+): RoundtablePlugin => ({
+	name,
+	setup: () =>
+		typeof contribution === "function" ? contribution() : contribution,
+});
+
+const tool = (name: string, minTier: "member" | "admin" | "owner" = "member") =>
+	defineTool({
+		name,
+		description: "A tool.",
+		parameters: Type.Object({}),
+		minTier,
+		run: () => "ok",
+	});
+
+const collect = (plugins: RoundtablePlugin[], tiers = toolTiers()) =>
+	collectContributions(plugins, context, tiers);
+
+describe("collectContributions", () => {
+	test("names the part a typo meant, or lists the parts", async () => {
+		await expect(
+			collect([plugin("p", { serivces: [] } as unknown as Contribution)]),
+		).rejects.toThrow(
+			'plugin p: setup returned an unknown part "serivces". Did you mean "services"? The parts are services,',
+		);
+		await expect(
+			collect([plugin("p", { zzzzzz: [] } as unknown as Contribution)]),
+		).rejects.toThrow(
+			'plugin p: setup returned an unknown part "zzzzzz". The parts are services,',
+		);
+	});
+
+	test("refuses a plugin that adds nothing, and says what to give it", async () => {
+		await expect(collect([plugin("empty", {})])).rejects.toThrow(
+			"plugin empty adds nothing. Give it a part (tools, services, channels, and so on), a migration, or a provider, or remove it.",
+		);
+	});
+
+	test("a setup that throws or returns no object is named and keeps its cause", async () => {
+		const boom = new Error("boom");
+		const failing = collect([
+			plugin("p", () => {
+				throw boom;
+			}),
+		]);
+		await expect(failing).rejects.toThrow(
+			"plugin p: setup failed: boom. Fix the error, or remove the plugin.",
+		);
+		await expect(failing).rejects.toHaveProperty("cause", boom);
+		await expect(
+			collect([
+				plugin("early", () => {
+					throw new NotLinkedError("parts are linked later.");
+				}),
+			]),
+		).rejects.toThrow(
+			"plugin early: setup failed: parts are linked later. Fix the error, or remove the plugin.",
+		);
+		await expect(
+			collect([
+				{ name: "q", setup: () => undefined as unknown as Contribution },
+			]),
+		).rejects.toThrow(
+			"plugin q: setup must return an object of the parts it adds; return {} to add none.",
+		);
+	});
+
+	test("a service, a session tool, or a hold rule two plugins register names both plugins", async () => {
+		const service = { name: "sweeper" };
+		await expect(
+			collect([
+				plugin("a", { services: [service] }),
+				plugin("b", { services: [service] }),
+			]),
+		).rejects.toThrow(
+			"plugin b: service sweeper is already registered by plugin a. Rename one of the two.",
+		);
+		const rule = { name: "shell", describe: () => undefined };
+		await expect(
+			collect([
+				plugin("a", { holdRules: [rule] }),
+				plugin("b", { holdRules: [rule] }),
+			]),
+		).rejects.toThrow(
+			"plugin b: hold rule shell is already registered by plugin a. Rename one of the two.",
+		);
+	});
+
+	test("a tool two plugins define names both plugins", async () => {
+		await expect(
+			collect([
+				plugin("a", { tools: [tool("note_add")] }),
+				plugin("b", { tools: [tool("note_add")] }),
+			]),
+		).rejects.toThrow(
+			"plugin b: tool note_add is already defined by plugin a. Rename one of the two tools.",
+		);
+	});
+
+	test("a plugin's tools carry their tier, their hold rule, and their place among the agent's tools", async () => {
+		const tiers = toolTiers({ note_list: "admin" });
+		const held = defineTool({
+			name: "note_clear",
+			description: "Clear the notes.",
+			parameters: Type.Object({}),
+			minTier: "admin",
+			agent: false,
+			hold: () => "clear every note",
+			run: () => "cleared",
+		});
+		const registry = await collect(
+			[
+				plugin("notes", {
+					tools: [tool("note_add"), tool("note_list", "member"), held],
+				}),
+			],
+			tiers,
+		);
+		expect(tiers.minTier("note_add")).toBe("member");
+		// The operator's setting wins over the plugin's.
+		expect(tiers.minTier("note_list")).toBe("admin");
+		expect(tiers.minTier("note_clear")).toBe("admin");
+		const linked = linkSessions(registry);
+		expect(linked.agentTools).toEqual(["note_add", "note_list"]);
+		expect(linked.holds("note_clear", {}, {})).toBe("clear every note");
+		expect(linked.holds("note_add", {}, {})).toBeUndefined();
+	});
+
+	test("seeds and prompt sections are collected in contribution order", async () => {
+		const seed = (name: string) => ({
+			name,
+			displayName: name,
+			prompt: "p",
+			avatarPrompt: "a",
+		});
+		const section = (name: string) => ({ name, build: () => name });
+		const registry = await collect([
+			plugin("a", { seeds: [seed("one")], prompt: [section("x")] }),
+			plugin("b", { seeds: [seed("two")], prompt: [section("y")] }),
+		]);
+		const linked = linkSessions(registry);
+		expect(linked.seeds.map((s) => s.name)).toEqual(["one", "two"]);
+		expect(linked.prompt.map((s) => s.name)).toEqual(["x", "y"]);
+	});
+
+	test("every plugin's agent selection is merged when read, each name once", async () => {
+		let groups = ["mail"];
+		const registry = await collect([
+			plugin("a", {
+				agentSelection: () => ({ tools: ["web_search"], groups }),
+			}),
+			plugin("b", {
+				agentSelection: () => ({
+					tools: ["web_search", "notes"],
+					groups: ["mail", "calendar"],
+				}),
+			}),
+		]);
+		const linked = linkSessions(registry);
+		expect(linked.agentSelection()).toEqual({
+			tools: ["web_search", "notes"],
+			groups: ["mail", "calendar"],
+		});
+		// Read again at each turn, so a set that changes while the process runs stays current.
+		groups = ["docs"];
+		expect(linked.agentSelection().groups).toEqual([
+			"docs",
+			"mail",
+			"calendar",
+		]);
+		expect(
+			linkSessions(
+				await collect([plugin("c", { dashboard: ["a line"] })]),
+			).agentSelection(),
+		).toEqual({ tools: [], groups: [] });
+	});
+
+	test("every refusal is a PluginError", async () => {
+		await expect(collect([plugin("empty", {})])).rejects.toBeInstanceOf(
+			PluginError,
+		);
+	});
+});
+
+describe("nearest", () => {
+	test("finds a close word and nothing for a far one", () => {
+		const known = ["services", "events", "interactions"];
+		expect(nearest("serivces", known)).toBe("services");
+		expect(nearest("event", known)).toBe("events");
+		expect(nearest("banana", known)).toBeUndefined();
+	});
+});

package/src/core/registry/contributions.ts

@@ -0,0 +1,249 @@
+import type { AgentSeed } from "../agents/agent-store.ts";
+import type { ChannelClaim } from "../contract/channels.ts";
+import type { InteractionContribution } from "../contract/discord.ts";
+import type { ToolContribution } from "../define.ts";
+import { PluginError } from "../errors.ts";
+import { type HoldRule, holdChain } from "../holds.ts";
+import type { HttpRoute } from "../http/listeners.ts";
+import {
+	CONTRIBUTION_KEYS,
+	type Contribution,
+	type EventHandlers,
+	type LinkedSessions,
+	type PluginContext,
+	type PromptSection,
+	type RoundtablePlugin,
+	type Service,
+} from "../plugin.ts";
+import {
+	compileSessionPlan,
+	type SessionTool,
+	type ToolSelection,
+} from "../sessions.ts";
+import type { ToolTierTable } from "../tool-tiers.ts";
+
+/** Everything the plugins contributed, in contribution order. */
+export interface Registry {
+	services: Service[];
+	handlers: { plugin: string; events: EventHandlers }[];
+	interactions: InteractionContribution[];
+	routes: HttpRoute[];
+	holdRules: HoldRule[];
+	piPackages: string[];
+	sessionTools: SessionTool[];
+	channels: ChannelClaim[];
+	dashboard: string[];
+	tools: ToolContribution[];
+	seeds: AgentSeed[];
+	prompt: PromptSection[];
+	agentSelections: (() => ToolSelection)[];
+}
+
+export const emptyRegistry = (): Registry => ({
+	services: [],
+	handlers: [],
+	interactions: [],
+	routes: [],
+	holdRules: [],
+	piPackages: [],
+	sessionTools: [],
+	channels: [],
+	dashboard: [],
+	tools: [],
+	seeds: [],
+	prompt: [],
+	agentSelections: [],
+});
+
+/** The edit distance between two words, for naming the key a typo meant. */
+function distance(a: string, b: string): number {
+	const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+	for (let i = 1; i <= a.length; i++) {
+		let previous = row[0] ?? 0;
+		row[0] = i;
+		for (let j = 1; j <= b.length; j++) {
+			const above = row[j] ?? 0;
+			row[j] = Math.min(
+				above + 1,
+				(row[j - 1] ?? 0) + 1,
+				previous + (a[i - 1] === b[j - 1] ? 0 : 1),
+			);
+			previous = above;
+		}
+	}
+	return row[b.length] ?? 0;
+}
+
+/** The known name nearest to `word`, when one is close enough to be what was meant. */
+export function nearest(
+	word: string,
+	known: readonly string[],
+): string | undefined {
+	let best: { name: string; distance: number } | undefined;
+	for (const name of known) {
+		const d = distance(word.toLowerCase(), name.toLowerCase());
+		if (!best || d < best.distance) best = { name, distance: d };
+	}
+	return best && best.distance <= Math.max(2, Math.floor(word.length / 3))
+		? best.name
+		: undefined;
+}
+
+/** Refuses a contribution with a key the contract does not define, naming the nearest one. */
+function checkKeys(plugin: string, contribution: Contribution): void {
+	for (const key of Object.keys(contribution)) {
+		if ((CONTRIBUTION_KEYS as readonly string[]).includes(key)) continue;
+		const meant = nearest(key, CONTRIBUTION_KEYS);
+		throw new PluginError(
+			`plugin ${plugin}: setup returned an unknown part "${key}".${
+				meant ? ` Did you mean "${meant}"?` : ""
+			} The parts are ${CONTRIBUTION_KEYS.join(", ")}.`,
+		);
+	}
+}
+
+/** The selections' tools and groups, each once, in the order the plugins gave them. */
+function mergeSelections(
+	selections: readonly (() => ToolSelection)[],
+): ToolSelection {
+	const read = selections.map((selection) => selection());
+	return {
+		tools: [...new Set(read.flatMap((s) => s.tools))],
+		groups: [...new Set(read.flatMap((s) => s.groups))],
+	};
+}
+
+/** Which plugin registered each name of one kind, so a clash names both. */
+class Names {
+	readonly #owners = new Map<string, string>();
+
+	constructor(private readonly kind: string) {}
+
+	claim(plugin: string, name: string): void {
+		const other = this.#owners.get(name);
+		if (other !== undefined)
+			throw new PluginError(
+				`plugin ${plugin}: ${this.kind} ${name} is already registered by plugin ${other}. Rename one of the two.`,
+			);
+		this.#owners.set(name, plugin);
+	}
+}
+
+/**
+ * Sets up every plugin in order and collects what each adds. A plugin that adds nothing, that
+ * reuses a name, or whose setup throws or returns a part the contract does not have is refused
+ * with its name and what to fix.
+ */
+export async function collectContributions(
+	plugins: readonly RoundtablePlugin[],
+	context: PluginContext,
+	tiers: ToolTierTable,
+): Promise<Registry> {
+	const registry = emptyRegistry();
+	const services = new Names("service");
+	const sessionTools = new Names("session tool");
+	const holds = new Names("hold rule");
+	for (const plugin of plugins) {
+		let contribution: Contribution;
+		try {
+			contribution = await plugin.setup(context);
+		} catch (error) {
+			if (error instanceof PluginError) throw error;
+			// Some messages end in a period already, such as a NotLinkedError's.
+			const reason = (
+				error instanceof Error ? error.message : String(error)
+			).replace(/\.+$/, "");
+			throw new PluginError(
+				`plugin ${plugin.name}: setup failed: ${reason}. Fix the error, or remove the plugin.`,
+				{ cause: error },
+			);
+		}
+		if (typeof contribution !== "object" || contribution === null)
+			throw new PluginError(
+				`plugin ${plugin.name}: setup must return an object of the parts it adds; return {} to add none.`,
+			);
+		checkKeys(plugin.name, contribution);
+		const {
+			events,
+			interactions = [],
+			http = [],
+			holdRules = [],
+			piPackages = [],
+			channels = [],
+			dashboard = [],
+			tools = [],
+			seeds = [],
+			prompt = [],
+		} = contribution;
+		const parts = [
+			contribution.services ?? [],
+			interactions,
+			http,
+			holdRules,
+			piPackages,
+			contribution.sessionTools ?? [],
+			channels,
+			dashboard,
+			tools,
+			seeds,
+			prompt,
+			contribution.agentSelection ? [contribution.agentSelection] : [],
+		];
+		const declares =
+			(plugin.migrations?.length ?? 0) > 0 ||
+			Object.keys(plugin.providers ?? {}).length > 0 ||
+			plugin.preflight !== undefined ||
+			plugin.useCommands !== undefined ||
+			plugin.agentServer !== undefined ||
+			plugin.stopTurn !== undefined;
+		if (!declares && !events && parts.every((part) => part.length === 0))
+			throw new PluginError(
+				`plugin ${plugin.name} adds nothing. Give it a part (tools, services, channels, and so on), a migration, or a provider, or remove it.`,
+			);
+		for (const service of contribution.services ?? []) {
+			services.claim(plugin.name, service.name);
+			registry.services.push(service);
+		}
+		for (const rule of holdRules) holds.claim(plugin.name, rule.name);
+		for (const tool of contribution.sessionTools ?? []) {
+			sessionTools.claim(plugin.name, tool.name);
+			registry.sessionTools.push(tool);
+		}
+		for (const tool of tools) {
+			tiers.declare(plugin.name, { [tool.name]: tool.minTier });
+			sessionTools.claim(plugin.name, tool.session.name);
+			registry.sessionTools.push(tool.session);
+			registry.tools.push(tool);
+			if (tool.hold) {
+				holds.claim(plugin.name, tool.hold.name);
+				registry.holdRules.push(tool.hold);
+			}
+		}
+		if (contribution.agentSelection)
+			registry.agentSelections.push(contribution.agentSelection);
+		if (events) registry.handlers.push({ plugin: plugin.name, events });
+		registry.interactions.push(...interactions);
+		registry.routes.push(...http);
+		registry.holdRules.push(...holdRules);
+		registry.piPackages.push(...piPackages);
+		registry.channels.push(...channels);
+		registry.dashboard.push(...dashboard);
+		registry.seeds.push(...seeds);
+		registry.prompt.push(...prompt);
+	}
+	return registry;
+}
+
+/** Links the collected session parts; throws PluginError on a clash. */
+export function linkSessions(registry: Registry): LinkedSessions {
+	return {
+		holds: holdChain(registry.holdRules),
+		// A package two plugins ask for loads once, where it was first asked for.
+		piPackages: [...new Set(registry.piPackages)],
+		plan: compileSessionPlan(registry.sessionTools),
+		seeds: registry.seeds,
+		prompt: registry.prompt,
+		agentTools: registry.tools.filter((t) => t.agent).map((t) => t.name),
+		agentSelection: () => mergeSelections(registry.agentSelections),
+	};
+}

package/src/core/registry/interactions.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { InteractionContextType } from "discord.js";
+import type { InteractionModule, RootOption } from "../contract/discord.ts";
+import { PluginError } from "../errors.ts";
+import { composeInteractions } from "./interactions.ts";
+
+const ROOT = {
+	name: "roundtable",
+	description: "control",
+	contexts: [InteractionContextType.Guild, InteractionContextType.BotDM],
+};
+
+function module(...names: string[]): InteractionModule {
+	return {
+		commands: () =>
+			names.map((name) => ({ name, description: name, type: 1 as const })),
+		handle: async () => false,
+	};
+}
+
+const sub = (name: string): RootOption => ({
+	type: 1,
+	name,
+	description: name,
+});
+
+describe("composeInteractions", () => {
+	test("puts every contribution's subcommands under one root, after the modules' own commands", () => {
+		const a = module("roll");
+		const b = module();
+		const composed = composeInteractions(ROOT, [
+			{ module: b, rootOptions: [sub("help"), sub("status")] },
+			{ module: a },
+			{ module: module(), rootOptions: [sub("party")] },
+		]);
+		expect(composed.commands.map((c) => c.name)).toEqual([
+			"roll",
+			"roundtable",
+		]);
+		const root = composed.commands[1];
+		expect(root?.options?.map((o) => o.name)).toEqual([
+			"help",
+			"status",
+			"party",
+		]);
+		expect(root?.contexts).toEqual(ROOT.contexts);
+		expect(composed.modules[0]).toBe(b);
+		expect(composed.modules[1]).toBe(a);
+	});
+
+	test("registers no root without subcommands", () => {
+		const composed = composeInteractions(ROOT, [{ module: module("dice") }]);
+		expect(composed.commands.map((c) => c.name)).toEqual(["dice"]);
+	});
+
+	test("refuses a subcommand added twice, a command registered twice, and a module registering the root", () => {
+		const refused = (build: () => unknown) => {
+			try {
+				build();
+				return undefined;
+			} catch (error) {
+				return error;
+			}
+		};
+		expect(
+			refused(() =>
+				composeInteractions(ROOT, [
+					{ module: module(), rootOptions: [sub("mcp")] },
+					{ module: module(), rootOptions: [sub("mcp")] },
+				]),
+			),
+		).toBeInstanceOf(PluginError);
+		expect(
+			refused(() =>
+				composeInteractions(ROOT, [
+					{ module: module("roll") },
+					{ module: module("roll") },
+				]),
+			),
+		).toBeInstanceOf(PluginError);
+		expect(
+			refused(() =>
+				composeInteractions(ROOT, [{ module: module("roundtable") }]),
+			),
+		).toBeInstanceOf(PluginError);
+	});
+});

package/src/core/registry/interactions.ts

@@ -0,0 +1,55 @@
+import {
+	type RESTPostAPIChatInputApplicationCommandsJSONBody,
+	SlashCommandBuilder,
+} from "discord.js";
+import type {
+	CommandRoot,
+	InteractionContribution,
+	InteractionModule,
+} from "../contract/discord.ts";
+import { PluginError } from "../errors.ts";
+
+/** Every command to register with Discord, and the modules that answer them in order. */
+export interface ComposedInteractions {
+	commands: RESTPostAPIChatInputApplicationCommandsJSONBody[];
+	modules: InteractionModule[];
+}
+
+/**
+ * Composes the root command from every contribution's subcommands, in contribution order, after
+ * the modules' own commands. Refuses a module that registers the root itself, and any command or
+ * subcommand name used twice.
+ */
+export function composeInteractions(
+	root: CommandRoot,
+	contributions: readonly InteractionContribution[],
+): ComposedInteractions {
+	const commands = contributions.flatMap(({ module }) => module.commands());
+	const names = new Set<string>();
+	for (const command of commands) {
+		if (command.name === root.name)
+			throw new PluginError(
+				`/${root.name} is composed from subcommands; a module may not register it`,
+			);
+		if (names.has(command.name))
+			throw new PluginError(`/${command.name} is registered twice`);
+		names.add(command.name);
+	}
+	const options = contributions.flatMap((c) => c.rootOptions ?? []);
+	const subcommands = new Set<string>();
+	for (const option of options) {
+		if (subcommands.has(option.name))
+			throw new PluginError(`/${root.name} ${option.name} is added twice`);
+		subcommands.add(option.name);
+	}
+	if (options.length > 0)
+		commands.push({
+			...new SlashCommandBuilder()
+				.setName(root.name)
+				.setDescription(root.description)
+				.setContexts(...root.contexts)
+				.toJSON(),
+			options: [...options],
+		});
+	return { commands, modules: contributions.map((c) => c.module) };
+}

package/src/core/registry/providers.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import type { Judge, Providers } from "../contract/providers.ts";
+import { PluginError, ProviderError } from "../errors.ts";
+import { Roundtable } from "../host.ts";
+import { ModelJudge } from "../judging/model-judge.ts";
+import { silentLogger } from "../log.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import { resolveProviders } from "./providers.ts";
+
+/** What the promise rejected with; undefined when it resolved. */
+async function rejection(promise: Promise<unknown>): Promise<unknown> {
+	try {
+		await promise;
+	} catch (error) {
+		return error;
+	}
+	return undefined;
+}
+
+const fixedJudge: Judge = {
+	askYesNo: async () => ({ approves: 1 }),
+	askChoice: async () => ({ choice: "a", confidence: 1 }),
+	askScore: async () => [1],
+};
+
+const providing = (
+	name: string,
+	providers: Partial<Providers>,
+): RoundtablePlugin => ({ name, providers, setup: () => ({}) });
+
+describe("resolveProviders", () => {
+	test("without plugins, the judge asks the given model and images refuse", async () => {
+		const resolved = resolveProviders([], async () => '{"approves": 0.7}');
+		expect(resolved.judge).toBeInstanceOf(ModelJudge);
+		expect(
+			await resolved.judge.askYesNo(
+				{},
+				{
+					approves: { type: "yesno", instructions: "Approve?" },
+				},
+			),
+		).toEqual({ approves: 0.7 });
+		expect(await rejection(resolved.images("a cat", []))).toBeInstanceOf(
+			ProviderError,
+		);
+	});
+
+	test("without a judge model, every judgment refuses so callers keep their defaults", async () => {
+		const { judge } = resolveProviders([]);
+		expect(
+			await rejection(
+				judge.askScore({}, "effort", {
+					type: "score",
+					instructions: "",
+					criteria: [],
+				}),
+			),
+		).toBeInstanceOf(ProviderError);
+	});
+
+	test("a plugin's provider replaces the default for its slot only", () => {
+		const images = async () => new Uint8Array([1]);
+		const resolved = resolveProviders([
+			providing("acme-judge", { judge: fixedJudge }),
+			providing("codex", { images }),
+		]);
+		expect(resolved.judge).toBe(fixedJudge);
+		expect(resolved.images).toBe(images);
+	});
+
+	test("two plugins filling one slot clash", () => {
+		expect(() =>
+			resolveProviders([
+				providing("acme-judge", { judge: fixedJudge }),
+				providing("other", { judge: fixedJudge }),
+			]),
+		).toThrow(PluginError);
+	});
+});
+
+describe("Roundtable providers", () => {
+	test("a provider-only plugin is valid, and setups read the resolved providers", async () => {
+		let seen: Judge | undefined;
+		const roundtable = new Roundtable(
+			{
+				logger: silentLogger(),
+				exit: () => {},
+			},
+			[
+				providing("acme-judge", { judge: fixedJudge }),
+				{
+					name: "reader",
+					setup: ({ providers }) => {
+						seen = providers.judge;
+						return { events: {} };
+					},
+				},
+			],
+		);
+		await roundtable.run();
+		expect(seen).toBe(fixedJudge);
+	});
+});