pi-roundtable 0.19.2 → 0.21.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;
+		}),
+	};
+}

package/src/core/runtime/ask-questions.ts

@@ -0,0 +1,93 @@
+import { messages } from "../i18n/index.ts";
+import type { OwnerIdentity } from "../identity.ts";
+import type { OwnerAnswer, Prompts } from "../interactions/prompts.ts";
+import {
+	type Questionnaire,
+	SINGLE_QUESTION,
+	shapeFor,
+	validateQuestionnaire,
+} from "../interactions/questionnaire.ts";
+import {
+	answerText,
+	lateAnswerText,
+	lateQuestionnaireText,
+	questionnaireText,
+	sequentialText,
+} from "./extensions/ask-user-text.ts";
+
+/**
+ * Asks a questionnaire on `prompts` and returns the tool's result text. A set the core refuses
+ * posts no card. One question without previews, and a surface without `questionnaire` or with
+ * room for fewer questions, go through `ask`: one question exactly as before 0.20, several one
+ * at a time, stopping at the first that does not come back answered.
+ */
+export async function askQuestions(
+	prompts: Prompts,
+	asker: string,
+	questionnaire: Questionnaire,
+	owner: OwnerIdentity,
+	signal: AbortSignal | undefined,
+): Promise<string> {
+	const refused = validateQuestionnaire(questionnaire);
+	if (refused !== undefined) return refused;
+	const title = messages().askTitle(asker);
+	const n = questionnaire.questions.length;
+	const support = prompts.asks;
+	const previews = questionnaire.questions.some((q) =>
+		q.options.some((o) => o.preview !== undefined),
+	);
+	if (
+		prompts.questionnaire &&
+		support &&
+		support.questions >= n &&
+		(n > 1 || (previews && support.previews))
+	) {
+		const answer = await prompts.questionnaire(
+			title,
+			shapeFor(questionnaire, support),
+			signal,
+			{
+				late: (late) =>
+					late.kind === "questionnaire"
+						? n === 1
+							? lateAnswerText(
+									questionnaire.questions[0]?.question ?? "",
+									late.answer.answers[0] ?? { choices: [] },
+									late.by,
+								)
+							: lateQuestionnaireText(questionnaire, late.answer, late.by)
+						: undefined,
+			},
+		);
+		if (n === 1)
+			return answerText(
+				answer === "pending" || answer === undefined
+					? answer
+					: (answer.answers[0] ?? { choices: [] }),
+				owner,
+			);
+		return questionnaireText(answer, questionnaire, owner);
+	}
+	const shaped = shapeFor(questionnaire, SINGLE_QUESTION);
+	const answers: OwnerAnswer[] = [];
+	for (const [i, question] of shaped.questions.entries()) {
+		const text = questionnaire.questions[i]?.question ?? question.question;
+		const answer = await prompts.ask(title, question, signal, {
+			late: (late) =>
+				late.kind === "question"
+					? lateAnswerText(text, late.answer, late.by)
+					: undefined,
+		});
+		if (n === 1) return answerText(answer, owner);
+		if (answer === "pending" || answer === undefined)
+			return sequentialText(
+				questionnaire,
+				answers,
+				answer === "pending" ? "pending" : "unanswered",
+				owner,
+				answerText(answer, owner),
+			);
+		answers.push(answer);
+	}
+	return sequentialText(questionnaire, answers, undefined, owner, "");
+}

package/src/core/runtime/extensions/ask-user-arguments.ts

@@ -0,0 +1,52 @@
+/** Parses a value a model double-encoded as a JSON string; anything else, or a bad string, comes back as it was. */
+// pi-lens-ignore: no-unknown-returns — this reads untyped model JSON; the tool schema is where it is parsed
+function decoded(value: unknown): unknown {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value) as unknown;
+	} catch {
+		return value;
+	}
+}
+
+/**
+ * The arguments of an `ask_user` call in the `questions` form: a legacy call's top-level
+ * `{ question, options, multi, allow_other }` becomes one question (its `allow_other` stays false
+ * unless set, as before 0.20), and a `questions` or `options` value that arrived as a JSON string
+ * is decoded. Anything else is left for the schema to refuse.
+ */
+// pi-lens-ignore: no-unknown-returns — pi checks the folded arguments against the tool schema right after
+export function foldAskArguments(args: unknown): unknown {
+	if (typeof args !== "object" || args === null || Array.isArray(args))
+		return args;
+	const input = args as Record<string, unknown>;
+	if (input.questions !== undefined && input.question !== undefined)
+		throw new Error(
+			"Use either `questions` or the old top-level `question`, not both.",
+		);
+	if (input.questions === undefined && typeof input.question === "string") {
+		const { question, options, multi, allow_other, ...rest } = input;
+		return {
+			...rest,
+			questions: [
+				{
+					question,
+					...(options !== undefined ? { options: decoded(options) } : {}),
+					...(multi !== undefined ? { multi } : {}),
+					allow_other: allow_other ?? false,
+				},
+			],
+		};
+	}
+	const questions = decoded(input.questions);
+	if (!Array.isArray(questions)) return { ...input, questions };
+	return {
+		...input,
+		questions: questions.map((item: unknown) => {
+			const q = decoded(item);
+			return typeof q === "object" && q !== null && "options" in q
+				? { ...q, options: decoded((q as { options: unknown }).options) }
+				: q;
+		}),
+	};
+}

package/src/core/runtime/extensions/ask-user-text.ts

