pi-roundtable 0.19.2 → 0.21.0

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

@@ -5,30 +5,24 @@ import type { ChannelKey } from "../domain/conversation.ts";
 import { messages } from "../i18n/index.ts";
 import type {
 	Approval,
-	OwnerAnswer,
-	OwnerQuestion,
 	PromptScope,
 	Prompts,
-	PromptWait,
 } from "../interactions/prompts.ts";
 import type { Logger } from "../log.ts";
-import {
-	type Audience,
-	type CardAudienceOptions,
-	CardAudiences,
-} from "./card-audience.ts";
+import { type CardAudienceOptions, CardAudiences } from "./card-audience.ts";
 import { CardCopies, copyReply, offeredCopy } from "./card-copies.ts";
 import { DiscordOwners, discordUser } from "./discord-owners.ts";
 import type { InteractionModule } from "./interaction-module.ts";
 import {
-	answeredLine,
-	answerModal,
+	answerDeferred,
+	answerForm,
+	answerSingle,
+	showPreviews,
+} from "./owner-card-answers.ts";
+import { askPrompts } from "./owner-card-asks.ts";
+import {
 	approvalRows,
-	askRows,
 	CARD_PREFIX,
-	OTHER,
-	type Rows,
-	TEXT_FIELD,
 	withdrawnFooter,
 } from "./owner-card-rows.ts";
 import type {
@@ -36,10 +30,11 @@ import type {
 	CardChannel,
 	CardMessage,
 	CardPayload,
+	CardSpec,
 	LateTurn,
 	OpenCard,
 } from "./owner-card-types.ts";
-import { ownerPanel, type PanelContent } from "./owner-panel.ts";
+import { ownerPanel } from "./owner-panel.ts";
 
 export type {
 	CardChannel,
@@ -47,6 +42,7 @@ export type {
 	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;
 
@@ -120,6 +116,12 @@ export class OwnerCards implements InteractionModule {
 	prompts(channel: ChannelKey, scope?: PromptScope): Prompts | undefined {
 		const channelId = parseChannelKey(channel).id;
 		return {
+			...askPrompts({
+				channelId,
+				scope,
+				audiences: this.#audiences,
+				post: (c, s, u, x, card) => this.#post(c, s, u, x, card),
+			}),
 			confirm: async (
 				title,
 				message,
@@ -139,6 +141,7 @@ export class OwnerCards implements InteractionModule {
 					scope,
 					minTier,
 					options?.approvers,
+					options?.speakerOnly === true,
 				);
 				// A private conversation's call above its person's tier is no one's to approve.
 				if (!audience) return "unavailable";
@@ -177,37 +180,6 @@ export class OwnerCards implements InteractionModule {
 					},
 				);
 			},
-			ask: async (title, question, signal, wait) => {
-				const audience = await this.#audiences.question(scope);
-				if (!audience) return undefined;
-				return this.#post<OwnerAnswer | "pending" | undefined>(
-					channelId,
-					signal,
-					undefined,
-					undefined,
-					{
-						audience,
-						...(wait
-							? {
-									wait: {
-										pending: "pending",
-										late: (value, by) =>
-											wait.late({
-												kind: "question",
-												answer: value as OwnerAnswer,
-												by: by.user.name,
-											}),
-									},
-								}
-							: {}),
-						title,
-						sections: [question.question],
-						question,
-						rows: (id, disabled) => askRows(id, question, disabled),
-						footer: messages().cardQuestionFooter,
-					},
-				);
-			},
 		};
 	}
 
@@ -220,28 +192,7 @@ export class OwnerCards implements InteractionModule {
 		signal: AbortSignal | undefined,
 		unposted: T,
 		cancelled: T,
-		card: {
-			audience: Audience;
-			title: string;
-			sections: string[];
-			/** The text behind the card's copy button, kept under the card's id. */
-			copy?: string;
-			/** Closes the card, also after its turn stopped waiting, when it aborts; see `ApprovalOptions.supersede`. */
-			supersede?: AbortSignal;
-			question?: OwnerQuestion;
-			rows(id: string, disabled: boolean): Rows;
-			footer: string;
-			wait?: {
-				pending: T;
-				late(
-					value: unknown,
-					by: Answerer,
-					prompt: string,
-				): ReturnType<PromptWait["late"]>;
-			};
-			/** Hears who approved the card, before it resolves approved in its turn. */
-			approved?(by: Answerer, prompt: string): void;
-		},
+		card: CardSpec<T>,
 	): Promise<T> {
 		const { logger, graceMs = CARD_GRACE_MS, resume } = this.#options;
 		if (signal?.aborted || card.supersede?.aborted)
@@ -279,12 +230,13 @@ export class OwnerCards implements InteractionModule {
 			};
 			const view = (footer: string, disabled = true) =>
 				this.#panel(
-					{
-						title: card.title,
-						sections,
-						rows: card.rows(id, disabled),
-						footer,
-					},
+					card.build?.(id, footer, disabled) ??
+						ownerPanel({
+							title: card.title,
+							sections,
+							rows: card.rows?.(id, disabled) ?? [],
+							footer,
+						}),
 					open.mention === true,
 					card.audience.mentions,
 				);
@@ -297,20 +249,26 @@ export class OwnerCards implements InteractionModule {
 				close(withdrawnFooter(card.supersede));
 				if (!late) resolve(cancelled);
 			};
-			const timer = wait
-				? setTimeout(() => {
-						if (!this.#open.has(id)) return;
-						late = true;
-						signal?.removeEventListener("abort", abort);
-						resolve(wait.pending);
-					}, graceMs)
-				: undefined;
+			const arm = () =>
+				wait
+					? setTimeout(() => {
+							if (!this.#open.has(id)) return;
+							late = true;
+							signal?.removeEventListener("abort", abort);
+							resolve(wait.pending);
+						}, graceMs)
+					: undefined;
+			let timer = arm();
 			signal?.addEventListener("abort", abort, { once: true });
 			card.supersede?.addEventListener("abort", withdraw, { once: true });
 			const open: OpenCard = {
-				title: card.title,
-				sections,
-				rows: (disabled) => card.rows(id, disabled),
+				view,
+				isOpen: () => this.#open.has(id),
+				touch: () => {
+					if (late || !this.#open.has(id)) return;
+					clearTimeout(timer);
+					timer = arm();
+				},
 				audience: card.audience,
 				end: (value, by) => {
 					// Withdrawn or answered already: this answer changes nothing.
@@ -336,6 +294,8 @@ export class OwnerCards implements InteractionModule {
 					return true;
 				},
 				...(card.question ? { question: card.question } : {}),
+				...(card.form ? { form: card.form } : {}),
+				...(card.previews ? { previews: card.previews } : {}),
 			};
 			this.#open.set(id, open);
 			this.#options
@@ -358,11 +318,10 @@ export class OwnerCards implements InteractionModule {
 
 	/** The card's panel; in a thread it leads with the mention of who may answer. */
 	#panel(
-		content: PanelContent,
+		panel: CardPayload,
 		mention: boolean,
 		userIds: readonly string[],
 	): CardPayload {
-		const panel = ownerPanel(content);
 		if (!mention) return panel;
 		return {
 			...panel,
@@ -386,7 +345,7 @@ export class OwnerCards implements InteractionModule {
 			!interaction.customId.startsWith(CARD_PREFIX)
 		)
 			return false;
-		const [id = "", action = ""] = interaction.customId
+		const [id = "", action = "", index = ""] = interaction.customId
 			.slice(CARD_PREFIX.length)
 			.split(":");
 		// Copying answers nothing: anyone who sees the card may copy, as often as they like, also
@@ -408,6 +367,10 @@ export class OwnerCards implements InteractionModule {
 			});
 			return true;
 		}
+		if (action === "previews") {
+			await showPreviews(card, interaction);
+			return true;
+		}
 		const user = discordUser(interaction);
 		const by: Answerer = {
 			user,
@@ -415,6 +378,14 @@ export class OwnerCards implements InteractionModule {
 			...(interaction.guildId ? { guildId: interaction.guildId } : {}),
 			isDirect: !interaction.inGuild(),
 		};
+		// A menu pick or Submit is deferred before the audience is looked up, which may take a while.
+		if (
+			card.form &&
+			(action === "qpick" || action === "submit" || action === "qtext")
+		) {
+			await answerDeferred(card, action, Number(index), interaction, by);
+			return true;
+		}
 		if (!(await card.audience.allows(user))) {
 			await interaction.reply({
 				content: card.audience.refusal,
@@ -422,17 +393,6 @@ export class OwnerCards implements InteractionModule {
 			});
 			return true;
 		}
-		const closed = (outcome: string) =>
-			this.#panel(
-				{
-					title: card.title,
-					sections: card.sections,
-					rows: card.rows(true),
-					footer: outcome,
-				},
-				card.mention === true,
-				card.audience.mentions,
-			);
 		if (interaction.isButton() && (action === "yes" || action === "no")) {
 			const approved = action === "yes";
 			const approver = approved
@@ -457,43 +417,12 @@ export class OwnerCards implements InteractionModule {
 				return true;
 			}
 			await interaction.update(
-				closed(approved ? messages().cardApproved : messages().cardDeclined),
+				card.view(approved ? messages().cardApproved : messages().cardDeclined),
 			);
 			return true;
 		}
-		const question = card.question;
-		if (!question) return true;
-		if (interaction.isButton() && action === "write") {
-			card.picked = [];
-			await interaction.showModal(answerModal(id));
-			return true;
-		}
-		if (interaction.isStringSelectMenu() && action === "pick") {
-			const values = interaction.values;
-			const choices = question.options.flatMap((option, i) =>
-				values.includes(String(i)) ? [option.label] : [],
-			);
-			if (values.includes(OTHER)) {
-				card.picked = choices;
-				await interaction.showModal(answerModal(id));
-				return true;
-			}
-			const answer = { choices };
-			card.end(answer, by);
-			await interaction.update(closed(answeredLine(answer)));
-			return true;
-		}
-		if (interaction.isModalSubmit() && action === "text") {
-			const answer = {
-				choices: card.picked ?? [],
-				text: interaction.fields.getTextInputValue(TEXT_FIELD),
-			};
-			card.end(answer, by);
-			if (interaction.isFromMessage())
-				await interaction.update(closed(answeredLine(answer)));
-			else await interaction.deferUpdate();
-			return true;
-		}
+		if (card.form) await answerForm(card, id, action, interaction);
+		else await answerSingle(card, id, action, interaction, by);
 		return true;
 	}
 }

package/src/core/discord/utf16.ts

@@ -0,0 +1,11 @@
+/**
+ * `text` cut to at most `max` UTF-16 units, the count discord.js validates, without splitting a
+ * surrogate pair; with `ellipsis` the cut ends in `…` inside the limit.
+ */
+export function clip(text: string, max: number, ellipsis = false): string {
+	if (text.length <= max) return text;
+	let end = ellipsis ? max - 1 : max;
+	const last = text.charCodeAt(end - 1);
+	if (last >= 0xd800 && last <= 0xdbff) end -= 1;
+	return ellipsis ? `${text.slice(0, end)}…` : text.slice(0, end);
+}

package/src/core/holds.ts

@@ -19,8 +19,20 @@ export interface HoldContext {
 
 /**
  * What a hold that runs in a turn answers with: the description of the call, or the description
- * as `text` with a `copy` the owner's approval card offers beside it (see `ApprovalDetails.copy`)
- * and a `supersede` signal to withdraw the call by.
+ * as `text` with a `copy` the owner's approval card offers beside it (see `ApprovalDetails.copy`),
+ * a `supersede` signal to withdraw the call by, and `approval: "speaker"` to make the card the
+ * speaker's alone.
+ *
+ * With `approval: "speaker"` only the speaker whose turn made the call may answer its card, on
+ * any of their identities the surface knows and at the call's tier; no owner may answer it as an
+ * owner (an owner who is the speaker answers as the speaker). A speaker below the call's tier, a
+ * turn with no speaker, or a surface that cannot tell who the speaker is gets `unavailable` at
+ * once and the call stays held. Combined with approvers the card is still the speaker's alone,
+ * and the runtime accepts their press only when the approvers name them or they are an owner;
+ * otherwise the call stays held. It governs the card only: a message that confirms the held call
+ * is judged as for any call, so a tool that must act on the speaker's press alone checks
+ * `ToolTurn.approvedPrompt` and `ToolTurn.approvedBy` in `run`. Anything but `"speaker"` leaves
+ * the card as every card is.
  *
  * Aborting `supersede` withdraws the call the hold held, when the plugin no longer wants it
  * (a newer request replaced it, its subject is gone): its approval card is closed, also after
@@ -39,6 +51,7 @@ export type HoldDescription =
 			text: string;
 			copy?: NonNullable<ApprovalDetails["copy"]>;
 			supersede?: AbortSignal;
+			approval?: "speaker";
 	  };
 
 /**

package/src/core/i18n/cards.ts

@@ -1,5 +1,12 @@
 import type { CatalogContext } from "./types.ts";
 
+/** `text` cut to at most 300 UTF-16 units without splitting a surrogate pair. */
+function clip(text: string, max: number): string {
+	if (text.length <= max) return text;
+	const last = text.charCodeAt(max - 1);
+	return text.slice(0, last >= 0xd800 && last <= 0xdbff ? max - 1 : max);
+}
+
 /** The owner's approval and question cards. */
 export function cardsEn(ctx: CatalogContext) {
 	return {
@@ -36,7 +43,19 @@ export function cardsEn(ctx: CatalogContext) {
 		cardModalField: "Your answer",
 		cardQuote: (text: string) => `“${text}”`,
 		cardAnswered: (parts: readonly string[]) =>
-			`Answered: ${parts.join(", ").slice(0, 300)}`,
+			`Answered: ${clip(parts.join(", "), 300)}`,
+		cardPreviewsFile:
+			"The previews contain code blocks, so they are attached as a file.",
+		cardSubmitLabel: "Submit",
+		cardWriteLabel: "Write answers / note…",
+		cardPreviewsLabel: "Previews",
+		cardQuestionName: (n: number) => `Question ${n}`,
+		cardNoteField: "Note on all answers",
+		cardNothingYet: "Choose or write at least one answer first.",
+		cardQuestionnaireFooter: (answered: number, total: number) =>
+			`${answered} of ${total} answered; submit when you are ready.`,
+		cardUnanswered: "not answered",
+		cardNoteLine: (note: string) => `Note: ${note}`,
 	};
 }
 
@@ -71,6 +90,17 @@ export function cardsZhTW(ctx: CatalogContext): ReturnType<typeof cardsEn> {
 		cardModalField: "你的回答",
 		cardQuote: (text: string) => `「${text}」`,
 		cardAnswered: (parts: readonly string[]) =>
-			`已回答：${parts.join("、").slice(0, 300)}`,
+			`已回答：${clip(parts.join("、"), 300)}`,
+		cardPreviewsFile: "預覽裡有程式碼區塊，所以用檔案附上。",
+		cardSubmitLabel: "送出",
+		cardWriteLabel: "寫答案／備註…",
+		cardPreviewsLabel: "預覽",
+		cardQuestionName: (n: number) => `問題 ${n}`,
+		cardNoteField: "給全部答案的備註",
+		cardNothingYet: "請先選或寫至少一個答案。",
+		cardQuestionnaireFooter: (answered: number, total: number) =>
+			`已回答 ${answered}／${total} 題；準備好再送出。`,
+		cardUnanswered: "未回答",
+		cardNoteLine: (note: string) => `備註：${note}`,
 	};
 }

package/src/core/interactions/prompts.ts

@@ -1,6 +1,22 @@
 import type { ConversationVisibility } from "../conversations/conversation-registry.ts";
 import type { TurnRequest } from "../domain/ports.ts";
 import type { Speaker, Tier } from "../speakers.ts";
+import type {
+	AskSupport,
+	OwnerAnswer,
+	OwnerQuestion,
+	Questionnaire,
+	QuestionnaireAnswer,
+} from "./questionnaire.ts";
+
+export type {
+	AskOption,
+	AskSupport,
+	OwnerAnswer,
+	OwnerQuestion,
+	Questionnaire,
+	QuestionnaireAnswer,
+} from "./questionnaire.ts";
 
 /**
  * How a prompt ended: answered yes or no; `expired` when the card was shown and no one answered
@@ -79,6 +95,16 @@ export interface ApprovalOptions {
 	 * conversation an approval it does not name is not accepted for a call that names approvers.
 	 */
 	approvers?: readonly string[];
+	/**
+	 * When true the card is the scope's speaker's alone: they answer it on any of their identities
+	 * the surface knows, at the call's `minTier` checked again when they answer, and the owners do
+	 * not, whatever the scope escalates to. Without a speaker, below the tier, or on a surface that
+	 * cannot tell, it resolves `unavailable` at once. With `approvers`, the speaker's press is
+	 * accepted only if they are named (the runtime refuses the rest). A surface that cannot honour
+	 * it must resolve `unavailable` rather than show the card to the owners. Absent or false leaves
+	 * the card as every card is.
+	 */
+	speakerOnly?: boolean;
 	/**
 	 * Called with who approved the call, before the approval resolves `approved`; not called for a
 	 * refusal, or by a surface that does not know who answered.
@@ -135,6 +161,7 @@ export type LateAnswer = { by: string } & (
 			prompt?: string;
 	  }
 	| { kind: "question"; answer: OwnerAnswer }
+	| { kind: "questionnaire"; answer: QuestionnaireAnswer }
 );
 
 /**
@@ -148,28 +175,6 @@ export interface PromptWait {
 	late(answer: LateAnswer): string | undefined;
 }
 
-export interface AskOption {
-	label: string;
-	description?: string;
-}
-
-export interface OwnerQuestion {
-	question: string;
-	/** Up to 25; none means a free-text answer. */
-	options: readonly AskOption[];
-	/** More than one option may be chosen. */
-	multi: boolean;
-	/** They may write an answer of their own besides the options. */
-	allowOther: boolean;
-}
-
-export interface OwnerAnswer {
-	/** The chosen options' labels, in the order they were offered. */
-	choices: string[];
-	/** What they wrote themselves, if anything. */
-	text?: string;
-}
-
 /**
  * Who may answer a running turn's prompts: the person whose turn asks, and, in a conversation
  * others share, the owners. The runtime makes it from the turn's speaker and the conversation's
@@ -235,6 +240,22 @@ export interface Prompts {
 		signal?: AbortSignal,
 		wait?: PromptWait,
 	): Promise<OwnerAnswer | "pending" | undefined>;
+	/**
+	 * What `questionnaire` can show; absent means the 0.19 contract (one question, no previews,
+	 * no note), and `ask` is the only way to ask.
+	 */
+	asks?: AskSupport;
+	/**
+	 * Asks several questions on one card, shaped for `asks` (see `shapeFor`); the answer is
+	 * index-aligned with the questions. Results are as for `ask`; a late answer is a
+	 * `questionnaire` `LateAnswer`. Present only on a surface that declares `asks`.
+	 */
+	questionnaire?(
+		title: string,
+		questionnaire: Questionnaire,
+		signal?: AbortSignal,
+		wait?: PromptWait,
+	): Promise<QuestionnaireAnswer | "pending" | undefined>;
 }
 
 /** @deprecated Since 0.9 the prompts are `Prompts`, answered by those their `PromptScope` names; this name goes away in 1.0. */