pi-roundtable 0.14.1 → 0.15.1

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

@@ -1,12 +1,5 @@
 import { randomUUID } from "node:crypto";
-import {
-	ActionRowBuilder,
-	ButtonBuilder,
-	ButtonStyle,
-	type Interaction,
-	MessageFlags,
-	TextDisplayBuilder,
-} from "discord.js";
+import { type Interaction, MessageFlags, TextDisplayBuilder } from "discord.js";
 import { parseChannelKey } from "../contract/surface.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import { messages } from "../i18n/index.ts";
@@ -30,11 +23,13 @@ import type { InteractionModule } from "./interaction-module.ts";
 import {
 	answeredLine,
 	answerModal,
+	approvalRows,
 	askRows,
 	CARD_PREFIX,
 	OTHER,
 	type Rows,
 	TEXT_FIELD,
+	withdrawnFooter,
 } from "./owner-card-rows.ts";
 import type {
 	Answerer,
@@ -158,52 +153,26 @@ export class OwnerCards implements InteractionModule {
 							? {
 									wait: {
 										pending: "pending",
-										late: (value, by) =>
+										late: (value, by, prompt) =>
 											wait.late({
 												kind: "approval",
 												approved: value === "approved",
 												by: by.user.name,
 												...(by.approver ? { approvedBy: by.approver } : {}),
+												prompt,
 											}),
 									},
 								}
 							: {}),
-						...(options?.approvedBy
-							? {
-									approved: (by: Answerer) => {
-										if (by.approver) options.approvedBy?.(by.approver);
-									},
-								}
-							: {}),
+						approved: (by: Answerer, prompt: string) => {
+							if (by.approver) options?.approvedBy?.(by.approver);
+							options?.approvedPrompt?.(prompt);
+						},
 						title,
 						sections: [message],
+						...(options?.supersede ? { supersede: options.supersede } : {}),
 						...(copy ? { copy: copy.text } : {}),
-						rows: (id, disabled) => [
-							new ActionRowBuilder<ButtonBuilder>().addComponents(
-								new ButtonBuilder()
-									.setCustomId(`${CARD_PREFIX}${id}:yes`)
-									.setLabel(messages().cardRunLabel)
-									.setEmoji("✅")
-									.setStyle(ButtonStyle.Success)
-									.setDisabled(disabled),
-								new ButtonBuilder()
-									.setCustomId(`${CARD_PREFIX}${id}:no`)
-									.setLabel(messages().cardCancelLabel)
-									.setEmoji("❌")
-									.setStyle(ButtonStyle.Secondary)
-									.setDisabled(disabled),
-								// Copying answers nothing, so it stays usable once the card has ended.
-								...(copy
-									? [
-											new ButtonBuilder()
-												.setCustomId(`${CARD_PREFIX}${id}:copy`)
-												.setLabel(copy.label)
-												.setEmoji("📋")
-												.setStyle(ButtonStyle.Secondary),
-										]
-									: []),
-							),
-						],
+						rows: (id, disabled) => approvalRows(id, disabled, copy),
 						footer: messages().cardApprovalFooter,
 					},
 				);
@@ -257,19 +226,26 @@ export class OwnerCards implements InteractionModule {
 			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): ReturnType<PromptWait["late"]>;
