pi-roundtable 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -5,6 +5,13 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-10-10
+
+### Added
+
+- `context.attachments` (`AttachmentPort`, with `AttachmentUpload`, `AttachmentRefusal` and `AttachmentRefusalCode`): a plugin keeps a file a person uploaded outside a turn until a turn uses it. `save` stages the file for its principal in a conversation, `turnAttachments` turns the named files into the turn's `TurnAttachments` (they move into the conversation's attachment directory, so `read_attachment` and the `## Attachments` block see them, and up to four images reach the model), `remove` and `discardPending` drop files no turn used, and `pendingBytes` counts what a principal has waiting. A staged file is usable only by the principal that saved it, in the conversation it was saved for; a conversation recorded private refuses every other principal (`AttachmentRefusal` with code `forbidden`). It needs the host's `dataDir`, a new `RoundtableOptions` field that `defineRoundtable` sets, and throws a `PluginError` without it.
+- `ToolTurn.attachment(file)` (`ToolAttachment`): a tool opens a file attached to the conversation, by the name in the turn's `## Attachments` block, and reads its bytes with `bytes()` or passes it on. A path or a hidden name is refused with a `ToolRefusal`. `SessionContext.attachmentDir` names the directory it reads.
+
 ## [0.9.1] - 2026-10-10
 
 ### Fixed

package/docs/plugins.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.9.1",
+	"version": "0.9.2",
 	"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-port.ts

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

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

