pi-roundtable 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-13
+
+### Added
+
+- `formatChannelContext` (`formatChannelContext(messages)`) is exported from `pi-roundtable/discord`, the function that writes `ChannelContext.text` (the `<channel-context>` block with each author in attributes and every `<` neutralised), so a host can test what the model sees without a deep import. It is the function the reader already used; nothing about the block changes.
+- `squarePng`, `SquarePngOptions` and `SQUARE_PNG_MAX_SIDE` (4096) are exported from `pi-roundtable/kit`. `squarePng(bytes, { size?, maxBytes?, maxSide? })` is the centered square crop, scaled down to at most `size` pixels per side (default 512) as PNG, that the agent avatars are made with. The header is read before decoding: a declared width or height over 4096 (or `maxSide`) rejects with `ImagePreparationError` (`pixel-limit`, with a message that names the side limit), bytes of no PNG, JPEG or GIF with `invalid-image`; a WebP is refused the same way, since the canvas cannot decode it, and so is any picture that fails to decode. With `maxBytes` the side steps down by a quarter until the PNG fits, and a picture that does not fit at 16 pixels throws a `RangeError`.
+- `discord.attachmentDownload: { deadlineMs?, idleMs? }` (each a whole number of milliseconds from 1,000 to 600,000) sets the limits of the downloads of the files of an owner or agent channel message on the agent server: `deadlineMs` is the overall deadline for the message and its reference together (default 60,000) and `idleMs` the time one file may send no byte before it is given up (default 10,000). `attachmentsOf` takes the same two as `limits.deadlineMs` and `limits.idleMs`, and `AgentServerOptions.attachmentDownload` passes them on for a host built without `defineRoundtable`. A file that goes quiet is recorded as `download failed: idle_timeout` and the next file is tried at once.
+
+### Changed
+
+- The avatar studio refuses a drawn picture that declares a side over 4096 (`ImagePreparationError`, `pixel-limit`), where it used to decode it. The configured `avatar` is not held to that: a photo of any side within the 64 MP decoded-pixel budget is accepted, and one that cannot be read as a picture is logged (`the configured avatar could not be used`, with its error code) and replaced by the plain bot, where it would stop the host from starting.
+- The default overall deadline for downloading the files of a message and its reference rises from 20 to 60 seconds, since a stalled download is now caught by the 10 second idle timeout instead of by the deadline: a body that sends no byte for 10 seconds (the wait for the headers counts, also for a fetch that ignores its abort signal) ends that file alone, where it used to hold every file still to come until the deadline. A slow download that keeps sending bytes now has up to 60 seconds. A host that wants the old bound sets `discord.attachmentDownload.deadlineMs: 20000`.
+
+### Fixed
+
+- An attachment's failure reason never quotes a file system path. A download that fails for any reason other than the ones with their own wording (a size over 25 MB, an HTTP status, the deadline) is recorded as `download failed: <code>`, where the code is the error's `code` (such as `ENOTDIR`, for a directory that could not be made, or `ECONNRESET`) or its `name` (such as `TimeoutError`), and `error` when it has neither; it used to be the error's own text, and the text of a failed `mkdir` quotes the directory. The reason is shown to the model in the turn's attachment block and to the channel, so a path of the host no longer reaches either.
+
 ## [0.12.1] - 2026-10-13
 
 ### Fixed

package/README.md

@@ -197,6 +197,7 @@ When a conversation is started over in a server channel or thread, the assistant
 | `false` | | Post no divider |
 
 An approval card or an `ask_user` question holds its turn for `discord.cardGraceSeconds` (default `120`).
+The files of a message in an agent's channel download within `discord.attachmentDownload.deadlineMs` (default 60,000) for the message and the one it replies to together, and a file that sends no byte for `discord.attachmentDownload.idleMs` (default 10,000) is given up; the turn goes on without a file it could not get.
 The copy button of an approval card keeps its text in `card-copies.json` under the data directory, the newest 100 for 30 days; `discord.cardCopies` (`{ keepDays?, keep? }`) changes that, and `false` keeps them in memory only.
 Answered within it, the turn goes on with the answer; otherwise the turn ends saying it is waiting, the card stays open with no deadline, and answering it later starts a new turn in that conversation with the answer, or with the result of the approved action.
 A coding worker's cards keep the worker waiting instead.

package/README.zh-TW.md

