pi-roundtable 0.1.0

package/src/core/discord/dispatch-threads.ts

@@ -0,0 +1,180 @@
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import type { ChannelKey } from "../domain/conversation.ts";
+import { messages } from "../i18n/index.ts";
+import type { Logger } from "../log.ts";
+
+const PREFIX = "discord:";
+/** Discord's limit on a thread name. */
+export const THREAD_NAME_LIMIT = 100;
+
+/** The chat side of dispatch threads; the Discord surface implements it. */
+export interface ThreadHost {
+	/**
+	 * Posts the start line in the parent and opens a public thread from it; `line` gets the
+	 * thread's mention once it exists. Undefined when the parent cannot host threads, such as a
+	 * DM or a thread; throws when Discord refuses.
+	 */
+	open(
+		parentId: string,
+		name: string,
+		line: (thread?: string) => string,
+	): Promise<string | undefined>;
+	post(threadId: string, text: string): Promise<void>;
+	/** Archives the thread, and locks it when allowed. */
+	close(threadId: string): Promise<void>;
+}
+
+/** One background dispatch's thread: its progress while it runs, then its report. */
+export interface DispatchThread {
+	readonly id: string;
+	/** The thread as a conversation channel, where its owner cards are posted. */
+	readonly channel: ChannelKey;
+	/** `<#id>`, for the report turn and the start line. */
+	readonly mention: string;
+	/** Posts in the thread; a failure is logged. */
+	post(text: string): Promise<void>;
+	/** Posts the final report, if any, then archives the thread. Runs once; never rejects. */
+	close(report?: string): Promise<void>;
+}
+
+export interface DispatchThreadsOptions {
+	host: ThreadHost;
+	/** Threads still open, so a start after a crash can archive them. */
+	ledgerPath: string;
+	/** Channels that keep posting in place, such as party channels. */
+	excluded?: (channel: ChannelKey) => boolean;
+	logger: Logger;
+}
+
+interface LedgerEntry {
+	title: string;
+	parent: ChannelKey;
+	startedAt: string;
+}
+
+/** The thread's name: the title on one line, within Discord's limit. */
+export function threadName(title: string): string {
+	const line = title.replace(/\s+/g, " ").trim() || "dispatch";
+	return line.length > THREAD_NAME_LIMIT
+		? `${line.slice(0, THREAD_NAME_LIMIT - 1)}…`
+		: line;
+}
+
+/**
+ * Background dispatches (coding tasks, delegated tasks, messages between agents) each get a
+ * thread in the channel that started them, leaving one start line there. A channel that cannot
+ * host one, or a failed creation, gets no thread, and the dispatch posts as before.
+ */
+export class DispatchThreads {
+	readonly #options: DispatchThreadsOptions;
+	readonly #open = new Map<string, LedgerEntry>();
+
+	constructor(options: DispatchThreadsOptions) {
+		this.#options = options;
+		const { ledgerPath } = options;
+		if (!existsSync(ledgerPath)) return;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(readFileSync(ledgerPath, "utf8"));
+		} catch (error) {
+			throw new Error(`${ledgerPath} is not valid JSON`, { cause: error });
+		}
+		if (typeof parsed !== "object" || parsed === null)
+			throw new Error(`${ledgerPath} must hold a JSON object`);
+		for (const [id, entry] of Object.entries(parsed))
+			this.#open.set(id, entry as LedgerEntry);
+	}
+
+	/** Opens the dispatch's thread under `origin`, posting `intro` first; never rejects. */
+	async open(
+		origin: ChannelKey | undefined,
+		title: string,
+		intro?: string,
+	): Promise<DispatchThread | undefined> {
+		const { host, excluded, logger } = this.#options;
+		if (!origin?.startsWith(PREFIX) || excluded?.(origin)) return undefined;
+		const name = threadName(title);
+		let id: string | undefined;
+		try {
+			id = await host.open(origin.slice(PREFIX.length), name, (thread) =>
+				messages().threadStarted(name, thread),
+			);
+		} catch (error) {
+			logger.warn({ origin, err: error }, "dispatch thread not opened");
+			return undefined;
+		}
+		if (!id) return undefined;
+		this.#open.set(id, {
+			title: name,
+			parent: origin,
+			startedAt: new Date().toISOString(),
+		});
+		this.#write();
+		logger.info({ origin, thread: id }, "dispatch thread opened");
+		const thread = this.#thread(id);
+		if (intro) await thread.post(intro);
+		return thread;
+	}
+
+	/** Archives the threads a restart left open; their dispatches never report. */
+	async sweep(): Promise<void> {
+		for (const id of [...this.#open.keys()])
+			await this.#thread(id).close(messages().restartNotice);
+	}
+
+	#thread(id: string): DispatchThread {
+		const { host, logger } = this.#options;
+		let closed = false;
+		const post = async (text: string) => {
+			try {
+				await host.post(id, text);
+			} catch (error) {
+				logger.warn({ thread: id, err: error }, "dispatch thread post failed");
+			}
+		};
+		return {
+			id,
+			channel: `${PREFIX}${id}`,
+			mention: `<#${id}>`,
+			post,
+			close: async (report) => {
+				if (closed) return;
+				closed = true;
+				if (report) await post(report);
+				try {
+					await host.close(id);
+				} catch (error) {
+					logger.warn(
+						{ thread: id, err: error },
+						"dispatch thread not archived",
+					);
+				}
+				this.#open.delete(id);
+				this.#write();
+			},
+		};
+	}
+
+	#write(): void {
+		const path = this.#options.ledgerPath;
+		try {
+			mkdirSync(dirname(path), { recursive: true });
+			const temporary = `${path}.tmp`;
+			writeFileSync(
+				temporary,
+				`${JSON.stringify(Object.fromEntries(this.#open), null, 2)}\n`,
+				{ mode: 0o600 },
+			);
+			renameSync(temporary, path);
+		} catch (error) {
+			this.#options.logger.warn({ err: error }, "dispatch threads not saved");
+		}
+	}
+}

