pi-roundtable 0.9.12 → 0.10.0

package/src/core/discord/card-audience.ts

@@ -1,5 +1,5 @@
 import { messages } from "../i18n/index.ts";
-import type { PromptScope } from "../interactions/prompts.ts";
+import type { ApprovedBy, PromptScope } from "../interactions/prompts.ts";
 import { type Tier, tierAtLeast } from "../speakers.ts";
 import type {
 	DiscordOwners,
@@ -17,6 +17,11 @@ export interface Audience {
 	note: string;
 	/** What someone else who presses it is told. */
 	refusal: string;
+	/**
+	 * Who answered, as the approval reports them, for a user `allows` admitted; undefined when it
+	 * cannot be read. Only an approval's audience has it.
+	 */
+	approver?(user: DiscordUser): Promise<ApprovedBy | undefined>;
 }
 
 /** The primary owner, who answers every card the owners may, and who else holds a tier. */
@@ -31,6 +36,13 @@ export type CardAudienceOptions = DiscordOwnersOptions;
  * escalates to the owners, every owner with a Discord identity answers it too, and a card the
  * speaker cannot answer, or whose principal has no Discord identity, is theirs alone; where it
  * escalates to no one, that card goes to no one. Without a scope, a card is the owners'.
+ *
+ * An approval that names `approvers`, where it escalates, is theirs instead of the speaker's:
+ * each named principal answers on any of their Discord identities that is still theirs when they
+ * press, at the tier it needs then, and the card mentions all of those identities. The speaker
+ * does not answer it unless named. The owners still do, and are the whole audience when none of
+ * the named has a Discord identity. Where the scope escalates to no one, the person is the only
+ * one who answers, and only if named or an owner: any other person's card is not posted.
  */
 export class CardAudiences {
 	readonly #options: CardAudienceOptions;
@@ -42,14 +54,28 @@ export class CardAudiences {
 	}
 
 	/** Who may approve a call held at `minTier`; undefined when no one may. */
-	approval(
+	async approval(
 		scope: PromptScope | undefined,
 		minTier: Tier,
+		named?: readonly string[],
 	): Promise<Audience | undefined> {
-		return this.#audience(scope, minTier, {
-			note: messages().cardApproversNote,
-			refusal: messages().cardApproversRefusal,
-		});
+		let approvers = named;
+		// A private conversation's person is the only one who answers, so a call naming others is theirs only if named or an owner.
+		if (approvers && scope?.escalate === "none") {
+			if (!(await this.#mayAnswerPrivately(scope, approvers))) return undefined;
+			approvers = undefined;
+		}
+		return this.#audience(
+			scope,
+			minTier,
+			{
+				note: messages().cardApproversNote,
+				refusal: approvers
+					? messages().cardNamedApproversRefusal
+					: messages().cardApproversRefusal,
+			},
+			approvers,
+		);
 	}
 
 	/** Who may answer a question; undefined when no one may. */
@@ -64,10 +90,33 @@ export class CardAudiences {
 		scope: PromptScope | undefined,
 		minTier: Tier | undefined,
 		words: { note(...userIds: string[]): string; refusal: string },
+		approvers?: readonly string[],
 	): Promise<Audience | undefined> {
 		const { ownerId } = this.#options;
 		const escalates = scope?.escalate !== "none";
-		const own = scope && (await this.#ownIdentities(scope, minTier));
+		if (approvers && scope) {
+			const named = await this.#approverIdentities(approvers);
+			if (named.size > 0)
+				return {
+					allows: async (user) => {
+						for (const [principalId, ids] of named)
+							if (
+								ids.includes(user.id) &&
+								// Read the links again: one moved or unlinked since the card was posted is no longer theirs.
+								(await this.#stillOwn(principalId, user.id)) &&
+								(await this.#owners.holds(user, minTier, principalId))
+							)
+								return true;
+						return this.#owners.isOwner(user);
+					},
+					mentions: [...new Set([...named.values()].flat())],
+					note: words.note(...new Set([...named.values()].flat())),
+					refusal: words.refusal,
+					approver: (user) => this.#approver(user),
+				};
+		}
+		const own =
+			scope && !approvers && (await this.#ownIdentities(scope, minTier));
 		if (scope && own) {
 			const primary = own.includes(ownerId);
 			const mentions = own.includes(scope.speakerId) ? [scope.speakerId] : own;
@@ -87,6 +136,7 @@ export class CardAudiences {
 				mentions,
 				note: primary ? "" : words.note(...mentions),
 				refusal: primary ? messages().cardOwnerOnly : words.refusal,
+				approver: (user) => this.#approver(user),
 			};
 		}
 		if (!escalates) return undefined;
@@ -95,9 +145,56 @@ export class CardAudiences {
 			mentions: await this.#owners.ids(),
 			note: "",
 			refusal: messages().cardOwnerOnly,
+			approver: (user) => this.#approver(user),
 		};
 	}
 
+	/**
+	 * The Discord identities of each named principal that has any, by principal id; a principal
+	 * whose identities cannot be read, or who has none, is left out.
+	 */
+	async #approverIdentities(
+		principals: readonly string[],
+	): Promise<Map<string, string[]>> {
+		const named = new Map<string, string[]>();
+		for (const principalId of new Set(principals)) {
+			const ids = await this.#discordIdentities(principalId);
+			if (ids && ids.length > 0) named.set(principalId, ids);
+		}
+		return named;
+	}
+
+	/** Whether a private conversation's person may answer a call that names `approvers`: when named, or an owner. */
+	async #mayAnswerPrivately(
+		scope: PromptScope,
+		approvers: readonly string[],
+	): Promise<boolean> {
+		return (
+			approvers.includes(scope.principalId) ||
+			scope.speakerId === this.#options.ownerId ||
+			(await this.#owners.isOwnerPrincipal(scope.principalId))
+		);
+	}
+
+	/** Who the user is as an approver: their principal, the name their identity goes by, and whether they are an owner. */
+	async #approver(user: DiscordUser): Promise<ApprovedBy | undefined> {
+		const owner = (await this.#owners.isOwner(user))
+			? { owner: true as const }
+			: {};
+		const who = await this.#owners.speakerOf(user);
+		if (who)
+			return {
+				principalId: who.principalId,
+				speakerId: user.id,
+				name: user.name,
+				...owner,
+			};
+		// Without an identity service the primary owner is the only one who answers.
+		return this.#options.identity
+			? undefined
+			: { principalId: user.id, speakerId: user.id, name: user.name, ...owner };
+	}
+
 	/** Whether the Discord user is still one of the principal's identities; false when that cannot be read. */
 	async #stillOwn(principalId: string, userId: string): Promise<boolean> {
 		return (

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

@@ -1,6 +1,6 @@
 import type { IdentityService } from "../identity/identity-service.ts";
 import type { Logger } from "../log.ts";
-import { type Tier, tierAtLeast } from "../speakers.ts";
+import { type Speaker, 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 {
@@ -102,19 +102,11 @@ export class DiscordOwners {
 		}
 	}
 
-	/**
-	 * 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> {
+	/** The speaker the user is as they act; undefined without an identity service or when none serves them. Call it only for someone already admitted. */
+	async speakerOf(user: DiscordUser): Promise<Speaker | undefined> {
 		const { identity } = this.#options;
-		if (!minTier) return true;
-		if (!identity) return false;
-		const who = await identity.resolve({
+		if (!identity) return undefined;
+		return identity.resolve({
 			provider: "discord",
 			subject: user.id,
 			name: user.name,
@@ -124,6 +116,20 @@ export class DiscordOwners {
 				: {}),
 			legacyId: user.id,
 		});
+	}
+
+	/**
+	 * 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> {
+		if (!minTier) return true;
+		if (!this.#options.identity) return false;
+		const who = await this.speakerOf(user);
 		return (
 			who !== undefined &&
 			(principalId === undefined || who.principalId === principalId) &&

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

@@ -0,0 +1,73 @@
+import type { TextDisplayBuilder } from "discord.js";
+import type { ApprovedBy, OwnerQuestion } from "../interactions/prompts.ts";
+import type { Audience } from "./card-audience.ts";
+import type { DiscordUser } from "./discord-owners.ts";
+import type { Rows } from "./owner-card-rows.ts";
+import type { ownerPanel } from "./owner-panel.ts";
+
+/** 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"
+> & {
+	components: (
+		| ReturnType<typeof ownerPanel>["components"][number]
+		| TextDisplayBuilder
+	)[];
+	allowedMentions: { parse?: never[]; users?: string[] };
+};
+
+/** The posted card, which is edited to show how it ended. */
+export interface CardMessage {
+	edit(payload: CardPayload): Promise<unknown>;
+}
+
+/** Where a channel's cards are posted. */
+export interface CardChannel {
+	send(payload: CardPayload): Promise<CardMessage>;
+	/** A thread, where those a card is for are mentioned so they hear of it; a channel mentions no one. */
+	thread?: boolean;
+}
+
+/** A turn a card answered after its turn stopped waiting starts, as a message in its channel. */
+export interface LateTurn {
+	channelId: string;
+	/** The card's message, which the turn's message stands for. */
+	messageId: string;
+	/** Who answered. */
+	user: DiscordUser;
+	/** The server the channel belongs to; absent in a direct message. */
+	guildId?: string;
+	isDirect: boolean;
+	text: string;
+}
+
+/** Where and by whom a card was answered. */
+export interface Answerer {
+	user: DiscordUser;
+	/** Who approved, for an approval card they approved. */
+	approver?: ApprovedBy;
+	messageId?: string;
+	guildId?: string;
+	isDirect: boolean;
+}
+
+/** One open card: how it looks, and how it ends. */
+export interface OpenCard {
+	title: string;
+	sections: string[];
+	/** The card's controls, disabled once it has ended. */
+	rows(disabled: boolean): Rows;
+	/**
+	 * Ends the card with its answer; the answering interaction shows the outcome. A card whose
+	 * turn stopped waiting starts a turn with the answer instead.
+	 */
+	end(value: unknown, by: Answerer): void;
+	question?: OwnerQuestion;
+	/** Options chosen together with "Other…", kept while its form is open. */
+	picked?: string[];
+	/** Posted in a thread, so it leads with the mention of who may answer. */
+	mention?: boolean;
+	/** Who may answer, and what to tell someone else who presses it. */
+	audience: Audience;
+}

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

@@ -24,11 +24,7 @@ import {
 	type CardAudienceOptions,
 	CardAudiences,
 } from "./card-audience.ts";
-import {
-	DiscordOwners,
-	type DiscordUser,
-	discordUser,
-} from "./discord-owners.ts";
+import { DiscordOwners, discordUser } from "./discord-owners.ts";
 import type { InteractionModule } from "./interaction-module.ts";
 import {
 	answeredLine,
@@ -39,36 +35,25 @@ import {
 	type Rows,
 	TEXT_FIELD,
 } from "./owner-card-rows.ts";
+import type {
+	Answerer,
+	CardChannel,
+	CardMessage,
+	CardPayload,
+	LateTurn,
+	OpenCard,
+} from "./owner-card-types.ts";
 import { ownerPanel, type PanelContent } from "./owner-panel.ts";
 
+export type {
+	CardChannel,
+	CardPayload,
+	LateTurn,
+} from "./owner-card-types.ts";
 export { CARD_PREFIX };
 /** How long a turn that can be resumed waits on its card before it goes on without the answer. */
 export const CARD_GRACE_MS = 2 * 60_000;
 
-/** 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"
-> & {
-	components: (
-		| ReturnType<typeof ownerPanel>["components"][number]
-		| TextDisplayBuilder
-	)[];
-	allowedMentions: { parse?: never[]; users?: string[] };
-};
-
-/** The posted card, which is edited to show how it ended. */
-export interface CardMessage {
-	edit(payload: CardPayload): Promise<unknown>;
-}
-
-/** Where a channel's cards are posted. */
-export interface CardChannel {
-	send(payload: CardPayload): Promise<CardMessage>;
-	/** 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;
@@ -92,47 +77,6 @@ export interface OwnerCardsOptions {
 	resume?(turn: LateTurn): void;
 }
 
-/** A turn a card answered after its turn stopped waiting starts, as a message in its channel. */
-export interface LateTurn {
-	channelId: string;
-	/** The card's message, which the turn's message stands for. */
-	messageId: string;
-	/** Who answered. */
-	user: DiscordUser;
-	/** The server the channel belongs to; absent in a direct message. */
-	guildId?: string;
-	isDirect: boolean;
-	text: string;
-}
-
-/** Where and by whom a card was answered. */
-interface Answerer {
-	user: DiscordUser;
-	messageId?: string;
-	guildId?: string;
-	isDirect: boolean;
-}
-
-/** One open card: how it looks, and how it ends. */
-interface OpenCard {
-	title: string;
-	sections: string[];
-	/** The card's controls, disabled once it has ended. */
-	rows(disabled: boolean): Rows;
-	/**
-	 * Ends the card with its answer; the answering interaction shows the outcome. A card whose
-	 * turn stopped waiting starts a turn with the answer instead.
-	 */
-	end(value: unknown, by: Answerer): void;
-	question?: OwnerQuestion;
-	/** Options chosen together with "Other…", kept while its form is open. */
-	picked?: string[];
-	/** Posted in a thread, so it leads with the mention of who may answer. */
-	mention?: boolean;
-	/** Who may answer, and what to tell someone else who presses it. */
-	audience: Audience;
-}
-
 /**
  * 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
@@ -164,8 +108,20 @@ export class OwnerCards implements InteractionModule {
 	prompts(channel: ChannelKey, scope?: PromptScope): Prompts | undefined {
 		const channelId = parseChannelKey(channel).id;
 		return {
-			confirm: async (title, message, signal, minTier = "owner", wait) => {
-				const audience = await this.#audiences.approval(scope, minTier);
+			confirm: async (
+				title,
+				message,
+				signal,
+				minTier = "owner",
+				wait,
+				_details,
+				options,
+			) => {
+				const audience = await this.#audiences.approval(
+					scope,
+					minTier,
+					options?.approvers,
+				);
 				// A private conversation's call above its person's tier is no one's to approve.
 				if (!audience) return "unavailable";
 				return this.#post<Approval>(
@@ -183,11 +139,19 @@ export class OwnerCards implements InteractionModule {
 											wait.late({
 												kind: "approval",
 												approved: value === "approved",
-												by,
+												by: by.user.name,
+												...(by.approver ? { approvedBy: by.approver } : {}),
 											}),
 									},
 								}
 							: {}),
+						...(options?.approvedBy
+							? {
+									approved: (by: Answerer) => {
+										if (by.approver) options.approvedBy?.(by.approver);
+									},
+								}
+							: {}),
 						title,
 						sections: [message],
 						rows: (id, disabled) => [
@@ -228,7 +192,7 @@ export class OwnerCards implements InteractionModule {
 											wait.late({
 												kind: "question",
 												answer: value as OwnerAnswer,
-												by,
+												by: by.user.name,
 											}),
 									},
 								}
@@ -262,8 +226,10 @@ export class OwnerCards implements InteractionModule {
 			footer: string;
 			wait?: {
 				pending: T;
-				late(value: unknown, by: string): ReturnType<PromptWait["late"]>;
+				late(value: unknown, by: Answerer): ReturnType<PromptWait["late"]>;
 			};
+			/** Hears who approved the card, before it resolves approved in its turn. */
+			approved?(by: Answerer): void;
 		},
 	): Promise<T> {
 		const { logger, graceMs = CARD_GRACE_MS, resume } = this.#options;
@@ -323,10 +289,11 @@ export class OwnerCards implements InteractionModule {
 				audience: card.audience,
 				end: (value, by) => {
 					const answeredLate = late;
+					if (value === "approved" && !answeredLate) card.approved?.(by);
 					settle(value as T, undefined);
 					if (!answeredLate || !wait || !resume) return;
 					try {
-						const text = wait.late(value, by.user.name);
+						const text = wait.late(value, by);
 						if (text === undefined) return;
 						resume({
 							channelId,
@@ -429,7 +396,19 @@ export class OwnerCards implements InteractionModule {
 			);
 		if (interaction.isButton() && (action === "yes" || action === "no")) {
 			const approved = action === "yes";
-			card.end(approved ? "approved" : "declined", by);
+			const approver = approved
+				? await card.audience.approver?.(user).catch((error: unknown) => {
+						this.#options.logger.warn(
+							{ err: error },
+							"could not tell who approved; the call runs without an approver",
+						);
+						return undefined;
+					})
+				: undefined;
+			card.end(
+				approved ? "approved" : "declined",
+				approver ? { ...by, approver } : by,
+			);
 			await interaction.update(
 				closed(approved ? messages().cardApproved : messages().cardDeclined),
 			);

package/src/core/domain/conversation.ts

@@ -19,6 +19,13 @@ export interface HeldCall {
 	action: string;
 	/** The lowest tier that may approve it, when higher than its tool's own; see `HoldRule.approvalTier`. */
 	minTier?: Tier;
+	/**
+	 * The principal ids that may approve it instead of the speaker whose turn held it, as the tool's
+	 * `approvers` named them; the owners may still. Absent when the tool names none, and an empty
+	 * list leaves the owners alone. They are kept with the call, so a message that confirms it after
+	 * a restart honors them; a private conversation ignores them.
+	 */
+	approverIds?: string[];
 }
 
 export interface PendingConfirmation {

package/src/core/domain/ports.ts

@@ -21,7 +21,10 @@ export interface TurnRequest {
 	text: string;
 	/** Files and images the message carries; none when absent. */
 	attachments?: TurnAttachments;
-	/** The owner confirmed the channel's pending actions, so they may run in this turn. */
+	/**
+	 * The speaker confirmed the channel's pending actions, so they may run in this turn, except
+	 * those that named approvers the speaker is neither among nor an owner of, which stay pending.
+	 */
 	confirmed?: boolean;
 	/** Set for a turn of an agent-server agent. */
 	agent?: AgentTurnScope;

package/src/core/holds.ts

@@ -57,6 +57,27 @@ export interface HoldRule {
 		input: Record<string, unknown>,
 		context: HoldContext,
 	): Tier | undefined;
+	/**
+	 * The principal ids that may approve a call of this rule's tool instead of the speaker whose turn
+	 * makes it, looked up as that turn; undefined when the rule names none and the speaker approves
+	 * it, as for any held call. The confirmation gate asks it, with the same wait and `turn.signal`
+	 * as `describeInTurn`, for each call it holds; a rejection or a timeout leaves the owners alone
+	 * to approve it. Where several rules name approvers for one call, only principals every rule
+	 * names may approve. It must change nothing.
+	 */
+	approversInTurn?(
+		tool: string,
+		input: Record<string, unknown>,
+		context: HoldContext,
+		turn: ToolTurn,
+	): readonly string[] | undefined | Promise<readonly string[] | undefined>;
+	/**
+	 * Whether `approversInTurn` may name approvers for some call of `tool`, for a rule whose answer
+	 * depends on the input. Asked when the input is not known yet, as for a precheck script's call
+	 * whose arguments are computed when it runs; a rule with `approversInTurn` and without this is
+	 * taken to name approvers for every tool.
+	 */
+	mayName?(tool: string): boolean;
 }
 
 /** The description of a call that must be approved first, or undefined to let it run. */
@@ -84,6 +105,19 @@ export type HoldCheck = ((
 		input: Record<string, unknown>,
 		context: HoldContext,
 	): Tier | undefined;
+	/**
+	 * Who may approve the call instead of its speaker, from the rules that name approvers; see
+	 * `HoldRule.approversInTurn`. Absent when no rule has the lookup; it answers at once when every
+	 * rule asked did, and otherwise as a promise that rejects when a rule's does.
+	 */
+	approversInTurn?(
+		tool: string,
+		input: Record<string, unknown>,
+		context: HoldContext,
+		turn: ToolTurn,
+	): readonly string[] | undefined | Promise<readonly string[] | undefined>;
+	/** The name of a rule that may name approvers for some call of `tool` whatever its input; see `HoldRule.mayName`. */
+	mayName?(tool: string): string | undefined;
 };
 
 /** The higher of two tiers; undefined only when both are. */
@@ -140,9 +174,35 @@ export function holdChain(rules: readonly HoldRule[]): HoldCheck {
 				higherTier(tier, rule.approvalTier?.(tool, input, context)),
 			undefined,
 		);
+	if (rules.some((rule) => rule.approversInTurn)) {
+		check.mayName = (tool) =>
+			rules.find(
+				(rule) => rule.approversInTurn && (rule.mayName?.(tool) ?? true),
+			)?.name;
+		check.approversInTurn = (tool, input, context, turn) => {
+			const named = rules.flatMap((rule) => {
+				const approvers = rule.approversInTurn?.(tool, input, context, turn);
+				return approvers === undefined ? [] : [approvers];
+			});
+			if (named.length === 0) return undefined;
+			if (named.some(isPromise))
+				return Promise.all(named).then(commonApprovers);
+			return commonApprovers(named as (readonly string[] | undefined)[]);
+		};
+	}
 	return check;
 }
 
+/** The principals every list names, in the first list's order; undefined when there are no lists. */
+function commonApprovers(
+	lists: readonly (readonly string[] | undefined)[],
+): readonly string[] | undefined {
+	const named = lists.filter((list): list is readonly string[] => !!list);
+	const [first, ...rest] = named;
+	if (!first) return undefined;
+	return first.filter((id) => rest.every((list) => list.includes(id)));
+}
+
 /** Whether a hold's answer comes later. */
 export function isPromise<T>(value: T | Promise<T>): value is Promise<T> {
 	return (

package/src/core/i18n/cards.ts

@@ -14,6 +14,8 @@ export function cardsEn(ctx: CatalogContext) {
 			`-# Who can approve: ${userIds.map((id) => `<@${id}>`).join(" ")}`,
 		cardApproversRefusal:
 			"This approval is for the speaker whose turn asked for it.",
+		cardNamedApproversRefusal:
+			"This approval is for the people it names, and the owners.",
 		cardAskerNote: (...userIds: readonly string[]) =>
 			`-# Who can answer: ${userIds.map((id) => `<@${id}>`).join(" ")}`,
 		cardAskerRefusal: "This question is for another speaker.",
@@ -44,6 +46,7 @@ export function cardsZhTW(ctx: CatalogContext): ReturnType<typeof cardsEn> {
 		cardApproversNote: (...userIds: readonly string[]) =>
 			`-# 可以核准的人：${userIds.map((id) => `<@${id}>`).join(" ")}`,
 		cardApproversRefusal: "這張核准卡是給提出這一輪的發話者的。",
+		cardNamedApproversRefusal: "這張核准卡是給卡片上點名的人和擁有者的。",
 		cardAskerNote: (...userIds: readonly string[]) =>
 			`-# 可以回答的人：${userIds.map((id) => `<@${id}>`).join(" ")}`,
 		cardAskerRefusal: "這張問題是問另一位發話者的。",