pi-roundtable 0.9.8 → 0.9.9

package/CHANGELOG.md

@@ -5,6 +5,18 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.9] - 2026-10-10
+
+### Added
+
+- `attachments.retention` (`AttachmentsConfig`, `AttachmentRetention`: `{ maxAgeMs, sweepEveryMs? }`) in the configuration, and `RoundtableOptions.attachments` for a host built by hand: the host removes the files turns used once they are `maxAgeMs` old, counted from the turn that took the file, sweeping when it starts and every `sweepEveryMs` (default one hour, at most `maxAgeMs`). It is off by default, where used files live as long as their conversation. It needs `dataDir`; a setting the host cannot keep stops the start and names it. The logs carry counts only (`files`, `bytes`, `unattributedBytes`), never a file name.
+- `AttachmentPort.expireUsed({ olderThanMs })` (`ExpireUsedOptions`, `ExpiredAttachments`), the call the sweep makes: it removes the used files older than the age and takes exactly their bytes off each owner's used-bytes tally for the conversation, under the same per-person serialization as a message taking files, so a sweep never races a turn or a conversation's deletion. The allowance behind `usedBytesLimit` (the web chat's `usedAttachmentBytesPerPrincipal`) no longer stays full for good once a host sweeps its files. The method is optional, so a custom `AttachmentPort` written before it keeps type-checking; a retention setting refuses a port without it.
+
+### Changed
+
+- A used file's record now carries its owner (a hash, never the principal id), when a turn took it and its size. A file used before this has none: the sweep ages it by its modified time, and gives the bytes back to the one person with a tally in its conversation; with several people it removes the file and reports the bytes as `unattributedBytes` without lowering any tally.
+- `read_attachment` and `ToolTurn.attachment()` answer a file removed after its retention period with a refusal that says so, and not "no attachment named …". The removed file's record keeps only that mark: neither the person's file name nor its type.
+
 ## [0.9.8] - 2026-10-10
 
 ### Added

package/docs/plugins.md

@@ -543,6 +543,7 @@ A plugin whose clients upload a file themselves, over HTTP for instance, has the
 | `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 |
+| `expireUsed({ olderThanMs })` | Optional on a custom port; the host's own has it. Removes the files turns used more than that long ago and returns `{ files, bytes, unattributedBytes }`; the owners' used-bytes tallies shrink by exactly the bytes removed. See [Retention](#retention-removing-used-files-after-a-period) |
 
 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.
@@ -554,6 +555,34 @@ The core limits only the size; the types a plugin accepts, the number of files,
 
 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)).
 
+#### Retention: removing used files after a period
+
+Left alone, a file a turn used lives as long as its conversation.
+A host that must not keep uploads (for privacy, say) sets a retention period, and the core removes used files that old:
+
+```ts
+export default {
+	// ...
+	attachments: { retention: { maxAgeMs: 7 * 24 * 60 * 60_000 } },
+} satisfies RoundtableConfig;
+```
+
+`maxAgeMs` counts from the turn that took the file, not from the upload, so a file that waited a day before a message used it still lives its full period.
+The host sweeps when it starts and then every `sweepEveryMs` (default one hour, never more than `maxAgeMs`); a host built without `defineRoundtable` passes the same object as `RoundtableOptions.attachments`.
+It needs a `dataDir`, and `maxAgeMs` and `sweepEveryMs` must be positive whole numbers of milliseconds: a host that cannot keep the setting stops at start and names it.
+A plugin that wants its own schedule calls `context.attachments.expireUsed({ olderThanMs })` itself.
+
+A sweep, for each person who used files:
+
+- runs with that person's other attachment calls, one after another, so it never races a message taking files; a conversation deleted meanwhile is skipped, not brought back;
+- removes the file, then replaces its record with a mark that keeps no file name or type, then takes exactly the removed bytes off that person's used-bytes tally for the conversation. A failure part way leaves a tally that is too high, never too low, and the next sweep finishes the job. The `usedBytesLimit` allowance a plugin enforces (the web chat's `usedAttachmentBytesPerPrincipal`) comes back as files expire, instead of filling for good.
+
+After that, `read_attachment` and `turn.attachment(file)` answer a clear refusal that the file "was removed after its retention period", with neither a host path nor a bare "not found". The refusal is the only trace; the person's name for the file is gone.
+Files waiting for a turn are not touched: `discardPending` is theirs.
+A file a turn used under an earlier release has no recorded owner; the sweep ages it by the file's modified time and gives its bytes back to the one person with a tally in that conversation. When several people have tallies there, it removes the file but cannot tell whose bytes they were, so no tally shrinks and the bytes are reported as `unattributedBytes`; deleting the conversation clears the tallies.
+Only files taken through `context.attachments` are covered. Files the core downloads from Discord links keep their conversation's lifetime.
+The host logs counts only (`files`, `bytes`, `unattributedBytes`), never a file name, and a failed sweep only its error code.
+
 ### `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.
@@ -561,7 +590,7 @@ Once a turn has used a file, the model reads it with `read_attachment`, and a to
 `turn.workspace` is `{ workspace, scratchDir? }` in a session with a shared workspace (an agent's), the same roots as `SessionContext.workspace`, and undefined elsewhere: a tool that makes a file can save it there, under the scratch dir when there is one, and name its path, so the model sends it on with `attach_file` or a `discord_send_message` file `path` instead of carrying its bytes.
 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.
+Only the conversation's own files open; a path, a hidden name, or a missing file throws a `ToolRefusal` the model reads, and so does a file the host's [retention period](#retention-removing-used-files-after-a-period) removed, which says so.
 Throw `ToolRefusal` for a call the model should correct; any other error fails the call.
 
 <!-- example: examples/tools.ts -->
@@ -3316,7 +3345,9 @@ Import from the entries listed below; source area files are internal.
 | `AttachmentRef` | `pi-roundtable` | type |
 | `AttachmentRefusal` | `pi-roundtable` | value |
 | `AttachmentRefusalCode` | `pi-roundtable` | type |
+| `AttachmentRetention` | `pi-roundtable` | type |
 | `AttachmentUpload` | `pi-roundtable` | type |
+| `AttachmentsConfig` | `pi-roundtable` | type |
 | `AvatarMode` | `pi-roundtable` | type |
 | `AvatarStudio` | `pi-roundtable` | type |
 | `BACKGROUND_TURNS` | `pi-roundtable` | value |
@@ -3355,6 +3386,8 @@ Import from the entries listed below; source area files are internal.
 | `DrainOptions` | `pi-roundtable` | type |
 | `EventHandlers` | `pi-roundtable` | type |
 | `EventSink` | `pi-roundtable` | type |
+| `ExpireUsedOptions` | `pi-roundtable` | type |
+| `ExpiredAttachments` | `pi-roundtable` | type |
 | `GroupStatus` | `pi-roundtable` | type |
 | `HeldActionStore` | `pi-roundtable` | type |
 | `HeldCall` | `pi-roundtable` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.9.8",
+	"version": "0.9.9",
 	"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

@@ -7,6 +7,9 @@ export const STAGING = "attachments-pending";
 /** Where each principal's tally of used bytes per conversation is kept. */
 export const USAGE = "attachments-used";
 
+/** The record of a saved file, in a directory next to it that no file name can be. */
+export const RECORDS = ".records";
+
 /** A channel key as a single path segment. */
 export function channelSegment(channel: ChannelKey): string {
 	return channel.replace(/[^A-Za-z0-9_-]/g, "_");

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

@@ -0,0 +1,170 @@
+import { readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExpiredAttachments } from "../contract/attachments.ts";
+import { listDir, RECORDS, USAGE } from "./attachment-dir.ts";
+import { isAttachmentName } from "./attachment-name.ts";
+import { shrinkTally } from "./attachment-tally.ts";
+
+/** What the core records about a file a turn used; the first two come from its upload. */
+export interface UsedRecord {
+	name: string;
+	contentType: string;
+	/** The owner's directory segment (a hash, never the id), when the core recorded it. */
+	principal?: string;
+	/** When the turn took the file, in epoch milliseconds. */
+	usedAt?: number;
+	size?: number;
+}
+
+/** What stays of a record once its file is removed: when, and nothing the person named. */
+interface ExpiredMark {
+	expiredAt: number;
+}
+
+/** The record file of `file` in a conversation's attachment directory. */
+export function recordPath(dir: string, file: string): string {
+	return join(dir, RECORDS, `${file}.json`);
+}
+
+/** The record as parsed, or undefined when there is none or it is not an object. */
+async function readRecord(path: string): Promise<unknown> {
+	try {
+		return JSON.parse(await readFile(path, "utf8"));
+	} catch (error) {
+		if (error instanceof SyntaxError) return undefined;
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+const isExpiredMark = (value: unknown): value is ExpiredMark =>
+	typeof value === "object" &&
+	value !== null &&
+	typeof (value as ExpiredMark).expiredAt === "number";
+
+const isUsedRecord = (value: unknown): value is UsedRecord =>
+	typeof value === "object" &&
+	value !== null &&
+	!isExpiredMark(value) &&
+	typeof (value as UsedRecord).name === "string";
+
+/** Whether the file's retention period ended and the core removed it. */
+export async function wasExpired(dir: string, file: string): Promise<boolean> {
+	if (!isAttachmentName(file)) return false;
+	return isExpiredMark(await readRecord(recordPath(dir, file)));
+}
+
+/** What a tool or the model reads for a file removed after its retention period. */
+export const expiredMessage = (shown: string): string =>
+	`"${shown}" was removed after its retention period and cannot be read any more. Ask the person to attach it again.`;
+
+export interface ExpiryDeps {
+	dataDir: string;
+	now(): number;
+	/** Runs after the principal's earlier calls, as every call that changes their files does. */
+	exclusive<T>(principal: string, run: () => Promise<T>): Promise<T>;
+}
+
+/** A used file the sweep found old, with the owner it could tell. */
+interface Candidate {
+	channel: string;
+	file: string;
+}
+
+/** Whoever the owner of an unowned record could only be: a lone tally in the conversation, else none. */
+async function soleHolders(
+	dataDir: string,
+): Promise<Map<string, string | null>> {
+	const holders = new Map<string, string | null>();
+	const root = join(dataDir, USAGE);
+	for (const principal of await listDir(root))
+		for (const entry of await listDir(join(root, principal))) {
+			if (entry.endsWith(".tmp")) continue;
+			holders.set(entry, holders.has(entry) ? null : principal);
+		}
+	return holders;
+}
+
+/** The used files older than `cutoff`, grouped by the owner whose calls they run with. */
+async function findOld(
+	dataDir: string,
+	cutoff: number,
+): Promise<Map<string, Candidate[]>> {
+	const holders = await soleHolders(dataDir);
+	const groups = new Map<string, Candidate[]>();
+	const root = join(dataDir, "attachments");
+	for (const channel of await listDir(root)) {
+		const dir = join(root, channel);
+		for (const entry of await listDir(join(dir, RECORDS))) {
+			if (!entry.endsWith(".json")) continue;
+			const file = entry.slice(0, -".json".length);
+			const record = await readRecord(recordPath(dir, file));
+			if (!isUsedRecord(record)) continue;
+			const usedAt =
+				record.usedAt ??
+				(await stat(join(dir, file)).catch(() => undefined))?.mtimeMs;
+			if (usedAt === undefined || usedAt >= cutoff) continue;
+			const owner = record.principal ?? holders.get(channel) ?? "";
+			groups.set(owner, [...(groups.get(owner) ?? []), { channel, file }]);
+		}
+	}
+	return groups;
+}
+
+/**
+ * Removes the files turns used before `now - olderThanMs`. Each owner's files go in one call that
+ * runs with their other calls: the file, then its record (which becomes a mark that keeps no
+ * name), then the bytes off their tally for the conversation, so a failure part way leaves a
+ * tally that is too high, never too low.
+ */
+export async function expireUsedFiles(
+	deps: ExpiryDeps,
+	olderThanMs: number,
+): Promise<ExpiredAttachments> {
+	const { dataDir } = deps;
+	const cutoff = deps.now() - olderThanMs;
+	const total: ExpiredAttachments = {
+		files: 0,
+		bytes: 0,
+		unattributedBytes: 0,
+	};
+	for (const [owner, candidates] of await findOld(dataDir, cutoff)) {
+		await deps.exclusive(owner || "unattributed", async () => {
+			const removed = new Map<string, number>();
+			for (const { channel, file } of candidates) {
+				const dir = join(dataDir, "attachments", channel);
+				const path = recordPath(dir, file);
+				const record = await readRecord(path);
+				// A turn may have deleted the conversation, or an earlier call this one.
+				if (!isUsedRecord(record)) continue;
+				const info = await stat(join(dir, file)).catch(() => undefined);
+				const size = info?.size ?? record.size ?? 0;
+				const usedAt = record.usedAt ?? info?.mtimeMs;
+				if (usedAt === undefined || usedAt >= cutoff) continue;
+				await rm(join(dir, file), { force: true });
+				const mark: ExpiredMark = { expiredAt: deps.now() };
+				if (!(await writeMark(path, mark))) continue;
+				total.files += 1;
+				total.bytes += size;
+				if (owner === "") total.unattributedBytes += size;
+				else removed.set(channel, (removed.get(channel) ?? 0) + size);
+			}
+			for (const [channel, bytes] of removed)
+				await shrinkTally(join(dataDir, USAGE, owner, channel), bytes);
+		});
+	}
+	return total;
+}
+
+/** Replaces a record by its mark; false when the conversation's directory is gone. */
+async function writeMark(path: string, mark: ExpiredMark): Promise<boolean> {
+	const temporary = `${path}.tmp`;
+	try {
+		await writeFile(temporary, JSON.stringify(mark));
+		await rename(temporary, path);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}

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

@@ -28,6 +28,7 @@ export function attachmentPort(options: {
 			remove: refuse,
 			discardPending: refuse,
 			pendingBytes: refuse,
+			expireUsed: refuse,
 		};
 	}
 	return new AttachmentStore({ dataDir, registry, logger });

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

@@ -0,0 +1,116 @@
+import type { AttachmentPort } from "../contract/attachments.ts";
+import { PluginError } from "../errors.ts";
+import type { Logger } from "../log.ts";
+import type { Service } from "../plugin.ts";
+
+/** How long used files are kept, and how often the host looks for the ones past it. */
+export interface AttachmentRetention {
+	/** Files a turn used more than this many milliseconds ago are removed. */
+	maxAgeMs: number;
+	/** The wait between two sweeps; default one hour, and never more than `maxAgeMs`. */
+	sweepEveryMs?: number;
+}
+
+/** The wait between two sweeps when the host sets none. */
+export const DEFAULT_SWEEP_EVERY_MS = 60 * 60_000;
+
+/** The port's `expireUsed`; `retentionServices` refuses a port without it before a sweep can run. */
+function expireUsedOf(
+	attachments: AttachmentPort,
+): NonNullable<AttachmentPort["expireUsed"]> {
+	const expire = attachments.expireUsed;
+	if (expire === undefined)
+		throw new PluginError("this attachment port cannot expire used files");
+	return expire.bind(attachments);
+}
+
+/** The wait between two sweeps for `retention`. */
+function sweepPeriod(retention: AttachmentRetention): number {
+	return Math.min(
+		retention.sweepEveryMs ?? DEFAULT_SWEEP_EVERY_MS,
+		retention.maxAgeMs,
+	);
+}
+
+/**
+ * The service that removes used attachments past their retention period: one sweep when the host
+ * starts, then one every period, never two at once. A sweep that fails is logged by its error
+ * code alone, since a file system error names the file, and the next sweep tries again. The logs
+ * carry counts, never a file's name.
+ */
+export function retentionService(
+	attachments: AttachmentPort,
+	retention: AttachmentRetention,
+	logger: Logger,
+): Service {
+	let timer: ReturnType<typeof setInterval> | undefined;
+	let sweeping: Promise<void> | undefined;
+	const sweep = async (): Promise<void> => {
+		try {
+			const result = await expireUsedOf(attachments)({
+				olderThanMs: retention.maxAgeMs,
+			});
+			if (result.files > 0)
+				logger.info(
+					{
+						files: result.files,
+						bytes: result.bytes,
+						unattributedBytes: result.unattributedBytes,
+					},
+					"used attachments past their retention period removed",
+				);
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			logger.warn(
+				code === undefined ? {} : { code },
+				"used attachments past their retention period not removed",
+			);
+		}
+	};
+	const once = (): Promise<void> => {
+		sweeping ??= sweep().finally(() => {
+			sweeping = undefined;
+		});
+		return sweeping;
+	};
+	return {
+		name: "attachment-retention",
+		start: async () => {
+			await once();
+			timer = setInterval(() => void once(), sweepPeriod(retention));
+		},
+		stop: async () => {
+			clearInterval(timer);
+			timer = undefined;
+			await sweeping;
+		},
+	};
+}
+
+/**
+ * The retention service for the host's options, or none when it sets no retention. A setting the
+ * host cannot keep stops the boot, naming it: no `dataDir` to keep files in, or an age or period
+ * that is not a positive whole number of milliseconds.
+ */
+export function retentionServices(
+	retention: AttachmentRetention | undefined,
+	dataDir: string | undefined,
+	attachments: AttachmentPort,
+	logger: Logger,
+): Service[] {
+	if (!retention) return [];
+	if (dataDir === undefined)
+		throw new PluginError(
+			"attachments.retention needs a dataDir: set dataDir in the configuration, or the dataDir option of the host.",
+		);
+	if (attachments.expireUsed === undefined)
+		throw new PluginError(
+			"attachments.retention needs an attachment port with expireUsed; this one has none.",
+		);
+	for (const [key, value] of Object.entries(retention))
+		if (!Number.isInteger(value) || value < 1)
+			throw new PluginError(
+				`attachments.retention.${key} must be a positive whole number of milliseconds; got ${String(value)}.`,
+			);
+	return [retentionService(attachments, retention, logger)];
+}

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

@@ -1,11 +1,12 @@
-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 { rename, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
 import {
 	type AttachmentPort,
 	AttachmentRefusal,
 	type AttachmentUpload,
+	type ExpiredAttachments,
+	type ExpireUsedOptions,
 	type TurnAttachmentOptions,
 } from "../contract/attachments.ts";
 import type { ConversationRegistry } from "../conversations/conversation-registry.ts";
@@ -19,22 +20,24 @@ import {
 	channelSegment,
 	listDir,
 	ownerAttachmentDir,
+	RECORDS,
 	removeIfEmpty,
 	STAGING,
 	USAGE,
 } from "./attachment-dir.ts";
+import { expireUsedFiles, type UsedRecord } from "./attachment-expiry.ts";
 import { MAX_ATTACHMENT_BYTES, safeFileName } from "./attachment-fetcher.ts";
 import { isAttachmentName } from "./attachment-name.ts";
+import { principalSegment, readTally, writeTally } from "./attachment-tally.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;
+	/** The clock that stamps the turn that takes a file; epoch milliseconds, default `Date.now`. */
+	now?: () => number;
 }
 
 interface StagedRecord {
@@ -48,35 +51,6 @@ const isRecord = (value: unknown): value is StagedRecord =>
 	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,
@@ -240,6 +214,18 @@ export class AttachmentStore implements AttachmentPort {
 					join(staging, RECORDS, `${stored.file}.json`),
 					join(target, RECORDS, `${stored.file}.json`),
 				);
+				// Who used the file and when, for the sweep that expires it and gives the tally back.
+				const used: UsedRecord = {
+					name: stored.name,
+					contentType: stored.contentType,
+					principal: principalSegment(principalId),
+					usedAt: (this.#options.now ?? Date.now)(),
+					size: stored.size,
+				};
+				await Bun.write(
+					join(target, RECORDS, `${stored.file}.json`),
+					JSON.stringify(used),
+				);
 			}
 			await writeTally(tally, before + added);
 		} catch (error) {
@@ -335,6 +321,17 @@ export class AttachmentStore implements AttachmentPort {
 		return total;
 	}
 
+	async expireUsed(options: ExpireUsedOptions): Promise<ExpiredAttachments> {
+		return expireUsedFiles(
+			{
+				dataDir: this.#options.dataDir,
+				now: this.#options.now ?? Date.now,
+				exclusive: (principal, run) => this.#exclusive(principal, run),
+			},
+			options.olderThanMs,
+		);
+	}
+
 	/** The bytes the principal's turns used, across their conversations. */
 	async #usedBytes(principalId: string): Promise<number> {
 		const dir = this.#tallyDir(principalId);

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

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/** A principal id as one path segment; hashed, so two ids never share a directory. */
+export 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. */
+export 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. */
+export 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);
+}
+
+/**
+ * Takes `bytes` off a tally that is there, never below zero. A tally that is gone, because the
+ * conversation was deleted, stays gone: nothing here brings a deleted conversation back.
+ */
+export async function shrinkTally(path: string, bytes: number): Promise<void> {
+	const temporary = `${path}.tmp`;
+	try {
+		const before = await readFile(path, "utf8");
+		const value = Number(before);
+		const left = Math.max(0, (Number.isFinite(value) ? value : 0) - bytes);
+		await writeFile(temporary, String(left));
+		await rename(temporary, path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+}

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

@@ -1,6 +1,7 @@
 import { join } from "node:path";
+import { RECORDS } from "./attachment-dir.ts";
+import { expiredMessage, wasExpired } from "./attachment-expiry.ts";
 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 {
@@ -19,6 +20,15 @@ export class AttachmentLookupError extends Error {
 	override name = "AttachmentLookupError";
 }
 
+/** A file the core removed after its retention period; the message says so, with no path. */
+export class AttachmentExpiredError extends AttachmentLookupError {
+	override name = "AttachmentExpiredError";
+
+	constructor(shown: string) {
+		super(expiredMessage(shown));
+	}
+}
+
 interface Recorded {
 	name?: unknown;
 	contentType?: unknown;
@@ -36,10 +46,12 @@ export async function openAttachment(
 	if (!isAttachmentName(file))
 		throw new AttachmentLookupError(`"${shown}" is not an attachment name`);
 	const handle = Bun.file(join(dir, file));
-	if (!(await handle.exists()))
+	if (!(await handle.exists())) {
+		if (await wasExpired(dir, file)) throw new AttachmentExpiredError(shown);
 		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 {

package/src/core/config/attachments.ts

@@ -0,0 +1,28 @@
+import type { AttachmentRetention } from "../attachments/attachment-retention.ts";
+import { integer, optional, shape } from "./schema.ts";
+
+/** The configuration's `attachments`: what the host does with the files people send. */
+export interface AttachmentsConfig {
+	/**
+	 * Removes the files turns used once they are `maxAgeMs` old (counted from the turn that took
+	 * the file), giving the owners' used-bytes allowance back; sweeps when the host starts and every
+	 * `sweepEveryMs` (default one hour, at most `maxAgeMs`). Left out, used files live as long as
+	 * their conversation. Files waiting for a turn are not touched; the plugin that took them
+	 * discards those.
+	 */
+	retention?: AttachmentRetention;
+}
+
+const YEAR_MS = 365 * 24 * 60 * 60_000;
+
+/** The `attachments` key's shape. */
+export const attachmentsShape = optional(
+	shape({
+		retention: optional(
+			shape({
+				maxAgeMs: integer(1, YEAR_MS),
+				sweepEveryMs: optional(integer(1, YEAR_MS)),
+			}),
+		),
+	}),
+);

package/src/core/config/config.ts

@@ -26,6 +26,7 @@ import {
 	type ResolvedDiscord,
 	resolvedDiscord,
 } from "./adapters.ts";
+import { type AttachmentsConfig, attachmentsShape } from "./attachments.ts";
 import {
 	bool,
 	guarded,
@@ -98,6 +99,8 @@ export interface RoundtableConfig {
 	database: { url: string };
 	/** Where the process keeps its files, such as pictures, attachments, and skills. */
 	dataDir: string;
+	/** What the host does with the files people send, such as removing them after a retention period. */
+	attachments?: AttachmentsConfig;
 	/** Pi's agent directory, holding the model logins; default `<dataDir>/pi`. */
 	agentDir?: string;
 	/** The model of the agents, written `<provider>/<id>`. */
@@ -211,6 +214,7 @@ const schema = shape({
 	discord: optional(discordShape),
 	database: shape({ url: text }),
 	dataDir: text,
+	attachments: attachmentsShape,
 	agentDir: optional(text),
 	model: text,
 	thinking: optional(oneOf(...THINKING_LEVELS)),
@@ -306,6 +310,8 @@ export interface ResolvedConfig {
 	discord?: ResolvedDiscord;
 	databaseUrl: string;
 	dataDir: string;
+	/** Absent `retention`: used files live as long as their conversation. */
+	attachments: AttachmentsConfig;
 	agentDir: string;
 	model: ModelRef;
 	thinking: ThinkingLevel;
@@ -421,6 +427,9 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 		...(discord ? { discord: resolvedDiscord(discord, slug) } : {}),
 		databaseUrl: config.database.url,
 		dataDir: config.dataDir,
+		attachments: config.attachments?.retention
+			? { retention: config.attachments.retention }
+			: {},
 		agentDir: config.agentDir ?? `${config.dataDir}/pi`,
 		model,
 		thinking,

package/src/core/contract/attachments.ts

@@ -44,6 +44,26 @@ export interface TurnAttachmentOptions {
 	usedBytesLimit?: number;
 }
 
+/** What `expireUsed` asks: how old a used file must be to go. */
+export interface ExpireUsedOptions {
+	/** Files a turn used more than this many milliseconds ago are removed. */
+	olderThanMs: number;
+}
+
+/** What `expireUsed` removed. */
+export interface ExpiredAttachments {
+	/** How many used files were removed. */
+	files: number;
+	/** Their bytes; the owners' used-bytes tallies shrank by as much, less `unattributedBytes`. */
+	bytes: number;
+	/**
+	 * Bytes of removed files whose owner the core could not tell, because a turn used them before
+	 * the core recorded owners and their conversation has more than one person's tally. The files
+	 * are gone, but no tally shrank for them; deleting the conversation clears the tallies.
+	 */
+	unattributedBytes: 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
@@ -89,4 +109,17 @@ export interface AttachmentPort {
 	discardPending(olderThan: Date): Promise<number>;
 	/** The bytes the principal has saved that no turn used yet, across their conversations. */
 	pendingBytes(principalId: string): Promise<number>;
+	/**
+	 * Removes the files turns used more than `olderThanMs` ago, and lowers each owner's used-bytes
+	 * tally for the conversation by exactly the bytes removed, so the allowance `usedBytesLimit`
+	 * checks comes back. The age counts from the turn that took the file, not from its upload. It
+	 * runs one after another with that person's other calls, so it never races a message taking
+	 * files. A removed file leaves a mark without its name: `read_attachment` and
+	 * `ToolTurn.attachment()` then say the file was removed after its retention period. Files
+	 * waiting for a turn are not touched; `discardPending` is theirs. A host sets
+	 * `attachments.retention` to run this on a timer. Optional, so a port a plugin wrote before it
+	 * existed still type-checks; the host's own port always has it, and a retention setting refuses
+	 * a port without it.
+	 */
+	expireUsed?(options: ExpireUsedOptions): Promise<ExpiredAttachments>;
 }

package/src/core/define-roundtable.ts

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

package/src/core/host.ts

@@ -1,5 +1,9 @@
 import type { SQL } from "bun";
 import { attachmentPort } from "./attachments/attachment-port.ts";
+import {
+	type AttachmentRetention,
+	retentionServices,
+} from "./attachments/attachment-retention.ts";
 import type { ConversationPort } from "./contract/channels.ts";
 import type { SurfacePort } from "./contract/surface.ts";
 import { openPool, runMigrations } from "./db/migrations.ts";
@@ -82,6 +86,13 @@ export interface RoundtableOptions {
 	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;
+	/**
+	 * What the host does with the attachments it keeps. `retention` removes the files turns used once
+	 * they are `maxAgeMs` old, sweeping at start and every `sweepEveryMs` (default one hour), and gives
+	 * the owners' used-bytes allowance back; without it used files live as long as their conversation.
+	 * Needs `dataDir`.
+	 */
+	attachments?: { retention?: AttachmentRetention };
 	/** Receives the work a shutdown drain gave up on, before any service stops. */
 	aborted?: (left: string[]) => Promise<void>;
 	/**
@@ -270,6 +281,17 @@ export class Roundtable {
 		this.#services = new ServiceRegistry(this.#active);
 		this.#services.checkRequires();
 		const providers = resolveProviders(this.#active, this.#options.judgeModel);
+		const attachments = attachmentPort({
+			dataDir: this.#options.dataDir,
+			registry: () => this.#services?.find(CONVERSATIONS),
+			logger,
+		});
+		const retention = retentionServices(
+			this.#options.attachments?.retention,
+			this.#options.dataDir,
+			attachments,
+			logger,
+		);
 		await this.#migrate();
 		this.#registry = await collectContributions(
 			this.#active,
@@ -287,11 +309,7 @@ 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,
-				}),
+				attachments,
 				surfaces: this.#surfaces(),
 				turns: this.#turns(),
 				database: () => {
@@ -331,7 +349,7 @@ export class Roundtable {
 		});
 		const http = new HttpListeners(listeners, routes, logger);
 		for (const plugin of this.#active) await plugin.preflight?.();
-		for (const service of this.#registry.services) {
+		for (const service of [...this.#registry.services, ...retention]) {
 			await service.start?.();
 			this.#started.push(service);
 		}

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

@@ -1,6 +1,8 @@
 import { join } from "node:path";
 import { extractText, getDocumentProxy } from "unpdf";
+import { wasExpired } from "../attachments/attachment-expiry.ts";
 import { isAttachmentName, plainText } from "../attachments/attachment-name.ts";
+import { AttachmentExpiredError } from "../attachments/tool-attachment.ts";
 
 /** Characters returned per read; the model can ask for a later offset. */
 export const READ_LIMIT = 60_000;
@@ -72,6 +74,8 @@ export async function readAttachment(
 	}
 	const handle = Bun.file(join(dir, file));
 	if (!(await handle.exists())) {
+		if (await wasExpired(dir, file))
+			throw new AttachmentExpiredError(plainText(file));
 		throw new Error(`no attachment named "${file}" in this channel`);
 	}
 	let bytes: Uint8Array;

package/src/index.ts

@@ -16,6 +16,7 @@ export type {
 	GroupStatus,
 	TeamStatus,
 } from "./core/agents/team-status.ts";
+export type { AttachmentRetention } from "./core/attachments/attachment-retention.ts";
 export type { ToolAttachment } from "./core/attachments/tool-attachment.ts";
 export {
 	AGENT_SERVER_PLUGIN,
@@ -26,6 +27,7 @@ export type {
 	AccessOwnerConfig,
 	AccessTierConfig,
 } from "./core/config/access.ts";
+export type { AttachmentsConfig } from "./core/config/attachments.ts";
 export type {
 	AdapterConfig,
 	BackgroundConfig,
@@ -38,6 +40,8 @@ export type {
 	AttachmentPort,
 	AttachmentRefusalCode,
 	AttachmentUpload,
+	ExpiredAttachments,
+	ExpireUsedOptions,
 	TurnAttachmentOptions,
 } from "./core/contract/attachments.ts";
 export { AttachmentRefusal } from "./core/contract/attachments.ts";