pi-roundtable-webchat 0.9.9 → 0.9.11

package/CHANGELOG.md

@@ -5,6 +5,26 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.11] - 2026-10-11
+
+### Added
+
+- Client calls: a connection may declare functions it can run for the assistant's tools, and a tool asks it through `turn.client` (`ClientPort`, new in pi-roundtable 0.9.11; this package needs pi-roundtable 0.9.11 with it, because its source imports types that release adds, so upgrade the two together; on an older core at run time the field is ignored and tools see no client). The client sends `client_hello` (`{ version: 1, tools }`); a call becomes `client_call` (`{ conversation, call, name, args, timeoutMs }`) on the one connection the turn's message arrived on, never the person's others, and is answered with `client_result` (`{ call, ok, value, parts? }` or `{ call, ok: false, code, message? }`) from that same connection; `client_cancel` (`turn_stopped`, `timeout` or `turn_ended`) tells the client to stop. A connection that never sends `client_hello` is unaffected: its turns carry no client.
+- `PUT <path>/conversations/<id>/client-calls/<call>/parts/<n>`: the binary parts of an answer, such as a screenshot, are uploaded over REST before the answer names them, since a frame stays at 64 KiB. Only `image/jpeg`, `image/png` and `image/webp` are accepted, with their bytes checked against the type.
+- `ready.clientCalls` (`{ timeoutMs, maxTimeoutMs, maxValueBytes, maxParts, maxPartBytes }`) advertises what a call may take; a server before this omits it. The error code `unknown_call` answers a `client_result` for a call not open on that connection.
+- `limits.clientCalls`: `timeoutMs` (default 30 seconds), `maxTimeoutMs` (60 seconds), `maxValueBytes` (48 KiB), `maxParts` (2), `maxPartBytes` (2 MiB) and `perMinute` (60 calls a minute per connection; the configuration is refused when it reaches the `rate` frame rate, since each answer is a frame). `ClientCallLimits` types it. One call is open on a connection at a time; a closed connection ends its call as `disconnected`, with no second chance after a reconnect.
+
+### Changed
+
+- The default `rate.messages` is 120 frames a minute per socket, up from 60, since a client's answers count with the person's own frames. `maxMessageBytes` stays 64 KiB.
+- The REST preflight also allows `PUT`.
+
+## [0.9.10] - 2026-10-10
+
+### Added
+
+- A turn run for a message carries the `Origin` header its connection's upgrade was accepted with, as `origin` on `context.turns.run`, so a tool reads it as `ToolTurn.origin`. It is trimmed and lower-cased and kept only when it is a serialized `scheme://host[:port]` of at most 256 characters; a connection that sent none, or an `Origin` of another shape, leaves it undefined. It is read from the transport at the upgrade, never from a frame or the message text. Needs pi-roundtable 0.9.10 or later to reach tools; on an older core the extra field is ignored.
+
 ## [0.9.9] - 2026-10-10
 
 ### Added

package/README.md

@@ -169,6 +169,9 @@ The token is never read from a URL.
 - **Another client**, such as a service, sends `Authorization: Bearer <token>` on the upgrade and offers `roundtable.webchat.v1`.
 
 The server echoes `roundtable.webchat.v1`.
