pi-roundtable 0.10.0 → 0.12.0

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

@@ -24,6 +24,7 @@ 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 {
@@ -75,6 +76,13 @@ export interface OwnerCardsOptions {
 	 * answered. Without it no turn stops waiting on its cards.
 	 */
 	resume?(turn: LateTurn): void;
+	/**
+	 * Where and how long the text behind approval cards' copy buttons is kept. With a `path` it is
+	 * a JSON file that survives a restart; without one the texts live in memory and a card's copy
+	 * button stops working when the process restarts. `keep` (default 100) is how many cards'
+	 * texts, the newest, and `keepDays` (default 30) how long.
+	 */
+	copies?: { path?: string; keep?: number; keepDays?: number };
 }
 
 /**
@@ -91,11 +99,18 @@ export class OwnerCards implements InteractionModule {
 	readonly #options: OwnerCardsOptions;
 	readonly #audiences: CardAudiences;
 	readonly #open = new Map<string, OpenCard>();
+	readonly #copies: CardCopies;
 
 	constructor(options: OwnerCardsOptions) {
 		this.#options = options;
+		this.#copies = new CardCopies({
+			...options.copies,
+			logger: options.logger,
+		});
 		this.#audiences = new CardAudiences(options, new DiscordOwners(options));
 	}
+	/** Resolves once the remembered copy texts are on disk. */
+	flushCopies = (): Promise<void> => this.#copies.flush();
 
 	commands() {
 		return [];
@@ -114,9 +129,15 @@ export class OwnerCards implements InteractionModule {
 				signal,
 				minTier = "owner",
 				wait,
-				_details,
+				details,
 				options,
 			) => {
+				const copy = offeredCopy(details?.copy, (chars) =>
+					this.#options.logger.warn(
+						{ channelId, chars },
+						"card copy text too long; the card has no copy button",
+					),
+				);
 				const audience = await this.#audiences.approval(
 					scope,
 					minTier,
@@ -154,6 +175,7 @@ export class OwnerCards implements InteractionModule {
 							: {}),
 						title,
 						sections: [message],
+						...(copy ? { copy: copy.text } : {}),
 						rows: (id, disabled) => [
 							new ActionRowBuilder<ButtonBuilder>().addComponents(
 								new ButtonBuilder()
@@ -168,6 +190,16 @@ export class OwnerCards implements InteractionModule {
 									.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),
+										]
+									: []),
 							),
 						],
 						footer: messages().cardApprovalFooter,
