pi-roundtable 0.1.0

package/src/core/registry/providers.ts

@@ -0,0 +1,55 @@
+import type { Judge, Providers } from "../contract/providers.ts";
+import { PluginError, ProviderError } from "../errors.ts";
+import { type JudgeModel, ModelJudge } from "../judging/model-judge.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+
+const SLOTS = [
+	"judge",
+	"images",
+] as const satisfies readonly (keyof Providers)[];
+
+/** A judge with no model: every question throws, so each caller keeps its own default. */
+const unconfiguredJudge = (): Judge => {
+	const refuse = async (): Promise<never> => {
+		throw new ProviderError(
+			"no judge is configured: provide one or give the host a judge model",
+		);
+	};
+	return { askYesNo: refuse, askChoice: refuse, askScore: refuse };
+};
+
+/** The core's own providers, for the slots no plugin fills. */
+function defaults(judgeModel: JudgeModel | undefined): Providers {
+	return {
+		judge: judgeModel ? new ModelJudge(judgeModel) : unconfiguredJudge(),
+		images: async () => {
+			throw new ProviderError(
+				"no image provider is configured; agents keep the neutral avatar",
+			);
+		},
+	};
+}
+
+/** Each slot from the one plugin that fills it, else the core's default; two plugins filling one slot clash. */
+export function resolveProviders(
+	plugins: readonly RoundtablePlugin[],
+	judgeModel?: JudgeModel,
+): Providers {
+	const resolved = defaults(judgeModel);
+	const filledBy = new Map<keyof Providers, string>();
+	for (const plugin of plugins) {
+		for (const slot of SLOTS) {
+			const provided = plugin.providers?.[slot];
+			if (!provided) continue;
+			const other = filledBy.get(slot);
+			if (other)
+				throw new PluginError(
+					`plugin ${plugin.name}: provider slot ${slot} is already filled by plugin ${other}. Keep one plugin that fills it.`,
+				);
+			filledBy.set(slot, plugin.name);
+			// One key of a Providers, so the slot and its provider agree.
+			Object.assign(resolved, { [slot]: provided });
+		}
+	}
+	return resolved;
+}

package/src/core/routing/channel-queue.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import { ChannelQueue } from "./channel-queue.ts";
+
+describe("ChannelQueue", () => {
+	test("reports every change of a channel's count", async () => {
+		const queue = new ChannelQueue();
+		const seen: [string, number][] = [];
+		queue.onChange((channel) => seen.push([channel, queue.size(channel)]));
+		let release = () => {};
+		const first = queue.run(
+			"discord:1",
+			() => new Promise<void>((resolve) => (release = resolve)),
+		);
+		const second = queue.run("discord:1", async () => {});
+		expect(seen).toEqual([
+			["discord:1", 1],
+			["discord:1", 2],
+		]);
+		// The first task starts on a later tick.
+		await Bun.sleep(0);
+		release();
+		await Promise.all([first, second]);
+		await Bun.sleep(0);
+		expect(seen).toEqual([
+			["discord:1", 1],
+			["discord:1", 2],
+			["discord:1", 1],
+			["discord:1", 0],
+		]);
+	});
+});

package/src/core/routing/channel-queue.ts

