pi-roundtable 0.8.0 → 0.9.1

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

@@ -18,20 +18,24 @@ import type {
 	OutboundReply,
 } from "../domain/conversation.ts";
 import type { InterimPosts } from "../domain/interim.ts";
-import type { OwnerPrompts } from "../domain/owner-prompts.ts";
 import type { OwnerNotifier } from "../domain/ports.ts";
 import { messages } from "../i18n/index.ts";
+import type { PromptScope, Prompts } from "../interactions/prompts.ts";
 import type { Logger } from "../log.ts";
 import type { OwnerOperations } from "../modules/discord-admin/discord-admin.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
-import type { Speaker } from "../speakers.ts";
 import { DiscordAgentChannels, DiscordDashboard } from "./agent-discord.ts";
+import {
+	type ContextSourceMessage,
+	contextSourceOf,
+} from "./channel-context.ts";
 import { discordChannelExecutor } from "./channel-executor.ts";
 import type { ChannelExecutor } from "./channel-operations.ts";
 import type { ComposedCommands } from "./compose-commands.ts";
 import type { ChannelInfo, DiscordConnection } from "./connection.ts";
 import { DiscordThreadHost } from "./dispatch-thread-host.ts";
 import type { ThreadHost } from "./dispatch-threads.ts";
+import { DEFAULT_FRESH_MARKER, postFreshMarker } from "./fresh-marker.ts";
 import { toInbound } from "./inbound-message.ts";
 import type { CardChannel } from "./owner-cards.ts";
 import { DiscordOwnerOps } from "./owner-discord.ts";
@@ -47,12 +51,15 @@ const STOP_PANEL_DELAY_MS = 5_000;
 
 export interface DiscordSurfaceOptions {
 	token: string;
+	/** The primary owner's Discord user id, whom the admin tools act as and the deprecated owner channel reaches. */
 	ownerId: string;
-	/** How the owner is named in audit-log reasons and refusals. */
+	/** How the primary owner is named in audit-log reasons and refusals. */
 	ownerName: string;
-	/** The owner's cards in a Discord channel; the surface hands them out as its `prompts`. */
-	prompts: (channel: ChannelKey, speaker?: Speaker) => OwnerPrompts | undefined;
+	/** The cards in a Discord channel; the surface hands them out as its `prompts`. */
+	prompts: (channel: ChannelKey, scope?: PromptScope) => Prompts | undefined;
 	logger: Logger;
+	/** The divider posted in a server channel when its conversation starts over; `false` posts none. Default: `DEFAULT_FRESH_MARKER`. */
+	freshMarker?: string | false;
 }
 
 /**
@@ -96,7 +103,7 @@ export class DiscordSurface
 			: undefined;
 	}
 
-	/** Discord reading and management for the owner's agent; calls fail until the connection is ready. */
+	/** Discord reading and management for the owner's agent, as the primary owner may; calls fail until the connection is ready. */
 	ownerOperations(): OwnerOperations {
 		return new DiscordOwnerOps(
 			this.#client,
@@ -150,14 +157,37 @@ export class DiscordSurface
 		};
 	}
 
