pi-roundtable-webchat 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-10-18
+
+### Added
+
+- Questionnaires: `ready.prompts` advertises them, a client that sees it may send `prompt_features`, and a `questionnaire` prompt is sent only to connections that declared support covering it. The client answers with a new `answers` frame (`bad_frame` for a malformed or non-fitting answer, `forbidden` from another person). The protocol name and `ready.protocol` stay v1, so old clients and old servers keep working; a person whose tabs have not declared is asked one question at a time. A questionnaire that no open connection can show (the declaring tab closed or narrowed its declaration, or none was connected) waits 60 seconds for one to declare, then expires so the model is told it went unanswered and a re-ask uses the one-question fallback. The public `ClientFrame`, `ServerFrame` and `PromptFrame` types gain `answers`, `prompt_features`, `kind: "questionnaire"` and `ready.prompts`, so a TypeScript client that switches exhaustively on `kind` needs a new case. This needs `pi-roundtable` 0.20.
+
+### Changed
+
+- An `answer` is checked by the core's shared `checkAnswer`; its behaviour is unchanged.
+
+## [0.19.2] - 2026-10-18
+
+- Release in lockstep with pi-roundtable 0.19.2. The core peer range stays `>=0.19.0 <0.20.0`.
+
 ## [0.19.1] - 2026-10-18
 
 - Release in lockstep with pi-roundtable 0.19.1. The core peer range stays `>=0.19.0 <0.20.0`.

package/README.md

@@ -224,6 +224,8 @@ The TypeScript types are `ClientFrame` and `ServerFrame`.
 | `{ type: "stop", conversation }` | Stops the conversation's running turn. |
 | `{ type: "approval", prompt, approved }` | Approves or declines an approval prompt. |
 | `{ type: "answer", prompt, choices, text? }` | Answers a question prompt: the chosen options' labels, and your own text where the question allows it. |