+				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): void;
+			approved?(by: Answerer, prompt: string): void;
 		},
 	): Promise<T> {
 		const { logger, graceMs = CARD_GRACE_MS, resume } = this.#options;
-		if (signal?.aborted) return Promise.resolve(cancelled);
+		if (signal?.aborted || card.supersede?.aborted)
+			return Promise.resolve(cancelled);
 		const wait = resume ? card.wait : undefined;
 		const id = randomUUID();
 		if (card.copy !== undefined) this.#copies.remember(id, card.copy);
@@ -282,20 +258,23 @@ export class OwnerCards implements InteractionModule {
 			let finish: string | undefined;
 			/** The turn went on without the answer; the card is the conversation's now. */
 			let late = false;
+			/** Shows the card as ended with `footer`, or once it is posted. */
+			const close = (footer: string) => {
+				finish = footer;
+				void message
+					?.edit(view(footer))
+					.catch((error: unknown) =>
+						logger.warn({ channelId, err: error }, "card not closed"),
+					);
+			};
 			const settle = (value: T, outcome: string | undefined) => {
 				if (!this.#open.delete(id)) return;
 				clearTimeout(timer);
 				signal?.removeEventListener("abort", abort);
+				card.supersede?.removeEventListener("abort", withdraw);
 				if (late) return;
 				// A card ended by an answer is edited by the answering interaction.
-				if (outcome !== undefined) {
-					finish = outcome;
-					void message
-						?.edit(view(outcome))
-						.catch((error: unknown) =>
-							logger.warn({ channelId, err: error }, "card not closed"),
-						);
-				}
+				if (outcome !== undefined) close(outcome);
 				resolve(value);
 			};
 			const view = (footer: string, disabled = true) =>
@@ -310,6 +289,14 @@ export class OwnerCards implements InteractionModule {
 					card.audience.mentions,
 				);
 			const abort = () => settle(cancelled, messages().cardStopped);
+			/** The plugin withdrew the call: the card closes, its turn waiting or not, unless an answer came first. */
+			const withdraw = () => {
+				if (!this.#open.delete(id) || !card.supersede) return;
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", abort);
+				close(withdrawnFooter(card.supersede));
+				if (!late) resolve(cancelled);
+			};
 			const timer = wait
 				? setTimeout(() => {
 						if (!this.#open.has(id)) return;
@@ -319,19 +306,22 @@ export class OwnerCards implements InteractionModule {
 					}, graceMs)
 				: undefined;
 			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),
 				audience: card.audience,
 				end: (value, by) => {
+					// Withdrawn or answered already: this answer changes nothing.
+					if (!this.#open.has(id)) return false;
 					const answeredLate = late;
-					if (value === "approved" && !answeredLate) card.approved?.(by);
+					if (value === "approved" && !answeredLate) card.approved?.(by, id);
 					settle(value as T, undefined);
-					if (!answeredLate || !wait || !resume) return;
+					if (!answeredLate || !wait || !resume) return true;
 					try {
-						const text = wait.late(value, by);
-						if (text === undefined) return;
+						const text = wait.late(value, by, id);
+						if (text === undefined) return true;
 						resume({
 							channelId,
 							messageId: by.messageId ?? `card-${id}`,
@@ -343,6 +333,7 @@ export class OwnerCards implements InteractionModule {
 					} catch (error) {
 						logger.warn({ channelId, err: error }, "late card answer lost");
 					}
+					return true;
 				},
 				...(card.question ? { question: card.question } : {}),
 			};
@@ -453,10 +444,18 @@ export class OwnerCards implements InteractionModule {
 						return undefined;
 					})
 				: undefined;
-			card.end(
+			const accepted = card.end(
 				approved ? "approved" : "declined",
 				approver ? { ...by, approver } : by,
 			);
+			// The plugin withdrew the call, or another press answered, while this one was being checked.
+			if (!accepted) {
+				await interaction.reply({
+					content: messages().cardInactive,
+					flags: MessageFlags.Ephemeral,
+				});
+				return true;
+			}
 			await interaction.update(
 				closed(approved ? messages().cardApproved : messages().cardDeclined),
 			);

package/src/core/domain/client.ts

@@ -39,6 +39,13 @@ export interface ClientCallOptions {
 	 * need not pass the turn's signal; the core adds it to every call.
 	 */
 	signal?: AbortSignal;
+	/**
+	 * The approval this call acts on, for a client that must check the person approved it: `prompt`
+	 * is the id of the approval card (`ToolTurn.approvedPrompt`). The transport hands it to the
+	 * client beside the call; a tool passes it only when it has one, so a call without it carries
+	 * no approval. The client, not the core, decides whether it satisfies the function.
+	 */
+	approval?: { prompt: string };
 }
 
 /**

package/src/core/domain/progress.ts

@@ -10,9 +10,15 @@
  * the owner turned down from a call that failed: `declined` on its approval card, `expired` when
  * a card was shown and went unanswered (the call is held for the owner's next message),
  * `pending` while the card stays open, and `held` when no card could be shown (no one may approve
- * it, or it could not be posted; the call waits for the owner's next message). A turn that was stopped is none of these.
+ * it, or it could not be posted; the call waits for the owner's next message), and `withdrawn` when the
+ * plugin that held it withdrew it (`HoldDescription.supersede`). A turn that was stopped is none of these.
  */
-export type HoldRefusal = "declined" | "expired" | "pending" | "held";
+export type HoldRefusal =
+	| "declined"
+	| "expired"
+	| "pending"
+	| "held"
+	| "withdrawn";
 
 export type TurnProgress =
 	| { type: "text"; delta: string }

package/src/core/holds.ts

@@ -19,11 +19,27 @@ 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`.
+ * 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.
+ *
+ * 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
+ * the turn stopped waiting on it, with the abort reason as its footer when that is a text
+ * (`controller.abort("replaced by a newer request")`); the held call is forgotten, so a later
+ * approval, on the card or by message, runs nothing; a turn still waiting on the card is told
+ * the call was withdrawn. An approval that was answered before the abort stands: the call runs
+ * once, or has run. Aborting again, or after the call ran or was answered, does nothing. A
+ * signal that is already aborted when the hold answers refuses the call without a card, and
+ * drops a confirmation of it, which is how a hold withdraws what a restart left held: the
+ * signals do not survive a restart, but a repeated call is described again.
  */
 export type HoldDescription =
 	| string
-	| { text: string; copy?: NonNullable<ApprovalDetails["copy"]> };
+	| {
+			text: string;
+			copy?: NonNullable<ApprovalDetails["copy"]>;
+			supersede?: AbortSignal;
+	  };
 
 /**
  * Decides whether a tool call waits for the owner's approval. A rule answers with a short

package/src/core/i18n/cards.ts

@@ -13,6 +13,7 @@ export function cardsEn(ctx: CatalogContext) {
 			"Nothing runs until you approve; answer whenever you are ready.",
 		cardQuestionFooter: "Answer whenever you are ready.",
 		cardStopped: "⏹️ This round was stopped.",
+		cardWithdrawn: "↩️ Withdrawn; nothing will run.",
 		cardOwnerOnly: `Only ${ctx.assistant}'s owner can answer this card.`,
 		cardApproversNote: (...userIds: readonly string[]) =>
 			`-# Who can approve: ${userIds.map((id) => `<@${id}>`).join(" ")}`,
@@ -23,7 +24,7 @@ export function cardsEn(ctx: CatalogContext) {
 		cardAskerNote: (...userIds: readonly string[]) =>
 			`-# Who can answer: ${userIds.map((id) => `<@${id}>`).join(" ")}`,
 		cardAskerRefusal: "This question is for another speaker.",
-		cardInactive: `This card is no longer valid (${ctx.assistant} restarted since it was posted, or it was already answered); ask again, or reply in text.`,
+		cardInactive: `This card is no longer valid (${ctx.assistant} restarted since it was posted, or it was already answered or withdrawn); ask again, or reply in text.`,
 		cardApproved: "✅ Approved to run.",
 		cardDeclined: "❌ Cancelled.",
 		cardAnswerLabel: "Answer…",
@@ -49,6 +50,7 @@ export function cardsZhTW(ctx: CatalogContext): ReturnType<typeof cardsEn> {
 		cardApprovalFooter: "你核准之前不會執行；準備好再回覆就好。",
 		cardQuestionFooter: "準備好再回答就好。",
 		cardStopped: "⏹️ 這一輪已停止。",
+		cardWithdrawn: "↩️ 已撤回，不會執行。",
 		cardOwnerOnly: `只有 ${ctx.assistant} 的擁有者能回答這張卡片。`,
 		cardApproversNote: (...userIds: readonly string[]) =>
 			`-# 可以核准的人：${userIds.map((id) => `<@${id}>`).join(" ")}`,
@@ -57,7 +59,7 @@ export function cardsZhTW(ctx: CatalogContext): ReturnType<typeof cardsEn> {
 		cardAskerNote: (...userIds: readonly string[]) =>
 			`-# 可以回答的人：${userIds.map((id) => `<@${id}>`).join(" ")}`,
 		cardAskerRefusal: "這張問題是問另一位發話者的。",
-		cardInactive: `這張卡片已經失效（${ctx.assistant} 在它發出後重新啟動過，或它已經回答過了）；請再問一次，或直接打字回覆。`,
+		cardInactive: `這張卡片已經失效（${ctx.assistant} 在它發出後重新啟動過，或它已經回答過或被撤回）；請再問一次，或直接打字回覆。`,
 		cardApproved: "✅ 已核准執行。",
 		cardDeclined: "❌ 已取消。",
 		cardAnswerLabel: "回答…",

package/src/core/interactions/prompts.ts

@@ -84,6 +84,42 @@ export interface ApprovalOptions {
 	 * refusal, or by a surface that does not know who answered.
 	 */
 	approvedBy?(by: ApprovedBy): void;
+	/**
+	 * Called with the id of the card whose approval released the call, right before the approval
+	 * resolves `approved` (after `approvedBy`); not called for a refusal, or by a surface whose
+	 * cards have no stable id. The id is the one the surface shows its people (Discord's card id in
+	 * the custom ids of its buttons, the web chat's `prompt` id), and reaches the tool's `run` as
+	 * `ToolTurn.approvedPrompt`, for a tool that must prove to a client which approval it acts on.
+	 */
+	approvedPrompt?(prompt: string): void;
+	/**
+	 * Aborts when the plugin that caused the call withdraws it (`HoldDescription.supersede`). A
+	 * surface that shows the card closes it then, controls off, with `withdrawalNote(signal)` as
+	 * its footer, also when the turn has stopped waiting and the card stays open; a card already
+	 * answered stays as answered, whichever came first. It resolves `cancelled`, or not at all when
+	 * it already resolved `pending`. A card that arrives with the signal already aborted is not
+	 * shown. A surface that ignores it loses nothing safety-relevant: the gate refuses the
+	 * withdrawn call whatever the card answers.
+	 */
+	supersede?: AbortSignal;
+}
+
+/** The longest footer a withdrawn card shows, in characters. */
+const WITHDRAWAL_NOTE_CHARS = 200;
+
+/**
+ * The footer for a card whose `ApprovalOptions.supersede` aborted: the abort reason when it is a
+ * text (`controller.abort("replaced by a newer request")`), one line cut to a short length, else
+ * `fallback`.
+ */
+export function withdrawalNote(signal: AbortSignal, fallback: string): string {
+	const reason: unknown = signal.reason;
+	if (typeof reason !== "string") return fallback;
+	const line = reason.replace(/\s+/g, " ").trim();
+	if (line === "") return fallback;
+	return line.length > WITHDRAWAL_NOTE_CHARS
+		? `${line.slice(0, WITHDRAWAL_NOTE_CHARS - 1)}…`
+		: line;
 }
 
 /**
@@ -91,7 +127,13 @@ export interface ApprovalOptions {
  * names the approver too, where the surface knows them.
  */
 export type LateAnswer = { by: string } & (
-	| { kind: "approval"; approved: boolean; approvedBy?: ApprovedBy }
+	| {
+			kind: "approval";
+			approved: boolean;
+			approvedBy?: ApprovedBy;
+			/** The id of the card that was answered; see `ApprovalOptions.approvedPrompt`. */
+			prompt?: string;
+	  }
 	| { kind: "question"; answer: OwnerAnswer }
 );
 

package/src/core/runtime/conversation-sessions.ts

@@ -80,6 +80,8 @@ export class ConversationSessions {
 
 	/** Disposes every open session. */
 	dispose(): void {
+		// A withdrawal after this must not touch what a later runtime keeps for the same conversations.
+		for (const gate of this.#gates.values()) gate.abandon();
 		for (const pending of this.#sessions.values()) {
 			void pending
 				.then(({ session }) => session.dispose())
@@ -118,6 +120,19 @@ export class ConversationSessions {
 						: undefined;
 				},
 			);
+			// A plugin's withdrawal of a held call is kept across a restart, unless the conversation was dropped since.
+			const own = gate;
+			gate.onHeldChange = (held) => {
+				if (this.#gates.get(key) !== own) return;
+				this.#options.confirmations
+					.save(key, held)
+					.catch((error: unknown) =>
+						this.#options.logger.error(
+							{ channel: key, err: error },
+							"held actions not saved",
+						),
+					);
+			};
 			this.#gates.set(key, gate);
 			this.#restored.delete(key);
 		}
@@ -295,6 +310,7 @@ export class ConversationSessions {
 		await pending
 			?.then(({ session }) => session.dispose())
 			.catch(() => undefined);
+		this.#gates.get(channel)?.abandon();
 		this.#gates.delete(channel);
 		this.#restored.delete(channel);
 		this.#slots.delete(channel);

package/src/core/runtime/extensions/approval-card.ts

@@ -3,6 +3,8 @@ import { resolve } from "node:path";
 import type { HeldCall } from "../../domain/conversation.ts";
 import { messages } from "../../i18n/index.ts";
 import type { ApprovalDetails } from "../../interactions/prompts.ts";
+import { fieldList, schemaFields } from "./approval-fields.ts";
+import { countPoints, firstPoints, prefix } from "./card-text.ts";
 
 /** The fewest characters of a long string value in a held call's input its approval card keeps, when the input does not fit whole. */
 const CARD_VALUE_CHARS = 200;
@@ -32,21 +34,30 @@ export interface CardLimits {
  * and never below `limits.valueChars`, each marked `… [N chars]` with its original length in code
  * points, until it fits, so one long value does not push the keys after it out of the card. If it
  * still does not fit, the rest is dropped and the keys that are no longer shown are listed.
+ *
+ * With the tool's `parameters` (its JSON Schema), the input is shown as fields instead of JSON:
+ * one per argument in the schema's order, labelled by the property's `title` or its name, a
+ * short value on the line (`**label**: value`, markdown in it escaped), a multi-line or long
+ * string, and JSON for anything nested, in a block that keeps its line breaks. The same limits
+ * apply, the cut values marked the same way and the fields no longer shown listed. A schema that
+ * lists no properties, or none, gives the JSON.
  */
 export function approvalCard(
 	call: HeldCall,
 	workspace?: string,
 	limits: CardLimits = {},
+	parameters?: unknown,
 ): string {
-	const input = shownInput(
-		call.input,
-		limits.valueChars ?? CARD_VALUE_CHARS,
-		limits.totalChars ?? CARD_INPUT_CHARS,
-	);
+	const valueChars = limits.valueChars ?? CARD_VALUE_CHARS;
+	const totalChars = limits.totalChars ?? CARD_INPUT_CHARS;
+	const fields = schemaFields(objectInput(call.input), parameters);
+	const body = fields
+		? fieldList(fields, { valueChars, totalChars })
+		: `\`\`\`json\n${shownInput(call.input, valueChars, totalChars).replaceAll("```", "`\u200b``")}\n\`\`\``;
 	const files = pathFiles(call.input).map(
 		(path) => `\n-# ${messages().cardFile(path, fileSize(path, workspace))}`,
 	);
-	return `**${call.action}**\n-# \`${call.tool}\`\n\`\`\`json\n${input.replaceAll("```", "`\u200b``")}\n\`\`\`${files.join("")}`;
+	return `**${call.action}**\n-# \`${call.tool}\`\n${body}${files.join("")}`;
 }
 
 /** The input as a card shows it within `total` characters; see `approvalCard`. */
@@ -120,34 +131,6 @@ function hiddenKeys(parsed: unknown, limit: number, shown: number): string {
 	return `\n${messages().cardHiddenKeys(names)}`;
 }
 
-/** How many code points `text` has. */
-function countPoints(text: string): number {
-	let points = 0;
-	for (let i = 0; i < text.length; i++) {
-		const code = text.charCodeAt(i);
-		if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) i++;
-		points++;
-	}
-	return points;
-}
-
-/** The first `count` code points of `text`. */
-function firstPoints(text: string, count: number): string {
-	let end = 0;
-	for (let points = 0; points < count && end < text.length; points++) {
-		const code = text.charCodeAt(end);
-		end += code >= 0xd800 && code <= 0xdbff && end + 1 < text.length ? 2 : 1;
-	}
-	return text.slice(0, end);
-}
-
-/** The first `max` characters of `text`, backing off a cut that would split a surrogate pair. */
-function prefix(text: string, max: number): string {
-	if (text.length <= max) return text;
-	const code = text.charCodeAt(max - 1);
-	return text.slice(0, code >= 0xd800 && code <= 0xdbff ? max - 1 : max);
-}
-
 /**
  * A held call as data for a card that is not text: the action, the tool, the whole input, and
  * each file it sends by path with its size now (absent when unreadable), and the `copy` its hold
@@ -173,11 +156,16 @@ export function approvalDetails(
 
 /** A call's input object; `{}` for input that is not one (a held call's always is). */
 function parsedInput(input: string): Record<string, unknown> {
+	return objectInput(input) ?? {};
+}
+
+/** A call's input as an object; undefined for input that is not one. */
+function objectInput(input: string): Record<string, unknown> | undefined {
 	try {
 		const parsed: unknown = JSON.parse(input);
-		return isPlainObject(parsed) ? parsed : {};
+		return isPlainObject(parsed) ? parsed : undefined;
 	} catch {
-		return {};
+		return undefined;
 	}
 }