pi-roundtable 0.9.7 → 0.9.9

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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
+
+- A tool's `hold` may return a promise and takes the turn as a second argument, the `ToolTurn` its `run` receives (the speaker, the channel, the agent, and a `signal`), so a plugin can describe a held call with data it fetches as the current speaker, such as an entity's display name looked up with the speaker's own credentials. The confirmation gate awaits it before it posts the card, so the card, `ApprovalDetails.action` (the web chat's `approval.action`) and the held call carry the fetched text. It waits `HOLD_DESCRIBE_TIMEOUT_MS` (10 seconds, exported from `pi-roundtable/kit`); a rejection, a throw or a timeout holds the call under a generic description (`run <tool>`) and never lets it run. `signal` aborts when the turn stops or the wait ends, and a turn stopped meanwhile opens no card and holds nothing. Calls made together are held and shown in the order they were made, each with its own description.
+- `HoldRule.describeInTurn(tool, input, context, turn)`, the same for a hold rule of a plugin's `holdRules`: it may return a promise and the gate asks it instead of `describe` in a turn. `HoldCheck.inTurn` asks a chain's rules as a turn does. `describe` stays required and is what a host with no turn sees.
+
+### Changed
+
+- A hold that throws, not only one that rejects, is now held under a generic description in a turn; it used to fail the tool call. A hold that declares only its arguments and answers at once behaves exactly as before, and is still called with the arguments alone where a host checks the hold with no turn, such as a precheck script's tool call. A hold that declares `turn` is not called there: it is described as `run <tool>` and counts as held.
+- Hold lookups are awaited one tool call at a time, because the agent loop checks calls one after another: a message with N calls whose lookups hang waits up to N × `HOLD_DESCRIBE_TIMEOUT_MS`, and an approved call in the confirming turn still waits for its lookup. Keep lookups fast. This is documented in `docs/plugins.md`; behavior is unchanged.
+- A hold that declares `turn` through a wrapper (so its arity is not visible), or returns a thenable without `catch`, is now held as `run <tool>` where there is no turn, instead of failing with an obscure `TypeError`.
+
 ## [0.9.7] - 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 -->