+| `{ type: "answers", prompt, answers, note? }` | Answers a `questionnaire` prompt: `answers` has one entry per question in order, each `{ choices, text? }` as for `answer`, or `null` for a question left blank (at least one answer or a `note` is needed); `note` is a note on the whole set. See [Questionnaires](#questionnaires). |
+| `{ type: "prompt_features", ask }` | Declares what this connection can show of a questionnaire: `ask` is `{ questions, previews, note }` (`questions` 1 to 4). Send it only after a `ready` that has `prompts`; a server before 0.20 would refuse it as `bad_frame`. A connection that never declares is never sent a `questionnaire` prompt. |
 | `{ type: "auth", token }` | A fresh token for the same person, sent after `reauth`. |
 | `{ type: "client_hello", version: 1, tools }` | Declares the functions this connection can run for the assistant's tools, such as reading the page the person has open: up to 64 names, each lowercase words joined by underscores. Send it after each `ready`. See [Client calls](#client-calls). |
 | `{ type: "client_result", call, ok: true, value, parts? }` or `{ type: "client_result", call, ok: false, code, message? }` | The answer to a `client_call`: the JSON `value` and how many binary `parts` were uploaded first, or a failure `code` (`refused`, `failed`, `timeout`, or `stopped`) with a short `message`. |
@@ -232,14 +234,14 @@ The TypeScript types are `ClientFrame` and `ServerFrame`.
 
 | Frame | Meaning |
 |---|---|
-| `{ type: "ready", protocol, speaker, personas, attachments, clientCalls, expiresAt }` | Sent first, and again after a fresh token: who you are (`{ id, name, tier, principalId }`), the personas you may open (`{ kind, label }`), what an upload may be (`attachments`: `{ maxBytes, perMessage, types }`), what a client call may take (`clientCalls`, below; absent from a server before 0.9.11, which never sends calls), and when the token expires. Open prompts follow it. |
+| `{ type: "ready", protocol, speaker, personas, attachments, clientCalls, prompts?, expiresAt }` | Sent first, and again after a fresh token: who you are (`{ id, name, tier, principalId }`), the personas you may open (`{ kind, label }`), what an upload may be (`attachments`: `{ maxBytes, perMessage, types }`), what a client call may take (`clientCalls`, below; absent from a server before 0.9.11, which never sends calls), what questionnaires it can send (`prompts`: `{ ask: { questions, previews, note } }`; absent from a server before 0.20, so send no `prompt_features` then), and when the token expires. Open prompts follow it; a `questionnaire` follows only to a connection that already declared (on a reauth `ready`), and a fresh connection gets it after its `prompt_features`. |
 | `{ type: "accepted", id, conversation }` | Your message `id` was taken into `conversation`, a new one when you named none. |
 | `{ type: "typing", conversation, on }` | The assistant is, or is no longer, working in the conversation. |
 | `{ type: "stoppable", conversation, on }` | A stop applies, or no longer applies. |
 | `{ type: "progress", conversation, event }` | What the running turn writes and which tools it runs: `{ type: "text", delta }`, `{ type: "tool_start", id, tool, preview? }`, or `{ type: "tool_end", id, tool, ok, refused? }`. Never the thinking, never a tool's full arguments. A `tool_end` that a hold refused (not a real failure) has `ok: false` and `refused`: `declined` (turned down on its approval card), `expired` (a card was shown and went unanswered; the call is held for the next message), `pending` (the card is still open), `withdrawn` (the plugin that held the call took it back) or `held` (no card could be shown: the person's tier is below the call's, or it could not be posted; the call is held for the next message). `refused` is absent for a success and for a real failure. |
 | `{ type: "reply", conversation, text, thinking?, files? }` | The turn's answer in full markdown, with its files inline as `{ name, data }` (base64). |
 | `{ type: "failed", conversation, stopped }` | The turn ended without an answer: it failed, the host refused it before it ran (for example when its conversation could not be recorded), or it was stopped. The cause stays in the host's log. |
-| `{ type: "prompt", conversation, prompt }` | The turn asks you: `{ id, kind: "approval", title, message, approval? }`, or `{ id, kind: "ask", title, question, options, multi, allowOther }`. |
+| `{ type: "prompt", conversation, prompt }` | The turn asks you: `{ id, kind: "approval", title, message, approval? }`, `{ id, kind: "ask", title, question, options, multi, allowOther }`, or `{ id, kind: "questionnaire", title, questions }` (only to connections that declared `prompt_features`; see [Questionnaires](#questionnaires)). |
 | `{ type: "prompt_closed", conversation, prompt, outcome, note? }` | The prompt closed: `approved`, `declined`, `answered`, `expired`, `cancelled` (the turn stopped), or `withdrawn` (the plugin that asked took the approval back; `note` may carry its reason in a few words). |
 | `{ type: "notice", notice: { id, text, createdAt, readAt } }` | A durable private inbox entry; `readAt` is `null` until read. Fetch the REST inbox to recover entries missed while offline. |
 | `{ type: "reauth", expiresAt }` | Your token expires soon: send `auth` with a fresh one. |
@@ -263,7 +265,7 @@ approval?: {
 
 The frame's size is bounded: when `approval` serialized as UTF-8 JSON would pass 256 KiB (`APPROVAL_MAX_BYTES` in `protocol.ts`), every string value of `input` longer than what fits is cut to its start plus `… [N chars]` (N counts code points; a cut never splits a surrogate pair) and `approval.truncated` is `true`. Then `input` is no longer whole: show `message`, or tell the person it is cut. If even the shortest cut cannot fit, `input` is `{}` and `files` are left out.
 
-Error codes: `bad_frame` (it does not parse, its text is blank or too long, or an answer the question does not allow), `unknown_conversation`, `forbidden` (someone else's conversation or prompt, or an approval above your tier), `unknown_persona` (none of that kind you may open), `unknown_prompt`, `too_many_conversations` (you hold `unusedConversationsPerPrincipal` conversations you have not written in, or opened `newConversationsPerHour` in the last hour), `unknown_attachment` (a `send` named a file that is not waiting for you in that conversation: never uploaded, uploaded to another conversation, already used by a message, or deleted after its time; the whole message is refused and nothing is run), `attachment_quota` (the files would take what your messages keep past `usedAttachmentBytesPerPrincipal`; the whole message is refused and the files stay waiting), `unknown_call` (a `client_result` named a call that is not open on this connection: it ended, was answered already, or was sent to another connection), and `busy` (you have `turnsPerPrincipal` turns running or queued, or the conversation already has a turn queued behind its running one; the message was not taken, so send it again once a turn ends).
+Error codes: `bad_frame` (it does not parse, its text is blank or too long, or an `answer` or `answers` the question does not allow), `unknown_conversation`, `forbidden` (someone else's conversation or prompt, or an approval above your tier), `unknown_persona` (none of that kind you may open), `unknown_prompt`, `too_many_conversations` (you hold `unusedConversationsPerPrincipal` conversations you have not written in, or opened `newConversationsPerHour` in the last hour), `unknown_attachment` (a `send` named a file that is not waiting for you in that conversation: never uploaded, uploaded to another conversation, already used by a message, or deleted after its time; the whole message is refused and nothing is run), `attachment_quota` (the files would take what your messages keep past `usedAttachmentBytesPerPrincipal`; the whole message is refused and the files stay waiting), `unknown_call` (a `client_result` named a call that is not open on this connection: it ended, was answered already, or was sent to another connection), and `busy` (you have `turnsPerPrincipal` turns running or queued, or the conversation already has a turn queued behind its running one; the message was not taken, so send it again once a turn ends).
 
 Close codes: `4401` when the token expired without a fresh `auth`, or a fresh one was refused; `4403` when the person is no longer admitted, or a fresh token names someone else.
 The host's own limits close with `1008` (too many frames), `1009` (a frame too big), and `1006` (a client that stopped reading).
@@ -336,6 +338,18 @@ This needs a pi-roundtable release that has `attachments.retention`; on an earli
 Uploads are as private as the transcript: files sit in the host's data directory under the private conversation, where the owner and the operator can read them, as they can the transcript.
 Only the person who uploaded a file can use it, and only in the conversation it was uploaded to; a shared conversation (one recorded for no one in particular) takes no uploads.
 
+## Questionnaires
+
+A turn may ask up to four related questions on one card. The protocol name and `ready.protocol` stay `roundtable.webchat.v1`; the change is additive:
+
+1. A server from 0.20 adds `prompts: { ask: { questions: 4, previews: true, note: true } }` to `ready`. A client that sees it may send `prompt_features` with what it can show. A client that does not see it sends nothing new.
+2. The server sends a `prompt` with `kind: "questionnaire"`, `title`, and `questions` (each `{ question, header?, options, multi, allowOther }`, an option being `{ label, description?, preview? }`), **only to connections that declared support covering it**. A client that never declared never receives one, while connected, after a reconnect, or beside a tab that did declare. On a reconnect the open questionnaire is sent after the declaration, not with the other open prompts.
+3. What the assistant may ask is the least of the person's declaring tabs. When no tab declared, the assistant asks one question at a time through the `ask` prompt, as before.
+4. The client answers with `answers`. `bad_frame` for a frame that does not parse or an answer the questions do not allow, `forbidden` from someone other than the conversation's person.
+5. A questionnaire that no open connection can show settles `expired` (a `prompt_closed` to the connections it was sent to) after 60 seconds without a covering declaration: it settles unanswered, the model is told, and if it asks again it gets the one-at-a-time fallback.
+
+A client must ignore a prompt `kind` it does not know.
+
 ## Client calls
 
 A tool may need something only the person's own client can do, such as a browser extension reading the page they have open.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-webchat",
-	"version": "0.19.1",
+	"version": "0.20.0",
 	"description": "A WebSocket chat adapter for pi-roundtable: private web conversations for people an OpenID Connect provider signs in, with live progress and approval cards",
 	"type": "module",
 	"license": "MIT",
@@ -38,14 +38,14 @@
 		"jose": "6.2.12"
 	},
 	"peerDependencies": {
-		"pi-roundtable": ">=0.19.0 <0.20.0"
+		"pi-roundtable": ">=0.20.0 <0.21.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.15",
 		"@earendil-works/pi-ai": ">=1.0.0 <2",
 		"@earendil-works/pi-coding-agent": ">=1.0.0 <2",
 		"@types/bun": "1.4.3",
-		"pi-roundtable": "0.19.1",
+		"pi-roundtable": "0.20.0",
 		"typebox": "1.3.37",
 		"typescript": "7.0.2"
 	}

package/src/chat.ts

@@ -32,6 +32,7 @@ import {
 } from "./oidc.ts";
 import { PromptDesk } from "./prompts.ts";
 import {
+	ADVERTISED_ASK,
 	CLOSE_CODES,
 	type ClientFrame,
 	type ErrorCode,
@@ -85,6 +86,8 @@ export interface WebChatLimits extends UploadLimits {
 
 export interface WebChatDeps {
 	surface: string;
+	/** How long a questionnaire no connection can show waits for one before it expires; default 60 seconds. */
+	promptGraceMs?: number;
 	verifier: TokenVerifier;
 	identity(): IdentityService;
 	personas: readonly WebPersona[];
@@ -240,7 +243,14 @@ export class WebChat {
 			this.connections.sendTo(principal, frame);
 		this.desk = new PromptDesk({
 			send,
+			sendWhere: (principal, frame, where) =>
+				this.connections.sendTo(principal, frame, where),
+			supports: (principal) => this.connections.askSupports(principal),
+			sendOne: (connection, frame) => this.connections.send(connection, frame),
 			timeoutMs: deps.limits.promptTimeoutMs,
+			...(deps.promptGraceMs === undefined
+				? {}
+				: { graceMs: deps.promptGraceMs }),
 		});
 		this.clients = new ClientDesk({
 			limits: deps.limits.clientCalls,
@@ -436,9 +446,13 @@ export class WebChat {
 			personas: this.personasFor(speaker),
 			attachments: this.uploads.advertised,
 			clientCalls: this.clients.advertised,
+			prompts: { ask: ADVERTISED_ASK },
 			expiresAt: identity.expiresAt.toISOString(),
 		});
-		for (const frame of this.desk.openFor(speaker.principalId))
+		for (const frame of this.desk.openFor(
+			speaker.principalId,
+			connection.askSupport,
+		))
 			this.connections.send(connection, frame);
 		this.#watchToken(connection);
 	}
@@ -477,6 +491,7 @@ export class WebChat {
 	closed(socket: RouteSocket<Connection>): void {
 		this.clients.closed(socket.data);
 		this.connections.closed(socket.data);
+		this.desk.closed(socket.data.speaker.principalId);
 	}
 
 	/** One frame from a socket; a refused frame is answered with `error`, never thrown. */
@@ -497,7 +512,9 @@ export class WebChat {
 			const ref =
 				frame.type === "send"
 					? frame.id
-					: frame.type === "approval" || frame.type === "answer"
+					: frame.type === "approval" ||
+							frame.type === "answer" ||
+							frame.type === "answers"
 						? frame.prompt
 						: frame.type === "client_result"
 							? frame.call
@@ -550,6 +567,12 @@ export class WebChat {
 				if (refused) throw new Refusal(refused);
 				return;
 			}
+			case "prompt_features":
+			case "answers": {
+				const refused = this.desk.receive(connection, speaker, frame);
+				if (refused) throw new Refusal(refused);
+				return;
+			}
 			case "client_hello":
 				connection.clientTools = frame.tools;
 				return;

package/src/connections.ts

@@ -1,4 +1,4 @@
-import type { Logger, RouteSocket, Speaker } from "pi-roundtable";
+import type { AskSupport, Logger, RouteSocket, Speaker } from "pi-roundtable";
 import type { WebIdentity } from "./oidc.ts";
 import type { ServerFrame } from "./protocol.ts";
 
@@ -18,6 +18,11 @@ export interface Connection {
 	 * never asked to run anything.
 	 */
 	clientTools?: readonly string[];
+	/**
+	 * What the client declared with `prompt_features` it can show of a questionnaire; undefined
+	 * until it declares. Such a connection is never sent a `questionnaire` prompt.
+	 */
+	askSupport?: AskSupport;
 	socket?: RouteSocket<Connection>;
 	/** Asks for a fresh token, then closes the socket when the token expires. */
 	timers: ReturnType<typeof setTimeout>[];
@@ -103,9 +108,20 @@ export class Connections {
 			);
 	}
 
-	/** Sends a frame to every connection of a person; none open is not an error. */
-	sendTo(principal: string, frame: ServerFrame): void {
+	/** Sends a frame to every connection of a person, or those `where` accepts; none open is not an error. */
+	sendTo(
+		principal: string,
+		frame: ServerFrame,
+		where?: (connection: Connection) => boolean,
+	): void {
 		for (const connection of this.#byPrincipal.get(principal) ?? [])
-			this.send(connection, frame);
+			if (!where || where(connection)) this.send(connection, frame);
+	}
+
+	/** What each open connection of a person declared it can show of a questionnaire; connections that declared nothing are left out. */
+	askSupports(principal: string): AskSupport[] {
+		return [...(this.#byPrincipal.get(principal) ?? [])].flatMap((c) =>
+			c.askSupport ? [c.askSupport] : [],
+		);
 	}
 }

package/src/prompts.ts

@@ -1,16 +1,23 @@
 import {
 	type Approval,
 	type ApprovalDetails,
+	type AskSupport,
+	checkAnswer,
+	checkQuestionnaireAnswer,
 	type OwnerAnswer,
 	type OwnerQuestion,
 	type PromptScope,
 	type Prompts,
+	type Questionnaire,
+	type QuestionnaireAnswer,
 	TIERS,
 	type Tier,
 	withdrawalNote,
 } from "pi-roundtable";
+import type { Connection } from "./connections.ts";
 import {
 	APPROVAL_MAX_BYTES,
+	type ClientFrame,
 	type ErrorCode,
 	type PromptFrame,
 	type PromptOutcome,
@@ -29,16 +36,38 @@ interface Open {
 	frame: PromptFrame;
 	/** The lowest tier that may approve; questions have none. */
 	minTier?: Tier;
-	settle(outcome: PromptOutcome, answer?: OwnerAnswer, note?: string): void;
+	/** A questionnaire: the connections it was sent to, which are the only ones told it closed. */
+	sentTo?: Set<Connection>;
+	/** A questionnaire no connection can show waits this long for one to, then expires. */
+	grace?: ReturnType<typeof setTimeout>;
+	settle(
+		outcome: PromptOutcome,
+		answer?: OwnerAnswer | QuestionnaireAnswer,
+		note?: string,
+	): void;
 }
 
 export interface PromptDeskOptions {
 	/** Sends a frame to every connection of a person. */
 	send(principal: string, frame: ServerFrame): void;
+	/** Sends a frame to the connections of a person that `where` accepts. */
+	sendWhere(
+		principal: string,
+		frame: ServerFrame,
+		where: (connection: Connection) => boolean,
+	): void;
+	/** What the open connections of a person declared they can show of a questionnaire. */
+	supports(principal: string): AskSupport[];
+	/** Sends a frame on one connection. */
+	sendOne(connection: Connection, frame: ServerFrame): void;
 	/** An unanswered prompt expires after this long. */
 	timeoutMs: number;
+	/** How long a questionnaire that no connection can show waits for one (default 60 seconds). */
+	graceMs?: number;
 }
 
+const GRACE_MS = 60_000;
+
 const atLeast = (tier: Tier, least: Tier) =>
 	TIERS.indexOf(tier) >= TIERS.indexOf(least);
 
@@ -62,6 +91,7 @@ export class PromptDesk {
 	 * a private conversation, so the call stays held, as an unanswered card leaves it.
 	 */
 	prompts(conversation: string, scope: PromptScope): Prompts {
+		const desk = this;
 		return {
 			confirm: async (
 				title,
@@ -91,7 +121,7 @@ export class PromptDesk {
 				return toApproval(outcome.outcome);
 			},
 			ask: async (title, question, signal) => {
-				const { outcome, answer } = await this.#ask(
+				const { outcome, answer } = await this.#ask<OwnerAnswer>(
 					conversation,
 					scope.principalId,
 					(id) => questionFrame(id, title, question),
@@ -99,13 +129,63 @@ export class PromptDesk {
 				);
 				return outcome === "answered" ? answer : undefined;
 			},
+			// The minimum of what the person's declaring panels show; read when asked, so a panel
+			// that connects mid-turn counts. None declared means the 0.19 contract.
+			get asks() {
+				return desk.#asksFor(scope.principalId);
+			},
+			get questionnaire() {
+				const asks = desk.#asksFor(scope.principalId);
+				if (!asks || (asks.questions < 2 && !asks.previews)) return undefined;
+				return async (
+					title: string,
+					questionnaire: Questionnaire,
+					signal?: AbortSignal,
+				) => {
+					const { outcome, answer } = await desk.#ask<QuestionnaireAnswer>(
+						conversation,
+						scope.principalId,
+						(id) => ({
+							id,
+							kind: "questionnaire",
+							title,
+							questions: questionnaire.questions.map((q) => ({
+								...q,
+								options: q.options.map((option) => ({ ...option })),
+							})),
+						}),
+						signal,
+					);
+					return outcome === "answered" ? answer : undefined;
+				};
+			},
 		};
 	}
 
-	/** The open prompts of a person, as frames to send again when they connect. */
-	openFor(principal: string): ServerFrame[] {
+	/** The field-wise minimum of the person's declared supports; undefined when none declared. */
+	#asksFor(principal: string): AskSupport | undefined {
+		const supports = this.#options.supports(principal);
+		const [first, ...rest] = supports;
+		if (!first) return undefined;
+		return rest.reduce<AskSupport>(
+			(least, s) => ({
+				questions: Math.min(least.questions, s.questions),
+				previews: least.previews && s.previews,
+				note: least.note && s.note,
+			}),
+			first,
+		);
+	}
+
+	/**
+	 * The open prompts of a person, as frames to send again when they connect. A questionnaire is
+	 * left out unless the connection declared `support` that covers it.
+	 */
+	openFor(principal: string, support?: AskSupport): ServerFrame[] {
 		return [...this.#open.values()]
-			.filter((open) => open.principal === principal)
+			.filter(
+				(open) => open.principal === principal && showable(open.frame, support),
+			)
 			.map((open) => ({
 				type: "prompt",
 				conversation: open.conversation,
@@ -113,6 +193,34 @@ export class PromptDesk {
 			}));
 	}
 
+	/**
+	 * A connection of the person closed. A questionnaire that no remaining connection can show
+	 * would leave the turn waiting for an answer no one can give, so it gets a grace period for a
+	 * panel to reconnect and declare, then expires and the model is told it went unanswered.
+	 */
+	closed(principal: string): void {
+		this.#regrace(principal);
+	}
+
+	/** Starts or cancels the grace timer of each open questionnaire of a person. */
+	#regrace(principal: string): void {
+		const supports = this.#options.supports(principal);
+		for (const open of this.#open.values()) {
+			if (open.principal !== principal || open.frame.kind !== "questionnaire")
+				continue;
+			const frame = open.frame;
+			if (supports.some((s) => showable(frame, s))) {
+				clearTimeout(open.grace);
+				open.grace = undefined;
+			} else if (!open.grace) {
+				open.grace = setTimeout(
+					() => open.settle("expired"),
+					this.#options.graceMs ?? GRACE_MS,
+				);
+			}
+		}
+	}
+
 	/** Approves or declines; an error code when the prompt is not an approval this person may answer. */
 	approve(
 		from: Answerer,
@@ -136,12 +244,74 @@ export class PromptDesk {
 		const open = this.#open.get(prompt);
 		if (open?.frame.kind !== "ask") return "unknown_prompt";
 		if (open.principal !== from.principalId) return "forbidden";
-		if (!fits(open.frame, answer)) return "bad_frame";
+		if (!checkAnswer(open.frame, answer)) return "bad_frame";
+		open.settle("answered", answer);
+		return undefined;
+	}
+
+	/**
+	 * Takes the frames that concern questionnaires: `prompt_features` declares what the connection
+	 * shows and sends it the open questionnaires it can now show, and `answers` answers one.
+	 * An error code when the frame is refused.
+	 */
+	receive(
+		connection: Connection,
+		from: Answerer,
+		frame: Extract<ClientFrame, { type: "prompt_features" | "answers" }>,
+	): ErrorCode | undefined {
+		if (frame.type === "answers") return this.#answers(from, frame);
+		const before = connection.askSupport;
+		connection.askSupport = frame.ask;
+		const changed =
+			!before ||
+			before.questions !== frame.ask.questions ||
+			before.previews !== frame.ask.previews ||
+			before.note !== frame.ask.note;
+		// A repeated declaration (each `ready` asks for one) does not send what is already shown.
+		if (changed)
+			for (const open of this.#open.values())
+				if (
+					open.principal === from.principalId &&
+					open.sentTo &&
+					showable(open.frame, frame.ask) &&
+					!(open.sentTo.has(connection) && showable(open.frame, before))
+				) {
+					open.sentTo.add(connection);
+					this.#options.sendOne(connection, {
+						type: "prompt",
+						conversation: open.conversation,
+						prompt: open.frame,
+					});
+				}
+		this.#regrace(from.principalId);
+		return undefined;
+	}
+
+	#answers(
+		from: Answerer,
+		frame: Extract<ClientFrame, { type: "answers" }>,
+	): ErrorCode | undefined {
+		const open = this.#open.get(frame.prompt);
+		if (open?.frame.kind !== "questionnaire") return "unknown_prompt";
+		if (open.principal !== from.principalId) return "forbidden";
+		const answer: QuestionnaireAnswer = {
+			answers: frame.answers.map((a) =>
+				a === null || !(a.choices.length > 0 || a.text?.trim())
+					? undefined
+					: {
+							choices: a.choices,
+							...(a.text?.trim() ? { text: a.text.trim() } : {}),
+						},
+			),
+			...(frame.note?.trim() ? { note: frame.note.trim() } : {}),
+		};
+		if (!checkQuestionnaireAnswer({ questions: open.frame.questions }, answer))
+			return "bad_frame";
 		open.settle("answered", answer);
 		return undefined;
 	}
 
-	#ask(
+	#ask<A extends OwnerAnswer | QuestionnaireAnswer = OwnerAnswer>(
 		conversation: string,
 		principal: string,
 		frameOf: (id: string) => PromptFrame,
@@ -149,13 +319,22 @@ export class PromptDesk {
 		minTier?: Tier,
 		supersede?: AbortSignal,
 		approvedPrompt?: (prompt: string) => void,
-	): Promise<{ outcome: PromptOutcome; answer?: OwnerAnswer }> {
+	): Promise<{ outcome: PromptOutcome; answer?: A }> {
 		const { send, timeoutMs } = this.#options;
 		if (signal?.aborted || supersede?.aborted)
 			return Promise.resolve({ outcome: "cancelled" });
 		return new Promise((resolve) => {
 			const id = crypto.randomUUID();
 			const frame = frameOf(id);
+			// A questionnaire reaches only the connections that declared support covering it.
+			const sentTo = new Set<Connection>();
+			const sendQuestionnaire = (out: ServerFrame) =>
+				this.#options.sendWhere(principal, out, (connection) => {
+					if (out.type === "prompt_closed") return sentTo.has(connection);
+					const shows = showable(frame, connection.askSupport);
+					if (shows) sentTo.add(connection);
+					return shows;
+				});
 			const onAbort = () => settle("cancelled");
 			const timer = setTimeout(() => settle("expired"), timeoutMs);
 			const onSupersede = () =>
@@ -163,35 +342,50 @@ export class PromptDesk {
 				settle("withdrawn", undefined, withdrawalNote(supersede, ""));
 			const settle = (
 				outcome: PromptOutcome,
-				answer?: OwnerAnswer,
+				answer?: OwnerAnswer | QuestionnaireAnswer,
 				note?: string,
 			) => {
 				// Whichever of an answer and a withdrawal comes first settles the prompt.
-				if (!this.#open.delete(id)) return;
+				const open = this.#open.get(id);
+				if (!open || !this.#open.delete(id)) return;
+				clearTimeout(open.grace);
 				// Heard before the approval resolves, so the call that runs on it can say which card it was.
 				if (outcome === "approved") approvedPrompt?.(id);
 				clearTimeout(timer);
 				signal?.removeEventListener("abort", onAbort);
 				supersede?.removeEventListener("abort", onSupersede);
-				send(principal, {
+				const closed: ServerFrame = {
 					type: "prompt_closed",
 					conversation,
 					prompt: id,
 					outcome,
 					...(note ? { note } : {}),
-				});
-				resolve(answer ? { outcome, answer } : { outcome });
+				};
+				if (frame.kind === "questionnaire") sendQuestionnaire(closed);
+				else send(principal, closed);
+				resolve(answer ? { outcome, answer: answer as A } : { outcome });
 			};
 			this.#open.set(id, {
 				conversation,
 				principal,
 				frame,
 				...(minTier ? { minTier } : {}),
+				...(frame.kind === "questionnaire" ? { sentTo } : {}),
 				settle,
 			});
 			signal?.addEventListener("abort", onAbort, { once: true });
 			supersede?.addEventListener("abort", onSupersede, { once: true });
-			send(principal, { type: "prompt", conversation, prompt: frame });
+			const shown: ServerFrame = {
+				type: "prompt",
+				conversation,
+				prompt: frame,
+			};
+			if (frame.kind === "questionnaire") {
+				sendQuestionnaire(shown);
+				// Sent to no one: wait the grace for a panel that can show it, never the full timeout.
+				// With no tab connected at all this waits too, so a reconnect can still rescue it.
+				this.#regrace(principal);
+			} else send(principal, shown);
 		});
 	}
 }
@@ -308,17 +502,19 @@ function questionFrame(
 	};
 }
 
-/** Whether an answer is one the question allows: offered labels, one unless multi, own text only where allowed. */
-function fits(
-	frame: Extract<PromptFrame, { kind: "ask" }>,
-	answer: OwnerAnswer,
+/**
+ * Whether a connection with `support` may be sent the prompt: every prompt but a questionnaire,
+ * which only a connection that declared support covering its questions and previews may have.
+ */
+function showable(
+	frame: PromptFrame,
+	support: AskSupport | undefined,
 ): boolean {
-	const labels = frame.options.map((option) => option.label);
-	const text = answer.text?.trim();
-	if (!answer.choices.every((choice) => labels.includes(choice))) return false;
-	if (new Set(answer.choices).size !== answer.choices.length) return false;
-	if (!frame.multi && answer.choices.length > 1) return false;
-	if (labels.length === 0) return answer.choices.length === 0 && Boolean(text);
-	if (text && !frame.allowOther) return false;
-	return answer.choices.length > 0 || Boolean(text);
+	if (frame.kind !== "questionnaire") return true;
+	if (!support) return false;
+	if (frame.questions.length > support.questions) return false;
+	const previews = frame.questions.some((q) =>
+		q.options.some((o) => o.preview),
+	);
+	return support.previews || !previews;
 }

package/src/protocol.ts

@@ -1,8 +1,12 @@
-import type {
-	ApprovalDetails,
-	AskOption,
-	Tier,
-	TurnProgress,
+import {
+	type ApprovalDetails,
+	type AskOption,
+	type AskSupport,
+	type OwnerAnswer,
+	type OwnerQuestion,
+	QUESTIONNAIRE_LIMITS,
+	type Tier,
+	type TurnProgress,
 } from "pi-roundtable";
 import type { Notice } from "./notices.ts";
 
@@ -70,8 +74,22 @@ export type PromptFrame =
 			options: readonly AskOption[];
 			multi: boolean;
 			allowOther: boolean;
+	  }
+	| {
+			id: string;
+			kind: "questionnaire";
+			title: string;
+			/** The core's questions, verbatim; sent only to connections that declared `prompt_features` covering them. */
+			questions: readonly OwnerQuestion[];
 	  };
 
+/** What a server that takes `prompt_features` advertises in `ready.prompts` and can send. */
+export const ADVERTISED_ASK: AskSupport = Object.freeze({
+	questions: QUESTIONNAIRE_LIMITS.questions,
+	previews: true,
+	note: true,
+});
+
 /**
  * How a prompt closed. `withdrawn` is an approval the plugin that asked for it took back; the
  * frame may carry a short `note` saying why.
@@ -163,6 +181,21 @@ export type ClientFrame =
 	| { type: "approval"; prompt: string; approved: boolean }
 	/** Answers a question prompt: the chosen options' labels and, where allowed, their own text. */
 	| { type: "answer"; prompt: string; choices: string[]; text?: string }
+	/**
+	 * Answers a `questionnaire` prompt: one entry per question in order, `null` for a question left
+	 * blank, and an optional note on the whole set.
+	 */
+	| {
+			type: "answers";
+			prompt: string;
+			answers: (OwnerAnswer | null)[];
+			note?: string;
+	  }
+	/**
+	 * Declares what this connection can show of a questionnaire. Send it only after a `ready` that
+	 * has `prompts`; a connection that never declares is never sent a `questionnaire` prompt.
+	 */
+	| { type: "prompt_features"; ask: AskSupport }
 	/**
 	 * Declares the functions this connection can run for the assistant's tools, such as reading the
 	 * page the person has open. Send it after each `ready`. A connection that declares none is never
@@ -214,6 +247,11 @@ export type ServerFrame =
 			 * `client_call`: show no feature that needs the page's help then.
 			 */
 			clientCalls?: ClientCallsAdvertised;
+			/**
+			 * What questionnaires this server can send. Absent from a server before 0.20: never send
+			 * `prompt_features` then. A client that sees it may declare what it shows.
+			 */
+			prompts?: { ask: AskSupport };
 	  }
 	/** The message `id` was taken into `conversation`, a new one when the client named none. */
 	| { type: "accepted"; id: string; conversation: string }
@@ -354,6 +392,10 @@ export function parseClientFrame(
 				...(text === undefined ? {} : { text }),
 			};
 		}
+		case "answers":
+			return parseAnswers(value);
+		case "prompt_features":
+			return parseFeatures(value);
 		case "client_hello":
 			return parseHello(value);
 		case "client_result":
@@ -363,6 +405,56 @@ export function parseClientFrame(
 	}
 }
 
+function parseAnswers(value: Record<string, unknown>): ClientFrame | undefined {
+	const { prompt, answers, note } = value;
+	if (!isId(prompt) || !Array.isArray(answers)) return undefined;
+	if (answers.length < 1 || answers.length > QUESTIONNAIRE_LIMITS.questions)
+		return undefined;
+	if (!optional(note, (n): n is string => typeof n === "string"))
+		return undefined;
+	const parsed: (OwnerAnswer | null)[] = [];
+	for (const answer of answers as unknown[]) {
+		if (answer === null) {
+			parsed.push(null);
+			continue;
+		}
+		if (!isRecord(answer) || !Array.isArray(answer.choices)) return undefined;
+		const { choices, text } = answer;
+		if (!choices.every((choice) => typeof choice === "string"))
+			return undefined;
+		if (!optional(text, (t): t is string => typeof t === "string"))
+			return undefined;
+		parsed.push({
+			choices: choices as string[],
+			...(text === undefined ? {} : { text }),
+		});
+	}
+	return {
+		type: "answers",
+		prompt,
+		answers: parsed,
+		...(note === undefined ? {} : { note }),
+	};
+}
+
+function parseFeatures(
+	value: Record<string, unknown>,
+): ClientFrame | undefined {
+	const { ask } = value;
+	if (!isRecord(ask)) return undefined;
+	const { questions, previews, note } = ask;
+	if (
+		typeof questions !== "number" ||
+		!Number.isInteger(questions) ||
+		questions < 1 ||
+		questions > QUESTIONNAIRE_LIMITS.questions ||
+		typeof previews !== "boolean" ||
+		typeof note !== "boolean"
+	)
+		return undefined;
+	return { type: "prompt_features", ask: { questions, previews, note } };
+}
+
 function parseHello(value: Record<string, unknown>): ClientFrame | undefined {
 	const { version, tools } = value;
 	if (version !== 1 || !Array.isArray(tools)) return undefined;