@@ -0,0 +1,44 @@
+import type { ChannelKey } from "../sessions.ts";
+
+/** Runs tasks one at a time per channel, in arrival order; different channels run independently. */
+export class ChannelQueue {
+	readonly #tails = new Map<ChannelKey, Promise<unknown>>();
+	readonly #sizes = new Map<ChannelKey, number>();
+	readonly #listeners: ((channel: ChannelKey) => void)[] = [];
+
+	/** Called whenever a channel's count of running and waiting tasks changes. */
+	onChange(listener: (channel: ChannelKey) => void): void {
+		this.#listeners.push(listener);
+	}
+
+	#changed(channel: ChannelKey): void {
+		for (const listener of this.#listeners) listener(channel);
+	}
+
+	run<T>(channel: ChannelKey, task: () => Promise<T>): Promise<T> {
+		this.#sizes.set(channel, this.size(channel) + 1);
+		this.#changed(channel);
+		const previous = this.#tails.get(channel) ?? Promise.resolve();
+		const result = previous.then(task, task);
+		const tail = result.catch(() => undefined);
+		this.#tails.set(channel, tail);
+		void tail.then(() => {
+			const left = this.size(channel) - 1;
+			if (left > 0) this.#sizes.set(channel, left);
+			else this.#sizes.delete(channel);
+			if (this.#tails.get(channel) === tail) this.#tails.delete(channel);
+			this.#changed(channel);
+		});
+		return result;
+	}
+
+	/** Tasks of the channel running or waiting. */
+	size(channel: ChannelKey): number {
+		return this.#sizes.get(channel) ?? 0;
+	}
+
+	/** Channels with a task running or waiting. */
+	busy(): ChannelKey[] {
+		return [...this.#sizes.keys()];
+	}
+}

package/src/core/routing/channel-router.test.ts

@@ -0,0 +1,326 @@
+import { describe, expect, test } from "bun:test";
+import type {
+	Admission,
+	ChannelClaim,
+	InboundMessage,
+} from "../contract/channels.ts";
+import { PluginError } from "../errors.ts";
+import { silentLogger } from "../log.ts";
+import type { ChannelKey } from "../sessions.ts";
+import { ChannelQueue } from "./channel-queue.ts";
+import { ChannelRouter, orderClaims } from "./channel-router.ts";
+
+function message(overrides: Partial<InboundMessage> = {}): InboundMessage {
+	return {
+		channel: "discord:1",
+		messageId: "m1",
+		authorId: "owner",
+		authorName: "Riley",
+		authorIsBot: false,
+		isDirect: true,
+		mentionsBot: false,
+		repliesToBot: false,
+		text: "hi",
+		attachments: [],
+		...overrides,
+	};
+}
+
+/** A claim over `channels` (every channel when empty) that records what it does in `log`. */
+function claim(
+	name: string,
+	priority: number,
+	log: string[],
+	options: {
+		channels?: string[];
+		guild?: string;
+		admit?: (message: InboundMessage) => Admission | undefined;
+		deletes?: boolean;
+	} = {},
+): ChannelClaim {
+	const { channels = [], guild } = options;
+	return {
+		name,
+		priority,
+		owns: (channel, guildId) =>
+			channels.length === 0 ||
+			channels.includes(channel) ||
+			(guild !== undefined && guildId === guild),
+		admit:
+			options.admit ??
+			((m) => ({
+				kind: "turn",
+				run: async () => void log.push(`${name} ${m.text}`),
+				failure: `${name} failed`,
+			})),
+		background: async (turn) => {
+			log.push(`${name} background ${turn.text}`);
+			return { status: "ran" };
+		},
+		startFresh: async (channel) => {
+			log.push(`${name} fresh ${channel}`);
+			return name;
+		},
+		...(options.deletes
+			? {
+					deleteConversation: async (channel: ChannelKey) =>
+						void log.push(`${name} delete ${channel}`),
+				}
+			: {}),
+	};
+}
+
+function router(claims: ChannelClaim[], queue = new ChannelQueue()) {
+	return new ChannelRouter({
+		claims,
+		queue,
+		stop: () => false,
+		logger: silentLogger(),
+		forwardJoinMs: 10,
+	});
+}
+
+describe("orderClaims", () => {
+	test("orders by descending priority, keeping registration order among equals", () => {
+		const log: string[] = [];
+		const ordered = orderClaims([
+			claim("owner", 0, log),
+			claim("party", 20, log),
+			claim("first", 30, log),
+			claim("second", 30, log),
+			claim("agents", 100, log),
+		]);
+		expect(ordered.map((c) => c.name)).toEqual([
+			"agents",
+			"first",
+			"second",
+			"party",
+			"owner",
+		]);
+	});
+
+	test("refuses a claim name used twice", () => {
+		const log: string[] = [];
+		expect(() =>
+			orderClaims([claim("party", 20, log), claim("party", 0, log)]),
+		).toThrow(PluginError);
+	});
+});
+
+describe("ChannelRouter", () => {
+	test("the highest claim owning a channel answers there; the owner takes the rest", async () => {
+		const log: string[] = [];
+		const routing = router([
+			claim("owner", 0, log),
+			claim("party", 20, log, { channels: ["discord:party"] }),
+			claim("agents", 100, log, { channels: ["discord:agent"] }),
+		]);
+		await routing.handle(message({ channel: "discord:party", text: "a" }));
+		await routing.handle(message({ channel: "discord:agent", text: "b" }));
+		await routing.handle(message({ channel: "discord:dm", text: "c" }));
+		expect(log).toEqual(["party a", "agents b", "owner c"]);
+	});
+
+	test("a message the owning claim refuses is dropped, never passed to a lower claim", async () => {
+		const log: string[] = [];
+		const routing = router([
+			claim("owner", 0, log),
+			claim("agents", 100, log, {
+				channels: ["discord:agent"],
+				guild: "agent-guild",
+				admit: () => undefined,
+			}),
+		]);
+		await routing.handle(message({ guildId: "agent-guild", text: "notes" }));
+		await routing.handle(message({ guildId: "other", text: "hello" }));
+		expect(log).toEqual(["owner hello"]);
+	});
+
+	test("an empty message reaches no claim", async () => {
+		const log: string[] = [];
+		await router([claim("owner", 0, log)]).handle(message({ text: " " }));
+		expect(log).toEqual([]);
+	});
+
+	test("a message during a turn is offered to it, else marked until its own turn starts", async () => {
+		const log: string[] = [];
+		const queue = new ChannelQueue();
+		let takes = true;
+		let release = () => {};
+		const running = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		const routing = router(
+			[
+				claim("owner", 0, log, {
+					admit: (m) => ({
+						kind: "turn",
+						busy: {
+							steer: async () => takes,
+							react: async (emoji) => void log.push(`+${emoji} ${m.text}`),
+							unreact: async (emoji) => void log.push(`-${emoji} ${m.text}`),
+						},
+						run: async () => {
+							log.push(`run ${m.text}`);
+							if (m.text === "first") await running;
+						},
+						failure: "failed",
+					}),
+				}),
+			],
+			queue,
+		);
+		const first = routing.handle(message({ text: "first" }));
+		await Bun.sleep(1);
+		await routing.handle(message({ text: "steered" }));
+		takes = false;
+		const waiting = routing.handle(message({ text: "waiting" }));
+		await Bun.sleep(1);
+		release();
+		await Promise.all([first, waiting]);
+		expect(log).toEqual([
+			"run first",
+			"+↪️ steered",
+			"+⏳ waiting",
+			"-⏳ waiting",
+			"run waiting",
+		]);
+	});
+
+	test("a claim without busy handling is never marked", async () => {
+		const log: string[] = [];
+		const queue = new ChannelQueue();
+		const routing = router([claim("party", 0, log)], queue);
+		const first = routing.handle(message({ text: "one" }));
+		await routing.handle(message({ text: "two" }));
+		await first;
+		expect(log).toEqual(["party one", "party two"]);
+	});
+
+	test("a background admission runs as a background turn and reports when it did not run", async () => {
+		const log: string[] = [];
+		const routing = router([
+			{
+				...claim("agents", 0, log),
+				admit: (m) => ({
+					kind: "background",
+					turn: {
+						channel: m.channel,
+						mode: "owner",
+						author: { id: "ci", name: "CI" },
+						turnId: "webhook-1",
+						text: m.text,
+						report: true,
+					},
+					unanswered: (outcome) => log.push(`unanswered ${outcome.status}`),
+				}),
+				background: async () => ({ status: "skipped", reason: "busy" }),
+			},
+		]);
+		await routing.handle(message({ text: "build failed" }));
+		expect(log).toEqual(["unanswered skipped"]);
+	});
+
+	test("background turns and starting over go to the channel's owner when their queued turn starts", async () => {
+		const log: string[] = [];
+		const queue = new ChannelQueue();
+		const party = new Set<string>();
+		const routing = router(
+			[
+				claim("owner", 0, log),
+				{
+					...claim("party", 20, log),
+					owns: (channel) => party.has(channel),
+				},
+			],
+			queue,
+		);
+		let release = () => {};
+		const blocker = queue.run(
+			"discord:1",
+			() =>
+				new Promise<void>((resolve) => {
+					release = resolve;
+				}),
+		);
+		await Bun.sleep(1);
+		const turn = routing.background({
+			channel: "discord:1",
+			mode: "party",
+			author: { id: "owner", name: "Riley" },
+			turnId: "schedule-1",
+			text: "reminder",
+		});
+		const fresh = routing.startFresh("discord:1");
+		// Party mode turns on while the turn waits in the queue.
+		party.add("discord:1");
+		release();
+		await blocker;
+		expect(await turn).toEqual({ status: "ran" });
+		expect(await fresh).toBe("party");
+		expect(log).toEqual(["party background reminder", "party fresh discord:1"]);
+	});
+
+	test("deletes only through a claim that deletes, and never while the channel is busy", async () => {
+		const log: string[] = [];
+		const queue = new ChannelQueue();
+		const routing = router(
+			[
+				claim("owner", 0, log, { deletes: true }),
+				claim("party", 20, log, { channels: ["discord:party"] }),
+			],
+			queue,
+		);
+		await expect(routing.deleteConversation("discord:party")).rejects.toThrow(
+			"discord:party is not an owner conversation",
+		);
+		let release = () => {};
+		const blocker = queue.run(
+			"discord:1",
+			() =>
+				new Promise<void>((resolve) => {
+					release = resolve;
+				}),
+		);
+		await Bun.sleep(1);
+		expect(await routing.deleteConversation("discord:1")).toBe("busy");
+		release();
+		await blocker;
+		// The queue counts the finished task out once its tail settles.
+		await Bun.sleep(1);
+		expect(await routing.deleteConversation("discord:1")).toBe("deleted");
+		expect(log).toEqual(["owner delete discord:1"]);
+	});
+
+	test("reports stay in place only where the channel's owner says so", () => {
+		const log: string[] = [];
+		const routing = router([
+			claim("owner", 0, log),
+			{
+				...claim("party", 20, log, { channels: ["discord:party"] }),
+				postsInPlace: true,
+			},
+		]);
+		expect(routing.postsInPlace("discord:party")).toBe(true);
+		expect(routing.postsInPlace("discord:dm")).toBe(false);
+	});
+
+	test("a turn that throws is logged and the next still runs", async () => {
+		const log: string[] = [];
+		const routing = router([
+			claim("owner", 0, log, {
+				admit: (m) => ({
+					kind: "turn",
+					run: async () => {
+						if (m.text === "boom") throw new Error("boom");
+						log.push(`run ${m.text}`);
+					},
+					failure: "failed",
+				}),
+			}),
+		]);
+		await routing.handle(message({ text: "boom" }));
+		await routing.handle(message({ text: "next" }));
+		expect(log).toEqual(["run next"]);
+	});
+});

package/src/core/routing/channel-router.ts

@@ -0,0 +1,157 @@
+import {
+	type BackgroundTurn,
+	type ChannelClaim,
+	type ConversationPort,
+	type InboundMessage,
+	QUEUED_MARK,
+	type ScheduledOutcome,
+	STEERED_MARK,
+} from "../contract/channels.ts";
+import { PluginError } from "../errors.ts";
+import type { Logger } from "../log.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type { ChannelQueue } from "./channel-queue.ts";
+import { ForwardJoin } from "./forward-join.ts";
+
+export interface ChannelRouterOptions {
+	/** Claims in registration order; the router orders them by priority. */
+	claims: readonly ChannelClaim[];
+	queue: ChannelQueue;
+	/** Stops the channel's running turn; false when none runs. */
+	stop(channel: ChannelKey): boolean;
+	logger: Logger;
+	/** How long a bare forward waits for the text sent with it; FORWARD_JOIN_MS by default. */
+	forwardJoinMs?: number;
+}
+
+/** Claims by descending priority, keeping registration order among equals; refuses a repeated name. */
+export function orderClaims(
+	claims: readonly ChannelClaim[],
+): readonly ChannelClaim[] {
+	const names = new Set<string>();
+	for (const { name } of claims) {
+		if (names.has(name))
+			throw new PluginError(`channel claim ${name} is registered twice`);
+		names.add(name);
+	}
+	return claims.toSorted((a, b) => b.priority - a.priority);
+}
+
+/**
+ * Routes every conversation operation to the claim that owns its channel, each inside the
+ * channel's queue: messages after joining a bare forward to its text, background turns,
+ * starting over, and deleting.
+ */
+export class ChannelRouter implements ConversationPort {
+	readonly #options: ChannelRouterOptions;
+	readonly #claims: readonly ChannelClaim[];
+	readonly #forwards: ForwardJoin;
+
+	constructor(options: ChannelRouterOptions) {
+		this.#options = options;
+		this.#claims = orderClaims(options.claims);
+		this.#forwards = new ForwardJoin(options.forwardJoinMs);
+	}
+
+	#owner(channel: ChannelKey, guildId?: string): ChannelClaim | undefined {
+		return this.#claims.find((claim) => claim.owns(channel, guildId));
+	}
+
+	/**
+	 * Never rejects; every failure is logged. Resolves when the reply is posted or dropped. A
+	 * forward without text waits briefly for the text its author sent with it, and the two make
+	 * one turn.
+	 */
+	handle(message: InboundMessage): Promise<void> {
+		return this.#forwards.handle(message, (m) => this.#route(m));
+	}
+
+	async #route(message: InboundMessage): Promise<void> {
+		const { queue, logger } = this.#options;
+		if (
+			!message.text.trim() &&
+			message.attachments.length === 0 &&
+			!message.forwarded?.text.trim()
+		)
+			return;
+		const admission = this.#owner(message.channel, message.guildId)?.admit(
+			message,
+		);
+		if (!admission) return;
+		if (admission.kind === "background") {
+			const outcome = await this.background(admission.turn);
+			if (outcome.status !== "ran") admission.unanswered(outcome);
+			return;
+		}
+		const { busy } = admission;
+		let queued = false;
+		// A message during a turn is added to it when the turn takes it, otherwise marked as waiting.
+		if (busy && queue.size(message.channel) > 0) {
+			if (await busy.steer?.()) {
+				await busy.react(STEERED_MARK);
+				return;
+			}
+			await busy.react(QUEUED_MARK);
+			queued = true;
+		}
+		await queue
+			.run(message.channel, () => {
+				if (queued) void busy?.unreact(QUEUED_MARK);
+				return admission.run();
+			})
+			// pi-lens-ignore: no-unknown-parameters
+			.catch((error: unknown) =>
+				logger.error(
+					{ channel: message.channel, err: error },
+					admission.failure,
+				),
+			);
+	}
+
+	/** A turn nobody wrote, run by the channel's claim inside its queue; never rejects. */
+	async background(turn: BackgroundTurn): Promise<ScheduledOutcome> {
+		try {
+			return await this.#options.queue.run(turn.channel, async () => {
+				const claim = this.#owner(turn.channel);
+				if (!claim?.background)
+					return {
+						status: "skipped",
+						reason: "no conversation takes background turns here",
+					};
+				return claim.background(turn);
+			});
+		} catch (error) {
+			return { status: "failed", error: String(error) };
+		}
+	}
+
+	startFresh(channel: ChannelKey): Promise<string> {
+		return this.#options.queue.run(channel, () => {
+			const claim = this.#owner(channel);
+			if (!claim) throw new Error(`no conversation owns ${channel}`);
+			return claim.startFresh(channel);
+		});
+	}
+
+	async deleteConversation(channel: ChannelKey): Promise<"deleted" | "busy"> {
+		const { queue } = this.#options;
+		const claim = this.#owner(channel);
+		const remove = claim?.deleteConversation?.bind(claim);
+		if (!remove) throw new Error(`${channel} is not an owner conversation`);
+		if (queue.size(channel) > 0) return "busy";
+		return queue.run(channel, async () => {
+			// A message queued between the check and this task would still be waiting behind it.
+			if (queue.size(channel) > 1) return "busy";
+			await remove(channel);
+			return "deleted";
+		});
+	}
+
+	stop(channel: ChannelKey): boolean {
+		return this.#options.stop(channel);
+	}
+
+	postsInPlace(channel: ChannelKey): boolean {
+		return this.#owner(channel)?.postsInPlace === true;
+	}
+}

