pi-roundtable 0.9.0 → 0.9.2

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/contract/channels.ts

@@ -259,6 +259,11 @@ export interface QueuePort {
 	size(channel: ChannelKey): number;
 	/** Channels with a task running or waiting. */
 	busy(): ChannelKey[];
+	/**
+	 * Whether the host is shutting down: a task that has not started is then refused with
+	 * HostStoppingError, and a plugin that starts work on its own, such as a timer, starts none.
+	 */
+	readonly closed: boolean;
 	/** Called whenever a channel's count of running and waiting tasks changes. */
 	onChange(listener: (channel: ChannelKey) => void): void;
 }

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)] : []),
@@ -283,6 +284,7 @@ export async function defineRoundtable(
 			],
 			judgeModel: judgeThrough(modelRuntime, config.judge.model),
 			apiKey: (provider) => registry.getApiKeyForProvider(provider),
+			drain: { limitMs: config.drainMs },
 			...(overrides.aborted ? { aborted: overrides.aborted } : {}),
 		},
 		plugins: [

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/drain.ts

@@ -1,19 +1,32 @@
-/** How long a shutdown waits for running work before aborting it (self-maintenance spec behavior 11). */
-export const DRAIN_LIMIT_MS = 60 * 60_000;
+import type { Logger } from "./log.ts";
+
+/**
+ * How long a shutdown waits for running work before aborting it: long enough for a usual turn to
+ * answer, short enough that a hung one never holds a restart for an hour.
+ */
+export const DRAIN_LIMIT_MS = 3 * 60_000;
+
+/** How long work that was told to stop gets to end before the shutdown goes on without it. */
+const ABORT_GRACE_MS = 10_000;
 
 export interface DrainOptions {
 	/** What still runs or waits, one entry per piece of work; empty when idle. */
 	busy: () => string[];
+	/** The most the drain waits for running work; DRAIN_LIMIT_MS by default. */
 	limitMs?: number;
+	/** How often it looks again; one second by default. */
 	intervalMs?: number;
+	/** The most work told to stop at the limit gets to end; ABORT_GRACE_MS by default. */
+	abortGraceMs?: number;
 	sleep?: (ms: number) => Promise<void>;
 	now?: () => number;
 }
 
 /**
- * Waits until nothing runs or waits, checking every interval, for at most the limit. Work that
- * arrives meanwhile is served as usual and waited for too. Returns what was still busy when the
- * limit ran out, or an empty list once idle.
+ * Waits until nothing runs or waits, checking every interval, for at most the limit. Returns what
+ * was still busy when the limit ran out, or an empty list once idle. It only waits: the host stops
+ * work from starting before it calls this, and a caller that does not must expect work that
+ * arrives meanwhile to be waited for too.
  */
 export async function waitUntilIdle(options: DrainOptions): Promise<string[]> {
 	const {
@@ -31,3 +44,41 @@ export async function waitUntilIdle(options: DrainOptions): Promise<string[]> {
 		await sleep(intervalMs);
 	}
 }
+
+/**
+ * Waits for running work up to the limit; if some is left, tells it to stop (`abort` says whether
+ * it told any) and gives it the abort grace to end. Returns what the limit ran out on, even when stopping it worked, so the
+ * caller can hand it over as cut short.
+ */
+export async function drainWork(
+	options: DrainOptions & { abort: (left: string[]) => boolean },
+): Promise<string[]> {
+	const { abort, abortGraceMs = ABORT_GRACE_MS, ...waiting } = options;
+	const left = await waitUntilIdle(waiting);
+	if (left.length === 0) return left;
+	// Work nothing could be told to stop would only be waited for in vain.
+	if (abort(left)) await waitUntilIdle({ ...waiting, limitMs: abortGraceMs });
+	return left;
+}
+
+/**
+ * Tells each channel's running turn to stop, as the owner's stop does; a failure is logged and the
+ * rest are still told. Whether any turn was running to be told.
+ */
+export function stopTurns(
+	channels: readonly string[],
+	stop: (channel: string) => boolean,
+	logger: Logger,
+): boolean {
+	let stopped = false;
+	for (const channel of new Set(channels)) {
+		try {
+			const told = stop(channel);
+			logger.warn({ channel, told }, "stopping the turn");
+			stopped ||= told;
+		} catch (error) {
+			logger.error({ channel, err: error }, "the turn could not be stopped");
+		}
+	}
+	return stopped;
+}

package/src/core/errors.ts

@@ -27,3 +27,16 @@ export class JudgeError extends Error {
 export class ProviderError extends Error {
 	override name = "ProviderError";
 }
+
+/**
+ * Work refused because the host is shutting down: once the drain starts, no turn, queue task, or
+ * background run starts any more, and what was waiting behind a running one is dropped.
+ */
+export class HostStoppingError extends Error {
+	override name = "HostStoppingError";
+	constructor() {
+		super(
+			"the host is shutting down and starts no new work; try again once it is back",
+		);
+	}
+}

package/src/core/host-background.ts

@@ -0,0 +1,56 @@
+import type { Logger } from "./log.ts";
+import type { ServiceStartedEvent } from "./plugin.ts";
+import type { Registry } from "./registry/contributions.ts";
+
+type Attempt = { ok: true } | { ok: false; error: unknown };
+
+/** Runs one step whose failure the caller reports and moves past. */
+export async function attempt(
+	step: () => Promise<void> | void,
+): Promise<Attempt> {
+	try {
+		await step();
+		return { ok: true };
+	} catch (error) {
+		return { ok: false, error };
+	}
+}
+
+/**
+ * Runs every service's background start at once and tells every plugin, as each ends, how it
+ * went; the rest of the process runs either way, and a failing start or handler never stops the
+ * others.
+ */
+export async function startInBackground(
+	registry: Registry,
+	logger: Logger,
+): Promise<void> {
+	const { services, servicePlugins, handlers } = registry;
+	await Promise.all(
+		// pi-lens-ignore: array-callback-return — an async callback returns its promise on every path; map only starts the tasks for Promise.all, and the early return skips a service with no background start
+		services.map(async (service) => {
+			if (!service.startInBackground) return;
+			const plugin = servicePlugins.get(service) ?? "unknown";
+			const started = await attempt(() => service.startInBackground?.());
+			if (started.ok) logger.info({ plugin, service: service.name }, "ready");
+			else
+				logger.error(
+					{ plugin, service: service.name, err: started.error },
+					"service did not start in the background",
+				);
+			const event: ServiceStartedEvent = {
+				plugin,
+				service: service.name,
+				outcome: started.ok ? "ready" : "failed",
+			};
+			for (const { plugin: heard, events } of handlers) {
+				const handled = await attempt(() => events.serviceStarted?.(event));
+				if (!handled.ok)
+					logger.error(
+						{ plugin: heard, err: handled.error },
+						"service started handler failed",
+					);
+			}
+		}),
+	);
+}

package/src/core/host.ts

@@ -1,10 +1,12 @@
 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";
-import { type DrainOptions, waitUntilIdle } from "./drain.ts";
+import { type DrainOptions, drainWork, stopTurns } from "./drain.ts";
 import { MigrationError, NotLinkedError, PluginError } from "./errors.ts";
 import { EventBus } from "./events.ts";
+import { attempt, startInBackground } from "./host-background.ts";
 import { HttpListeners, type ListenerConfig } from "./http/listeners.ts";
 import { type Locale, setLocale } from "./i18n/index.ts";
 import { contactsOf } from "./identity/identity-view.ts";
@@ -15,7 +17,6 @@ import type {
 	LinkedSessions,
 	RoundtablePlugin,
 	Service,
-	ServiceStartedEvent,
 } from "./plugin.ts";
 import { refuseRemovedFields } from "./plugin.ts";
 import {
@@ -34,6 +35,7 @@ import {
 } from "./routing/conversation-turns.ts";
 import { surfacePort } from "./routing/surface-port.ts";
 import { CONVERSATIONS, IDENTITY, RUNTIME } from "./services.ts";
+import type { ChannelKey } from "./sessions.ts";
 import { setTimeZone } from "./time.ts";
 import { type ToolTierTable, toolTiers } from "./tool-tiers.ts";
 
@@ -76,9 +78,15 @@ 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>;
-	/** The drain's limit and clock; tests shorten them. */
+	/**
+	 * The shutdown drain: it waits up to `limitMs` (3 minutes by default) for the turns already
+	 * running, then stops them, gives them `abortGraceMs` (10 seconds) to end, and goes on without
+	 * them. Nothing new starts once it begins. Tests shorten the limits and the clock.
+	 */
 	drain?: Omit<DrainOptions, "busy">;
 	/** What `listen()` calls with the shutdown's exit code; the process's own exit by default. */
 	exit?: (code: number) => void;
@@ -87,63 +95,13 @@ export interface RoundtableOptions {
 /** The host running in this process; the text catalog, time zone and environment are process-wide. */
 let running: Roundtable | undefined;
 
-type Attempt = { ok: true } | { ok: false; error: unknown };
-
-/** Runs one step whose failure the caller reports and moves past. */
-async function attempt(step: () => Promise<void> | void): Promise<Attempt> {
-	try {
-		await step();
-		return { ok: true };
-	} catch (error) {
-		return { ok: false, error };
-	}
-}
-
-/**
- * Runs every service's background start at once and tells every plugin, as each ends, how it
- * went; the rest of the process runs either way, and a failing start or handler never stops the
- * others.
- */
-async function startInBackground(
-	registry: Registry,
-	logger: Logger,
-): Promise<void> {
-	const { services, servicePlugins, handlers } = registry;
-	await Promise.all(
-		// pi-lens-ignore: array-callback-return — an async callback returns its promise on every path; map only starts the tasks for Promise.all, and the early return skips a service with no background start
-		services.map(async (service) => {
-			if (!service.startInBackground) return;
-			const plugin = servicePlugins.get(service) ?? "unknown";
-			const started = await attempt(() => service.startInBackground?.());
-			if (started.ok) logger.info({ plugin, service: service.name }, "ready");
-			else
-				logger.error(
-					{ plugin, service: service.name, err: started.error },
-					"service did not start in the background",
-				);
-			const event: ServiceStartedEvent = {
-				plugin,
-				service: service.name,
-				outcome: started.ok ? "ready" : "failed",
-			};
-			for (const { plugin: heard, events } of handlers) {
-				const handled = await attempt(() => events.serviceStarted?.(event));
-				if (!handled.ok)
-					logger.error(
-						{ plugin: heard, err: handled.error },
-						"service started handler failed",
-					);
-			}
-		}),
-	);
-}
-
 /**
  * The process around the plugins: it sets them all up, links what they add (session parts,
  * HTTP routes) and runs the preflight, then starts their services in order and the
  * HTTP listeners last, then runs the services' background starts. Nothing reaches Discord or a listener unless
- * every setup, link, and the preflight succeeded. On shutdown it waits until no work runs or
- * waits before closing the listeners and stopping the services in reverse.
+ * every setup, link, and the preflight succeeded. On shutdown it starts no new work, waits for
+ * what runs for at most the drain limit, then closes the listeners and stops the services in
+ * reverse.
  */
 // pi-lens-ignore: large-class
 export class Roundtable {
@@ -243,6 +201,7 @@ export class Roundtable {
 			registry: () => this.#services?.find(CONVERSATIONS),
 			surfaces: this.#surfaces(),
 			events: this.#events.sink,
+			stopping: () => this.#queue.closed,
 			selection: () => {
 				if (!this.#sessions)
 					throw new NotLinkedError("session parts are not linked yet.");
@@ -320,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: () => {
@@ -423,7 +387,8 @@ export class Roundtable {
 	}
 
 	/**
-	 * Stops the host once no work runs or waits and returns the exit code: 0, or 1 when the
+	 * Stops the host once no work runs or waits, or the drain limit has passed, and returns the
+	 * exit code: 0, or 1 when the
 	 * boot had failed or a listener, service or the pool did not stop. Every call shares the one
 	 * shutdown.
 	 */
@@ -437,19 +402,27 @@ export class Roundtable {
 		// A signal during the boot waits for it to settle; a failed boot has already stopped.
 		await this.#booting?.catch(() => undefined);
 		if (running !== this) return this.#bootFailed ? 1 : 0;
-		// Everything keeps serving until nothing runs or waits, so a deploy never cuts a turn short.
+		// Turns already running finish, but nothing new starts from here on, whoever asks.
 		logger.info({ signal }, "shutting down once idle");
-		const left = await waitUntilIdle({
+		this.#queue.close();
+		const left = await drainWork({
 			...drain,
 			busy: () => [
 				...this.#queue.busy(),
 				...this.#started.flatMap((service) => service.busy?.() ?? []),
 			],
+			// A turn the limit finds still running is stopped, as the owner's stop would.
+			abort: () =>
+				stopTurns(
+					this.#queue.busy(),
+					(channel) => this.#router?.stop(channel as ChannelKey) ?? false,
+					logger,
+				),
 		});
 		if (left.length > 0) {
 			logger.warn(
 				{ aborted: left },
-				"still busy after the drain limit; aborting",
+				"still busy after the drain limit; aborted",
 			);
 			const recorded = await attempt(() => aborted?.(left));
 			if (!recorded.ok)

package/src/core/i18n/conversation.ts

@@ -6,6 +6,7 @@ export function conversationEn(ctx: CatalogContext) {
 		failureNotice:
 			"Sorry, this reply did not go through. Please try again later.",
 		stoppedNotice: "-# Stopped.",
+		restartingNotice: `-# ${ctx.assistant} is restarting and takes no new messages right now; please send this again in a few minutes.`,
 		roundLimitNotice:
 			"-# This round already has 8 replies, so it stops here; call us again if you need more.",
 		restartNotice: `-# ${ctx.assistant} restarted before this job finished, so nothing more will be reported here.`,
@@ -30,6 +31,7 @@ export function conversationZhTW(
 	return {
 		failureNotice: "抱歉，這次沒能完成回覆，請稍後再試一次。",
 		stoppedNotice: "-# 已停止。",
+		restartingNotice: `-# ${ctx.assistant} 正在重新啟動，暫時不接新訊息；請過幾分鐘再傳一次。`,
 		roundLimitNotice:
 			"-# 這一輪已經有 8 則回覆，先停在這裡；需要的話請再叫我們。",
 		restartNotice: `-# ${ctx.assistant} 在這項工作結束前重新啟動了，這裡不會再有回報。`,

package/src/core/modules/schedules/scheduler.ts

@@ -49,6 +49,12 @@ export interface SchedulerOptions {
 	holds?: () => HoldCheck;
 	/** Posts a skipping precheck's note in the schedule's channel as the bot's own message, which starts no turn. */
 	notify?: (schedule: Schedule, note: string) => Promise<void>;
+	/**
+	 * Whether the host is shutting down. A due schedule is then left unclaimed, so it stays due and
+	 * fires after the next start, if it is not too late by then (LATE_LIMIT_MS), instead of being
+	 * moved on to its next run and its turn refused.
+	 */
+	draining?: () => boolean;
 	logger: Logger;
 	intervalMs?: number;
 	/** Replaceable in tests. */
@@ -119,15 +125,20 @@ export class Scheduler {
 		await this.#prechecks.drain(PRECHECK_STOP_MS);
 	}
 
+	#draining(): boolean {
+		return this.#options.draining?.() ?? false;
+	}
+
 	/** Claims every due schedule and starts its run; runs continue after tick resolves. */
 	async tick(): Promise<void> {
-		if (this.#ticking || this.#stopping.signal.aborted) return;
+		if (this.#ticking || this.#stopping.signal.aborted || this.#draining())
+			return;
 		this.#ticking = true;
 		const { store, logger } = this.#options;
 		try {
 			const now = this.#options.now?.() ?? new Date();
 			for (const schedule of await store.due(now)) {
-				if (this.#stopping.signal.aborted) break;
+				if (this.#stopping.signal.aborted || this.#draining()) break;
 				const claimed = await store.claim(
 					schedule,
 					nextRun(schedule.recurrence, now),

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/routing/channel-queue.ts

@@ -1,3 +1,4 @@
+import { HostStoppingError } from "../errors.ts";
 import type { ChannelKey } from "../sessions.ts";
 
 /** Runs tasks one at a time per channel, in arrival order; different channels run independently. */
@@ -5,6 +6,7 @@ export class ChannelQueue {
 	readonly #tails = new Map<ChannelKey, Promise<unknown>>();
 	readonly #sizes = new Map<ChannelKey, number>();
 	readonly #listeners: ((channel: ChannelKey) => void)[] = [];
+	#closed = false;
 
 	/** Called whenever a channel's count of running and waiting tasks changes. */
 	onChange(listener: (channel: ChannelKey) => void): void {
@@ -15,11 +17,26 @@ export class ChannelQueue {
 		for (const listener of this.#listeners) listener(channel);
 	}
 
+	/** Whether the host is shutting down, so no task starts any more. */
+	get closed(): boolean {
+		return this.#closed;
+	}
+
+	/**
+	 * Starts the shutdown: from now on a task that has not started, whether queued before or after
+	 * this call, is refused with HostStoppingError. A running task finishes.
+	 */
+	close(): void {
+		this.#closed = true;
+	}
+
 	run<T>(channel: ChannelKey, task: () => Promise<T>): Promise<T> {
+		const start = () =>
+			this.#closed ? Promise.reject(new HostStoppingError()) : task();
 		this.#sizes.set(channel, this.size(channel) + 1);
 		this.#changed(channel);
 		const previous = this.#tails.get(channel) ?? Promise.resolve();
-		const result = previous.then(task, task);
+		const result = previous.then(start, start);
 		const tail = result.catch(() => undefined);
 		this.#tails.set(channel, tail);
 		void tail.then(() => {