pi-roundtable-webchat 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-14
+
+Release in lockstep with pi-roundtable 0.15.0. The core peer range moves to `>=0.15.0 <0.16.0`.
+
+### Changed
+
+- The approval prompt's `message` is the card text the core builds, and for a tool whose parameter schema is known it is now a list of labelled fields in markdown (`**label**: value`, long and multi-line values in fenced blocks) instead of one JSON block; a client that read the JSON out of `message` should read `approval.input`, which is unchanged and whole. A tool without a schema keeps the JSON block.
+- `PromptOutcome` gains `withdrawn`: a client that switches over the outcomes must handle it (close the prompt as for `cancelled`).
+
+### Added
+
+- `prompt_closed` may carry the outcome `withdrawn` (new in `PromptOutcome`) and a `note`: the plugin that asked for an approval took it back (`ApprovalOptions.supersede`), and `note` is its reason, when it gave one as a text. The prompt is removed from the open ones a reconnect resends, and an answer to it finds `unknown_prompt`. A client that does not know the outcome should close the prompt as it does for `cancelled`. The turn reads a withdrawn approval as cancelled; the core tells the model it was withdrawn.
+- `client_call` may carry `approval: { prompt }` (`ClientCallOptions.approval` in the core): the id of the approval prompt the tool's call acts on, written into the frame unchanged when the tool passes one and absent otherwise. The server accepts a text of 1 to 128 characters and fails the call otherwise.
+
+## [0.14.1] - 2026-10-14
+
+- Release in lockstep with pi-roundtable 0.14.1; no package-specific behavior changes. The core peer range stays `>=0.14.0 <0.15.0`.
+
 ## [0.14.0] - 2026-10-14
 
 - Release in lockstep with pi-roundtable 0.14.0; no package-specific behavior changes. The core peer range moves to `>=0.14.0 <0.15.0`.

package/README.md

@@ -214,14 +214,14 @@ The TypeScript types are `ClientFrame` and `ServerFrame`.
 | `{ type: "accepted", id, conversation }` | Your message `id` was taken into `conversation`, a new one when you named none. |
 | `{ type: "typing", conversation, on }` | The assistant is, or is no longer, working in the conversation. |
 | `{ type: "stoppable", conversation, on }` | A stop applies, or no longer applies. |
-| `{ type: "progress", conversation, event }` | What the running turn writes and which tools it runs: `{ type: "text", delta }`, `{ type: "tool_start", id, tool, preview? }`, or `{ type: "tool_end", id, tool, ok, refused? }`. Never the thinking, never a tool's full arguments. A `tool_end` that a hold refused (not a real failure) has `ok: false` and `refused`: `declined` (turned down on its approval card), `expired` (a card was shown and went unanswered; the call is held for the next message), `pending` (the card is still open) or `held` (no card could be shown: the person's tier is below the call's, or it could not be posted; the call is held for the next message). `refused` is absent for a success and for a real failure. |
+| `{ type: "progress", conversation, event }` | What the running turn writes and which tools it runs: `{ type: "text", delta }`, `{ type: "tool_start", id, tool, preview? }`, or `{ type: "tool_end", id, tool, ok, refused? }`. Never the thinking, never a tool's full arguments. A `tool_end` that a hold refused (not a real failure) has `ok: false` and `refused`: `declined` (turned down on its approval card), `expired` (a card was shown and went unanswered; the call is held for the next message), `pending` (the card is still open), `withdrawn` (the plugin that held the call took it back) or `held` (no card could be shown: the person's tier is below the call's, or it could not be posted; the call is held for the next message). `refused` is absent for a success and for a real failure. |
 | `{ type: "reply", conversation, text, thinking?, files? }` | The turn's answer in full markdown, with its files inline as `{ name, data }` (base64). |
 | `{ type: "failed", conversation, stopped }` | The turn ended without an answer: it failed, the host refused it before it ran (for example when its conversation could not be recorded), or it was stopped. The cause stays in the host's log. |
 | `{ type: "prompt", conversation, prompt }` | The turn asks you: `{ id, kind: "approval", title, message, approval? }`, or `{ id, kind: "ask", title, question, options, multi, allowOther }`. |
-| `{ type: "prompt_closed", conversation, prompt, outcome }` | The prompt closed: `approved`, `declined`, `answered`, `expired`, or `cancelled` (the turn stopped). |
+| `{ type: "prompt_closed", conversation, prompt, outcome, note? }` | The prompt closed: `approved`, `declined`, `answered`, `expired`, `cancelled` (the turn stopped), or `withdrawn` (the plugin that asked took the approval back; `note` may carry its reason in a few words). |
 | `{ type: "notice", notice: { id, text, createdAt, readAt } }` | A durable private inbox entry; `readAt` is `null` until read. Fetch the REST inbox to recover entries missed while offline. |
 | `{ type: "reauth", expiresAt }` | Your token expires soon: send `auth` with a fresh one. |
