pi-roundtable 0.8.0 → 0.9.0

package/src/core/discord/connection.ts

@@ -11,9 +11,17 @@ export type ChannelInfo =
 
 /** The Discord connection as plugins use it, apart from the chat surface the host drives. */
 export interface DiscordConnection {
-	/** The owner's direct-message channel. */
+	/**
+	 * The primary owner's direct-message channel.
+	 * @deprecated Since 0.9 there may be more than one owner; this is the primary owner's, kept for
+	 * plugins written for 0.8. Reach a principal through their own channel instead. Goes away in 1.0.
+	 */
 	ownerChannel(): Promise<ChannelKey>;
-	/** Sends the owner a direct message. */
+	/**
+	 * Sends the primary owner a direct message.
+	 * @deprecated Since 0.9 there may be more than one owner; this is the primary owner's, kept for
+	 * plugins written for 0.8. Goes away in 1.0.
+	 */
 	notifyOwner(text: string): Promise<void>;
 	/**
 	 * What a channel is called: undefined when Discord no longer knows it; throws while the
@@ -30,6 +38,10 @@ export interface DiscordConnection {
 	agentDashboard(guildId: string): DashboardBoard;
 	/** Threads for background dispatches, in the channel that started each. */
 	threadHost(): ThreadHost;
-	/** 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, checked against what the primary owner
+	 * may do on the server, whichever owner's turn calls them; calls fail until the connection is
+	 * ready.
+	 */
 	ownerOperations(): OwnerOperations;
 }

package/src/core/discord/direct-channel.ts

@@ -0,0 +1,54 @@
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { IdentityService } from "../identity/identity-service.ts";
+import type { DirectChannelProvider } from "../presence/direct-channels.ts";
+
+export interface DiscordDirectChannelOptions {
+	/** A Discord user's direct-message channel; throws when Discord cannot be reached. */
+	directChannel(userId: string): Promise<ChannelKey>;
+	/** Sends a Discord user a direct message. */
+	sendDirect(userId: string, text: string): Promise<void>;
+	/**
+	 * Whom a principal is on Discord, by the Discord identities linked to them. Without it only the
+	 * primary owner is reached, whose principal 0.8 knew by their Discord user id.
+	 */
+	identity?: Pick<IdentityService, "identities">;
+	/**
+	 * The primary owner's Discord user id: of a principal's Discord identities, the one reached
+	 * first, so a single owner is reached in the direct messages 0.8 used.
+	 */
+	ownerId: string;
+}
+
+/**
+ * Reaches a person in their Discord direct messages, through a Discord identity linked to their
+ * principal; a principal with none is not reached here.
+ */
+export function discordDirectChannel(
+	options: DiscordDirectChannelOptions,
+): DirectChannelProvider {
+	const { identity, ownerId } = options;
+	const userOf = async (principalId: string): Promise<string | undefined> => {
+		if (!identity) return principalId === ownerId ? ownerId : undefined;
+		const users = (await identity.identities(principalId))
+			.filter((link) => link.provider === "discord")
+			.map((link) => link.subject);
+		return users.includes(ownerId) ? ownerId : users[0];
+	};
+	return {
+		name: "discord",
+		label: "a direct message on Discord",
+		knows: async (principalId) => (await userOf(principalId)) !== undefined,
+		reaches: async (principalId) => {
+			const user = await userOf(principalId);
+			return user === undefined ? undefined : options.directChannel(user);
+		},
+		deliver: async (principalId, text) => {
+			const user = await userOf(principalId);
+			if (user === undefined)
+				throw new Error(
+					`principal ${principalId} has no Discord identity to send a direct message to`,
+				);
+			await options.sendDirect(user, text);
+		},
+	};
+}

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