+The `Origin` an accepted upgrade carried is kept on the connection, trimmed and lower-cased, and each message's turn passes it to the core as `origin`, so a tool reads it as `turn.origin` (for example to write where an issue was filed from).
+It is read from the transport only, never from a frame or the message text.
+A client that sent none, which only a route with `origins: "any"` admits, or a header that is not a serialized `scheme://host[:port]`, leaves `turn.origin` undefined; a tool that needs it should fail closed then.
 An upgrade from an origin not in `origins`, or without one, is refused with 403; without a valid ticket or token with 401; for a person the core policy does not admit with 403; past the person's connection limit with 429.
 
 ```js
@@ -200,12 +203,14 @@ The TypeScript types are `ClientFrame` and `ServerFrame`.
 | `{ type: "approval", prompt, approved }` | Approves or declines an approval prompt. |
 | `{ type: "answer", prompt, choices, text? }` | Answers a question prompt: the chosen options' labels, and your own text where the question allows it. |
 | `{ type: "auth", token }` | A fresh token for the same person, sent after `reauth`. |
+| `{ type: "client_hello", version: 1, tools }` | Declares the functions this connection can run for the assistant's tools, such as reading the page the person has open: up to 64 names, each lowercase words joined by underscores. Send it after each `ready`. See [Client calls](#client-calls). |
+| `{ type: "client_result", call, ok: true, value, parts? }` or `{ type: "client_result", call, ok: false, code, message? }` | The answer to a `client_call`: the JSON `value` and how many binary `parts` were uploaded first, or a failure `code` (`refused`, `failed`, `timeout`, or `stopped`) with a short `message`. |
 
 ### Server frames
 
 | Frame | Meaning |
 |---|---|
-| `{ type: "ready", protocol, speaker, personas, attachments, expiresAt }` | Sent first, and again after a fresh token: who you are (`{ id, name, tier, principalId }`), the personas you may open (`{ kind, label }`), what an upload may be (`attachments`: `{ maxBytes, perMessage, types }`), and when the token expires. Open prompts follow it. |
+| `{ type: "ready", protocol, speaker, personas, attachments, clientCalls, expiresAt }` | Sent first, and again after a fresh token: who you are (`{ id, name, tier, principalId }`), the personas you may open (`{ kind, label }`), what an upload may be (`attachments`: `{ maxBytes, perMessage, types }`), what a client call may take (`clientCalls`, below; absent from a server before 0.9.11, which never sends calls), and when the token expires. Open prompts follow it. |
 | `{ type: "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. |
@@ -216,7 +221,9 @@ The TypeScript types are `ClientFrame` and `ServerFrame`.
 | `{ type: "prompt_closed", conversation, prompt, outcome }` | The prompt closed: `approved`, `declined`, `answered`, `expired`, or `cancelled` (the turn stopped). |
 | `{ 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: "error", code, ref? }` | A frame was refused. `ref` is the `send` id or prompt id it was about. |
+| `{ 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_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. |
 
 An approval prompt's `message` is the card as markdown, as it always was, and its long input values are cut there (each marked with its length). `approval`, when present, is the same approval as data, so a client need not read it back out of the markdown:
 
@@ -234,7 +241,7 @@ approval?: {
 
 The frame's size is bounded: when `approval` serialized as UTF-8 JSON would pass 256 KiB (`APPROVAL_MAX_BYTES` in `protocol.ts`), every string value of `input` longer than what fits is cut to its start plus `… [N chars]` (N counts code points; a cut never splits a surrogate pair) and `approval.truncated` is `true`. Then `input` is no longer whole: show `message`, or tell the person it is cut. If even the shortest cut cannot fit, `input` is `{}` and `files` are left out.
 
-Error codes: `bad_frame` (it does not parse, its text is blank or too long, or an answer the question does not allow), `unknown_conversation`, `forbidden` (someone else's conversation or prompt, or an approval above your tier), `unknown_persona` (none of that kind you may open), `unknown_prompt`, `too_many_conversations` (you hold `unusedConversationsPerPrincipal` conversations you have not written in, or opened `newConversationsPerHour` in the last hour), `unknown_attachment` (a `send` named a file that is not waiting for you in that conversation: never uploaded, uploaded to another conversation, already used by a message, or deleted after its time; the whole message is refused and nothing is run), `attachment_quota` (the files would take what your messages keep past `usedAttachmentBytesPerPrincipal`; the whole message is refused and the files stay waiting), and `busy` (you have `turnsPerPrincipal` turns running or queued, or the conversation already has a turn queued behind its running one; the message was not taken, so send it again once a turn ends).
+Error codes: `bad_frame` (it does not parse, its text is blank or too long, or an answer the question does not allow), `unknown_conversation`, `forbidden` (someone else's conversation or prompt, or an approval above your tier), `unknown_persona` (none of that kind you may open), `unknown_prompt`, `too_many_conversations` (you hold `unusedConversationsPerPrincipal` conversations you have not written in, or opened `newConversationsPerHour` in the last hour), `unknown_attachment` (a `send` named a file that is not waiting for you in that conversation: never uploaded, uploaded to another conversation, already used by a message, or deleted after its time; the whole message is refused and nothing is run), `attachment_quota` (the files would take what your messages keep past `usedAttachmentBytesPerPrincipal`; the whole message is refused and the files stay waiting), `unknown_call` (a `client_result` named a call that is not open on this connection: it ended, was answered already, or was sent to another connection), and `busy` (you have `turnsPerPrincipal` turns running or queued, or the conversation already has a turn queued behind its running one; the message was not taken, so send it again once a turn ends).
 
 Close codes: `4401` when the token expired without a fresh `auth`, or a fresh one was refused; `4403` when the person is no longer admitted, or a fresh token names someone else.
 The host's own limits close with `1008` (too many frames), `1009` (a frame too big), and `1006` (a client that stopped reading).
@@ -250,6 +257,7 @@ A request from a browser origin not in `origins` gets 403; an allowed origin get
 | `GET <path>/conversations` | `{ conversations: [{ conversation, persona, title?, createdAt, lastActiveAt }] }`: your own, the most recently active first. |
 | `POST <path>/conversations` with `{ persona, title? }` | 201 `{ conversation, persona }`: a new conversation to write in. 429 `too_many_conversations` past either conversation limit. |
 | `POST <path>/conversations/<conversation>/files?name=<file name>` with the file's bytes as the body and its type as `Content-Type` | 201 `{ file, name, contentType, size }`: the file waits for your next message that names `file`. 400 `bad_request` (no name, or a name over 255 characters), 403 (not your conversation), 404 (unknown conversation), 413 `payload_too_large`, 415 `unsupported_media_type`, 429 `too_many_uploads`. See [Attachments](#attachments). |
+| `PUT <path>/conversations/<conversation>/client-calls/<call>/parts/<n>` with the part's bytes as the body and an image type as `Content-Type` | 201 `{ part: n }`: part `n` (0-based) of the answer to an open [client call](#client-calls). 400 `bad_request` (`n` is not below `maxParts`), 403 (not your conversation), 404 `unknown_call` (not open, not yours, or not in that conversation), 409 `duplicate_part`, 413 `payload_too_large`, 415 `unsupported_media_type` (not `image/jpeg`, `image/png` or `image/webp`, or bytes that are not the type). |
 | `GET <path>/conversations/<conversation>/messages?limit=50` | `{ messages: [{ role, text }] }`: its last messages, at most 500. Someone else's conversation is 403. |
 | `GET <path>/notices?limit=50&before=<id>` | `{ notices: [{ id, text, createdAt, readAt }] }`: only your principal's entries on this surface, newest first, at most 100. Omit `before` for the first page; use its last id to fetch the next. |
 | `POST <path>/notices/<id>/read` | `{ notice }` with `readAt` set. Idempotent; unknown ids or another principal's notice return 404. |
@@ -306,6 +314,24 @@ This needs a pi-roundtable release that has `attachments.retention`; on an earli
 Uploads are as private as the transcript: files sit in the host's data directory under the private conversation, where the owner and the operator can read them, as they can the transcript.
 Only the person who uploaded a file can use it, and only in the conversation it was uploaded to; a shared conversation (one recorded for no one in particular) takes no uploads.
 
+## Client calls
+
+A tool may need something only the person's own client can do, such as a browser extension reading the page they have open.
+A client that can says so, and the assistant's tools then call it:
+
+1. After `ready`, the client sends `client_hello` with the names of the functions it can run (`ready.clientCalls` says the server supports calls; a server before 0.9.11 omits it, so show no such feature then). A connection that declares none is never asked anything, and its turns carry no client: `turn.client` is undefined for a tool, which should fail closed.
+2. A message sent on that connection starts a turn whose tools read `turn.client` (`ClientPort`: `names` and `call(name, args, { timeoutMs?, maxValueBytes? })`). A call becomes a `client_call` frame **on the connection that sent the message, and on no other connection of the person**; an old client that never sent `client_hello` is unaffected.
+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.
+
+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.
+
+Client calls need pi-roundtable 0.9.11 or later: the source of this package uses types that release adds, so type-check both together and upgrade them together.
+
+`ready.clientCalls` is `{ timeoutMs, maxTimeoutMs, maxValueBytes, maxParts, maxPartBytes }`; `limits.clientCalls` sets them and `perMinute` (below).
+
 ## Security model
 
 - **Private conversations.** A conversation belongs to the person who opened it.
@@ -324,6 +350,7 @@ Only the person who uploaded a file can use it, and only in the conversation it
 - **Uploads.** Only a conversation's own person may upload to it, a file waits for that person and conversation alone, and a message names it by an id nobody can guess.
   Type, size, rate and the waiting total are limited per person, and the bytes of an image or PDF are checked against the type.
   See [Attachments](#attachments).
+- **Client calls.** A call goes only to the connection that started the turn and is answered only by that same connection and person, so another tab, another device, or another person cannot answer it or add a part. Each connection has one call open at a time and `perMinute` calls a minute; an answer is bounded in bytes and a part's bytes are checked against its image type. A connection that declared nothing is never asked.
 - **Approvals.** A held call's card goes to the conversation's person only, and needs the tier the call needs.
   A card whose tier the person lacks is never shown: its prompt resolves `unavailable` (no frame is sent), without owner escalation.
 - **Owner.** Nobody becomes the owner through a token's claims; grant owner in core configuration or the principal CLI.
@@ -342,7 +369,13 @@ Only the person who uploaded a file can use it, and only in the conversation it
 | `reauthLeadMs` | `reauth` 60 seconds before the token expires |
 | `maxConnections` | 256 sockets on the route |
 | `maxMessageBytes` | 64 KiB per client frame |
-| `rate` | 60 frames a minute per socket |
+| `rate` | 120 frames a minute per socket |
+| `clientCalls.timeoutMs` | 30 seconds a [client call](#client-calls) waits for its answer unless the tool names a time |
+| `clientCalls.maxTimeoutMs` | 60 seconds, the longest any call waits |
+| `clientCalls.maxValueBytes` | 48 KiB of JSON in an answer's `value`, under `maxMessageBytes` |
+| `clientCalls.maxParts` | 2 binary parts per answer (at most 16) |
+| `clientCalls.maxPartBytes` | 2 MiB per part (at most 16 MiB) |
+| `clientCalls.perMinute` | 60 calls a minute per connection; it must be under the `rate` frame rate, since each answer is a frame |
 | `maxBufferedBytes` | 4 MiB waiting for a slow client |
 | `ticketTtlMs` | 30 seconds |
 | `attachmentBytes` | 10 MiB per uploaded file; never above the core's 25 MiB |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-webchat",
-	"version": "0.9.9",
+	"version": "0.9.11",
 	"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",
@@ -43,7 +43,7 @@
 		"@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.9.9",
+		"pi-roundtable": "0.9.11",
 		"typebox": "1.3.34",
 		"typescript": "7.0.2"
 	}

package/src/chat.ts

@@ -22,6 +22,7 @@ import {
 	type TurnResult,
 } from "pi-roundtable";
 import { RateWindow, TurnBudget } from "./budget.ts";
+import { type ClientCallLimits, ClientDesk } from "./client-calls.ts";
 import { type Connection, Connections } from "./connections.ts";
 import {
 	identityActor,
@@ -78,6 +79,8 @@ export interface WebChatLimits extends UploadLimits {
 	promptTimeoutMs: number;
 	/** How long before a token expires the client is asked for a fresh one; default 60 seconds. */
 	reauthLeadMs: number;
+	/** What the assistant's tools may ask a client that declared functions to run. */
+	clientCalls: ClientCallLimits;
 }
 
 export interface WebChatDeps {
@@ -112,6 +115,10 @@ interface Minted {
 
 interface Pending {
 	speaker: Speaker;
+	/** The connection the message arrived on, which a call the turn makes to its client goes to. */
+	connection: Connection;
+	/** The origin of the connection the message arrived on. */
+	origin?: string;
 	persona: WebPersona;
 	title: string;
 	/** The files the message references, moved into the conversation when it was accepted. */
@@ -192,6 +199,8 @@ export class WebChat {
 	readonly uploads: Uploads;
 	readonly connections: Connections;
 	readonly desk: PromptDesk;
+	/** The calls the assistant's tools make to the client that started their turn. */
+	readonly clients: ClientDesk;
 	readonly #deps: WebChatDeps;
 	readonly #personas: Map<string, WebPersona>;
 	/** Conversations opened but not yet written in, so the registry has no record of them. */
@@ -231,6 +240,11 @@ export class WebChat {
 			send,
 			timeoutMs: deps.limits.promptTimeoutMs,
 		});
+		this.clients = new ClientDesk({
+			limits: deps.limits.clientCalls,
+			send: (connection, frame) => this.connections.send(connection, frame),
+			...(deps.now ? { now: deps.now } : {}),
+		});
 		this.surface = new WebSurface({
 			surface: deps.surface,
 			principalOf: (conversation) => this.#owners.get(conversation),
@@ -353,6 +367,28 @@ export class WebChat {
 		);
 	}
 
+	/**
+	 * Keeps a binary part of the answer to a call the assistant made to the speaker's client, for the
+	 * conversation it was made in; a Refusal when the conversation is not theirs, a ClientPartRefusal
+	 * when the part is not accepted.
+	 */
+	async clientPart(
+		speaker: Speaker,
+		conversation: string,
+		call: string,
+		index: number,
+		request: Request,
+	): Promise<void> {
+		await this.own(speaker, conversation);
+		await this.clients.receivePart(
+			speaker.principalId,
+			conversation,
+			call,
+			index,
+			request,
+		);
+	}
+
 	/** The speaker's web conversations, the most recently active first. */
 	async list(speaker: Speaker): Promise<ConversationRecord[]> {
 		const records = await this.#deps
@@ -396,6 +432,7 @@ export class WebChat {
 			speaker: { ...speaker },
 			personas: this.personasFor(speaker),
 			attachments: this.uploads.advertised,
+			clientCalls: this.clients.advertised,
 			expiresAt: identity.expiresAt.toISOString(),
 		});
 		for (const frame of this.desk.openFor(speaker.principalId))
@@ -435,6 +472,7 @@ export class WebChat {
 	}
 
 	closed(socket: RouteSocket<Connection>): void {
+		this.clients.closed(socket.data);
 		this.connections.closed(socket.data);
 	}
 
@@ -458,7 +496,9 @@ export class WebChat {
 					? frame.id
 					: frame.type === "approval" || frame.type === "answer"
 						? frame.prompt
-						: undefined;
+						: frame.type === "client_result"
+							? frame.call
+							: undefined;
 			this.connections.send(connection, {
 				type: "error",
 				code: error.code,
@@ -507,6 +547,14 @@ export class WebChat {
 				if (refused) throw new Refusal(refused);
 				return;
 			}
+			case "client_hello":
+				connection.clientTools = frame.tools;
+				return;
+			case "client_result": {
+				const refused = this.clients.result(connection, frame);
+				if (refused) throw new Refusal(refused);
+				return;
+			}
 			case "answer": {
 				const refused = this.desk.answer(speaker, frame.prompt, {
 					choices: frame.choices,
@@ -600,6 +648,8 @@ export class WebChat {
 		const messageId = crypto.randomUUID();
 		this.#pending.set(messageId, {
 			speaker,
+			connection,
+			...(connection.origin ? { origin: connection.origin } : {}),
 			persona,
 			title: minted?.title ?? titleOf(text),
 			fresh: record === undefined,
@@ -800,30 +850,38 @@ export class WebChat {
 					throw new Refusal("forbidden");
 			}
 			this.#registered.add(channel);
-			await this.#deps.turns().run({
-				channel,
-				kind: persona.kind,
-				text,
-				speaker,
-				interactive: true,
-				...(pending.attachments ? { attachments: pending.attachments } : {}),
-				...(persona.selection
-					? {
-							selection: {
-								id: `webchat:${persona.kind}`,
-								...persona.selection,
-							},
-						}
-					: {}),
-				conversation: {
-					visibility: "private",
-					...(pending.fresh && pending.title ? { title: pending.title } : {}),
-				},
-				reply: async (result) => {
-					answered = true;
-					this.#reply(speaker.principalId, conversation, result);
-				},
-			});
+			// What the connection that sent the message can do for the turn's tools, until the turn ends.
+			const client = this.clients.portFor(pending.connection, conversation);
+			try {
+				await this.#deps.turns().run({
+					channel,
+					kind: persona.kind,
+					text,
+					speaker,
+					...(pending.origin ? { origin: pending.origin } : {}),
+					...(client ? { client } : {}),
+					interactive: true,
+					...(pending.attachments ? { attachments: pending.attachments } : {}),
+					...(persona.selection
+						? {
+								selection: {
+									id: `webchat:${persona.kind}`,
+									...persona.selection,
+								},
+							}
+						: {}),
+					conversation: {
+						visibility: "private",
+						...(pending.fresh && pending.title ? { title: pending.title } : {}),
+					},
+					reply: async (result) => {
+						answered = true;
+						this.#reply(speaker.principalId, conversation, result);
+					},
+				});
+			} finally {
+				client?.end();
+			}
 		} catch (error) {
 			// A turn the host refused before it ran, such as one whose conversation could not be
 			// recorded, has no reply: the person is told it failed, and the router logs the cause.

package/src/client-calls.ts

@@ -0,0 +1,407 @@
+import type {
+	ClientCallError,
+	ClientCallOptions,
+	ClientCallResult,
+	ClientPart,
+	ClientPort,
+} from "pi-roundtable";
+import { RateWindow } from "./budget.ts";
+import type { Connection } from "./connections.ts";
+import { baseType, bytesMatchType } from "./file-types.ts";
+import type {
+	ClientCallsAdvertised,
+	ClientCancelReason,
+	ClientFailure,
+	ClientFrame,
+	ErrorCode,
+	ServerFrame,
+} from "./protocol.ts";
+import { readLimited } from "./uploads.ts";
+
+/** The limits of the calls the assistant's tools make to a client. */
+export interface ClientCallLimits extends ClientCallsAdvertised {
+	/** Calls one connection may be asked to run in any minute; default 60. */
+	perMinute: number;
+}
+
+/** The types a binary part may be: the images a model reads, as a screenshot is. */
+const PART_TYPES = ["image/jpeg", "image/png", "image/webp"];
+/** The most bytes of the arguments a call carries (UTF-8, as JSON). */
+const MAX_ARGS_BYTES = 16 * 1024;
+/** The most characters of a client's failure message a tool sees. */
+const MESSAGE_CHARS = 300;
+const MINUTE_MS = 60_000;
+
+/** Control characters, line and paragraph separators, and bidi controls: none reaches a tool as it is. */
+const UNSAFE_CHARS =
+	/[\p{Cc}\p{Zl}\p{Zp}\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu;
+
+/** `text` on one plain line, cut to `MESSAGE_CHARS` characters. */
+function plain(text: string): string {
+	const line = text.replace(UNSAFE_CHARS, " ").replace(/ +/g, " ").trim();
+	const points = Array.from(line);
+	return points.length > MESSAGE_CHARS
+		? points.slice(0, MESSAGE_CHARS).join("")
+		: line;
+}
+
+const bytesOf = (text: string) => new TextEncoder().encode(text).length;
+
+const failure = (
+	error: ClientCallError,
+	message: string,
+): ClientCallResult => ({
+	ok: false,
+	error,
+	message,
+});
+
+/** How each failure a client reports reads to a tool. */
+const REPORTED: Record<ClientFailure, ClientCallError> = {
+	refused: "refused",
+	failed: "failed",
+	timeout: "timeout",
+	stopped: "cancelled",
+};
+
+/** Why a binary part was refused, as the HTTP status and error code the client reads. */
+export class ClientPartRefusal extends Error {
+	override name = "ClientPartRefusal";
+	readonly status: number;
+	readonly code:
+		| "unknown_call"
+		| "bad_request"
+		| "duplicate_part"
+		| "payload_too_large"
+		| "unsupported_media_type";
+
+	constructor(status: number, code: ClientPartRefusal["code"]) {
+		super(code);
+		this.status = status;
+		this.code = code;
+	}
+}
+
+/** The port of one turn: the assistant's tools call through it, and the turn's end closes it. */
+export interface TurnClient extends ClientPort {
+	/** The turn is over: the call in flight is cancelled, and every later call finds no client. */
+	end(): void;
+}
+
+interface Open {
+	id: string;
+	connection: Connection;
+	principal: string;
+	conversation: string;
+	/** The most bytes of JSON this call's answer may take. */
+	maxValueBytes: number;
+	/** The binary parts uploaded for this call, by index. */
+	parts: Map<number, ClientPart>;
+	/** The indexes whose body is being read, so one index is never buffered twice at once. */
+	receiving: Set<number>;
+	/** The turn's port that made the call. */
+	owner: object;
+	/** Ends the call with `result`; tells the client to stop when `cancel` says why. */
+	settle(result: ClientCallResult, cancel?: ClientCancelReason): void;
+}
+
+export interface ClientDeskOptions {
+	limits: ClientCallLimits;
+	/** Sends a frame on one connection; never to the person's other connections. */
+	send(connection: Connection, frame: ServerFrame): void;
+	/** The clock, in milliseconds; default `Date.now`. */
+	now?(): number;
+}
+
+/**
+ * The calls the assistant's tools make to the client that started their turn, such as a browser
+ * extension reading the page the person has open. It is the opposite of `PromptDesk`: a call goes
+ * to the one connection the turn started on, never to the person's others; it is answered only by
+ * that same connection; and it ends when the connection closes, with no second chance after a
+ * reconnect. One call is open on a connection at a time, and each connection may be asked a
+ * limited number of calls a minute.
+ */
+export class ClientDesk {
+	readonly #limits: ClientCallLimits;
+	readonly #send: ClientDeskOptions["send"];
+	readonly #now: () => number;
+	readonly #open = new Map<string, Open>();
+	readonly #byConnection = new Map<Connection, Open>();
+	readonly #gone = new WeakSet<Connection>();
+	readonly #rates = new WeakMap<Connection, RateWindow>();
+
+	constructor(options: ClientDeskOptions) {
+		this.#limits = options.limits;
+		this.#send = options.send;
+		this.#now = options.now ?? Date.now;
+	}
+
+	/** What `ready` tells a client about the calls it may be asked to run. */
+	get advertised(): ClientCallsAdvertised {
+		const { timeoutMs, maxTimeoutMs, maxValueBytes, maxParts, maxPartBytes } =
+			this.#limits;
+		return { timeoutMs, maxTimeoutMs, maxValueBytes, maxParts, maxPartBytes };
+	}
+
+	/**
+	 * The port of a turn that started on `connection` in `conversation`, naming the functions the
+	 * connection declared; undefined when it declared none, so the turn carries no client.
+	 */
+	portFor(
+		connection: Connection,
+		conversation: string,
+	): TurnClient | undefined {
+		const names = connection.clientTools;
+		if (!names || names.length === 0) return undefined;
+		const declared = [...names];
+		const owner = {};
+		let ended = false;
+		return {
+			names: declared,
+			call: (name, args, options) => {
+				if (ended)
+					return Promise.resolve(failure("no_client", "the turn has ended"));
+				return this.#call(
+					{ connection, conversation, declared, owner },
+					name,
+					args,
+					options,
+				);
+			},
+			end: () => {
+				ended = true;
+				const open = this.#byConnection.get(connection);
+				if (open?.owner === owner)
+					open.settle(failure("cancelled", "the turn has ended"), "turn_ended");
+			},
+		};
+	}
+
+	#call(
+		turn: {
+			connection: Connection;
+			conversation: string;
+			declared: readonly string[];
+			owner: object;
+		},
+		name: string,
+		args: unknown,
+		options: ClientCallOptions | undefined,
+	): Promise<ClientCallResult> {
+		const { connection } = turn;
+		const refuse = (error: ClientCallError, message: string) =>
+			Promise.resolve(failure(error, message));
+		if (this.#gone.has(connection))
+			return refuse("disconnected", "the client's connection is closed");
+		if (options?.signal?.aborted)
+			return refuse("cancelled", "the turn was stopped");
+		if (!turn.declared.includes(name))
+			return refuse("refused", "the client declared no function of that name");
+		let argsJson: string | undefined;
+		try {
+			argsJson = JSON.stringify(args ?? null);
+		} catch {
+			return refuse("failed", "the arguments are not JSON");
+		}
+		if (argsJson === undefined || bytesOf(argsJson) > MAX_ARGS_BYTES)
+			return refuse(
+				"failed",
+				`the arguments must be JSON of at most ${MAX_ARGS_BYTES} bytes`,
+			);
+		if (this.#byConnection.has(connection))
+			return refuse("busy", "another call is open on this client");
+		let rate = this.#rates.get(connection);
+		if (!rate) {
+			rate = new RateWindow(this.#limits.perMinute, MINUTE_MS, this.#now);
+			this.#rates.set(connection, rate);
+		}
+		if (!rate.take("calls"))
+			return refuse("busy", "this client was asked too many calls this minute");
+		const timeoutMs = bounded(
+			options?.timeoutMs,
+			this.#limits.timeoutMs,
+			this.#limits.maxTimeoutMs,
+		);
+		const maxValueBytes = bounded(
+			options?.maxValueBytes,
+			this.#limits.maxValueBytes,
+			this.#limits.maxValueBytes,
+		);
+		return new Promise((resolve) => {
+			const id = crypto.randomUUID();
+			const signal = options?.signal;
+			const onAbort = () =>
+				open.settle(
+					failure("cancelled", "the turn was stopped"),
+					"turn_stopped",
+				);
+			const timer = setTimeout(
+				() =>
+					open.settle(
+						failure("timeout", "the client did not answer in time"),
+						"timeout",
+					),
+				timeoutMs,
+			);
+			const open: Open = {
+				id,
+				connection,
+				principal: connection.speaker.principalId,
+				conversation: turn.conversation,
+				maxValueBytes,
+				parts: new Map(),
+				receiving: new Set(),
+				owner: turn.owner,
+				settle: (result, cancel) => {
+					if (this.#open.get(id) !== open) return;
+					this.#open.delete(id);
+					this.#byConnection.delete(connection);
+					clearTimeout(timer);
+					signal?.removeEventListener("abort", onAbort);
+					if (cancel)
+						this.#send(connection, {
+							type: "client_cancel",
+							call: id,
+							reason: cancel,
+						});
+					resolve(result);
+				},
+			};
+			this.#open.set(id, open);
+			this.#byConnection.set(connection, open);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			this.#send(connection, {
+				type: "client_call",
+				conversation: turn.conversation,
+				call: id,
+				name,
+				args: JSON.parse(argsJson),
+				timeoutMs,
+			});
+		});
+	}
+
+	/**
+	 * Takes a client's answer; `unknown_call` unless the call is open on exactly this connection and
+	 * this person's, so another connection of the same person, or anyone else's, cannot answer it.
+	 */
+	result(
+		connection: Connection,
+		frame: Extract<ClientFrame, { type: "client_result" }>,
+	): ErrorCode | undefined {
+		const open = this.#open.get(frame.call);
+		if (
+			!open ||
+			open.connection !== connection ||
+			open.principal !== connection.speaker.principalId
+		)
+			return "unknown_call";
+		if (!frame.ok) {
+			open.settle(
+				failure(
+					REPORTED[frame.code],
+					plain(frame.message ?? "") || `the client reported: ${frame.code}`,
+				),
+			);
+			return undefined;
+		}
+		const size = bytesOf(JSON.stringify(frame.value) ?? "null");
+		if (size > open.maxValueBytes) {
+			open.settle(
+				failure("too_large", `the answer is over ${open.maxValueBytes} bytes`),
+			);
+			return undefined;
+		}
+		const declared = frame.parts ?? 0;
+		if (declared > this.#limits.maxParts) {
+			open.settle(
+				failure(
+					"failed",
+					`the answer declared ${declared} parts, over the limit of ${this.#limits.maxParts}`,
+				),
+			);
+			return undefined;
+		}
+		const parts: ClientPart[] = [];
+		for (let index = 0; index < declared; index++) {
+			const part = open.parts.get(index);
+			if (!part) {
+				open.settle(
+					failure(
+						"failed",
+						`the answer declared ${declared} parts, and part ${index} did not arrive`,
+					),
+				);
+				return undefined;
+			}
+			parts.push(part);
+		}
+		open.settle({ ok: true, value: frame.value, parts });
+		return undefined;
+	}
+
+	/**
+	 * Keeps a binary part of the answer to an open call, from the REST request that carries it;
+	 * throws a ClientPartRefusal. The call's id is known only to the connection it was sent to, and
+	 * the call must be this person's, in this conversation, and still open.
+	 */
+	async receivePart(
+		principal: string,
+		conversation: string,
+		call: string,
+		index: number,
+		request: Request,
+	): Promise<void> {
+		const open = this.#open.get(call);
+		if (
+			!open ||
+			open.principal !== principal ||
+			open.conversation !== conversation
+		)
+			throw new ClientPartRefusal(404, "unknown_call");
+		const { maxParts, maxPartBytes } = this.#limits;
+		if (!Number.isInteger(index) || index < 0 || index >= maxParts)
+			throw new ClientPartRefusal(400, "bad_request");
+		const type = baseType(request.headers.get("content-type"));
+		if (!type || !PART_TYPES.includes(type))
+			throw new ClientPartRefusal(415, "unsupported_media_type");
+		if (open.parts.has(index) || open.receiving.has(index))
+			throw new ClientPartRefusal(409, "duplicate_part");
+		const header = request.headers.get("content-length");
+		const length = header === null ? Number.NaN : Number(header);
+		if (Number.isFinite(length) && length > maxPartBytes)
+			throw new ClientPartRefusal(413, "payload_too_large");
+		// The index is held while the body is read, so parallel uploads of it buffer one body.
+		open.receiving.add(index);
+		let bytes: Uint8Array | undefined;
+		try {
+			bytes = await readLimited(request, maxPartBytes);
+		} finally {
+			open.receiving.delete(index);
+		}
+		if (!bytes) throw new ClientPartRefusal(413, "payload_too_large");
+		// The call may have ended, or the same part arrived, while the body was read.
+		if (this.#open.get(call) !== open)
+			throw new ClientPartRefusal(404, "unknown_call");
+		if (open.parts.has(index))
+			throw new ClientPartRefusal(409, "duplicate_part");
+		if (!bytesMatchType(type, bytes))
+			throw new ClientPartRefusal(415, "unsupported_media_type");
+		open.parts.set(index, { mimeType: type, data: bytes });
+	}
+
+	/** The connection closed: its open call ends as disconnected, and so does every later one. */
+	closed(connection: Connection): void {
+		this.#gone.add(connection);
+		this.#byConnection
+			.get(connection)
+			?.settle(failure("disconnected", "the client's connection closed"));
+	}
+}
+
+/** `asked` as a whole number of at most `max`, or `fallback` when it is no positive number. */
+function bounded(asked: number | undefined, fallback: number, max: number) {
+	if (typeof asked !== "number" || !Number.isFinite(asked) || asked < 1)
+		return Math.min(fallback, max);
+	return Math.min(Math.floor(asked), max);
+}