@@ -185,6 +185,7 @@ export default {
 | `attachments` | `{ images: 0, maxBytes: 10 MiB }` | `images`：替這一輪抓取保留訊息中的幾張圖片，最多 4 張 |
 
 核准卡和 `ask_user` 問題會讓這一輪等 `discord.cardGraceSeconds` 秒（預設 `120`）。
+agent 頻道裡訊息的附件，整則訊息（連同它回覆的那則）要在 `discord.attachmentDownload.deadlineMs`（預設 60,000）毫秒內下載完；單一檔案連續 `discord.attachmentDownload.idleMs`（預設 10,000）毫秒沒收到任何位元組就放棄，這一輪會略過收不到的檔案繼續。
 核准卡「複製」按鈕的文字存在資料目錄的 `card-copies.json`，預設留最新 100 張、30 天；`discord.cardCopies`（`{ keepDays?, keep? }`）可以調整，設成 `false` 則只留在記憶體。
 在這段時間內回答，這一輪就帶著答案繼續；沒回答的話，這一輪會說它在等你，然後結束，卡片繼續開著、沒有期限，之後再回答就會在同一個對話開新的一輪，帶上你的答案，或核准後那個動作的結果。
 coding worker 的卡片則會讓 worker 一直等下去。

package/docs/plugins.md

@@ -60,6 +60,9 @@ Use the kit's building blocks for a plugin that runs Pi itself, such as a coding
   `ImagePreparationError.reason` is `byte-limit`, `pixel-limit`, or `invalid-image`; hosts can localize refusals without parsing native decoder errors.
   Ordinary 48 MP images and thin 9000×1 images remain admitted.
   This helper is not a downloader or filesystem validator.
+- Square pictures: `squarePng(bytes, { size?, maxBytes?, maxSide? })` crops a PNG, JPEG or GIF to its centered square and scales it down to at most `size` pixels per side (default 512; a smaller picture is not enlarged), as PNG: the helper the agent avatars are made with, for a plugin that needs a profile picture or an icon.
+  The header is read first, and nothing is decoded for a picture that declares a width or height over `SQUARE_PNG_MAX_SIDE` (4096), which rejects with `ImagePreparationError` (`pixel-limit`, the message naming the side limit; `maxSide` sets another limit, and the 64 MP decoded-pixel budget always applies), or for bytes of no such type, a WebP (the canvas cannot decode it) or a picture that fails to decode (`invalid-image`).
+  With `maxBytes` the side steps down by a quarter at a time until the PNG is no larger; a picture that does not fit even at 16 pixels throws a `RangeError`, as does a `size` or `maxBytes` that is not a whole number in range. `SquarePngOptions` types the options.
 - Work: `promptSlot` (how a run asks the owner while it works), `workTimeout` (a time limit that does not count the time spent waiting on the owner), `runWorkerTask`, `archiveSessions`, and `approvalCard`, `approvalDetails` and `canonicalJson` for the cards of held actions.
   `InterimPoster(posts, { logger, channel, primaryChars?, editMs? })` posts a run's [interim text](#interim-text-what-a-turn-writes-before-its-final-answer) to an `InterimPosts`, such as a dispatch thread's `interim`: feed it `messageEnd(message)` and `toolStart(name)` from the session's events, bind `() => poster.flush()` as the slot's `beforeCard`, and `await poster.flush()` before the final report.
 - Diagnostics: `scrubDiagnostic(text, max = 600)` masks credentials (URL userinfo, token shapes, secret-named assignments and JSON fields, `Authorization`/`Cookie`/`x-api-key` headers, JWTs, PEM blocks), turns control characters other than tab and newline into spaces, and cuts the result at `max` characters.
@@ -553,7 +556,7 @@ A key the contract does not have stops the start and names the closest one.
 ### `context.attachments`: files from outside a turn
 
 A surface that takes a file as it arrives, such as Discord, hands the core a link, and the core downloads it into the conversation's attachment directory.
-The downloads of one message and of the message it replies to share a 20 second deadline; a file still to come when it passes, or whose directory cannot be made, is reported as `download failed` and the turn goes on without it.
+The downloads of one message and of the message it replies to share a 60 second deadline, and a file that sends no byte for 10 seconds (the wait for its headers counts) is given up at once, so a stalled download costs 10 seconds, not the whole deadline. A file still to come when the deadline passes, a file that went quiet (`download failed: idle_timeout`), or one whose directory cannot be made, is reported as `download failed` and the turn goes on without it. `attachmentsOf(message, dir, logger, fetch?, { deadlineMs?, idleMs?, signal? })` takes both limits; on the agent server they are `discord.attachmentDownload: { deadlineMs?, idleMs? }` (each 1,000 to 600,000 ms; defaults 60,000 and 10,000), for a host on a slow link or with large files. A failure reason carries a code only (`download failed: ENOTDIR`, `download failed: TimeoutError`, `download failed: error`), never the error's text, which could quote a path of the host.
 A plugin whose clients upload a file themselves, over HTTP for instance, has the file before any turn exists.
 `context.attachments` keeps such a file for the conversation until a turn uses it:
 
@@ -2317,6 +2320,7 @@ A surface a plugin contributes may implement the optional `ChatSurface.markFresh
 The block gives each author as a name, their Discord id and a role (`owner`, `bot` or `member`) in separate attributes, and says the messages were not addressed to the assistant. A name loses the characters `"`, `'`, `=`, `<`, `>`, `(`, `)` and `,`, so it cannot imitate another author, an attribute or a role, and every `<` (also the full-width `＜`) in a message's text is replaced by `‹`, so a message can neither close the block nor open a message of its own.
 `ChannelContext` is `{ messages, text, images? }`: `messages` are `ChannelContextMessage`s (`id`, `authorId`, `authorName`, `bot`, `owner`, `text`, `at`, `attachments`), oldest first, `text` is the block, and `images` the fetched images (see above).
 `ChannelContextOptions` holds the options above, and `CHANNEL_CONTEXT_DEFAULTS` their defaults.
+`formatChannelContext(messages)` is the function that writes `ChannelContext.text`, exported so a host can test what the model sees without reaching into the core: it takes `ChannelContextMessage`s (only `authorId`, `authorName`, `bot`, `owner` and `text` are read) and returns the block, headed and delimited by `<channel-context>`. Each message is a `<message from="…" id="…" role="owner|member|bot">` line whose author is in the attributes, never in the text, and every `<` of a name or text (plain or full-width) is replaced by `‹`, so no message can pass as markup. It does not fetch, cut or select anything, and it is the same function the reader calls, so a block it returns is the block a turn carries.
 In a test, `fakeDiscord({ channelContext })` answers `DISCORD.channelContext` as the test says; by default with no context.
 
 <!-- example: examples/channel-context.ts -->
@@ -3727,6 +3731,9 @@ Import from the entries listed below; source area files are internal.
 | `withReplyFiles` | `pi-roundtable` | value |
 | `prepareImageBytes` | `pi-roundtable/kit` | value |
 | `ImagePreparationError` | `pi-roundtable/kit` | value |
+| `squarePng` | `pi-roundtable/kit` | value |
+| `SQUARE_PNG_MAX_SIDE` | `pi-roundtable/kit` | value |
+| `SquarePngOptions` | `pi-roundtable/kit` | type |
 | `scrubDiagnostic` | `pi-roundtable/kit` | value |
 | `channelKey` | `pi-roundtable` | value |
 | `definePlugin` | `pi-roundtable` | value |
@@ -3923,6 +3930,7 @@ Import from the entries listed below; source area files are internal.
 | `ChannelContextAttachmentOptions` | `pi-roundtable/discord` | type |
 | `ChannelContextMessage` | `pi-roundtable/discord` | type |
 | `ChannelContextOptions` | `pi-roundtable/discord` | type |
+| `formatChannelContext` | `pi-roundtable/discord` | value |
 | `ChannelExecutor` | `pi-roundtable/discord` | type |
 | `ChannelInfo` | `pi-roundtable/discord` | type |
 | `ChannelOperation` | `pi-roundtable/discord` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.12.1",
+	"version": "0.13.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/agents/agent-claim.ts

@@ -60,6 +60,8 @@ export interface AgentClaimOptions {
 	surface: Pick<SurfacePort, "react" | "unreact">;
 	/** Where a channel's attachments are saved. */
 	attachmentDir: (channel: ChannelKey) => string;
+	/** The downloads' limits: all of a message's files together (default 60 s), and one file without a byte (default 10 s). */
+	attachmentDownload?: { deadlineMs?: number; idleMs?: number };
 	logger: Logger;
 	/** Replaceable in tests. */
 	fetchImpl?: typeof fetch;
@@ -80,7 +82,13 @@ export interface AgentClaimOptions {
 export function agentClaim(options: AgentClaimOptions): ChannelClaim {
 	const { team, runtime, surface, attachmentDir, logger, fetchImpl } = options;
 	const attachments = (message: InboundMessage) =>
-		attachmentsOf(message, attachmentDir(message.channel), logger, fetchImpl);
+		attachmentsOf(
+			message,
+			attachmentDir(message.channel),
+			logger,
+			fetchImpl,
+			options.attachmentDownload,
+		);
 	/** The channel context of a message in an agent's channel; none, logged, when it cannot be read. */
 	const around = async (
 		message: InboundMessage,

package/src/core/agents/avatar-studio.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { createCanvas, loadImage } from "canvas";
+import { squarePng } from "../attachments/square-png.ts";
 import type { ImageDrawer } from "../contract/providers.ts";
 import { ProviderError } from "../errors.ts";
 import type { HttpRoute } from "../http/listeners.ts";
@@ -10,6 +10,8 @@ import { fallbackAvatar } from "./fallback-avatar.ts";
 
 const AVATAR_SIDE = 512;
 const REFERENCE_SIDE = 512;
+/** The configured reference is the host's own photo, so only the decoded-pixel budget limits it. */
+const REFERENCE_MAX_SIDE = Number.MAX_SAFE_INTEGER;
 const HASH_PATH = /^\/avatars\/([0-9a-f]{64})\.png$/;
 
 export type { ImageDrawer };
@@ -21,32 +23,14 @@ export interface AvatarStudioOptions {
 	publicUrl: string;
 	/** The assistant's neutral avatar: the style reference and the picture of an agent without one. */
 	referencePath: string;
+	/** The neutral avatar shipped with the package; the reference is replaced by it when the reference cannot be read as a picture. */
+	neutralPath?: string;
+	/** Told the error code of a reference that was replaced by `neutralPath`. */
+	onReferenceFailed?: (code: string) => void;
 	/** Draws the pictures. Without one, the studio only makes each agent a picture from its name. */
 	draw?: ImageDrawer;
 }
 
-/** A centered square crop scaled to at most `side` pixels, as PNG. */
-async function squarePng(bytes: Uint8Array, side: number): Promise<Buffer> {
-	const image = await loadImage(Buffer.from(bytes));
-	const crop = Math.min(image.width, image.height);
-	const size = Math.min(side, crop);
-	const canvas = createCanvas(size, size);
-	canvas
-		.getContext("2d")
-		.drawImage(
-			image,
-			(image.width - crop) / 2,
-			(image.height - crop) / 2,
-			crop,
-			crop,
-			0,
-			0,
-			size,
-			size,
-		);
-	return canvas.toBuffer("image/png");
-}
-
 /**
  * Agent avatars: an image provider draws them in the assistant's style, and without one each agent
  * gets a picture generated from its display name. They are kept and served by content hash, so a
@@ -55,17 +39,37 @@ async function squarePng(bytes: Uint8Array, side: number): Promise<Buffer> {
 export class FileAvatarStudio implements AvatarStudio {
 	readonly #options: AvatarStudioOptions;
 	#defaultHash: string | undefined;
+	#referencePath: string;
 
 	constructor(options: AvatarStudioOptions) {
 		this.#options = options;
+		this.#referencePath = options.referencePath;
 		mkdirSync(options.dir, { recursive: true });
 	}
 
 	/** Stores the assistant's neutral avatar, the picture of an agent that has none yet. */
 	async init(): Promise<void> {
-		this.#defaultHash = await this.#store(
-			readFileSync(this.#options.referencePath),
-		);
+		try {
+			this.#defaultHash = await this.#referenceStore();
+		} catch (error) {
+			const { neutralPath, onReferenceFailed } = this.#options;
+			if (!neutralPath || neutralPath === this.#referencePath) throw error;
+			const code =
+				(error as { code?: unknown }).code ??
+				(error as { reason?: unknown }).reason ??
+				(error as Error).name;
+			onReferenceFailed?.(
+				/^[A-Za-z][A-Za-z0-9_-]{0,40}$/.test(String(code))
+					? String(code)
+					: "error",
+			);
+			this.#referencePath = neutralPath;
+			this.#defaultHash = await this.#referenceStore();
+		}
+	}
+
+	async #referenceStore(): Promise<string> {
+		return this.#store(readFileSync(this.#referencePath), REFERENCE_MAX_SIDE);
 	}
 
 	/** Whether an image provider is configured; without one, only `fallback` makes pictures. */
@@ -87,10 +91,10 @@ export class FileAvatarStudio implements AvatarStudio {
 	 */
 	async draw(avatarPrompt: string): Promise<string> {
 		const draw = this.#drawer();
-		const reference = await squarePng(
-			readFileSync(this.#options.referencePath),
-			REFERENCE_SIDE,
-		);
+		const reference = await squarePng(readFileSync(this.#referencePath), {
+			size: REFERENCE_SIDE,
+			maxSide: REFERENCE_MAX_SIDE,
+		});
 		const bytes = await draw(
 			`Draw a square Discord avatar of the person in the reference image, redrawn as an anime character: keep their face, short dark hair, and features recognizable as the same person, but in vivid anime cel-shading with a big, exaggerated expression and a dramatic pose that shows the role. Dress them and paint the background exactly in the colours the description names; ignore the reference's green jacket and teal background. Head-and-shoulders framing that still reads at 40 px. No text, no border. The role: ${avatarPrompt}`,
 			[{ data: reference.toString("base64"), mimeType: "image/png" }],
@@ -119,7 +123,7 @@ export class FileAvatarStudio implements AvatarStudio {
 		return this.#store(
 			await fallbackAvatar(
 				displayName,
-				readFileSync(this.#options.referencePath),
+				readFileSync(this.#referencePath),
 				name,
 			),
 		);
@@ -171,8 +175,11 @@ export class FileAvatarStudio implements AvatarStudio {
 		return join(this.#options.dir, `${hash}.png`);
 	}
 
-	async #store(bytes: Uint8Array): Promise<string> {
-		const png = await squarePng(bytes, AVATAR_SIDE);
+	async #store(bytes: Uint8Array, maxSide?: number): Promise<string> {
+		const png = await squarePng(bytes, {
+			size: AVATAR_SIDE,
+			...(maxSide === undefined ? {} : { maxSide }),
+		});
 		const hash = createHash("sha256").update(png).digest("hex");
 		const path = this.#path(hash);
 		if (!existsSync(path)) writeFileSync(path, png);

package/src/core/attachments/attachment-fetcher.ts

@@ -9,6 +9,9 @@ import { plainText } from "./attachment-name.ts";
 
 export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
 
+/** How long one download may go without a byte (the headers count as the first) before it is given up, by default. */
+export const DEFAULT_IDLE_MS = 10_000;
+
 export interface FetchRequest {
 	refs: readonly AttachmentRef[];
 	/** Directory of the channel's attachment store; created when missing. */
@@ -18,6 +21,8 @@ export interface FetchRequest {
 	fromReference: boolean;
 	/** Aborts the download of the files still to come, and the one in flight. */
 	signal?: AbortSignal;
+	/** Gives up on a file that sends no byte for this long, and goes on to the next; default 10 s. */
+	idleMs?: number;
 }
 
 export interface FetchResult {
@@ -58,6 +63,70 @@ export function safeFileName(name: string): string {
 	return cleaned || "file";
 }
 
+/**
+ * A failure's code, never its message: a message can quote the directory a file was to be written
+ * to, a host path the model and the channel have no use for. The code is an error's `code` (such
+ * as `ENOTDIR`) or its `name` (such as `TimeoutError`), and `error` when it has neither.
+ */
+function failureCode(error: unknown): string {
+	const word = /^[A-Za-z][A-Za-z0-9_]{0,40}$/;
+	if (typeof error !== "object" || error === null) return "error";
+	const { code, name } = error as { code?: unknown; name?: unknown };
+	if (typeof code === "string" && word.test(code)) return code;
+	if (typeof name === "string" && name !== "Error" && word.test(name))
+		return name;
+	return "error";
+}
+
+/**
+ * Ends a download that has gone quiet: `signal` aborts, with the reason `idle`, once `idleMs` pass
+ * without a `touch`, and also when the outer signal does.
+ */
+class IdleWatch {
+	readonly signal: AbortSignal;
+	readonly #own = new AbortController();
+	readonly #idleMs: number;
+	#timer: ReturnType<typeof setTimeout> | undefined;
+
+	constructor(idleMs: number, outer?: AbortSignal) {
+		this.#idleMs = idleMs;
+		this.signal = outer
+			? AbortSignal.any([outer, this.#own.signal])
+			: this.#own.signal;
+		this.touch();
+	}
+
+	/** Whether the download was ended for want of bytes, not by the outer signal. */
+	get idled(): boolean {
+		return this.#own.signal.aborted;
+	}
+
+	touch(): void {
+		clearTimeout(this.#timer);
+		this.#timer = setTimeout(
+			() => this.#own.abort(new Error("idle")),
+			this.#idleMs,
+		);
+	}
+
+	stop(): void {
+		clearTimeout(this.#timer);
+	}
+}
+
+/** Rejects with the signal's reason when it aborts, so a fetch that ignores the signal still ends. */
+function untilAborted<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	let onAbort: (() => void) | undefined;
+	const aborted = new Promise<never>((_, reject) => {
+		onAbort = () => reject(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	return Promise.race([work, aborted]).finally(() => {
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+	});
+}
+
 /** Downloads attachments one by one; a failed file is reported without stopping the others. */
 export async function fetchAttachments(
 	request: FetchRequest,
@@ -66,6 +135,7 @@ export async function fetchAttachments(
 	const files: StoredAttachment[] = [];
 	const failures: AttachmentFailure[] = [];
 	const { refs, dir, prefix, fromReference, signal } = request;
+	const idleMs = request.idleMs ?? DEFAULT_IDLE_MS;
 	if (refs.length === 0) return { files, failures };
 
 	for (const [index, ref] of refs.entries()) {
@@ -79,19 +149,20 @@ export async function fetchAttachments(
 			fail(`larger than 25 MB (${ref.size} bytes)`);
 			continue;
 		}
+		const watch = new IdleWatch(idleMs, signal);
 		try {
 			// A directory that cannot be made fails the file, not the turn.
 			mkdirSync(dir, { recursive: true, mode: 0o700 });
-			const response = await fetchImpl(
-				ref.url,
-				signal ? { signal } : undefined,
+			const response = await untilAborted(
+				fetchImpl(ref.url, { signal: watch.signal }),
+				watch.signal,
 			);
 			if (!response.ok) {
 				await response.body?.cancel();
 				fail(`download failed with HTTP ${response.status}`);
 				continue;
 			}
-			const data = await readAttachmentBody(response, signal);
+			const data = await readAttachmentBody(response, watch);
 			if (typeof data === "number") {
 				fail(`larger than 25 MB (${data} bytes)`);
 				continue;
@@ -111,7 +182,11 @@ export async function fetchAttachments(
 				fromReference,
 			});
 		} catch (error) {
-			fail(`download failed: ${String(error)}`);
+			fail(
+				`download failed: ${watch.idled && !signal?.aborted ? "idle_timeout" : failureCode(error)}`,
+			);
+		} finally {
+			watch.stop();
 		}
 	}
 	return { files, failures };
@@ -120,20 +195,22 @@ export async function fetchAttachments(
 /** Returns the bytes, or the observed size once the stream exceeds the limit. */
 async function readAttachmentBody(
 	response: Response,
-	signal?: AbortSignal,
+	watch: IdleWatch,
 ): Promise<Uint8Array | number> {
 	if (!response.body) return new Uint8Array();
+	const { signal } = watch;
 	const reader = response.body.getReader();
 	const chunks: Uint8Array[] = [];
 	let size = 0;
 	// A body that stalls ends with the signal, also when the fetch itself ignores it.
-	const stop = () => void reader.cancel(signal?.reason).catch(() => {});
-	signal?.addEventListener("abort", stop, { once: true });
+	const stop = () => void reader.cancel(signal.reason).catch(() => {});
+	signal.addEventListener("abort", stop, { once: true });
 	try {
-		if (signal?.aborted) throw signal.reason ?? new Error("aborted");
+		if (signal.aborted) throw signal.reason ?? new Error("aborted");
 		for (;;) {
 			const { done, value } = await reader.read();
 			if (done) break;
+			watch.touch();
 			size += value.byteLength;
 			if (size > MAX_ATTACHMENT_BYTES) {
 				await reader.cancel();
@@ -142,9 +219,9 @@ async function readAttachmentBody(
 			chunks.push(value);
 		}
 		// A cancelled reader reads as the end of the body, so a cut-short body is not a whole file.
-		if (signal?.aborted) throw signal.reason ?? new Error("aborted");
+		if (signal.aborted) throw signal.reason ?? new Error("aborted");
 	} finally {
-		signal?.removeEventListener("abort", stop);
+		signal.removeEventListener("abort", stop);
 		reader.releaseLock();
 	}
 	const data = new Uint8Array(size);

package/src/core/attachments/image-budget.ts

@@ -2,10 +2,22 @@ import { ImagePreparationError } from "./image-preparation-error.ts";
 
 const invalid = () => new ImagePreparationError("invalid-image");
 
-/** Inspect only encoded headers/blocks. Never allocate a raster or follow a media URL. */
-export function assertImagePixelBudget(bytes: Buffer, budget: number): void {
+/**
+ * Inspect only encoded headers/blocks. Never allocate a raster or follow a media URL. With
+ * `maxSide`, a declared width or height (of a canvas or of any frame) over it is `pixel-limit` too.
+ */
+export function assertImagePixelBudget(
+	bytes: Buffer,
+	budget: number,
+	maxSide?: number,
+): void {
 	const pixels = (width: number, height: number): number => {
 		if (width < 1 || height < 1) throw invalid();
+		if (maxSide !== undefined && (width > maxSide || height > maxSide))
+			throw new ImagePreparationError(
+				"pixel-limit",
+				`Image exceeds the ${maxSide}-pixel side limit.`,
+			);
 		const area = width * height;
 		check(area);
 		return area;

package/src/core/attachments/image-preparation-error.ts

@@ -2,13 +2,17 @@
 export class ImagePreparationError extends Error {
 	override readonly name = "ImagePreparationError";
 
-	constructor(readonly reason: "byte-limit" | "pixel-limit" | "invalid-image") {
+	constructor(
+		readonly reason: "byte-limit" | "pixel-limit" | "invalid-image",
+		detail?: string,
+	) {
 		super(
-			{
-				"byte-limit": "Image is larger than 25 MiB.",
-				"pixel-limit": "Image exceeds the 64 MP decoded-pixel budget.",
-				"invalid-image": "Image has an invalid or unsupported raster header.",
-			}[reason],
+			detail ??
+				{
+					"byte-limit": "Image is larger than 25 MiB.",
+					"pixel-limit": "Image exceeds the 64 MP decoded-pixel budget.",
+					"invalid-image": "Image has an invalid or unsupported raster header.",
+				}[reason],
 		);
 	}
 }

package/src/core/attachments/square-png.ts

@@ -0,0 +1,94 @@
+import { createCanvas, loadImage } from "canvas";
+import { assertImagePixelBudget } from "./image-budget.ts";
+import { ImagePreparationError } from "./image-preparation-error.ts";
+
+/** The longest side a picture may declare before `squarePng` refuses to decode it. */
+export const SQUARE_PNG_MAX_SIDE = 4096;
+/** The side `squarePng` scales to when it is not told one. */
+const DEFAULT_SIDE = 512;
+/** Below this side `squarePng` gives up fitting `maxBytes`. */
+const SMALLEST_SIDE = 16;
+/** Frames of an animation add up, so the whole stays within the budget `prepareImageBytes` allows. */
+const DECODED_PIXEL_BUDGET = 8000 * 8000;
+
+export interface SquarePngOptions {
+	/** The most pixels per side of the result; default 512. A smaller picture is not enlarged. */
+	size?: number;
+	/** The most bytes of the result; the side steps down by a quarter until it fits. Default none. */
+	maxBytes?: number;
+	/**
+	 * The longest side the picture may declare before it is refused, default 4096
+	 * (`SQUARE_PNG_MAX_SIDE`). A picture within the 64 MP decoded-pixel budget but over it, such as a
+	 * camera photo, is admitted by a larger value.
+	 */
+	maxSide?: number;
+}
+
+const wholeNumber = (name: string, value: number, max: number) => {
+	if (!Number.isInteger(value) || value < 1 || value > max)
+		throw new RangeError(
+			`squarePng: ${name} must be a whole number from 1 to ${max}`,
+		);
+};
+
+/**
+ * A centered square crop of a PNG, JPEG or GIF, scaled down to at most `size` pixels per
+ * side, as PNG. The header is read before anything is decoded: a declared width or height over
+ * 4096 (`SQUARE_PNG_MAX_SIDE`, or `maxSide`) rejects with `ImagePreparationError` (`pixel-limit`),
+ * and bytes of none of the three types (WebP included) with `invalid-image`, as does a picture
+ * that cannot be decoded. With `maxBytes` the side steps down (by a quarter
+ * each time) until the PNG is no larger; a picture that does not fit even at 16 pixels throws a
+ * `RangeError`.
+ */
+export async function squarePng(
+	bytes: Uint8Array,
+	options: SquarePngOptions = {},
+): Promise<Buffer> {
+	const side = options.size ?? DEFAULT_SIDE;
+	wholeNumber("size", side, SQUARE_PNG_MAX_SIDE);
+	if (options.maxBytes !== undefined)
+		wholeNumber("maxBytes", options.maxBytes, Number.MAX_SAFE_INTEGER);
+	if (options.maxSide !== undefined)
+		wholeNumber("maxSide", options.maxSide, Number.MAX_SAFE_INTEGER);
+	const source = Buffer.from(bytes);
+	// The canvas has no WebP decoder, so a WebP is refused here rather than failing in the decode.
+	if (
+		source.toString("ascii", 0, 4) === "RIFF" &&
+		source.toString("ascii", 8, 12) === "WEBP"
+	)
+		throw new ImagePreparationError("invalid-image");
+	assertImagePixelBudget(
+		source,
+		DECODED_PIXEL_BUDGET,
+		options.maxSide ?? SQUARE_PNG_MAX_SIDE,
+	);
+	const image = await loadImage(source).catch(() => {
+		throw new ImagePreparationError("invalid-image");
+	});
+	const crop = Math.min(image.width, image.height);
+	let size = Math.min(side, crop);
+	for (;;) {
+		const canvas = createCanvas(size, size);
+		canvas
+			.getContext("2d")
+			.drawImage(
+				image,
+				(image.width - crop) / 2,
+				(image.height - crop) / 2,
+				crop,
+				crop,
+				0,
+				0,
+				size,
+				size,
+			);
+		const png = canvas.toBuffer("image/png");
+		if (options.maxBytes === undefined || png.byteLength <= options.maxBytes)
+			return png;
+		size = Math.floor(size * 0.75);
+		if (size < SMALLEST_SIDE)
+			throw new RangeError(
+				`squarePng: the picture does not fit ${options.maxBytes} bytes even at ${SMALLEST_SIDE} pixels`,
+			);
+	}
+}

package/src/core/attachments/turn-attachments.ts

@@ -4,8 +4,11 @@ import type { Logger } from "../log.ts";
 import { fetchAttachments } from "./attachment-fetcher.ts";
 import { modelImagesOf } from "./model-images.ts";
 
-/** The most milliseconds all of a message's downloads take together by default. */
-const DEADLINE_MS = 20_000;
+/**
+ * The most milliseconds all of a message's downloads take together by default. A download that
+ * stalls ends at `DEFAULT_IDLE_MS` without bytes, so the deadline only has to cover slow ones.
+ */
+export const DEFAULT_DEADLINE_MS = 60_000;
 
 /** Saves the message's and its reference's files, and turns up to four images into model images. */
 export async function collectAttachments(
@@ -14,17 +17,22 @@ export async function collectAttachments(
 	options: {
 		logger: Logger;
 		fetchImpl?: typeof fetch;
-		/** One deadline for the message's and its reference's files together; default 20 s. */
+		/** One deadline for the message's and its reference's files together; default 60 s. */
 		deadlineMs?: number;
+		/** How long one file may send no byte before it is given up and the next one tried; default 10 s. */
+		idleMs?: number;
 		/** Aborts the downloads, as the deadline does. */
 		signal?: AbortSignal;
 	},
 ): Promise<TurnAttachments> {
 	const { fetchImpl, logger } = options;
-	const deadline = AbortSignal.timeout(options.deadlineMs ?? DEADLINE_MS);
+	const deadline = AbortSignal.timeout(
+		options.deadlineMs ?? DEFAULT_DEADLINE_MS,
+	);
 	const signal = options.signal
 		? AbortSignal.any([deadline, options.signal])
 		: deadline;
+	const idle = options.idleMs === undefined ? {} : { idleMs: options.idleMs };
 	const own = await fetchAttachments(
 		{
 			refs: message.attachments,
@@ -32,6 +40,7 @@ export async function collectAttachments(
 			prefix: message.messageId,
 			fromReference: false,
 			signal,
+			...idle,
 		},
 		fetchImpl,
 	);
@@ -42,6 +51,7 @@ export async function collectAttachments(
 			prefix: `${message.messageId}-ref`,
 			fromReference: true,
 			signal,
+			...idle,
 		},
 		fetchImpl,
 	);
@@ -70,7 +80,7 @@ export function attachmentsOf(
 	dir: string,
 	logger: Logger,
 	fetchImpl?: typeof fetch,
-	limits: { deadlineMs?: number; signal?: AbortSignal } = {},
+	limits: { deadlineMs?: number; idleMs?: number; signal?: AbortSignal } = {},
 ): Promise<TurnAttachments> {
 	return collectAttachments(message, dir, {
 		logger,

package/src/core/builtin/agent-server.ts

@@ -69,6 +69,12 @@ export interface AgentServerOptions {
 	 * `"owners"`, which leaves a speaker below the owner tier unanswered.
 	 */
 	speakers?: "everyone" | "owners";
+	/**
+	 * Limits of the downloads of a message's files (`discord.attachmentDownload`): `deadlineMs`
+	 * for all of a message's files together (default 60 s), `idleMs` for one file to send no byte
+	 * (default 10 s).
+	 */
+	attachmentDownload?: { deadlineMs?: number; idleMs?: number };
 	/** The prompt every agent starts with, and the one for speakers other than the owner. */
 	prompts: { shared: string; guest?: string };
 	/** The listener the avatar pictures are served on. */
@@ -77,6 +83,8 @@ export interface AgentServerOptions {
 	avatarUrl: string;
 	/** The assistant's neutral avatar: the style reference and the picture of an agent without one. */
 	avatarReference: string;
+	/** The picture used instead when `avatarReference` cannot be read as one; the failure is logged. */
+	avatarNeutral?: string;
 	/** Reports the process's own errors to an agent; without one nothing is reported. */
 	errorReporter?: ErrorReporter;
 }
@@ -155,6 +163,16 @@ export function agentServerPlugin(
 				dir: join(options.dataDir, "avatars"),
 				publicUrl: options.avatarUrl,
 				referencePath: options.avatarReference,
+				...(options.avatarNeutral
+					? {
+							neutralPath: options.avatarNeutral,
+							onReferenceFailed: (code: string) =>
+								logger.warn(
+									{ code },
+									"the configured avatar could not be used; the neutral avatar is used instead",
+								),
+						}
+					: {}),
 				// Without an image provider the studio makes each agent a picture from its name.
 				...(providers.filled.has("images") ? { draw: providers.images } : {}),
 			});
@@ -293,6 +311,9 @@ export function agentServerPlugin(
 						runtime: running,
 						surface: context.surfaces,
 						attachmentDir,
+						...(options.attachmentDownload
+							? { attachmentDownload: options.attachmentDownload }
+							: {}),
 						logger,
 						channelContext: (message) => discord.channelContext(message),
 					}),

package/src/core/config/adapters.ts

@@ -71,6 +71,14 @@ export interface DiscordConfig {
 	 * remove them; they age out.
 	 */
 	cardCopies?: { keepDays?: number; keep?: number } | false;
+	/**
+	 * How the files of an owner's or an agent's channel message are downloaded: `deadlineMs`
+	 * (default 60,000) is the most time all of a message's files, and those of the message it
+	 * replies to, may take together; `idleMs` (default 10,000) is how long one file may send no
+	 * byte before it is given up. A file still to come at the deadline, or one that went quiet, is
+	 * reported as `download failed` and the turn goes on without it.
+	 */
+	attachmentDownload?: { deadlineMs?: number; idleMs?: number };
 }
 
 /** The Discord settings with every default filled in. */
@@ -89,6 +97,8 @@ export interface ResolvedDiscord {
 	cardGraceSeconds: number;
 	/** As configured: `{}` when left out, so the defaults apply, or `false`. */
 	cardCopies: NonNullable<DiscordConfig["cardCopies"]> | false;
+	/** As configured: left out unless set, so the defaults apply. */
+	attachmentDownload?: NonNullable<DiscordConfig["attachmentDownload"]>;
 }
 
 /** The configured Discord settings, defaults filled in; `rootCommand` is the host's slug. */
@@ -117,6 +127,9 @@ export function resolvedDiscord(
 			: { freshMarker: discord.freshMarker }),
 		cardGraceSeconds: discord.cardGraceSeconds ?? 120,
 		cardCopies: discord.cardCopies ?? {},
+		...(discord.attachmentDownload === undefined
+			? {}
+			: { attachmentDownload: discord.attachmentDownload }),
 	};
 }
 
@@ -163,6 +176,12 @@ export const discordShape = shape({
 			}),
 		),
 	),
+	attachmentDownload: optional(
+		shape({
+			deadlineMs: optional(integer(1_000, 600_000)),
+			idleMs: optional(integer(1_000, 600_000)),
+		}),
+	),
 });
 
 /** The adapters `adapters` takes, by the name their factory gives them. */

package/src/core/config/config.ts

@@ -146,7 +146,11 @@ export interface RoundtableConfig {
 		socketPath?: string;
 		socketMode?: number;
 	};
-	/** A picture of your own for agents without one, and the style reference for drawing them; default a plain bot. */
+	/**
+	 * A picture of your own for agents without one, and the style reference for drawing them; default
+	 * a plain bot. A PNG, JPEG or GIF of any side within the 64 MP decoded-pixel budget (an ordinary
+	 * camera photo); one that cannot be read as a picture is logged and the plain bot is used.
+	 */
 	avatar?: string;
 	/** The agents' shared working directory; default `<dataDir>/work`. */
 	workDir?: string;

package/src/core/define-roundtable.ts

@@ -202,10 +202,14 @@ function discordAssembly(
 			prompts: { shared: sharedPrompt, guest },
 			...(discord.agentMemory ? { memory: discord.agentMemory } : {}),
 			...(discord.agentSpeakers ? { speakers: discord.agentSpeakers } : {}),
+			...(discord.attachmentDownload
+				? { attachmentDownload: discord.attachmentDownload }
+				: {}),
 			avatarListener: "public",
 			// resolveConfig refuses Discord without a public address.
 			avatarUrl: config.http?.publicUrl ?? "",
 			avatarReference: config.avatar ?? join(ASSETS, "neutral.png"),
+			avatarNeutral: join(ASSETS, "neutral.png"),
 			// An ops agent's reports are the agent server's to deliver.
 			...(errorReporter && "agent" in errorReporter.destination
 				? { errorReporter }

package/src/discord/index.ts

@@ -21,7 +21,10 @@ export type {
 	AgentPanelOptions,
 } from "../core/discord/agent-panel.ts";
 export { agentPanel } from "../core/discord/agent-panel.ts";
-export { CHANNEL_CONTEXT_DEFAULTS } from "../core/discord/channel-context.ts";
+export {
+	CHANNEL_CONTEXT_DEFAULTS,
+	formatChannelContext,
+} from "../core/discord/channel-context.ts";
 export type { ManagedChannel } from "../core/discord/channel-executor.ts";
 export {
 	fetchManagedChannel,

package/src/kit/channels.ts

@@ -9,6 +9,11 @@ export {
 export { prepareImageBytes } from "../core/attachments/image-prep.ts";
 export { ImagePreparationError } from "../core/attachments/image-preparation-error.ts";
 export { withAttachmentsBlock } from "../core/attachments/prompt-block.ts";
+export {
+	SQUARE_PNG_MAX_SIDE,
+	type SquarePngOptions,
+	squarePng,
+} from "../core/attachments/square-png.ts";
 export { attachmentsOf } from "../core/attachments/turn-attachments.ts";
 export type { ChannelQueue } from "../core/routing/channel-queue.ts";
 export { channelQueue } from "../core/routing/channel-queue.ts";

package/src/kit/index.ts

@@ -10,7 +10,10 @@ export {
 	outcome,
 	ownerAttachmentDir,
 	prepareImageBytes,
+	SQUARE_PNG_MAX_SIDE,
+	type SquarePngOptions,
 	settleTurn,
+	squarePng,
 	withAttachmentsBlock,
 	withReference,
 } from "./channels.ts";