pi-roundtable-webchat 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -5,6 +5,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-10-10
+
+### Added
+
+- File attachments. A person uploads a file to one of their conversations with `POST <path>/conversations/<id>/files?name=<file name>` (the body is the file, its `Content-Type` the type; answers 201 `{ file, name, contentType, size }`), then names it in a `send` frame's new `attachments` field. The turn runs with the files as the core's attachments: images reach the model, every file is listed under `## Attachments`, and `read_attachment` and a tool's `turn.attachment()` read them. An rrweb recording is an ordinary `application/json` file.
+- `ready` carries `attachments: { maxBytes, perMessage, types }`, so a client shows an upload control only when the server takes files; the subprotocol stays `roundtable.webchat.v1`, and a client that sends no `attachments` sees no change.
+- The error code `unknown_attachment` (a `send` named a file that is not waiting for the person in that conversation; the whole message is refused) and the REST errors `payload_too_large` (413), `unsupported_media_type` (415) and `too_many_uploads` (429).
+- The limits `attachmentBytes` (10 MiB, at most the core's 25 MiB), `attachmentsPerMessage` (8), `uploadsPerHour` (60), `unsentUploadBytesPerPrincipal` (64 MiB), `attachmentTypes` (PNG, JPEG, WebP, GIF, JSON, plain text, PDF; an entry may end in `/*`) and `unsentUploadTtlMs` (24 hours). The first bytes of an image or PDF must match its type. An upload no message used is deleted after its time; a swept file, a file of another conversation or person, or a file a message already used is `unknown_attachment`.
+- Nothing needs configuring. The plugin needs `context.attachments` from pi-roundtable 0.9.2 and refuses to set up without it, and a host that has no `dataDir` fails at startup with a message naming it.
+
+### Fixed
+
+- The README named `>=0.8.0 <0.9.0` as the peer range of pi-roundtable; it is `>=0.9.0 <0.10.0`.
+
 ## [0.9.1] - 2026-10-10
 
 - Release in lockstep with pi-roundtable 0.9.1; no package-specific behavior changes.

package/README.md

@@ -8,19 +8,20 @@ Source lives in [`packages/webchat`][source] in the pi-roundtable repository and
 [roundtable]: https://www.npmjs.com/package/pi-roundtable
 [source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/webchat
 
-The plugin adds four things to a host:
+The plugin adds five things to a host:
 
 - a chat surface whose conversations have keys `web:<conversation>`;
 - the claim that runs each message as a turn of its conversation's persona, through `context.turns` and the host's runtime;
 - a REST API and a WebSocket under one path of the host's HTTP listener;
-- a durable private inbox for `notify`, with live `notice` frames and an authenticated REST inbox.
+- a durable private inbox for `notify`, with live `notice` frames and an authenticated REST inbox;
+- file uploads to a conversation (screenshots, a JSON recording, a PDF), which a message then references; see [Attachments](#attachments).
 
 It needs no Discord: a host whose `roundtable.config.ts` has no `discord` key and lists this plugin is a web-only assistant.
 `roundtable init --adapter web` creates such a project.
 
 ## Requirements
 
-- Bun 1.3 or later, and pi-roundtable `>=0.8.0 <0.9.0` as a peer dependency.
+- Bun 1.3 or later, and pi-roundtable `>=0.9.0 <0.10.0` as a peer dependency. Uploading files needs `context.attachments`, which pi-roundtable added in 0.9.2: the plugin refuses to set up on an earlier core and names the version to install.
 - An HTTP listener on the host (`http` in the configuration), behind a reverse proxy that serves it over HTTPS.
 - An OpenID Connect provider that issues access tokens for this API, with signing keys published as a JWKS.
 
@@ -194,7 +195,7 @@ The TypeScript types are `ClientFrame` and `ServerFrame`.
 | Frame | Meaning |
 |---|---|
 | `{ type: "send", id, persona, text }` | Opens a new conversation of `persona` with this message. `id` is your reference, echoed by `accepted` or `error`. |
-| `{ type: "send", id, conversation, text }` | A message in one of your conversations. |
+| `{ type: "send", id, conversation, text, attachments? }` | A message in one of your conversations. `attachments` lists files you [uploaded](#attachments) to this conversation, by the `file` each upload returned. |
 | `{ type: "stop", conversation }` | Stops the conversation's running turn. |
 | `{ type: "approval", prompt, approved }` | Approves or declines an approval prompt. |
 | `{ type: "answer", prompt, choices, text? }` | Answers a question prompt: the chosen options' labels, and your own text where the question allows it. |
@@ -204,7 +205,7 @@ The TypeScript types are `ClientFrame` and `ServerFrame`.
 
 | Frame | Meaning |
 |---|---|
-| `{ type: "ready", protocol, speaker, personas, expiresAt }` | Sent first, and again after a fresh token: who you are (`{ id, name, tier, principalId }`), the personas you may open (`{ kind, label }`), and when the token expires. Open prompts follow it. |
+| `{ 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: "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. |
@@ -217,7 +218,7 @@ The TypeScript types are `ClientFrame` and `ServerFrame`.
 | `{ 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. |
 
-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), 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), 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).
@@ -232,6 +233,7 @@ A request from a browser origin not in `origins` gets 403; an allowed origin get
 | `POST <path>/tickets` | 201 `{ ticket, expiresAt }`. |
 | `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). |
 | `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. |
@@ -243,6 +245,44 @@ List, read acknowledgements, pagination cursors and retention are isolated by su
 Offline inbox discovery requires a private conversation on this surface or a linked identity whose provider equals this surface; a generic `oidc:` link alone does not establish membership in every webchat inbox.
 A REST notice page therefore contains at most 100 bounded entries, less than 2.5 MiB at the default text cap.
 
+## Attachments
+
+A person sends a file in two steps, because the socket carries JSON text only: they upload it over REST to a conversation they own, then name it in a `send` frame.
+Open the conversation first (`POST <path>/conversations`, or an earlier message), since a message that opens a conversation cannot reference files that have no conversation to wait in.
+`ready.attachments` tells the client the limits (`maxBytes`, `perMessage`, `types`) before it shows an upload control.
+
+```js
+const open = await fetch("/chat/conversations", {
+	method: "POST",
+	headers: { authorization: `Bearer ${token}` },
+	body: JSON.stringify({ persona: "helpdesk" }),
+});
+const { conversation } = await open.json();
+const response = await fetch(`/chat/conversations/${conversation}/files?name=${encodeURIComponent(file.name)}`, {
+	method: "POST",
+	headers: { authorization: `Bearer ${token}`, "content-type": file.type },
+	body: file,
+});
+const { file: id } = await response.json();
+socket.send(JSON.stringify({ type: "send", id: "2", conversation, text: "Why did this fail?", attachments: [id] }));
+```
+
+What the server checks, in this order: the conversation is the caller's (403, 404); the file name is present and at most 255 characters, with control characters replaced and quotes made apostrophes so a name cannot add lines to the model's prompt (400); the `Content-Type` is one of `limits.attachmentTypes` (415); the person has not made `uploadsPerHour` uploads in the last hour (429); the file is within `attachmentBytes`, by `Content-Length` and again while the body streams, so a body that lies about its length is cut off (413); the person's uploads waiting for a message stay within `unsentUploadBytesPerPrincipal` (429); and for PNG, JPEG, GIF, WebP and PDF the first bytes match the type (415), whatever the file name says.
+JSON, plain text and other types have no such check, since any bytes may be labelled so.
+The default types are `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `application/json`, `text/plain` and `application/pdf`; an entry ending in `/*` admits every type under it.
+An rrweb recording is an ordinary `application/json` file.
+
+A `send` that names files runs the turn with them: the core moves each file into the conversation's attachment directory, shows up to four images to the model, lists every file under `## Attachments` in the turn's prompt, and lets the model read text, JSON and PDF files with `read_attachment`.
+A plugin's tool passes a file on with `turn.attachment(file)`, which returns the bytes (see the core's [plugin guide](https://github.com/wayne930242/pi-roundtable/blob/master/docs/plugins.md)).
+A message may name at most `attachmentsPerMessage` files, a file belongs to one message, and a message that names a file that is not waiting for the person is refused whole with `unknown_attachment`.
+
+An upload no message used is deleted after `unsentUploadTtlMs` (24 hours): the plugin sweeps every ten minutes, and once when the host starts.
+Files a message used stay with their conversation, in the host's data directory, as long as the conversation does.
+This plugin has no way to delete a conversation, so none of its files go with it.
+
+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.
+
 ## Security model
 
 - **Private conversations.** A conversation belongs to the person who opened it.
@@ -258,6 +298,9 @@ A REST notice page therefore contains at most 100 bounded entries, less than 2.5
   Each person has at most `turnsPerPrincipal` interactive turns running or queued at once, however many conversations or sockets they use, and a conversation at most its running interactive turn and one queued behind it; a browser message over either limit is refused with `busy` and never queued.
   Personal schedules and delegated reports use the core runtime's conversation queue separately from this interactive admission budget, so a busy browser cannot discard them; runtime stop and shutdown still apply.
   Each person opens at most `newConversationsPerHour` conversations an hour, over the socket or the REST API alike.
+- **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).
 - **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 `expired`, without owner escalation.
 - **Owner.** Nobody becomes the owner through a token's claims; grant owner in core configuration or the principal CLI.
@@ -279,10 +322,15 @@ A REST notice page therefore contains at most 100 bounded entries, less than 2.5
 | `rate` | 60 frames a minute per socket |
 | `maxBufferedBytes` | 4 MiB waiting for a slow client |
 | `ticketTtlMs` | 30 seconds |
+| `attachmentBytes` | 10 MiB per uploaded file; never above the core's 25 MiB |
+| `attachmentsPerMessage` | 8 files named by one message |
+| `uploadsPerHour` | 60 uploads per person in any hour |
+| `unsentUploadBytesPerPrincipal` | 64 MiB per person uploaded and not yet used by a message |
+| `attachmentTypes` | `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `application/json`, `text/plain`, `application/pdf` |
+| `unsentUploadTtlMs` | 24 hours before an unused upload is deleted |
 
 ## What it does not do yet
 
-- Attachments: messages carry text only.
 - System error reports into a person's web conversation: the background claim accepts only `PERSONAL_TARGET` turns checked by core, whose author principal is the private conversation's principal.
   The claim declares `takesSystemReports: false`: configuring `ops.conversation` on this surface (for example, `web:ops`) fails at startup with core `ConfigError`, rather than silently skipping every report.
   Use a shared conversation on another surface, such as a Discord channel, or `ops.agent`.

package/package.json

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

package/src/chat.ts

@@ -1,5 +1,7 @@
 import {
 	type AgentRuntime,
+	type AttachmentPort,
+	AttachmentRefusal,
 	type ChannelClaim,
 	type ChannelKey,
 	type ConversationPort,
@@ -16,6 +18,7 @@ import {
 	type Tier,
 	type ToolSelection,
 	type TranscriptEntry,
+	type TurnAttachments,
 	type TurnResult,
 } from "pi-roundtable";
 import { RateWindow, TurnBudget } from "./budget.ts";
@@ -37,6 +40,7 @@ import {
 	WEBCHAT_PROTOCOL_VERSION,
 } from "./protocol.ts";
 import { WebSurface } from "./surface.ts";
+import { type UploadedFile, type UploadLimits, Uploads } from "./uploads.ts";
 
 /** A conversation kind a client may open. */
 export interface WebPersona {
@@ -55,8 +59,8 @@ export interface WebPersona {
 	selection?: ToolSelection;
 }
 
-/** The limits of one web chat. */
-export interface WebChatLimits {
+/** The limits of one web chat, those of uploads and attachments included. */
+export interface WebChatLimits extends UploadLimits {
 	/** Connections one person may hold open at once; default 5. */
 	connectionsPerPrincipal: number;
 	/** New conversations one person may hold before writing in them; default 20. */
@@ -86,6 +90,8 @@ export interface WebChatDeps {
 	/** Read when used, after the host linked every plugin. */
 	registry(): ConversationRegistry;
 	conversations(): ConversationPort;
+	/** Where uploaded files wait for the message that uses them. */
+	attachments(): AttachmentPort;
 	turns(): ConversationTurns;
 	runtime(): AgentRuntime;
 	/** The clock, in milliseconds; default `Date.now`. */
@@ -108,6 +114,8 @@ interface Pending {
 	speaker: Speaker;
 	persona: WebPersona;
 	title: string;
+	/** The files the message references, moved into the conversation when it was accepted. */
+	attachments?: TurnAttachments;
 	/** Whether the conversation was new when the message was accepted. */
 	fresh: boolean;
 	/** Frees the message's place in the person's turn budget; called once its turn ends or never runs. */
@@ -181,6 +189,7 @@ export function checkPersonas(
  */
 export class WebChat {
 	readonly surface: WebSurface;
+	readonly uploads: Uploads;
 	readonly connections: Connections;
 	readonly desk: PromptDesk;
 	readonly #deps: WebChatDeps;
@@ -200,6 +209,11 @@ export class WebChat {
 
 	constructor(deps: WebChatDeps) {
 		this.#deps = deps;
+		this.uploads = new Uploads({
+			limits: deps.limits,
+			attachments: deps.attachments,
+			...(deps.now ? { now: deps.now } : {}),
+		});
 		this.#personas = checkPersonas(deps.personas);
 		this.#turns = new TurnBudget(deps.limits.turnsPerPrincipal);
 		this.#opened = new RateWindow(
@@ -319,6 +333,26 @@ export class WebChat {
 		return { persona, minted };
 	}
 
+	/**
+	 * Keeps the request's body as a file for one of the speaker's conversations until a message
+	 * uses it; a Refusal when the conversation is not theirs, an UploadRefusal when the file is not
+	 * accepted.
+	 */
+	async upload(
+		speaker: Speaker,
+		conversation: string,
+		request: Request,
+		name: string | null,
+	): Promise<UploadedFile> {
+		await this.own(speaker, conversation);
+		return this.uploads.receive(
+			request,
+			channelKey(this.#deps.surface, conversation),
+			speaker.principalId,
+			name,
+		);
+	}
+
 	/** The speaker's web conversations, the most recently active first. */
 	async list(speaker: Speaker): Promise<ConversationRecord[]> {
 		const records = await this.#deps
@@ -361,6 +395,7 @@ export class WebChat {
 			protocol: WEBCHAT_PROTOCOL_VERSION,
 			speaker: { ...speaker },
 			personas: this.personasFor(speaker),
+			attachments: this.uploads.advertised,
 			expiresAt: identity.expiresAt.toISOString(),
 		});
 		for (const frame of this.desk.openFor(speaker.principalId))
@@ -520,6 +555,9 @@ export class WebChat {
 		const text = frame.text;
 		if (!text.trim() || text.length > this.#deps.limits.messageChars)
 			throw new Refusal("bad_frame");
+		const files = frame.attachments ?? [];
+		if (files.length > this.#deps.limits.attachmentsPerMessage)
+			throw new Refusal("bad_frame");
 		// Checked before a conversation is opened for it, so a refused message opens none.
 		if (!this.#turns.allows(speaker.principalId, frame.conversation))
 			throw new Refusal("busy");
@@ -532,12 +570,33 @@ export class WebChat {
 			if (!frame.conversation) this.#minted.delete(conversation);
 			throw new Refusal("busy");
 		}
+		let attachments: TurnAttachments | undefined;
+		if (files.length > 0) {
+			try {
+				attachments = await this.#deps
+					.attachments()
+					.turnAttachments(
+						channelKey(this.#deps.surface, conversation),
+						speaker.principalId,
+						files,
+					);
+			} catch (error) {
+				// The refused message holds no place and opens no conversation.
+				release();
+				if (!frame.conversation) this.#minted.delete(conversation);
+				if (!(error instanceof AttachmentRefusal)) throw error;
+				throw new Refusal(
+					error.code === "unknown_file" ? "unknown_attachment" : "forbidden",
+				);
+			}
+		}
 		const messageId = crypto.randomUUID();
 		this.#pending.set(messageId, {
 			speaker,
 			persona,
 			title: minted?.title ?? titleOf(text),
 			fresh: record === undefined,
+			...(attachments ? { attachments } : {}),
 			release,
 		});
 		this.connections.send(connection, {
@@ -740,6 +799,7 @@ export class WebChat {
 				text,
 				speaker,
 				interactive: true,
+				...(pending.attachments ? { attachments: pending.attachments } : {}),
 				...(persona.selection
 					? {
 							selection: {

package/src/file-types.ts

@@ -0,0 +1,50 @@
+/** The content type without parameters, lower case; undefined for a missing or empty header. */
+export function baseType(header: string | null): string | undefined {
+	const type = header?.split(";")[0]?.trim().toLowerCase();
+	return type ? type : undefined;
+}
+
+/** Whether `type` is one of `allowed`; an entry ending in `/*` admits every type under it. */
+export function isAllowedType(
+	allowed: readonly string[],
+	type: string,
+): boolean {
+	return allowed.some((entry) =>
+		entry.endsWith("/*")
+			? type.startsWith(entry.slice(0, -1)) && type.length > entry.length - 1
+			: entry === type,
+	);
+}
+
+const startsWith = (bytes: Uint8Array, signature: readonly number[], at = 0) =>
+	signature.every((byte, index) => bytes[at + index] === byte);
+
+const ascii = (text: string) => [...text].map((char) => char.charCodeAt(0));
+
+/**
+ * Whether the bytes are what the type says, for the types whose first bytes say so: the four
+ * image formats the model reads, and PDF. Any other type has nothing to check and passes.
+ */
+export function bytesMatchType(type: string, bytes: Uint8Array): boolean {
+	switch (type) {
+		case "image/png":
+			return startsWith(
+				bytes,
+				[0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+			);
+		case "image/jpeg":
+			return startsWith(bytes, [0xff, 0xd8, 0xff]);
+		case "image/gif":
+			return (
+				startsWith(bytes, ascii("GIF87a")) || startsWith(bytes, ascii("GIF89a"))
+			);
+		case "image/webp":
+			return (
+				startsWith(bytes, ascii("RIFF")) && startsWith(bytes, ascii("WEBP"), 8)
+			);
+		case "application/pdf":
+			return startsWith(bytes, ascii("%PDF-"));
+		default:
+			return true;
+	}
+}

package/src/plugin.ts

@@ -24,6 +24,7 @@ import { TokenRefused, type TokenVerifier } from "./oidc.ts";
 import { TICKET_PROTOCOL_PREFIX, WEBCHAT_PROTOCOL } from "./protocol.ts";
 import { restHandler } from "./rest.ts";
 import { TicketBook } from "./tickets.ts";
+import { DEFAULT_ATTACHMENT_TYPES } from "./uploads.ts";
 
 /** Limits of the WebSocket route, besides the chat's own. */
 export interface WebChatRouteLimits {
@@ -68,6 +69,12 @@ const DEFAULT_LIMITS: WebChatLimits & WebChatRouteLimits = {
 	messageChars: 32_000,
 	promptTimeoutMs: 30 * 60_000,
 	reauthLeadMs: 60_000,
+	attachmentBytes: 10 * 1024 * 1024,
+	attachmentsPerMessage: 8,
+	uploadsPerHour: 60,
+	unsentUploadBytesPerPrincipal: 64 * 1024 * 1024,
+	attachmentTypes: DEFAULT_ATTACHMENT_TYPES,
+	unsentUploadTtlMs: 24 * 60 * 60_000,
 	maxConnections: 256,
 	maxMessageBytes: 64 * 1024,
 	rate: { messages: 60, perMs: 60_000 },
@@ -100,6 +107,41 @@ function checkOptions(options: WebChatOptions): {
 	return { path, surface };
 }
 
+/** The core keeps no file over this; a web chat's own limit may be lower, never higher. */
+const CORE_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+/** The longest wait between two sweeps of uploads no message used. */
+const SWEEP_EVERY_MS = 10 * 60_000;
+
+/** Refuses an attachment limit that is not a positive whole number, or a size the core cannot keep. */
+function checkAttachmentLimits(limits: WebChatLimits): void {
+	for (const key of [
+		"attachmentBytes",
+		"attachmentsPerMessage",
+		"uploadsPerHour",
+		"unsentUploadBytesPerPrincipal",
+		"unsentUploadTtlMs",
+	] as const)
+		if (!Number.isInteger(limits[key]) || limits[key] < 1)
+			throw new Error(
+				`webChat: limits.${key} must be a positive whole number; got ${String(limits[key])}`,
+			);
+	if (limits.attachmentBytes > CORE_ATTACHMENT_BYTES)
+		throw new Error(
+			`webChat: limits.attachmentBytes may be at most ${CORE_ATTACHMENT_BYTES} (25 MiB), the most the core keeps; got ${limits.attachmentBytes}`,
+		);
+	if (
+		!Array.isArray(limits.attachmentTypes) ||
+		limits.attachmentTypes.some(
+			(type) =>
+				typeof type !== "string" ||
+				!/^[a-z0-9.+-]+\/(\*|[a-z0-9.+-]+)$/.test(type),
+		)
+	)
+		throw new Error(
+			'webChat: limits.attachmentTypes must list content types in lower case, such as "image/png" or "image/*"',
+		);
+}
+
 /** The subprotocols a WebSocket upgrade offers. */
 function offered(request: Request): string[] {
 	return (request.headers.get("sec-websocket-protocol") ?? "")
@@ -122,11 +164,16 @@ export function webChat(options: WebChatOptions): RoundtablePlugin {
 	const limits = { ...DEFAULT_LIMITS, ...options.limits };
 	// The personas are checked now, so a broken list stops the configuration rather than the boot.
 	checkPersonas(options.personas);
+	checkAttachmentLimits(limits);
 	return definePlugin({
 		name: surface === "web" ? "webchat" : `webchat-${surface}`,
 		requires: [IDENTITY, CONVERSATIONS, RUNTIME],
 		migrations: [PgNotices.migration],
 		setup: (context: PluginContext) => {
+			if (!context.attachments)
+				throw new Error(
+					"webChat: this version keeps uploaded files with context.attachments, which pi-roundtable 0.9.2 added. Update pi-roundtable to 0.9.2 or later.",
+				);
 			const chat = new WebChat({
 				surface,
 				verifier: options.verifier,
@@ -136,6 +183,7 @@ export function webChat(options: WebChatOptions): RoundtablePlugin {
 				logger: context.logger,
 				registry: () => context.services.get(CONVERSATIONS),
 				conversations: () => context.conversations,
+				attachments: () => context.attachments,
 				turns: () => context.turns,
 				runtime: () => context.services.get(RUNTIME),
 			});
@@ -216,7 +264,41 @@ export function webChat(options: WebChatOptions): RoundtablePlugin {
 				handle: rest,
 				websocket,
 			};
+			// Uploads no message used are deleted once they are older than the limit's time.
+			let sweeper: ReturnType<typeof setInterval> | undefined;
+			const sweep = async () => {
+				try {
+					const dropped = await chat.uploads.sweep();
+					if (dropped > 0)
+						context.logger.info({ dropped }, "unused web chat uploads deleted");
+				} catch (error) {
+					context.logger.warn(
+						{ err: error },
+						"unused web chat uploads not deleted",
+					);
+				}
+			};
 			return {
+				services: [
+					{
+						name: `${surface}-uploads`,
+						start: async () => {
+							// Not caught: a host without a `dataDir` stops here, naming it, instead of failing at the first upload.
+							await chat.uploads.sweep();
+							sweeper = setInterval(
+								sweep,
+								Math.min(
+									SWEEP_EVERY_MS,
+									Math.max(limits.unsentUploadTtlMs, 100),
+								),
+							);
+						},
+						stop: () => {
+							clearInterval(sweeper);
+							sweeper = undefined;
+						},
+					},
+				],
 				surfaces: [chat.surface],
 				channels: [chat.claim()],
 				directChannels: [

package/src/protocol.ts

@@ -65,7 +65,9 @@ export type ErrorCode =
 	| "unknown_persona"
 	| "unknown_prompt"
 	| "too_many_conversations"
-	| "busy";
+	| "busy"
+	/** A `send` named a file that is not waiting for this person in this conversation; the whole message is refused. */
+	| "unknown_attachment";
 
 /** What a client sends: one JSON object per WebSocket text message. */
 export type ClientFrame =
@@ -81,6 +83,11 @@ export type ClientFrame =
 			conversation?: string;
 			persona?: string;
 			text: string;
+			/**
+			 * Files uploaded to the conversation (`POST <path>/conversations/<id>/files`) for this
+			 * message, by the `file` each upload returned; at most `ready.attachments.perMessage`.
+			 */
+			attachments?: string[];
 	  }
 	/** Stops the conversation's running turn. */
 	| { type: "stop"; conversation: string }
@@ -97,6 +104,16 @@ export type ServerFrame =
 			protocol: typeof WEBCHAT_PROTOCOL_VERSION;
 			speaker: { id: string; name: string; tier: Tier; principalId: string };
 			personas: readonly PersonaSummary[];
+			/**
+			 * What an upload may be: the most bytes in a file, the most files in a message, and the
+			 * content types accepted, each exactly or as `<type>/*`. Absent from a server before 0.9.2,
+			 * which takes no attachments: show no upload control then.
+			 */
+			attachments: {
+				maxBytes: number;
+				perMessage: number;
+				types: readonly string[];
+			};
 			/** When the token expires, as an ISO time. */
 			expiresAt: string;
 	  }
@@ -135,6 +152,10 @@ export type ServerFrame =
 
 /** The longest client reference, conversation id, or prompt id accepted. */
 const ID_CHARS = 128;
+/** The longest uploaded file reference accepted: a 36-character id, a dash, and a name cut to 120. */
+const FILE_ID_CHARS = 200;
+/** The most file references one frame may carry, whatever the server's own limit is. */
+const MAX_FRAME_FILES = 32;
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
 	typeof value === "object" && value !== null && !Array.isArray(value);
@@ -142,6 +163,16 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
 const isId = (value: unknown): value is string =>
 	typeof value === "string" && value.length > 0 && value.length <= ID_CHARS;
 
+const isFileList = (value: unknown): value is string[] =>
+	Array.isArray(value) &&
+	value.length <= MAX_FRAME_FILES &&
+	value.every(
+		(item) =>
+			typeof item === "string" &&
+			item.length > 0 &&
+			item.length <= FILE_ID_CHARS,
+	);
+
 const optional = <T>(value: unknown, check: (v: unknown) => v is T) =>
 	value === undefined || check(value);
 
@@ -169,12 +200,17 @@ export function parseClientFrame(
 			if (!optional(conversation, isId) || !optional(persona, isId))
 				return undefined;
 			if (conversation === undefined && persona === undefined) return undefined;
+			if (!optional(value.attachments, isFileList)) return undefined;
+			const { attachments } = value;
 			return {
 				type: "send",
 				id,
 				text,
 				...(conversation === undefined ? {} : { conversation }),
 				...(persona === undefined ? {} : { persona }),
+				...(attachments === undefined || attachments.length === 0
+					? {}
+					: { attachments }),
 			};
 		}
 		case "stop":

package/src/rest.ts

@@ -3,6 +3,7 @@ import { type Admitted, Refusal, type WebChat } from "./chat.ts";
 import { MAX_NOTICES, type PgNotices } from "./notices.ts";
 import { TokenRefused } from "./oidc.ts";
 import type { TicketBook } from "./tickets.ts";
+import { UploadRefusal } from "./uploads.ts";
 
 export interface RestOptions {
 	chat: WebChat;
@@ -62,13 +63,17 @@ const STATUS: Record<string, number> = {
 	unknown_conversation: 404,
 	unknown_persona: 404,
 	too_many_conversations: 429,
+	unknown_attachment: 400,
 };
 
 /**
  * The web chat's REST API, under its path, every call with `Authorization: Bearer <token>`:
  * `POST tickets` (a one-time ticket for the WebSocket), `GET conversations` (the caller's own),
  * `POST conversations` (`{ persona, title? }` opens one), and `GET conversations/<id>/messages`
- * (`?limit=`, its last messages). A browser on another origin gets CORS headers when its origin
+ * (`?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
  * is allowed and 403 otherwise.
  */
 export function restHandler(options: RestOptions) {
@@ -143,6 +148,16 @@ export function restHandler(options: RestOptions) {
 			const entries = await chat.transcript(speaker, messages[1], limit);
 			return json({ messages: entries }, 200, headers);
 		}
+		const files = /^conversations\/([A-Za-z0-9-]{1,128})\/files$/.exec(rest);
+		if (files?.[1] && request.method === "POST") {
+			const uploaded = await chat.upload(
+				speaker,
+				files[1],
+				request,
+				url.searchParams.get("name"),
+			);
+			return json(uploaded, 201, headers);
+		}
 		return json({ error: "not_found" }, 404, headers);
 	}
 	return async (request: Request): Promise<Response> => {
@@ -179,6 +194,8 @@ export function restHandler(options: RestOptions) {
 		try {
 			return await route(request, url, who, headers);
 		} catch (error) {
+			if (error instanceof UploadRefusal)
+				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

@@ -0,0 +1,198 @@
+import type { AttachmentPort, ChannelKey } from "pi-roundtable";
+import { RateWindow } from "./budget.ts";
+import { baseType, bytesMatchType, isAllowedType } from "./file-types.ts";
+
+/** The types a web chat takes unless its `limits.attachmentTypes` says otherwise. */
+export const DEFAULT_ATTACHMENT_TYPES: readonly string[] = [
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif",
+	"application/json",
+	"text/plain",
+	"application/pdf",
+];
+
+/** The limits of uploads and of the attachments a message carries. */
+export interface UploadLimits {
+	/** The largest file in bytes; default 10 MiB, and never over the core's 25 MiB. */
+	attachmentBytes: number;
+	/** The most files one message may reference; default 8. */
+	attachmentsPerMessage: number;
+	/** Uploads one person may make in any hour; default 60. */
+	uploadsPerHour: number;
+	/** The bytes one person may have uploaded and not yet sent in a message; default 64 MiB. */
+	unsentUploadBytesPerPrincipal: number;
+	/** The content types accepted, such as `image/png`; an entry ending in `/*` admits every type under it. */
+	attachmentTypes: readonly string[];
+	/** How long an upload no message referenced is kept before it is deleted; default 24 hours. */
+	unsentUploadTtlMs: number;
+}
+
+/** Why an upload was refused, as the HTTP status and error code the client reads. */
+export class UploadRefusal extends Error {
+	override name = "UploadRefusal";
+	readonly status: number;
+	readonly code:
+		| "bad_request"
+		| "payload_too_large"
+		| "unsupported_media_type"
+		| "too_many_uploads";
+
+	constructor(status: number, code: UploadRefusal["code"]) {
+		super(code);
+		this.status = status;
+		this.code = code;
+	}
+}
+
+/** What an upload returns: `file` is what a `send` frame's `attachments` names. */
+export interface UploadedFile {
+	file: string;
+	name: string;
+	contentType: string;
+	size: number;
+}
+
+export interface UploadsDeps {
+	limits: UploadLimits;
+	/** Read when used, after the host linked every plugin. */
+	attachments(): AttachmentPort;
+	/** The clock, in milliseconds; default `Date.now`. */
+	now?(): number;
+}
+
+const HOUR_MS = 60 * 60_000;
+/** The longest file name accepted, in characters. */
+const NAME_CHARS = 255;
+
+/**
+ * A name the model can read in its prompt: control characters become underscores and quotes
+ * become apostrophes, so a name cannot add lines or close the quotes around it.
+ */
+function safeName(name: string | null): string {
+	const cleaned = (name ?? "")
+		.replace(/\p{Cc}/gu, "_")
+		.replaceAll('"', "'")
+		.trim();
+	if (cleaned === "" || cleaned.length > NAME_CHARS)
+		throw new UploadRefusal(400, "bad_request");
+	return cleaned;
+}
+
+/** The request body, or undefined once it passes `max` bytes; the rest of the stream is not read. */
+async function readLimited(
+	request: Request,
+	max: number,
+): Promise<Uint8Array | undefined> {
+	const reader = request.body?.getReader();
+	if (!reader) return new Uint8Array();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			size += value.byteLength;
+			if (size > max) {
+				await reader.cancel();
+				return undefined;
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const bytes = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return bytes;
+}
+
+/**
+ * The files people upload to their conversations before they send a message: it checks the
+ * content type, the bytes, the size and the person's allowance, and keeps the file with the
+ * core's attachment port until a message uses it. Who may upload to which conversation is the
+ * chat's to decide before it calls `receive`.
+ */
+export class Uploads {
+	readonly #deps: UploadsDeps;
+	readonly #rate: RateWindow;
+
+	constructor(deps: UploadsDeps) {
+		this.#deps = deps;
+		this.#rate = new RateWindow(
+			deps.limits.uploadsPerHour,
+			HOUR_MS,
+			deps.now ?? Date.now,
+		);
+	}
+
+	/** What `ready` tells a client about attachments. */
+	get advertised(): {
+		maxBytes: number;
+		perMessage: number;
+		types: readonly string[];
+	} {
+		const { limits } = this.#deps;
+		return {
+			maxBytes: limits.attachmentBytes,
+			perMessage: limits.attachmentsPerMessage,
+			types: limits.attachmentTypes,
+		};
+	}
+
+	/** Takes the request's body as a file for `principalId` in `channel`; throws an UploadRefusal. */
+	async receive(
+		request: Request,
+		channel: ChannelKey,
+		principalId: string,
+		name: string | null,
+	): Promise<UploadedFile> {
+		const { limits } = this.#deps;
+		const fileName = safeName(name);
+		const type = baseType(request.headers.get("content-type"));
+		if (!type || !isAllowedType(limits.attachmentTypes, type))
+			throw new UploadRefusal(415, "unsupported_media_type");
+		const declared = Number(request.headers.get("content-length"));
+		if (Number.isFinite(declared) && declared > limits.attachmentBytes)
+			throw new UploadRefusal(413, "payload_too_large");
+		if (!this.#rate.take(principalId))
+			throw new UploadRefusal(429, "too_many_uploads");
+		const attachments = this.#deps.attachments();
+		const waiting = await attachments.pendingBytes(principalId);
+		const room = limits.unsentUploadBytesPerPrincipal - waiting;
+		const bytes = await readLimited(
+			request,
+			Math.min(limits.attachmentBytes, Math.max(room, 0)),
+		);
+		if (!bytes)
+			throw room < limits.attachmentBytes
+				? new UploadRefusal(429, "too_many_uploads")
+				: new UploadRefusal(413, "payload_too_large");
+		if (!bytesMatchType(type, bytes))
+			throw new UploadRefusal(415, "unsupported_media_type");
+		const stored = await attachments.save(channel, principalId, {
+			name: fileName,
+			contentType: type,
+			data: bytes,
+		});
+		return {
+			file: stored.file,
+			name: stored.name,
+			contentType: stored.contentType,
+			size: stored.size,
+		};
+	}
+
+	/** Deletes the uploads no message used within the time to live; returns how many. */
+	sweep(): Promise<number> {
+		const now = (this.#deps.now ?? Date.now)();
+		return this.#deps
+			.attachments()
+			.discardPending(new Date(now - this.#deps.limits.unsentUploadTtlMs));
+	}
+}