pi-roundtable 0.9.2 → 0.9.5

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

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
 import { mkdirSync } from "node:fs";
-import { readdir, rename, rm, stat } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import {
 	type AttachmentPort,
 	AttachmentRefusal,
 	type AttachmentUpload,
+	type TurnAttachmentOptions,
 } from "../contract/attachments.ts";
 import type { ConversationRegistry } from "../conversations/conversation-registry.ts";
 import type {
@@ -14,12 +15,18 @@ import type {
 } from "../domain/attachment.ts";
 import type { Logger } from "../log.ts";
 import type { ChannelKey } from "../sessions.ts";
-import { channelSegment, ownerAttachmentDir } from "./attachment-dir.ts";
+import {
+	channelSegment,
+	listDir,
+	ownerAttachmentDir,
+	removeIfEmpty,
+	STAGING,
+	USAGE,
+} from "./attachment-dir.ts";
 import { MAX_ATTACHMENT_BYTES, safeFileName } from "./attachment-fetcher.ts";
+import { isAttachmentName } from "./attachment-name.ts";
 import { modelImagesOf } from "./model-images.ts";
 
-/** Where saved files wait, beside the conversations' attachment directories. */
-const STAGING = "attachments-pending";
 /** The record of a saved file, in a directory next to it that no file name can be. */
 export const RECORDS = ".records";
 
@@ -46,23 +53,28 @@ function principalSegment(principalId: string): string {
 	return createHash("sha256").update(principalId).digest("hex").slice(0, 32);
 }
 
-/** Whether `file` could be a name this store gave out: one path segment that is not hidden. */
-function isFileName(file: string): boolean {
-	return (
-		file !== "" &&
-		basename(file) === file &&
-		!file.startsWith(".") &&
-		!file.includes("\0")
-	);
+/** The bytes of a tally file; none when it is missing or unreadable as a number. */
+async function readTally(path: string): Promise<number> {
+	try {
+		const value = Number(await readFile(path, "utf8"));
+		return Number.isFinite(value) && value > 0 ? value : 0;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0;
+		throw error;
+	}
 }
 
-async function listDir(dir: string): Promise<string[]> {
+/** Writes a tally whole or not at all, creating its directory if a conversation's deletion removed it meanwhile. */
+async function writeTally(path: string, bytes: number): Promise<void> {
+	const temporary = `${path}.tmp`;
 	try {
-		return await readdir(dir);
+		await writeFile(temporary, String(bytes));
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-		throw error;
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+		await writeFile(temporary, String(bytes));
 	}
+	await rename(temporary, path);
 }
 
 /**
@@ -70,14 +82,34 @@ async function listDir(dir: string): Promise<string[]> {
  * its conversation until a turn uses it, then moved into the conversation's attachment directory,
  * the one `read_attachment` reads. The conversation's record decides who may stage: a private
  * conversation takes only its principal's files.
+ *
+ * Calls that change one principal's files run one after another, so two messages of one person
+ * never see each other half done; the tally of the bytes a principal used per conversation lives
+ * beside the staging directories.
  */
 export class AttachmentStore implements AttachmentPort {
 	readonly #options: AttachmentStoreOptions;
+	/** The last call queued for each principal, which the next one waits for. */
+	readonly #tails = new Map<string, Promise<void>>();
 
 	constructor(options: AttachmentStoreOptions) {
 		this.#options = options;
 	}
 
+	/** Runs `run` after the principal's earlier calls, whether they succeeded or not. */
+	#exclusive<T>(principal: string, run: () => Promise<T>): Promise<T> {
+		const result = (this.#tails.get(principal) ?? Promise.resolve()).then(run);
+		const tail = result.then(
+			() => undefined,
+			() => undefined,
+		);
+		this.#tails.set(principal, tail);
+		void tail.then(() => {
+			if (this.#tails.get(principal) === tail) this.#tails.delete(principal);
+		});
+		return result;
+	}
+
 	#stagingDir(channel: ChannelKey, principalId: string): string {
 		return join(
 			this.#options.dataDir,
@@ -87,6 +119,10 @@ export class AttachmentStore implements AttachmentPort {
 		);
 	}
 
+	#tallyDir(principalId: string): string {
+		return join(this.#options.dataDir, USAGE, principalSegment(principalId));
+	}
+
 	/** Refuses a principal other than the one a private conversation belongs to. */
 	async #admit(channel: ChannelKey, principalId: string): Promise<void> {
 		const record = await this.#options.registry()?.get(channel);
@@ -110,15 +146,25 @@ export class AttachmentStore implements AttachmentPort {
 				`a file may be at most 25 MiB; "${upload.name}" is ${size} bytes`,
 			);
 		const dir = this.#stagingDir(channel, principalId);
-		mkdirSync(join(dir, RECORDS), { recursive: true, mode: 0o700 });
 		const file = `${crypto.randomUUID()}-${safeFileName(upload.name)}`;
 		const path = join(dir, file);
-		await Bun.write(path, upload.data);
+		const recordPath = join(dir, RECORDS, `${file}.json`);
 		const record: StagedRecord = {
 			name: upload.name,
 			contentType: upload.contentType,
 		};
-		await Bun.write(join(dir, RECORDS, `${file}.json`), JSON.stringify(record));
+		await this.#exclusive(principalSegment(principalId), async () => {
+			mkdirSync(join(dir, RECORDS), { recursive: true, mode: 0o700 });
+			try {
+				await Bun.write(path, upload.data);
+				await Bun.write(recordPath, JSON.stringify(record));
+			} catch (error) {
+				// A file without its record could never be used or removed, yet would count as waiting.
+				await rm(path, { force: true });
+				await rm(recordPath, { force: true });
+				throw error;
+			}
+		});
 		return {
 			name: upload.name,
 			file,
@@ -133,8 +179,26 @@ export class AttachmentStore implements AttachmentPort {
 		channel: ChannelKey,
 		principalId: string,
 		files: readonly string[],
+		options: TurnAttachmentOptions = {},
 	): Promise<TurnAttachments> {
 		await this.#admit(channel, principalId);
+		const found = await this.#exclusive(principalSegment(principalId), () =>
+			this.#claim(channel, principalId, files, options),
+		);
+		const { images, failures } = await modelImagesOf(
+			found,
+			this.#options.logger,
+		);
+		return { files: found, images, failures };
+	}
+
+	/** Checks every file, then moves them all into the conversation, or none when any step fails. */
+	async #claim(
+		channel: ChannelKey,
+		principalId: string,
+		files: readonly string[],
+		options: TurnAttachmentOptions,
+	): Promise<StoredAttachment[]> {
 		const staging = this.#stagingDir(channel, principalId);
 		const target = ownerAttachmentDir(this.#options.dataDir, channel);
 		const found: StoredAttachment[] = [];
@@ -145,39 +209,70 @@ export class AttachmentStore implements AttachmentPort {
 					"unknown_file",
 					`no saved file "${file}" is waiting for this person in ${channel}`,
 				);
-			const from = join(staging, file);
 			found.push({
 				name: record.name,
 				file,
 				path: join(target, file),
 				contentType: record.contentType,
-				size: (await stat(from)).size,
+				size: (await stat(join(staging, file))).size,
 				fromReference: false,
 			});
 		}
+		const added = found.reduce((sum, stored) => sum + stored.size, 0);
+		const tally = join(this.#tallyDir(principalId), channelSegment(channel));
+		const before = await readTally(tally);
+		if (options.usedBytesLimit !== undefined) {
+			const used = await this.#usedBytes(principalId);
+			if (used + added > options.usedBytesLimit)
+				throw new AttachmentRefusal(
+					"quota_exceeded",
+					`the files already used in turns hold ${used} bytes, and ${added} more would pass the limit of ${options.usedBytesLimit} bytes`,
+				);
+		}
 		mkdirSync(join(target, RECORDS), { recursive: true, mode: 0o700 });
-		for (const stored of found) {
-			try {
+		mkdirSync(this.#tallyDir(principalId), { recursive: true, mode: 0o700 });
+		const moved: StoredAttachment[] = [];
+		try {
+			for (const stored of found) {
 				await rename(join(staging, stored.file), stored.path);
-			} catch (error) {
-				// Another turn used the file between the check and the move.
-				if ((error as NodeJS.ErrnoException).code === "ENOENT")
-					throw new AttachmentRefusal(
-						"unknown_file",
-						`the saved file "${stored.file}" was used already`,
-					);
-				throw error;
+				moved.push(stored);
+				await rename(
+					join(staging, RECORDS, `${stored.file}.json`),
+					join(target, RECORDS, `${stored.file}.json`),
+				);
 			}
+			await writeTally(tally, before + added);
+		} catch (error) {
+			await this.#putBack(moved, staging, target, tally, before);
+			// Something else took the file between the check and the move.
+			if ((error as NodeJS.ErrnoException).code === "ENOENT")
+				throw new AttachmentRefusal(
+					"unknown_file",
+					"a saved file was used or discarded while the message was taken",
+				);
+			throw error;
+		}
+		return found;
+	}
+
+	/** Undoes a partial move: the files return to staging and the tally to what it was. */
+	async #putBack(
+		moved: readonly StoredAttachment[],
+		staging: string,
+		target: string,
+		tally: string,
+		before: number,
+	): Promise<void> {
+		for (const stored of moved) {
+			await rename(stored.path, join(staging, stored.file)).catch(
+				() => undefined,
+			);
 			await rename(
-				join(staging, RECORDS, `${stored.file}.json`),
 				join(target, RECORDS, `${stored.file}.json`),
-			);
+				join(staging, RECORDS, `${stored.file}.json`),
+			).catch(() => undefined);
 		}
-		const { images, failures } = await modelImagesOf(
-			found,
-			this.#options.logger,
-		);
-		return { files: found, images, failures };
+		await writeTally(tally, before).catch(() => undefined);
 	}
 
 	async remove(
@@ -187,27 +282,37 @@ export class AttachmentStore implements AttachmentPort {
 	): Promise<boolean> {
 		await this.#admit(channel, principalId);
 		const staging = this.#stagingDir(channel, principalId);
-		if (!(await this.#recordOf(staging, file))) return false;
-		await rm(join(staging, file), { force: true });
-		await rm(join(staging, RECORDS, `${file}.json`), { force: true });
-		return true;
+		return this.#exclusive(principalSegment(principalId), async () => {
+			if (!(await this.#recordOf(staging, file))) return false;
+			await rm(join(staging, file), { force: true });
+			await rm(join(staging, RECORDS, `${file}.json`), { force: true });
+			return true;
+		});
 	}
 
 	async discardPending(olderThan: Date): Promise<number> {
 		const root = join(this.#options.dataDir, STAGING);
 		let discarded = 0;
 		for (const principal of await listDir(root)) {
-			for (const channel of await listDir(join(root, principal))) {
-				const dir = join(root, principal, channel);
-				for (const entry of await listDir(dir)) {
-					if (entry === RECORDS) continue;
-					const info = await stat(join(dir, entry)).catch(() => undefined);
-					if (!info || info.mtimeMs >= olderThan.getTime()) continue;
-					await rm(join(dir, entry), { force: true });
-					await rm(join(dir, RECORDS, `${entry}.json`), { force: true });
-					discarded += 1;
+			discarded += await this.#exclusive(principal, async () => {
+				let count = 0;
+				for (const channel of await listDir(join(root, principal))) {
+					const dir = join(root, principal, channel);
+					for (const entry of await listDir(dir)) {
+						if (entry === RECORDS) continue;
+						const info = await stat(join(dir, entry)).catch(() => undefined);
+						if (!info || info.mtimeMs >= olderThan.getTime()) continue;
+						await rm(join(dir, entry), { force: true });
+						await rm(join(dir, RECORDS, `${entry}.json`), { force: true });
+						count += 1;
+					}
+					// A conversation with nothing waiting keeps no directory.
+					await removeIfEmpty(join(dir, RECORDS));
+					await removeIfEmpty(dir);
 				}
-			}
+				await removeIfEmpty(join(root, principal));
+				return count;
+			});
 		}
 		return discarded;
 	}
@@ -230,12 +335,22 @@ export class AttachmentStore implements AttachmentPort {
 		return total;
 	}
 
+	/** The bytes the principal's turns used, across their conversations. */
+	async #usedBytes(principalId: string): Promise<number> {
+		const dir = this.#tallyDir(principalId);
+		let total = 0;
+		for (const channel of await listDir(dir))
+			if (!channel.endsWith(".tmp"))
+				total += await readTally(join(dir, channel));
+		return total;
+	}
+
 	/** The record of a staged file, or undefined when it is not staged here. */
 	async #recordOf(
 		staging: string,
 		file: string,
 	): Promise<StagedRecord | undefined> {
-		if (!isFileName(file)) return undefined;
+		if (!isAttachmentName(file)) return undefined;
 		const stored = Bun.file(join(staging, RECORDS, `${file}.json`));
 		if (
 			!(await stored.exists()) ||

package/src/core/attachments/prompt-block.ts

@@ -1,4 +1,8 @@
 import type { TurnAttachments } from "../domain/attachment.ts";
+import { plainContentType, plainText } from "./attachment-name.ts";
+
+/** A name a prompt can quote: no control or bidi characters, and no quote to close it early. */
+const quotable = (name: string): string => plainText(name).replaceAll('"', "'");
 
 function formatSize(bytes: number): string {
 	if (bytes < 1024) return `${bytes} B`;
@@ -19,13 +23,13 @@ export function withAttachmentsBlock(
 	for (const file of attachments.files) {
 		const origin = file.fromReference ? ", from the replied-to message" : "";
 		lines.push(
-			`- ${file.file} (original name "${file.name}", ${file.contentType}, ${formatSize(file.size)}${origin})`,
+			`- ${plainText(file.file)} (original name "${quotable(file.name)}", ${plainContentType(file.contentType)}, ${formatSize(file.size)}${origin})`,
 		);
 	}
 	for (const failure of attachments.failures) {
 		const origin = failure.fromReference ? " from the replied-to message" : "";
 		lines.push(
-			`- "${failure.name}"${origin} could not be received: ${failure.reason}`,
+			`- "${quotable(failure.name)}"${origin} could not be received: ${failure.reason}`,
 		);
 	}
 	if (lines.length === 0) return text;

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

@@ -1,4 +1,5 @@
-import { basename, join } from "node:path";
+import { join } from "node:path";
+import { isAttachmentName, plainText } from "./attachment-name.ts";
 import { RECORDS } from "./attachment-store.ts";
 
 /** A file someone attached to the conversation, as a tool reads it. */
@@ -31,12 +32,13 @@ export async function openAttachment(
 	dir: string,
 	file: string,
 ): Promise<ToolAttachment> {
-	if (file === "" || basename(file) !== file || file.startsWith("."))
-		throw new AttachmentLookupError(`"${file}" is not an attachment name`);
+	const shown = plainText(file);
+	if (!isAttachmentName(file))
+		throw new AttachmentLookupError(`"${shown}" is not an attachment name`);
 	const handle = Bun.file(join(dir, file));
 	if (!(await handle.exists()))
 		throw new AttachmentLookupError(
-			`no attachment named "${file}" in this channel`,
+			`no attachment named "${shown}" in this channel`,
 		);
 	const record = Bun.file(join(dir, RECORDS, `${file}.json`));
 	const recorded: Recorded = (await record.exists()) ? await record.json() : {};
@@ -48,6 +50,13 @@ export async function openAttachment(
 				? recorded.contentType
 				: handle.type,
 		size: handle.size,
-		bytes: async () => new Uint8Array(await handle.arrayBuffer()),
+		// A file system error names the path on the host; the model sees only the attachment's name.
+		bytes: async () => {
+			try {
+				return new Uint8Array(await handle.arrayBuffer());
+			} catch {
+				throw new AttachmentLookupError(`"${shown}" could not be read`);
+			}
+		},
 	};
 }

package/src/core/builtin/discord-admin.ts

@@ -30,8 +30,12 @@ export function discordAdminPlugin(
 			const { connection } = services.get(DISCORD);
 			return {
 				sessionTools: [
-					fixed("discord-admin", () =>
-						discordAdminExtension(connection.ownerOperations(), owner),
+					fixed("discord-admin", (session) =>
+						discordAdminExtension(
+							connection.ownerOperations(),
+							owner,
+							session.workspace,
+						),
 					),
 				],
 				// Administering the server stays with the owner until an operator lowers a tool.

package/src/core/builtin/discord.ts

@@ -67,6 +67,11 @@ export interface DiscordOptions {
 	channelContext?: ChannelContextOptions | false;
 	/** The divider posted in a server channel when its conversation starts over; `false` posts none. Default: a short English divider. */
 	freshMarker?: string | false;
+	/**
+	 * How long a turn waits on its owner card before it goes on without the answer, leaving the
+	 * card open; a later answer starts a new turn. Default `CARD_GRACE_MS`, two minutes.
+	 */
+	cardGraceMs?: number;
 }
 
 /**
@@ -96,6 +101,10 @@ export function discordPlugin(options: DiscordOptions): RoundtablePlugin {
 				...(identity ? { identity } : {}),
 				channel: (channelId) => connected.cardChannel(channelId),
 				logger,
+				...(options.cardGraceMs === undefined
+					? {}
+					: { graceMs: options.cardGraceMs }),
+				resume: (turn) => connected.resume(turn),
 			});
 			const connected = new DiscordSurface({
 				token: options.token,
@@ -124,6 +133,7 @@ export function discordPlugin(options: DiscordOptions): RoundtablePlugin {
 					open: (parentId, name, line) =>
 						connected.threadHost().open(parentId, name, line),
 					post: (threadId, text) => connected.threadHost().post(threadId, text),
+					send: (threadId, text) => connected.threadHost().send(threadId, text),
 					close: (threadId) => connected.threadHost().close(threadId),
 				},
 				ledgerPath: join(options.dataDir, "dispatch-threads.json"),

package/src/core/config/adapters.ts

@@ -50,6 +50,52 @@ export interface DiscordConfig {
 	 * never in a direct message. Default `─── new conversation ───`; `false` posts none.
 	 */
 	freshMarker?: string | false;
+	/**
+	 * Seconds a turn waits on an owner card (an approval or an `ask_user` question) before it goes
+	 * on without the answer; the card stays open, and answering it later starts a new turn with
+	 * the answer. Default 120.
+	 */
+	cardGraceSeconds?: number;
+}
+
+/** The Discord settings with every default filled in. */
+export interface ResolvedDiscord {
+	token: string;
+	guild: string;
+	entryChannel: string;
+	rootCommand: string;
+	admin: boolean;
+	refusalHint?: string;
+	agentMemory?: "everyone" | "owners";
+	/** As configured: `{}` when left out, so the defaults apply, or `false`. */
+	channelContext: NonNullable<DiscordConfig["channelContext"]>;
+	freshMarker?: string | false;
+	cardGraceSeconds: number;
+}
+
+/** The configured Discord settings, defaults filled in; `rootCommand` is the host's slug. */
+export function resolvedDiscord(
+	discord: DiscordConfig,
+	rootCommand: string,
+): ResolvedDiscord {
+	return {
+		token: discord.token,
+		guild: discord.guild,
+		entryChannel: discord.entryChannel,
+		rootCommand,
+		admin: discord.admin ?? true,
+		...(discord.refusalHint === undefined
+			? {}
+			: { refusalHint: discord.refusalHint }),
+		...(discord.agentMemory === undefined
+			? {}
+			: { agentMemory: discord.agentMemory }),
+		channelContext: discord.channelContext ?? {},
+		...(discord.freshMarker === undefined
+			? {}
+			: { freshMarker: discord.freshMarker }),
+		cardGraceSeconds: discord.cardGraceSeconds ?? 120,
+	};
 }
 
 /** What `discord.channelContext` takes besides `false`. */
@@ -72,6 +118,7 @@ export const discordShape = shape({
 	agentMemory: optional(oneOf<"everyone" | "owners">("everyone", "owners")),
 	channelContext: optional(orOff(channelContextShape)),
 	freshMarker: optional(orOff(text)),
+	cardGraceSeconds: optional(integer(1, 86_400)),
 });
 
 /** The adapters `adapters` takes, by the name their factory gives them. */

package/src/core/config/config.ts

@@ -19,7 +19,13 @@ import { PRIMARY_CHARS } from "../runtime/interim-text.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { Tier, TierMembers } from "../speakers.ts";
 import { type AccessConfig, accessOf, accessShape } from "./access.ts";
-import { type DiscordConfig, discordShape, liftAdapters } from "./adapters.ts";
+import {
+	type DiscordConfig,
+	discordShape,
+	liftAdapters,
+	type ResolvedDiscord,
+	resolvedDiscord,
+} from "./adapters.ts";
 import {
 	bool,
 	guarded,
@@ -297,18 +303,7 @@ export interface ResolvedConfig {
 	/** What the configuration wrote in a deprecated form, which the host logs once. */
 	deprecations: string[];
 	/** Undefined on a host without Discord. */
-	discord?: {
-		token: string;
-		guild: string;
-		entryChannel: string;
-		rootCommand: string;
-		admin: boolean;
-		refusalHint?: string;
-		agentMemory?: "everyone" | "owners";
-		/** As configured: `{}` when left out, so the defaults apply, or `false`. */
-		channelContext: NonNullable<DiscordConfig["channelContext"]>;
-		freshMarker?: string | false;
-	};
+	discord?: ResolvedDiscord;
 	databaseUrl: string;
 	dataDir: string;
 	agentDir: string;
@@ -423,27 +418,7 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 			name: primaryOwner.name,
 			pronouns: primaryOwner.pronouns,
 		},
-		...(discord
-			? {
-					discord: {
-						token: discord.token,
-						guild: discord.guild,
-						entryChannel: discord.entryChannel,
-						rootCommand: slug,
-						admin: discord.admin ?? true,
-						...(discord.refusalHint === undefined
-							? {}
-							: { refusalHint: discord.refusalHint }),
-						...(discord.agentMemory === undefined
-							? {}
-							: { agentMemory: discord.agentMemory }),
-						channelContext: discord.channelContext ?? {},
-						...(discord.freshMarker === undefined
-							? {}
-							: { freshMarker: discord.freshMarker }),
-					},
-				}
-			: {}),
+		...(discord ? { discord: resolvedDiscord(discord, slug) } : {}),
 		databaseUrl: config.database.url,
 		dataDir: config.dataDir,
 		agentDir: config.agentDir ?? `${config.dataDir}/pi`,

package/src/core/contract/attachments.ts

@@ -19,7 +19,9 @@ export type AttachmentRefusalCode =
 	/** No saved file of that name is waiting for this person in this conversation. */
 	| "unknown_file"
 	/** The file is over the core's limit of 25 MiB. */
-	| "too_large";
+	| "too_large"
+	/** Using the files would take the principal past the `usedBytesLimit` the plugin passed. */
+	| "quota_exceeded";
 
 /** An attachment call the store refused; `code` says why, and the plugin decides what its client sees. */
 export class AttachmentRefusal extends Error {
@@ -32,6 +34,16 @@ export class AttachmentRefusal extends Error {
 	}
 }
 
+/** What a plugin asks of `turnAttachments` besides the files. */
+export interface TurnAttachmentOptions {
+	/**
+	 * The most bytes the principal may have used in turns across all their conversations, these
+	 * files included. A call that would pass it is refused with `quota_exceeded` and moves nothing.
+	 * Without it the core sets no limit; deleting a conversation gives its bytes back.
+	 */
+	usedBytesLimit?: number;
+}
+
 /**
  * Files a plugin takes from a person outside a turn, such as an upload over HTTP, kept for the
  * conversation until a turn uses them. A saved file waits for its person: only the principal that
@@ -40,6 +52,13 @@ export class AttachmentRefusal extends Error {
  * conversation's attachment directory, where the turn's `read_attachment` and
  * `ToolTurn.attachment()` find it. Calls reject with `AttachmentRefusal` for a refused call, and
  * throw a PluginError when the host has no `dataDir`.
+ *
+ * Who may use a channel is the plugin's to check, not the port's. The port refuses another
+ * principal only in a conversation the host's registry records as private to someone else; for a
+ * channel the registry does not know, or when the host has no registry, it admits every principal.
+ * A plugin whose channel key comes from a person must first check that the channel is that
+ * person's, as the web chat does before every call; the plugin that owns a channel checks it,
+ * because only that plugin knows what the channel is.
  */
 export interface AttachmentPort {
 	/** Keeps a file for the principal in the conversation until a turn uses it. */
@@ -51,12 +70,14 @@ export interface AttachmentPort {
 	/**
 	 * The turn's attachments for files `save` returned: each moves into the conversation, up to four
 	 * images are prepared for the model, and every file is named in the turn's `## Attachments`
-	 * block. Refuses the whole set when one file is unknown or already used; none moves then.
+	 * block. Refuses the whole set when one file is unknown or already used, or when
+	 * `options.usedBytesLimit` would be passed; none moves then, however many calls run at once.
 	 */
 	turnAttachments(
 		channel: ChannelKey,
 		principalId: string,
 		files: readonly string[],
+		options?: TurnAttachmentOptions,
 	): Promise<TurnAttachments>;
 	/** Discards a saved file no turn used; false when there is none. */
 	remove(

package/src/core/define-roundtable.ts

@@ -172,6 +172,7 @@ function discordAssembly(
 			...(discord.freshMarker === undefined
 				? {}
 				: { freshMarker: discord.freshMarker }),
+			cardGraceMs: discord.cardGraceSeconds * 1_000,
 		}),
 		admin: discord.admin ? [discordAdminPlugin({ owner })] : [],
 		skills: config.skills
@@ -274,6 +275,7 @@ export async function defineRoundtable(
 				assistant: name,
 				rootCommand: config.slug,
 				agentDir: config.agentDir,
+				scratchDir: config.scratchDir,
 			},
 			database: { url: config.databaseUrl },
 			dataDir: config.dataDir,

package/src/core/define.ts

@@ -29,6 +29,11 @@ export interface ToolTurn {
 	/** The agent whose turn it is. */
 	agent: AgentTurnScope | undefined;
 	signal: AbortSignal | undefined;
+	/**
+	 * 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.
+	 */
+	workspace?: { workspace: string; scratchDir?: string };
 	/** Queues a file for this turn's successful reply; throws ReplyFileError when refused. */
 	attachFile(file: ReplyFile): void;
 	/**
@@ -124,6 +129,9 @@ export function defineTool<Schema extends TObject>(
 									channel: context.turnChannel,
 									agent: context.agent,
 									signal,
+									...(context.workspace
+										? { workspace: context.workspace }
+										: {}),
 									attachFile: attachReplyFile,
 									attachment: async (file) => {
 										if (context.attachmentDir === undefined)