pi-roundtable 0.1.0

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

@@ -0,0 +1,282 @@
+import {
+	ChannelType,
+	type Client,
+	type Guild,
+	PermissionFlagsBits,
+} from "discord.js";
+import { messages } from "../i18n/index.ts";
+import type { OwnerDiscord } from "../modules/discord-admin/discord-admin.ts";
+import {
+	discordChannelExecutor,
+	fetchOwnerChannel,
+	operationPermissions,
+} from "./channel-executor.ts";
+import { CHANNEL_TOOLS, parseChannelTool } from "./channel-operations.ts";
+import {
+	CHANNEL_TYPES,
+	OwnerAccess,
+	permissionFlags,
+	permissionNames,
+	refuse,
+	roleOptions,
+	SERVER_PERMISSIONS,
+} from "./owner-discord-access.ts";
+import { OwnerThreads } from "./owner-discord-threads.ts";
+
+export { outranksMember, outranksRole } from "./owner-discord-access.ts";
+
+/**
+ * Discord operations for the owner's agent over the bot's connection. Every call is bounded
+ * by what both the owner and the bot may do where it acts, read fresh from Discord.
+ */
+export class DiscordOwnerOps implements OwnerDiscord {
+	readonly #client: Client;
+	readonly #ownerId: string;
+	/** The audit-log reason of an action taken without one of its own. */
+	readonly #reason: string;
+	readonly #access: OwnerAccess;
+	readonly #threadOps: OwnerThreads;
+
+	constructor(client: Client, ownerId: string, ownerName = "the owner") {
+		this.#client = client;
+		this.#ownerId = ownerId;
+		this.#reason = messages().auditRequested(ownerName);
+		this.#access = new OwnerAccess(ownerId, ownerName);
+		this.#threadOps = new OwnerThreads(
+			client,
+			this.#access,
+			ownerId,
+			this.#reason,
+		);
+	}
+
+	async run(tool: string, args: Record<string, unknown>): Promise<unknown> {
+		if (!this.#client.isReady())
+			throw refuse("DISCORD_NOT_READY", "try again shortly");
+		const channelTool = CHANNEL_TOOLS[tool];
+		if (channelTool) {
+			const parsed = parseChannelTool(tool, args);
+			const channel = await fetchOwnerChannel(
+				this.#client,
+				String(parsed.channelId),
+			);
+			await this.#access.members(
+				channel.guild,
+				operationPermissions(channelTool.operation, channel),
+				channel,
+			);
+			return discordChannelExecutor(this.#client, { threads: true }).execute(
+				tool,
+				parsed,
+			);
+		}
+		if (tool === "discord_list_servers") return this.#servers();
+		if (tool === "discord_delete_channel") return this.#deleteChannel(args);
+		if (tool === "discord_create_thread") return this.#threadOps.create(args);
+		if (tool === "discord_edit_thread") return this.#threadOps.edit(args);
+		const needed = SERVER_PERMISSIONS[tool];
+		if (!needed) throw refuse("INVALID_TOOL", tool);
+		const guild = await this.#client.guilds
+			.fetch(String(args.guildId))
+			.catch(() => {
+				throw refuse("UNKNOWN_SERVER", messages().refuseNotInServer);
+			});
+		return this.#serverTool(tool, guild, needed, args);
+	}
+
+	async #serverTool(
+		tool: string,
+		guild: Guild,
+		needed: bigint[],
+		args: Record<string, unknown>,
+	): Promise<unknown> {
+		const reason = typeof args.reason === "string" ? args.reason : this.#reason;
+		if (tool === "discord_create_channel") {
+			const parent = args.parentId
+				? await this.#access.category(guild, String(args.parentId))
+				: undefined;
+			await this.#access.members(guild, needed, parent);
+			const created = await guild.channels.create({
+				name: String(args.name),
+				type: CHANNEL_TYPES[args.type as keyof typeof CHANNEL_TYPES],
+				...(parent ? { parent } : {}),
+				...(typeof args.topic === "string" ? { topic: args.topic } : {}),
+				reason,
+			});
+			return { id: created.id, name: created.name, parentId: created.parentId };
+		}
+
+		const { owner, bot } = await this.#access.members(guild, needed);
+		switch (tool) {
+			case "discord_list_channels": {
+				const channels = await guild.channels.fetch();
+				return [...channels.values()]
+					.filter((c) => c !== null)
+					.filter(
+						(c) =>
+							c.permissionsFor(owner).has(PermissionFlagsBits.ViewChannel) &&
+							c.permissionsFor(bot).has(PermissionFlagsBits.ViewChannel),
+					)
+					.sort((a, b) => a.rawPosition - b.rawPosition)
+					.map((c) => ({
+						id: c.id,
+						name: c.name,
+						type: ChannelType[c.type],
+						parentId: c.parentId,
+						...("topic" in c && c.topic ? { topic: c.topic } : {}),
+					}));
+			}
+			case "discord_list_threads":
+				return this.#threadOps.list(guild, owner, bot, args);
+			case "discord_list_roles": {
+				const roles = await guild.roles.fetch();
+				return [...roles.values()]
+					.sort((a, b) => b.comparePositionTo(a))
+					.map((role) => ({
+						id: role.id,
+						name: role.name,
+						color: role.hexColor,
+						managed: role.managed,
+						hoist: role.hoist,
+						mentionable: role.mentionable,
+						permissions: role.permissions.toArray(),
+					}));
+			}
+			case "discord_find_members": {
+				const found = await guild.members.search({
+					query: String(args.query),
+					limit: typeof args.limit === "number" ? args.limit : 10,
+				});
+				return [...found.values()].map((m) => ({
+					id: m.id,
+					username: m.user.username,
+					displayName: m.displayName,
+					nickname: m.nickname,
+					bot: m.user.bot,
+					roles: m.roles.cache
+						.filter((r) => r.id !== guild.id)
+						.map((r) => r.name),
+				}));
+			}
+			case "discord_create_role": {
+				const permissions = permissionFlags(args.permissions);
+				this.#access.holdsAll(owner, permissions);
+				const role = await guild.roles.create({
+					...roleOptions(args, permissions),
+					reason,
+				});
+				return { id: role.id, name: role.name };
+			}
+			case "discord_edit_role": {
+				const role = await this.#access.role(guild, owner, args.roleId);
+				const permissions =
+					args.permissions === undefined
+						? undefined
+						: permissionFlags(args.permissions);
+				if (permissions) this.#access.holdsAll(owner, permissions);
+				await role.edit({ ...roleOptions(args, permissions), reason });
+				return { id: role.id, name: role.name };
+			}
+			case "discord_delete_role": {
+				const role = await this.#access.role(guild, owner, args.roleId);
+				await role.delete(reason);
+				return { id: role.id, deleted: true };
+			}
+			case "discord_add_member_role":
+			case "discord_remove_member_role": {
+				const role = await this.#access.role(guild, owner, args.roleId);
+				const member = await this.#access.member(guild, args.userId);
+				if (tool === "discord_add_member_role")
+					await member.roles.add(role, reason);
+				else await member.roles.remove(role, reason);
+				return { userId: member.id, roleId: role.id };
+			}
+			case "discord_set_nickname": {
+				const member = await this.#access.member(guild, args.userId);
+				// The assistant's own nickname is the owner's to set wherever the owner may manage nicknames.
+				if (member.id !== bot.id) this.#access.outranks(owner, member);
+				const nickname = String(args.nickname).trim();
+				await member.setNickname(nickname || null, reason);
+				return { userId: member.id, nickname: nickname || null };
+			}
+			case "discord_timeout_member": {
+				const member = await this.#access.member(guild, args.userId);
+				this.#access.outranks(owner, member);
+				const minutes = Number(args.minutes);
+				await member.timeout(minutes > 0 ? minutes * 60_000 : null, reason);
+				return { userId: member.id, minutes };
+			}
+			case "discord_kick_member": {
+				const member = await this.#access.member(guild, args.userId);
+				this.#access.outranks(owner, member);
+				await member.kick(reason);
+				return { userId: member.id, kicked: true };
+			}
+			case "discord_ban_member": {
+				const userId = String(args.userId);
+				// A user who already left can still be banned by id.
+				const member = await guild.members
+					.fetch({ user: userId, force: true })
+					.catch(() => undefined);
+				if (member) this.#access.outranks(owner, member);
+				await guild.members.ban(userId, {
+					deleteMessageSeconds:
+						typeof args.deleteMessageSeconds === "number"
+							? args.deleteMessageSeconds
+							: 0,
+					reason,
+				});
+				return { userId, banned: true };
+			}
+			case "discord_unban_member": {
+				const userId = String(args.userId);
+				await guild.members.unban(userId, reason);
+				return { userId, banned: false };
+			}
+		}
+		throw refuse("INVALID_TOOL", tool);
+	}
+
+	/** Servers the owner and the assistant share, with what each of them may do there. */
+	async #servers() {
+		const servers = [];
+		for (const guild of this.#client.guilds.cache.values()) {
+			const owner = await guild.members
+				.fetch({ user: this.#ownerId })
+				.catch(() => undefined);
+			if (!owner) continue;
+			const bot = await guild.members.fetchMe();
+			servers.push({
+				id: guild.id,
+				name: guild.name,
+				memberCount: guild.memberCount,
+				ownerOwnsServer: guild.ownerId === this.#ownerId,
+				assistantPermissions: permissionNames(bot),
+				ownerPermissions: permissionNames(owner),
+			});
+		}
+		return servers;
+	}
+
+	async #deleteChannel(args: Record<string, unknown>) {
+		const channel = await this.#client.channels
+			.fetch(String(args.channelId), { force: true })
+			.catch(() => null);
+		if (!channel || channel.isDMBased())
+			throw refuse("INVALID_CHANNEL", messages().refuseNotVisible);
+		await this.#access.members(
+			channel.guild,
+			[
+				PermissionFlagsBits.ViewChannel,
+				channel.isThread()
+					? PermissionFlagsBits.ManageThreads
+					: PermissionFlagsBits.ManageChannels,
+			],
+			channel,
+		);
+		await channel.delete(
+			typeof args.reason === "string" ? args.reason : this.#reason,
+		);
+		return { id: channel.id, deleted: true };
+	}
+}