@@ -0,0 +1,146 @@
+import { type OwnerIdentity, ownerWords, PRONOUNS } from "../../identity.ts";
+import type {
+	OwnerAnswer,
+	OwnerQuestion,
+	Questionnaire,
+	QuestionnaireAnswer,
+} from "../../interactions/prompts.ts";
+
+/** The longest a question's name is when it has no header, in characters. */
+const NAME_CHARS = 120;
+
+/** The tool's result: what the owner chose and wrote. */
+export function answerText(
+	answer: OwnerAnswer | "pending" | undefined,
+	owner: OwnerIdentity,
+): string {
+	const o = ownerWords(owner);
+	if (answer === "pending")
+		return `${o.name} has not answered yet. The card stays open, so do not ask again and do not wait for it. End your turn now: say briefly that you are waiting for ${o.his} answer on the card. When ${o.he} answers, a new turn brings you the answer and you continue from there.`;
+	if (!answer)
+		return `No answer: ${o.name} did not answer. Go on without it if you safely can, otherwise ask in your reply.`;
+	const lines = [
+		...(answer.choices.length > 0
+			? [`${o.name} chose: ${answer.choices.join("; ")}`]
+			: []),
+		...(answer.text !== undefined ? [`${o.name} wrote: ${answer.text}`] : []),
+	];
+	return lines.length > 0 ? lines.join("\n") : `${o.name} chose nothing.`;
+}
+
+/** The turn a late answer starts: the question it answers and what was chosen and written. */
+export function lateAnswerText(
+	question: string,
+	answer: OwnerAnswer,
+	by: string,
+): string {
+	return `(${by} answered your earlier ask_user question on its card, after your turn had ended. Continue from where you stopped, with this answer.)\nQuestion: ${question}\n${answerText(answer, { name: by, pronouns: PRONOUNS.they })}`;
+}
+
+/** How a question is named in a result: its header, else its text cut short. */
+function nameOf(question: OwnerQuestion): string {
+	if (question.header) return question.header;
+	const chars = Array.from(question.question.replace(/\s+/g, " ").trim());
+	return chars.length <= NAME_CHARS
+		? chars.join("")
+		: `${chars.slice(0, NAME_CHARS - 1).join("")}…`;
+}
+
+function lineOf(answer: OwnerAnswer | undefined) {
+	const parts = [
+		...(answer && answer.choices.length > 0
+			? [`chose ${answer.choices.join("; ")}`]
+			: []),
+		...(answer?.text !== undefined ? [`Wrote: ${answer.text}`] : []),
+	];
+	return parts.length > 0 ? parts.join(". ") : "not answered";
+}
+
+/** One numbered line per question, then the note. */
+function listOf(
+	questionnaire: Questionnaire,
+	answer: QuestionnaireAnswer,
+): string[] {
+	return [
+		...questionnaire.questions.map(
+			(question, i) =>
+				`${i + 1}. ${nameOf(question)}: ${lineOf(answer.answers[i])}`,
+		),
+		...(answer.note !== undefined ? [`Note: ${answer.note}`] : []),
+	];
+}
+
+/** The tool's result for a questionnaire: each question's answer, and the note. */
+export function questionnaireText(
+	answer: QuestionnaireAnswer | "pending" | undefined,
+	questionnaire: Questionnaire,
+	owner: OwnerIdentity,
+): string {
+	if (answer === "pending" || !answer) return answerText(answer, owner);
+	return [
+		`${owner.name} answered your questions on the card:`,
+		...listOf(questionnaire, answer),
+	].join("\n");
+}
+
+/** The turn a late questionnaire answer starts: the same list, under a line saying when it came. */
+export function lateQuestionnaireText(
+	questionnaire: Questionnaire,
+	answer: QuestionnaireAnswer,
+	by: string,
+): string {
+	return [
+		`(${by} answered your earlier ask_user questions on their card, after your turn had ended. Continue from where you stopped, with these answers.)`,
+		...listOf(questionnaire, answer),
+	].join("\n");
+}
+
+/**
+ * The result of questions asked one at a time on a surface that takes one: what was answered
+ * before the first that was not (`stopped` says how it ended), and the questions not asked.
+ */
+export function sequentialText(
+	asked: Questionnaire,
+	answers: readonly OwnerAnswer[],
+	stopped: "pending" | "unanswered" | undefined,
+	owner: OwnerIdentity,
+	stoppedText: string,
+): string {
+	const notAsked = asked.questions.slice(
+		answers.length + (stopped === undefined ? 0 : 1),
+	);
+	return [
+		...(answers.length > 0
+			? [
+					`${owner.name} answered your questions on the card:`,
+					...asked.questions
+						.slice(0, answers.length)
+						.map(
+							(question, i) =>
+								`${i + 1}. ${nameOf(question)}: ${lineOf(answers[i])}`,
+						),
+				]
+			: []),
+		...(stopped === undefined
+			? []
+			: [
+					`${
+						asked.questions.length > 1
+							? `${answers.length + 1}. ${nameOf(asked.questions[answers.length] as OwnerQuestion)}: `
+							: ""
+					}${stoppedText}`,
+				]),
+		...(notAsked.length > 0
+			? [
+					`Not asked: ${notAsked
+						.map(
+							(question, i) =>
+								`${answers.length + (stopped === undefined ? 0 : 1) + i + 1}. ${nameOf(question)}`,
+						)
+						.join(
+							"; ",
+						)}; this channel takes one question at a time, so ask again if you still need them.`,
+				]
+			: []),
+	].join("\n");
+}