pi-roundtable 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -5,6 +5,32 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-10-10
+
+### Fixed
+
+- A long non-ASCII upload name no longer fails with `ENAMETOOLONG` on Linux: a stored file name is cut by UTF-8 bytes (150 at most, on a code point, keeping the end so the extension stays) instead of by UTF-16 units, so the file name and its `.json` record fit the 255 bytes a file system takes. A leading dot left by the cut is replaced too. The Discord download path shares the fix. `AttachmentPort.save` removes the data file when the record write fails, so a half-saved file no longer counts as waiting.
+- Calls on one principal's attachments run one after another, so two messages that name overlapping files no longer leave the refused one's other files moved into the conversation: `turnAttachments` moves the whole set or none, rolls back a partial move, and answers a file a sweep or a message took meanwhile with `AttachmentRefusal` (`unknown_file`) instead of a raw `ENOENT`.
+- The `## Attachments` block prints a name and a content type a prompt can trust: control characters, line and paragraph separators and bidi controls in a name become underscores and quotes become apostrophes, and a content type that is not a plain `type/subtype` prints as `application/octet-stream`.
+- `ToolTurn.attachment()` and `read_attachment` refuse a name with a NUL byte as "not an attachment name"; a NUL name no longer surfaces a runtime error that quoted the host's attachment directory, and a file that cannot be read reports its name, not its path.
+- `discardPending` removes the staging directories it emptied, so a conversation's uploads leave no empty directories behind.
+- `deleteConversation` of the Pi runtime removes the conversation's attachment directory, the files saved for it that no turn used, and its share of the used-bytes tally, so a deleted conversation keeps no files (a conversation deleted in the instant a message is taking its files can leave that message's share of the tally behind).
+
+### Added
+
+- `TurnAttachmentOptions` and `AttachmentPort.turnAttachments(channel, principalId, files, options?)`: `options.usedBytesLimit` caps the bytes one principal's turns keep across all their conversations. A call that would pass it moves nothing and is refused with the new `AttachmentRefusalCode` `quota_exceeded`; without it the core sets no limit. The core tallies the bytes per principal and conversation, and deleting a conversation gives its bytes back.
+
+### Documented
+
+- The guide says what the port checks (a private conversation's record) and what it does not: a channel with no record, or any channel on a host with no conversation registry, is admitted for every principal, so the plugin that owns a channel checks that the caller may use it before every call.
+
+## [0.9.2] - 2026-10-10
+
+### Added
+
+- `context.attachments` (`AttachmentPort`, with `AttachmentUpload`, `AttachmentRefusal` and `AttachmentRefusalCode`): a plugin keeps a file a person uploaded outside a turn until a turn uses it. `save` stages the file for its principal in a conversation, `turnAttachments` turns the named files into the turn's `TurnAttachments` (they move into the conversation's attachment directory, so `read_attachment` and the `## Attachments` block see them, and up to four images reach the model), `remove` and `discardPending` drop files no turn used, and `pendingBytes` counts what a principal has waiting. A staged file is usable only by the principal that saved it, in the conversation it was saved for; a conversation recorded private refuses every other principal (`AttachmentRefusal` with code `forbidden`). It needs the host's `dataDir`, a new `RoundtableOptions` field that `defineRoundtable` sets, and throws a `PluginError` without it.
+- `ToolTurn.attachment(file)` (`ToolAttachment`): a tool opens a file attached to the conversation, by the name in the turn's `## Attachments` block, and reads its bytes with `bytes()` or passes it on. A path or a hidden name is refused with a `ToolRefusal`. `SessionContext.attachmentDir` names the directory it reads.
+
 ## [0.9.1] - 2026-10-10
 
 ### Fixed

package/docs/plugins.md

