pi-roundtable 0.19.2 → 0.21.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-10-20
+
+### Added
+
+- A held call's approval card can be its speaker's alone (`pi-roundtable`). A hold answers `{ text, approval: "speaker" }` (`HoldDescription.approval`, beside `copy` and `supersede`; a tool's `hold` and a rule's `describeInTurn` both may) and the card reaches the surface as `ApprovalOptions.speakerOnly`. Only the speaker whose turn made the call answers it, on any of their identities the surface knows and at the call's tier, checked again when they press: in a shared conversation no owner does, and an owner's press or decline is refused with the card's own line while the card stays open for the speaker. A speaker below the tier, a turn with no speaker and a speaker with no Discord identity get `unavailable` at once, shown to no one, so the call stays held. With `approvers` the card is still the speaker's alone, and the runtime accepts their press only when the approvers name them or they are an owner. The option governs the card only; a message that confirms the held call is judged as before, so a tool that must act on the speaker's press alone checks `ToolTurn.approvedPrompt` and `ToolTurn.approvedBy` in `run`. Without it every card behaves as before. The Discord cards and the web chat honour it, and `SurfaceContractSubject.speakerOnly` makes `describeSurfaceContract` check, with an `owner`, that an owner's answer leaves such an approval open in a shared conversation; a subject that does not declare it skips the check.
+
+## [0.20.0] - 2026-10-18
+
+### Added
+
+- The core model for asking several questions in one `ask_user` call (`pi-roundtable`): `Questionnaire` (one to four `OwnerQuestion`s), `QuestionnaireAnswer` (`answers` aligned with the questions, each undefined when left blank, and an optional `note`), `AskSupport` (`{ questions, previews, note }`, what a surface can show) and `SINGLE_QUESTION` (the 0.19 contract). `AskOption` gains `preview` and `OwnerQuestion` gains `header`. `Prompts` gains two optional members, `asks` and `questionnaire(title, questionnaire, signal?, wait?)`; a `Prompts` without them type-checks and behaves as before. `LateAnswer` gains `{ kind: "questionnaire"; answer: QuestionnaireAnswer }`, which only a `questionnaire` call produces, so a consumer that switches on `kind` exhaustively needs a case for it. `QUESTIONNAIRE_LIMITS` is the one table of limits; `validateQuestionnaire` returns the model-facing reason a set is refused; `checkAnswer` and `checkQuestionnaireAnswer` check an answer against its questions; `shapeFor` (`shapeFor(questionnaire, support)`) degrades a set to what a surface shows, folding previews into the question text as fenced blocks for a surface without previews and dropping headers for one that takes a single question.
+
+- The Discord card for a whole `ask_user` set (`pi-roundtable`): `Prompts.asks` is `{ questions: 4, previews: true, note: true }` and `Prompts.questionnaire` posts one card with a menu per question that has options (it can be cleared again), **Submit**, **Write answers / note…** (a form with one field per question that takes text of its own, plus a note on the whole set; five fields at most), and, when an option has a preview, **Previews**. The draft is one per card and shared by everyone who may answer; each pick or edit restarts the grace period of a turn that waits on the card, and the one who presses Submit is reported as the answerer. Answers may be partial, but Submit with nothing chosen or written is refused. Previews opens an ephemeral reply for anyone who can see the card, never answers, and is sent as a file when a preview holds a code fence. A Submit after the turn stopped waiting starts a turn with the questionnaire answer. One question with previews is the single-question card with a Previews button, so it still answers on the first click. The card keeps within Discord's limits for four questions of 25 options each (ten container children, 40 components, 4,000 characters of text, five form fields, 45-character labels); `src/core/testing/discord-limits.ts` checks them. A restart abandons open cards as before. Every limit is counted in UTF-16 units, as Discord counts them, so an emoji or rare character weighs two, and the core's refusal of an over-long set (3,000 characters of questions and headers) counts them the same way; a card of emoji-heavy questions is refused with a reason instead of failing to post.
+
+- The web chat shows a whole set on one card too, to clients that declared they can (see the `pi-roundtable-webchat` changelog); a person whose tabs have not is asked one question at a time.
+
+- Questionnaire checks in the surface contract (`pi-roundtable/testing`): a surface that declares `asks` must settle a questionnaire as its person answers it (a blank question stays blank, the note comes back where `asks.note`), close it when the turn stops, and ignore another person's answer. `SurfaceContractSubject` and `SurfaceContractAnswerer` gain an optional `answerQuestionnaire(prompt, answer, questionnaire)`; without it the checks are skipped, and a subject that gives it must declare `asks`, or the contract fails it. The Discord cards and the web chat run them; the example surface stays on one question at a time.
+
+### Changed
+
+- `ask_user` takes `questions`: one to four related questions in one call, each with an optional `header`, options that may carry a `description` and a markdown `preview`, `multi`, and `allow_other` (which defaults to true in this form; set it false for a closed choice). A call in the old form (`question`, `options`, `multi`, `allow_other` at the top level) and a `questions` or `options` value that arrives as a JSON string are folded into it before the schema is checked, so old sessions keep working; the old form keeps `allow_other` false by default. A set is checked first and a refused one (more than four questions, an option offered twice, a question asked twice, a text or preview over its limit, questions and headers together over 3,000 characters) posts no card and tells the model why. This refuses duplicate option labels and duplicate questions for every call, the old form included, which 0.19 accepted, and a whitespace-only question text is refused too. A surface without a questionnaire card is asked one question at a time, stopping at the first that is not answered and telling the model which questions it did not ask; previews are folded into the question text and headers are dropped there. A single question posts the same card and returns the same text as 0.19, previews or not, and so does its late answer. `PromptSlot` forwards `asks` and `questionnaire` to the prompts it wraps when they have them.
+
+### Fixed
+
+- A single-question Discord card with 25 options and an answer of their own (`allow_other`) dropped the 25th option, because "Other…" took its place in the menu. The menu now keeps all 25 options and an "Answer…" button under it opens the form. A card with fewer options is unchanged.
+
 ## [0.19.2] - 2026-10-18
 
 ### Changed