@@ -714,6 +743,38 @@ export const cleanup = definePlugin({
 ```
 <!-- /example -->
 
+#### A hold that looks things up
+
+A hold may need something it must fetch as the speaker before it can describe the call, such as the display name of the entity an id stands for, read with the speaker's own credentials.
+A tool's `hold` may then return a promise and takes the turn as a second argument: the `ToolTurn` its `run` receives, with the `speaker`, the `channel` and the `agent` of the turn that makes the call.
+
+```ts
+defineTool({
+	name: "ticket_close",
+	description: "Close a ticket.",
+	parameters: Type.Object({ id: Type.String() }),
+	minTier: "member",
+	hold: async ({ id }, turn) => {
+		const ticket = await tickets.get(id, turn.speaker, turn.signal);
+		return `Close ticket ${ticket.title}`;
+	},
+	run: ({ id }) => tickets.close(id),
+});
+```
+
+The gate awaits the description before it posts the card, so the card's bold line, the `action` of `ApprovalDetails` (the web chat's `approval.action`) and the held call all carry the fetched text.
+
+- `turn.signal` aborts when the turn stops, or when the wait ends. A turn stopped while its description is awaited opens no card and holds nothing.
+- The wait lasts `HOLD_DESCRIBE_TIMEOUT_MS` (10 seconds, exported from `pi-roundtable/kit`). A rejection, a throw or a timeout holds the call under a generic description (`run <tool>`, in the host's locale), never lets it run: the owner still sees the exact input on the card.
+- Returning `undefined` after the lookup lets the call run, as for a hold that answers at once.
+- Calls made together are held, and their cards opened, in the order they were made, each with its own description, whichever lookup returns first.
+- The agent loop runs one tool call's checks after another's, so hold lookups are awaited one call at a time: a model message with N calls whose lookups all hang waits up to N × `HOLD_DESCRIBE_TIMEOUT_MS` before the last card. This holds in the confirming turn too, where an already approved call still waits for its lookup before it is released. Keep lookups fast and give them a short timeout of their own.
+- A hold must change nothing: it may be called again for the same call, such as when the owner's confirming message makes the call again.
+- A hold that declares only its arguments and answers at once is called as it always was. Where a host checks the hold with no turn, such as the `holds` of a test harness or a [precheck script](#precheck-scripts-prechecks-the-agent-writes)'s tool call, a hold that declares `turn` is not called; it is described as `run <tool>` and so counts as held.
+
+A rule of `holdRules` does the same with `describeInTurn(tool, input, context, turn)`, which may return a promise and which the gate asks instead of `describe` in a turn.
+`describe` is still required and is what a host without a turn sees. `holdChain(rules).inTurn(tool, input, context, turn)` asks the rules as a turn does, in order: each rule's `describeInTurn`, or its `describe` for a rule without one.
+
 A rule whose verdict depends on the input, such as one that holds only a `delete` action, can also answer `mayHold(tool)`: whether it may hold some call of that tool.
 It is asked when the input is not known yet, as for a [precheck script](#precheck-scripts-prechecks-the-agent-writes)'s call whose arguments are computed when it runs; a rule without it is judged by `describe` with an empty input.
 A rule whose held call stands for others can answer `approvalTier(tool, input, context)`: the lowest tier that may approve it when higher than the tool's own. The held call keeps it as `minTier`, and both its card and a confirming message require it. A card is answered, and a confirming message accepted, from the speaker whose turn held the call, when their tier is at least `minTier`, and from the owners where the conversation is shared ([who answers a prompt](#who-answers-a-prompt-promptscope)); nobody else in the channel may approve it. The held call records that speaker as `PendingConfirmation.speakerId` and their principal as `principalId`, so a confirming message from another identity of theirs counts after a restart too; a call held without them is the owners' to approve, and one held before 0.9, without a principal, is matched by `speakerId`.
@@ -2893,7 +2954,7 @@ It returns:
 |---|---|
 | `contribution` | What the plugin added, as the host would collect it: `tools`, `prompt`, `seeds`, `events`, `services`, `http`, and the rest |
 | `tools`, `tiers` | The tool names, and the table that says what tier each needs |
-| `holds` | The plugin's `holdRules` chained as the host links them (`holdChain`): `holds(tool, input, { workspace?, scratchDir? })` returns the description of a call that must be approved first, or `undefined` |
+| `holds` | The plugin's `holdRules` chained as the host links them (`holdChain`): `holds(tool, input, { workspace?, scratchDir? })` returns the description of a call that must be approved first, or `undefined`; `holds.inTurn(tool, input, context, turn)` asks them as a turn does, and returns a promise when a hold looks things up |
 | `runTool(name, args, { speaker, channel, workspace }?)` | Runs a tool the way an agent's turn would, in the channel (default `test:1`) for the speaker, and returns the text the model reads; `workspace` (`{ workspace, scratchDir? }`) is the session's `turn.workspace` |
 | `files` | Accepted files from `runTool`, recorded as `{ channel, file: ReplyFile }`; inject a surface with `supportsFiles: true` and pass its channel to test attachment tools |
 | `events` | The events the plugin itself reported through `context.events`, and those of `context.turns` |
@@ -3284,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 |
@@ -3323,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 |
@@ -3606,6 +3671,7 @@ Import from the entries listed below; source area files are internal.
 | `formatModelRef` | `pi-roundtable/kit` | value |
 | `headline` | `pi-roundtable/kit` | value |
 | `holdChain` | `pi-roundtable/kit` | value |
+| `HOLD_DESCRIBE_TIMEOUT_MS` | `pi-roundtable/kit` | value |
 | `COMPACT_HEADROOM_TOKENS` | `pi-roundtable/kit` | value |
 | `CompactionTiers` | `pi-roundtable/kit` | value |
 | `compactionEngine` | `pi-roundtable/kit` | value |

package/package.json

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