pi-roundtable 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-14
+
+### Added
+
+- `approvalCard(call, workspace?, limits?, parameters?)` (`pi-roundtable/kit`) takes the tool's parameter JSON Schema, and the confirmation gate passes the schema of the held tool, read from the session's tool list. With it the approval card shows the call as a field list instead of one JSON block: a line `**label**: value` per argument, in the order the schema declares its properties, labelled by the property's `title` or its name, absent arguments left out. An argument the schema does not list follows the listed ones with its name in code format, so it cannot pass for a declared label. Only an argument's own properties count: one named `toString` or `constructor` is shown with its value. A multi-line or long string (a lone `\r`, `\u2028`, `\u2029` and `\u0085` are line breaks too) and any nested value (as compact JSON) go in a fenced block that keeps their line breaks. A value on a line has its markdown, links and `@everyone`/`@here` escaped, as the model writes it; an array of scalars is joined with commas unless an item is empty, shows nothing, or holds a comma and a space or a line break, and then it is JSON; a string that is empty or shows nothing is written out (`""`, `"\u200b"`) so the person sees it is there. The `limits` apply as they did to the JSON: a long string is cut and marked `… [N chars]`, and fields that no longer fit are dropped and listed by label. A tool with no schema, or one that lists no properties, keeps the JSON block, as does a card built without `parameters` (the coding desk's).
+- A plugin can withdraw an approval card it caused. A hold answers `{ text, supersede: signal }` (`HoldDescription.supersede`; a tool's `hold` and a rule's `describeInTurn`), and aborting the signal closes the call's approval card, also after the turn stopped waiting and the card stayed open (the Discord message is edited: controls off, the abort reason as footer when it is a text, else "Withdrawn; nothing will run"; the web chat closes the prompt as `withdrawn` with the reason as `note`), forgets the held call so no later approval runs it (a card's late approval, a confirming message, and the saved held actions included), and tells a turn still waiting that the call was withdrawn (`refused: "withdrawn"` in `HoldRefusal`). Whichever of an approval and the abort comes first decides: an approval answered first runs the call once and the abort changes nothing, and an abort first wins whatever a surface then reports, a call it withdrew is never held again; aborting twice does nothing. Withdrawing removes every identical call (same tool, same canonical input) held for the conversation, whichever hold held it. Nothing stays listening once the call is released, refused, dropped, or its card failed. A signal does not survive a restart, so a withdrawal cannot reach a call held before one; a hold that answers an already aborted `supersede` when the call is repeated refuses it without a card and drops a confirmation of it. New in `pi-roundtable`: `ApprovalOptions.supersede` for surfaces (a surface closes the card when it aborts; a card that arrives with it aborted is not shown) and `withdrawalNote` (`withdrawalNote(signal, fallback)`), the footer from the reason.
+- `ToolTurn.approvedPrompt` (also `SessionContext.approvedPrompt(toolCallId)`): the id of the approval card that released the call a tool's `run` is making, for a tool that must show a client which approval it acts on. It is set when the person approved the held call on its card, in the turn that asked or, for a card answered after that turn stopped waiting, in the later turn whose call that approval releases; it is undefined for a call that was not held, one a message confirmed (also after a restart, which keeps no cards), one a surface released without a card id, and in a host with no turn. A surface reports it through `ApprovalOptions.approvedPrompt(prompt)` (called before `confirm` resolves `approved`; Discord reports the card id, the web chat the `prompt` frame's id) and `LateAnswer.prompt`; a surface whose cards have no stable id leaves both out.
+- `ClientCallOptions.approval?: { prompt: string }`: a tool names the approval a client call acts on, normally `{ prompt: turn.approvedPrompt }`, and the transport hands it to the client beside the call. The web chat writes it into the `client_call` frame as `approval: { prompt }` (a text of 1 to 128 characters, else the call fails); a call without it carries no field.
+
+### Changed
+
+- **Breaking for code that matches exhaustively:** `HoldRefusal` (a tool's end in `TurnProgress`) gains `"withdrawn"`, and the web chat's `PromptOutcome` gains `"withdrawn"` (with `prompt_closed.note`). A switch over either needs a case for it; a web chat client closes a withdrawn prompt as it does a cancelled one.
+- **Breaking for third-party surfaces:** `describeSurfaceContract` adds a check that an approval its plugin withdraws (`ApprovalOptions.supersede`) resolves `cancelled` and closes, that one answered first stays answered, and that one withdrawn before it opens is not shown. A surface with approval cards that does not implement `supersede` fails it; the gate still refuses a withdrawn call whatever such a surface reports.
+- The web chat's approval prompt `message`, and the text of the Discord card, show a held call as fields rather than a JSON block when the tool's parameter schema is known (see Added). `approval.input` and `ApprovalDetails` are unchanged.
+- `@babel/parser` and `@babel/types` move to Babel 8 (8.0.7 and 8.0.6), which read a schedule's precheck script and the files the boundary check scans. Import attributes (`with { type: "json" }`) are on by default there, and `importAttributes` is no longer a plugin name. Babel 8 packages need Node 22.18 or newer, or Bun.
+
 ## [0.14.1] - 2026-10-14
 
 ### Fixed

package/docs/plugins.md

@@ -627,7 +627,7 @@ Throw `ToolRefusal` for a call the model should correct; any other error fails t
 
 Some transports carry a client that can do something for a tool: the web chat's browser extension can read the page the person has open.
 `turn.client` is that client's `ClientPort` when the turn's transport provides one and the client declared it, and undefined otherwise (a Discord message, a schedule, an agent's turn, and a web chat connection that declared nothing have none), so a tool that needs it fails closed with a `ToolRefusal` when it is undefined.
-`client.names` lists the functions the client declared, and `client.call(name, args, { timeoutMs?, maxValueBytes? })` asks it to run one.
+`client.names` lists the functions the client declared, and `client.call(name, args, { timeoutMs?, maxValueBytes?, signal?, approval? })` asks it to run one. `approval: { prompt }` names the approval the call acts on, normally `{ prompt: turn.approvedPrompt }` for a tool whose hold the person approved: the transport hands it to the client beside the call (the web chat as `client_call.approval`, see its README), so a client can check that the person approved this very card before it acts. A call without `approval` carries no such field; the core does not judge it, the client does.
 The call never rejects for a transport problem: it resolves `{ ok: true, value, parts }`, with the value the client answered with and its binary `parts` (`{ mimeType, data }`, such as a screenshot), or `{ ok: false, error, message }` where `error` is `no_client`, `refused`, `timeout`, `cancelled`, `disconnected`, `too_large`, `busy`, or `failed`.
 One call is open on a client at a time: a second one made meanwhile resolves `busy`, so make calls one after another.
 The core gives every call the turn's `signal`, so stopping the turn cancels the call in flight (`cancelled`) and the tool need not handle it.
@@ -720,7 +720,9 @@ Transient `SessionContext.runTask` tasks return only text and cannot attach to t
 The model attaches a file it already has on disk with the core's `attach_file({ path, filename? })`. A session with a workspace (`SessionContext.workspace`, an agent's) registers it; the path must resolve, symlinks followed, inside the workspace or the scratch dir, a relative path resolves in the workspace, and `filename` defaults to the path's base name. It queues the file with `attachReplyFile`, so `REPLY_FILE_LIMITS` apply and a surface without reply files refuses it as a tool error; its result tells the model the file will appear with its reply. It holds nothing, since it only posts in the channel the turn answers in, and its tier defaults to the owner, like any tool the core's table does not name.
 
 With an `images` provider, agent and owner sessions also offer the core's `generate_image({ prompt, reference_paths? })`, which draws a new picture from a description (`prompt`, at most 4,000 characters). `reference_paths` lists up to 4 local images, checked like `attach_file` paths (inside the workspace or the scratch dir, symlinks followed, regular files only), each a PNG, JPEG, WebP or GIF by content, at most 20 MiB each and 40 MiB together; a refused reference is a tool error before the provider is called. It passes them to the provider as `ReferenceImage`s with the turn's signal, saves the picture under `<scratch dir or workspace>/drawings/generated-<ISO time>.<ext>`, and attaches it with `attachReplyFile`; when it cannot be attached the file is kept and the result says so. The result names the saved path, never the bytes, so the model can send it on or edit it. A provider error, such as a refusal, is a tool error carrying the provider's message. It holds nothing, and its tier defaults to the owner; `toolTiers` lowers it. The agents' prompt mentions it only when it is offered.
-The Discord tools that upload, `discord_send_message` and `discord_edit_message`, take each file as exactly one of `path` (a local file, read when the call runs, with the same roots; `filename` defaults to its base name) or `dataBase64` with a `filename`, at most 8 MiB in all. A session without a workspace takes only `dataBase64`, and so does remote MCP, whose schemas stay inline only. A path outside the roots, a missing file, or a directory is a tool error naming the path. A held call's card (`approvalCard(call, workspace?, limits?)`) lists each file it sends by path with the file's size now, never its bytes, and shows an input within `limits.totalChars` (1,500) whole; a longer input has its string values cut, longest first and never below `limits.valueChars` (200), to their start plus `… [N chars]` (N in code points) until it fits, and if it still does not, the rest is dropped and the keys no longer shown are listed. `approvalDetails(call, workspace?)` gives the same call as data (`{ action, tool, input, files? }`, the whole input, files as `{ path, bytes? }`); the gate passes it to `Prompts.confirm` as `details`, for a surface that is not text.
+The Discord tools that upload, `discord_send_message` and `discord_edit_message`, take each file as exactly one of `path` (a local file, read when the call runs, with the same roots; `filename` defaults to its base name) or `dataBase64` with a `filename`, at most 8 MiB in all. A session without a workspace takes only `dataBase64`, and so does remote MCP, whose schemas stay inline only. A path outside the roots, a missing file, or a directory is a tool error naming the path. A held call's card (`approvalCard(call, workspace?, limits?, parameters?)`) lists each file it sends by path with the file's size now, never its bytes, and shows an input within `limits.totalChars` (1,500) whole; a longer input has its string values cut, longest first and never below `limits.valueChars` (200), to their start plus `… [N chars]` (N in code points) until it fits, and if it still does not, the rest is dropped and the keys no longer shown are listed. `approvalDetails(call, workspace?)` gives the same call as data (`{ action, tool, input, files? }`, the whole input, files as `{ path, bytes? }`); the gate passes it to `Prompts.confirm` as `details`, for a surface that is not text.
+
+Given `parameters`, the tool's JSON Schema, `approvalCard` shows the input as fields instead of JSON, and the gate does so for every tool the session lists (it reads the schema from the tool list of the Pi session): one line or block per argument, in the order the schema declares its properties (an argument the schema does not list follows them, its name in code format so it cannot pass for a declared label), labelled by the property's `title` or else its name, absent arguments left out; only an argument's own properties count, so one named `toString` or `constructor` is shown with its value. A short value sits on the line (`**label**: value`, with markdown, links and `@everyone`/`@here` in it escaped so nothing in a model-written value formats or mentions anyone); a string with a line break or over 100 characters, and a nested value as compact JSON, go in a fenced block that keeps their line breaks and in which nothing is markdown (`\r`, `\u2028`, `\u2029` and `\u0085` are line breaks too); booleans, numbers and enum values show as they are; an array of scalars is joined with commas, unless an item is empty, shows nothing, holds a comma and a space or a line break, in which case the array is shown as JSON; a string that is empty or shows nothing (white space, zero-width characters) is written out as a quoted, escaped text, such as `""`, so the person sees it is there. `limits` apply as they do to the JSON: a long string is cut, the longest first and never below `limits.valueChars`, marked `… [N chars]`, and when that is not enough the last fields are dropped and their labels listed. A tool with no schema, or one that lists no properties (and a card a plugin builds without `parameters`, such as the coding desk's), shows the JSON as before. The card is text, so every surface that shows `message` shows the fields; `approvalDetails` is unchanged.
 Calling the helper outside `context.turns.run` or an agent-team turn, or after that turn finishes, throws `ReplyFileError`; direct standalone runtime calls have no reply collector.
 Await work that produces files before returning from the tool.
 A standalone isolated worker may wrap its complete awaited turn in `withReplyFiles(supported, run)` from the main entry.