+	/**
+	 * A server text channel's messages before one, as channel context reads them; undefined for a
+	 * direct message or a channel that holds no messages. Throws while the connection is not ready
+	 * or when Discord refuses, such as for a channel the bot cannot read.
+	 */
+	async messagesBefore(
+		channelId: string,
+		before: string,
+		limit: number,
+	): Promise<ContextSourceMessage[] | undefined> {
+		if (!this.#client.isReady()) throw new Error("Discord is not connected");
+		const channel = await this.#client.channels.fetch(channelId);
+		if (!channel?.isTextBased() || channel.isDMBased()) return undefined;
+		const fetched = await channel.messages.fetch({ before, limit });
+		const self = {
+			botId: this.#client.user.id,
+			applicationId: this.#client.application.id,
+		};
+		return [...fetched.values()].map((message) =>
+			contextSourceOf(message, self),
+		);
+	}
+
 	/** Reports deleted server channels by id; register before start. */
 	onChannelDeleted(handler: (channelId: string) => void): void {
 		this.#client.on(Events.ChannelDelete, (channel) => handler(channel.id));
 	}
 
-	/** The owner's approval and question cards in a Discord channel. */
-	prompts(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined {
-		return this.#options.prompts(channel, speaker);
+	/** The approval and question cards in a Discord channel, for those the scope names. */
+	prompts(channel: ChannelKey, scope?: PromptScope): Prompts | undefined {
+		return this.#options.prompts(channel, scope);
 	}
 
 	/** The channel's interim posts: ordinary messages, edited in place for the progress line. */
@@ -244,6 +274,20 @@ export class DiscordSurface
 		}
 	}
 
+	/** The divider that ends channel context's window; see `postFreshMarker`. */
+	async markFresh(channel: ChannelKey): Promise<void> {
+		await postFreshMarker(
+			this.#options.freshMarker ?? DEFAULT_FRESH_MARKER,
+			async () => {
+				const target = await this.#sendable(channel);
+				return {
+					dm: target.isDMBased(),
+					send: (text) => target.send({ content: text }),
+				};
+			},
+		);
+	}
+
 	startTyping(channel: ChannelKey): () => void {
 		let stopped = false;
 		const tick = () => {
@@ -339,15 +383,26 @@ export class DiscordSurface
 		};
 	}
 
-	/** The owner's direct-message channel. */
+	/** A Discord user's direct-message channel. */
+	async directChannel(userId: string): Promise<ChannelKey> {
+		const user = await this.#client.users.fetch(userId);
+		return `${PREFIX}${(await user.createDM()).id}`;
+	}
+
+	/** Sends a Discord user a direct message, split as a reply is. */
+	async sendDirect(userId: string, text: string): Promise<void> {
+		const user = await this.#client.users.fetch(userId);
+		for (const chunk of splitReply(text)) await user.send({ content: chunk });
+	}
+
+	/** @deprecated The primary owner's direct-message channel; see `DiscordConnection.ownerChannel`. */
 	async ownerChannel(): Promise<ChannelKey> {
-		const owner = await this.#client.users.fetch(this.#options.ownerId);
-		return `${PREFIX}${(await owner.createDM()).id}`;
+		return this.directChannel(this.#options.ownerId);
 	}
 
+	/** @deprecated Sends the primary owner a direct message; see `DiscordConnection.notifyOwner`. */
 	async notifyOwner(text: string): Promise<void> {
-		const owner = await this.#client.users.fetch(this.#options.ownerId);
-		for (const chunk of splitReply(text)) await owner.send({ content: chunk });
+		await this.sendDirect(this.#options.ownerId, text);
 	}
 
 	async stop(): Promise<void> {

package/src/core/discord/fresh-marker.ts

@@ -0,0 +1,24 @@
+/** The divider a guild channel gets when its conversation starts over. */
+export const DEFAULT_FRESH_MARKER = "─── new conversation ───";
+
+/** A channel as the divider needs it: whether it is a direct message, and a way to post. */
+export interface MarkerTarget {
+	dm: boolean;
+	send(text: string): Promise<unknown>;
+}
+
+/**
+ * Posts the divider that ends channel context's window after a conversation started over: a
+ * public post of the assistant in a server channel or thread, never in a direct message, and
+ * nothing for `false`. A channel that cannot be found or posted to is left as it is; a Discord
+ * error rejects, for the caller to log.
+ */
+export async function postFreshMarker(
+	marker: string | false,
+	find: () => Promise<MarkerTarget | undefined>,
+): Promise<void> {
+	if (marker === false) return;
+	const target = await find();
+	if (!target || target.dm) return;
+	await target.send(marker);
+}

package/src/core/discord/inbound-message.ts

@@ -55,18 +55,32 @@ export async function toInbound(
 		reference?.messageId && !forward
 			? await message.fetchReference().catch(() => undefined)
 			: undefined;
+	const authorName =
+		message.member?.displayName ??
+		message.author.globalName ??
+		message.author.username;
+	const roleIds = message.member
+		? [...message.member.roles.cache.keys()]
+		: undefined;
 	return {
 		channel: channelKey("discord", message.channelId),
 		messageId: message.id,
+		// A DM has no member, so its author's roles are unknown, not none.
+		actor: {
+			provider: "discord",
+			subject: message.author.id,
+			name: authorName,
+			surface: "discord",
+			...(roleIds
+				? { roles: roleIds.map((role) => `discord:role:${role}`) }
+				: {}),
+			...(message.guildId ? { space: message.guildId } : {}),
+			legacyId: message.author.id,
+		},
 		authorId: message.author.id,
-		authorName:
-			message.member?.displayName ??
-			message.author.globalName ??
-			message.author.username,
+		authorName,
 		authorIsBot: message.author.bot,
-		...(message.member
-			? { authorRoleIds: [...message.member.roles.cache.keys()] }
-			: {}),
+		...(roleIds ? { authorRoleIds: roleIds } : {}),
 		...(message.webhookId
 			? {
 					integration: {

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

@@ -5,6 +5,7 @@ import type {
 	InteractionContextType,
 	RESTPostAPIChatInputApplicationCommandsJSONBody,
 } from "discord.js";
+import type { DiscordActor } from "./discord-owners.ts";
 
 /** A group of slash commands and the components they post, handled together. */
 export interface InteractionModule {
@@ -50,7 +51,16 @@ export interface CommandGuard {
 	 * anyone may use; include the space or punctuation your language needs before it.
 	 */
 	readonly refusalHint?: string;
-	/** Whether the actor is the owner: an interaction, or anything with `user.id`, such as a test's. */
+	/**
+	 * Whether the actor may use the owner's commands now: an owner, the primary owner by their user
+	 * id and any other by their Discord identity, checked again each time. The actor is an
+	 * interaction, or anything with `user.id`, such as a test's.
+	 */
+	allows(actor: DiscordActor): Promise<boolean>;
+	/**
+	 * Whether the actor is the primary owner, by user id.
+	 * @deprecated Since 0.9 every owner uses the owner's commands; ask `allows`. Goes away in 1.0.
+	 */
 	isOwner(actor: { user: { id: string } }): boolean;
 	/** Runs a handler; a failure becomes a panel instead of a hanging interaction. */
 	run(interaction: Interaction, run: () => Promise<void>): Promise<void>;

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

@@ -0,0 +1,80 @@
+import type { Interaction } from "discord.js";
+import { CARD_PREFIX, type CardPayload } from "./owner-cards.ts";
+
+/** The primary owner of the cards' tests. */
+export const OWNER = "100000000000000001";
+
+/** The card's JSON, where its text, custom ids, and disabled flags can be read. */
+export 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. */
+export 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);
+					},
+				};
+			},
+		}),
+	};
+}
+
+export type Kind = "button" | "select" | "modal";
+
+/** A press of a card's control, recording how it was answered. */
+export function press(
+	kind: Kind,
+	customId: string,
+	options: {
+		user?: string;
+		roles?: string[];
+		values?: string[];
+		text?: string;
+	} = {},
+) {
+	const replies: string[] = [];
+	const updates: CardPayload[] = [];
+	const modals: unknown[] = [];
+	// SAFETY: the cards read only these members of an interaction.
+	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 };
+}
+
+/** Lets a posted card settle. */
+export const tick = () => Bun.sleep(1);

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

@@ -14,20 +14,21 @@ import {
 } from "discord.js";
 import { parseChannelKey } from "../contract/surface.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
+import { messages } from "../i18n/index.ts";
 import type {
 	Approval,
 	OwnerAnswer,
-	OwnerPrompts,
 	OwnerQuestion,
-} from "../domain/owner-prompts.ts";
-import { messages } from "../i18n/index.ts";
+	PromptScope,
+	Prompts,
+} from "../interactions/prompts.ts";
 import type { Logger } from "../log.ts";
 import {
-	type Speaker,
-	type SpeakerPolicy,
-	type Tier,
-	tierAtLeast,
-} from "../speakers.ts";
+	type Audience,
+	type CardAudienceOptions,
+	CardAudiences,
+} from "./card-audience.ts";
+import { DiscordOwners, discordUser } from "./discord-owners.ts";
 import type { InteractionModule } from "./interaction-module.ts";
 import { ownerPanel, type PanelContent, plain } from "./owner-panel.ts";
 
