pi-roundtable 0.19.2 → 0.21.0

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/extensions/card-ask.ts

@@ -18,6 +18,8 @@ export interface CardAsk {
 	wait: PromptWait;
 	details: ApprovalDetails;
 	approvers: readonly string[] | undefined;
+	/** Only the speaker may answer the card; see `HoldDescription`. */
+	speakerOnly: boolean;
 	/** The call's watch, when its plugin may withdraw it. */
 	watch: Watch | undefined;
 }
@@ -41,6 +43,7 @@ export async function askOnCard(
 	const found: Omit<CardAnswer, "answer"> = {};
 	const options: ApprovalOptions = {
 		...(ask.approvers ? { approvers: ask.approvers } : {}),
+		...(ask.speakerOnly ? { speakerOnly: true } : {}),
 		approvedBy: (by) => {
 			found.approvedBy = by;
 		},

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

@@ -334,6 +334,7 @@ export class ConfirmationGate {
 				wait: { late: (late) => this.#late(call, late, watch) },
 				details: approvalDetails(call, this.#fileRoot, needing.copy),
 				approvers: call.approverIds,
+				speakerOnly: needing.speakerOnly === true,
 				watch,
 			},
 		);
@@ -446,6 +447,7 @@ export class ConfirmationGate {
 			held: call,
 			...(judged.copy ? { copy: judged.copy } : {}),
 			...(judged.supersede ? { supersede: judged.supersede } : {}),
+			...(judged.speakerOnly ? { speakerOnly: judged.speakerOnly } : {}),
 		};
 	}
 

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

@@ -34,6 +34,8 @@ export type Needing =
 			copy?: NonNullable<ApprovalDetails["copy"]>;
 			/** Aborts when the plugin withdraws the call; see `HoldDescription`. */
 			supersede?: AbortSignal;
+			/** The card is the speaker's alone; see `HoldDescription`. */
+			speakerOnly?: true;
 	  }
 	| { released: Release };
 

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

@@ -32,6 +32,8 @@ export interface Judgment {
 	/** Aborts when the plugin withdraws the call; see `HoldDescription`. */
 	supersede?: AbortSignal;
 	approvers?: readonly string[];
+	/** The card is the speaker's alone; see `HoldDescription`. */
+	speakerOnly?: true;
 }
 
 export type Judged = Judgment | undefined | typeof STOPPED;
@@ -55,13 +57,16 @@ function isSignal(value: unknown): value is AbortSignal {
 export function described(
 	answer: HoldDescription,
 	tool: string,
-): Pick<Judgment, "action" | "copy" | "supersede"> {
+): Pick<Judgment, "action" | "copy" | "supersede" | "speakerOnly"> {
 	if (typeof answer === "string") return { action: answer };
 	if (typeof answer !== "object" || answer === null)
 		return { action: messages().holdGeneric(tool) };
-	const { text, copy, supersede } = answer;
+	const { text, copy, supersede, approval } = answer;
 	if (typeof text !== "string") return { action: messages().holdGeneric(tool) };
-	const withdrawal = isSignal(supersede) ? { supersede } : {};
+	const withdrawal = {
+		...(isSignal(supersede) ? { supersede } : {}),
+		...(approval === "speaker" ? { speakerOnly: true as const } : {}),
+	};
 	if (
 		!copy ||
 		typeof copy !== "object" ||
@@ -125,7 +130,12 @@ export function joinApprovers(
 	if (!lookup) return withoutApprovers(answer, tool);
 	const join = (action: Described): Judged | Promise<Judged> => {
 		if (action === STOPPED || action === undefined) return action;
-		const { action: text, copy, supersede } = described(action, tool);
+		const {
+			action: text,
+			copy,
+			supersede,
+			speakerOnly,
+		} = described(action, tool);
 		const controller = new AbortController();
 		if (turn.signal?.aborted) controller.abort();
 		let named:
@@ -149,6 +159,7 @@ export function joinApprovers(
 				action: text,
 				...(copy ? { copy } : {}),
 				...(supersede ? { supersede } : {}),
+				...(speakerOnly ? { speakerOnly } : {}),
 				...(named ? { approvers: named } : {}),
 			};
 		}
@@ -159,6 +170,7 @@ export function joinApprovers(
 					action: text,
 					...(copy ? { copy } : {}),
 					...(supersede ? { supersede } : {}),
+					...(speakerOnly ? { speakerOnly } : {}),
 					...(approvers ? { approvers } : {}),
 				};
 			},

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(

package/src/core/testing/surface-contract-questionnaire.ts

@@ -0,0 +1,192 @@
+import { describe, test } from "bun:test";
+import {
+	type AskSupport,
+	type Questionnaire,
+	type QuestionnaireAnswer,
+	shapeFor,
+} from "../interactions/questionnaire.ts";
+import type { SurfaceContractSubject } from "./surface-contract.ts";
+import {
+	ContractBroken,
+	expectThat,
+	nextPrompt,
+	type Running,
+	runCheck,
+	scopeOf,
+	seen,
+	until,
+} from "./surface-contract-support.ts";
+
+/** One check of the questionnaire part of the surface contract. */
+export interface QuestionnaireCheck {
+	name: string;
+	applies(subject: SurfaceContractSubject): boolean;
+	run(running: Running): Promise<void>;
+}
+
+/** The set the checks ask: two questions, the first with previews where the surface shows them. */
+function contractSet(asks: AskSupport): Questionnaire {
+	const preview = asks.previews ? { preview: "```\nlayout\n```" } : {};
+	const day = {
+		question: "Which day?",
+		header: "Day",
+		options: [
+			{ label: "Saturday", ...preview },
+			{ label: "Sunday", ...preview },
+		],
+		multi: false,
+		allowOther: true,
+	};
+	const food = {
+		question: "Which food?",
+		options: [{ label: "Rice" }, { label: "Noodles" }],
+		multi: true,
+		allowOther: false,
+	};
+	return shapeFor(
+		{ questions: asks.questions >= 2 ? [day, food] : [day] },
+		asks,
+	);
+}
+
+/** The person's prompts, once the surface has started; undefined where it declares no `asks`. */
+function questionnairePrompts(running: Running) {
+	const { surface, channel } = running.subject;
+	const prompts = surface.prompts?.(channel, scopeOf(running.subject));
+	if (!prompts?.asks || !prompts.questionnaire)
+		throw new ContractBroken(
+			"the subject answers questionnaires, but its prompts declare no asks",
+		);
+	return { prompts, asks: prompts.asks, ask: prompts.questionnaire };
+}
+
+const answerOf = (
+	set: Questionnaire,
+	asks: AskSupport,
+): QuestionnaireAnswer => ({
+	answers: set.questions.map((_, i) =>
+		i === 0 ? { choices: ["Sunday"] } : undefined,
+	),
+	...(asks.note ? { note: "thanks" } : {}),
+});
+
+const applies = (subject: SurfaceContractSubject) =>
+	subject.surface.prompts !== undefined &&
+	subject.answerQuestionnaire !== undefined;
+
+/**
+ * The questionnaire checks. They apply to a subject that gives `answerQuestionnaire`, which must declare `asks`;
+ * a surface that takes one question at a time gives none and is skipped.
+ */
+export const QUESTIONNAIRE_CHECKS: readonly QuestionnaireCheck[] = [
+	{
+		name: "a questionnaire resolves as the person answers it, keeps a blank question blank, and closes",
+		applies,
+		run: async (running) => {
+			const found = questionnairePrompts(running);
+			const answer = running.subject.answerQuestionnaire;
+			if (!answer) return;
+			const set = contractSet(found.asks);
+			const before = seen(running, "prompt").length;
+			const result = found.ask("Questions", set);
+			const id = await nextPrompt(running, before);
+			const given = answerOf(set, found.asks);
+			await answer(id, given, set);
+			const got = await result;
+			if (got === "pending" || got === undefined)
+				throw new ContractBroken(`the person's answers came back ${got}`);
+			expectThat(
+				JSON.stringify(got.answers.map((a) => a ?? null)) ===
+					JSON.stringify(given.answers.map((a) => a ?? null)),
+				`the answers came back as ${JSON.stringify(got.answers)}`,
+			);
+			expectThat(
+				got.note === given.note,
+				`the note came back as ${JSON.stringify(got.note)}`,
+			);
+			await until(
+				() =>
+					seen(running, "prompt_closed").some(
+						(o) => o.kind === "prompt_closed" && o.id === id,
+					),
+				"the answered questionnaire closes",
+			);
+		},
+	},
+	{
+		name: "a stopped turn's questionnaire resolves with no answer and closes",
+		applies,
+		run: async (running) => {
+			const found = questionnairePrompts(running);
+			const stop = new AbortController();
+			const before = seen(running, "prompt").length;
+			const result = found.ask(
+				"Questions",
+				contractSet(found.asks),
+				stop.signal,
+			);
+			const id = await nextPrompt(running, before);
+			stop.abort();
+			const got = await result;
+			expectThat(
+				got === undefined,
+				`a stopped turn's questionnaire got ${got}`,
+			);
+			await until(
+				() =>
+					seen(running, "prompt_closed").some(
+						(o) => o.kind === "prompt_closed" && o.id === id,
+					),
+				"the stopped questionnaire closes",
+			);
+		},
+	},
+	{
+		name: "another person cannot answer the person's questionnaire",
+		applies: (subject) =>
+			applies(subject) && subject.stranger?.answerQuestionnaire !== undefined,
+		run: async (running) => {
+			const found = questionnairePrompts(running);
+			const stranger = running.subject.stranger;
+			const answer = running.subject.answerQuestionnaire;
+			if (!answer || !stranger?.answerQuestionnaire) return;
+			await stranger.join?.();
+			const set = contractSet(found.asks);
+			const before = seen(running, "prompt").length;
+			let settled: unknown;
+			const result = found.ask("Questions", set).then((value) => {
+				settled = value;
+				return value;
+			});
+			const id = await nextPrompt(running, before);
+			await stranger.answerQuestionnaire(id, answerOf(set, found.asks), set);
+			await Bun.sleep(50);
+			expectThat(
+				settled === undefined,
+				"another person's answer settled the questionnaire",
+			);
+			await answer(id, answerOf(set, found.asks), set);
+			const own = await result;
+			expectThat(
+				own !== "pending" && own !== undefined,
+				`the person's answer came back ${own}`,
+			);
+		},
+	},
+];
+
+/**
+ * Registers only the questionnaire part of the contract, for a card layer without a chat around
+ * it. Internal: the published contract is `describeSurfaceContract`.
+ */
+export function describeQuestionnaireContract(
+	name: string,
+	make: () => Promise<SurfaceContractSubject>,
+): void {
+	describe(`${name} keeps the questionnaire contract`, () => {
+		for (const check of QUESTIONNAIRE_CHECKS)
+			test(check.name, async () => {
+				await runCheck(check, make);
+			});
+	});
+}

package/src/core/testing/surface-contract-support.ts

@@ -95,6 +95,7 @@ export async function answeredOnlyByThem(
 	other: SurfaceContractAnswerer | undefined,
 	visibility: "private" | "shared",
 	approvers?: readonly string[],
+	speakerOnly = false,
 ): Promise<void> {
 	const { surface, channel, answer } = running.subject;
 	const prompts = surface.prompts?.(
@@ -114,7 +115,12 @@ export async function answeredOnlyByThem(
 			speakerOf(running.subject).tier,
 			undefined,
 			undefined,
-			approvers ? { approvers } : undefined,
+			approvers || speakerOnly
+				? {
+						...(approvers ? { approvers } : {}),
+						...(speakerOnly ? { speakerOnly } : {}),
+					}
+				: undefined,
 		)
 		.then((value) => {
 			settled = value;
@@ -192,3 +198,25 @@ export async function namedApproverAnswers(running: Running): Promise<void> {
 		`the approval reported ${reported?.principalId} as its approver, not ${approver.principalId}`,
 	);
 }
+
+/** Runs one check on a fresh subject from `make`, starting and stopping its surface around it. */
+export async function runCheck(
+	check: {
+		applies?(subject: SurfaceContractSubject): boolean;
+		run(running: Running): Promise<void>;
+	},
+	make: () => Promise<SurfaceContractSubject>,
+): Promise<"passed" | "skipped"> {
+	const subject = await make();
+	const running: Running = { subject, delivered: [] };
+	try {
+		if (check.applies && !check.applies(subject)) return "skipped";
+		await subject.surface.start((message) => running.delivered.push(message));
+		await subject.join?.();
+		await check.run(running);
+		return "passed";
+	} finally {
+		await subject.close?.();
+		await subject.surface.stop?.();
+	}
+}