pi-roundtable 0.14.0 → 0.15.0

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;
 	}
 }
 

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

@@ -0,0 +1,212 @@
+import { messages } from "../../i18n/index.ts";
+import { countPoints, firstPoints } from "./card-text.ts";
+
+/** The longest label a card shows for a field, in code points. */
+const LABEL_CHARS = 40;
+
+/** A one-line string longer than this goes in a block of its own, as does any with a line break. */
+const INLINE_CHARS = 100;
+
+/** How many hidden labels a card lists. */
+const HIDDEN_LABELS = 20;
+
+/** One argument of a held call as a card shows it. */
+export interface CardField {
+	label: string;
+	/** An argument the schema does not list: its name is shown in code format, so it reads as a name the tool never declared. */
+	extra?: true;
+	// pi-lens-ignore: no-unknown-parameters — a tool's argument is untyped model JSON
+	value: unknown;
+}
+
+/** What the fields of a card may take up; see `fieldList`. */
+export interface FieldLimits {
+	/** The fewest code points of a long string kept when the fields do not fit whole. */
+	valueChars: number;
+	/** The most characters the field list takes up. */
+	totalChars: number;
+}
+
+// pi-lens-ignore: no-unknown-parameters — a tool's parameter schema is untyped JSON
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * The arguments of a call in the order its tool's parameter schema lists them, each labelled by
+ * its property's `title` or else its name; absent arguments are left out, and an argument the
+ * schema does not list follows the listed ones under its own name in code format. Undefined when the schema
+ * lists no properties, or the call has no arguments to show.
+ */
+export function schemaFields(
+	input: Record<string, unknown> | undefined,
+	// pi-lens-ignore: no-unknown-parameters — a tool's parameter schema is untyped JSON
+	schema: unknown,
+): CardField[] | undefined {
+	if (!input || !isRecord(schema) || !isRecord(schema.properties))
+		return undefined;
+	const properties = schema.properties;
+	const fields: CardField[] = [];
+	// Own properties only: a name like `toString` or `constructor` is not the prototype's.
+	for (const [name, property] of Object.entries(properties)) {
+		if (!Object.hasOwn(input, name)) continue;
+		const value = input[name];
+		if (value === undefined) continue;
+		const title =
+			isRecord(property) && typeof property.title === "string"
+				? property.title.trim()
+				: "";
+		fields.push({ label: title || name, value });
+	}
+	for (const [name, value] of Object.entries(input))
+		if (value !== undefined && !Object.hasOwn(properties, name))
+			fields.push({ label: name, value, extra: true });
+	return fields.length > 0 ? fields : undefined;
+}
+
+/**
+ * The fields as the lines of a card, within `limits.totalChars`: a long string is cut, the
+ * longest first and never below `limits.valueChars`, and marked `… [N chars]` with its length in
+ * code points. If that is not enough the last fields are dropped and their labels listed, so a
+ * card never hides that it shows less than the call carries.
+ */
+export function fieldList(fields: CardField[], limits: FieldLimits): string {
+	const render = (limit: number, among: CardField[] = fields) =>
+		among.map((field) => fieldLines(field, limit)).join("\n");
+	const whole = render(Number.POSITIVE_INFINITY);
+	if (whole.length <= limits.totalChars) return whole;
+	let limit = limits.valueChars;
+	if (render(limit).length <= limits.totalChars) {
+		// The largest limit that still fits: the longest values give up characters first.
+		let low = limit;
+		let high = Math.max(low, longestValue(fields) - 1);
+		while (low < high) {
+			const mid = Math.ceil((low + high) / 2);
+			if (render(mid).length <= limits.totalChars) low = mid;
+			else high = mid - 1;
+		}
+		limit = low;
+		return render(limit);
+	}
+	// At least the first field stays, cut as far as the limit allows.
+	const shown: CardField[] = [];
+	let size = 0;
+	for (const field of fields) {
+		const lines = fieldLines(field, limit);
+		if (shown.length > 0 && size + lines.length + 1 > limits.totalChars) break;
+		shown.push(field);
+		size += lines.length + 1;
+	}
+	const hidden = fields.slice(shown.length);
+	const labels = hidden.slice(0, HIDDEN_LABELS).map(labelText);
+	if (hidden.length > HIDDEN_LABELS) labels.push("…");
+	return `${render(limit, shown)}\n${messages().cardHiddenKeys(labels)}`;
+}
+
+/** The code points in the longest string a field carries. */
+function longestValue(fields: CardField[]): number {
+	let longest = 0;
+	for (const field of fields) {
+		const text = textOf(field.value);
+		if (text !== undefined) longest = Math.max(longest, countPoints(text));
+	}
+	return longest;
+}
+
+/** The line-break characters a model can put in a string besides `\n`, made `\n` before a value is laid out. */
+const LINE_BREAKS = /\r\n?|\u2028|\u2029|\u0085/g;
+
+const lines = (text: string): string => text.replace(LINE_BREAKS, "\n");
+
+/** Whether a string shows nothing: empty, or only white space and zero-width characters. */
+const isInvisible = (text: string): boolean =>
+	/^[\s\u00ad\u061c\u180e\u200b-\u200f\u202a-\u202e\u2060-\u2064\ufeff]*$/.test(
+		text,
+	);
+
+/** `text` written with every character that is not printable ASCII escaped, so nothing in it is invisible. */
+function visible(text: string): string {
+	return JSON.stringify(text).replace(
+		/[^\x20-\x7e]/g,
+		(char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`,
+	);
+}
+
+/**
+ * The text a field's value is shown as, or undefined for a number, a boolean or null, which are
+ * never cut: a string as it is, an array of such scalars joined, anything else as compact JSON.
+ */
+// pi-lens-ignore: no-unknown-parameters — a tool's argument is untyped model JSON
+function textOf(value: unknown): string | undefined {
+	if (typeof value === "string") return lines(value);
+	if (value === null || typeof value === "number" || typeof value === "boolean")
+		return undefined;
+	if (Array.isArray(value) && value.every(isScalarText))
+		return value.map((item) => String(item)).join(", ");
+	return JSON.stringify(value);
+}
+
+/** Whether an array item reads unambiguously in a comma-joined line: not a string that is empty, invisible, has a comma and space, or a line break. */
+// pi-lens-ignore: no-unknown-parameters — a tool's argument is untyped model JSON
+function isScalarText(item: unknown): boolean {
+	if (typeof item === "string")
+		return (
+			!isInvisible(item) &&
+			!item.includes(", ") &&
+			lines(item) === item &&
+			!item.includes("\n")
+		);
+	return item === null || typeof item === "number" || typeof item === "boolean";
+}
+
+/** The label of a field as a card shows it: its title or name made safe, or a name the schema did not list in code format. */
+function labelText(field: CardField): string {
+	const label = firstPoints(lines(field.label), LABEL_CHARS);
+	if (field.extra)
+		return `\`${label.replace(/\s*\n\s*/g, " ").replaceAll("`", "'")}\``;
+	return inline(label);
+}
+
+const labelOf = (field: CardField): string => `**${labelText(field)}**`;
+
+/** One field as the lines of a card; strings over `limit` code points are cut and marked. */
+function fieldLines(field: CardField, limit: number): string {
+	const label = labelOf(field);
+	const text = textOf(field.value);
+	if (text === undefined) return `${label}: ${String(field.value)}`;
+	const points = countPoints(text);
+	const cut = points > limit;
+	const shown = cut ? firstPoints(text, limit) : text;
+	const note = cut ? `… [${points} chars]` : "";
+	// A string that shows nothing is written out, so the person sees it is there.
+	if (typeof field.value === "string" && isInvisible(shown))
+		return `${label}: \`${visible(shown)}\`${note}`;
+	const structured = typeof field.value !== "string" && !isScalarArray(field);
+	if (structured)
+		return shown.length + note.length <= INLINE_CHARS && !shown.includes("`")
+			? `${label}: \`${shown}\`${note}`
+			: `${label}:\n${fenced(`${shown}${note}`, "json")}`;
+	return shown.includes("\n") || points > INLINE_CHARS
+		? `${label}:\n${fenced(`${shown}${note}`)}`
+		: `${label}: ${inline(shown)}${note}`;
+}
+
+function isScalarArray(field: CardField): boolean {
+	return Array.isArray(field.value) && field.value.every(isScalarText);
+}
+
+/** `text` in a fenced block, which keeps its line breaks and in which nothing is markdown. */
+function fenced(text: string, language = ""): string {
+	return `\`\`\`${language}\n${text.replaceAll("```", "`\u200b``")}\n\`\`\``;
+}
+
+/**
+ * `text` made safe to put inside a line of Discord markdown: nothing in it formats, links or
+ * mentions anyone, and a line break becomes a space. An `@` stays, so an address reads as written.
+ */
+function inline(text: string): string {
+	return text
+		.replace(/\s*\n\s*/g, " ")
+		.replace(/[\\*_~`|[\]<>]/g, "\\$&")
+		.replace(/@(?=everyone|here)/g, "@\u200b");
+}

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

@@ -0,0 +1,74 @@
+import type {
+	Approval,
+	ApprovalDetails,
+	ApprovalOptions,
+	ApprovedBy,
+	Prompts,
+	PromptWait,
+} from "../../interactions/prompts.ts";
+import type { Tier } from "../../speakers.ts";
+import type { Watch } from "./withdrawals.ts";
+
+/** What a held call's card is opened with. */
+export interface CardAsk {
+	title: string;
+	message: string;
+	signal: AbortSignal | undefined;
+	minTier: Tier | undefined;
+	wait: PromptWait;
+	details: ApprovalDetails;
+	approvers: readonly string[] | undefined;
+	/** The call's watch, when its plugin may withdraw it. */
+	watch: Watch | undefined;
+}
+
+/** How a card came out: its answer, or `withdrawn` when the plugin took the call back first, and who approved it on which card. */
+export interface CardAnswer {
+	answer: Approval | "withdrawn";
+	approvedBy?: ApprovedBy;
+	approvedPrompt?: string;
+}
+
+/**
+ * Opens the card and waits for the first of its answer and the plugin's withdrawal of the call;
+ * the other changes nothing. A card that fails answers nothing, so its watch ends and the
+ * failure goes on.
+ */
+export async function askOnCard(
+	prompts: Prompts,
+	ask: CardAsk,
+): Promise<CardAnswer> {
+	const found: Omit<CardAnswer, "answer"> = {};
+	const options: ApprovalOptions = {
+		...(ask.approvers ? { approvers: ask.approvers } : {}),
+		approvedBy: (by) => {
+			found.approvedBy = by;
+		},
+		approvedPrompt: (prompt) => {
+			found.approvedPrompt = prompt;
+		},
+		...(ask.watch ? { supersede: ask.watch.signal } : {}),
+	};
+	try {
+		const asking = prompts.confirm(
+			ask.title,
+			ask.message,
+			ask.signal,
+			ask.minTier,
+			ask.wait,
+			ask.details,
+			options,
+		);
+		// What the surface reports is read after the answer, never before it.
+		if (!ask.watch) {
+			const answer = await asking;
+			return { ...found, answer };
+		}
+		asking.catch(() => undefined);
+		const answer = await Promise.race([asking, ask.watch.whenWithdrawn]);
+		return { ...found, answer };
+	} catch (error) {
+		ask.watch?.end();
+		throw error;
+	}
+}

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

@@ -0,0 +1,27 @@
+/** How many code points `text` has. */
+export 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`. */
+export 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. */
+export 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);
+}

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

@@ -26,6 +26,9 @@ export function confirmationGateExtension(
 			};
 		});
 		pi.on("tool_call", async (event, ctx) => {
+			// A tool call id the model reused must not inherit an earlier call's approval.
+			gate.finish(event.toolCallId);
+			approved.delete(event.toolCallId);
 			const prompts = slot?.prompts;
 			let ask: Parameters<ConfirmationGate["review"]>[2];
 			if (prompts && slot) {
@@ -35,14 +38,22 @@ export function confirmationGateExtension(
 			const turn: HoldTurn | undefined = turnOf
 				? { toolTurn: turnOf, ...(ctx.signal ? { signal: ctx.signal } : {}) }
 				: undefined;
-			const { reason, approvedOnCard, approvedBy, refused } = await gate.decide(
-				event.toolName,
-				event.input as Record<string, unknown>,
-				ask,
-				turn,
-			);
+			const { reason, approvedOnCard, approvedBy, approvedPrompt, refused } =
+				await gate.decide(
+					event.toolName,
+					event.input as Record<string, unknown>,
+					ask,
+					turn,
+					// A host that gives no tool list shows the call as JSON.
+					pi.getAllTools?.().find((tool) => tool.name === event.toolName)
+						?.parameters,
+				);
 			if (approvedOnCard) approved.add(event.toolCallId);
-			if (approvedBy && !reason) gate.grant(event.toolCallId, approvedBy);
+			if (!reason && (approvedBy || approvedPrompt))
+				gate.grant(event.toolCallId, {
+					...(approvedBy ? { by: approvedBy } : {}),
+					...(approvedPrompt ? { prompt: approvedPrompt } : {}),
+				});
 			if (refused) slot?.refuse(event.toolCallId, refused);
 			return reason ? { block: true, reason } : undefined;
 		});