-| `{ type: "client_call", conversation, call, name, args, timeoutMs }` | The assistant asks this connection, and no other, to run the function `name` it declared and to answer with `client_result` within `timeoutMs`. See [Client calls](#client-calls). |
+| `{ type: "client_call", conversation, call, name, args, timeoutMs, approval? }` | The assistant asks this connection, and no other, to run the function `name` it declared and to answer with `client_result` within `timeoutMs`. `approval` (`{ prompt }`) is present only when the tool that made the call named the approval it acts on: `prompt` is the `id` of the `prompt` frame (an approval card) the person approved. See [Client calls](#client-calls). |
 | `{ type: "client_cancel", call, reason }` | The call is no longer wanted (`turn_stopped`, `timeout`, or `turn_ended`): stop running it; an answer is dropped. |
 | `{ type: "error", code, ref? }` | A frame was refused. `ref` is the `send` id, prompt id or call id it was about. |
 
@@ -324,6 +324,8 @@ A client that can says so, and the assistant's tools then call it:
 3. The client runs the function and answers with `client_result` on the same connection. A binary result, such as a screenshot, does not fit a frame: it `PUT`s each part to `<path>/conversations/<conversation>/client-calls/<call>/parts/<n>` first (see the [REST API](#rest-api)), then names the count in `parts`.
 4. The tool gets `{ ok: true, value, parts }`, or `{ ok: false, error }`: `refused` or `failed` as the client reported, `timeout` (no answer in time; the client gets `client_cancel`), `cancelled` (the turn was stopped, or the client reported `stopped`; the client gets `client_cancel`), `disconnected` (the connection closed first), `too_large` (the `value` passed `maxValueBytes`), `busy` (a call is already open on this connection, or the connection was asked `perMinute` calls in the last minute), `no_client`, or `failed` for a bad argument or a part that did not arrive.
 
+A call may carry `approval: { prompt }`: a tool that acts on something the person approved on an approval card (`turn.approvedPrompt` in the core) passes that card's id, and the server writes it into the frame unchanged, after checking only that it is a text of 1 to 128 characters (otherwise the tool's call fails). The client, not the server, decides what it is worth: it compares `prompt` with the `prompt` frames it showed and the `approval` frames it sent, and refuses a function that needs an approval when the id is absent or is not one it sent as approved. A call whose tool names none has no `approval` field.
+
 This is the opposite of an approval card: a card goes to every connection of the person and survives a reconnect, a call goes to one connection, ends when it closes, and is never sent again after a reconnect. Only the connection a call was sent to may answer it, and only as the same person; an answer from another connection, even the same person's, gets `error` `unknown_call`. A part is accepted for an open call of that person and conversation, whose id only the right connection received.
 The `value`, the parts and the `message` come from the client, so the tool treats them as untrusted data; the server accepts only JSON of at most `maxValueBytes`, images of the three types whose bytes match, and a message cut to one plain line of 300 characters.
 Stopping the conversation, or the turn ending, cancels the call in flight.

package/package.json

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

package/src/client-calls.ts

@@ -47,6 +47,15 @@ function plain(text: string): string {
 
 const bytesOf = (text: string) => new TextEncoder().encode(text).length;
 
+/** The longest prompt id a call may name as its approval, as long as the ids a client may answer. */
+const APPROVAL_PROMPT_CHARS = 128;
+
+/** Whether `prompt` can be a prompt id: a text of 1 to 128 characters. */
+const validPrompt = (prompt: unknown): prompt is string =>
+	typeof prompt === "string" &&
+	prompt.length > 0 &&
+	prompt.length <= APPROVAL_PROMPT_CHARS;
+
 const failure = (
 	error: ClientCallError,
 	message: string,
@@ -208,6 +217,14 @@ export class ClientDesk {
 				"failed",
 				`the arguments must be JSON of at most ${MAX_ARGS_BYTES} bytes`,
 			);
+		const approval = options?.approval;
+		if (
+			approval !== undefined &&
+			(typeof approval !== "object" ||
+				approval === null ||
+				!validPrompt(approval.prompt))
+		)
+			return refuse("failed", "approval.prompt must be a prompt id");
 		if (this.#byConnection.has(connection))
 			return refuse("busy", "another call is open on this client");
 		let rate = this.#rates.get(connection);
@@ -277,6 +294,7 @@ export class ClientDesk {
 				name,
 				args: JSON.parse(argsJson),
 				timeoutMs,
+				...(approval ? { approval: { prompt: approval.prompt } } : {}),
 			});
 		});
 	}

package/src/prompts.ts

@@ -7,6 +7,7 @@ import {
 	type Prompts,
 	TIERS,
 	type Tier,
+	withdrawalNote,
 } from "pi-roundtable";
 import {
 	APPROVAL_MAX_BYTES,
@@ -28,7 +29,7 @@ interface Open {
 	frame: PromptFrame;
 	/** The lowest tier that may approve; questions have none. */
 	minTier?: Tier;
-	settle(outcome: PromptOutcome, answer?: OwnerAnswer): void;
+	settle(outcome: PromptOutcome, answer?: OwnerAnswer, note?: string): void;
 }
 
 export interface PromptDeskOptions {
@@ -69,6 +70,7 @@ export class PromptDesk {
 				minTier = "owner",
 				_wait,
 				details,
+				options,
 			) => {
 				if (!atLeast(scope.tier, minTier)) return "unavailable";
 				const outcome = await this.#ask(
@@ -83,6 +85,8 @@ export class PromptDesk {
 					}),
 					signal,
 					minTier,
+					options?.supersede,
+					options?.approvedPrompt,
 				);
 				return toApproval(outcome.outcome);
 			},
@@ -143,23 +147,38 @@ export class PromptDesk {
 		frameOf: (id: string) => PromptFrame,
 		signal: AbortSignal | undefined,
 		minTier?: Tier,
+		supersede?: AbortSignal,
+		approvedPrompt?: (prompt: string) => void,
 	): Promise<{ outcome: PromptOutcome; answer?: OwnerAnswer }> {
 		const { send, timeoutMs } = this.#options;
-		if (signal?.aborted) return Promise.resolve({ outcome: "cancelled" });
+		if (signal?.aborted || supersede?.aborted)
+			return Promise.resolve({ outcome: "cancelled" });
 		return new Promise((resolve) => {
 			const id = crypto.randomUUID();
 			const frame = frameOf(id);
 			const onAbort = () => settle("cancelled");
 			const timer = setTimeout(() => settle("expired"), timeoutMs);
-			const settle = (outcome: PromptOutcome, answer?: OwnerAnswer) => {
+			const onSupersede = () =>
+				supersede &&
+				settle("withdrawn", undefined, withdrawalNote(supersede, ""));
+			const settle = (
+				outcome: PromptOutcome,
+				answer?: OwnerAnswer,
+				note?: string,
+			) => {
+				// Whichever of an answer and a withdrawal comes first settles the prompt.
 				if (!this.#open.delete(id)) return;
+				// Heard before the approval resolves, so the call that runs on it can say which card it was.
+				if (outcome === "approved") approvedPrompt?.(id);
 				clearTimeout(timer);
 				signal?.removeEventListener("abort", onAbort);
+				supersede?.removeEventListener("abort", onSupersede);
 				send(principal, {
 					type: "prompt_closed",
 					conversation,
 					prompt: id,
 					outcome,
+					...(note ? { note } : {}),
 				});
 				resolve(answer ? { outcome, answer } : { outcome });
 			};
@@ -171,6 +190,7 @@ export class PromptDesk {
 				settle,
 			});
 			signal?.addEventListener("abort", onAbort, { once: true });
+			supersede?.addEventListener("abort", onSupersede, { once: true });
 			send(principal, { type: "prompt", conversation, prompt: frame });
 		});
 	}
@@ -266,7 +286,10 @@ function cutStrings(value: unknown, limit: number): unknown {
 
 function toApproval(outcome: PromptOutcome): Approval {
 	if (outcome === "approved" || outcome === "declined") return outcome;
-	return outcome === "cancelled" ? "cancelled" : "expired";
+	// A withdrawal is read as the turn's wait ending; the gate knows it was withdrawn.
+	return outcome === "cancelled" || outcome === "withdrawn"
+		? "cancelled"
+		: "expired";
 }
 
 function questionFrame(

package/src/protocol.ts

@@ -72,13 +72,17 @@ export type PromptFrame =
 			allowOther: boolean;
 	  };
 
-/** How a prompt closed. */
+/**
+ * How a prompt closed. `withdrawn` is an approval the plugin that asked for it took back; the
+ * frame may carry a short `note` saying why.
+ */
 export type PromptOutcome =
 	| "approved"
 	| "declined"
 	| "answered"
 	| "expired"
-	| "cancelled";
+	| "cancelled"
+	| "withdrawn";
 
 /** The most functions a client may declare. */
 export const MAX_CLIENT_TOOLS = 64;
@@ -236,6 +240,8 @@ export type ServerFrame =
 			conversation: string;
 			prompt: string;
 			outcome: PromptOutcome;
+			/** Why a `withdrawn` prompt was taken back, in the plugin's words; absent otherwise. */
+			note?: string;
 	  }
 	/** A durable private inbox entry; fetch the REST inbox to recover missed notices. */
 	| { type: "notice"; notice: Notice }
@@ -252,6 +258,11 @@ export type ServerFrame =
 			name: string;
 			args: unknown;
 			timeoutMs: number;
+			/**
+			 * The approval the call acts on, when the tool passed one: `prompt` is the id of the
+			 * `prompt` frame the person approved. Absent for a call that acts on no approval.
+			 */
+			approval?: { prompt: string };
 	  }
 	/** The call is no longer wanted: stop running it; any answer is dropped. */
 	| { type: "client_cancel"; call: string; reason: ClientCancelReason }