pi-roundtable 0.22.4 → 0.23.0

package/src/core/agents/team-turns.ts

@@ -1,16 +1,18 @@
+import { channelKey, parseChannelKey } from "../contract/surface.ts";
 import type { TurnAttachments } from "../domain/attachment.ts";
 import type {
 	ChannelKey,
 	PendingConfirmation,
+	PostAuthor,
 	ReplyFile,
 	TurnResult,
 } from "../domain/conversation.ts";
 import { AgentError } from "../domain/errors.ts";
 import type { InterimPosts } from "../domain/interim.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
-import { failureNotice } from "../presentation/failure-notice.ts";
+import type { TurnProgress } from "../domain/progress.ts";
+import { replyBody } from "../presentation/reply-body.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
-import { thinkingLine } from "../presentation/thinking-line.ts";
 import { withReplyFiles } from "../reply-files.ts";
 import { endOf, settleTurn } from "../routing/settle-turn.ts";
 import { mayApproveNamed } from "../runtime/extensions/held-calls.ts";
@@ -20,10 +22,15 @@ import { AgentMessages } from "./agent-messages.ts";
 import type { Agent } from "./agent-store.ts";
 import { GroupTurns } from "./group-turns.ts";
 import {
+	agentOfChannel,
 	channelIdOf,
 	channelOwner,
+	coordinatorOf,
+	discordIdOf,
 	discordKey,
 	homeScope,
+	keysOf,
+	roomScope,
 } from "./team-keys.ts";
 import {
 	type Chain,
@@ -45,6 +52,8 @@ export class TeamTurns {
 	readonly #chains = new Map<ChannelKey, Chain>();
 	/** The channel each working agent's turn posts in. */
 	readonly #working = new Map<string, ChannelKey>();
+	/** The channel each running turn posts in, by session key; a seat's turns run in its group's room. */
+	readonly #posting = new Map<ChannelKey, ChannelKey>();
 	/** When each agent or group (by `group:<name>`) last started or ended a turn. */
 	readonly #lastActive = new Map<string, Date>();
 
@@ -97,7 +106,7 @@ export class TeamTurns {
 		attachments: TurnAttachments,
 	): Promise<TurnResult> {
 		const agent = this.#agentOf(channel);
-		const scope = homeScope(agent);
+		const scope = this.#scopeOf(agent, channel);
 		const pending = await this.#options.runtime().heldActions(scope.session);
 		const confirmed =
 			pending !== undefined &&
@@ -131,7 +140,7 @@ export class TeamTurns {
 		const agent = this.#agentOf(channel);
 		return this.#turn(
 			agent,
-			homeScope(agent),
+			this.#scopeOf(agent, channel),
 			channel,
 			text,
 			{ messages: 0, speaker },
@@ -164,12 +173,30 @@ export class TeamTurns {
 		);
 	}
 
+	/** The surfaces that host rooms; none for a team without a surface port. */
+	#rooms(channel: ChannelKey): readonly string[] {
+		// Only a room key needs the list, which a surface port gives once the hosts are linked.
+		return discordIdOf(channel) === undefined
+			? (this.#options.surfaces?.roomSurfaces() ?? [])
+			: [];
+	}
+
+	/** The agent whose channel or room it is. */
 	#agentOf(channel: ChannelKey): Agent {
-		const agent = this.#options.store.agentByChannel(channelIdOf(channel));
-		if (!agent) throw new AgentError(`no agent owns ${channel}`);
+		const { store, surfaces } = this.#options;
+		const agent = agentOfChannel(store, surfaces, channel);
+		if (agent?.status !== "active")
+			throw new AgentError(`no agent owns ${channel}`);
 		return agent;
 	}
 
+	/** The agent's own conversation in the channel: its Discord channel's, or its room's. */
+	#scopeOf(agent: Agent, channel: ChannelKey): AgentTurnScope {
+		return discordIdOf(channel) === undefined
+			? roomScope(agent, channel)
+			: homeScope(agent);
+	}
+
 	/**
 	 * Runs one agent turn and posts its reply, or a failure notice, in `postTo` under the
 	 * agent's name. Never rejects.
@@ -187,6 +214,7 @@ export class TeamTurns {
 		// A group round has several sessions; only an agent's own channel maps to one.
 		const hideStop = scope.group ? undefined : showStop(postTo);
 		this.#chains.set(scope.session, chain);
+		this.#posting.set(scope.session, postTo);
 		this.#working.set(agent.name, postTo);
 		this.#active(agent.name, scope.group);
 		const turn = {
@@ -198,11 +226,12 @@ export class TeamTurns {
 		};
 		this.#options.events?.turnStarted(turn);
 		const interim = this.#interim(postTo, agent);
+		const progress = this.#progress(postTo);
 		let result: TurnResult;
 		try {
 			result = await settleTurn(
 				() =>
-					withReplyFiles(true, () =>
+					withReplyFiles(this.#carriesFiles(postTo), () =>
 						this.#options.runtime().runTurn({
 							channel: postTo,
 							selection: this.#options.selection(scope),
@@ -214,6 +243,7 @@ export class TeamTurns {
 							agent: scope,
 							speaker: chain.speaker,
 							...(interim ? { interim } : {}),
+							...(progress ? { progress } : {}),
 						}),
 					),
 				"agent turn",
@@ -221,6 +251,7 @@ export class TeamTurns {
 		} finally {
 			hideStop?.();
 			this.#chains.delete(scope.session);
+			this.#posting.delete(scope.session);
 			this.#working.delete(agent.name);
 			this.#active(agent.name, scope.group);
 		}
@@ -235,15 +266,7 @@ export class TeamTurns {
 					"agent turn failed",
 				);
 			}
-			const thinking =
-				result.ok && result.thinking
-					? thinkingLine(result.thinking)
-					: undefined;
-			await this.#post(postTo, this.#current(agent), {
-				...(thinking ? { thinking } : {}),
-				chunks: result.ok ? splitReply(result.text) : [failureNotice(result)],
-				...(result.ok && result.files?.length ? { files: result.files } : {}),
-			});
+			await this.#post(postTo, this.#current(agent), replyBody(result));
 		} catch (error) {
 			logger.error({ agent: agent.name, err: error }, "agent reply not posted");
 		} finally {
@@ -252,6 +275,17 @@ export class TeamTurns {
 		return result;
 	}
 
+	/**
+	 * Whether a reply in the channel may carry files: Discord's webhook posts do; a room only when
+	 * its surface declares `supportsFiles`, since a reply with files that surface refuses is lost whole.
+	 */
+	#carriesFiles(channel: ChannelKey): boolean {
+		return (
+			discordIdOf(channel) !== undefined ||
+			this.#options.surfaces?.of(channel)?.supportsFiles === true
+		);
+	}
+
 	#active(agent: string, group: string | undefined): void {
 		const now = new Date();
 		this.#lastActive.set(agent, now);