@@ -37,7 +38,7 @@ export const CARD_TIMEOUT_MS = 30 * 60_000;
 const OTHER = "other";
 const TEXT_FIELD = "text";
 
-/** A card's message: the panel, led by a mention of the owner in a thread. */
+/** A card's message: the panel, led in a thread by a mention of those it is for. */
 export type CardPayload = Omit<
 	ReturnType<typeof ownerPanel>,
 	"components" | "allowedMentions"
@@ -57,14 +58,18 @@ export interface CardMessage {
 /** Where a channel's cards are posted. */
 export interface CardChannel {
 	send(payload: CardPayload): Promise<CardMessage>;
-	/** A thread, where the owner is mentioned so they hear of the card; a channel never mentions them. */
+	/** A thread, where those a card is for are mentioned so they hear of it; a channel mentions no one. */
 	thread?: boolean;
 }
 
 export interface OwnerCardsOptions {
+	/** The primary owner's Discord user id. */
 	ownerId: string;
-	/** Decides who holds a tier, for cards that lower tiers may answer; without it only the owner answers. */
-	speakers?: SpeakerPolicy;
+	/**
+	 * Who holds a tier now, and which owners have a Discord identity, for cards that others than
+	 * the primary owner may answer; without it only the primary owner answers.
+	 */
+	identity?: CardAudienceOptions["identity"];
 	/** The Discord channel by id; throws when it cannot take messages. */
 	channel(channelId: string): Promise<CardChannel>;
 	logger: Logger;
@@ -91,42 +96,41 @@ interface OpenCard {
 	audience: Audience;
 }
 
-/** The people a card is for. */
-interface Audience {
-	allows(user: { id: string; roleIds: readonly string[] }): boolean;
-	/** The user the card mentions in a thread. */
-	mentionId: string;
-	/** Shown on the card. */
-	note: string;
-	refusal: string;
-}
-
 /**
- * The owner's cards in the assistant's channels: approvals of held actions and ask_user questions,
- * answered with buttons, a menu, or a form. The owner may answer, and so may the speaker whose
- * turn asks, when the card allows (a question always; an approval at its tier); an unanswered card
- * expires after 30 minutes and a stopped turn cancels it. Open cards live in memory, so a
- * restart abandons them; pressing one then says it no longer works.
+ * The cards in the assistant's channels: approvals of held actions and ask_user questions,
+ * answered with buttons, a menu, or a form, by those the turn's prompt scope names (see
+ * `CardAudiences`): the speaker whose turn asks, when the card allows (a question always; an
+ * approval at its tier), and, in a shared conversation, the owners. An unanswered card expires
+ * after 30 minutes and a stopped turn cancels it. Open cards live in memory, so a restart
+ * abandons them; pressing one then says it no longer works.
  */
 export class OwnerCards implements InteractionModule {
 	readonly #options: OwnerCardsOptions;
+	readonly #audiences: CardAudiences;
 	readonly #open = new Map<string, OpenCard>();
 
 	constructor(options: OwnerCardsOptions) {
 		this.#options = options;
+		this.#audiences = new CardAudiences(options, new DiscordOwners(options));
 	}
 
 	commands() {
 		return [];
 	}
 
-	/** The channel's cards; the chat surface port sends only Discord keys here. */
-	prompts(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined {
+	/**
+	 * The channel's cards for the scope's turn; without a scope they are the owners'. The chat
+	 * surface port sends only Discord keys here.
+	 */
+	prompts(channel: ChannelKey, scope?: PromptScope): Prompts | undefined {
 		const channelId = parseChannelKey(channel).id;
 		return {
-			confirm: (title, message, signal, minTier = "owner") =>
-				this.#post<Approval>(channelId, signal, "expired", "cancelled", {
-					audience: this.#approvers(minTier, speaker),
+			confirm: async (title, message, signal, minTier = "owner") => {
+				const audience = await this.#audiences.approval(scope, minTier);
+				// A private conversation's call above its person's tier is no one's to approve.
+				if (!audience) return "expired";
+				return this.#post<Approval>(channelId, signal, "expired", "cancelled", {
+					audience,
 					title,
 					sections: [message],
 					rows: (id, disabled) => [
@@ -146,22 +150,26 @@ export class OwnerCards implements InteractionModule {
 						),
 					],
 					footer: messages().cardApprovalFooter,
-				}),
-			ask: (title, question, signal) =>
-				this.#post<OwnerAnswer | undefined>(
+				});
+			},
+			ask: async (title, question, signal) => {
+				const audience = await this.#audiences.question(scope);
+				if (!audience) return undefined;
+				return this.#post<OwnerAnswer | undefined>(
 					channelId,
 					signal,
 					undefined,
 					undefined,
 					{
-						audience: this.#asker(speaker),
+						audience,
 						title,
 						sections: [question.question],
 						question,
 						rows: (id, disabled) => askRows(id, question, disabled),
 						footer: messages().cardQuestionFooter,
 					},
-				),
+				);
+			},
 		};
 	}
 