@@ -135,6 +135,7 @@ A plugin that replaces `IDENTITY` replaces this too: the declarations are the bu
 | `apiKey(provider)` | The credential the host's model login holds for a provider such as `openai-codex`, the same login the agents use. It resolves to `undefined` when the host has none for that provider and never throws for that. The value is a secret: keep it out of logs and error messages. Read it when you use it rather than keeping it, since a login may refresh its token |
 | `queue` | The one channel queue that every conversation and channel operation shares |
 | `services` | The services plugins provide to each other, read by key: `services.get(SCHEDULES)`; see [services](#services-what-plugins-provide-to-each-other) |
+| `attachments` | Files a plugin takes from a person outside a turn, such as an upload, kept for a conversation until a turn uses them: [`attachments`](#contextattachments-files-from-outside-a-turn) |
 | `surfaces` | Every contributed [chat surface](#surfaces-a-chat-network-of-your-own), chosen by the prefix of a channel key: `of`, `sendReply`, `startTyping`, `showStop`, `react`, `unreact`, `prompts` |
 | `turns` | Runs one turn of a conversation your claim owns, over the runtime and the surfaces: [`turns.run`](#personas-and-contextturns-conversations-of-a-kind-of-your-own) |
 | `directChannels` | Every plugin's [direct channels](#directchannels-reaching-a-person-on-their-own): `providers()`, `reach(principalId)`, `known(principalId)`, and `notify(principalId, text)` |
@@ -528,11 +529,37 @@ A plugin that adds raw session tools names their tiers with `toolTiers`; the cor
 Each heading below is a key `setup` may return.
 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.
+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:
+
+| Call | What it does |
+|---|---|
+| `save(channel, principalId, { name, contentType, data })` | Keeps the file for that principal in that conversation and returns a `StoredAttachment`; its `file` is the name to hand back to the client. Refuses a file over 25 MiB (`too_large`) |
+| `turnAttachments(channel, principalId, files, options?)` | Takes the `file` names `save` returned and returns the turn's `TurnAttachments`; pass it as `attachments` to [`turns.run`](#personas-and-contextturns-conversations-of-a-kind-of-your-own). Each file moves into the conversation's attachment directory, up to four images are prepared for the model, and the turn's prompt lists every file under `## Attachments`. Refuses the whole set when one name is unknown or already used (`unknown_file`), or when `options.usedBytesLimit` would be passed (`quota_exceeded`); then none moves, even when other calls for the same principal run at once |
+| `remove(channel, principalId, file)` | Discards a saved file no turn used; `false` when there is none |
+| `discardPending(olderThan)` | Discards every saved file no turn used that was saved before the date, and returns how many; call it from a service's timer so abandoned uploads do not pile up |
+| `pendingBytes(principalId)` | The bytes the principal has saved that no turn used yet, for a quota of your own |
+
+A saved file waits for its owner: only the principal that saved it can use it, and only in the conversation it was saved for.
+The conversation's record decides who may save into it: a private conversation refuses every principal but its own with an `AttachmentRefusal` whose `code` is `forbidden`, and a shared one lets each principal save and use their own files.
+**The plugin that owns a channel checks that the caller may use it, before every call.** The port knows only the conversation's record: a channel with no record yet, such as a conversation opened but not written in, is admitted for every principal, and so is every channel on a host with no conversation registry. A plugin that takes the channel key from a person (a URL, a frame) and passes it on unchecked lets that person stage files into, and move files into the attachment directory of, a conversation that is not theirs. Check first that the channel is the person's, as the web chat does before it saves or uses a file.
+`usedBytesLimit` caps what one principal's turns keep, across all their conversations; the core sets no limit of its own, and a deleted conversation gives its bytes back.
+Deleting a conversation (`runtime.deleteConversation`) also removes its attachment directory, the files saved for it that no turn used, and its share of the tally.
+The calls reject with `AttachmentRefusal`, and throw a `PluginError` when the host has no `dataDir` (a host built by `defineRoundtable` always has one).
+The core limits only the size; the types a plugin accepts, the number of files, and the rate are its own to limit.
+
+Once a turn has used a file, the model reads it with `read_attachment`, and a tool reads it with `turn.attachment(file)` (see [`tools`](#tools-what-agents-can-call)).
+
 ### `tools`: what agents can call
 
 `defineTool` takes a name (lowercase words joined by underscores), a description the model reads to decide when to call it, a Typebox parameter schema, the lowest tier that may call it, and the function.
-`run` receives the arguments, already typed, and the turn: the speaker, the channel, the agent, an abort signal, and `attachFile`.
+`run` receives the arguments, already typed, and the turn: the speaker, the channel, the agent, an abort signal, `attachFile`, and `attachment`.
 It returns the text the model reads.
+`turn.attachment(file)` opens a file someone attached to the conversation, by the name the turn's `## Attachments` block lists, and returns `{ file, name, contentType, size, bytes() }`: a tool passes a user's file on without the model carrying its bytes.
+Only the conversation's own files open; a path, a hidden name, or a missing file throws a `ToolRefusal` the model reads.
 Throw `ToolRefusal` for a call the model should correct; any other error fails the call.
 
 <!-- example: examples/tools.ts -->
@@ -2709,12 +2736,14 @@ The package README documents every frame, error code, close code, and limit.
 The verifier is generic; what makes it safe is how it is pointed at your provider.
 The README's [provider settings][webchat-provider-settings] explain, with Microsoft Entra ID as the example, why to name people by a claim that stays the same across app registrations (`subjectClaim`), pin the tenant in `check`, accept access tokens only, refuse app-only tokens, merge issuers of one tenant only (`speakerIssuer`), and mind the guests `everyone` admits.
 
-The web chat takes no attachments or system error reports (`takesSystemReports: false`), so `ops.conversation` cannot name it.
+The web chat takes files people upload to their conversation and then name in a message (see the README's [attachments][webchat-attachments]), built on [`context.attachments`](#contextattachments-files-from-outside-a-turn).
+It takes no system error reports (`takesSystemReports: false`), so `ops.conversation` cannot name it.
 It accepts `PERSONAL_TARGET` background turns only for the private conversation's principal; include `schedule_*`, `delegate_task`, and `notify` in a persona's selection only deliberately, adjusting their tiers if needed.
 Leave out `web_search` and `fetch_content` unless people may make the host fetch any address, internal ones included.
 
 [webchat-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/webchat/README.md
 [webchat-provider-settings]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/webchat/README.md#provider-settings
+[webchat-attachments]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/webchat/README.md#attachments
 
 ### What plugins do not extend
 
@@ -3219,7 +3248,11 @@ Import from the entries listed below; source area files are internal.
 | `Approval` | `pi-roundtable` | type |
 | `AskOption` | `pi-roundtable` | type |
 | `AttachmentFailure` | `pi-roundtable` | type |
+| `AttachmentPort` | `pi-roundtable` | type |
 | `AttachmentRef` | `pi-roundtable` | type |
+| `AttachmentRefusal` | `pi-roundtable` | value |
+| `AttachmentRefusalCode` | `pi-roundtable` | type |
+| `AttachmentUpload` | `pi-roundtable` | type |
 | `AvatarMode` | `pi-roundtable` | type |
 | `AvatarStudio` | `pi-roundtable` | type |
 | `BACKGROUND_TURNS` | `pi-roundtable` | value |
@@ -3388,6 +3421,7 @@ Import from the entries listed below; source area files are internal.
 | `ThinkingSetting` | `pi-roundtable` | type |
 | `Tier` | `pi-roundtable` | type |
 | `TierConfig` | `pi-roundtable` | type |
+| `ToolAttachment` | `pi-roundtable` | type |
 | `ToolContribution` | `pi-roundtable` | type |
 | `ToolRefusal` | `pi-roundtable` | value |
 | `ToolSelection` | `pi-roundtable` | type |
@@ -3397,6 +3431,7 @@ Import from the entries listed below; source area files are internal.
 | `ToolTurn` | `pi-roundtable` | type |
 | `TranscriptEntry` | `pi-roundtable` | type |
 | `TransientTask` | `pi-roundtable` | type |
+| `TurnAttachmentOptions` | `pi-roundtable` | type |
 | `TurnAttachments` | `pi-roundtable` | type |
 | `TurnConversation` | `pi-roundtable` | type |
 | `TurnEndEvent` | `pi-roundtable` | type |

package/package.json

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

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

@@ -1,6 +1,12 @@
+import { readdir, rm, rmdir } from "node:fs/promises";
 import { join } from "node:path";
 import type { ChannelKey } from "../domain/conversation.ts";
 
+/** Where saved files wait for a turn, beside the conversations' attachment directories. */
+export const STAGING = "attachments-pending";
+/** Where each principal's tally of used bytes per conversation is kept. */
+export const USAGE = "attachments-used";
+
 /** A channel key as a single path segment. */
 export function channelSegment(channel: ChannelKey): string {
 	return channel.replace(/[^A-Za-z0-9_-]/g, "_");
@@ -13,3 +19,48 @@ export function ownerAttachmentDir(
 ): string {
 	return join(dataDir, "attachments", channelSegment(channel));
 }
+
+/** The entries of `dir`; none when it is not there. */
+export async function listDir(dir: string): Promise<string[]> {
+	try {
+		return await readdir(dir);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+/** Removes `dir` when it is empty; a directory that has entries, or is gone, stays as it is. */
+export async function removeIfEmpty(dir: string): Promise<void> {
+	try {
+		await rmdir(dir);
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code !== "ENOTEMPTY" && code !== "EEXIST" && code !== "ENOENT")
+			throw error;
+	}
+}
+
+/**
+ * Removes everything the core keeps for a deleted conversation: the files its turns used, the
+ * files people saved for it and no turn used, and the tally of what each principal used in it.
+ */
+export async function discardConversationFiles(
+	dataDir: string,
+	channel: ChannelKey,
+): Promise<void> {
+	const segment = channelSegment(channel);
+	await rm(ownerAttachmentDir(dataDir, channel), {
+		recursive: true,
+		force: true,
+	});
+	for (const area of [STAGING, USAGE]) {
+		const root = join(dataDir, area);
+		for (const principal of await listDir(root)) {
+			const dir = join(root, principal);
+			await rm(join(dir, segment), { recursive: true, force: true });
+			await rm(join(dir, `${segment}.tmp`), { force: true });
+			await removeIfEmpty(dir);
+		}
+	}
+}

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

@@ -5,6 +5,7 @@ import type {
 	AttachmentRef,
 	StoredAttachment,
 } from "../domain/attachment.ts";
+import { plainText } from "./attachment-name.ts";
 
 export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
 
@@ -22,13 +23,36 @@ export interface FetchResult {
 	failures: AttachmentFailure[];
 }
 
-/** Keeps a file name readable while removing path separators and control characters. */
+/** The most UTF-8 bytes a stored name keeps; a file system takes 255 bytes for the whole file name. */
+const MAX_NAME_BYTES = 150;
+
+const utf8Length = (codePoint: number): number =>
+	codePoint < 0x80 ? 1 : codePoint < 0x800 ? 2 : codePoint < 0x10000 ? 3 : 4;
+
+/** The end of `text` that fits `max` UTF-8 bytes, cut on a code point. */
+function lastBytes(text: string, max: number): string {
+	const points = [...text];
+	let bytes = 0;
+	let start = points.length;
+	while (start > 0) {
+		const size = utf8Length(points[start - 1]?.codePointAt(0) ?? 0);
+		if (bytes + size > max) break;
+		bytes += size;
+		start -= 1;
+	}
+	return points.slice(start).join("");
+}
+
+/**
+ * Keeps a file name readable while removing path separators and control characters, and keeps the
+ * end of a long name (its extension) within 150 UTF-8 bytes so a prefix and a record suffix still
+ * fit the 255 bytes a file system takes.
+ */
 export function safeFileName(name: string): string {
-	const cleaned = name
-		.normalize("NFC")
-		.replace(/[/\\\p{Cc}]/gu, "_")
-		.replace(/^\.+/, "_")
-		.slice(-120);
+	const cleaned = lastBytes(
+		plainText(name.toWellFormed().normalize("NFC").replace(/[/\\]/g, "_")),
+		MAX_NAME_BYTES,
+	).replace(/^\.+/, "_");
 	return cleaned || "file";
 }
 

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

@@ -0,0 +1,34 @@
+import { basename } from "node:path";
+
+/**
+ * Characters that must not reach a prompt or a file name as they are: controls, the line and
+ * paragraph separators, and the bidi controls that reorder or hide the text around them.
+ */
+const UNSAFE_CHARS =
+	/[\p{Cc}\p{Zl}\p{Zp}\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu;
+
+/** `value` with each unsafe character replaced by an underscore. */
+export function plainText(value: string): string {
+	return value.replace(UNSAFE_CHARS, "_");
+}
+
+/** Whether `file` could be a name the attachment stores give out: one path segment, not hidden, no NUL. */
+export function isAttachmentName(file: string): boolean {
+	return (
+		file !== "" &&
+		basename(file) === file &&
+		!file.startsWith(".") &&
+		!file.includes("\0")
+	);
+}
+
+const TYPE_GRAMMAR = /^[a-z0-9.+-]+\/[a-z0-9.+-]+$/i;
+
+/**
+ * The type a prompt may print: `type` without its parameters (`text/plain; charset=utf-8` is
+ * `text/plain`) when that is a plain type/subtype, else the generic binary type.
+ */
+export function plainContentType(type: string): string {
+	const base = type.split(";")[0]?.trim().toLowerCase() ?? "";
+	return TYPE_GRAMMAR.test(base) ? base : "application/octet-stream";
+}

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

@@ -0,0 +1,34 @@
+import type { AttachmentPort } from "../contract/attachments.ts";
+import { PluginError } from "../errors.ts";
+import type { Logger } from "../log.ts";
+import {
+	AttachmentStore,
+	type AttachmentStoreOptions,
+} from "./attachment-store.ts";
+
+/**
+ * The attachment port a plugin gets as `context.attachments`: over the host's `dataDir`, or, when
+ * the host has none, a port whose every call throws a PluginError naming the option to set.
+ */
+export function attachmentPort(options: {
+	dataDir: string | undefined;
+	registry: AttachmentStoreOptions["registry"];
+	logger: Logger;
+}): AttachmentPort {
+	const { dataDir, registry, logger } = options;
+	if (dataDir === undefined) {
+		const refuse = (): never => {
+			throw new PluginError(
+				"no dataDir is configured, so attachments cannot be kept. Set dataDir in the configuration, or the dataDir option of the host.",
+			);
+		};
+		return {
+			save: refuse,
+			turnAttachments: refuse,
+			remove: refuse,
+			discardPending: refuse,
+			pendingBytes: refuse,
+		};
+	}
+	return new AttachmentStore({ dataDir, registry, logger });
+}

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

@@ -0,0 +1,363 @@
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+	type AttachmentPort,
+	AttachmentRefusal,
+	type AttachmentUpload,
+	type TurnAttachmentOptions,
+} from "../contract/attachments.ts";
+import type { ConversationRegistry } from "../conversations/conversation-registry.ts";
+import type {
+	StoredAttachment,
+	TurnAttachments,
+} from "../domain/attachment.ts";
+import type { Logger } from "../log.ts";
+import type { ChannelKey } from "../sessions.ts";
+import {
+	channelSegment,
+	listDir,
+	ownerAttachmentDir,
+	removeIfEmpty,
+	STAGING,
+	USAGE,
+} from "./attachment-dir.ts";
+import { MAX_ATTACHMENT_BYTES, safeFileName } from "./attachment-fetcher.ts";
+import { isAttachmentName } from "./attachment-name.ts";
+import { modelImagesOf } from "./model-images.ts";
+
+/** The record of a saved file, in a directory next to it that no file name can be. */
+export const RECORDS = ".records";
+
+export interface AttachmentStoreOptions {
+	dataDir: string;
+	/** Read when used, once the host linked its services; undefined when no registry records conversations. */
+	registry(): Pick<ConversationRegistry, "get"> | undefined;
+	logger: Logger;
+}
+
+interface StagedRecord {
+	name: string;
+	contentType: string;
+}
+
+const isRecord = (value: unknown): value is StagedRecord =>
+	typeof value === "object" &&
+	value !== null &&
+	typeof (value as StagedRecord).name === "string" &&
+	typeof (value as StagedRecord).contentType === "string";
+
+/** A principal id as one path segment; hashed, so two ids never share a directory. */
+function principalSegment(principalId: string): string {
+	return createHash("sha256").update(principalId).digest("hex").slice(0, 32);
+}
+
+/** The bytes of a tally file; none when it is missing or unreadable as a number. */
+async function readTally(path: string): Promise<number> {
+	try {
+		const value = Number(await readFile(path, "utf8"));
+		return Number.isFinite(value) && value > 0 ? value : 0;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0;
+		throw error;
+	}
+}
+
+/** Writes a tally whole or not at all, creating its directory if a conversation's deletion removed it meanwhile. */
+async function writeTally(path: string, bytes: number): Promise<void> {
+	const temporary = `${path}.tmp`;
+	try {
+		await writeFile(temporary, String(bytes));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+		await writeFile(temporary, String(bytes));
+	}
+	await rename(temporary, path);
+}
+
+/**
+ * The files plugins take from people outside a turn. A saved file is staged under its principal and
+ * its conversation until a turn uses it, then moved into the conversation's attachment directory,
+ * the one `read_attachment` reads. The conversation's record decides who may stage: a private
+ * conversation takes only its principal's files.
+ *
+ * Calls that change one principal's files run one after another, so two messages of one person
+ * never see each other half done; the tally of the bytes a principal used per conversation lives
+ * beside the staging directories.
+ */
+export class AttachmentStore implements AttachmentPort {
+	readonly #options: AttachmentStoreOptions;
+	/** The last call queued for each principal, which the next one waits for. */
+	readonly #tails = new Map<string, Promise<void>>();
+
+	constructor(options: AttachmentStoreOptions) {
+		this.#options = options;
+	}
+
+	/** Runs `run` after the principal's earlier calls, whether they succeeded or not. */
+	#exclusive<T>(principal: string, run: () => Promise<T>): Promise<T> {
+		const result = (this.#tails.get(principal) ?? Promise.resolve()).then(run);
+		const tail = result.then(
+			() => undefined,
+			() => undefined,
+		);
+		this.#tails.set(principal, tail);
+		void tail.then(() => {
+			if (this.#tails.get(principal) === tail) this.#tails.delete(principal);
+		});
+		return result;
+	}
+
+	#stagingDir(channel: ChannelKey, principalId: string): string {
+		return join(
+			this.#options.dataDir,
+			STAGING,
+			principalSegment(principalId),
+			channelSegment(channel),
+		);
+	}
+
+	#tallyDir(principalId: string): string {
+		return join(this.#options.dataDir, USAGE, principalSegment(principalId));
+	}
+
+	/** Refuses a principal other than the one a private conversation belongs to. */
+	async #admit(channel: ChannelKey, principalId: string): Promise<void> {
+		const record = await this.#options.registry()?.get(channel);
+		if (record?.visibility === "private" && record.principalId !== principalId)
+			throw new AttachmentRefusal(
+				"forbidden",
+				`${channel} is private to someone else, so its files cannot be saved or used by ${principalId}`,
+			);
+	}
+
+	async save(
+		channel: ChannelKey,
+		principalId: string,
+		upload: AttachmentUpload,
+	): Promise<StoredAttachment> {
+		await this.#admit(channel, principalId);
+		const size = upload.data.byteLength;
+		if (size > MAX_ATTACHMENT_BYTES)
+			throw new AttachmentRefusal(
+				"too_large",
+				`a file may be at most 25 MiB; "${upload.name}" is ${size} bytes`,
+			);
+		const dir = this.#stagingDir(channel, principalId);
+		const file = `${crypto.randomUUID()}-${safeFileName(upload.name)}`;
+		const path = join(dir, file);
+		const recordPath = join(dir, RECORDS, `${file}.json`);
+		const record: StagedRecord = {
+			name: upload.name,
+			contentType: upload.contentType,
+		};
+		await this.#exclusive(principalSegment(principalId), async () => {
+			mkdirSync(join(dir, RECORDS), { recursive: true, mode: 0o700 });
+			try {
+				await Bun.write(path, upload.data);
+				await Bun.write(recordPath, JSON.stringify(record));
+			} catch (error) {
+				// A file without its record could never be used or removed, yet would count as waiting.
+				await rm(path, { force: true });
+				await rm(recordPath, { force: true });
+				throw error;
+			}
+		});
+		return {
+			name: upload.name,
+			file,
+			path,
+			contentType: upload.contentType,
+			size,
+			fromReference: false,
+		};
+	}
+
+	async turnAttachments(
+		channel: ChannelKey,
+		principalId: string,
+		files: readonly string[],
+		options: TurnAttachmentOptions = {},
+	): Promise<TurnAttachments> {
+		await this.#admit(channel, principalId);
+		const found = await this.#exclusive(principalSegment(principalId), () =>
+			this.#claim(channel, principalId, files, options),
+		);
+		const { images, failures } = await modelImagesOf(
+			found,
+			this.#options.logger,
+		);
+		return { files: found, images, failures };
+	}
+
+	/** Checks every file, then moves them all into the conversation, or none when any step fails. */
+	async #claim(
+		channel: ChannelKey,
+		principalId: string,
+		files: readonly string[],
+		options: TurnAttachmentOptions,
+	): Promise<StoredAttachment[]> {
+		const staging = this.#stagingDir(channel, principalId);
+		const target = ownerAttachmentDir(this.#options.dataDir, channel);
+		const found: StoredAttachment[] = [];
+		for (const file of new Set(files)) {
+			const record = await this.#recordOf(staging, file);
+			if (!record)
+				throw new AttachmentRefusal(
+					"unknown_file",
+					`no saved file "${file}" is waiting for this person in ${channel}`,
+				);
+			found.push({
+				name: record.name,
+				file,
+				path: join(target, file),
+				contentType: record.contentType,
+				size: (await stat(join(staging, file))).size,
+				fromReference: false,
+			});
+		}
+		const added = found.reduce((sum, stored) => sum + stored.size, 0);
+		const tally = join(this.#tallyDir(principalId), channelSegment(channel));
+		const before = await readTally(tally);
+		if (options.usedBytesLimit !== undefined) {
+			const used = await this.#usedBytes(principalId);
+			if (used + added > options.usedBytesLimit)
+				throw new AttachmentRefusal(
+					"quota_exceeded",
+					`the files already used in turns hold ${used} bytes, and ${added} more would pass the limit of ${options.usedBytesLimit} bytes`,
+				);
+		}
+		mkdirSync(join(target, RECORDS), { recursive: true, mode: 0o700 });
+		mkdirSync(this.#tallyDir(principalId), { recursive: true, mode: 0o700 });
+		const moved: StoredAttachment[] = [];
+		try {
+			for (const stored of found) {
+				await rename(join(staging, stored.file), stored.path);
+				moved.push(stored);
+				await rename(
+					join(staging, RECORDS, `${stored.file}.json`),
+					join(target, RECORDS, `${stored.file}.json`),
+				);
+			}
+			await writeTally(tally, before + added);
+		} catch (error) {
+			await this.#putBack(moved, staging, target, tally, before);
+			// Something else took the file between the check and the move.
+			if ((error as NodeJS.ErrnoException).code === "ENOENT")
+				throw new AttachmentRefusal(
+					"unknown_file",
+					"a saved file was used or discarded while the message was taken",
+				);
+			throw error;
+		}
+		return found;
+	}
+
+	/** Undoes a partial move: the files return to staging and the tally to what it was. */
+	async #putBack(
+		moved: readonly StoredAttachment[],
+		staging: string,
+		target: string,
+		tally: string,
+		before: number,
+	): Promise<void> {
+		for (const stored of moved) {
+			await rename(stored.path, join(staging, stored.file)).catch(
+				() => undefined,
+			);
+			await rename(
+				join(target, RECORDS, `${stored.file}.json`),
+				join(staging, RECORDS, `${stored.file}.json`),
+			).catch(() => undefined);
+		}
+		await writeTally(tally, before).catch(() => undefined);
+	}
+
+	async remove(
+		channel: ChannelKey,
+		principalId: string,
+		file: string,
+	): Promise<boolean> {
+		await this.#admit(channel, principalId);
+		const staging = this.#stagingDir(channel, principalId);
+		return this.#exclusive(principalSegment(principalId), async () => {
+			if (!(await this.#recordOf(staging, file))) return false;
+			await rm(join(staging, file), { force: true });
+			await rm(join(staging, RECORDS, `${file}.json`), { force: true });
+			return true;
+		});
+	}
+
+	async discardPending(olderThan: Date): Promise<number> {
+		const root = join(this.#options.dataDir, STAGING);
+		let discarded = 0;
+		for (const principal of await listDir(root)) {
+			discarded += await this.#exclusive(principal, async () => {
+				let count = 0;
+				for (const channel of await listDir(join(root, principal))) {
+					const dir = join(root, principal, channel);
+					for (const entry of await listDir(dir)) {
+						if (entry === RECORDS) continue;
+						const info = await stat(join(dir, entry)).catch(() => undefined);
+						if (!info || info.mtimeMs >= olderThan.getTime()) continue;
+						await rm(join(dir, entry), { force: true });
+						await rm(join(dir, RECORDS, `${entry}.json`), { force: true });
+						count += 1;
+					}
+					// A conversation with nothing waiting keeps no directory.
+					await removeIfEmpty(join(dir, RECORDS));
+					await removeIfEmpty(dir);
+				}
+				await removeIfEmpty(join(root, principal));
+				return count;
+			});
+		}
+		return discarded;
+	}
+
+	async pendingBytes(principalId: string): Promise<number> {
+		const root = join(
+			this.#options.dataDir,
+			STAGING,
+			principalSegment(principalId),
+		);
+		let total = 0;
+		for (const channel of await listDir(root)) {
+			const dir = join(root, channel);
+			for (const entry of await listDir(dir)) {
+				if (entry === RECORDS) continue;
+				total +=
+					(await stat(join(dir, entry)).catch(() => undefined))?.size ?? 0;
+			}
+		}
+		return total;
+	}
+
+	/** The bytes the principal's turns used, across their conversations. */
+	async #usedBytes(principalId: string): Promise<number> {
+		const dir = this.#tallyDir(principalId);
+		let total = 0;
+		for (const channel of await listDir(dir))
+			if (!channel.endsWith(".tmp"))
+				total += await readTally(join(dir, channel));
+		return total;
+	}
+
+	/** The record of a staged file, or undefined when it is not staged here. */
+	async #recordOf(
+		staging: string,
+		file: string,
+	): Promise<StagedRecord | undefined> {
+		if (!isAttachmentName(file)) return undefined;
+		const stored = Bun.file(join(staging, RECORDS, `${file}.json`));
+		if (
+			!(await stored.exists()) ||
+			!(await Bun.file(join(staging, file)).exists())
+		)
+			return undefined;
+		const value: unknown = await stored.json();
+		return isRecord(value) ? value : undefined;
+	}
+}

package/src/core/attachments/model-images.ts

@@ -0,0 +1,39 @@
+import type {
+	AttachmentFailure,
+	ModelImage,
+	StoredAttachment,
+} from "../domain/attachment.ts";
+import type { Logger } from "../log.ts";
+import {
+	isModelImage,
+	MAX_IMAGES_PER_TURN,
+	prepareImage,
+} from "./image-prep.ts";
+
+/**
+ * The first four images among the files, prepared as the model accepts them. An image that cannot
+ * be decoded is reported as a failure and the turn goes on without it.
+ */
+export async function modelImagesOf(
+	files: readonly StoredAttachment[],
+	logger: Logger,
+): Promise<{ images: ModelImage[]; failures: AttachmentFailure[] }> {
+	const images: ModelImage[] = [];
+	const failures: AttachmentFailure[] = [];
+	for (const file of files.filter(isModelImage).slice(0, MAX_IMAGES_PER_TURN)) {
+		try {
+			images.push(await prepareImage(file));
+		} catch (error) {
+			logger.warn(
+				{ file: file.file, err: error },
+				"image could not be prepared",
+			);
+			failures.push({
+				name: file.name,
+				reason: "the image could not be decoded",
+				fromReference: file.fromReference,
+			});
+		}
+	}
+	return { images, failures };
+}

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

@@ -1,4 +1,8 @@
 import type { TurnAttachments } from "../domain/attachment.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. */
+const quotable = (name: string): string => plainText(name).replaceAll('"', "'");
 
 function formatSize(bytes: number): string {
 	if (bytes < 1024) return `${bytes} B`;
@@ -19,13 +23,13 @@ export function withAttachmentsBlock(
 	for (const file of attachments.files) {
 		const origin = file.fromReference ? ", from the replied-to message" : "";
 		lines.push(
-			`- ${file.file} (original name "${file.name}", ${file.contentType}, ${formatSize(file.size)}${origin})`,
+			`- ${plainText(file.file)} (original name "${quotable(file.name)}", ${plainContentType(file.contentType)}, ${formatSize(file.size)}${origin})`,
 		);
 	}
 	for (const failure of attachments.failures) {
 		const origin = failure.fromReference ? " from the replied-to message" : "";
 		lines.push(
-			`- "${failure.name}"${origin} could not be received: ${failure.reason}`,
+			`- "${quotable(failure.name)}"${origin} could not be received: ${failure.reason}`,
 		);
 	}
 	if (lines.length === 0) return text;

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

@@ -0,0 +1,62 @@
+import { join } from "node:path";
+import { isAttachmentName, plainText } from "./attachment-name.ts";
+import { RECORDS } from "./attachment-store.ts";
+
+/** A file someone attached to the conversation, as a tool reads it. */
+export interface ToolAttachment {
+	/** The file name inside the conversation's attachment store; what `## Attachments` lists. */
+	file: string;
+	/** The name the person gave it, when the core recorded one; else the file name. */
+	name: string;
+	contentType: string;
+	size: number;
+	/** The file's whole content. */
+	bytes(): Promise<Uint8Array>;
+}
+
+/** A name that is no attachment of the conversation, or a file that is not there. */
+export class AttachmentLookupError extends Error {
+	override name = "AttachmentLookupError";
+}
+
+interface Recorded {
+	name?: unknown;
+	contentType?: unknown;
+}
+
+/**
+ * Opens one attachment of a conversation's store for a tool. `file` must be a name in `dir`, as
+ * `read_attachment` takes it: a path or a hidden name is refused.
+ */
+export async function openAttachment(
+	dir: string,
+	file: string,
+): Promise<ToolAttachment> {
+	const shown = plainText(file);
+	if (!isAttachmentName(file))
+		throw new AttachmentLookupError(`"${shown}" is not an attachment name`);
+	const handle = Bun.file(join(dir, file));
+	if (!(await handle.exists()))
+		throw new AttachmentLookupError(
+			`no attachment named "${shown}" in this channel`,
+		);
+	const record = Bun.file(join(dir, RECORDS, `${file}.json`));
+	const recorded: Recorded = (await record.exists()) ? await record.json() : {};
+	return {
+		file,
+		name: typeof recorded.name === "string" ? recorded.name : file,
+		contentType:
+			typeof recorded.contentType === "string"
+				? recorded.contentType
+				: handle.type,
+		size: handle.size,
+		// A file system error names the path on the host; the model sees only the attachment's name.
+		bytes: async () => {
+			try {
+				return new Uint8Array(await handle.arrayBuffer());
+			} catch {
+				throw new AttachmentLookupError(`"${shown}" could not be read`);
+			}
+		},
+	};
+}

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

@@ -2,11 +2,7 @@ import type { TurnAttachments } from "../domain/attachment.ts";
 import type { InboundMessage } from "../domain/conversation.ts";
 import type { Logger } from "../log.ts";
 import { fetchAttachments } from "./attachment-fetcher.ts";
-import {
-	isModelImage,
-	MAX_IMAGES_PER_TURN,
-	prepareImage,
-} from "./image-prep.ts";
+import { modelImagesOf } from "./model-images.ts";
 
 /** Saves the message's and its reference's files, and turns up to four images into model images. */
 export async function collectAttachments(
@@ -35,22 +31,9 @@ export async function collectAttachments(
 	);
 	const files = [...own.files, ...referenced.files];
 	const failures = [...own.failures, ...referenced.failures];
-	const images = [];
-	for (const file of files.filter(isModelImage).slice(0, MAX_IMAGES_PER_TURN)) {
-		try {
-			images.push(await prepareImage(file));
-		} catch (error) {
-			logger.warn(
-				{ file: file.file, err: error },
-				"image could not be prepared",
-			);
-			failures.push({
-				name: file.name,
-				reason: "the image could not be decoded",
-				fromReference: file.fromReference,
-			});
-		}
-	}
+	const prepared = await modelImagesOf(files, logger);
+	const images = prepared.images;
+	failures.push(...prepared.failures);
 	if (files.length > 0 || failures.length > 0) {
 		logger.info(
 			{

package/src/core/contract/attachments.ts

@@ -0,0 +1,92 @@
+import type {
+	StoredAttachment,
+	TurnAttachments,
+} from "../domain/attachment.ts";
+import type { ChannelKey } from "../sessions.ts";
+
+/** A file a plugin hands the core to keep for a conversation. */
+export interface AttachmentUpload {
+	/** The name the person gave it; shown to the model and kept as is. */
+	name: string;
+	contentType: string;
+	data: Uint8Array;
+}
+
+/** Why the attachment store refused a call. */
+export type AttachmentRefusalCode =
+	/** The conversation is private to someone else. */
+	| "forbidden"
+	/** No saved file of that name is waiting for this person in this conversation. */
+	| "unknown_file"
+	/** The file is over the core's limit of 25 MiB. */
+	| "too_large"
+	/** Using the files would take the principal past the `usedBytesLimit` the plugin passed. */
+	| "quota_exceeded";
+
+/** An attachment call the store refused; `code` says why, and the plugin decides what its client sees. */
+export class AttachmentRefusal extends Error {
+	override name = "AttachmentRefusal";
+	readonly code: AttachmentRefusalCode;
+
+	constructor(code: AttachmentRefusalCode, message: string) {
+		super(message);
+		this.code = code;
+	}
+}
+
+/** What a plugin asks of `turnAttachments` besides the files. */
+export interface TurnAttachmentOptions {
+	/**
+	 * The most bytes the principal may have used in turns across all their conversations, these
+	 * files included. A call that would pass it is refused with `quota_exceeded` and moves nothing.
+	 * Without it the core sets no limit; deleting a conversation gives its bytes back.
+	 */
+	usedBytesLimit?: number;
+}
+
+/**
+ * Files a plugin takes from a person outside a turn, such as an upload over HTTP, kept for the
+ * conversation until a turn uses them. A saved file waits for its person: only the principal that
+ * saved it may use it, in the conversation it was saved for. A private conversation refuses every
+ * other principal; a shared one lets each use their own. Using a file moves it into the
+ * conversation's attachment directory, where the turn's `read_attachment` and
+ * `ToolTurn.attachment()` find it. Calls reject with `AttachmentRefusal` for a refused call, and
+ * throw a PluginError when the host has no `dataDir`.
+ *
+ * Who may use a channel is the plugin's to check, not the port's. The port refuses another
+ * principal only in a conversation the host's registry records as private to someone else; for a
+ * channel the registry does not know, or when the host has no registry, it admits every principal.
+ * A plugin whose channel key comes from a person must first check that the channel is that
+ * person's, as the web chat does before every call; the plugin that owns a channel checks it,
+ * because only that plugin knows what the channel is.
+ */
+export interface AttachmentPort {
+	/** Keeps a file for the principal in the conversation until a turn uses it. */
+	save(
+		channel: ChannelKey,
+		principalId: string,
+		upload: AttachmentUpload,
+	): Promise<StoredAttachment>;
+	/**
+	 * The turn's attachments for files `save` returned: each moves into the conversation, up to four
+	 * images are prepared for the model, and every file is named in the turn's `## Attachments`
+	 * block. Refuses the whole set when one file is unknown or already used, or when
+	 * `options.usedBytesLimit` would be passed; none moves then, however many calls run at once.
+	 */
+	turnAttachments(
+		channel: ChannelKey,
+		principalId: string,
+		files: readonly string[],
+		options?: TurnAttachmentOptions,
+	): Promise<TurnAttachments>;
+	/** Discards a saved file no turn used; false when there is none. */
+	remove(
+		channel: ChannelKey,
+		principalId: string,
+		file: string,
+	): Promise<boolean>;
+	/** Discards every saved file no turn used that was saved before `olderThan`; returns how many. */
+	discardPending(olderThan: Date): Promise<number>;
+	/** The bytes the principal has saved that no turn used yet, across their conversations. */
+	pendingBytes(principalId: string): Promise<number>;
+}

package/src/core/define-roundtable.ts

@@ -276,6 +276,7 @@ export async function defineRoundtable(
 				agentDir: config.agentDir,
 			},
 			database: { url: config.databaseUrl },
+			dataDir: config.dataDir,
 			toolTiers: toolTiers(config.toolTiers, logger),
 			listeners: [
 				...(config.http ? [publicListener(config.http)] : []),

package/src/core/define.ts

@@ -1,4 +1,9 @@
 import type { Static, TObject } from "typebox";
+import {
+	AttachmentLookupError,
+	openAttachment,
+	type ToolAttachment,
+} from "./attachments/tool-attachment.ts";
 import type { ReplyFile } from "./domain/conversation.ts";
 import { PluginError } from "./errors.ts";
 import type { HoldRule } from "./holds.ts";
@@ -26,6 +31,13 @@ export interface ToolTurn {
 	signal: AbortSignal | undefined;
 	/** Queues a file for this turn's successful reply; throws ReplyFileError when refused. */
 	attachFile(file: ReplyFile): void;
+	/**
+	 * Opens a file someone attached to this conversation, by the name `## Attachments` lists, to read
+	 * its bytes or pass it on. Only this conversation's files open; a path, a hidden name, or a file
+	 * that is not there throws a ToolRefusal the model reads. A session without an attachment store
+	 * refuses every call.
+	 */
+	attachment(file: string): Promise<ToolAttachment>;
 }
 
 /**
@@ -113,6 +125,19 @@ export function defineTool<Schema extends TObject>(
 									agent: context.agent,
 									signal,
 									attachFile: attachReplyFile,
+									attachment: async (file) => {
+										if (context.attachmentDir === undefined)
+											throw new ToolRefusal(
+												"this session keeps no attachments",
+											);
+										try {
+											return await openAttachment(context.attachmentDir, file);
+										} catch (error) {
+											if (error instanceof AttachmentLookupError)
+												throw new ToolRefusal(error.message);
+											throw error;
+										}
+									},
 								}),
 							);
 						} catch (error) {

package/src/core/host.ts

@@ -1,4 +1,5 @@
 import type { SQL } from "bun";
+import { attachmentPort } from "./attachments/attachment-port.ts";
 import type { ConversationPort } from "./contract/channels.ts";
 import type { SurfacePort } from "./contract/surface.ts";
 import { openPool, runMigrations } from "./db/migrations.ts";
@@ -77,6 +78,8 @@ export interface RoundtableOptions {
 	toolTiers?: ToolTierTable;
 	/** The database the plugins' migrations and stores use; the host owns its one pool. */
 	database?: { url: string };
+	/** The directory the host keeps files in; `context.attachments` keeps its files there. Without it that port refuses every call. */
+	dataDir?: string;
 	/** Receives the work a shutdown drain gave up on, before any service stops. */
 	aborted?: (left: string[]) => Promise<void>;
 	/**
@@ -276,6 +279,11 @@ export class Roundtable {
 				toolTiers: this.#tiers,
 				events: this.#events.sink,
 				conversations: this.#conversations(),
+				attachments: attachmentPort({
+					dataDir: this.#options.dataDir,
+					registry: () => this.#services?.find(CONVERSATIONS),
+					logger,
+				}),
 				surfaces: this.#surfaces(),
 				turns: this.#turns(),
 				database: () => {

package/src/core/plugin.ts

@@ -1,5 +1,6 @@
 import type { SQL } from "bun";
 import type { AgentSeed } from "./agents/agent-store.ts";
+import type { AttachmentPort } from "./contract/attachments.ts";
 import type {
 	BackgroundTarget,
 	ChannelClaim,
@@ -287,6 +288,11 @@ export interface PluginContext {
 	events: EventSink;
 	/** The claimed channels' conversations; calls during setup throw NotLinkedError. */
 	conversations: ConversationPort;
+	/**
+	 * Files a plugin takes from a person outside a turn, such as an upload, kept for a conversation
+	 * until a turn uses them; a call throws PluginError when the host has no `dataDir`.
+	 */
+	attachments: AttachmentPort;
 	/** Every contributed chat surface, chosen by a channel's prefix; calls during setup throw NotLinkedError. */
 	surfaces: SurfacePort;
 	/** Every plugin's direct channels, which reach a person on their own; calls during setup throw NotLinkedError. */

package/src/core/runtime/pi-agent-runtime.ts

@@ -3,7 +3,10 @@ import {
 	type ModelRuntime,
 	SessionManager,
 } from "@earendil-works/pi-coding-agent";
-import { ownerAttachmentDir } from "../attachments/attachment-dir.ts";
+import {
+	discardConversationFiles,
+	ownerAttachmentDir,
+} from "../attachments/attachment-dir.ts";
 import { withAttachmentsBlock } from "../attachments/prompt-block.ts";
 import type { AgentRuntime } from "../contract/runtime.ts";
 import { NO_ATTACHMENTS, type TurnAttachments } from "../domain/attachment.ts";
@@ -447,6 +450,7 @@ export class PiAgentRuntime implements AgentRuntime {
 	async deleteConversation(channel: ChannelKey): Promise<void> {
 		await this.#sessions.forget(channel);
 		rmSync(this.#factory.sessionDir(channel), { recursive: true, force: true });
+		await discardConversationFiles(this.#options.dataDir, channel);
 		this.#options.logger.info({ channel }, "conversation deleted");
 	}
 

package/src/core/runtime/session-factory.ts

@@ -332,6 +332,7 @@ export class SessionFactory {
 			},
 			conversation,
 			addressee,
+			attachmentDir,
 			get memory() {
 				return state.memory;
 			},

package/src/core/sessions.ts

@@ -83,6 +83,8 @@ export interface SessionContext {
 	 * it reads `"none"` for that turn alone.
 	 */
 	memory: "speaker" | "none";
+	/** Where the session's conversation keeps the files people attached; absent when the session keeps none. */
+	attachmentDir?: string;
 	/** The person the session's running turn is for; undefined between turns. */
 	speaker(): Speaker | undefined;
 	/** Runs a task beside this session, under its confirmation gate. */

package/src/core/shared/attachment-reader.ts

@@ -1,5 +1,6 @@
-import { basename, join } from "node:path";
+import { join } from "node:path";
 import { extractText, getDocumentProxy } from "unpdf";
+import { isAttachmentName, plainText } from "../attachments/attachment-name.ts";
 
 /** Characters returned per read; the model can ask for a later offset. */
 export const READ_LIMIT = 60_000;
@@ -66,14 +67,20 @@ export async function readAttachment(
 	file: string,
 	offset = 0,
 ): Promise<ReadResult> {
-	if (basename(file) !== file || file.startsWith(".")) {
-		throw new Error(`"${file}" is not an attachment name`);
+	if (!isAttachmentName(file)) {
+		throw new Error(`"${plainText(file)}" is not an attachment name`);
 	}
 	const handle = Bun.file(join(dir, file));
 	if (!(await handle.exists())) {
 		throw new Error(`no attachment named "${file}" in this channel`);
 	}
-	const bytes = new Uint8Array(await handle.arrayBuffer());
+	let bytes: Uint8Array;
+	try {
+		bytes = new Uint8Array(await handle.arrayBuffer());
+	} catch {
+		// A file system error names the path on the host; the model sees only the attachment's name.
+		throw new Error(`"${plainText(file)}" could not be read`);
+	}
 	let text: string;
 	if (isPdf(file, bytes)) {
 		const pdf = await getDocumentProxy(bytes);

package/src/index.ts

@@ -16,6 +16,7 @@ export type {
 	GroupStatus,
 	TeamStatus,
 } from "./core/agents/team-status.ts";
+export type { ToolAttachment } from "./core/attachments/tool-attachment.ts";
 export {
 	AGENT_SERVER_PLUGIN,
 	AGENT_TEAM_SERVICE,
@@ -33,6 +34,13 @@ export type {
 	RoundtableConfig,
 	TierConfig,
 } from "./core/config/config.ts";
+export type {
+	AttachmentPort,
+	AttachmentRefusalCode,
+	AttachmentUpload,
+	TurnAttachmentOptions,
+} from "./core/contract/attachments.ts";
+export { AttachmentRefusal } from "./core/contract/attachments.ts";
 export type {
 	Admission,
 	AttachmentRef,

package/src/testing.ts

@@ -4,6 +4,8 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { SQL } from "bun";
 import { agentClaim } from "./core/agents/agent-claim.ts";
+import { ownerAttachmentDir } from "./core/attachments/attachment-dir.ts";
+import { attachmentPort } from "./core/attachments/attachment-port.ts";
 import { DISCORD, type DiscordServices } from "./core/builtin/discord.ts";
 import type {
 	ConversationPort,
@@ -486,6 +488,7 @@ export async function testPlugin(
 			}),
 		);
 	services.checkRequires();
+	const attachmentDir = mkdtempSync(join(tmpdir(), "roundtable-test-plugin-"));
 	const context: Omit<PluginContext, "services" | "directChannels"> = {
 		logger,
 		env,
@@ -494,6 +497,11 @@ export async function testPlugin(
 		toolTiers: tiers,
 		events: sink,
 		conversations,
+		attachments: attachmentPort({
+			dataDir: attachmentDir,
+			registry: () => services.find(CONVERSATIONS),
+			logger,
+		}),
 		surfaces,
 		turns,
 		database: () => {
@@ -518,7 +526,6 @@ export async function testPlugin(
 	// With a team given, the agent server's claim and its target are in the router, as on a host.
 	const team = given.get(AGENTS.id)?.given;
 	const agentServer = team && "team" in team ? services.get(AGENTS) : undefined;
-	const attachmentDir = mkdtempSync(join(tmpdir(), "roundtable-test-plugin-"));
 	const identity = services.find(IDENTITY);
 	// Who wrote a message, and whom a background turn runs as: by the given IDENTITY, else the owner alone, at the owner tier.
 	const people = mapIdentity({ owners: [owner.id] });
@@ -625,6 +632,7 @@ export async function testPlugin(
 				conversation: { visibility: "shared" },
 				addressee: THE_SPEAKER,
 				memory: "speaker",
+				attachmentDir: ownerAttachmentDir(attachmentDir, channel),
 				speaker: () => runOptions?.speaker,
 				runTask: async () => {
 					throw new Error("test session cannot run tasks");