@@ -264,13 +298,47 @@ export class TeamTurns {
 		return this.#options.store.agent(agent.name) ?? agent;
 	}
 
+	/**
+	 * What a turn in a room shows as it goes, through the room's surface; none in a Discord
+	 * channel, which shows only the final reply, or on a surface that shows no progress.
+	 */
+	#progress(channel: ChannelKey): ((event: TurnProgress) => void) | undefined {
+		const { surfaces, logger } = this.#options;
+		if (discordIdOf(channel) !== undefined || !surfaces?.progress)
+			return undefined;
+		return (event) => {
+			// pi-lens-ignore: no-unknown-parameters — a rejection reason is unknown; it only reaches the logger
+			surfaces
+				.progress?.(channel, event)
+				.catch((error: unknown) =>
+					logger.warn({ channel, err: error }, "progress not shown"),
+				);
+		};
+	}
+
 	/**
 	 * The turn's interim posts under the agent's name, read as each goes out so a name changed
 	 * during the turn shows; none in a channel no agent or group owns any more.
 	 */
 	#interim(channel: ChannelKey, agent: Agent): InterimPosts | undefined {
-		const { store, channels, studio } = this.#options;
-		if (!channels.interim) return undefined;
+		const { store, channels, studio, surfaces } = this.#options;
+		if (discordIdOf(channel) === undefined) {
+			// A room's interim posts are its surface's, under the agent as author.
+			if (!surfaces?.interim(channel, this.#author(agent))) return undefined;
+			return {
+				post: async (text) => {
+					if (!channelOwner(store, channel, this.#rooms(channel)))
+						throw new AgentError(`${channel} is archived`);
+					const posts = surfaces.interim(
+						channel,
+						this.#author(this.#current(agent)),
+					);
+					if (!posts) throw new AgentError(`${channel} shows no interim posts`);
+					return posts.post(text);
+				},
+			};
+		}
+		if (!channels?.interim) return undefined;
 		const interim = channels.interim.bind(channels);
 		return {
 			post: async (text) => {
@@ -297,23 +365,50 @@ export class TeamTurns {
 			chunks: string[];
 			files?: ReplyFile[];
 			threadId?: string;
+			failed?: true;
 		},
 	): Promise<void> {
-		const { store, channels, studio, logger } = this.#options;
-		if (!channelOwner(store, channel)) {
+		const { store, channels, studio, surfaces, logger } = this.#options;
+		if (!channelOwner(store, channel, this.#rooms(channel))) {
 			logger.info(
 				{ channel, agent: as.name },
 				"post to an archived channel dropped",
 			);
 			return;
 		}
+		// Discord ignores `failed`.
+		const { failed, ...rest } = body;
+		if (discordIdOf(channel) === undefined) {
+			if (!surfaces)
+				throw new AgentError(`no surface serves the room ${channel}`);
+			const { thinking, chunks, files, threadId } = rest;
+			// A thread of the room's surface is a channel of that surface, and speaks there.
+			return surfaces.sendReply(
+				threadId === undefined
+					? channel
+					: channelKey(parseChannelKey(channel).surface, threadId),
+				{
+					...(thinking ? { thinking } : {}),
+					chunks,
+					...(files?.length ? { files } : {}),
+					author: this.#author(as),
+					...(failed ? { failed } : {}),
+				},
+			);
+		}
+		if (!channels) throw new AgentError(`no Discord channels serve ${channel}`);
 		return channels.post(channelIdOf(channel), {
 			name: as.displayName,
 			avatarUrl: studio.url(as.avatarHash),
-			...body,
+			...rest,
 		});
 	}
 
+	/** Who speaks for the agent on a surface that shows authors. */
+	#author(agent: Agent): PostAuthor {
+		return { name: agent.displayName, agent: agent.name };
+	}
+
 	/**
 	 * Posts text under the caller's name in the channel of its turn: the group's in a group
 	 * round, otherwise its own, as a change report is.
@@ -330,18 +425,38 @@ export class TeamTurns {
 		const group = scope.group
 			? this.#options.store.group(scope.group)
 			: undefined;
-		return group ? discordKey(group.channelId) : scope.home;
+		if (!group) return scope.home;
+		// A seat of a room's group runs in that room; its running turn knows which.
+		return (
+			this.#posting.get(scope.session) ??
+			(group.channelId ? discordKey(group.channelId) : scope.home)
+		);
 	}
 
-	/** The assistant's own notice, such as a new release, posted in the coordinator's channel under its name. */
+	/**
+	 * The assistant's own notice, such as a new release, posted in the coordinator's channel under
+	 * its name: the entry channel, or, without Discord, its room on the first surface that hosts rooms.
+	 */
 	async announce(text: string): Promise<void> {
 		const { store, entryChannelId } = this.#options;
-		const coordinator = store.agentByChannel(entryChannelId);
+		const coordinator = coordinatorOf(store, this.#options);
 		if (!coordinator)
-			throw new AgentError("no active agent in the entry channel");
-		await this.#post(discordKey(entryChannelId), coordinator, {
-			chunks: splitReply(text),
-		});
+			throw new AgentError(
+				entryChannelId === undefined
+					? "no active coordinator"
+					: "no active agent in the entry channel",
+			);
+		const home =
+			entryChannelId !== undefined
+				? discordKey(entryChannelId)
+				: keysOf(
+						store,
+						coordinator.name,
+						this.#options.surfaces?.roomSurfaces() ?? [],
+					)[0];
+		if (!home)
+			throw new AgentError(`${coordinator.name} has no room to post in`);
+		await this.#post(home, coordinator, { chunks: splitReply(text) });
 	}
 
 	message(caller: AgentTurnScope, to: string, text: string): string {

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

@@ -1,10 +1,13 @@
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { constants, mkdirSync } from "node:fs";
+import { lstat, open, rm } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import type { AttachmentContent } from "../contract/channels.ts";
 import type {
 	AttachmentFailure,
 	AttachmentRef,
 	StoredAttachment,
 } from "../domain/attachment.ts";
+import { PluginError } from "../errors.ts";
 import { plainText } from "./attachment-name.ts";
 
 export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
@@ -23,6 +26,16 @@ export interface FetchRequest {
 	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;
+	/** The most bytes of one file; default `MAX_ATTACHMENT_BYTES`. Holds a ref, a file, a stream and a download alike. */
+	maxBytes?: number;
+	/**
+	 * Reads a ref through the surface that made it. A function that answers a promise is the ref's
+	 * only source: the ref is never fetched over the network, and a rejection fails that file.
+	 * The answer is the bytes, the path of a file to copy or a stream to store; the last two are
+	 * never held whole in memory. `undefined` = the surface has no reader, and the ref's URL is
+	 * downloaded.
+	 */
+	read?: (ref: AttachmentRef) => Promise<AttachmentContent> | undefined;
 }
 
 export interface FetchResult {
@@ -127,6 +140,113 @@ function untilAborted<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
 	});
 }
 
+/** The refusal for a file over the limit, such as `larger than 25 MB (26214401 bytes)`. */
+function tooLarge(limit: number, size: number): string {
+	return `larger than ${Number((limit / 1024 / 1024).toFixed(1))} MB (${size} bytes)`;
+}
+
+/**
+ * Writes a stream to `path` as it comes, never holding more than a chunk. Returns the bytes
+ * written, or the observed size once the stream passes `limit`, in which case nothing is left
+ * behind; a failure or an abort removes the partial file too.
+ */
+async function storeStream(
+	stream: ReadableStream<Uint8Array>,
+	path: string,
+	limit: number,
+	watch: IdleWatch,
+): Promise<number | { tooLarge: number }> {
+	const { signal } = watch;
+	const reader = stream.getReader();
+	// 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 });
+	let size = 0;
+	let handle: Awaited<ReturnType<typeof open>> | undefined;
+	let kept = false;
+	try {
+		if (signal.aborted) throw signal.reason ?? new Error("aborted");
+		handle = await open(path, "w");
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			watch.touch();
+			size += value.byteLength;
+			if (size > limit) {
+				await reader.cancel();
+				return { tooLarge: size };
+			}
+			await handle.write(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");
+		await handle.close();
+		handle = undefined;
+		kept = true;
+		return size;
+	} finally {
+		signal.removeEventListener("abort", stop);
+		reader.releaseLock();
+		await handle?.close().catch(() => {});
+		if (!kept) await rm(path, { force: true });
+	}
+}
+
+/** Stores what a surface handed over at `path`; the size, or the observed size once it is over `limit`. */
+async function storeContent(
+	content: AttachmentContent,
+	path: string,
+	limit: number,
+	watch: IdleWatch,
+): Promise<number | { tooLarge: number }> {
+	if (content instanceof Uint8Array) {
+		if (content.byteLength > limit) return { tooLarge: content.byteLength };
+		await Bun.write(path, content);
+		return content.byteLength;
+	}
+	if (content instanceof ReadableStream)
+		return storeStream(content, path, limit, watch);
+	return storeFile(content.path, path, limit, watch);
+}
+
+/** An error that carries a code, so the failure reports the code and never a message that may quote a path. */
+function codedError(code: string, message: string): Error {
+	return Object.assign(new Error(message), { code });
+}
+
+/** Copies a regular file the surface owns: absolute, not a symlink, opened once and read from that handle. */
+async function storeFile(
+	source: string,
+	path: string,
+	limit: number,
+	watch: IdleWatch,
+): Promise<number | { tooLarge: number }> {
+	if (!isAbsolute(source))
+		throw codedError("EINVAL", "attachment path is not absolute");
+	if ((await lstat(source)).isSymbolicLink())
+		throw codedError("EINVAL", "attachment path is a symlink");
+	// O_NOFOLLOW closes the gap between the check above and the open.
+	const handle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+	try {
+		const info = await handle.stat();
+		if (!info.isFile())
+			throw codedError("EINVAL", "attachment path is not a regular file");
+		if (info.size > limit) return { tooLarge: info.size };
+		// The count in `storeStream` also holds a file that grows while it is copied.
+		const stream = new ReadableStream<Uint8Array>({
+			async pull(controller) {
+				const chunk = new Uint8Array(64 * 1024);
+				const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+				if (bytesRead === 0) controller.close();
+				else controller.enqueue(chunk.subarray(0, bytesRead));
+			},
+		});
+		return await storeStream(stream, path, limit, watch);
+	} finally {
+		await handle.close().catch(() => {});
+	}
+}
+
 /** Downloads attachments one by one; a failed file is reported without stopping the others. */
 export async function fetchAttachments(
 	request: FetchRequest,
@@ -136,6 +256,11 @@ export async function fetchAttachments(
 	const failures: AttachmentFailure[] = [];
 	const { refs, dir, prefix, fromReference, signal } = request;
 	const idleMs = request.idleMs ?? DEFAULT_IDLE_MS;
+	const limit = request.maxBytes ?? MAX_ATTACHMENT_BYTES;
+	if (!Number.isSafeInteger(limit) || limit <= 0)
+		throw new PluginError(
+			`the attachment size limit (maxAttachmentBytes) must be a positive integer of bytes, not ${limit}`,
+		);
 	if (refs.length === 0) return { files, failures };
 
 	for (const [index, ref] of refs.entries()) {
@@ -145,40 +270,54 @@ export async function fetchAttachments(
 			fail("download failed: deadline passed or download aborted");
 			continue;
 		}
-		if (ref.size > MAX_ATTACHMENT_BYTES) {
-			fail(`larger than 25 MB (${ref.size} bytes)`);
+		if (ref.size > limit) {
+			fail(tooLarge(limit, ref.size));
 			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 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 file = `${prefix}-${index}-${safeFileName(ref.name)}`;
+			const path = join(dir, file);
+			let contentType = ref.contentType || "application/octet-stream";
+			let stored: number | { tooLarge: number };
+			const read = request.read?.(ref);
+			if (read) {
+				stored = await storeContent(
+					await untilAborted(read, watch.signal),
+					path,
+					limit,
+					watch,
+				);
+			} else {
+				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;
+				}
+				contentType =
+					ref.contentType ||
+					response.headers.get("content-type") ||
+					"application/octet-stream";
+				stored = response.body
+					? await storeStream(response.body, path, limit, watch)
+					: await Bun.write(path, new Uint8Array());
 			}
-			const data = await readAttachmentBody(response, watch);
-			if (typeof data === "number") {
-				fail(`larger than 25 MB (${data} bytes)`);
+			if (typeof stored === "object") {
+				fail(tooLarge(limit, stored.tooLarge));
 				continue;
 			}
-			const file = `${prefix}-${index}-${safeFileName(ref.name)}`;
-			const path = join(dir, file);
-			await Bun.write(path, data);
 			files.push({
 				name: ref.name,
 				file,
 				path,
-				contentType:
-					ref.contentType ||
-					response.headers.get("content-type") ||
-					"application/octet-stream",
-				size: data.byteLength,
+				contentType,
+				size: stored,
 				fromReference,
 			});
 		} catch (error) {
@@ -191,44 +330,3 @@ export async function fetchAttachments(
 	}
 	return { files, failures };
 }
-
-/** Returns the bytes, or the observed size once the stream exceeds the limit. */
-async function readAttachmentBody(
-	response: Response,
-	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 });
-	try {
-		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();
-				return size;
-			}
-			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");
-	} finally {
-		signal.removeEventListener("abort", stop);
-		reader.releaseLock();
-	}
-	const data = new Uint8Array(size);
-	let offset = 0;
-	for (const chunk of chunks) {
-		data.set(chunk, offset);
-		offset += chunk.byteLength;
-	}
-	return data;
-}

package/src/core/attachments/prompt-block.ts

@@ -1,4 +1,5 @@
 import type { TurnAttachments } from "../domain/attachment.ts";
+import { MAX_ATTACHMENT_BYTES } from "./attachment-fetcher.ts";
 import { plainContentType, plainText } from "./attachment-name.ts";
 
 /** A name a prompt can quote: no control or bidi characters, and no quote to close it early. */
@@ -22,8 +23,13 @@ export function withAttachmentsBlock(
 	const lines: string[] = [];
 	for (const file of attachments.files) {
 		const origin = file.fromReference ? ", from the replied-to message" : "";
+		// read_attachment reads no file over the size every surface takes; tools that take files can.
+		const large =
+			file.size > MAX_ATTACHMENT_BYTES
+				? ", too large for read_attachment; kept as a file for tools"
+				: "";
 		lines.push(
-			`- ${plainText(file.file)} (original name "${quotable(file.name)}", ${plainContentType(file.contentType)}, ${formatSize(file.size)}${origin})`,
+			`- ${plainText(file.file)} (original name "${quotable(file.name)}", ${plainContentType(file.contentType)}, ${formatSize(file.size)}${origin}${large})`,
 		);
 	}
 	for (const failure of attachments.failures) {

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

@@ -12,8 +12,10 @@ export interface ToolAttachment {
 	name: string;
 	contentType: string;
 	size: number;
-	/** The file's whole content. */
+	/** The file's whole content, in memory; for a large file prefer `stream()`. */
 	bytes(): Promise<Uint8Array>;
+	/** The file's content as a stream, for a file too large to hold in memory, such as a video. */
+	stream(): ReadableStream<Uint8Array>;
 }
 
 /** A file someone attached to the conversation, as a tool lists it. */
@@ -83,6 +85,23 @@ export async function openAttachment(
 				throw new AttachmentLookupError(`"${shown}" could not be read`);
 			}
 		},
+		stream: () => {
+			const source = handle.stream().getReader();
+			return new ReadableStream<Uint8Array>({
+				async pull(controller) {
+					try {
+						const next = await source.read();
+						if (next.done) controller.close();
+						else controller.enqueue(next.value);
+					} catch {
+						controller.error(
+							new AttachmentLookupError(`"${shown}" could not be read`),
+						);
+					}
+				},
+				cancel: (reason) => source.cancel(reason),
+			});
+		},
 	};
 }
 

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

@@ -1,4 +1,5 @@
-import type { TurnAttachments } from "../domain/attachment.ts";
+import type { AttachmentContent } from "../contract/channels.ts";
+import type { AttachmentRef, TurnAttachments } from "../domain/attachment.ts";
 import type { InboundMessage } from "../domain/conversation.ts";
 import type { Logger } from "../log.ts";
 import { fetchAttachments } from "./attachment-fetcher.ts";
@@ -29,6 +30,15 @@ export async function collectAttachments(
 		 * the files on to something that prepares them itself.
 		 */
 		prepareImages?: boolean;
+		/** The most bytes of one file; default 25 MiB (`MAX_ATTACHMENT_BYTES`). */
+		maxBytes?: number;
+		/**
+		 * Reads a ref through the surface that made it. A function that answers a promise is the
+		 * ref's only source: it is never fetched, and a rejection fails that file. The answer is the
+		 * bytes, `{ path }` of a file or a stream, the last two stored without holding them whole.
+		 * `undefined` = the surface has no reader, and the ref's URL is downloaded.
+		 */
+		read?: (ref: AttachmentRef) => Promise<AttachmentContent> | undefined;
 	},
 ): Promise<TurnAttachments> {
 	const { fetchImpl, logger } = options;
@@ -38,7 +48,11 @@ export async function collectAttachments(
 	const signal = options.signal
 		? AbortSignal.any([deadline, options.signal])
 		: deadline;
-	const idle = options.idleMs === undefined ? {} : { idleMs: options.idleMs };
+	const idle = {
+		...(options.idleMs === undefined ? {} : { idleMs: options.idleMs }),
+		...(options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes }),
+		...(options.read ? { read: options.read } : {}),
+	};
 	const own = await fetchAttachments(
 		{
 			refs: message.attachments,
@@ -97,6 +111,8 @@ export function attachmentsOf(
 		idleMs?: number;
 		signal?: AbortSignal;
 		prepareImages?: boolean;
+		maxBytes?: number;
+		read?: (ref: AttachmentRef) => Promise<AttachmentContent> | undefined;
 	} = {},
 ): Promise<TurnAttachments> {
 	return collectAttachments(message, dir, {