package/src/core/routing/conversation-kind.ts

@@ -0,0 +1,14 @@
+/** Whose conversation a channel holds, as starting it over reports it. */
+export type ConversationKind = "owner" | "party" | "agent";
+
+const isKind = (kind: string): kind is ConversationKind =>
+	kind === "owner" || kind === "party" || kind === "agent";
+
+/** Narrows what a claim's startFresh said; a claim the host does not know about is a bug. */
+export async function conversationKind(
+	whose: Promise<string>,
+): Promise<ConversationKind> {
+	const kind = await whose;
+	if (!isKind(kind)) throw new Error(`unknown conversation kind "${kind}"`);
+	return kind;
+}

package/src/core/routing/forward-join.ts

@@ -0,0 +1,65 @@
+import type { InboundMessage } from "../contract/channels.ts";
+import type { ChannelKey } from "../sessions.ts";
+
+/** Discord sends a forward's added text as a second message right after the forward. */
+export const FORWARD_JOIN_MS = 2_000;
+
+/** A forward without text, waiting for the message Discord sends with its added text. */
+interface HeldForward {
+	message: InboundMessage;
+	timer: ReturnType<typeof setTimeout>;
+	release(run: Promise<void>): void;
+}
+
+/**
+ * Joins a forward without text to the text its author sends right after it, so the two make
+ * one turn; a forward nothing follows runs alone once the wait ends.
+ */
+export class ForwardJoin {
+	readonly #waitMs: number;
+	readonly #held = new Map<ChannelKey, HeldForward>();
+
+	constructor(waitMs = FORWARD_JOIN_MS) {
+		this.#waitMs = waitMs;
+	}
+
+	/** Passes each message, or a joined one, to `dispatch`; resolves when its run does. */
+	handle(
+		message: InboundMessage,
+		dispatch: (message: InboundMessage) => Promise<void>,
+	): Promise<void> {
+		const held = this.#held.get(message.channel);
+		if (held && held.message.authorId === message.authorId) {
+			this.#held.delete(message.channel);
+			clearTimeout(held.timer);
+			if (!message.forwarded) {
+				const run = dispatch(joinForward(held.message, message));
+				held.release(run);
+				return run;
+			}
+			held.release(dispatch(held.message));
+		}
+		if (!message.forwarded || message.text.trim()) return dispatch(message);
+		return new Promise((resolve) => {
+			const release = (run: Promise<void>) => resolve(run);
+			const timer = setTimeout(() => {
+				this.#held.delete(message.channel);
+				release(dispatch(message));
+			}, this.#waitMs);
+			this.#held.set(message.channel, { message, timer, release });
+		});
+	}
+}
+
+/** A forward and the text its author sent right after it, as one message. */
+function joinForward(
+	forward: InboundMessage,
+	text: InboundMessage,
+): InboundMessage {
+	return {
+		...text,
+		mentionsBot: forward.mentionsBot || text.mentionsBot,
+		attachments: [...forward.attachments, ...text.attachments],
+		...(forward.forwarded ? { forwarded: forward.forwarded } : {}),
+	};
+}