pi-roundtable 0.14.1 → 0.15.1

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