package/src/core/discord/owner-panel.ts

@@ -0,0 +1,103 @@
+import {
+	type ActionRowBuilder,
+	type ButtonBuilder,
+	type ChatInputCommandInteraction,
+	ContainerBuilder,
+	MessageFlags,
+	SeparatorBuilder,
+	SeparatorSpacingSize,
+	type StringSelectMenuBuilder,
+	TextDisplayBuilder,
+} from "discord.js";
+import { messages } from "../i18n/index.ts";
+
+export interface PanelContent {
+	title: string;
+	/** Markdown sections, each its own text block. */
+	sections: string[];
+	/** One quiet line under the content, such as what to do next. */
+	footer?: string;
+	rows?: ActionRowBuilder<ButtonBuilder | StringSelectMenuBuilder>[];
+}
+
+/** A message the owner should read as is; anything else becomes a generic failure. */
+export class OwnerFacingError extends Error {}
+
+/** Discord allows 4,000 characters of text per Components V2 message; keep a margin. */
+const PANEL_TEXT_LIMIT = 3_600;
+
+/**
+ * The single look of every root-command answer: a Components V2 container with no accent color
+ * (Discord draws accents as a bar on one side), a heading, sections, controls, and a footer.
+ */
+export function ownerPanel(content: PanelContent) {
+	const container = new ContainerBuilder().addTextDisplayComponents(
+		new TextDisplayBuilder().setContent(`### ${content.title}`),
+	);
+	for (const section of content.sections)
+		container.addTextDisplayComponents(
+			new TextDisplayBuilder().setContent(section),
+		);
+	if (content.rows?.length)
+		container
+			.addSeparatorComponents(
+				new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small),
+			)
+			.addActionRowComponents(...content.rows);
+	if (content.footer)
+		container.addTextDisplayComponents(
+			new TextDisplayBuilder().setContent(`-# ${content.footer}`),
+		);
+	return {
+		components: [container],
+		flags: MessageFlags.IsComponentsV2 as const,
+		allowedMentions: { parse: [] },
+	};
+}
+
+/** A panel only the person who used the command sees. */
+export function ephemeralPanel(content: PanelContent) {
+	return {
+		...ownerPanel(content),
+		flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral,
+	};
+}
+
+/** Answers a deferred command with the panel, its overflow pages as ephemeral follow-ups. */
+export async function replyWithPanels(
+	interaction: ChatInputCommandInteraction,
+	content: PanelContent,
+): Promise<void> {
+	const [first, ...rest] = ownerPanels(content);
+	if (first) await interaction.editReply(ownerPanel(first));
+	for (const page of rest) await interaction.followUp(ephemeralPanel(page));
+}
+
+/** Splits long sections into panels that each fit Discord's text limit. */
+export function ownerPanels(content: PanelContent): PanelContent[] {
+	const pages: PanelContent[] = [];
+	let sections: string[] = [];
+	let size = content.title.length;
+	for (const section of content.sections) {
+		if (sections.length > 0 && size + section.length > PANEL_TEXT_LIMIT) {
+			pages.push({ title: content.title, sections });
+			sections = [];
+			size = content.title.length;
+		}
+		sections.push(section.slice(0, PANEL_TEXT_LIMIT));
+		size += section.length;
+	}
+	pages.push({ ...content, sections });
+	return pages.map((page, i) =>
+		pages.length > 1
+			? {
+					...page,
+					title: messages().panelPage(page.title, i + 1, pages.length),
+				}
+			: page,
+	);
+}
+
+/** Text a user typed, made safe to put inside Discord markdown. */
+export const plain = (value: string): string =>
+	value.replace(/[\n\r`*_~<>|#@]/g, " ").trim();

package/src/core/discord/schedule-commands.ts

@@ -0,0 +1,149 @@
+import type {
+	AutocompleteInteraction,
+	ChatInputCommandInteraction,
+	SlashCommandSubcommandGroupBuilder,
+} from "discord.js";
+import type { InteractionContribution } from "../contract/discord.ts";
+import { messages } from "../i18n/index.ts";
+import { describeRecurrence } from "../modules/schedules/recurrence.ts";
+import type {
+	Schedule,
+	ScheduleStore,
+} from "../modules/schedules/schedule-store.ts";
+import {
+	groupOption,
+	type OwnerGuard,
+	ownerCommandModule,
+} from "./owner-command.ts";
+import {
+	OwnerFacingError,
+	ownerPanel,
+	plain,
+	replyWithPanels,
+} from "./owner-panel.ts";
+
+const PROMPT_PREVIEW = 160;
+
+function scheduleGroup(group: SlashCommandSubcommandGroupBuilder) {
+	return group
+		.setName("schedule")
+		.setDescription(messages().scheduleGroupDescription)
+		.addSubcommand((sub) =>
+			sub.setName("list").setDescription(messages().scheduleListDescription),
+		)
+		.addSubcommand((sub) =>
+			sub
+				.setName("cancel")
+				.setDescription(messages().scheduleCancelDescription)
+				.addStringOption((option) =>
+					option
+						.setName("id")
+						.setDescription(messages().scheduleIdDescription)
+						.setRequired(true)
+						.setAutocomplete(true),
+				),
+		);
+}
+
+function channelMention(schedule: Schedule): string {
+	const [surface, id] = schedule.channel.split(":");
+	return surface === "discord" && id ? `<#${id}>` : plain(schedule.channel);
+}
+
+const unix = (at: Date) => Math.floor(at.getTime() / 1000);
+
+function section(schedule: Schedule): string {
+	const prompt =
+		schedule.prompt.length > PROMPT_PREVIEW
+			? `${schedule.prompt.slice(0, PROMPT_PREVIEW)}…`
+			: schedule.prompt;
+	const text = messages();
+	const last = schedule.lastRun
+		? text.scheduleLastRun(
+				unix(schedule.lastRun),
+				plain(schedule.lastStatus ?? "?"),
+			)
+		: "";
+	const mode =
+		schedule.mode === "owner" ? text.scheduleModeOwner : text.scheduleModeParty;
+	return [
+		text.scheduleHead(
+			schedule.id,
+			plain(schedule.title),
+			channelMention(schedule),
+			mode,
+		),
+		text.scheduleNextRun(
+			describeRecurrence(schedule.recurrence),
+			unix(schedule.nextRun),
+		),
+		text.scheduleSetBy(plain(schedule.createdByName), last),
+		`-# ${plain(prompt)}`,
+	].join("\n");
+}
+
+/** `/<root> schedule`: the owner's view over every channel's schedules. */
+export class ScheduleCommands {
+	readonly #store: ScheduleStore;
+
+	constructor(store: ScheduleStore) {
+		this.#store = store;
+	}
+
+	async autocomplete(interaction: AutocompleteInteraction): Promise<void> {
+		const query = interaction.options.getFocused().trim().toLocaleLowerCase();
+		const choices = (await this.#store.all())
+			.map((s) => ({
+				name: messages()
+					.scheduleChoice(s.id, s.title, describeRecurrence(s.recurrence))
+					.slice(0, 100),
+				value: String(s.id),
+			}))
+			.filter((choice) => choice.name.toLocaleLowerCase().includes(query));
+		await interaction.respond(choices.slice(0, 25));
+	}
+
+	/** The interaction is deferred and ephemeral. */
+	async command(interaction: ChatInputCommandInteraction): Promise<void> {
+		if (interaction.options.getSubcommand(true) === "cancel")
+			return this.#cancel(interaction);
+		const all = await this.#store.all();
+		await replyWithPanels(interaction, {
+			title: messages().scheduleTitle,
+			sections: all.length ? all.map(section) : [messages().scheduleNone],
+			footer: messages().scheduleFooter,
+		});
+	}
+
+	async #cancel(interaction: ChatInputCommandInteraction): Promise<void> {
+		const raw = interaction.options.getString("id", true).replace(/^#/, "");
+		const id = Number(raw);
+		if (!Number.isInteger(id))
+			throw new OwnerFacingError(messages().schedulePickOne);
+		const removed = await this.#store.remove(id);
+		if (!removed)
+			throw new OwnerFacingError(messages().scheduleUnknown(plain(raw)));
+		await interaction.editReply(
+			ownerPanel({
+				title: messages().scheduleCancelled,
+				sections: [section(removed)],
+			}),
+		);
+	}
+}
+
+/** `/<root> schedule list|cancel`. */
+export function scheduleCommands(
+	guard: OwnerGuard,
+	store: ScheduleStore,
+): InteractionContribution {
+	const commands = new ScheduleCommands(store);
+	return {
+		module: ownerCommandModule(guard, {
+			owns: (group) => group === "schedule",
+			autocomplete: (interaction) => commands.autocomplete(interaction),
+			command: (interaction) => commands.command(interaction),
+		}),
+		rootOptions: [groupOption(scheduleGroup)],
+	};
+}

package/src/core/discord/stop-button.ts

@@ -0,0 +1,20 @@
+import { ActionRowBuilder, ButtonBuilder, ButtonStyle } from "discord.js";
+import { messages } from "../i18n/index.ts";
+
+export const STOP_BUTTON_ID = "roundtable:stop";
+
+/** The message a long turn shows: a stop button only the owner may press. */
+export function stopPanel() {
+	return {
+		content: messages().stopNote,
+		components: [
+			new ActionRowBuilder<ButtonBuilder>().addComponents(
+				new ButtonBuilder()
+					.setCustomId(STOP_BUTTON_ID)
+					.setLabel(messages().stopLabel)
+					.setEmoji("⏹️")
+					.setStyle(ButtonStyle.Danger),
+			),
+		],
+	};
+}

package/src/core/domain/attachment.ts

@@ -0,0 +1,39 @@
+export type { AttachmentRef } from "../contract/channels.ts";
+
+/** An attachment saved in the channel's attachment store. */
+export interface StoredAttachment {
+	name: string;
+	/** File name inside the channel's attachment store. */
+	file: string;
+	/** Absolute path on the host. */
+	path: string;
+	contentType: string;
+	size: number;
+	/** True for files from the message this one replies to. */
+	fromReference: boolean;
+}
+
+export interface AttachmentFailure {
+	name: string;
+	reason: string;
+	fromReference: boolean;
+}
+
+/** An image in the form the model accepts. */
+export interface ModelImage {
+	data: string;
+	mimeType: string;
+}
+
+/** Everything a turn carries besides its text. */
+export interface TurnAttachments {
+	files: StoredAttachment[];
+	images: ModelImage[];
+	failures: AttachmentFailure[];
+}
+
+export const NO_ATTACHMENTS: TurnAttachments = Object.freeze({
+	files: [],
+	images: [],
+	failures: [],
+}) as TurnAttachments;

package/src/core/domain/conversation.ts

@@ -0,0 +1,42 @@
+import type { InboundMessage } from "../contract/channels.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type { AgentRunError } from "./errors.ts";
+import type { ProfileId } from "./profile.ts";
+
+export { QUEUED_MARK, STEERED_MARK } from "../contract/channels.ts";
+export type { ChannelKey, InboundMessage };
+
+export interface TranscriptEntry {
+	role: "user" | "assistant";
+	text: string;
+}
+
+/** One tool call held for the owner's confirmation, exactly as the model made it. */
+export interface HeldCall {
+	tool: string;
+	/** The call's input as canonical JSON; only an identical call is released. */
+	input: string;
+	/** What the call would do, in plain words. */
+	action: string;
+}
+
+export interface PendingConfirmation {
+	profile: ProfileId;
+	heldAt: Date;
+	calls: HeldCall[];
+}
+
+export type TurnResult =
+	| { ok: true; text: string; thinking?: string }
+	| { ok: false; error: AgentRunError; stopped?: true };
+
+export interface OutboundReply {
+	/** The assistant's thinking for this turn, posted as a quiet line before the card. */
+	thinking?: string;
+	/** PNG card, absent when rendering failed or the channel shows none. */
+	card?: Uint8Array;
+	/** Message texts in posting order; the card is posted before them. */
+	chunks: string[];
+	/** Files the run produced, posted after the text. */
+	files?: { name: string; data: Uint8Array }[];
+}

package/src/core/domain/errors.ts

@@ -0,0 +1,31 @@
+// Error types shared across layers. Each carries the failing component in its name so logs and
+// tests can tell them apart without string matching.
+
+export class ConfigError extends Error {
+	override name = "ConfigError";
+}
+
+export class AgentRunError extends Error {
+	override name = "AgentRunError";
+}
+
+export class CardRenderError extends Error {
+	override name = "CardRenderError";
+}
+
+export class MemoryError extends Error {
+	override name = "MemoryError";
+}
+
+export class ScheduleError extends Error {
+	override name = "ScheduleError";
+}
+
+export class DelegationError extends Error {
+	override name = "DelegationError";
+}
+
+/** A request about agents or groups that cannot be met; its message is shown to whoever asked. */
+export class AgentError extends Error {
+	override name = "AgentError";
+}

package/src/core/domain/expression.ts

@@ -0,0 +1,21 @@
+export const EXPRESSIONS = [
+	"neutral",
+	"happy",
+	"thinking",
+	"concerned",
+	"apologetic",
+	"surprised",
+	"proud",
+	"amused",
+	"curious",
+	"sympathetic",
+	"playful",
+	"determined",
+	"sleepy",
+] as const;
+
+export type Expression = (typeof EXPRESSIONS)[number];
+
+export function isExpression(value: string): value is Expression {
+	return (EXPRESSIONS as readonly string[]).includes(value);
+}