@@ -214,7 +222,7 @@ export class OwnerCards implements InteractionModule {
 						footer,
 					},
 					open.mention === true,
-					card.audience.mentionId,
+					card.audience.mentions,
 				);
 			const abort = () => settle(cancelled, messages().cardStopped);
 			const timer = setTimeout(
@@ -250,67 +258,22 @@ export class OwnerCards implements InteractionModule {
 	}
 
 	/** The card's panel; in a thread it leads with the mention of who may answer. */
-	#panel(content: PanelContent, mention: boolean, userId: string): CardPayload {
+	#panel(
+		content: PanelContent,
+		mention: boolean,
+		userIds: readonly string[],
+	): CardPayload {
 		const panel = ownerPanel(content);
 		if (!mention) return panel;
 		return {
 			...panel,
 			components: [
-				new TextDisplayBuilder().setContent(`<@${userId}>`),
+				new TextDisplayBuilder().setContent(
+					userIds.map((id) => `<@${id}>`).join(" "),
+				),
 				...panel.components,
 			],
-			allowedMentions: { users: [userId] },
-		};
-	}
-
-	/**
-	 * An approval is for the speaker whose turn held the call, when their tier holds it, and for
-	 * the owner; the owner's alone by default. Nobody else in the channel may approve it.
-	 */
-	#approvers(minTier: Tier, speaker: Speaker | undefined): Audience {
-		const { ownerId, speakers } = this.#options;
-		if (
-			minTier === "owner" ||
-			!speakers ||
-			!speaker ||
-			speaker.id === ownerId ||
-			!tierAtLeast(speaker.tier, minTier)
-		)
-			return {
-				allows: (user) => user.id === ownerId,
-				mentionId: ownerId,
-				note: "",
-				refusal: messages().cardOwnerOnly,
-			};
-		return {
-			allows: (user) => {
-				if (user.id === ownerId) return true;
-				if (user.id !== speaker.id) return false;
-				// Their tier when they press, in case it was lowered during the turn.
-				const who = speakers.resolve({ ...user, name: "" });
-				return who !== undefined && tierAtLeast(who.tier, minTier);
-			},
-			mentionId: speaker.id,
-			note: messages().cardApproversNote(speaker.id),
-			refusal: messages().cardApproversRefusal,
-		};
-	}
-
-	/** A question is for the speaker whose turn asks it, and for the owner. */
-	#asker(speaker: Speaker | undefined): Audience {
-		const { ownerId } = this.#options;
-		if (!speaker || speaker.id === ownerId)
-			return {
-				allows: (user) => user.id === ownerId,
-				mentionId: ownerId,
-				note: "",
-				refusal: messages().cardOwnerOnly,
-			};
-		return {
-			allows: (user) => user.id === speaker.id || user.id === ownerId,
-			mentionId: speaker.id,
-			note: messages().cardAskerNote(speaker.id),
-			refusal: messages().cardAskerRefusal,
+			allowedMentions: { users: [...userIds] },
 		};
 	}
 
@@ -335,10 +298,8 @@ export class OwnerCards implements InteractionModule {
 			});
 			return true;
 		}
-		const { member } = interaction;
-		const roleIds =
-			member && "cache" in member.roles ? [...member.roles.cache.keys()] : [];
-		if (!card.audience.allows({ id: interaction.user.id, roleIds })) {
+		const user = discordUser(interaction);
+		if (!(await card.audience.allows(user))) {
 			await interaction.reply({
 				content: card.audience.refusal,
 				flags: MessageFlags.Ephemeral,
@@ -354,7 +315,7 @@ export class OwnerCards implements InteractionModule {
 					footer: outcome,
 				},
 				card.mention === true,
-				card.audience.mentionId,
+				card.audience.mentions,
 			);
 		if (interaction.isButton() && (action === "yes" || action === "no")) {
 			const approved = action === "yes";