package/README.md

@@ -201,7 +201,7 @@ When a conversation is started over in a server channel or thread, the assistant
 | text | Markdown renders except tables | What the model is told, in English, about how a reply renders in Discord; appended to the system prompt of every turn that replies there |
 | `false` | | Tell the model nothing |
 
-An approval card or an `ask_user` question holds its turn for `discord.cardGraceSeconds` (default `120`).
+An approval card or an `ask_user` question (a set of up to four questions is one card) holds its turn for `discord.cardGraceSeconds` (default `120`).
 The files of a message in an agent's channel download within `discord.attachmentDownload.deadlineMs` (default 60,000) for the message and the one it replies to together, and a file that sends no byte for `discord.attachmentDownload.idleMs` (default 10,000) is given up; the turn goes on without a file it could not get.
 The copy button of an approval card keeps its text in `card-copies.json` under the data directory, the newest 100 for 30 days; `discord.cardCopies` (`{ keepDays?, keep? }`) changes that, and `false` keeps them in memory only.
 Answered within it, the turn goes on with the answer; otherwise the turn ends saying it is waiting, the card stays open with no deadline, and answering it later starts a new turn in that conversation with the answer, or with the result of the approved action.

package/README.zh-TW.md

@@ -184,7 +184,7 @@ export default {
 | `foreignWebhook` | 無 | `(webhookId) => boolean \| "skip"`：回傳 true 的 webhook 所發的貼文視為別人的訊息，不是助理自己的；回傳 `"skip"` 則把該 webhook 的貼文當作不存在，不納入也不截斷範圍（只能用程式碼設定） |
 | `attachments` | `{ images: 0, maxBytes: 10 MiB }` | `images`：替這一輪抓取保留訊息中的幾張圖片，最多 4 張 |
 
-核准卡和 `ask_user` 問題會讓這一輪等 `discord.cardGraceSeconds` 秒（預設 `120`）。
+核准卡和 `ask_user` 問題（一次最多四題的一組問題放在同一張卡片上）會讓這一輪等 `discord.cardGraceSeconds` 秒（預設 `120`）。
 agent 頻道裡訊息的附件，整則訊息（連同它回覆的那則）要在 `discord.attachmentDownload.deadlineMs`（預設 60,000）毫秒內下載完；單一檔案連續 `discord.attachmentDownload.idleMs`（預設 10,000）毫秒沒收到任何位元組就放棄，這一輪會略過收不到的檔案繼續。
 核准卡「複製」按鈕的文字存在資料目錄的 `card-copies.json`，預設留最新 100 張、30 天；`discord.cardCopies`（`{ keepDays?, keep? }`）可以調整，設成 `false` 則只留在記憶體。
 在這段時間內回答，這一輪就帶著答案繼續；沒回答的話，這一輪會說它在等你，然後結束，卡片繼續開著、沒有期限，之後再回答就會在同一個對話開新的一輪，帶上你的答案，或核准後那個動作的結果。

package/docs/plugins.md

@@ -876,6 +876,21 @@ A rule whose verdict depends on the input, such as one that holds only a `delete
 It is asked when the input is not known yet, as for a [precheck script](#precheck-scripts-prechecks-the-agent-writes)'s call whose arguments are computed when it runs; a rule without it is judged by `describe` with an empty input.
 A rule whose held call stands for others can answer `approvalTier(tool, input, context)`: the lowest tier that may approve it when higher than the tool's own. The held call keeps it as `minTier`, and both its card and a confirming message require it. A card is answered, and a confirming message accepted, from the speaker whose turn held the call, when their tier is at least `minTier`, and from the owners where the conversation is shared ([who answers a prompt](#who-answers-a-prompt-promptscope)); nobody else in the channel may approve it. The held call records that speaker as `PendingConfirmation.speakerId` and their principal as `principalId`, so a confirming message from another identity of theirs counts after a restart too; a call held without them is the owners' to approve, and one held before 0.9, without a principal, is matched by `speakerId`.
 
+#### A hold that makes its card the speaker's alone
+
+By default the speaker whose turn made a held call may answer its card, and in a shared conversation so may every owner. A hold that wants only the speaker to press, such as one whose tool books something under the speaker's name, answers `{ text, approval: "speaker" }` (`HoldDescription.approval`, beside `copy` and `supersede`; a tool's `hold` and a rule's `describeInTurn` both may):
+
+```ts
+hold: async ({ draft }, turn) => ({ text: await summaryOf(draft, turn), approval: "speaker" }),
+```
+
+- Only the speaker answers the card: their principal, on any of their identities the surface knows, at the call's tier, checked again when they press. An owner's press is refused with the card's own line, the card stays open for the speaker, and the owner's decline is refused too. An owner who is the speaker answers as the speaker.
+- It holds for a late press as well: a card answered after the turn stopped waiting is still the speaker's alone, so the turn that follows is started by the speaker.
+- A speaker below the call's tier, a turn with no speaker, and a surface that cannot tell who the speaker is get `unavailable` at once, shown to no one, and the call stays held, as for any card nobody may answer. It never falls back to the owners.
+- Combined with [approvers](#a-hold-that-names-its-approvers) the card is still the speaker's alone, and the runtime accepts the press only when the approvers name the speaker (or they are an owner); otherwise the call stays held.
+- The option governs the card only. A message that confirms the held call is judged as for any call, so an owner's message can still release it. A tool that must act on the speaker's press alone checks in `run` that `turn.approvedPrompt` is set (a message sets none) and that `turn.approvedBy?.speakerId` is the speaker's.
+- Anything but `"speaker"` leaves the card as every card is. A surface implements this through `ApprovalOptions.speakerOnly`; the Discord cards and the web chat (whose prompts are its person's alone) honour it, and the contract checks it where a subject declares `speakerOnly`.
+
 #### A hold that names its approvers
 
 A held call is approved by the speaker whose turn made it, or by an owner where the conversation is shared. A tool whose call stands for someone else, such as a message sent under another person's name, can name who approves it instead:
@@ -2608,7 +2623,7 @@ The agent server claims only `discord:` keys, so claims on your surface's channe
 | `startTyping(channel)` | Shows a typing indicator until the returned function is called | none is shown |
 | `showStop(channel)` | Shows the owner a stop control until the returned function is called; using it calls `conversations.stop(channel)` | none is shown |
 | `react`, `unreact` | Adds or removes the bot's reaction on a message | no marks on queued or steered messages |
-| `prompts(channel, scope?)` | How those the turn's `PromptScope` names approve a held action or answer `ask_user` inside a running turn, as `Prompts`: `confirm` and `ask`; without a scope, the owners | the action is held until a message approves it |
+| `prompts(channel, scope?)` | How those the turn's `PromptScope` names approve a held action or answer `ask_user` inside a running turn, as `Prompts`: `confirm` and `ask`, and, where the surface declares `asks`, `questionnaire` ([several questions on one card](#several-questions-on-one-card-questionnaire-and-asksupport)); without a scope, the owners | the action is held until a message approves it |
 | `interim(channel)` | Where a running turn posts the text it writes before its final answer, as `InterimPosts`: `post(text)` sends one message of at most 2000 characters and resolves to an `InterimMessage` whose `edit(text)` changes it in place | only the final reply is posted |
 | `progress(channel, event)` | Shows a turn run through `context.turns` as it goes, such as a live preview in a web chat. `event` is a `TurnProgress`: `{ type: "text", delta }` (the reply's text, joined over 250 ms and always sent before a tool event, never the thinking), `{ type: "tool_start", id, tool, preview? }` (a one-line preview of the arguments, at most 80 characters, never their full text), or `{ type: "tool_end", id, tool, ok, refused? }` (`refused`, only on a failed end that a hold refused, says how: `declined` on its approval card, `expired` when a card was shown and went unanswered, `pending` while the card stays open, or `held` when no card could be shown (no one may approve it, or it could not be posted); it is absent for a success and for a real failure). The final reply still comes through `sendReply`; a rejection is logged and the turn goes on | only the final reply is shown |
 
@@ -2645,6 +2660,8 @@ A surface's prompts keep these rules:
 - Without a scope, as for a turn with no speaker, the prompts are the owners'.
 - An approval that names [approvers](#a-hold-that-names-its-approvers) (`ApprovalOptions.approvers`, which `confirm` receives beside the scope) is theirs **instead of the speaker's**, where the scope escalates to the owners: each named principal answers on any of their identities the surface knows, at the tier it needs, checked again when they answer; the speaker does not answer it unless named, and an owner still does. When none of the named has an identity on the surface, or none is named, it is the owners' alone. Where the scope escalates to no one, the person alone answers, and only when they are named or an owner: for anyone else the approval resolves `unavailable` at once, shown to no one. The runtime also refuses such a call before it asks, whatever the surface does.
 
+- An approval that is the [speaker's alone](#a-hold-that-makes-its-card-the-speakers-alone) (`ApprovalOptions.speakerOnly`) is theirs without the owner escalation, whatever the scope says: the speaker's principal answers on any of their identities the surface knows, at the tier it needs, checked again when they answer, and no owner does. Without a scope, or when the speaker is below the tier or has no identity on the surface, it resolves `unavailable` at once, shown to no one.
+
 On Discord a card for named approvers mentions every Discord identity of every named principal that has one, in a thread, and refuses anyone else with a line that says it is for the people it names and the owners.
 The web chat shows prompts to the conversation's person only. The runtime never asks it about a call that names approvers the person is neither among nor an owner of, and the person is the approver of one that names them.
 
@@ -2656,7 +2673,7 @@ The web chat shows prompts to the conversation's person only: its owners are not
 
 `confirm(title, message, signal?, minTier?, wait?, details?, options?)` takes the approval twice: `message` is the card as markdown text, and the optional `details` (`ApprovalDetails`: `{ action, tool, input, files? }`) is the same held call as data, with its whole input (the web chat cuts it only past 256 KiB and says so with `truncated`), and each file it sends by path as `{ path, bytes? }`.
 The confirmation gate and a coding worker's cards pass both.
-`options` (`ApprovalOptions`) says who else may approve the call and hears who did: `approvers`, the principal ids that approve it instead of the speaker (see [who answers a prompt](#who-answers-a-prompt-promptscope)), and `approvedBy(by)`, which a surface that knows who answered calls with `{ principalId, speakerId, name, owner? }` (`ApprovedBy`; `owner` when they approved as an owner) before `confirm` resolves `approved`. `approvedPrompt(prompt)` is called, likewise before `confirm` resolves `approved`, with the id of the card that approved the call, for `ToolTurn.approvedPrompt`; a surface whose cards have no stable id leaves it uncalled. A surface may ignore all three for a call that names no approvers. For one that does, the runtime accepts the approval only from a surface that calls `approvedBy` with a named principal or an `owner`, so a surface that cannot say who answered must not offer such a call to a shared conversation.
+`options` (`ApprovalOptions`) says who else may approve the call and hears who did: `approvers`, the principal ids that approve it instead of the speaker (see [who answers a prompt](#who-answers-a-prompt-promptscope)), `speakerOnly`, true when the card is the speaker's alone and no owner may answer it (see [a hold that makes its card the speaker's alone](#a-hold-that-makes-its-card-the-speakers-alone); a surface that cannot honour it resolves `unavailable` instead of showing the card to the owners), and `approvedBy(by)`, which a surface that knows who answered calls with `{ principalId, speakerId, name, owner? }` (`ApprovedBy`; `owner` when they approved as an owner) before `confirm` resolves `approved`. `approvedPrompt(prompt)` is called, likewise before `confirm` resolves `approved`, with the id of the card that approved the call, for `ToolTurn.approvedPrompt`; a surface whose cards have no stable id leaves it uncalled. A surface may ignore all three for a call that names no approvers. For one that does, the runtime accepts the approval only from a surface that calls `approvedBy` with a named principal or an `owner`, so a surface that cannot say who answered must not offer such a call to a shared conversation.
 A surface that shows text, such as Discord, uses `message` and reads only `details.copy` (below); the web chat sends `details` to the client as the prompt frame's `approval`, beside the unchanged `title` and `message`.
 A surface or a `Prompts` of your own may ignore it: nothing requires reading it.
 
@@ -2668,7 +2685,7 @@ Because anyone who can see the card can copy the text, it holds nothing they may
 
 #### A prompt that outlives its turn: `PromptWait`
 
-`confirm(title, message, signal?, minTier?, wait?)` and `ask(title, question, signal?, wait?)` take an optional `PromptWait`, whose `late(answer)` hears a `LateAnswer` (`{ kind: "approval", approved, by, approvedBy?, prompt? }`, `approvedBy` naming the approver where the surface knows them and `prompt` the id of the card that was answered, or `{ kind: "question", answer, by }`, `by` naming who answered) and returns the text of the turn that tells the conversation, or undefined for none.
+`confirm(title, message, signal?, minTier?, wait?)` and `ask(title, question, signal?, wait?)` take an optional `PromptWait`, whose `late(answer)` hears a `LateAnswer` (`{ kind: "approval", approved, by, approvedBy?, prompt? }`, `approvedBy` naming the approver where the surface knows them and `prompt` the id of the card that was answered, `{ kind: "question", answer, by }`, or `{ kind: "questionnaire", answer: QuestionnaireAnswer, by }`, `by` naming who answered; only a `questionnaire` call can produce the last) and returns the text of the turn that tells the conversation, or undefined for none.
 Given one, a surface may stop the turn's wait after a grace period: `confirm` then resolves `pending` and `ask` resolves `"pending"`, the prompt stays open, and when it is answered later the surface starts a turn in the prompt's conversation with that text, as a message from whoever answered, so the conversation's claim answers it as theirs.
 Without one, a prompt waits for its answer, or for its turn's stop; a surface that cannot start a turn ignores `wait` and waits too.
 A stop cancels a prompt only while its turn still waits on it; after that the prompt belongs to the conversation.
@@ -2682,6 +2699,25 @@ On Discord the grace period is `discord.cardGraceSeconds` (default 120), and the
 A card answered late is edited to show the answer with its controls disabled, as one answered in time is; a second press finds it answered.
 Open cards live in memory: after a restart, pressing one replies, to the presser alone, that it is no longer valid and to ask again.
 
+#### Several questions on one card: `questionnaire` and `AskSupport`
+
+`ask_user` takes one to four questions in one call (`questions`; a whitespace-only question is refused), each with an optional short `header`, options with an optional `description` and markdown `preview`, `multi`, and `allow_other` (true by default in this form, so every question takes a written answer too), and the person may add a note on the whole set. The older single-question arguments (`question`, `options`, `multi`, `allow_other`) still work and read as one question with `allow_other` false; double-encoded `questions` and `options` values are decoded. A call that breaks `QUESTIONNAIRE_LIMITS` (the table of every limit: four questions, a header of 30 characters, 25 options, 100 characters for a label or description, 1,500 characters for a lone question and 3,000 for the questions and headers of a set, 1,200 characters per preview and 10,000 in all, 1,000 for an answer of their own or the note) is refused to the model with the reason and posts no card. `validateQuestionnaire` gives the reason. Since 0.20 the same option label twice in a question, or the same question twice in a call, is refused for every call; 0.19 accepted both.
+
+A surface says what it can show with `Prompts.asks` (`AskSupport`: `{ questions, previews, note }`) and, when it declares it, implements `Prompts.questionnaire(title, questionnaire, signal?, wait?)`, which resolves with a `QuestionnaireAnswer` (`answers`, one per question in order and `undefined` for one left blank, and `note`), `"pending"`, or `undefined` as `ask` does. Both members are optional: a `Prompts` without them is the 0.19 contract (`SINGLE_QUESTION`: one question, no previews, no note) and keeps working unchanged. The runtime gives `questionnaire` a set already shaped for `asks` (`shapeFor`), so a surface renders only what it declared:
+
+| The surface lacks | What the core does |
+|---|---|
+| room for the questions (`asks.questions`, or no `asks` at all) | asks them one at a time through `ask` and stops at the first one that does not come back answered; the model is told which were not asked |
+| `previews` | appends each preview to its question as `**label**` and a fenced block (a longer fence when the preview holds one), cut to the question limit with `…` |
+| a `header` (a surface that takes one question) | drops it; the tool description already asks that each question read on its own |
+| `note` | shows no note control, and the answer carries no `note` |
+
+One question without previews always goes through `ask` and returns the same text as 0.19. `checkAnswer` and `checkQuestionnaireAnswer` check that an answer is one the questions allow (offered labels only, one unless `multi`, text of their own only where `allowOther`); a surface that takes answers from a network uses them rather than its own rules. `describeSurfaceContract` runs the questionnaire checks (answered, blank question kept blank, closed on stop, a stranger's answer ignored) for a subject that gives `answerQuestionnaire(prompt, answer, questionnaire)`; a subject that gives it must declare `asks`, and the contract fails it otherwise.
+
+On Discord the whole set is one card (`asks` is four questions, previews and a note): a menu per question with its options (an option can be cleared again, and the menus show the draft), `Submit`, a button that opens one form with a field per question that takes written text plus the note, and, when an option has a preview, a `Previews` button that replies ephemerally to whoever presses it and answers nothing. A short footer outside the container says how many questions are answered. The draft is one per card, shared by everyone who may answer and visible to everyone who sees the card; the last write wins and the submitter is reported. Presses are checked against the same audience as any question each time (menus, form and Submit). `Submit` needs at least one answer or the note, and a partial answer is allowed. Every limit Discord enforces is counted in UTF-16 units, so an emoji weighs two: the core's refusal of an over-long set counts them too. With a `wait`, each draft edit restarts the grace period, and a `Submit` after the turn stopped waiting starts the late turn with a `questionnaire` `LateAnswer`. A single question keeps its 0.19 card (a menu answers at once; "Other…" opens the form, or, with 25 options plus `allow_other`, an `Answer…` button does), with a `Previews` button when an option has a preview. Open cards live in memory, as before.
+
+On the web chat the support is the least of the person's connections that declared theirs (`prompt_features`), so the assistant only sends a set a tab can show, and a person whose tabs all lack it is asked one question at a time. A questionnaire that no connection can show expires after 60 seconds: it settles unanswered, the model is told, and if it asks again it gets the one-at-a-time fallback. See the web chat package's README for the frames.
+
 #### Interim text: what a turn writes before its final answer
 
 A model often writes text in an assistant message that then calls tools, such as a proposal before it asks `ask_user` "go with this version?".
@@ -3400,11 +3436,12 @@ test("the production configuration registers every plugin", async () => {
 ### `describeSurfaceContract`: what every chat surface keeps
 
 A plugin that contributes a `ChatSurface` can test it against the contract every surface keeps.
-`describeSurfaceContract(name, make)` registers one test per check, each on a fresh `SurfaceContractSubject` from `make`: the `surface`, a `channel` of it, and one person on its network, who can `write(text)`, whose `observations()` list what they have seen (`SurfaceObservation`: a reply's text and file names, typing and stop controls going on and off, progress, and prompts opening and closing), and who may `answer(prompt, approved)` an approval; `speaker` is who they are to `surface.prompts`, given as `promptScope(speaker, visibility)`, an owner by default, and every approval the contract asks for needs exactly their tier. `stranger`, when given, is someone else on the network, another principal and not an owner, who knows the id of the person's open approval and may `join()` and `answer(prompt, approved)` it; `owner`, when given, is an owner on the network, another principal than the person, who does the same in the person's private conversation. Both are `SurfaceContractAnswerer`s. `approver`, when given, is a third person on the network with a `principalId`, not an owner and at the person's tier, whom the contract names in `approvers`; `privateOnly` marks a surface that serves only conversations private to one person, such as the web chat.
+`describeSurfaceContract(name, make)` registers one test per check, each on a fresh `SurfaceContractSubject` from `make`: the `surface`, a `channel` of it, and one person on its network, who can `write(text)`, whose `observations()` list what they have seen (`SurfaceObservation`: a reply's text and file names, typing and stop controls going on and off, progress, and prompts opening and closing), and who may `answer(prompt, approved)` an approval; `speaker` is who they are to `surface.prompts`, given as `promptScope(speaker, visibility)`, an owner by default, and every approval the contract asks for needs exactly their tier. `stranger`, when given, is someone else on the network, another principal and not an owner, who knows the id of the person's open approval and may `join()` and `answer(prompt, approved)` it; `owner`, when given, is an owner on the network, another principal than the person, who does the same in the person's private conversation. Both are `SurfaceContractAnswerer`s. `approver`, when given, is a third person on the network with a `principalId`, not an owner and at the person's tier, whom the contract names in `approvers`; `speakerOnly` marks a surface that honours `ApprovalOptions.speakerOnly` in a shared conversation, which the contract then checks with the `owner`; `privateOnly` marks a surface that serves only conversations private to one person, such as the web chat.
 The contract starts the surface, calls the subject's `join()`, and stops the surface after the subject's `close()`.
-It checks that the surface names a prefix and owns its channel, delivers what the person writes, and shows every chunk of a reply; and, for the parts the surface offers, that it delivers files when `supportsFiles` is set, ends typing and stop controls idempotently, shows progress, and resolves an approval as the person approves or declines it, or `cancelled` when the turn stops or its plugin withdraws it (`ApprovalOptions.supersede`; one answered first stays answered), with a `stranger`, that the stranger's answer leaves the person's approval open, and with an `owner`, that an owner's answer leaves it open in a private conversation; with an `approver` and a `stranger`, that an approval naming the approver is answered by the approver and not by the person or the stranger, unless the surface is `privateOnly`, and, with an `approver`, that a private conversation ignores the names; and, for a speaker below the owner tier, that a private conversation's approval above their tier resolves `unavailable` (or `expired`, as older surfaces answer) at once and is not shown.
+It checks that the surface names a prefix and owns its channel, delivers what the person writes, and shows every chunk of a reply; and, for the parts the surface offers, that it delivers files when `supportsFiles` is set, ends typing and stop controls idempotently, shows progress, and resolves an approval as the person approves or declines it, or `cancelled` when the turn stops or its plugin withdraws it (`ApprovalOptions.supersede`; one answered first stays answered), with a `stranger`, that the stranger's answer leaves the person's approval open, and with an `owner`, that an owner's answer leaves it open in a private conversation; with an `approver` and a `stranger`, that an approval naming the approver is answered by the approver and not by the person or the stranger, unless the surface is `privateOnly`, and, with an `approver`, that a private conversation ignores the names; with a `speakerOnly` subject and an `owner`, that an owner's answer leaves an approval that is the speaker's alone open in a shared conversation, unless the surface is `privateOnly`; and, for a speaker below the owner tier, that a private conversation's approval above their tier resolves `unavailable` (or `expired`, as older surfaces answer) at once and is not shown.
 A check for a part the surface does not offer passes.
 The contract has no check for `ApprovalDetails.copy`: a surface that shows it keeps it informational, so using it never resolves, approves or declines the prompt, whoever uses it.
+A subject that gives `answerQuestionnaire` (and a `stranger` that gives its own) must declare `asks` and also keeps the questionnaire checks.
 `checkSurfaceContract(make)` runs the same checks and returns the ones that failed, as `SurfaceContractFailure`s.
 
 ## What happens when the bot starts and stops
@@ -3665,6 +3702,7 @@ Import from the entries listed below; source area files are internal.
 | `ApprovalOptions` | `pi-roundtable` | type |
 | `ApprovedBy` | `pi-roundtable` | type |
 | `AskOption` | `pi-roundtable` | type |
+| `AskSupport` | `pi-roundtable` | type |
 | `AttachmentFailure` | `pi-roundtable` | type |
 | `AttachmentPort` | `pi-roundtable` | type |
 | `AttachmentRef` | `pi-roundtable` | type |
@@ -3793,6 +3831,9 @@ Import from the entries listed below; source area files are internal.
 | `Provisioning` | `pi-roundtable` | type |
 | `ProvisioningRule` | `pi-roundtable` | type |
 | `QueuePort` | `pi-roundtable` | type |
+| `QUESTIONNAIRE_LIMITS` | `pi-roundtable` | value |
+| `Questionnaire` | `pi-roundtable` | type |
+| `QuestionnaireAnswer` | `pi-roundtable` | type |
 | `Recurrence` | `pi-roundtable` | type |
 | `ReferenceImage` | `pi-roundtable` | type |
 | `ResolvedProviders` | `pi-roundtable` | type |
@@ -3825,6 +3866,7 @@ Import from the entries listed below; source area files are internal.
 | `PrecheckTool` | `pi-roundtable` | type |
 | `PRECHECK_SCRIPT_CHARS` | `pi-roundtable` | value |
 | `SKILLS` | `pi-roundtable` | value |
+| `SINGLE_QUESTION` | `pi-roundtable` | value |
 | `Schedule` | `pi-roundtable` | type |
 | `ScheduleChange` | `pi-roundtable` | type |
 | `ScheduleError` | `pi-roundtable` | value |
@@ -3886,6 +3928,7 @@ Import from the entries listed below; source area files are internal.
 | `Weekday` | `pi-roundtable` | type |
 | `attachReplyFile` | `pi-roundtable` | value |
 | `promptScope` | `pi-roundtable` | value |
+| `validateQuestionnaire` | `pi-roundtable` | value |
 | `withReplyFiles` | `pi-roundtable` | value |
 | `withdrawalNote` | `pi-roundtable` | value |
 | `prepareImageBytes` | `pi-roundtable/kit` | value |
@@ -3895,12 +3938,15 @@ Import from the entries listed below; source area files are internal.
 | `SquarePngOptions` | `pi-roundtable/kit` | type |
 | `scrubDiagnostic` | `pi-roundtable/kit` | value |
 | `channelKey` | `pi-roundtable` | value |
+| `checkAnswer` | `pi-roundtable` | value |
+| `checkQuestionnaireAnswer` | `pi-roundtable` | value |
 | `definePlugin` | `pi-roundtable` | value |
 | `defineRoundtable` | `pi-roundtable` | value |
 | `defineTool` | `pi-roundtable` | value |
 | `migrateDatabase` | `pi-roundtable` | value |
 | `parseChannelKey` | `pi-roundtable` | value |
 | `serviceKey` | `pi-roundtable` | value |
+| `shapeFor` | `pi-roundtable` | value |
 | `FakeDiscord` | `pi-roundtable/testing` | type |
 | `FakeThreadHost` | `pi-roundtable/testing` | type |
 | `OWNER_SPEAKER` | `pi-roundtable/testing` | value |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.19.2",
+	"version": "0.21.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",
@@ -26,6 +26,7 @@
 		"src",
 		"!src/**/*.test.ts",
 		"!src/core/testing/file-size.ts",
+		"!src/core/testing/discord-limits.ts",
 		"!src/core/testing/prompt-capture*.ts",
 		"!src/core/testing/discord-api-emulator*.ts",
 		"!src/core/discord/poster/poster-contract*.ts",

package/src/core/discord/card-audience.ts

@@ -58,7 +58,9 @@ export class CardAudiences {
 		scope: PromptScope | undefined,
 		minTier: Tier,
 		named?: readonly string[],
+		speakerOnly = false,
 	): Promise<Audience | undefined> {
+		if (speakerOnly) return this.#speakers(scope, minTier);
 		let approvers = named;
 		// A private conversation's person is the only one who answers, so a call naming others is theirs only if named or an owner.
 		if (approvers && scope?.escalate === "none") {
@@ -78,6 +80,51 @@ export class CardAudiences {
 		);
 	}
 
+	/**
+	 * The card of a call that is its speaker's alone (`ApprovalOptions.speakerOnly`): the scope's
+	 * principal on any of their Discord identities still theirs when they press, at the tier the
+	 * call needs, checked again then, and no owner as such, whatever the scope escalates to. The
+	 * primary owner answers their own card, and where there is no identity service the primary owner
+	 * is the only speaker who has one. Undefined, so the call is unavailable at once, when there is
+	 * no scope, or the speaker is below the tier or has no Discord identity.
+	 */
+	async #speakers(
+		scope: PromptScope | undefined,
+		minTier: Tier,
+	): Promise<Audience | undefined> {
+		if (!scope) return undefined;
+		const { ownerId, identity } = this.#options;
+		if (!identity) {
+			// Without an identity service the primary owner is the only one who answers, and the only speaker who can.
+			if (scope.speakerId !== ownerId) return undefined;
+			return {
+				allows: async (user) => user.id === ownerId,
+				mentions: [ownerId],
+				note: "",
+				refusal: messages().cardOwnerOnly,
+				approver: (user) => this.#approver(user),
+			};
+		}
+		const own = await this.#ownIdentities(scope, minTier);
+		if (!own) return undefined;
+		const mentions = own.includes(scope.speakerId) ? [scope.speakerId] : own;
+		const primary = own.includes(ownerId);
+		return {
+			allows: async (user) =>
+				own.includes(user.id) &&
+				// Read the links again: one moved or unlinked since the card was posted is no longer theirs.
+				(await this.#stillOwn(scope.principalId, user.id)) &&
+				((primary && user.id === ownerId) ||
+					(await this.#owners.holds(user, minTier, scope.principalId))),
+			mentions,
+			note: primary ? "" : messages().cardApproversNote(...mentions),
+			refusal: primary
+				? messages().cardOwnerOnly
+				: messages().cardApproversRefusal,
+			approver: (user) => this.#approver(user),
+		};
+	}
+
 	/** Who may answer a question; undefined when no one may. */
 	question(scope: PromptScope | undefined): Promise<Audience | undefined> {
 		return this.#audience(scope, undefined, {

package/src/core/discord/owner-card-answers.ts

@@ -0,0 +1,180 @@
+import { type Interaction, MessageFlags } from "discord.js";
+import { messages } from "../i18n/index.ts";
+import {
+	checkQuestionnaireAnswer,
+	type QuestionnaireAnswer,
+} from "../interactions/questionnaire.ts";
+import {
+	answerOf,
+	formFields,
+	previewReplies,
+	questionnaireModal,
+} from "./owner-card-questionnaire.ts";
+import {
+	answeredLine,
+	answerModal,
+	OTHER,
+	TEXT_FIELD,
+} from "./owner-card-rows.ts";
+import type { Answerer, OpenCard } from "./owner-card-types.ts";
+
+const ephemeral = (content: string) => ({
+	content,
+	flags: MessageFlags.Ephemeral as const,
+});
+
+/** The single-question card's controls: a menu pick, "Write answer…", and the answer form. */
+export async function answerSingle(
+	card: OpenCard,
+	id: string,
+	action: string,
+	interaction: Interaction,
+	by: Answerer,
+): Promise<void> {
+	const question = card.question;
+	if (!question) return;
+	if (interaction.isButton() && action === "write") {
+		card.picked = [];
+		await interaction.showModal(answerModal(id));
+		return;
+	}
+	if (interaction.isStringSelectMenu() && action === "pick") {
+		const values = interaction.values;
+		const choices = question.options.flatMap((option, i) =>
+			values.includes(String(i)) ? [option.label] : [],
+		);
+		if (values.includes(OTHER)) {
+			card.picked = choices;
+			await interaction.showModal(answerModal(id));
+			return;
+		}
+		const answer = { choices };
+		card.end(answer, by);
+		await interaction.update(card.view(answeredLine(answer)));
+		return;
+	}
+	if (interaction.isModalSubmit() && action === "text") {
+		const answer = {
+			choices: card.picked ?? [],
+			text: interaction.fields.getTextInputValue(TEXT_FIELD),
+		};
+		card.end(answer, by);
+		if (interaction.isFromMessage())
+			await interaction.update(card.view(answeredLine(answer)));
+		else await interaction.deferUpdate();
+	}
+}
+
+/** Previews answer nothing, so anyone who sees the card may open them. */
+export async function showPreviews(
+	card: OpenCard,
+	interaction: Interaction,
+): Promise<void> {
+	const source = card.form?.questionnaire ?? card.previews;
+	if (!interaction.isButton() || !source) return;
+	const [first, ...rest] = previewReplies(source);
+	if (first) await interaction.reply(first);
+	for (const page of rest) await interaction.followUp(page);
+}
+
+/** Ends the card with `answer`; false when another press or the plugin ended it first. */
+function finish(
+	card: OpenCard,
+	answer: QuestionnaireAnswer,
+	by: Answerer,
+): boolean {
+	const draft = card.form?.draft;
+	if (draft) {
+		for (const [i, a] of answer.answers.entries()) {
+			draft.choices[i] = [...(a?.choices ?? [])];
+			draft.texts[i] = a?.text;
+		}
+		if (answer.note !== undefined) draft.note = answer.note;
+	}
+	return card.end(answer, by);
+}
+
+/** The note an ended card shows as its footer: the draft's note, when it has one. */
+const endedFooter = (card: OpenCard) => {
+	const note = card.form?.draft.note?.trim();
+	return note ? messages().cardNoteLine(note) : "";
+};
+
+/**
+ * A menu pick, Submit or the submitted form of a questionnaire card. The press is deferred first
+ * (the audience lookup may take a while), then the audience and the card are checked: a refusal
+ * or a closed card changes nothing, and a refused pick re-draws the card so their menu resets.
+ */
+export async function answerDeferred(
+	card: OpenCard,
+	action: string,
+	index: number,
+	interaction: Interaction,
+	by: Answerer,
+): Promise<void> {
+	const form = card.form;
+	if (!form) return;
+	const picks = interaction.isStringSelectMenu() && action === "qpick";
+	const submits = interaction.isButton() && action === "submit";
+	const writes = interaction.isModalSubmit() && action === "qtext";
+	if (!picks && !submits && !writes) return;
+	await interaction.deferUpdate();
+	const fromMessage =
+		!interaction.isModalSubmit() || interaction.isFromMessage();
+	if (!(await card.audience.allows(by.user))) {
+		await interaction.followUp(ephemeral(card.audience.refusal));
+		if (picks && card.isOpen())
+			await interaction.editReply(card.view("", false));
+		return;
+	}
+	// Stopped, withdrawn or answered meanwhile: the closed card must not be drawn open again.
+	if (!card.isOpen()) {
+		await interaction.followUp(ephemeral(messages().cardInactive));
+		return;
+	}
+	const { questions } = form.questionnaire;
+	if (picks) {
+		const question = questions[index];
+		if (!question) return;
+		form.draft.choices[index] = question.options.flatMap((option, n) =>
+			interaction.values.includes(String(n)) ? [option.label] : [],
+		);
+	} else if (writes) {
+		const { texts, note } = formFields(form, (field) =>
+			interaction.fields.getTextInputValue(field),
+		);
+		for (const [i, value] of texts)
+			form.draft.texts[i] = value.trim() || undefined;
+		form.draft.note = note.trim() || undefined;
+	}
+	if (!submits) {
+		card.touch();
+		if (fromMessage) await interaction.editReply(card.view("", false));
+		return;
+	}
+	const answer = answerOf(form.draft);
+	if (!checkQuestionnaireAnswer(form.questionnaire, answer)) {
+		await interaction.followUp(ephemeral(messages().cardNothingYet));
+		return;
+	}
+	if (!finish(card, answer, by)) {
+		await interaction.followUp(ephemeral(messages().cardInactive));
+		return;
+	}
+	await interaction.editReply(card.view(endedFooter(card)));
+}
+
+/** "Write answers / note…": opens the form, which a modal cannot defer; the audience was checked. */
+export async function answerForm(
+	card: OpenCard,
+	id: string,
+	action: string,
+	interaction: Interaction,
+): Promise<void> {
+	if (!card.form || !interaction.isButton() || action !== "notes") return;
+	if (!card.isOpen()) {
+		await interaction.reply(ephemeral(messages().cardInactive));
+		return;
+	}
+	await interaction.showModal(questionnaireModal(id, card.form));
+}

package/src/core/discord/owner-card-asks.ts

@@ -0,0 +1,149 @@
+import { messages } from "../i18n/index.ts";
+import type {
+	OwnerAnswer,
+	PromptScope,
+	Prompts,
+} from "../interactions/prompts.ts";
+import type {
+	AskSupport,
+	QuestionnaireAnswer,
+} from "../interactions/questionnaire.ts";
+import type { CardAudiences } from "./card-audience.ts";
+import type { QuestionnaireForm } from "./owner-card-questionnaire.ts";
+import { newDraft, questionnaireCard } from "./owner-card-questionnaire.ts";
+import { askRows, previewsRow } from "./owner-card-rows.ts";
+import type { PostCard } from "./owner-card-types.ts";
+
+/** What the Discord card shows of a questionnaire: four questions, previews, and a note. */
+export const DISCORD_ASKS: AskSupport = {
+	questions: 4,
+	previews: true,
+	note: true,
+};
+
+/** A channel's question cards: one question on its own card, or up to four on one. */
+export function askPrompts(args: {
+	channelId: string;
+	scope: PromptScope | undefined;
+	audiences: CardAudiences;
+	post: PostCard;
+}): Pick<Prompts, "ask" | "asks" | "questionnaire"> {
+	const { channelId, scope, audiences, post } = args;
+	return {
+		asks: DISCORD_ASKS,
+		ask: async (title, question, signal, wait) => {
+			const audience = await audiences.question(scope);
+			if (!audience) return undefined;
+			return post<OwnerAnswer | "pending" | undefined>(
+				channelId,
+				signal,
+				undefined,
+				undefined,
+				{
+					audience,
+					...(wait
+						? {
+								wait: {
+									pending: "pending",
+									late: (value, by) =>
+										wait.late({
+											kind: "question",
+											answer: value as OwnerAnswer,
+											by: by.user.name,
+										}),
+								},
+							}
+						: {}),
+					title,
+					sections: [question.question],
+					question,
+					rows: (id, disabled) => askRows(id, question, disabled),
+					footer: messages().cardQuestionFooter,
+				},
+			);
+		},
+		questionnaire: async (title, questionnaire, signal, wait) => {
+			const audience = await audiences.question(scope);
+			if (!audience) return undefined;
+			const [only] = questionnaire.questions;
+			if (only && questionnaire.questions.length === 1) {
+				// One question is the 0.19 card, answered by one click, with a Previews button.
+				const answer = await post<OwnerAnswer | "pending" | undefined>(
+					channelId,
+					signal,
+					undefined,
+					undefined,
+					{
+						audience,
+						...(wait
+							? {
+									wait: {
+										pending: "pending",
+										late: (value, by) =>
+											wait.late({
+												kind: "questionnaire",
+												answer: { answers: [value as OwnerAnswer] },
+												by: by.user.name,
+											}),
+									},
+								}
+							: {}),
+						title,
+						sections: [only.question],
+						question: only,
+						previews: questionnaire,
+						rows: (id, disabled) => [
+							...askRows(id, only, disabled),
+							...(only.options.some((o) => o.preview !== undefined)
+								? [previewsRow(id, disabled)]
+								: []),
+						],
+						footer: messages().cardQuestionFooter,
+					},
+				);
+				return answer === "pending" || answer === undefined
+					? answer
+					: { answers: [answer] };
+			}
+			const form: QuestionnaireForm = {
+				questionnaire,
+				draft: newDraft(questionnaire.questions.length),
+			};
+			return post<QuestionnaireAnswer | "pending" | undefined>(
+				channelId,
+				signal,
+				undefined,
+				undefined,
+				{
+					audience,
+					...(wait
+						? {
+								wait: {
+									pending: "pending",
+									late: (value, by) =>
+										wait.late({
+											kind: "questionnaire",
+											answer: value as QuestionnaireAnswer,
+											by: by.user.name,
+										}),
+								},
+							}
+						: {}),
+					title,
+					sections: [],
+					form,
+					build: (id, footer, disabled) =>
+						questionnaireCard({
+							id,
+							title,
+							note: audience.note,
+							form,
+							disabled,
+							footer,
+						}),
+					footer: "",
+				},
+			);
+		},
+	};
+}