package/src/connections.ts

@@ -6,6 +6,18 @@ import type { ServerFrame } from "./protocol.ts";
 export interface Connection {
 	identity: WebIdentity;
 	speaker: Speaker;
+	/**
+	 * The normalized `Origin` the upgrade carried and the route accepted; undefined when it sent none
+	 * (a client that is not a browser, on a route that admits `"any"` origin). Fixed for the
+	 * connection's life: it comes from the transport, never from a frame.
+	 */
+	origin?: string;
+	/**
+	 * The functions the client declared with `client_hello` it can run for the assistant's tools;
+	 * undefined until it declares, and then it is a client's: a connection that declares none is
+	 * never asked to run anything.
+	 */
+	clientTools?: readonly string[];
 	socket?: RouteSocket<Connection>;
 	/** Asks for a fresh token, then closes the socket when the token expires. */
 	timers: ReturnType<typeof setTimeout>[];

package/src/index.ts

@@ -1,4 +1,5 @@
 export type { WebChatLimits, WebPersona } from "./chat.ts";
+export type { ClientCallLimits } from "./client-calls.ts";
 export type { Notice } from "./notices.ts";
 export type {
 	OidcJwtVerifierOptions,
@@ -15,6 +16,9 @@ export {
 export type { WebChatOptions, WebChatRouteLimits } from "./plugin.ts";
 export { webChat } from "./plugin.ts";
 export type {
+	ClientCallsAdvertised,
+	ClientCancelReason,
+	ClientFailure,
 	ClientFrame,
 	ErrorCode,
 	PersonaSummary,

package/src/origin.ts

@@ -0,0 +1,17 @@
+/** The longest origin kept; a longer header is not a browser's. */
+const MAX_ORIGIN_LENGTH = 256;
+
+/** A serialized origin: a scheme, `://`, and a host with an optional port, with no path, query or space. */
+const ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/[^\s/?#@]+$/;
+
+/**
+ * The connection's `Origin` header as a tool may label a record with it: trimmed and lower-cased,
+ * or undefined when the header is absent, the opaque `null`, over-long, or not a serialized origin.
+ * Browsers always send one; a client that is not a browser sends any text it likes, so the shape
+ * is checked here and nothing else is trusted about it.
+ */
+export function normalizeOrigin(header: string | null): string | undefined {
+	const value = header?.trim().toLowerCase();
+	if (!value || value.length > MAX_ORIGIN_LENGTH) return undefined;
+	return ORIGIN.test(value) ? value : undefined;
+}

package/src/plugin.ts

@@ -17,10 +17,12 @@ import {
 	type WebChatLimits,
 	type WebPersona,
 } from "./chat.ts";
+import type { ClientCallLimits } from "./client-calls.ts";
 import type { Connection } from "./connections.ts";
 import { webDirectChannel } from "./direct-channel.ts";
 import { PgNotices } from "./notices.ts";
 import { TokenRefused, type TokenVerifier } from "./oidc.ts";
+import { normalizeOrigin } from "./origin.ts";
 import { TICKET_PROTOCOL_PREFIX, WEBCHAT_PROTOCOL } from "./protocol.ts";
 import { restHandler } from "./rest.ts";
 import { TicketBook } from "./tickets.ts";
@@ -58,7 +60,9 @@ export interface WebChatOptions {
 	path?: string;
 	/** The key prefix of the conversations; default `web`. Two web chats on one host need two. */
 	surface?: string;
-	limits?: Partial<WebChatLimits & WebChatRouteLimits>;
+	limits?: Partial<Omit<WebChatLimits & WebChatRouteLimits, "clientCalls">> & {
+		clientCalls?: Partial<ClientCallLimits>;
+	};
 }
 
 const DEFAULT_LIMITS: WebChatLimits & WebChatRouteLimits = {
@@ -69,6 +73,14 @@ const DEFAULT_LIMITS: WebChatLimits & WebChatRouteLimits = {
 	messageChars: 32_000,
 	promptTimeoutMs: 30 * 60_000,
 	reauthLeadMs: 60_000,
+	clientCalls: {
+		timeoutMs: 30_000,
+		maxTimeoutMs: 60_000,
+		maxValueBytes: 48 * 1024,
+		maxParts: 2,
+		maxPartBytes: 2 * 1024 * 1024,
+		perMinute: 60,
+	},
 	attachmentBytes: 10 * 1024 * 1024,
 	attachmentsPerMessage: 8,
 	uploadsPerHour: 60,
@@ -78,7 +90,7 @@ const DEFAULT_LIMITS: WebChatLimits & WebChatRouteLimits = {
 	unsentUploadTtlMs: 24 * 60 * 60_000,
 	maxConnections: 256,
 	maxMessageBytes: 64 * 1024,
-	rate: { messages: 60, perMs: 60_000 },
+	rate: { messages: 120, perMs: 60_000 },
 	maxBufferedBytes: 4 * 1024 * 1024,
 	ticketTtlMs: 30_000,
 };
@@ -144,6 +156,52 @@ function checkAttachmentLimits(limits: WebChatLimits): void {
 		);
 }
 
+/** The most binary parts one answer may declare; see the protocol. */
+const MAX_PARTS = 16;
+/** The most bytes of one binary part, which the chat holds in memory until the call ends. */
+const MAX_PART_BYTES = 16 * 1024 * 1024;
+
+/** Refuses a client-call limit that is not a positive whole number, or one the protocol cannot carry. */
+function checkClientCallLimits(
+	limits: ClientCallLimits,
+	maxMessageBytes: number,
+	rate: { messages: number; perMs: number },
+): void {
+	for (const key of [
+		"timeoutMs",
+		"maxTimeoutMs",
+		"maxValueBytes",
+		"maxParts",
+		"maxPartBytes",
+		"perMinute",
+	] as const)
+		if (!Number.isInteger(limits[key]) || limits[key] < 1)
+			throw new Error(
+				`webChat: limits.clientCalls.${key} must be a positive whole number; got ${String(limits[key])}`,
+			);
+	if (limits.timeoutMs > limits.maxTimeoutMs)
+		throw new Error(
+			`webChat: limits.clientCalls.timeoutMs (${limits.timeoutMs}) may be at most maxTimeoutMs (${limits.maxTimeoutMs})`,
+		);
+	if (limits.maxValueBytes >= maxMessageBytes)
+		throw new Error(
+			`webChat: limits.clientCalls.maxValueBytes (${limits.maxValueBytes}) must be under maxMessageBytes (${maxMessageBytes}), the most a client's answer frame can carry`,
+		);
+	const framesPerMinute = (rate.messages * 60_000) / rate.perMs;
+	if (limits.perMinute >= framesPerMinute)
+		throw new Error(
+			`webChat: limits.clientCalls.perMinute (${limits.perMinute}) must be under the frame rate of ${framesPerMinute} a minute (limits.rate), since each answer to a call is a frame the socket counts; a busy client would be disconnected. Lower perMinute or raise rate.messages`,
+		);
+	if (limits.maxParts > MAX_PARTS)
+		throw new Error(
+			`webChat: limits.clientCalls.maxParts may be at most ${MAX_PARTS}; got ${limits.maxParts}`,
+		);
+	if (limits.maxPartBytes > MAX_PART_BYTES)
+		throw new Error(
+			`webChat: limits.clientCalls.maxPartBytes may be at most ${MAX_PART_BYTES} (16 MiB); got ${limits.maxPartBytes}`,
+		);
+}
+
 /** The subprotocols a WebSocket upgrade offers. */
 function offered(request: Request): string[] {
 	return (request.headers.get("sec-websocket-protocol") ?? "")
@@ -163,10 +221,22 @@ function offered(request: Request): string[] {
  */
 export function webChat(options: WebChatOptions): RoundtablePlugin {
 	const { path, surface } = checkOptions(options);
-	const limits = { ...DEFAULT_LIMITS, ...options.limits };
+	const limits = {
+		...DEFAULT_LIMITS,
+		...options.limits,
+		clientCalls: {
+			...DEFAULT_LIMITS.clientCalls,
+			...options.limits?.clientCalls,
+		},
+	};
 	// The personas are checked now, so a broken list stops the configuration rather than the boot.
 	checkPersonas(options.personas);
 	checkAttachmentLimits(limits);
+	checkClientCallLimits(
+		limits.clientCalls,
+		limits.maxMessageBytes,
+		limits.rate,
+	);
 	return definePlugin({
 		name: surface === "web" ? "webchat" : `webchat-${surface}`,
 		requires: [IDENTITY, CONVERSATIONS, RUNTIME],
@@ -240,7 +310,12 @@ export function webChat(options: WebChatOptions): RoundtablePlugin {
 					if (error instanceof Refusal) return refuse(403, "Forbidden");
 					throw error;
 				}
-				const connection: Connection = { ...admitted, timers: [] };
+				const origin = normalizeOrigin(request.headers.get("origin"));
+				const connection: Connection = {
+					...admitted,
+					...(origin ? { origin } : {}),
+					timers: [],
+				};
 				if (!chat.connections.reserve(connection))
 					return refuse(429, "Too Many Connections");
 				return {

package/src/protocol.ts

@@ -79,6 +79,43 @@ export type PromptOutcome =
 	| "expired"
 	| "cancelled";
 
+/** The most functions a client may declare. */
+export const MAX_CLIENT_TOOLS = 64;
+/** The longest function name a client may declare. */
+const CLIENT_TOOL_CHARS = 64;
+/** A function name: lowercase words joined by underscores, as a tool's name is. */
+const CLIENT_TOOL_NAME = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+/** The most binary parts one answer may declare, whatever the server's own limit is. */
+const MAX_FRAME_PARTS = 16;
+/** The longest failure message accepted from a client, in characters. */
+const CLIENT_MESSAGE_CHARS = 2000;
+
+/** Why a client says a call failed; the server maps each to a `ClientCallError`. */
+export const CLIENT_FAILURES = [
+	"refused",
+	"failed",
+	"timeout",
+	"stopped",
+] as const;
+export type ClientFailure = (typeof CLIENT_FAILURES)[number];
+
+/** Why the server cancels a call it sent. */
+export type ClientCancelReason = "turn_stopped" | "timeout" | "turn_ended";
+
+/** What the server tells a client about the calls it may be asked to run. */
+export interface ClientCallsAdvertised {
+	/** How long a call waits for an answer unless it names a time, in milliseconds. */
+	timeoutMs: number;
+	/** The longest a call waits, in milliseconds. */
+	maxTimeoutMs: number;
+	/** The most bytes (UTF-8, as JSON) an answer's `value` may take. */
+	maxValueBytes: number;
+	/** The most binary parts one answer may carry. */
+	maxParts: number;
+	/** The most bytes of one part. */
+	maxPartBytes: number;
+}
+
 /** Why the server refused a frame or a request. */
 export type ErrorCode =
 	| "bad_frame"
@@ -88,6 +125,8 @@ export type ErrorCode =
 	| "unknown_prompt"
 	| "too_many_conversations"
 	| "busy"
+	/** A `client_result` named a call that is not open on this connection. */
+	| "unknown_call"
 	/** A `send` named a file that is not waiting for this person in this conversation; the whole message is refused. */
 	| "unknown_attachment"
 	/** A `send` would take the person past `usedAttachmentBytesPerPrincipal`; the whole message is refused and its files stay waiting. */
@@ -118,7 +157,32 @@ export type ClientFrame =
 	/** Approves or declines an approval prompt. */
 	| { type: "approval"; prompt: string; approved: boolean }
 	/** Answers a question prompt: the chosen options' labels and, where allowed, their own text. */
-	| { type: "answer"; prompt: string; choices: string[]; text?: string };
+	| { type: "answer"; prompt: string; choices: string[]; text?: string }
+	/**
+	 * Declares the functions this connection can run for the assistant's tools, such as reading the
+	 * page the person has open. Send it after each `ready`. A connection that declares none is never
+	 * asked to run anything, and its turns carry no client.
+	 */
+	| { type: "client_hello"; version: 1; tools: string[] }
+	/**
+	 * The answer to a `client_call`, sent on the connection the call arrived on. Binary parts are
+	 * uploaded first (`PUT <path>/conversations/<id>/client-calls/<call>/parts/<n>`), and `parts`
+	 * says how many; a failure names why, and `message` is shown to the assistant as data.
+	 */
+	| {
+			type: "client_result";
+			call: string;
+			ok: true;
+			value: unknown;
+			parts?: number;
+	  }
+	| {
+			type: "client_result";
+			call: string;
+			ok: false;
+			code: ClientFailure;
+			message?: string;
+	  };
 
 /** What the server sends: one JSON object per WebSocket text message. */
 export type ServerFrame =
@@ -140,6 +204,11 @@ export type ServerFrame =
 			};
 			/** When the token expires, as an ISO time. */
 			expiresAt: string;
+			/**
+			 * What a call to this client may take. Absent from a server before 0.9.11, which never sends
+			 * `client_call`: show no feature that needs the page's help then.
+			 */
+			clientCalls?: ClientCallsAdvertised;
 	  }
 	/** The message `id` was taken into `conversation`, a new one when the client named none. */
 	| { type: "accepted"; id: string; conversation: string }
@@ -171,7 +240,21 @@ export type ServerFrame =
 	| { type: "notice"; notice: Notice }
 	/** The token expires soon: send `auth` with a fresh one before `expiresAt`, or the server closes with 4401. */
 	| { type: "reauth"; expiresAt: string }
-	/** A frame was refused; `ref` is the `send` id or prompt id it was about. */
+	/**
+	 * The assistant asks this connection, and no other, to run a function it declared and answer
+	 * with `client_result` within `timeoutMs`. One call is open on a connection at a time.
+	 */
+	| {
+			type: "client_call";
+			conversation: string;
+			call: string;
+			name: string;
+			args: unknown;
+			timeoutMs: number;
+	  }
+	/** The call is no longer wanted: stop running it; any answer is dropped. */
+	| { type: "client_cancel"; call: string; reason: ClientCancelReason }
+	/** A frame was refused; `ref` is the `send` id, prompt id or call id it was about. */
 	| { type: "error"; code: ErrorCode; ref?: string };
 
 /** The longest client reference, conversation id, or prompt id accepted. */
@@ -259,7 +342,66 @@ export function parseClientFrame(
 				...(text === undefined ? {} : { text }),
 			};
 		}
+		case "client_hello":
+			return parseHello(value);
+		case "client_result":
+			return parseResult(value);
 		default:
 			return undefined;
 	}
 }
+
+function parseHello(value: Record<string, unknown>): ClientFrame | undefined {
+	const { version, tools } = value;
+	if (version !== 1 || !Array.isArray(tools)) return undefined;
+	if (tools.length > MAX_CLIENT_TOOLS) return undefined;
+	for (const tool of tools)
+		if (
+			typeof tool !== "string" ||
+			tool.length > CLIENT_TOOL_CHARS ||
+			!CLIENT_TOOL_NAME.test(tool)
+		)
+			return undefined;
+	return {
+		type: "client_hello",
+		version: 1,
+		tools: [...new Set(tools as string[])],
+	};
+}
+
+function parseResult(value: Record<string, unknown>): ClientFrame | undefined {
+	const { call, ok, message } = value;
+	if (!isId(call) || typeof ok !== "boolean") return undefined;
+	if (ok) {
+		const { parts } = value;
+		if (
+			parts !== undefined &&
+			(typeof parts !== "number" ||
+				!Number.isInteger(parts) ||
+				parts < 0 ||
+				parts > MAX_FRAME_PARTS)
+		)
+			return undefined;
+		return {
+			type: "client_result",
+			call,
+			ok: true,
+			value: value.value === undefined ? null : value.value,
+			...(parts === undefined ? {} : { parts }),
+		};
+	}
+	const { code } = value;
+	if (!CLIENT_FAILURES.includes(code as ClientFailure)) return undefined;
+	if (
+		message !== undefined &&
+		(typeof message !== "string" || message.length > CLIENT_MESSAGE_CHARS)
+	)
+		return undefined;
+	return {
+		type: "client_result",
+		call,
+		ok: false,
+		code: code as ClientFailure,
+		...(message === undefined ? {} : { message }),
+	};
+}

package/src/rest.ts

@@ -1,5 +1,6 @@
 import type { ConversationRecord, Logger } from "pi-roundtable";
 import { type Admitted, Refusal, type WebChat } from "./chat.ts";
+import { ClientPartRefusal } from "./client-calls.ts";
 import { MAX_NOTICES, type PgNotices } from "./notices.ts";
 import { TokenRefused } from "./oidc.ts";
 import type { TicketBook } from "./tickets.ts";
@@ -61,6 +62,7 @@ const STATUS: Record<string, number> = {
 	bad_frame: 400,
 	forbidden: 403,
 	unknown_conversation: 404,
+	unknown_call: 404,
 	unknown_persona: 404,
 	too_many_conversations: 429,
 	unknown_attachment: 400,
@@ -74,7 +76,10 @@ const STATUS: Record<string, number> = {
  * (`?limit=`, its last messages), and `POST conversations/<id>/files?name=<file name>` (the body is
  * the file's bytes, its `Content-Type` the file's type; answers 201 with `{ file, name, contentType,
  * size }`, 413 over the size limit, 415 for a type that is not accepted, 429 over the person's
- * allowance). A browser on another origin gets CORS headers when its origin
+ * allowance), and `PUT conversations/<id>/client-calls/<call>/parts/<n>` (the body is a binary part of
+ * the answer to a call the assistant made to the caller's client, its `Content-Type` an image type;
+ * answers 201, 404 for a call that is not open, 409 for a part sent twice, 413 over the size limit,
+ * 415 for a type that is not an image or bytes that are not the type). A browser on another origin gets CORS headers when its origin
  * is allowed and 403 otherwise.
  */
 export function restHandler(options: RestOptions) {
@@ -159,6 +164,20 @@ export function restHandler(options: RestOptions) {
 			);
 			return json(uploaded, 201, headers);
 		}
+		const part =
+			/^conversations\/([A-Za-z0-9-]{1,128})\/client-calls\/([A-Za-z0-9-]{1,128})\/parts\/(\d{1,3})$/.exec(
+				rest,
+			);
+		if (part?.[1] && part[2] && part[3] && request.method === "PUT") {
+			await chat.clientPart(
+				speaker,
+				part[1],
+				part[2],
+				Number(part[3]),
+				request,
+			);
+			return json({ part: Number(part[3]) }, 201, headers);
+		}
 		return json({ error: "not_found" }, 404, headers);
 	}
 	return async (request: Request): Promise<Response> => {
@@ -169,7 +188,7 @@ export function restHandler(options: RestOptions) {
 				status: 204,
 				headers: {
 					...headers,
-					"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+					"Access-Control-Allow-Methods": "GET, POST, PUT, OPTIONS",
 					"Access-Control-Allow-Headers": "authorization, content-type",
 					"Access-Control-Max-Age": "600",
 				},
@@ -195,7 +214,7 @@ export function restHandler(options: RestOptions) {
 		try {
 			return await route(request, url, who, headers);
 		} catch (error) {
-			if (error instanceof UploadRefusal)
+			if (error instanceof UploadRefusal || error instanceof ClientPartRefusal)
 				return json({ error: error.code }, error.status, headers);
 			if (!(error instanceof Refusal)) throw error;
 			return json({ error: error.code }, STATUS[error.code] ?? 400, headers);

package/src/uploads.ts

@@ -93,7 +93,7 @@ function safeName(name: string | null): string {
 }
 
 /** The request body, or undefined once it passes `max` bytes; the rest of the stream is not read. */
-async function readLimited(
+export async function readLimited(
 	request: Request,
 	max: number,
 ): Promise<Uint8Array | undefined> {