package/src/core/discord/interaction-module.ts

@@ -0,0 +1 @@
+export type { InteractionModule } from "../contract/discord.ts";

package/src/core/discord/owner-cards.test.ts

@@ -0,0 +1,435 @@
+import { describe, expect, test } from "bun:test";
+import type { Interaction } from "discord.js";
+import type { OwnerQuestion } from "../domain/owner-prompts.ts";
+import { messages } from "../i18n/index.ts";
+import { silentLogger } from "../log.ts";
+import { speakerPolicy } from "../speakers.ts";
+import {
+	CARD_PREFIX,
+	type CardPayload,
+	OwnerCards,
+	type OwnerCardsOptions,
+} from "./owner-cards.ts";
+
+const OWNER = "100000000000000001";
+
+/** The card's JSON, where its text, custom ids, and disabled flags can be read. */
+const json = (payload: CardPayload | undefined) =>
+	JSON.stringify(payload?.components.map((c) => c.toJSON()));
+
+/** A channel, or a thread, that records the cards sent to it and every edit of them. */
+function fakeChannel(thread = false) {
+	const sent: CardPayload[] = [];
+	const edits: CardPayload[] = [];
+	return {
+		sent,
+		edits,
+		/** The id of the latest card sent. */
+		cardId: () =>
+			json(sent.at(-1)).match(new RegExp(`${CARD_PREFIX}([0-9a-f-]+):`))?.[1] ??
+			"",
+		channel: async () => ({
+			thread,
+			send: async (payload: CardPayload) => {
+				sent.push(payload);
+				return {
+					edit: async (change: CardPayload) => {
+						edits.push(change);
+					},
+				};
+			},
+		}),
+	};
+}
+
+type Kind = "button" | "select" | "modal";
+
+/** A press of a card's control, recording how it was answered. */
+function press(
+	kind: Kind,
+	customId: string,
+	options: {
+		user?: string;
+		roles?: string[];
+		values?: string[];
+		text?: string;
+	} = {},
+) {
+	const replies: string[] = [];
+	const updates: CardPayload[] = [];
+	const modals: unknown[] = [];
+	const interaction = {
+		isButton: () => kind === "button",
+		isStringSelectMenu: () => kind === "select",
+		isModalSubmit: () => kind === "modal",
+		isFromMessage: () => true,
+		customId,
+		user: { id: options.user ?? OWNER },
+		member: {
+			roles: { cache: new Map((options.roles ?? []).map((r) => [r, r])) },
+		},
+		values: options.values ?? [],
+		fields: { getTextInputValue: () => options.text ?? "" },
+		reply: async (answer: { content: string }) => {
+			replies.push(answer.content);
+		},
+		update: async (payload: CardPayload) => {
+			updates.push(payload);
+		},
+		showModal: async (modal: unknown) => {
+			modals.push(modal);
+		},
+		deferUpdate: async () => undefined,
+	} as unknown as Interaction;
+	return { interaction, replies, updates, modals };
+}
+
+function setup(options: Partial<OwnerCardsOptions> = {}) {
+	const fake = fakeChannel();
+	const cards = new OwnerCards({
+		ownerId: OWNER,
+		channel: fake.channel,
+		logger: silentLogger(),
+		...options,
+	});
+	const prompts = cards.prompts("discord:555");
+	if (!prompts) throw new Error("no prompts for a Discord channel");
+	return { fake, cards, prompts };
+}
+
+const tick = () => Bun.sleep(1);
+
+describe("OwnerCards", () => {
+	test("a conversation outside Discord has no cards", () => {
+		const { cards } = setup();
+		expect(cards.prompts("mcp:agent")).toBeUndefined();
+	});
+
+	test("a dispatch thread's cards are posted in the thread", async () => {
+		const asked: string[] = [];
+		const fake = fakeChannel();
+		const cards = new OwnerCards({
+			ownerId: OWNER,
+			channel: async (channelId) => {
+				asked.push(channelId);
+				return fake.channel();
+			},
+			logger: silentLogger(),
+			timeoutMs: 5,
+		});
+		await cards.prompts("discord:900")?.confirm("t", "m");
+		expect(asked).toEqual(["900"]);
+		expect(fake.sent).toHaveLength(1);
+	});
+
+	test("the owner approves; the card then shows the outcome with its buttons disabled", async () => {
+		const { fake, cards, prompts } = setup();
+		const answer = prompts.confirm(
+			"The assistant wants to run this action",
+			"**send mail**",
+		);
+		await tick();
+		expect(json(fake.sent[0])).toContain("send mail");
+		expect(json(fake.sent[0])).toContain(messages().cardRunLabel);
+		const yes = press("button", `${CARD_PREFIX}${fake.cardId()}:yes`);
+		expect(await cards.handle(yes.interaction)).toBe(true);
+		expect(await answer).toBe("approved");
+		expect(json(yes.updates[0])).toContain(messages().cardApproved);
+		expect(json(yes.updates[0])).toContain('"disabled":true');
+	});
+
+	test("a card in a channel mentions nobody", async () => {
+		const { fake, prompts } = setup({ timeoutMs: 5 });
+		await prompts.confirm(
+			"The assistant wants to run this action",
+			"**send mail**",
+		);
+		expect(fake.sent[0]?.allowedMentions).toEqual({ parse: [] });
+		expect(json(fake.sent[0])).not.toContain(`<@${OWNER}>`);
+	});
+
+	test("a card in a thread mentions the owner alone, above the unchanged card", async () => {
+		const inChannel = fakeChannel();
+		const inThread = fakeChannel(true);
+		const cards = (fake: ReturnType<typeof fakeChannel>) =>
+			new OwnerCards({
+				ownerId: OWNER,
+				channel: fake.channel,
+				logger: silentLogger(),
+			});
+		const threadCards = cards(inThread);
+		void cards(inChannel).prompts("discord:555")?.confirm("t", "**m**");
+		const answer = threadCards.prompts("discord:900")?.confirm("t", "**m**");
+		await tick();
+		const card = inThread.sent[0];
+		expect(card?.allowedMentions).toEqual({ users: [OWNER] });
+		const [mention, ...panel] = card?.components ?? [];
+		expect(mention?.toJSON()).toMatchObject({ content: `<@${OWNER}>` });
+		// Past the mention the card is the one a channel gets.
+		expect(JSON.stringify(panel.map((c) => c.toJSON()))).toBe(
+			json(inChannel.sent[0]).replaceAll(inChannel.cardId(), inThread.cardId()),
+		);
+		const yes = press("button", `${CARD_PREFIX}${inThread.cardId()}:yes`);
+		await threadCards.handle(yes.interaction);
+		expect(await answer).toBe("approved");
+		// The closed card keeps its mention line.
+		expect(json(yes.updates[0])).toContain(`<@${OWNER}>`);
+	});
+
+	test("only the owner may answer; anyone else is refused and the card stays open", async () => {
+		const { fake, cards, prompts } = setup();
+		const answer = prompts.confirm("t", "m");
+		await tick();
+		const id = fake.cardId();
+		const stranger = press("button", `${CARD_PREFIX}${id}:yes`, { user: "1" });
+		await cards.handle(stranger.interaction);
+		expect(stranger.replies).toEqual([messages().cardOwnerOnly]);
+		expect(stranger.updates).toHaveLength(0);
+		const no = press("button", `${CARD_PREFIX}${id}:no`);
+		await cards.handle(no.interaction);
+		expect(await answer).toBe("declined");
+		expect(json(no.updates[0])).toContain(messages().cardDeclined);
+	});
+
+	test("an unanswered card expires and is edited to say so", async () => {
+		const { fake, cards, prompts } = setup({ timeoutMs: 5 });
+		expect(await prompts.confirm("t", "m")).toBe("expired");
+		await tick();
+		expect(json(fake.edits[0])).toContain(messages().cardExpired);
+		expect(json(fake.edits[0])).toContain('"disabled":true');
+		// A late press finds the card gone.
+		const late = press("button", `${CARD_PREFIX}${fake.cardId()}:yes`);
+		await cards.handle(late.interaction);
+		expect(late.replies[0]).toContain(messages().cardInactive);
+	});
+
+	test("a stopped turn cancels its card", async () => {
+		const { fake, prompts } = setup();
+		const stop = new AbortController();
+		const answer = prompts.confirm("t", "m", stop.signal);
+		await tick();
+		stop.abort();
+		expect(await answer).toBe("cancelled");
+		await tick();
+		expect(json(fake.edits[0])).toContain(messages().cardStopped);
+	});
+
+	test("a card that cannot be posted counts as expired", async () => {
+		const { prompts } = setup({
+			channel: async () => {
+				throw new Error("missing access");
+			},
+		});
+		expect(await prompts.confirm("t", "m")).toBe("expired");
+	});
+
+	test("a press of a card from before a restart says it no longer works", async () => {
+		const { cards } = setup();
+		const old = press("button", `${CARD_PREFIX}gone:yes`);
+		expect(await cards.handle(old.interaction)).toBe(true);
+		expect(old.replies[0]).toContain(messages().cardInactive);
+	});
+
+	test("other components are left to other modules", async () => {
+		const { cards } = setup();
+		expect(
+			await cards.handle(press("button", "roundtable:stop").interaction),
+		).toBe(false);
+	});
+
+	describe("questions", () => {
+		const question = (q: Partial<OwnerQuestion>): OwnerQuestion => ({
+			question: "Which day?",
+			options: [
+				{ label: "Saturday", description: "morning" },
+				{ label: "Sunday" },
+				{ label: "Monday" },
+			],
+			multi: false,
+			allowOther: false,
+			...q,
+		});
+
+		test("a single choice", async () => {
+			const { fake, cards, prompts } = setup();
+			const answer = prompts.ask(
+				"The assistant has a question for you",
+				question({}),
+			);
+			await tick();
+			const card = json(fake.sent[0]);
+			expect(card).toContain("Which day?");
+			expect(card).toContain('"max_values":1');
+			expect(card).not.toContain(messages().cardOtherLabel);
+			const pick = press("select", `${CARD_PREFIX}${fake.cardId()}:pick`, {
+				values: ["1"],
+			});
+			await cards.handle(pick.interaction);
+			expect(await answer).toEqual({ choices: ["Sunday"] });
+			expect(json(pick.updates[0])).toContain(
+				messages().cardAnswered(["Sunday"]),
+			);
+		});
+
+		test("several choices, in the order they were offered", async () => {
+			const { fake, cards, prompts } = setup();
+			const answer = prompts.ask("t", question({ multi: true }));
+			await tick();
+			expect(json(fake.sent[0])).toContain('"max_values":3');
+			await cards.handle(
+				press("select", `${CARD_PREFIX}${fake.cardId()}:pick`, {
+					values: ["2", "0"],
+				}).interaction,
+			);
+			expect(await answer).toEqual({ choices: ["Saturday", "Monday"] });
+		});
+
+		test("the other option opens a form, and its text comes back with the other choices", async () => {
+			const { fake, cards, prompts } = setup();
+			const answer = prompts.ask(
+				"t",
+				question({ multi: true, allowOther: true }),
+			);
+			await tick();
+			const id = fake.cardId();
+			expect(json(fake.sent[0])).toContain(messages().cardOtherLabel);
+			const pick = press("select", `${CARD_PREFIX}${id}:pick`, {
+				values: ["0", "other"],
+			});
+			await cards.handle(pick.interaction);
+			expect(pick.modals).toHaveLength(1);
+			expect(pick.updates).toHaveLength(0);
+			const submit = press("modal", `${CARD_PREFIX}${id}:text`, {
+				text: "Wednesday evening",
+			});
+			await cards.handle(submit.interaction);
+			expect(await answer).toEqual({
+				choices: ["Saturday"],
+				text: "Wednesday evening",
+			});
+			expect(json(submit.updates[0])).toContain("Wednesday evening");
+		});
+
+		test("without options, a button opens the answer form", async () => {
+			const { fake, cards, prompts } = setup();
+			const answer = prompts.ask("t", question({ options: [] }));
+			await tick();
+			const id = fake.cardId();
+			const write = press("button", `${CARD_PREFIX}${id}:write`);
+			await cards.handle(write.interaction);
+			expect(write.modals).toHaveLength(1);
+			await cards.handle(
+				press("modal", `${CARD_PREFIX}${id}:text`, { text: "anything" })
+					.interaction,
+			);
+			expect(await answer).toEqual({ choices: [], text: "anything" });
+		});
+
+		test("an unanswered question has no answer", async () => {
+			const { prompts } = setup({ timeoutMs: 5 });
+			expect(await prompts.ask("t", question({}))).toBeUndefined();
+		});
+	});
+});
+
+describe("cards for lower tiers", () => {
+	const ADMIN = "100000000000000002";
+	const MEMBER = "100000000000000003";
+	const ROLE = "100000000000000004";
+	const speakers = speakerPolicy({
+		owners: [OWNER],
+		admins: { users: [ADMIN] },
+		members: { roles: [ROLE] },
+	});
+	const askAdminApproval = () => {
+		const fake = fakeChannel();
+		const cards = new OwnerCards({
+			ownerId: OWNER,
+			speakers,
+			channel: fake.channel,
+			logger: silentLogger(),
+		});
+		const speaker = { id: ADMIN, name: "Ada", tier: "admin" } as const;
+		const answer = cards
+			.prompts("discord:555", speaker)
+			?.confirm("t", "**create an agent**", undefined, "admin");
+		return { fake, cards, answer };
+	};
+
+	test("an approval for admin tools shows who may approve and takes an admin's press", async () => {
+		const { fake, cards, answer } = askAdminApproval();
+		await tick();
+		expect(json(fake.sent[0])).toContain(messages().cardApproversNote("admin"));
+		const admin = press("button", `${CARD_PREFIX}${fake.cardId()}:yes`, {
+			user: ADMIN,
+		});
+		await cards.handle(admin.interaction);
+		expect(await answer).toBe("approved");
+		expect(admin.replies).toEqual([]);
+	});
+
+	test("the owner may approve it too, but a member may not", async () => {
+		const { fake, cards, answer } = askAdminApproval();
+		await tick();
+		const member = press("button", `${CARD_PREFIX}${fake.cardId()}:yes`, {
+			user: MEMBER,
+			roles: [ROLE],
+		});
+		await cards.handle(member.interaction);
+		expect(member.replies).toEqual([messages().cardApproversRefusal("admin")]);
+		const owner = press("button", `${CARD_PREFIX}${fake.cardId()}:no`, {
+			user: OWNER,
+		});
+		await cards.handle(owner.interaction);
+		expect(await answer).toBe("declined");
+	});
+
+	test("a shell approval stays the owner's even when the speaker is an admin", async () => {
+		const fake = fakeChannel();
+		const cards = new OwnerCards({
+			ownerId: OWNER,
+			speakers,
+			channel: fake.channel,
+			logger: silentLogger(),
+		});
+		const speaker = { id: ADMIN, name: "Ada", tier: "admin" } as const;
+		void cards.prompts("discord:555", speaker)?.confirm("t", "**rm**");
+		await tick();
+		const admin = press("button", `${CARD_PREFIX}${fake.cardId()}:yes`, {
+			user: ADMIN,
+		});
+		await cards.handle(admin.interaction);
+		expect(admin.replies).toEqual([messages().cardOwnerOnly]);
+	});
+
+	test("a question is for the speaker who is asked, and the owner", async () => {
+		const fake = fakeChannel();
+		const cards = new OwnerCards({
+			ownerId: OWNER,
+			speakers,
+			channel: fake.channel,
+			logger: silentLogger(),
+		});
+		const speaker = { id: ADMIN, name: "Ada", tier: "admin" } as const;
+		const question = {
+			question: "Which one?",
+			options: [{ label: "First" }, { label: "Second" }],
+			multi: false,
+			allowOther: false,
+		};
+		const answer = cards.prompts("discord:555", speaker)?.ask("t", question);
+		await tick();
+		const stranger = press("select", `${CARD_PREFIX}${fake.cardId()}:pick`, {
+			user: MEMBER,
+			values: ["0"],
+		});
+		await cards.handle(stranger.interaction);
+		expect(stranger.replies).toEqual([messages().cardAskerRefusal]);
+		const asked = press("select", `${CARD_PREFIX}${fake.cardId()}:pick`, {
+			user: ADMIN,
+			values: ["1"],
+		});
+		await cards.handle(asked.interaction);
+		expect(await answer).toEqual({ choices: ["Second"] });
+	});
+});