@@ -0,0 +1,248 @@
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { readdir, rename, rm, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import {
+	type AttachmentPort,
+	AttachmentRefusal,
+	type AttachmentUpload,
+} from "../contract/attachments.ts";
+import type { ConversationRegistry } from "../conversations/conversation-registry.ts";
+import type {
+	StoredAttachment,
+	TurnAttachments,
+} from "../domain/attachment.ts";
+import type { Logger } from "../log.ts";
+import type { ChannelKey } from "../sessions.ts";
+import { channelSegment, ownerAttachmentDir } from "./attachment-dir.ts";
+import { MAX_ATTACHMENT_BYTES, safeFileName } from "./attachment-fetcher.ts";
+import { modelImagesOf } from "./model-images.ts";
+
+/** Where saved files wait, beside the conversations' attachment directories. */
+const STAGING = "attachments-pending";
+/** The record of a saved file, in a directory next to it that no file name can be. */
+export const RECORDS = ".records";
+
+export interface AttachmentStoreOptions {
+	dataDir: string;
+	/** Read when used, once the host linked its services; undefined when no registry records conversations. */
+	registry(): Pick<ConversationRegistry, "get"> | undefined;
+	logger: Logger;
+}
+
+interface StagedRecord {
+	name: string;
+	contentType: string;
+}
+
+const isRecord = (value: unknown): value is StagedRecord =>
+	typeof value === "object" &&
+	value !== null &&
+	typeof (value as StagedRecord).name === "string" &&
+	typeof (value as StagedRecord).contentType === "string";
+
+/** A principal id as one path segment; hashed, so two ids never share a directory. */
+function principalSegment(principalId: string): string {
+	return createHash("sha256").update(principalId).digest("hex").slice(0, 32);
+}
+
+/** Whether `file` could be a name this store gave out: one path segment that is not hidden. */
+function isFileName(file: string): boolean {
+	return (
+		file !== "" &&
+		basename(file) === file &&
+		!file.startsWith(".") &&
+		!file.includes("\0")
+	);
+}
+
+async function listDir(dir: string): Promise<string[]> {
+	try {
+		return await readdir(dir);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+/**
+ * The files plugins take from people outside a turn. A saved file is staged under its principal and
+ * its conversation until a turn uses it, then moved into the conversation's attachment directory,
+ * the one `read_attachment` reads. The conversation's record decides who may stage: a private
+ * conversation takes only its principal's files.
+ */
+export class AttachmentStore implements AttachmentPort {
+	readonly #options: AttachmentStoreOptions;
+
+	constructor(options: AttachmentStoreOptions) {
+		this.#options = options;
+	}
+
+	#stagingDir(channel: ChannelKey, principalId: string): string {
+		return join(
+			this.#options.dataDir,
+			STAGING,
+			principalSegment(principalId),
+			channelSegment(channel),
+		);
+	}
+
+	/** Refuses a principal other than the one a private conversation belongs to. */
+	async #admit(channel: ChannelKey, principalId: string): Promise<void> {
+		const record = await this.#options.registry()?.get(channel);
+		if (record?.visibility === "private" && record.principalId !== principalId)
+			throw new AttachmentRefusal(
+				"forbidden",
+				`${channel} is private to someone else, so its files cannot be saved or used by ${principalId}`,
+			);
+	}
+
+	async save(
+		channel: ChannelKey,
+		principalId: string,
+		upload: AttachmentUpload,
+	): Promise<StoredAttachment> {
+		await this.#admit(channel, principalId);
+		const size = upload.data.byteLength;
+		if (size > MAX_ATTACHMENT_BYTES)
+			throw new AttachmentRefusal(
+				"too_large",
+				`a file may be at most 25 MiB; "${upload.name}" is ${size} bytes`,
+			);
+		const dir = this.#stagingDir(channel, principalId);
+		mkdirSync(join(dir, RECORDS), { recursive: true, mode: 0o700 });
+		const file = `${crypto.randomUUID()}-${safeFileName(upload.name)}`;
+		const path = join(dir, file);
+		await Bun.write(path, upload.data);
+		const record: StagedRecord = {
+			name: upload.name,
+			contentType: upload.contentType,
+		};
+		await Bun.write(join(dir, RECORDS, `${file}.json`), JSON.stringify(record));
+		return {
+			name: upload.name,
+			file,
+			path,
+			contentType: upload.contentType,
+			size,
+			fromReference: false,
+		};
+	}
+
+	async turnAttachments(
+		channel: ChannelKey,
+		principalId: string,
+		files: readonly string[],
+	): Promise<TurnAttachments> {
+		await this.#admit(channel, principalId);
+		const staging = this.#stagingDir(channel, principalId);
+		const target = ownerAttachmentDir(this.#options.dataDir, channel);
+		const found: StoredAttachment[] = [];
+		for (const file of new Set(files)) {
+			const record = await this.#recordOf(staging, file);
+			if (!record)
+				throw new AttachmentRefusal(
+					"unknown_file",
+					`no saved file "${file}" is waiting for this person in ${channel}`,
+				);
+			const from = join(staging, file);
+			found.push({
+				name: record.name,
+				file,
+				path: join(target, file),
+				contentType: record.contentType,
+				size: (await stat(from)).size,
+				fromReference: false,
+			});
+		}
+		mkdirSync(join(target, RECORDS), { recursive: true, mode: 0o700 });
+		for (const stored of found) {
+			try {
+				await rename(join(staging, stored.file), stored.path);
+			} catch (error) {
+				// Another turn used the file between the check and the move.
+				if ((error as NodeJS.ErrnoException).code === "ENOENT")
+					throw new AttachmentRefusal(
+						"unknown_file",
+						`the saved file "${stored.file}" was used already`,
+					);
+				throw error;
+			}
+			await rename(
+				join(staging, RECORDS, `${stored.file}.json`),
+				join(target, RECORDS, `${stored.file}.json`),
+			);
+		}
+		const { images, failures } = await modelImagesOf(
+			found,
+			this.#options.logger,
+		);
+		return { files: found, images, failures };
+	}
+
+	async remove(
+		channel: ChannelKey,
+		principalId: string,
+		file: string,
+	): Promise<boolean> {
+		await this.#admit(channel, principalId);
+		const staging = this.#stagingDir(channel, principalId);
+		if (!(await this.#recordOf(staging, file))) return false;
+		await rm(join(staging, file), { force: true });
+		await rm(join(staging, RECORDS, `${file}.json`), { force: true });
+		return true;
+	}
+
+	async discardPending(olderThan: Date): Promise<number> {
+		const root = join(this.#options.dataDir, STAGING);
+		let discarded = 0;
+		for (const principal of await listDir(root)) {
+			for (const channel of await listDir(join(root, principal))) {
+				const dir = join(root, principal, channel);
+				for (const entry of await listDir(dir)) {
+					if (entry === RECORDS) continue;
+					const info = await stat(join(dir, entry)).catch(() => undefined);
+					if (!info || info.mtimeMs >= olderThan.getTime()) continue;
+					await rm(join(dir, entry), { force: true });
+					await rm(join(dir, RECORDS, `${entry}.json`), { force: true });
+					discarded += 1;
+				}
+			}
+		}
+		return discarded;
+	}
+
+	async pendingBytes(principalId: string): Promise<number> {
+		const root = join(
+			this.#options.dataDir,
+			STAGING,
+			principalSegment(principalId),
+		);
+		let total = 0;
+		for (const channel of await listDir(root)) {
+			const dir = join(root, channel);
+			for (const entry of await listDir(dir)) {
+				if (entry === RECORDS) continue;
+				total +=
+					(await stat(join(dir, entry)).catch(() => undefined))?.size ?? 0;
+			}
+		}
+		return total;
+	}
+
+	/** The record of a staged file, or undefined when it is not staged here. */
+	async #recordOf(
+		staging: string,
+		file: string,
+	): Promise<StagedRecord | undefined> {
+		if (!isFileName(file)) return undefined;
+		const stored = Bun.file(join(staging, RECORDS, `${file}.json`));
+		if (
+			!(await stored.exists()) ||
+			!(await Bun.file(join(staging, file)).exists())
+		)
+			return undefined;
+		const value: unknown = await stored.json();
+		return isRecord(value) ? value : undefined;
+	}
+}

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

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

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

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

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

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

package/src/core/contract/attachments.ts

@@ -0,0 +1,71 @@
+import type {
+	StoredAttachment,
+	TurnAttachments,
+} from "../domain/attachment.ts";
+import type { ChannelKey } from "../sessions.ts";
+
+/** A file a plugin hands the core to keep for a conversation. */
+export interface AttachmentUpload {
+	/** The name the person gave it; shown to the model and kept as is. */
+	name: string;
+	contentType: string;
+	data: Uint8Array;
+}
+
+/** Why the attachment store refused a call. */
+export type AttachmentRefusalCode =
+	/** The conversation is private to someone else. */
+	| "forbidden"
+	/** No saved file of that name is waiting for this person in this conversation. */
+	| "unknown_file"
+	/** The file is over the core's limit of 25 MiB. */
+	| "too_large";
+
+/** An attachment call the store refused; `code` says why, and the plugin decides what its client sees. */
+export class AttachmentRefusal extends Error {
+	override name = "AttachmentRefusal";
+	readonly code: AttachmentRefusalCode;
+
+	constructor(code: AttachmentRefusalCode, message: string) {
+		super(message);
+		this.code = code;
+	}
+}
+
+/**
+ * Files a plugin takes from a person outside a turn, such as an upload over HTTP, kept for the
+ * conversation until a turn uses them. A saved file waits for its person: only the principal that
+ * saved it may use it, in the conversation it was saved for. A private conversation refuses every
+ * other principal; a shared one lets each use their own. Using a file moves it into the
+ * conversation's attachment directory, where the turn's `read_attachment` and
+ * `ToolTurn.attachment()` find it. Calls reject with `AttachmentRefusal` for a refused call, and
+ * throw a PluginError when the host has no `dataDir`.
+ */
+export interface AttachmentPort {
+	/** Keeps a file for the principal in the conversation until a turn uses it. */
+	save(
+		channel: ChannelKey,
+		principalId: string,
+		upload: AttachmentUpload,
+	): Promise<StoredAttachment>;
+	/**
+	 * The turn's attachments for files `save` returned: each moves into the conversation, up to four
+	 * images are prepared for the model, and every file is named in the turn's `## Attachments`
+	 * block. Refuses the whole set when one file is unknown or already used; none moves then.
+	 */
+	turnAttachments(
+		channel: ChannelKey,
+		principalId: string,
+		files: readonly string[],
+	): Promise<TurnAttachments>;
+	/** Discards a saved file no turn used; false when there is none. */
+	remove(
+		channel: ChannelKey,
+		principalId: string,
+		file: string,
+	): Promise<boolean>;
+	/** Discards every saved file no turn used that was saved before `olderThan`; returns how many. */
+	discardPending(olderThan: Date): Promise<number>;
+	/** The bytes the principal has saved that no turn used yet, across their conversations. */
+	pendingBytes(principalId: string): Promise<number>;
+}

package/src/core/define-roundtable.ts

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

package/src/core/define.ts

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

package/src/core/host.ts

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

package/src/core/plugin.ts

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

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

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

package/src/core/sessions.ts

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

package/src/index.ts

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

package/src/testing.ts

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