@@ -221,6 +253,8 @@ export class OwnerCards implements InteractionModule {
 			audience: Audience;
 			title: string;
 			sections: string[];
+			/** The text behind the card's copy button, kept under the card's id. */
+			copy?: string;
 			question?: OwnerQuestion;
 			rows(id: string, disabled: boolean): Rows;
 			footer: string;
@@ -236,6 +270,7 @@ export class OwnerCards implements InteractionModule {
 		if (signal?.aborted) return Promise.resolve(cancelled);
 		const wait = resume ? card.wait : undefined;
 		const id = randomUUID();
+		if (card.copy !== undefined) this.#copies.remember(id, card.copy);
 		const sections = [
 			...card.sections,
 			...(card.audience.note ? [card.audience.note] : []),
@@ -361,6 +396,17 @@ export class OwnerCards implements InteractionModule {
 		const [id = "", action = ""] = interaction.customId
 			.slice(CARD_PREFIX.length)
 			.split(":");
+		// Copying answers nothing: anyone who sees the card may copy, as often as they like, also
+		// once the card has ended or the process restarted.
+		if (interaction.isButton() && action === "copy") {
+			const text = this.#copies.recall(id);
+			await interaction.reply(
+				text === undefined
+					? { content: messages().cardCopyGone, flags: MessageFlags.Ephemeral }
+					: copyReply(text),
+			);
+			return true;
+		}
 		const card = this.#open.get(id);
 		if (!card) {
 			await interaction.reply({

package/src/core/domain/attachment.ts

@@ -19,6 +19,9 @@ export interface AttachmentFailure {
 	fromReference: boolean;
 }
 
+/** The most images one turn carries to the model. */
+export const MAX_TURN_IMAGES = 4;
+
 /** An image in the form the model accepts. */
 export interface ModelImage {
 	data: string;

package/src/core/holds.ts

@@ -1,5 +1,6 @@
 import type { ToolTurn } from "./define.ts";
 import { PluginError } from "./errors.ts";
+import type { ApprovalDetails } from "./interactions/prompts.ts";
 import { type Tier, tierAtLeast } from "./speakers.ts";
 
 /**
@@ -16,6 +17,14 @@ export interface HoldContext {
 	scratchDir?: string;
 }
 
+/**
+ * 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`.
+ */
+export type HoldDescription =
+	| string
+	| { text: string; copy?: NonNullable<ApprovalDetails["copy"]> };
+
 /**
  * Decides whether a tool call waits for the owner's approval. A rule answers with a short
  * description of what the call would do, or undefined when it has no opinion on the call.
@@ -40,14 +49,15 @@ export interface HoldRule {
 	 * when a turn makes the call, and waits for the answer up to `HOLD_DESCRIBE_TIMEOUT_MS`; a
 	 * rejection or a timeout holds the call under a generic description. `turn.signal` aborts when the
 	 * turn stops or the wait ends. `describe` stays what a host without a turn sees, such as a
-	 * precheck script's call, and answers at once.
+	 * precheck script's call, and answers at once. It may answer `{ text, copy }` instead of the
+	 * text alone, for the approval card to offer `copy`; a host that shows no card uses `text`.
 	 */
 	describeInTurn?(
 		tool: string,
 		input: Record<string, unknown>,
 		context: HoldContext,
 		turn: ToolTurn,
-	): string | undefined | Promise<string | undefined>;
+	): HoldDescription | undefined | Promise<HoldDescription | undefined>;
 	/**
 	 * The lowest tier that may approve a call this rule holds, when it is higher than the tool's own:
 	 * for a call that stands for others, such as saving a script whose runs make held calls.
@@ -98,7 +108,7 @@ export type HoldCheck = ((
 		input: Record<string, unknown>,
 		context: HoldContext,
 		turn: ToolTurn,
-	): string | undefined | Promise<string | undefined>;
+	): HoldDescription | undefined | Promise<HoldDescription | undefined>;
 	/** The highest tier any rule requires to approve the call; see `HoldRule.approvalTier`. */
 	approvalTier?(
 		tool: string,
@@ -150,7 +160,7 @@ export function holdChain(rules: readonly HoldRule[]): HoldCheck {
 	check.inTurn = (tool, input, context, turn) => {
 		const ask = (
 			from: number,
-		): string | undefined | Promise<string | undefined> => {
+		): HoldDescription | undefined | Promise<HoldDescription | undefined> => {
 			for (let at = from; at < rules.length; at++) {
 				const rule = rules[at];
 				if (!rule) continue;

package/src/core/i18n/cards.ts

@@ -5,6 +5,10 @@ export function cardsEn(ctx: CatalogContext) {
 	return {
 		cardRunLabel: "Run",
 		cardCancelLabel: "Cancel",
+		cardCopyLabel: "Copy",
+		cardCopyGone:
+			"The text of this card is no longer kept; ask the assistant to show it again.",
+		cardCopyFile: "The text is long, so it is attached as a file.",
 		cardApprovalFooter:
 			"Nothing runs until you approve; answer whenever you are ready.",
 		cardQuestionFooter: "Answer whenever you are ready.",
@@ -39,6 +43,9 @@ export function cardsZhTW(ctx: CatalogContext): ReturnType<typeof cardsEn> {
 	return {
 		cardRunLabel: "執行",
 		cardCancelLabel: "取消",
+		cardCopyLabel: "複製",
+		cardCopyGone: "這張卡片的文字已經不在了；請再請助理顯示一次。",
+		cardCopyFile: "文字比較長，所以用檔案附上。",
 		cardApprovalFooter: "你核准之前不會執行；準備好再回覆就好。",
 		cardQuestionFooter: "準備好再回答就好。",
 		cardStopped: "⏹️ 這一輪已停止。",

package/src/core/interactions/prompts.ts

@@ -35,6 +35,16 @@ export interface ApprovalDetails {
 	input: Record<string, unknown>;
 	/** The files the call sends by path; absent when it sends none. */
 	files?: ApprovalFile[];
+	/**
+	 * A text the card offers to copy, such as a command or a message the call would send. A surface
+	 * that can shows a control, usable by anyone who sees the card, any number of times, that hands
+	 * them `text` (`label` names the control, default the surface's own); using it never answers
+	 * the prompt. It is informational: a surface that cannot show it ignores it. The text is
+	 * visible to anyone who can see the card, so it holds nothing they may not read. A text over
+	 * 20,000 characters is not offered (Discord logs a warning), and a surface with a size limit of
+	 * its own leaves it out before it cuts the call's `input`.
+	 */
+	copy?: { label?: string; text: string };
 }
 
 /**

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

@@ -150,12 +150,13 @@ function prefix(text: string, max: number): string {
 
 /**
  * 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). Unlike the text card,
- * nothing is cut and nothing is worded for a locale.
+ * each file it sends by path with its size now (absent when unreadable), and the `copy` its hold
+ * offered. Unlike the text card, nothing is cut and nothing is worded for a locale.
  */
 export function approvalDetails(
 	call: HeldCall,
 	workspace?: string,
+	copy?: ApprovalDetails["copy"],
 ): ApprovalDetails {
 	const files = pathFiles(call.input).map((path) => {
 		const bytes = fileSize(path, workspace);
@@ -166,6 +167,7 @@ export function approvalDetails(
 		tool: call.tool,
 		input: parsedInput(call.input),
 		...(files.length > 0 ? { files } : {}),
+		...(copy ? { copy } : {}),
 	};
 }
 

package/src/core/runtime/extensions/confirmation-gate.ts

@@ -39,6 +39,7 @@ import {
 	awaited,
 	type Described,
 	type HoldTurn,
+	type Judgment,
 	joinApprovers,
 	STOPPED,
 } from "./hold-lookups.ts";
@@ -284,7 +285,7 @@ export class ConfirmationGate {
 			ask.signal,
 			higherTier(this.#tiers?.minTier(call.tool), call.minTier),
 			{ late: (late) => this.#late(call, late) },
-			approvalDetails(call, this.#fileRoot),
+			approvalDetails(call, this.#fileRoot, needing.copy),
 			options,
 		);
 		if (answer === "approved") {
@@ -361,7 +362,7 @@ export class ConfirmationGate {
 		if (!turn || !inTurn) return this.#needing(tool, input);
 		const controller = new AbortController();
 		if (turn.signal?.aborted) controller.abort();
-		let answer: string | undefined | Promise<string | undefined>;
+		let answer: ReturnType<NonNullable<HoldCheck["inTurn"]>>;
 		try {
 			answer = inTurn.call(
 				this.#holds,
@@ -373,7 +374,7 @@ export class ConfirmationGate {
 		} catch {
 			answer = messages().holdGeneric(tool);
 		}
-		const described: Described | Promise<Described> = isPromise(answer)
+		const found: Described | Promise<Described> = isPromise(answer)
 			? awaited(
 					answer,
 					messages().holdGeneric(tool),
@@ -384,7 +385,7 @@ export class ConfirmationGate {
 			: answer;
 		return this.#inOrder(
 			joinApprovers(
-				described,
+				found,
 				{
 					holds: this.#holds,
 					context: this.#context,
@@ -431,7 +432,7 @@ export class ConfirmationGate {
 	#unlessApproved(
 		tool: string,
 		input: Record<string, unknown>,
-		judged: { action: string; approvers?: readonly string[] },
+		judged: Judgment,
 	): Needing {
 		const minTier = this.#holds.approvalTier?.(tool, input, this.#context);
 		const call: HeldCall = {
@@ -448,7 +449,7 @@ export class ConfirmationGate {
 			const [spent] = approved === -1 ? [] : released.splice(approved, 1);
 			if (spent) return { released: spent.by };
 		}
-		return { held: call };
+		return { held: call, ...(judged.copy ? { copy: judged.copy } : {}) };
 	}
 
 	/** Records the call as held and returns what the model is told about it. */

package/src/core/runtime/extensions/gate-refusals.ts

@@ -3,7 +3,10 @@ import type {
 	PendingConfirmation,
 } from "../../domain/conversation.ts";
 import { type OwnerIdentity, ownerWords } from "../../identity.ts";
-import type { ApprovedBy } from "../../interactions/prompts.ts";
+import type {
+	ApprovalDetails,
+	ApprovedBy,
+} from "../../interactions/prompts.ts";
 import type { Speaker } from "../../speakers.ts";
 import { mayApproveNamed } from "./held-calls.ts";
 
@@ -23,7 +26,9 @@ export interface Release {
 }
 
 /** What a call needs of the gate: nothing, a hold, or a release that spends an approval. */
-export type Needing = { held: HeldCall } | { released: ApprovedBy | undefined };
+export type Needing =
+	| { held: HeldCall; copy?: NonNullable<ApprovalDetails["copy"]> }
+	| { released: ApprovedBy | undefined };
 
 /** The text for a held call that the speaker's own message confirms. */
 export function askSpeaker(addressee: OwnerIdentity, call: HeldCall): string {

package/src/core/runtime/extensions/hold-lookups.ts

@@ -1,5 +1,12 @@
 import type { ToolTurn } from "../../define.ts";
-import { type HoldCheck, type HoldContext, isPromise } from "../../holds.ts";
+import {
+	type HoldCheck,
+	type HoldContext,
+	type HoldDescription,
+	isPromise,
+} from "../../holds.ts";
+import { messages } from "../../i18n/index.ts";
+import type { ApprovalDetails } from "../../interactions/prompts.ts";
 
 /** The turn a hold that looks things up sees; see `HoldRule.describeInTurn`. */
 export interface HoldTurn {
@@ -13,13 +20,48 @@ export interface HoldTurn {
 export const STOPPED = Symbol("stopped");
 
 /** What waiting for a call's description comes to: its text, or the turn stopped first. */
-export type Described = string | undefined | typeof STOPPED;
+export type Described = HoldDescription | undefined | typeof STOPPED;
 
-/** A held call's description with who may approve it instead of the speaker; see `HoldRule.approversInTurn`. */
-export type Judged =
-	| { action: string; approvers?: readonly string[] }
-	| undefined
-	| typeof STOPPED;
+/**
+ * A held call's description, the text its card offers to copy, and who may approve it instead of
+ * the speaker; see `HoldRule.approversInTurn`.
+ */
+export interface Judgment {
+	action: string;
+	copy?: NonNullable<ApprovalDetails["copy"]>;
+	approvers?: readonly string[];
+}
+
+export type Judged = Judgment | undefined | typeof STOPPED;
+
+/**
+ * A hold's description as the action and the copy it carries. An answer that is neither a text
+ * nor a text with a copy still holds the call, under the generic description; a copy that is not
+ * a non-empty text is left out, so a hold that gets it wrong never lets the call run.
+ */
+export function described(
+	answer: HoldDescription,
+	tool: string,
+): { action: string; copy?: NonNullable<ApprovalDetails["copy"]> } {
+	if (typeof answer === "string") return { action: answer };
+	if (typeof answer !== "object" || answer === null)
+		return { action: messages().holdGeneric(tool) };
+	const { text, copy } = answer;
+	if (typeof text !== "string") return { action: messages().holdGeneric(tool) };
+	if (
+		!copy ||
+		typeof copy !== "object" ||
+		typeof copy.text !== "string" ||
+		copy.text === ""
+	)
+		return { action: text };
+	const label = typeof copy.label === "string" ? copy.label : undefined;
+	return {
+		action: text,
+		copy:
+			label === undefined ? { text: copy.text } : { label, text: copy.text },
+	};
+}
 
 /**
  * What a lookup that answers later comes to: its answer; `fallback` when it rejects or outlasts
@@ -58,16 +100,17 @@ export function awaited<T>(
  * none, so only the owners approve the call. A call no rule holds asks no one.
  */
 export function joinApprovers(
-	described: Described | Promise<Described>,
+	answer: Described | Promise<Described>,
 	from: { holds: HoldCheck; context: HoldContext; timeoutMs: number },
 	tool: string,
 	input: Record<string, unknown>,
 	turn: HoldTurn,
 ): Judged | Promise<Judged> {
 	const lookup = from.holds.approversInTurn;
-	if (!lookup) return withoutApprovers(described);
+	if (!lookup) return withoutApprovers(answer, tool);
 	const join = (action: Described): Judged | Promise<Judged> => {
 		if (action === STOPPED || action === undefined) return action;
+		const { action: text, copy } = described(action, tool);
 		const controller = new AbortController();
 		if (turn.signal?.aborted) controller.abort();
 		let named:
@@ -87,22 +130,31 @@ export function joinApprovers(
 		}
 		if (!isPromise(named)) {
 			controller.abort();
-			return named ? { action, approvers: named } : { action };
+			return {
+				action: text,
+				...(copy ? { copy } : {}),
+				...(named ? { approvers: named } : {}),
+			};
 		}
 		return awaited(named, [], controller, turn.signal, from.timeoutMs).then(
 			(approvers) => {
 				if (approvers === STOPPED) return STOPPED;
-				return approvers ? { action, approvers } : { action };
+				return {
+					action: text,
+					...(copy ? { copy } : {}),
+					...(approvers ? { approvers } : {}),
+				};
 			},
 		);
 	};
-	return isPromise(described) ? described.then(join) : join(described);
+	return isPromise(answer) ? answer.then(join) : join(answer);
 }
 
 function withoutApprovers(
-	described: Described | Promise<Described>,
+	answer: Described | Promise<Described>,
+	tool: string,
 ): Judged | Promise<Judged> {
-	const wrap = (action: Described): Judged =>
-		action === STOPPED || action === undefined ? action : { action };
-	return isPromise(described) ? described.then(wrap) : wrap(described);
+	const wrap = (found: Described): Judged =>
+		found === STOPPED || found === undefined ? found : described(found, tool);
+	return isPromise(answer) ? answer.then(wrap) : wrap(answer);
 }

package/src/discord/index.ts

@@ -6,10 +6,15 @@ export { DISCORD } from "../core/builtin/discord.ts";
 export type { DiscordAdapterConfig } from "../core/config/config.ts";
 export type {
 	ChannelContext,
+	ChannelContextAttachment,
+	ChannelContextAttachmentOptions,
 	ChannelContextMessage,
 	ChannelContextOptions,
 } from "../core/contract/channel-context.ts";
-export { withChannelContext } from "../core/contract/channel-context.ts";
+export {
+	withChannelContext,
+	withChannelContextImages,
+} from "../core/contract/channel-context.ts";
 export type { AgentPanelMessage } from "../core/discord/agent-commands.ts";
 export type {
 	AgentPanel,

package/src/index.ts

@@ -147,7 +147,12 @@ export {
 	PluginError,
 	ProviderError,
 } from "./core/errors.ts";
-export type { HoldCheck, HoldContext, HoldRule } from "./core/holds.ts";
+export type {
+	HoldCheck,
+	HoldContext,
+	HoldDescription,
+	HoldRule,
+} from "./core/holds.ts";
 export type { HostEnvironment, RoundtableOptions } from "./core/host.ts";
 export { Roundtable } from "./core/host.ts";
 export type {