pi-roundtable 0.9.8 → 0.9.10

package/CHANGELOG.md

@@ -5,6 +5,24 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.10] - 2026-10-10
+
+### Added
+
+- `ToolTurn.origin`, `TurnRequest.origin`, `ConversationTurnInput.origin` and `SessionContext.origin()`: where a turn's request came from, as the transport that carried it reported it, such as the browser origin of a web chat connection (`https://chat.example.com`). A tool's `run` and its `hold` read it from the `ToolTurn` they receive, so a tool can label what it creates (an issue's source line) and fail closed when it is undefined. A claim passes it to `context.turns.run({ ..., origin })`; the runtime keeps it with the turn's speaker and clears it when the turn ends. Only the transport sets it, never the message text or the model. A turn whose channel gives none (Discord, a schedule, an agent's turn, the CLI) leaves it undefined, and `testPlugin().runTool` takes `origin` in its options. Additive: nothing changes for a claim or a tool that does not use it, and `SessionContext.origin` is optional on the type so a context built before this still type-checks.
+
+## [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,14 +555,46 @@ 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.
 `run` receives the arguments, already typed, and the turn: the speaker, the channel, the agent, an abort signal, `workspace`, `attachFile`, and `attachment`.
 `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.origin` is where the turn's request came from, as the transport that carried it reported it, and undefined when the channel gives none: the web chat sets it to the browser origin its connection opened with (`https://chat.example.com`, `chrome-extension://<id>`), a Discord message, a schedule or an agent's turn leave it undefined.
+Only a channel's transport sets it, never the message text or the model, so a tool may write it on a record it creates, such as an issue's source line; a tool that needs it fails closed when it is undefined.
+A claim passes it to `context.turns.run` as `origin`, and the hold of the same call sees it too, since `hold` receives the same `ToolTurn`.
+
 `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 -->
@@ -717,7 +750,7 @@ export const cleanup = definePlugin({
 #### 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.
+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`, the `agent` and the `origin` of the turn that makes the call.
 
 ```ts
 defineTool({
@@ -1832,6 +1865,7 @@ The factory gets the session's `SessionContext`, fixed when the session is made:
 - `addressee` is whom tool descriptions should name: the primary owner exactly as configured in their own private conversation, another person by their name and pronouns (their name alone when they gave none), and `THE_SPEAKER` in a shared conversation, or a private one of someone the host knows by no name yet.
 - `memory` is `"none"` for a persona that declares it, and `"speaker"` otherwise; a memory tool of your own loads nothing for `"none"`. A task the session runs with `runTask` keeps its conversation's `memory`.
 - `speaker()` is the running turn's speaker, undefined between turns; a tool reads it when it runs, never when the session is made, since a session outlives the turn it is built in.
+- `origin()` is where the running turn's request came from, as `TurnRequest.origin` says, and undefined between turns and for a turn whose transport gives none; read it when the tool runs, like `speaker()`. It is optional on the type so a context built before 0.9.10 still type-checks.
 
 The core's Jev compactor is one such extension:
 
@@ -1983,7 +2017,7 @@ Call `context.turns.run(input)` inside your claim's queue task to run a turn in
 It shows typing and the stop control on the channel's surface, runs the turn, and emits `turnStarted` and `turnEnded` with the turn's `kind`.
 It catches runtime errors as failed results and posts the answer, failure notice, or stopped notice through the surface.
 Supply `reply(result)` to handle the reply yourself.
-`input` has `channel`, `kind`, `text`, `speaker`, and optionally `attachments`, `selection` (by default the plugins' `agentSelection`), `steerable`, `interactive`, `confirmed`, `reply`, and `conversation`.
+`input` has `channel`, `kind`, `text`, `speaker`, and optionally `origin` (where the request came from, as your claim's transport knows it, such as a connection's browser origin; tools read it as `turn.origin`, so never fill it from message text), `attachments`, `selection` (by default the plugins' `agentSelection`), `steerable`, `interactive`, `confirmed`, `reply`, and `conversation`.
 It rejects with `NotLinkedError` during `setup`, and with a `PluginError` on a host whose runtime plugin has not provided a runtime.
 
 Before each turn runs, `context.turns.run` records its conversation in the host's registry, `CONVERSATIONS`: at the first turn its key, surface, kind, visibility, owner, and title, and at every later turn only that it was active.
@@ -2926,7 +2960,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.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` |
+| `runTool(name, args, { speaker, origin, 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; `origin` is the turn's `turn.origin`, and `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` |
 | `conversations`, `turns`, `surfaces` | What the plugin sees as `context.conversations`, `context.turns`, and `context.surfaces`, for a test to drive its claims |
@@ -3316,7 +3350,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 +3391,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.10",
 	"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/define.ts

@@ -26,6 +26,14 @@ export interface ToolTurn {
 	/** The agent whose turn it is. */
 	agent: AgentTurnScope | undefined;
 	signal: AbortSignal | undefined;
+	/**
+	 * Where the turn's request came from, as its transport reported it, such as the browser origin
+	 * of a web chat connection (`https://chat.example.com`); undefined for a turn whose channel gives
+	 * none, such as a Discord message or a schedule. Only the transport sets it, never the message
+	 * text or the model, so a tool may label a record with it; a tool that needs one fails closed
+	 * when it is undefined.
+	 */
+	origin?: string;
 	/**
 	 * The session's shared workspace and scratch dir, where a tool may save a file for the model to
 	 * pass on by path; undefined for a session without a workspace.

package/src/core/domain/ports.ts

@@ -30,6 +30,13 @@ export interface TurnRequest {
 	 * starts a turn on someone's behalf gets theirs from `IDENTITY.speakerFor`.
 	 */
 	speaker: Speaker;
+	/**
+	 * Where the request came from, as the transport that carried it knows: the browser origin of a
+	 * web chat connection, such as `https://chat.example.com`. A channel with no such thing leaves it
+	 * out. Only a channel's transport sets it, never the message text or the model; a tool reads it
+	 * as `ToolTurn.origin`.
+	 */
+	origin?: string;
 	/**
 	 * Who the conversation belongs to, as the host records it: `private` to one principal, or
 	 * `shared` by whoever its claim admits, which it is taken to be when absent. A private

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/routing/conversation-turns.ts

@@ -29,6 +29,12 @@ export interface ConversationTurnInput {
 	text: string;
 	/** Who the turn is for; its tier limits the tools. */
 	speaker: Speaker;
+	/**
+	 * Where the request came from, as the claim's transport knows it, such as a web chat
+	 * connection's browser origin; tools read it as `ToolTurn.origin`. Leave it out for a turn the
+	 * transport gives none, and never fill it from message text.
+	 */
+	origin?: string;
 	/** Files and images the message carries. */
 	attachments?: TurnAttachments;
 	/** The turn's tools; by default the plugins' `agentSelection`, read at the turn. */
@@ -184,6 +190,7 @@ export function conversationTurns(
 								},
 								text: input.text,
 								speaker,
+								...(input.origin === undefined ? {} : { origin: input.origin }),
 								...(conversation ? { conversation } : {}),
 								...(input.attachments
 									? { attachments: input.attachments }

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

@@ -71,10 +71,10 @@ export class PiAgentRuntime implements AgentRuntime {
 	readonly #tiers: ToolTiers;
 	readonly #factory: SessionFactory;
 	readonly #sessions: ConversationSessions;
-	/** The tier and speaker of each conversation's running turn. */
+	/** The tier, speaker and origin of each conversation's running turn. */
 	readonly #turns = new Map<
 		ChannelKey,
-		{ tier: Tier; speaker: Speaker; withheld: boolean }
+		{ tier: Tier; speaker: Speaker; origin?: string; withheld: boolean }
 	>();
 	/** Each conversation's turn in progress, which the owner may steer or stop. */
 	readonly #running = new Map<ChannelKey, SteerableRun>();
@@ -87,6 +87,7 @@ export class PiAgentRuntime implements AgentRuntime {
 		this.#tiers = options.toolTiers ?? toolTiers();
 		this.#factory = new SessionFactory(options, {
 			speaker: (channel) => this.#turns.get(channel)?.speaker,
+			origin: (channel) => this.#turns.get(channel)?.origin,
 			withholdsMemory: (channel) => this.#turns.get(channel)?.withheld === true,
 			runTask: (scope, task) => this.#runTask(scope, task),
 		});
@@ -192,7 +193,12 @@ export class PiAgentRuntime implements AgentRuntime {
 				loadsMemory(registered),
 		);
 		this.#memoryTurns.set(key, markPrivateMemory);
-		this.#turns.set(key, { tier, speaker: request.speaker, withheld });
+		this.#turns.set(key, {
+			tier,
+			speaker: request.speaker,
+			...(request.origin === undefined ? {} : { origin: request.origin }),
+			withheld,
+		});
 		const missing = wanted.filter((name) => !registered.has(name));
 		if (missing.length > 0) {
 			logger.warn(

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

@@ -73,6 +73,8 @@ import {
 export interface SessionFactoryDeps {
 	/** The person the conversation's running turn is for. */
 	speaker(channel: ChannelKey): Speaker | undefined;
+	/** Where the conversation's running turn came from, as its transport reported it. */
+	origin(channel: ChannelKey): string | undefined;
 	/** Whether the conversation's running turn loads no memory, as the agent server's option keeps a speaker out of it. */
 	withholdsMemory(channel: ChannelKey): boolean;
 	/**
@@ -355,6 +357,7 @@ export class SessionFactory {
 				return state.memory;
 			},
 			speaker: () => this.#deps.speaker(turnKey),
+			origin: () => this.#deps.origin(turnKey),
 			runTask: (task) =>
 				this.#deps.runTask({ turn: turnKey, home: channel }, task),
 		};

package/src/core/sessions.ts

@@ -92,6 +92,12 @@ export interface SessionContext {
 	attachmentDir?: string;
 	/** The person the session's running turn is for; undefined between turns. */
 	speaker(): Speaker | undefined;
+	/**
+	 * Where the running turn's request came from, as `TurnRequest.origin` says; undefined between
+	 * turns and for a turn whose transport gives none. A context built before 0.9.10 has no such
+	 * method, which reads as undefined.
+	 */
+	origin?(): string | undefined;
 	/** Runs a task beside this session, under its confirmation gate. */
 	runTask(task: TransientTask): Promise<string>;
 }

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/core/tool-turn.ts

@@ -15,11 +15,13 @@ export function toolTurn(
 	context: SessionContext,
 	signal: AbortSignal | undefined,
 ): ToolTurn {
+	const origin = context.origin?.();
 	return {
 		speaker: context.speaker(),
 		channel: context.turnChannel,
 		agent: context.agent,
 		signal,
+		...(origin === undefined ? {} : { origin }),
 		...(context.workspace ? { workspace: context.workspace } : {}),
 		attachFile: attachReplyFile,
 		attachment: async (file) => {

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";

package/src/testing.ts

@@ -270,6 +270,8 @@ export interface TestPluginResult {
 		/** `workspace` gives the session a workspace and scratch dir, as an agent's session has. */
 		options?: {
 			speaker?: Speaker;
+			/** Where the turn's request came from, as `ToolTurn.origin` shows it to the tool. */
+			origin?: string;
 			channel?: ChannelKey;
 			workspace?: SessionContext["workspace"];
 		},
@@ -640,6 +642,7 @@ export async function testPlugin(
 				...(runOptions?.workspace ? { workspace: runOptions.workspace } : {}),
 				attachmentDir: ownerAttachmentDir(attachmentDir, channel),
 				speaker: () => runOptions?.speaker,
+				origin: () => runOptions?.origin,
 				runTask: async () => {
 					throw new Error("test session cannot run tasks");
 				},