pi-roundtable 0.19.1 → 0.20.0

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

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

@@ -1,40 +1,16 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { messages } from "../../i18n/index.ts";
-import { type OwnerIdentity, ownerWords, PRONOUNS } from "../../identity.ts";
-import type { OwnerAnswer, OwnerQuestion } from "../../interactions/prompts.ts";
+import { type Static, Type } from "typebox";
+import { type OwnerIdentity, ownerWords } from "../../identity.ts";
+import type { OwnerQuestion } from "../../interactions/prompts.ts";
+import { QUESTIONNAIRE_LIMITS as L } from "../../interactions/questionnaire.ts";
 import { toolText } from "../../shared/tool-result.ts";
+import { askQuestions } from "../ask-questions.ts";
 import type { PromptSlot } from "../prompt-slot.ts";
+import { foldAskArguments } from "./ask-user-arguments.ts";
 
-export const ASK_USER_TOOL = "ask_user";
-
-/** 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.`;
-}
+export { answerText, lateAnswerText } from "./ask-user-text.ts";
 
-/** 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 })}`;
-}
+export const ASK_USER_TOOL = "ask_user";
 
 /** Registers ask_user, which asks the owner on a card in the turn's channel and waits. */
 export function askUserExtension(
@@ -45,36 +21,68 @@ export function askUserExtension(
 ): ExtensionFactory {
 	const o = ownerWords(owner);
 	return (pi) => {
+		const parameters = Type.Object(
+			{
+				questions: Type.Array(
+					Type.Object(
+						{
+							question: Type.String({
+								minLength: 1,
+								maxLength: L.questionChars,
+							}),
+							header: Type.Optional(
+								Type.String({
+									maxLength: L.headerChars,
+									description: "A short name for the question in a set.",
+								}),
+							),
+							options: Type.Optional(
+								Type.Array(
+									Type.Object(
+										{
+											label: Type.String({
+												minLength: 1,
+												maxLength: L.labelChars,
+											}),
+											description: Type.Optional(
+												Type.String({ maxLength: L.descriptionChars }),
+											),
+											preview: Type.Optional(
+												Type.String({
+													maxLength: L.previewChars,
+													description:
+														"A markdown mock-up or snippet shown with the option.",
+												}),
+											),
+										},
+										{ additionalProperties: false },
+									),
+									{ maxItems: L.options },
+								),
+							),
+							multi: Type.Optional(
+								Type.Boolean({ description: "Several options may be chosen." }),
+							),
+							allow_other: Type.Optional(
+								Type.Boolean({
+									description: `${o.He} may write an answer besides the options (default true; false for a closed choice).`,
+								}),
+							),
+						},
+						{ additionalProperties: false },
+					),
+					{ minItems: 1, maxItems: L.questions },
+				),
+			},
+			{ additionalProperties: false },
+		);
 		pi.registerTool({
 			name: ASK_USER_TOOL,
 			label: `Ask ${o.name}`,
-			description: `Ask ${o.name} a question on a card with buttons in this channel and wait for ${o.his} answer, within this turn. Use it when you need ${o.his} decision to continue, instead of ending your turn with a question. The card should read on its own, so put the context ${o.he} needs in the question too. Offer options when the choices are known; set multi when several may apply and allow_other to let ${o.him} write ${o.his} own answer. If ${o.he} does not answer soon, the result says so and the card stays open: then end your turn saying you are waiting, and ${o.his} answer comes in a new turn.`,
-			parameters: Type.Object(
-				{
-					question: Type.String({ minLength: 1, maxLength: 1500 }),
-					options: Type.Optional(
-						Type.Array(
-							Type.Object(
-								{
-									label: Type.String({ minLength: 1, maxLength: 100 }),
-									description: Type.Optional(Type.String({ maxLength: 100 })),
-								},
-								{ additionalProperties: false },
-							),
-							{ maxItems: 25 },
-						),
-					),
-					multi: Type.Optional(
-						Type.Boolean({ description: "Several options may be chosen." }),
-					),
-					allow_other: Type.Optional(
-						Type.Boolean({
-							description: `${o.He} may write an answer besides the options.`,
-						}),
-					),
-				},
-				{ additionalProperties: false },
-			),
+			description: `Ask ${o.name} a question, or up to four related ones, on a card with buttons in this channel and wait for ${o.his} answer, within this turn. Use it when you need ${o.his} decision to continue, instead of ending your turn with a question. The card should read on its own, so put the context ${o.he} needs in the question too. Put every question you have into one call as questions. Offer options when the choices are known, each with a short description, and a preview (markdown) when seeing the option helps; set multi when several may apply, and allow_other to false for a closed choice (otherwise ${o.he} may write ${o.his} own answer). Give each question a short header when you ask several. If ${o.he} does not answer soon, the result says so and the card stays open: then end your turn saying you are waiting, and ${o.his} answer comes in a new turn.`,
+			parameters,
+			prepareArguments: (args) =>
+				foldAskArguments(args) as Static<typeof parameters>,
 			execute: async (_toolCallId, params, signal) => {
 				const prompts = slot.prompts;
 				if (!prompts)
@@ -82,31 +90,29 @@ export function askUserExtension(
 						`${o.name} cannot answer buttons in this turn, such as a schedule's. Ask ${o.him} in your reply instead.`,
 					);
 				const p = params as {
-					question: string;
-					options?: { label: string; description?: string }[];
-					multi?: boolean;
-					allow_other?: boolean;
-				};
-				const question: OwnerQuestion = {
-					question: p.question,
-					options: p.options ?? [],
-					multi: p.multi === true,
-					allowOther: p.allow_other === true,
+					questions: {
+						question: string;
+						header?: string;
+						options?: OwnerQuestion["options"];
+						multi?: boolean;
+						allow_other?: boolean;
+					}[];
 				};
 				return toolText(
-					answerText(
-						await prompts.ask(
-							messages().askTitle(slot.asker),
-							question,
-							signal,
-							{
-								late: (late) =>
-									late.kind === "question"
-										? lateAnswerText(p.question, late.answer, late.by)
-										: undefined,
-							},
-						),
+					await askQuestions(
+						prompts,
+						slot.asker,
+						{
+							questions: p.questions.map((q) => ({
+								question: q.question,
+								...(q.header !== undefined ? { header: q.header } : {}),
+								options: q.options ?? [],
+								multi: q.multi === true,
+								allowOther: q.allow_other !== false,
+							})),
+						},
 						addressee?.() ?? owner,
+						signal,
 					),
 				);
 			},

package/src/core/runtime/prompt-slot.ts

@@ -1,6 +1,11 @@
 import type { HoldRefusal } from "../domain/progress.ts";
 import { assistantName } from "../i18n/index.ts";
-import type { OwnerQuestion, Prompts } from "../interactions/prompts.ts";
+import type {
+	OwnerQuestion,
+	Prompts,
+	PromptWait,
+	Questionnaire,
+} from "../interactions/prompts.ts";
 import { turnBudget } from "./turn-budget.ts";
 
 /**
@@ -61,7 +66,22 @@ export class PromptSlot {
 	get prompts(): Prompts | undefined {
 		const prompts = this.#prompts;
 		if (!prompts) return undefined;
+		const { questionnaire } = prompts;
 		return {
+			...(prompts.asks && questionnaire
+				? {
+						asks: prompts.asks,
+						questionnaire: (
+							title: string,
+							asked: Questionnaire,
+							signal?: AbortSignal,
+							wait?: PromptWait,
+						) =>
+							this.#waiting(() =>
+								questionnaire.call(prompts, title, asked, signal, wait),
+							),
+					}
+				: {}),
 			confirm: (title, message, signal, minTier, wait, details, options) =>
 				this.#waiting(() =>
 					prompts.confirm(