pi-roundtable 0.19.1 → 0.20.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,
@@ -177,37 +179,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 +191,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 +229,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 +248,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 +293,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 +317,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 +344,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 +366,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 +377,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 +392,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 +416,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/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
@@ -135,6 +151,7 @@ export type LateAnswer = { by: string } & (
 			prompt?: string;
 	  }
 	| { kind: "question"; answer: OwnerAnswer }
+	| { kind: "questionnaire"; answer: QuestionnaireAnswer }
 );
 
 /**
@@ -148,28 +165,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 +230,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. */

package/src/core/interactions/questionnaire.ts

@@ -0,0 +1,213 @@
+/** One choice a question offers. */
+export interface AskOption {
+	label: string;
+	description?: string;
+	/** A markdown mock-up or snippet shown beside the option, where the surface can; see `AskSupport.previews`. */
+	preview?: string;
+}
+
+export interface OwnerQuestion {
+	question: string;
+	/** A short name for the question in a set (see `QUESTIONNAIRE_LIMITS.headerChars`); surfaces that take one question drop it. */
+	header?: 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;
+}
+
+/** One to four related questions asked on a single card. */
+export interface Questionnaire {
+	questions: readonly OwnerQuestion[];
+}
+
+/** The answer to a `Questionnaire`: `answers[i]` is for `questions[i]`, undefined when left blank. */
+export interface QuestionnaireAnswer {
+	answers: readonly (OwnerAnswer | undefined)[];
+	/** A note on the whole set, where the surface takes one. */
+	note?: string;
+}
+
+/**
+ * What a surface can show of a questionnaire. A `Prompts` without `asks` is the 0.19 contract:
+ * one question, no previews, no note.
+ */
+export interface AskSupport {
+	/** The most questions one card holds (1 to 4). */
+	questions: number;
+	/** Options may carry a `preview`. */
+	previews: boolean;
+	/** The card takes a note on the whole set. */
+	note: boolean;
+}
+
+export const SINGLE_QUESTION: AskSupport = {
+	questions: 1,
+	previews: false,
+	note: false,
+};
+
+/** Every limit of a questionnaire, one table for the tool schema, the validation and the tests. */
+export const QUESTIONNAIRE_LIMITS = {
+	questions: 4,
+	/** A question's text, alone in a call. */
+	questionChars: 1500,
+	/** Question texts and headers together when a call holds several questions. */
+	setChars: 3000,
+	headerChars: 30,
+	options: 25,
+	labelChars: 100,
+	descriptionChars: 100,
+	/** One option's preview. */
+	previewChars: 1200,
+	/** All previews of a call together. */
+	previewTotalChars: 10000,
+	/** Their own answer to one question, and the note. */
+	answerChars: 1000,
+} as const;
+
+const L = QUESTIONNAIRE_LIMITS;
+
+const pointsOf = (text: string) => Array.from(text).length;
+const units = (text: string) => Math.max(pointsOf(text), text.length);
+
+function duplicate(values: readonly string[]): string | undefined {
+	return values.find((v, i) => values.indexOf(v) !== i);
+}
+
+/** The model-facing reason a questionnaire is refused, or undefined when it is sound. */
+export function validateQuestionnaire(q: Questionnaire): string | undefined {
+	const n = q.questions.length;
+	if (n < 1 || n > L.questions)
+		return `Ask between 1 and ${L.questions} questions in one call (got ${n}).`;
+	const many = n > 1;
+	let setChars = 0;
+	let previews = 0;
+	for (const [i, question] of q.questions.entries()) {
+		const at = many ? `Question ${i + 1}: ` : "";
+		const text = question.question.trim();
+		if (text === "") return `${at}the question is empty.`;
+		if (!many && pointsOf(question.question) > L.questionChars)
+			return `${at}the question is over ${L.questionChars} characters.`;
+		if (
+			question.header !== undefined &&
+			pointsOf(question.header) > L.headerChars
+		)
+			return `${at}the header is over ${L.headerChars} characters.`;
+		// Discord counts UTF-16 units, so an emoji or rare character weighs two here.
+		setChars += units(question.question) + units(question.header ?? "");
+		if (question.options.length > L.options)
+			return `${at}offer at most ${L.options} options.`;
+		for (const option of question.options) {
+			if (option.label.trim() === "") return `${at}an option has no label.`;
+			if (pointsOf(option.label) > L.labelChars)
+				return `${at}an option label is over ${L.labelChars} characters.`;
+			if (pointsOf(option.description ?? "") > L.descriptionChars)
+				return `${at}an option description is over ${L.descriptionChars} characters.`;
+			const preview = pointsOf(option.preview ?? "");
+			if (preview > L.previewChars)
+				return `${at}the preview of "${option.label}" is over ${L.previewChars} characters.`;
+			previews += preview;
+		}
+		const same = duplicate(question.options.map((o) => o.label));
+		if (same !== undefined)
+			return `${at}the option "${same}" is offered twice.`;
+	}
+	if (many && setChars > L.setChars)
+		return `The questions and headers together are over ${L.setChars} characters (an emoji or rare character counts as two); shorten them or ask fewer.`;
+	if (previews > L.previewTotalChars)
+		return `The previews together are over ${L.previewTotalChars} characters.`;
+	const twice = duplicate(q.questions.map((x) => x.question.trim()));
+	if (twice !== undefined) return `The question "${twice}" is asked twice.`;
+	return undefined;
+}
+
+/** Whether an answer is one the question allows: offered labels, one unless multi, own text only where allowed. */
+export function checkAnswer(q: OwnerQuestion, a: OwnerAnswer): boolean {
+	const labels = q.options.map((option) => option.label);
+	const text = a.text?.trim();
+	if (!a.choices.every((choice) => labels.includes(choice))) return false;
+	if (new Set(a.choices).size !== a.choices.length) return false;
+	if (!q.multi && a.choices.length > 1) return false;
+	if (labels.length === 0) return a.choices.length === 0 && Boolean(text);
+	if (text && !q.allowOther) return false;
+	return a.choices.length > 0 || Boolean(text);
+}
+
+/** Whether an answer fits the set: aligned with the questions, each given answer allowed, something given. */
+export function checkQuestionnaireAnswer(
+	q: Questionnaire,
+	a: QuestionnaireAnswer,
+): boolean {
+	if (a.answers.length !== q.questions.length) return false;
+	const note = a.note?.trim();
+	if (a.note !== undefined && pointsOf(a.note) > L.answerChars) return false;
+	let given = Boolean(note);
+	for (const [i, answer] of a.answers.entries()) {
+		const question = q.questions[i];
+		if (answer === undefined || !question) continue;
+		if (!checkAnswer(question, answer)) return false;
+		if (answer.text !== undefined && pointsOf(answer.text) > L.answerChars)
+			return false;
+		given = true;
+	}
+	return given;
+}
+
+/** `text` cut to `max` characters with a closing `…`. */
+function cut(text: string, max: number): string {
+	const chars = Array.from(text);
+	return chars.length <= max ? text : `${chars.slice(0, max - 1).join("")}…`;
+}
+
+/** A fenced block for `body`, its fence longer than any backtick run inside. */
+function fenced(body: string): string {
+	const longest = Math.max(
+		0,
+		...(body.match(/`+/g) ?? []).map((run) => run.length),
+	);
+	const fence = "`".repeat(Math.max(3, longest + 1));
+	return `${fence}\n${body}\n${fence}`;
+}
+
+function foldPreviews(question: OwnerQuestion): OwnerQuestion {
+	if (!question.options.some((o) => o.preview)) return question;
+	const shown = question.options
+		.filter((o) => o.preview)
+		.map((o) => `**${o.label}**\n${fenced(o.preview ?? "")}`);
+	return {
+		...question,
+		question: cut(
+			`${question.question}\n\n${shown.join("\n\n")}`,
+			L.questionChars,
+		),
+		options: question.options.map(({ preview: _preview, ...rest }) => rest),
+	};
+}
+
+/**
+ * The questionnaire a surface with `support` can show; the same questions, in the same order.
+ * A surface without previews gets each preview appended to its question as a fenced block, cut
+ * to the question limit. A surface that takes one question drops the headers. Questions beyond
+ * `support.questions` are not removed here: the runtime asks a surface that takes fewer one
+ * question at a time.
+ */
+export function shapeFor(q: Questionnaire, support: AskSupport): Questionnaire {
+	return {
+		questions: q.questions.map((question) => {
+			const shaped = support.previews ? question : foldPreviews(question);
+			if (support.questions > 1) return shaped;
+			const { header: _header, ...rest } = shaped;
+			return rest;
+		}),
+	};
+}