@@ -826,6 +828,32 @@ hold: async ({ customer, body }, turn) => ({
 
 `text` is the description, with every behaviour above; `copy` goes to the gate's `ApprovalDetails.copy` for that call, so the Discord card gets the [copy button](#who-answers-a-prompt-promptscope) with all of its limits (the 20,000 character cap, the label, `discord.cardCopies`), and the web chat forwards it as `approval.copy`. It is part of the same answer, so a rejection, a throw or a timeout drops it with the description: the call is held under the generic description with no copy, and the exact input is still on the card. A `copy` whose `text` is not a non-empty string is left out and the call is still held. The copy is not kept with the held call (`HeldCall` has no copy), so a card the owner answers by a message after a restart has no button, and a host that shows no card, or that checks the hold with no turn, such as a precheck script's call, uses `text` and ignores `copy`. A hold that answers a plain string is unchanged. The copy is visible to anyone who sees the card, so it holds nothing they may not read.
 
+#### Withdrawing a held call
+
+A hold that no longer wants a call it held, because a newer request replaced it or its subject is gone, withdraws it by answering `{ text, supersede }` with an `AbortSignal` of its own and aborting the signal when the time comes (`HoldDescription.supersede`, beside `copy`; a tool's `hold` and a rule's `describeInTurn` both may):
+
+```ts
+const replaced = new AbortController();
+hold: (args) => ({ text: `send ${args.to} the quote`, supersede: replaced.signal }),
+// later, when a newer quote for the same customer replaces it:
+replaced.abort("replaced by a newer quote");
+```
+
+Aborting does four things, whichever way the call was held, and the abort reason, when it is a text, is the footer the closed card shows (`withdrawalNote(signal, fallback)` gives the one-line text, cut to 200 characters; any other reason, and no reason, gives `fallback`):
+
+- Its approval card closes: controls off and the footer instead of "answer whenever you are ready", **also after the turn stopped waiting** (the card then stays open for as long as the process runs, and now closes by itself). On Discord the message is edited; on the web chat the prompt closes with the outcome `withdrawn` and the reason as `note`. A card that arrives with the signal already aborted is not shown. A surface implements this through `ApprovalOptions.supersede`, which the contract checks (`describeSurfaceContract`: an approval its plugin withdraws resolves `cancelled` and closes, and one answered first stays answered).
+- The held call is forgotten: it leaves the held actions (saved so, if it was held for a message), and an approval of the identical call that has not been spent yet, on the card late, or by a confirming message, no longer releases it. A repeated call is described by the hold anew.
+- A turn still waiting on the card is told the call was withdrawn (progress reports `refused: "withdrawn"`), not that it was declined or stopped. It does not retry.
+- A late answer to the closed card, or a press that was being checked when the signal aborted, answers nothing and starts no turn.
+
+**One outcome.** Withdrawing and approving are the two ways a held call leaves "may run", and the first one wins. An approval that was answered before the abort stands: the call runs once, or has run, and the abort changes nothing, the card keeps its answered footer. An abort that came first wins whatever the card then reports, also on a surface that ignores `supersede`, since the gate decides, not the card. Aborting twice, after the call ran, or after the card was declined does nothing. A call approved late but not made yet is withdrawable until the call is made.
+
+**Identical calls.** A held call is identified by its tool and its canonical input, as everywhere in the gate. Withdrawing a call therefore removes every identical call held for the conversation, including one that another hold (another tool's rule, or a second request from the same plugin) held with the same tool and input, and an approval that is waiting for it. A plugin that needs to withdraw one of two identical requests apart from the other gives the calls different inputs.
+
+**Nothing leaks.** The gate listens to the signal only while the call can still run: from the hold until it is released, refused, or no longer held (the next turn that does not confirm it drops it); a gate that is dropped with its conversation stops listening. A signal that is never aborted keeps nothing alive after that.
+
+**After a restart.** A signal does not survive one, so a withdrawal cannot reach a call held before it: the stored call stays held, a confirming message still releases it, and its card (open cards are in memory) is gone anyway. The hold is what decides then: it describes the repeated call again, and a hold that answers with an already aborted `supersede` refuses the call without opening a card, drops a confirmation of it, and tells the model it was withdrawn. That is how a plugin withdraws what a restart left held.
+
 A rule of `holdRules` does the same with `describeInTurn(tool, input, context, turn)`, which may return a promise, and a `HoldDescription` as well as a string, and which the gate asks instead of `describe` in a turn.
 `describe` is still required and is what a host without a turn sees. `holdChain(rules).inTurn(tool, input, context, turn)` asks the rules as a turn does, in order: each rule's `describeInTurn`, or its `describe` for a rule without one.
 
@@ -869,6 +897,8 @@ defineTool({
 
 `run` learns who approved: `turn.approvedBy` is `{ principalId, speakerId, name, owner? }` of the person who pressed the card, or whose message confirmed the call, and the same for a card answered after the turn stopped waiting. It is undefined for a call that was not held, and for a call a surface released without saying who (the web chat does not, for a call that names no approvers); a tool that must know the approver fails closed when it is undefined. `name` is the name the person's identity goes by on the surface, which they may change: look the sender up by `principalId`. `owner` is true when they approved as an owner. A surface reports it through `ApprovalOptions.approvedBy` of `Prompts.confirm`, and `LateAnswer.approvedBy`; for a call that names approvers it must, because the runtime accepts an approval from a named principal or an `owner` only: in a shared conversation an approval that does not say who gave it leaves the call held.
 
+`run` also learns which card approved: `turn.approvedPrompt` is the id of the approval card whose answer released the call, for a tool that must show a client which approval it acts on (it passes it as `approval: { prompt }` in the options of `turn.client.call`). It is set when the person approved the held call on its card, in the turn that asked, or, for a card answered after that turn stopped waiting, in the later turn whose call that approval releases. It is undefined for a call that was not held; for one a message confirmed (no card was involved, and a restart keeps no cards); for one a surface released without a card id; and in a host with no turn, such as a precheck script's call. Discord's id is the one in the custom ids of its card buttons (`roundtable:card:<id>:yes`), the web chat's is the `id` of the `prompt` frame, and a surface reports it through `ApprovalOptions.approvedPrompt` of `Prompts.confirm` and `LateAnswer.prompt`. It comes from the surface, never from the model or the message text; a tool that needs it fails closed when it is undefined.
+
 #### The shell rule
 
 `shellHoldRule` in `pi-roundtable/kit` judges the agents' `bash`, `write` and `edit` calls; the agent server links it, and a session without a workspace has no shell.
@@ -2563,7 +2593,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`. A surface may ignore both 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)), 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.
 
@@ -2571,11 +2601,11 @@ A surface or a `Prompts` of your own may ignore it: nothing requires reading it.
 It is informational and never an answer: using it does not approve, decline or otherwise settle the prompt, and a surface that cannot show it ignores it, as the web chat's own client does (the frame carries it as `approval.copy`, left out when it would not fit beside the call's `input` in the frame's 256 KiB: the input is never cut for it).
 On Discord the card gets a third button (`label`, default "Copy", or its Traditional Chinese equivalent on a host in that language) that any member who can see the card may press, any number of times, also after the card has ended; it replies ephemerally with the text in a code block, or as a `copy.txt` file when the text does not fit a message (2,000 characters) or holds a code fence. The button's custom id holds the card's id, never the text: the text is kept under that id in `card-copies.json` in the host's `dataDir`, in plain text and readable by the host's user only, so the button works after a restart even though the card itself no longer answers; a card whose text is gone says so. `discord.cardCopies` (`{ keepDays?, keep? }`, default the newest 100 cards for 30 days) sets how long and how many; `false` keeps the texts in memory only, with the same limits, so they are gone at a restart. The file is written in the background, one write at a time, so a card is not held up by it. A text past `keepDays` leaves the file too, not only memory: when the host starts or a button finds one expired, and on an hourly sweep that does not keep the process alive. The attachments' `retention` and discarding a conversation do not remove the texts: they age out, or set `cardCopies` to `false` on a host that wants none on disk: the host then deletes an existing `card-copies.json` when it starts. A text over 20,000 characters gets no button, and a warning is logged.
 Because anyone who can see the card can copy the text, it holds nothing they may not read.
-`confirm` resolves `approved`, `declined`, `expired` (a card was shown and went unanswered), `unavailable` (no card could be shown: no one may approve the call, the speaker is below its tier, or the card could not be posted), `cancelled` (the turn stopped), or `pending` (with a `wait`). Both `expired` and `unavailable` leave the call held for the owner's next message; the turn's progress reports them as `refused: "expired"` and `refused: "held"`.
+`confirm` resolves `approved`, `declined`, `expired` (a card was shown and went unanswered), `unavailable` (no card could be shown: no one may approve the call, the speaker is below its tier, or the card could not be posted), `cancelled` (the turn stopped, or the plugin that held the call withdrew it through `ApprovalOptions.supersede`), or `pending` (with a `wait`). Both `expired` and `unavailable` leave the call held for the owner's next message; the turn's progress reports them as `refused: "expired"` and `refused: "held"`.
 
 #### 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? }`, `approvedBy` naming the approver where the surface knows them, 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, or `{ kind: "question", answer, by }`, `by` naming who answered) 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.
@@ -2739,7 +2769,7 @@ export class FakeSurface implements ChatSurface {
 					TIERS.indexOf(scope.tier) >= TIERS.indexOf(minTier);
 				const principals = shared ?? (theirs ? [scope.principalId] : []);
 				if (principals.length === 0 && !owners) return "unavailable";
-				return this.#ask(channel, title, signal, {
+				return this.#ask(channel, title, [signal, options?.supersede], {
 					principals,
 					owners,
 					...(shared ? { minTier } : {}),
@@ -2787,9 +2817,12 @@ export class FakeSurface implements ChatSurface {
 	#ask(
 		channel: ChannelKey,
 		title: string,
-		signal: AbortSignal | undefined,
+		// The turn's stop and the plugin's withdrawal of the call both close the prompt as cancelled.
+		closers: (AbortSignal | undefined)[],
 		audience: Omit<Answering, "settle">,
 	): Promise<Approval> {
+		if (closers.some((closer) => closer?.aborted))
+			return Promise.resolve("cancelled");
 		const asked = {
 			id: `q${this.asked.length + 1}`,
 			channel,
@@ -2804,9 +2837,10 @@ export class FakeSurface implements ChatSurface {
 				resolve(answer);
 			};
 			this.#answering.set(asked.id, { ...audience, settle });
-			signal?.addEventListener("abort", () => settle("cancelled"), {
-				once: true,
-			});
+			for (const closer of closers)
+				closer?.addEventListener("abort", () => settle("cancelled"), {
+					once: true,
+				});
 		});
 	}
 }
@@ -3249,7 +3283,7 @@ It returns:
 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.
 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, 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; 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.
 `checkSurfaceContract(make)` runs the same checks and returns the ones that failed, as `SurfaceContractFailure`s.
@@ -3730,6 +3764,7 @@ Import from the entries listed below; source area files are internal.
 | `attachReplyFile` | `pi-roundtable` | value |
 | `promptScope` | `pi-roundtable` | value |
 | `withReplyFiles` | `pi-roundtable` | value |
+| `withdrawalNote` | `pi-roundtable` | value |
 | `prepareImageBytes` | `pi-roundtable/kit` | value |
 | `ImagePreparationError` | `pi-roundtable/kit` | value |
 | `squarePng` | `pi-roundtable/kit` | value |

package/examples/fake-surface.ts

@@ -124,7 +124,7 @@ export class FakeSurface implements ChatSurface {
 					TIERS.indexOf(scope.tier) >= TIERS.indexOf(minTier);
 				const principals = shared ?? (theirs ? [scope.principalId] : []);
 				if (principals.length === 0 && !owners) return "unavailable";
-				return this.#ask(channel, title, signal, {
+				return this.#ask(channel, title, [signal, options?.supersede], {
 					principals,
 					owners,
 					...(shared ? { minTier } : {}),
@@ -172,9 +172,12 @@ export class FakeSurface implements ChatSurface {
 	#ask(
 		channel: ChannelKey,
 		title: string,
-		signal: AbortSignal | undefined,
+		// The turn's stop and the plugin's withdrawal of the call both close the prompt as cancelled.
+		closers: (AbortSignal | undefined)[],
 		audience: Omit<Answering, "settle">,
 	): Promise<Approval> {
+		if (closers.some((closer) => closer?.aborted))
+			return Promise.resolve("cancelled");
 		const asked = {
 			id: `q${this.asked.length + 1}`,
 			channel,
@@ -189,9 +192,10 @@ export class FakeSurface implements ChatSurface {
 				resolve(answer);
 			};
 			this.#answering.set(asked.id, { ...audience, settle });
-			signal?.addEventListener("abort", () => settle("cancelled"), {
-				once: true,
-			});
+			for (const closer of closers)
+				closer?.addEventListener("abort", () => settle("cancelled"), {
+					once: true,
+				});
 		});
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.14.1",
+	"version": "0.15.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",
@@ -58,15 +58,15 @@
 		"check:packages": "bun run --workspaces typecheck && bun run --workspaces lint && bun run --workspaces --sequential test"
 	},
 	"dependencies": {
-		"@babel/parser": "7.29.9",
-		"@babel/types": "7.29.8",
+		"@babel/parser": "8.0.7",
+		"@babel/types": "8.0.6",
 		"@earendil-works/pi-ai": ">=0.99.2 <2",
 		"@earendil-works/pi-coding-agent": ">=0.99.2 <2",
 		"canvas": "3.2.3",
 		"discord.js": "14.27.0",
 		"pi-jev-compaction": "1.0.0",
 		"pi-mcp-adapter": "5.0.0",
-		"pino": "10.3.1",
+		"pino": "10.4.0",
 		"typebox": "1.3.34",
 		"unpdf": "1.8.1"
 	},

package/src/core/define.ts

@@ -50,6 +50,17 @@ export interface ToolTurn {
 	 * that must know the approver fails closed when it is undefined.
 	 */
 	approvedBy?: ApprovedBy;
+	/**
+	 * The id of the approval card that released this call, for a tool that must show a client which
+	 * approval it acts on (pass it as `ClientCallOptions.approval.prompt`). Set when the person
+	 * approved the held call on its card (Discord's card id, the web chat's `prompt` id), in the turn
+	 * that asked or, for a card answered after that turn stopped waiting, when a later turn makes
+	 * the identical call. Undefined for a call that ran without a hold, one a message confirmed
+	 * (including after a restart, which keeps no cards), one a surface released without a card id,
+	 * and in a turn that has no gate, such as a precheck script's call; a tool that needs it fails
+	 * closed. It is never from the model or the message text.
+	 */
+	approvedPrompt?: string;
 	/**
 	 * What the client that started the turn can do for this tool, such as run a function in the
 	 * browser the person chats from; undefined for a turn whose transport gives none, such as a
@@ -117,6 +128,10 @@ export interface ToolSpec<Schema extends TObject> {
 	 * answer as the description, so it shares its wait and its failure: a hold that rejects or
 	 * outlasts the timeout holds the call with the generic description and no copy. A host with no
 	 * card, or that checks the hold with no turn, uses `text` and ignores `copy`.
+	 *
+	 * It may add `supersede`, an `AbortSignal` the plugin aborts to withdraw the call it held (a
+	 * newer request replaced it): the card closes, the held call is forgotten, and an approval after
+	 * that runs nothing; see `HoldDescription`.
 	 */
 	hold?: (
 		args: Static<Schema>,

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

@@ -9,7 +9,11 @@ import {
 	TextInputStyle,
 } from "discord.js";
 import { messages } from "../i18n/index.ts";
-import type { OwnerAnswer, OwnerQuestion } from "../interactions/prompts.ts";
+import {
+	type OwnerAnswer,
+	type OwnerQuestion,
+	withdrawalNote,
+} from "../interactions/prompts.ts";
 import { type ownerPanel, plain } from "./owner-panel.ts";
 
 /** The prefix of every card control's custom id. */
@@ -96,3 +100,42 @@ export function answeredLine(answer: OwnerAnswer): string {
 	];
 	return messages().cardAnswered(parts);
 }
+
+/** An approval's controls: run, cancel, and, when the card offers a copy, a copy button that stays usable once it ended. */
+export function approvalRows(
+	id: string,
+	disabled: boolean,
+	copy: { label: string } | undefined,
+): Rows {
+	return [
+		new ActionRowBuilder<ButtonBuilder>().addComponents(
+			new ButtonBuilder()
+				.setCustomId(`${CARD_PREFIX}${id}:yes`)
+				.setLabel(messages().cardRunLabel)
+				.setEmoji("✅")
+				.setStyle(ButtonStyle.Success)
+				.setDisabled(disabled),
+			new ButtonBuilder()
+				.setCustomId(`${CARD_PREFIX}${id}:no`)
+				.setLabel(messages().cardCancelLabel)
+				.setEmoji("❌")
+				.setStyle(ButtonStyle.Secondary)
+				.setDisabled(disabled),
+			// Copying answers nothing, so it stays usable once the card has ended.
+			...(copy
+				? [
+						new ButtonBuilder()
+							.setCustomId(`${CARD_PREFIX}${id}:copy`)
+							.setLabel(copy.label)
+							.setEmoji("📋")
+							.setStyle(ButtonStyle.Secondary),
+					]
+				: []),
+		),
+	];
+}
+
+/** The footer of a card its plugin withdrew: the reason it gave as plain text, or that the call was withdrawn. */
+export function withdrawnFooter(signal: AbortSignal): string {
+	return plain(withdrawalNote(signal, messages().cardWithdrawn));
+}

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

@@ -60,9 +60,10 @@ export interface OpenCard {
 	rows(disabled: boolean): Rows;
 	/**
 	 * Ends the card with its answer; the answering interaction shows the outcome. A card whose
-	 * turn stopped waiting starts a turn with the answer instead.
+	 * turn stopped waiting starts a turn with the answer instead. False when the card had ended
+	 * already, answered by another press or withdrawn by its plugin, and this answer changed nothing.
 	 */
-	end(value: unknown, by: Answerer): void;
+	end(value: unknown, by: Answerer): boolean;
 	question?: OwnerQuestion;
 	/** Options chosen together with "Other…", kept while its form is open. */
 	picked?: string[];

package/src/core/discord/owner-cards.ts

@@ -1,12 +1,5 @@
 import { randomUUID } from "node:crypto";
-import {
-	ActionRowBuilder,
-	ButtonBuilder,
-	ButtonStyle,
-	type Interaction,
-	MessageFlags,
-	TextDisplayBuilder,
-} from "discord.js";
+import { type Interaction, MessageFlags, TextDisplayBuilder } from "discord.js";
 import { parseChannelKey } from "../contract/surface.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import { messages } from "../i18n/index.ts";
@@ -30,11 +23,13 @@ import type { InteractionModule } from "./interaction-module.ts";
 import {
 	answeredLine,
 	answerModal,
+	approvalRows,
 	askRows,
 	CARD_PREFIX,
 	OTHER,
 	type Rows,
 	TEXT_FIELD,
+	withdrawnFooter,
 } from "./owner-card-rows.ts";
 import type {
 	Answerer,
@@ -158,52 +153,26 @@ export class OwnerCards implements InteractionModule {
 							? {
 									wait: {
 										pending: "pending",
-										late: (value, by) =>
+										late: (value, by, prompt) =>
 											wait.late({
 												kind: "approval",
 												approved: value === "approved",
 												by: by.user.name,
 												...(by.approver ? { approvedBy: by.approver } : {}),
+												prompt,
 											}),
 									},
 								}
 							: {}),
-						...(options?.approvedBy
-							? {
-									approved: (by: Answerer) => {
-										if (by.approver) options.approvedBy?.(by.approver);
-									},
-								}
-							: {}),
+						approved: (by: Answerer, prompt: string) => {
+							if (by.approver) options?.approvedBy?.(by.approver);
+							options?.approvedPrompt?.(prompt);
+						},
 						title,
 						sections: [message],
+						...(options?.supersede ? { supersede: options.supersede } : {}),
 						...(copy ? { copy: copy.text } : {}),
-						rows: (id, disabled) => [
-							new ActionRowBuilder<ButtonBuilder>().addComponents(
-								new ButtonBuilder()
-									.setCustomId(`${CARD_PREFIX}${id}:yes`)
-									.setLabel(messages().cardRunLabel)
-									.setEmoji("✅")
-									.setStyle(ButtonStyle.Success)
-									.setDisabled(disabled),
-								new ButtonBuilder()
-									.setCustomId(`${CARD_PREFIX}${id}:no`)
-									.setLabel(messages().cardCancelLabel)
-									.setEmoji("❌")
-									.setStyle(ButtonStyle.Secondary)
-									.setDisabled(disabled),
-								// Copying answers nothing, so it stays usable once the card has ended.
-								...(copy
-									? [
-											new ButtonBuilder()
-												.setCustomId(`${CARD_PREFIX}${id}:copy`)
-												.setLabel(copy.label)
-												.setEmoji("📋")
-												.setStyle(ButtonStyle.Secondary),
-										]
-									: []),
-							),
-						],
+						rows: (id, disabled) => approvalRows(id, disabled, copy),
 						footer: messages().cardApprovalFooter,
 					},
 				);
@@ -257,19 +226,26 @@ export class OwnerCards implements InteractionModule {
 			sections: string[];
 			/** The text behind the card's copy button, kept under the card's id. */
 			copy?: string;
+			/** Closes the card, also after its turn stopped waiting, when it aborts; see `ApprovalOptions.supersede`. */
+			supersede?: AbortSignal;
 			question?: OwnerQuestion;
 			rows(id: string, disabled: boolean): Rows;
 			footer: string;
 			wait?: {
 				pending: T;
-				late(value: unknown, by: Answerer): ReturnType<PromptWait["late"]>;
+				late(
+					value: unknown,
+					by: Answerer,
+					prompt: string,
+				): ReturnType<PromptWait["late"]>;
 			};
 			/** Hears who approved the card, before it resolves approved in its turn. */
-			approved?(by: Answerer): void;
+			approved?(by: Answerer, prompt: string): void;
 		},
 	): Promise<T> {
 		const { logger, graceMs = CARD_GRACE_MS, resume } = this.#options;
-		if (signal?.aborted) return Promise.resolve(cancelled);
+		if (signal?.aborted || card.supersede?.aborted)
+			return Promise.resolve(cancelled);
 		const wait = resume ? card.wait : undefined;
 		const id = randomUUID();
 		if (card.copy !== undefined) this.#copies.remember(id, card.copy);
@@ -282,20 +258,23 @@ export class OwnerCards implements InteractionModule {
 			let finish: string | undefined;
 			/** The turn went on without the answer; the card is the conversation's now. */
 			let late = false;
+			/** Shows the card as ended with `footer`, or once it is posted. */
+			const close = (footer: string) => {
+				finish = footer;
+				void message
+					?.edit(view(footer))
+					.catch((error: unknown) =>
+						logger.warn({ channelId, err: error }, "card not closed"),
+					);
+			};
 			const settle = (value: T, outcome: string | undefined) => {
 				if (!this.#open.delete(id)) return;
 				clearTimeout(timer);
 				signal?.removeEventListener("abort", abort);
+				card.supersede?.removeEventListener("abort", withdraw);
 				if (late) return;
 				// A card ended by an answer is edited by the answering interaction.
-				if (outcome !== undefined) {
-					finish = outcome;
-					void message
-						?.edit(view(outcome))
-						.catch((error: unknown) =>
-							logger.warn({ channelId, err: error }, "card not closed"),
-						);
-				}
+				if (outcome !== undefined) close(outcome);
 				resolve(value);
 			};
 			const view = (footer: string, disabled = true) =>
@@ -310,6 +289,14 @@ export class OwnerCards implements InteractionModule {
 					card.audience.mentions,
 				);
 			const abort = () => settle(cancelled, messages().cardStopped);
+			/** The plugin withdrew the call: the card closes, its turn waiting or not, unless an answer came first. */
+			const withdraw = () => {
+				if (!this.#open.delete(id) || !card.supersede) return;
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", abort);
+				close(withdrawnFooter(card.supersede));
+				if (!late) resolve(cancelled);
+			};
 			const timer = wait
 				? setTimeout(() => {
 						if (!this.#open.has(id)) return;
@@ -319,19 +306,22 @@ export class OwnerCards implements InteractionModule {
 					}, graceMs)
 				: undefined;
 			signal?.addEventListener("abort", abort, { once: true });
+			card.supersede?.addEventListener("abort", withdraw, { once: true });
 			const open: OpenCard = {
 				title: card.title,
 				sections,
 				rows: (disabled) => card.rows(id, disabled),
 				audience: card.audience,
 				end: (value, by) => {
+					// Withdrawn or answered already: this answer changes nothing.
+					if (!this.#open.has(id)) return false;
 					const answeredLate = late;
-					if (value === "approved" && !answeredLate) card.approved?.(by);
+					if (value === "approved" && !answeredLate) card.approved?.(by, id);
 					settle(value as T, undefined);
-					if (!answeredLate || !wait || !resume) return;
+					if (!answeredLate || !wait || !resume) return true;
 					try {
-						const text = wait.late(value, by);
-						if (text === undefined) return;
+						const text = wait.late(value, by, id);
+						if (text === undefined) return true;
 						resume({
 							channelId,
 							messageId: by.messageId ?? `card-${id}`,
@@ -343,6 +333,7 @@ export class OwnerCards implements InteractionModule {
 					} catch (error) {
 						logger.warn({ channelId, err: error }, "late card answer lost");
 					}
+					return true;
 				},
 				...(card.question ? { question: card.question } : {}),
 			};
@@ -453,10 +444,18 @@ export class OwnerCards implements InteractionModule {
 						return undefined;
 					})
 				: undefined;
-			card.end(
+			const accepted = card.end(
 				approved ? "approved" : "declined",
 				approver ? { ...by, approver } : by,
 			);
+			// The plugin withdrew the call, or another press answered, while this one was being checked.
+			if (!accepted) {
+				await interaction.reply({
+					content: messages().cardInactive,
+					flags: MessageFlags.Ephemeral,
+				});
+				return true;
+			}
 			await interaction.update(
 				closed(approved ? messages().cardApproved : messages().cardDeclined),
 			);

package/src/core/domain/client.ts

@@ -39,6 +39,13 @@ export interface ClientCallOptions {
 	 * need not pass the turn's signal; the core adds it to every call.
 	 */
 	signal?: AbortSignal;
+	/**
+	 * The approval this call acts on, for a client that must check the person approved it: `prompt`
+	 * is the id of the approval card (`ToolTurn.approvedPrompt`). The transport hands it to the
+	 * client beside the call; a tool passes it only when it has one, so a call without it carries
+	 * no approval. The client, not the core, decides whether it satisfies the function.
+	 */
+	approval?: { prompt: string };
 }
 
 /**

package/src/core/domain/progress.ts

@@ -10,9 +10,15 @@
  * the owner turned down from a call that failed: `declined` on its approval card, `expired` when
  * a card was shown and went unanswered (the call is held for the owner's next message),
  * `pending` while the card stays open, and `held` when no card could be shown (no one may approve
- * it, or it could not be posted; the call waits for the owner's next message). A turn that was stopped is none of these.
+ * it, or it could not be posted; the call waits for the owner's next message), and `withdrawn` when the
+ * plugin that held it withdrew it (`HoldDescription.supersede`). A turn that was stopped is none of these.
  */
-export type HoldRefusal = "declined" | "expired" | "pending" | "held";
+export type HoldRefusal =
+	| "declined"
+	| "expired"
+	| "pending"
+	| "held"
+	| "withdrawn";
 
 export type TurnProgress =
 	| { type: "text"; delta: string }