pi-roundtable 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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

package/docs/plugins.md

@@ -538,14 +538,16 @@ A plugin whose clients upload a file themselves, over HTTP for instance, has the
 | 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)` | 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`); then none moves |
+| `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.
-A channel with no record yet, such as a conversation opened but not written in, is not checked; the plugin that owns the channel checks it, as the web chat does before it saves.
+**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.
 
@@ -3429,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.2",
+	"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-store.ts

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
 import { mkdirSync } from "node:fs";
-import { readdir, rename, rm, stat } from "node:fs/promises";
-import { basename, join } from "node:path";
+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 {
@@ -14,12 +15,18 @@ import type {
 } from "../domain/attachment.ts";
 import type { Logger } from "../log.ts";
 import type { ChannelKey } from "../sessions.ts";
-import { channelSegment, ownerAttachmentDir } from "./attachment-dir.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";
 
-/** Where saved files wait, beside the conversations' attachment directories. */
-const STAGING = "attachments-pending";
 /** The record of a saved file, in a directory next to it that no file name can be. */
 export const RECORDS = ".records";
 
@@ -46,23 +53,28 @@ function principalSegment(principalId: string): string {
 	return createHash("sha256").update(principalId).digest("hex").slice(0, 32);
 }
 
-/** Whether `file` could be a name this store gave out: one path segment that is not hidden. */
-function isFileName(file: string): boolean {
-	return (
-		file !== "" &&
-		basename(file) === file &&
-		!file.startsWith(".") &&
-		!file.includes("\0")
-	);
+/** 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;
+	}
 }
 
-async function listDir(dir: string): Promise<string[]> {
+/** 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 {
-		return await readdir(dir);
+		await writeFile(temporary, String(bytes));
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-		throw 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);
 }
 
 /**
@@ -70,14 +82,34 @@ async function listDir(dir: string): Promise<string[]> {
  * 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,
@@ -87,6 +119,10 @@ export class AttachmentStore implements AttachmentPort {
 		);
 	}
 
+	#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);
@@ -110,15 +146,25 @@ export class AttachmentStore implements AttachmentPort {
 				`a file may be at most 25 MiB; "${upload.name}" is ${size} bytes`,
 			);
 		const dir = this.#stagingDir(channel, principalId);
-		mkdirSync(join(dir, RECORDS), { recursive: true, mode: 0o700 });
 		const file = `${crypto.randomUUID()}-${safeFileName(upload.name)}`;
 		const path = join(dir, file);
-		await Bun.write(path, upload.data);
+		const recordPath = join(dir, RECORDS, `${file}.json`);
 		const record: StagedRecord = {
 			name: upload.name,
 			contentType: upload.contentType,
 		};
-		await Bun.write(join(dir, RECORDS, `${file}.json`), JSON.stringify(record));
+		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,
@@ -133,8 +179,26 @@ export class AttachmentStore implements AttachmentPort {
 		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[] = [];
@@ -145,39 +209,70 @@ export class AttachmentStore implements AttachmentPort {
 					"unknown_file",
 					`no saved file "${file}" is waiting for this person in ${channel}`,
 				);
-			const from = join(staging, file);
 			found.push({
 				name: record.name,
 				file,
 				path: join(target, file),
 				contentType: record.contentType,
-				size: (await stat(from)).size,
+				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 });
-		for (const stored of found) {
-			try {
+		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);
-			} catch (error) {
-				// Another turn used the file between the check and the move.
-				if ((error as NodeJS.ErrnoException).code === "ENOENT")
-					throw new AttachmentRefusal(
-						"unknown_file",
-						`the saved file "${stored.file}" was used already`,
-					);
-				throw error;
+				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(staging, RECORDS, `${stored.file}.json`),
 				join(target, RECORDS, `${stored.file}.json`),
-			);
+				join(staging, RECORDS, `${stored.file}.json`),
+			).catch(() => undefined);
 		}
-		const { images, failures } = await modelImagesOf(
-			found,
-			this.#options.logger,
-		);
-		return { files: found, images, failures };
+		await writeTally(tally, before).catch(() => undefined);
 	}
 
 	async remove(
@@ -187,27 +282,37 @@ export class AttachmentStore implements AttachmentPort {
 	): Promise<boolean> {
 		await this.#admit(channel, principalId);
 		const staging = this.#stagingDir(channel, principalId);
-		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;
+		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)) {
-			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 });
-					discarded += 1;
+			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;
 	}
@@ -230,12 +335,22 @@ export class AttachmentStore implements AttachmentPort {
 		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 (!isFileName(file)) return undefined;
+		if (!isAttachmentName(file)) return undefined;
 		const stored = Bun.file(join(staging, RECORDS, `${file}.json`));
 		if (
 			!(await stored.exists()) ||

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

@@ -1,4 +1,5 @@
-import { basename, join } from "node:path";
+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. */
@@ -31,12 +32,13 @@ export async function openAttachment(
 	dir: string,
 	file: string,
 ): Promise<ToolAttachment> {
-	if (file === "" || basename(file) !== file || file.startsWith("."))
-		throw new AttachmentLookupError(`"${file}" is not an attachment name`);
+	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 "${file}" in this channel`,
+			`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() : {};
@@ -48,6 +50,13 @@ export async function openAttachment(
 				? recorded.contentType
 				: handle.type,
 		size: handle.size,
-		bytes: async () => new Uint8Array(await handle.arrayBuffer()),
+		// 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/contract/attachments.ts

@@ -19,7 +19,9 @@ export type AttachmentRefusalCode =
 	/** 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";
+	| "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 {
@@ -32,6 +34,16 @@ export class AttachmentRefusal extends Error {
 	}
 }
 
+/** 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
@@ -40,6 +52,13 @@ export class AttachmentRefusal extends Error {
  * 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. */
@@ -51,12 +70,14 @@ export interface AttachmentPort {
 	/**
 	 * 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; none moves then.
+	 * 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(

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/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

@@ -38,6 +38,7 @@ export type {
 	AttachmentPort,
 	AttachmentRefusalCode,
 	AttachmentUpload,
+	TurnAttachmentOptions,
 } from "./core/contract/attachments.ts";
 export { AttachmentRefusal } from "./core/contract/attachments.ts";
 export type {