@@ -0,0 +1,133 @@
+import type { IdentityService } from "../identity/identity-service.ts";
+import type { Logger } from "../log.ts";
+import { type Tier, tierAtLeast } from "../speakers.ts";
+
+/** A Discord user who pressed or ran something; their roles are unknown where the interaction carries no member. */
+export interface DiscordUser {
+	id: string;
+	name: string;
+	roleIds?: readonly string[];
+}
+
+/** What a Discord interaction tells of who made it; a test may give only `user.id`. */
+export interface DiscordActor {
+	user: { id: string; username?: string; globalName?: string | null };
+	member?: unknown;
+}
+
+/** The user of an interaction, with their roles where its member carries them. */
+export function discordUser(actor: DiscordActor): DiscordUser {
+	const { user, member } = actor;
+	const roles =
+		typeof member === "object" && member !== null && "roles" in member
+			? member.roles
+			: undefined;
+	const roleIds =
+		typeof roles === "object" &&
+		roles !== null &&
+		"cache" in roles &&
+		roles.cache instanceof Map
+			? [...roles.cache.keys()].map(String)
+			: undefined;
+	return {
+		id: user.id,
+		name: user.globalName ?? user.username ?? user.id,
+		...(roleIds ? { roleIds } : {}),
+	};
+}
+
+export interface DiscordOwnersOptions {
+	/** The primary owner's Discord user id, an owner whatever the identity service says. */
+	ownerId: string;
+	/** Who holds a tier and which owners have a Discord identity; without it the primary owner is the only owner. */
+	identity?: Pick<IdentityService, "resolve" | "owners" | "identities">;
+	logger: Logger;
+}
+
+/**
+ * The owners as Discord knows them: the primary owner by their user id, and every other owner
+ * principal's Discord identities, each checked again as they act. Only an owner's own identity is
+ * ever resolved, so someone else's press or command admits no one.
+ */
+export class DiscordOwners {
+	readonly #options: DiscordOwnersOptions;
+
+	constructor(options: DiscordOwnersOptions) {
+		this.#options = options;
+	}
+
+	/** The primary owner's Discord user id. */
+	get primary(): string {
+		return this.#options.ownerId;
+	}
+
+	/** The primary owner, then every other owner's Discord user ids. */
+	async ids(): Promise<string[]> {
+		const { ownerId, identity, logger } = this.#options;
+		if (!identity) return [ownerId];
+		const ids = new Set([ownerId]);
+		try {
+			for (const owner of await identity.owners())
+				for (const link of await identity.identities(owner.id))
+					if (link.provider === "discord") ids.add(link.subject);
+		} catch (error) {
+			logger.warn(
+				{ err: error },
+				"could not read the owners' identities; only the primary owner counts",
+			);
+		}
+		return [...ids];
+	}
+
+	/** Whether the user is an owner now: the primary owner, or another owner's Discord identity at the owner tier. */
+	async isOwner(user: DiscordUser): Promise<boolean> {
+		if (user.id === this.#options.ownerId) return true;
+		if (!(await this.ids()).includes(user.id)) return false;
+		return this.holds(user, "owner");
+	}
+
+	/** Whether the principal is an owner's; false when it cannot be read. */
+	async isOwnerPrincipal(principalId: string): Promise<boolean> {
+		const { identity, logger } = this.#options;
+		if (!identity) return false;
+		try {
+			const owners = await identity.owners();
+			return owners.some((owner) => owner.id === principalId);
+		} catch (error) {
+			logger.warn(
+				{ principal: principalId, err: error },
+				"could not read the owners; the principal is not counted as one",
+			);
+			return false;
+		}
+	}
+
+	/**
+	 * Whether the user holds `minTier` as they act, as the principal named when there is one;
+	 * without `minTier` anyone does. Call it only for someone already known, so it admits no one.
+	 */
+	async holds(
+		user: DiscordUser,
+		minTier: Tier | undefined,
+		principalId?: string,
+	): Promise<boolean> {
+		const { identity } = this.#options;
+		if (!minTier) return true;
+		if (!identity) return false;
+		const who = await identity.resolve({
+			provider: "discord",
+			subject: user.id,
+			name: user.name,
+			surface: "discord",
+			...(user.roleIds
+				? { roles: user.roleIds.map((role) => `discord:role:${role}`) }
+				: {}),
+			legacyId: user.id,
+		});
+		return (
+			who !== undefined &&
+			(principalId === undefined || who.principalId === principalId) &&
+			tierAtLeast(who.tier, minTier)
+		);
+	}
+}

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);