pi-roundtable 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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
+
+- A SIGTERM no longer lets the host keep taking work until it was idle: in 0.9.0 the shutdown drain only waited, so messages, error and webhook reports, schedules, and plugin turns that arrived meanwhile were served and waited for too, and a host that kept getting them never became idle until the one-hour limit (a deploy waited for systemd to kill it). The drain now starts by closing the channel queue: no new turn starts from any source. A message that arrives is not run and its channel gets one short restarting notice (not for a bot's or an integration's message, which is only logged), including a message that waited behind a running turn, and a message is no longer steered into a running turn; a background turn (a schedule's, a delegated task's report, an error report) is skipped; `context.turns.run`, a task for `context.queue.run` that has not started, and a group's next member's turn are refused (`HostStoppingError`, new in `pi-roundtable`), and so are new worker tasks; a remote MCP run fails instead of starting. The scheduler claims nothing during the drain, so a due schedule stays due and fires after the next start if it is less than twelve hours late. Turns already running finish.
+- The drain is bounded by three minutes by default instead of an hour: `drainSeconds` in the config, or `drain.limitMs` in `RoundtableOptions`. At the limit the host stops each running turn as the owner's stop does, gives it `drain.abortGraceMs` (ten seconds by default) to end, hands what is left to `aborted`, and goes on to stop the services and exit. Give the service manager a stop timeout a minute longer than the drain, such as systemd's `TimeoutStopSec=5min`.
+- A turn or worker task whose model ignores the abort (a claude-bridge subprocess that stays alive after "turn timed out; aborting") no longer holds its channel, and the drain, for ever: a run still going `turnAbortGraceMs` (15 seconds by default, `PiAgentRuntimeOptions`) after its abort has its session disposed of and ends as failed, and the conversation's next turn opens a new session from its files. An owner's stop of such a turn is guarded the same way.
+
+### Added
+
+- `QueuePort.closed` (`context.queue.closed`): whether the host is shutting down, for a plugin that starts work from its own timer or route.
+- The `drainSeconds` configuration key.
+
 ## [0.9.0] - 2026-10-09
 
 Principal and identity attribution replace implicit owner authority.

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 -->
@@ -898,7 +923,7 @@ test("the handlers record a turn, a team change, and the shutdown", async () =>
 
 A service has a name and optional `start`, `stop`, and `busy`.
 Services start once everything is set up and stop in reverse order.
-`busy` lists the work still running, one entry each; a shutdown waits until every service's list is empty, for at most an hour, so a deploy rarely cuts work short.
+`busy` lists the work still running, one entry each; a shutdown waits until every service's list is empty, for at most the drain limit (three minutes by default, `drainSeconds` in the config), so a deploy rarely cuts work short.
 The host adds its own channel queue to that wait, so a surface that queues its turns through `context.queue` needs no `busy` for them.
 
 A service may also have `startInBackground`.
@@ -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
 
@@ -2791,7 +2818,7 @@ The copied file begins with this warning.
 `release-notice` listens to two [events](#events-hear-what-the-core-does).
 When the agent server's team service reports `ready`, it reads the release file and posts if the release's `sha` differs from the one it last announced (`announced-release` in the data directory), or if the previous shutdown cut work short.
 It records the announced `sha` only after the post succeeds, so a failed post is tried again at the next start, and a `release.json` that is not valid (not JSON, an empty `sha`, or `commits` that is not a list of strings) fails the handler with its path in the log.
-At `shutdown(left)` it adds the channels in `left`, the work the drain gave up on after an hour, to `aborted-on-shutdown.json` in the data directory; the next start's announcement names them as cut short (a Discord channel key as a `<#id>` mention), and once it is posted they are removed from the file. A shutdown that arrives while a post is still in flight keeps its channels for the next announcement.
+At `shutdown(left)` it adds the channels in `left`, the work the drain gave up on at its limit, to `aborted-on-shutdown.json` in the data directory; the next start's announcement names them as cut short (a Discord channel key as a `<#id>` mention), and once it is posted they are removed from the file. A shutdown that arrives while a post is still in flight keeps its channels for the next announcement.
 A plain restart of the same release with nothing cut short posts nothing.
 
 The deploy writes `release.json` into the release directory, where the bot runs, before it starts the bot.
@@ -2999,16 +3026,19 @@ If a startup step fails, the host stops its listeners, stops services in reverse
 The process exits non-zero.
 The same host may call `run()` again after that.
 
-On `SIGTERM` or `SIGINT` the bot stops serving new work last:
+On `SIGTERM` or `SIGINT` the bot takes no new work at once, finishes what runs, and stops serving last:
 
-1. It keeps serving until the channel queue is empty and no service reports `busy()` work, for at most an hour; whatever is left is logged and given up on.
-2. Every plugin hears `shutdown(left)`, while every service is still running.
-3. The HTTP listener closes, so no request reaches a service that has stopped.
-4. Services stop in the reverse of the order they started.
-5. The database pool closes.
+1. It stops starting work: the channel queue closes (`context.queue.closed` turns true), and from then on no new turn starts, whoever asks. A message that arrives is not run; its channel gets one short "restarting, try again shortly" reply, except a bot's or an integration's message, which is only logged. A background turn (a schedule's, a delegated task's report, an error report) is skipped, and so is a turn a plugin asks of `context.turns.run`, which rejects with `HostStoppingError`; a task for the queue that has not started, whether queued before or after, is refused with the same error. The scheduler claims nothing, so a due schedule stays due and fires after the next start if it is less than twelve hours late. A turn that is already running finishes. A plugin that starts turns from a timer or a route of its own should check `context.queue.closed` first.
+2. It waits until the channel queue is empty and no service reports `busy()` work, for at most three minutes (`drainSeconds` in the config, `drain.limitMs` in `RoundtableOptions`). If work is left, it stops each running turn as the owner's stop does, gives them ten seconds (`drain.abortGraceMs`) to end, and goes on; whatever is left is logged and given up on.
+3. Every plugin hears `shutdown(left)`, while every service is still running.
+4. The HTTP listener closes, so no request reaches a service that has stopped.
+5. Services stop in the reverse of the order they started.
+6. The database pool closes.
 
 `shutdown()` returns exit code `0`, or `1` if a listener, service, or pool failed to stop.
 Every call shares the same shutdown.
+Give the service manager a stop timeout longer than the drain limit plus about a minute for the steps after it, such as systemd's `TimeoutStopSec=5min` with the default three-minute drain; a shorter one has the manager kill the process in the middle of the drain.
+A turn whose model ignores its abort (a subprocess that does not exit) is given up on too: a turn that outlives its timeout, or is stopped, gets `turnAbortGraceMs` (15 seconds by default) to end, and then its session is disposed of and the turn is reported failed, so it cannot hold the queue.
 `listen()`, called by the command line and a host's own entry point, exits the process with that code.
 
 ## Errors and their fixes
@@ -3216,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 |
@@ -3263,6 +3297,7 @@ Import from the entries listed below; source area files are internal.
 | `HoldRule` | `pi-roundtable` | type |
 | `HostEnv` | `pi-roundtable` | type |
 | `HostEnvironment` | `pi-roundtable` | type |
+| `HostStoppingError` | `pi-roundtable` | value |
 | `HttpRoute` | `pi-roundtable` | type |
 | `IDENTITY` | `pi-roundtable` | value |
 | `IdentityError` | `pi-roundtable` | value |
@@ -3384,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.0",
+	"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/builtin/modules.ts

@@ -331,7 +331,15 @@ export function modulesPlugin(options: ModulesOptions): RoundtablePlugin {
 export function schedulerPlugin(): RoundtablePlugin {
 	return {
 		name: "schedules",
-		setup: ({ conversations, services, env, logger, surfaces, sessions }) => {
+		setup: ({
+			conversations,
+			services,
+			env,
+			logger,
+			surfaces,
+			sessions,
+			queue,
+		}) => {
 			const schedules = services.get(SCHEDULES);
 			const prechecks = services.find(PRECHECKS);
 			const scheduler = new Scheduler({
@@ -339,6 +347,7 @@ export function schedulerPlugin(): RoundtablePlugin {
 				runner: services.get(BACKGROUND_TURNS),
 				...(prechecks ? { prechecks } : {}),
 				holds: () => sessions().holds,
+				draining: () => queue.closed,
 				// The bot's own message: the surface drops it, so it starts no turn.
 				notify: (schedule, note) =>
 					surfaces.sendReply(schedule.channel, {

package/src/core/config/config.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import type { AgentSeed } from "../agents/agent-rules.ts";
 import { ConfigError } from "../domain/errors.ts";
 import type { InterimTextMode } from "../domain/interim.ts";
+import { DRAIN_LIMIT_MS } from "../drain.ts";
 import { isLocale, type Locale } from "../i18n/index.ts";
 import type { AccessRules } from "../identity/access-policy.ts";
 import type { OwnerIdentity } from "../identity.ts";
@@ -164,6 +165,11 @@ export interface RoundtableConfig {
 	 * conversation or no plugin's claim owns it; the web chat takes no error reports.
 	 */
 	ops?: { agent: string } | { conversation: string };
+	/**
+	 * Seconds a shutdown waits for running turns before stopping them; default 180. Give the
+	 * service manager a stop timeout a minute longer, such as systemd's `TimeoutStopSec`.
+	 */
+	drainSeconds?: number;
 	/**
 	 * Whether a turn posts the text it writes before its final answer as it goes: long or
 	 * structured text as ordinary messages, short narration and the tools called in one small
@@ -261,6 +267,7 @@ const schema = shape({
 	),
 	memory: optional(bool),
 	ops: optional(shape({ agent: optional(text), conversation: optional(text) })),
+	drainSeconds: optional(integer(1, 3_600)),
 	interimText: optional(oneOf<InterimTextMode>("on", "off")),
 	interimPrimaryChars: optional(integer(1, 100_000)),
 	plugins: optional(
@@ -334,6 +341,7 @@ export interface ResolvedConfig {
 	skills: false | { builtinDir?: string; reposDir?: string };
 	memory: boolean;
 	ops?: { agent: string } | { conversation: ChannelKey };
+	drainMs: number;
 	interimText: InterimTextMode;
 	interimPrimaryChars: number;
 	plugins: RoundtablePlugin[];
@@ -483,6 +491,7 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 		skills: config.skills ?? (discord ? {} : false),
 		memory: config.memory ?? true,
 		...(ops ? { ops } : {}),
+		drainMs: (config.drainSeconds ?? DRAIN_LIMIT_MS / 1_000) * 1_000,
 		interimText: config.interimText ?? "on",
 		interimPrimaryChars: config.interimPrimaryChars ?? PRIMARY_CHARS,
 		plugins: config.plugins ?? [],