pi-roundtable 0.22.5 → 0.23.1

package/src/core/services.ts

@@ -1,4 +1,5 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { CharacterInput, CharacterSpec } from "../characters/index.ts";
 import type { Agent, AgentGroup } from "./agents/agent-rules.ts";
 import type { AvatarMode } from "./agents/agent-tools.ts";
 import type { TeamStatus } from "./agents/team-status.ts";
@@ -14,6 +15,7 @@ import type { HttpRoute } from "./http/listeners.ts";
 import type { IdentityLinks } from "./identity/identity-links.ts";
 import type { IdentityService } from "./identity/identity-service.ts";
 import type { ThinkingLevel, ThinkingSetting } from "./models.ts";
+import type { ConversationModes } from "./modes/conversation-modes.ts";
 import type {
 	DelegationJob,
 	DelegationOutcome,
@@ -37,6 +39,7 @@ import type {
 	SkillSet,
 } from "./modules/skills/skill-rules.ts";
 import type { AgentTurnScope, ChannelKey } from "./sessions.ts";
+import type { DispatchThreads } from "./threads/dispatch-threads.ts";
 
 // The services the built-in plugins provide, and the ports they keep to. Each port is an
 // interface, so an object with the same methods satisfies it without being one of the built-in
@@ -71,6 +74,22 @@ export const RUNTIME: ServiceKey<AgentRuntime> =
  */
 export const CONVERSATIONS: ServiceKey<ConversationRegistry> =
 	serviceKey<ConversationRegistry>("roundtable.conversations");
+/**
+ * The per-conversation modes, yolo and long-running: read a conversation's with `peek`, set them
+ * with `set` as an owner. They are stored per conversation key and survive a restart. Provided by
+ * the `modes` plugin, which every host registers.
+ */
+export const MODES: ServiceKey<ConversationModes> =
+	serviceKey<ConversationModes>("roundtable.modes");
+/**
+ * The dispatch threads of the host: a background dispatch (a coding task, a delegated task, a
+ * message between agents) opens its thread beside the channel that started it, on the surface
+ * that serves the channel, when that surface hosts threads (`ChatSurface.threads`). One instance
+ * serves every surface; `DISCORD.threads` is the same instance. Provided by the `threads` plugin,
+ * which every host registers.
+ */
+export const THREADS: ServiceKey<DispatchThreads> =
+	serviceKey<DispatchThreads>("roundtable.threads");
 /** The agent server: its team, its directory, the runtime that runs every agent turn. Provided by the agent-server plugin. */
 export const AGENTS: ServiceKey<AgentServer> =
 	serviceKey<AgentServer>("roundtable.agents");
@@ -136,17 +155,22 @@ export interface AgentServer {
 	avatars: AvatarStudio;
 }
 
-/** Agent pictures: drawn by an image provider, or made from the agent's name, kept and served by content hash. */
+/** Agent pictures: rendered from the agent's character, kept and served by content hash. */
 export interface AvatarStudio {
-	/** Whether an image provider is configured; without one, only `fallback` makes pictures. */
+	/** @deprecated Agents are no longer drawn, so this only tells whether an image provider is configured (it gates the generate_image hint); removed in 1.0. */
 	readonly canDraw: boolean;
 	/** The public URL of a picture, or of the default when there is none. */
 	url(hash: string | undefined): string;
-	/** Draws a new picture from an avatar prompt; returns its hash. */
+	/**
+	 * Renders a character as the agent's picture (512 px PNG, modern light disc, idle face), stores
+	 * it by content hash, and returns the hash; the same spec gives the same hash.
+	 */
+	render(spec: CharacterSpec): Promise<string>;
+	/** @deprecated Agents are composed characters and no longer drawn; removed in 1.0. Draws a new picture from an avatar prompt; returns its hash. */
 	draw(avatarPrompt: string): Promise<string>;
-	/** Edits a stored picture by an instruction; returns the new picture's hash. */
+	/** @deprecated Removed in 1.0. Edits a stored picture by an instruction; returns the new picture's hash. */
 	edit(hash: string | undefined, instruction: string): Promise<string>;
-	/** A picture made from an agent's display name and name, for a host without an image provider; returns its hash. */
+	/** @deprecated Removed in 1.0. A picture made from an agent's display name and name, for a host without an image provider; returns its hash. */
 	fallback(displayName: string, name: string): Promise<string>;
 	/** The pictures, public on the named listener. */
 	route(listener: string): HttpRoute;
@@ -176,21 +200,40 @@ export interface AgentChange {
 
 /** The agent team as plugins use it: who is in it, what model they run, and their channels. */
 export interface AgentTeam {
+	/** The team's id: the Discord guild, or `"local"` on a host without Discord. */
 	readonly guildId: string;
 	/** Called when a turn starts or ends and when an agent or group changes. */
 	onChange(listener: () => void): void;
 	/** Every active agent and group, with what each is doing now. */
 	status(): Promise<TeamStatus>;
-	/** The agent or group that owns a channel of the agent server. */
+	/**
+	 * The agent or group that owns a channel of the agent server: a Discord channel, or a room
+	 * (`<surface>:agent.<name>`, `<surface>:group.<name>`) on a surface that declares `agentRooms`.
+	 */
 	owns(channel: ChannelKey): "agent" | "group" | undefined;
+	/**
+	 * The name of the coordinator: the agent that answers in the entry channel, or, on a host without
+	 * Discord, the one `coordinator` names (the first seed by default); undefined while none is active.
+	 */
+	coordinator(): string | undefined;
+	/**
+	 * Every key an agent or group is addressed by: its Discord channel when it has one, then its
+	 * room on each surface with `agentRooms`; empty for an unknown name.
+	 */
+	roomsOf(name: string): ChannelKey[];
 	/** The model and thinking setting of an agent's next run: its own, or the assistant's. */
 	modelOf(name: string): { model: string; thinking: ThinkingSetting };
 	/** The assistant's model and thinking setting, which agents without their own follow. */
 	defaultModel(): { model: string; thinking: ThinkingSetting };
 	/** Models an agent can be set to: every one the host runs, `current` first when given. */
 	usableModels(current?: string): Promise<string[]>;
-	/** An active agent's channel; throws ScheduleError for an unknown agent, as the schedule tools catch it. */
-	channelOf(name: string): ChannelKey;
+	/**
+	 * An active agent's conversation, for reading its schedules: its room on the surface `near`
+	 * (the asker's own conversation) is on when that surface hosts rooms, otherwise its Discord
+	 * channel, otherwise its room on the first surface that hosts rooms. Throws ScheduleError for an
+	 * unknown agent or one with none, as the schedule tools catch it.
+	 */
+	channelOf(name: string, near?: ChannelKey): ChannelKey;
 	/** The channel the scope's turns run in: the group's in a group round, otherwise its own. */
 	turnChannel(scope: AgentTurnScope): ChannelKey;
 	/** Posts text under the caller's name in the channel of its turn. */
@@ -199,7 +242,16 @@ export interface AgentTeam {
 	announce(text: string): Promise<void>;
 	/** Changes an agent's display name, prompt, model, or thinking level; a model must be one the host runs. */
 	update(name: string, change: AgentChange): Promise<string>;
-	/** Draws and stores a new picture for an agent. */
+	/**
+	 * Changes an agent's look: `input` is resolved over its current character (a new class keeps
+	 * its colors unless the input gives a palette or colors), rendered, and stored with the new
+	 * picture. Throws AgentError naming the field of a bad input, and for an unknown or archived agent.
+	 */
+	dress(name: string, input: CharacterInput): Promise<Agent>;
+	/**
+	 * @deprecated Agents are composed characters and no longer drawn; use `dress`. Removed in 1.0.
+	 * Draws and stores a new picture for an agent; it still needs an image provider.
+	 */
 	redrawAvatar(name: string, mode: AvatarMode, text?: string): Promise<Agent>;
 }
 

package/src/core/shared/attachment-reader.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { extractText, getDocumentProxy } from "unpdf";
 import { wasExpired } from "../attachments/attachment-expiry.ts";
+import { MAX_ATTACHMENT_BYTES } from "../attachments/attachment-fetcher.ts";
 import { isAttachmentName, plainText } from "../attachments/attachment-name.ts";
 import { AttachmentExpiredError } from "../attachments/tool-attachment.ts";
 
@@ -78,6 +79,11 @@ export async function readAttachment(
 			throw new AttachmentExpiredError(plainText(file));
 		throw new Error(`no attachment named "${file}" in this channel`);
 	}
+	// A file a surface took past the default limit is for tools that take files, not for reading whole.
+	if (handle.size > MAX_ATTACHMENT_BYTES)
+		throw new Error(
+			`"${plainText(file)}" is too large to read as text (${handle.size} bytes); it is kept as a file for tools that take files.`,
+		);
 	let bytes: Uint8Array;
 	try {
 		bytes = new Uint8Array(await handle.arrayBuffer());

package/src/core/shared/unix-server.ts

@@ -6,6 +6,7 @@ import type { Server, WebSocketHandler } from "bun";
  * turns and quiet model streams. Bun 1.4.2 honors `idleTimeout` on unix sockets, but its
  * types reject the option there, hence the cast. A stale socket file is removed first.
  * `error` answers a failure raised outside the fetch handler; without it Bun's own page is sent.
+ * `maxRequestBodySize` is the most bytes of request body, 413 over it; without it Bun's default.
  */
 export function serveUnix(
 	socketPath: string,
@@ -13,7 +14,10 @@ export function serveUnix(
 		request: Request,
 		server: Server<undefined>,
 	) => Response | Promise<Response>,
-	options?: { error?: (error: Error) => Response | Promise<Response> },
+	options?: {
+		error?: (error: Error) => Response | Promise<Response>;
+		maxRequestBodySize?: number;
+	},
 ): Server<undefined>;
 /**
  * Serves HTTP and WebSockets on a unix socket: `websocket` serves the sockets `fetch` upgrades
@@ -27,6 +31,7 @@ export function serveUnix<WebSocketData>(
 	) => Response | undefined | Promise<Response | undefined>,
 	options: {
 		error?: (error: Error) => Response | Promise<Response>;
+		maxRequestBodySize?: number;
 		websocket: WebSocketHandler<WebSocketData>;
 	},
 ): Server<WebSocketData>;
@@ -38,6 +43,7 @@ export function serveUnix<WebSocketData>(
 	) => Response | undefined | Promise<Response | undefined>,
 	options: {
 		error?: (error: Error) => Response | Promise<Response>;
+		maxRequestBodySize?: number;
 		websocket?: WebSocketHandler<WebSocketData>;
 	} = {},
 ): Server<WebSocketData> {
@@ -47,6 +53,9 @@ export function serveUnix<WebSocketData>(
 		idleTimeout: 0,
 		fetch,
 		...(options.error ? { error: options.error } : {}),
+		...(options.maxRequestBodySize === undefined
+			? {}
+			: { maxRequestBodySize: options.maxRequestBodySize }),
 		...(options.websocket ? { websocket: options.websocket } : {}),
 	};
 	// SAFETY: these are Bun's unix-socket options; only `idleTimeout` is missing from its types.

package/src/core/testing/modules.ts

@@ -31,8 +31,10 @@ import {
 	IDENTITY,
 	MEMORY,
 	SCHEDULES,
+	THREADS,
 } from "../services.ts";
 import type { Tier } from "../speakers.ts";
+import type { DispatchThreads } from "../threads/dispatch-threads.ts";
 import { toolTiers } from "../tool-tiers.ts";
 
 /** What the modules' tools did, for a test to read. */
@@ -170,8 +172,8 @@ export async function setUpModules(
 		services.preset(AGENTS, {
 			team: { channelOf: options.agentChannelOf },
 		} as unknown as AgentServer);
-	if (options.discord !== false)
-		// SAFETY: the tools under test use the connection's owner channel and the threads' open only.
+	if (options.discord !== false) {
+		// SAFETY: the tools under test use the connection's owner channel only.
 		services.preset(DISCORD, {
 			connection: {
 				ownerChannel: async () => {
@@ -180,15 +182,17 @@ export async function setUpModules(
 				},
 				ownerOperations: () => ({}),
 			},
-			threads: {
-				open: async (origin: ChannelKey | undefined) => {
-					record.threadOrigins.push(origin);
-					return undefined;
-				},
-			},
 			guard: {},
 			commands: { add: () => undefined },
 		} as unknown as DiscordServices);
+		// SAFETY: the modules use the threads' open only, which records where each opens.
+		services.preset(THREADS, {
+			open: async (origin: ChannelKey | undefined) => {
+				record.threadOrigins.push(origin);
+				return undefined;
+			},
+		} as unknown as DispatchThreads);
+	}
 	const owns =
 		options.owns ?? ((channel: ChannelKey) => channel.startsWith("discord:"));
 	// Only Discord's channels have a surface; any other conversation has none to report in.

package/src/core/testing/surface-threads.ts

@@ -0,0 +1,58 @@
+import type { SurfaceThreads } from "../contract/surface.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { InterimMessage } from "../domain/interim.ts";
+
+/**
+ * A surface's `threads` that records what happens, for a test of the core over a surface other
+ * than Discord. A thread's id is `thread.<n>`, as the web's are `thread.<uuid>`, and its mention
+ * is its name; parents in `hostless` cannot host threads.
+ */
+export class FakeSurfaceThreads implements SurfaceThreads {
+	/** Start lines by parent key, as last edited. */
+	readonly lines = new Map<ChannelKey, string>();
+	readonly opened: { parent: ChannelKey; name: string; id: string }[] = [];
+	readonly posts: { thread: string; text: string }[] = [];
+	readonly closed: string[] = [];
+	/** Edits of messages `send` posted, in order; each also changes its entry in `posts`. */
+	readonly edits: { thread: string; text: string }[] = [];
+	readonly hostless = new Set<ChannelKey>();
+	failOpen = false;
+	#next = 1;
+
+	async open(
+		parent: ChannelKey,
+		name: string,
+		line: (mention?: string) => string,
+	): Promise<{ id: string; mention: string } | undefined> {
+		if (this.hostless.has(parent)) return undefined;
+		if (this.failOpen) throw new Error("the surface refused");
+		const id = `thread.${this.#next++}`;
+		this.opened.push({ parent, name, id });
+		this.lines.set(parent, line(name));
+		return { id, mention: name };
+	}
+
+	async post(thread: string, text: string): Promise<void> {
+		this.posts.push({ thread, text });
+	}
+
+	async send(thread: string, text: string): Promise<InterimMessage> {
+		const post = { thread, text };
+		this.posts.push(post);
+		return {
+			edit: async (change) => {
+				post.text = change;
+				this.edits.push({ thread, text: change });
+			},
+		};
+	}
+
+	async close(thread: string): Promise<void> {
+		this.closed.push(thread);
+	}
+
+	/** The texts posted in one thread, in order. */
+	textsIn(thread: string): string[] {
+		return this.posts.filter((p) => p.thread === thread).map((p) => p.text);
+	}
+}

package/src/core/testing/thread-host.ts

@@ -1,12 +1,15 @@
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import type { ChatSurface } from "../contract/surface.ts";
+import type { InterimMessage } from "../domain/interim.ts";
+import { silentLogger } from "../log.ts";
+import { surfacePort } from "../routing/surface-port.ts";
 import {
 	DispatchThreads,
 	type ThreadHost,
-} from "../discord/dispatch-threads.ts";
-import type { InterimMessage } from "../domain/interim.ts";
-import { silentLogger } from "../log.ts";
+} from "../threads/dispatch-threads.ts";
+import { threadsOfHost } from "../threads/host-threads.ts";
 
 /** A ThreadHost that records what happens; parents in `hostless` cannot host threads. */
 export class FakeThreadHost implements ThreadHost {
@@ -59,14 +62,23 @@ export class FakeThreadHost implements ThreadHost {
 	}
 }
 
-/** Dispatch threads over a fake host, with a ledger in a fresh temporary directory. */
+/**
+ * Dispatch threads over a fake host, as the `discord` surface hosts them, with a ledger in a
+ * fresh temporary directory.
+ */
 export function fakeThreads(host = new FakeThreadHost()) {
 	const ledgerPath = join(
 		mkdtempSync(join(tmpdir(), "roundtable-threads-")),
 		"dispatch-threads.json",
 	);
+	const discord: ChatSurface = {
+		surface: "discord",
+		start: async () => undefined,
+		sendReply: async () => undefined,
+		threads: threadsOfHost(host),
+	};
 	const threads = new DispatchThreads({
-		host,
+		surfaces: surfacePort(() => [discord]),
 		ledgerPath,
 		logger: silentLogger(),
 	});

package/src/core/threads/dispatch-threads.ts

@@ -0,0 +1,299 @@
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import {
+	channelKey,
+	parseChannelKey,
+	type SurfacePort,
+	type SurfaceThreads,
+} from "../contract/surface.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { InterimMessage, InterimPosts } from "../domain/interim.ts";
+import { messages } from "../i18n/index.ts";
+import type { Logger } from "../log.ts";
+import { threadsOfHost } from "./host-threads.ts";
+
+/** The only surface a `ThreadHost` serves. */
+const DISCORD_PREFIX = "discord:";
+/** Discord's limit on a thread name. */
+const THREAD_NAME_LIMIT = 100;
+
+/**
+ * The chat side of dispatch threads in Discord's terms: ids are Discord channel ids.
+ *
+ * @deprecated Until 1.0. A surface hosts dispatch threads with `ChatSurface.threads`
+ * (`SurfaceThreads`), for any chat network; the Discord surface implements it. Pass `surfaces`
+ * to `DispatchThreads` instead of a host.
+ */
+export interface ThreadHost {
+	/**
+	 * Posts the start line in the parent and opens a public thread from it; `line` gets the
+	 * thread's mention once it exists. Undefined when the parent cannot host threads, such as a
+	 * DM or a thread; throws when Discord refuses.
+	 */
+	open(
+		parentId: string,
+		name: string,
+		line: (thread?: string) => string,
+	): Promise<string | undefined>;
+	post(threadId: string, text: string): Promise<void>;
+	/**
+	 * Posts one message of at most Discord's 2000 characters and resolves to it, so it can be
+	 * edited in place; without it a thread has no `interim` posts.
+	 */
+	send?(threadId: string, text: string): Promise<InterimMessage>;
+	/** Archives the thread, and locks it when allowed. */
+	close(threadId: string): Promise<void>;
+}
+
+/** One background dispatch's thread: its progress while it runs, then its report. */
+export interface DispatchThread {
+	/** The thread's id on its surface, such as the Discord thread's channel id. */
+	readonly id: string;
+	/** The thread as a conversation channel, `<surface>:<id>`, where its owner cards are posted. */
+	readonly channel: ChannelKey;
+	/** How the thread is named in text, such as `<#id>` on Discord: for the report turn and the start line. */
+	readonly mention: string;
+	/** Posts in the thread; a failure is logged. */
+	post(text: string): Promise<void>;
+	/**
+	 * Where the dispatch posts its progress as it goes, under the same name as its report, such
+	 * as a coding worker's interim text; absent when the surface cannot edit a message it posted.
+	 * Unlike `post`, a failure rejects.
+	 */
+	readonly interim?: InterimPosts;
+	/** Posts the final report, if any, then archives the thread. Runs once; never rejects. */
+	close(report?: string): Promise<void>;
+}
+
+export interface DispatchThreadsOptions {
+	/**
+	 * The chat surfaces. A dispatch started in a channel opens its thread through the `threads` of
+	 * the surface that serves the channel's prefix; a channel whose surface has none gets no thread.
+	 * Give this or `host`, not both.
+	 */
+	surfaces?: Pick<SurfacePort, "of">;
+	/**
+	 * Discord's thread host, for the `discord:` channels only.
+	 *
+	 * @deprecated Until 1.0; use `surfaces`, which serves every surface that hosts threads.
+	 */
+	host?: ThreadHost;
+	/** Threads still open, so a start after a crash can close them. */
+	ledgerPath: string;
+	/** Channels whose claims keep reports in place rather than opening threads. */
+	excluded?: (channel: ChannelKey) => boolean;
+	logger: Logger;
+}
+
+interface LedgerEntry {
+	title: string;
+	parent: ChannelKey;
+	startedAt: string;
+}
+
+/** The thread's name: the title on one line, within Discord's limit. */
+export function threadName(title: string): string {
+	const line = title.replace(/\s+/g, " ").trim() || "dispatch";
+	return line.length > THREAD_NAME_LIMIT
+		? `${line.slice(0, THREAD_NAME_LIMIT - 1)}…`
+		: line;
+}
+
+/**
+ * Background dispatches (coding tasks, delegated tasks, messages between agents) each get a
+ * thread in the channel that started them, leaving one start line there. The thread lives on the
+ * surface of that channel, picked by the prefix of its key. A channel that cannot host one, or a
+ * failed creation, gets no thread, and the dispatch posts as before.
+ */
+export class DispatchThreads {
+	readonly #options: DispatchThreadsOptions;
+	readonly #threadsOf: (channel: ChannelKey) => SurfaceThreads | undefined;
+	/** The threads still open, by their channel key, `<surface>:<id>`. */
+	readonly #open = new Map<ChannelKey, LedgerEntry>();
+	/** The keys the ledger held at construction: the threads of an earlier run, which `sweep` closes. */
+	readonly #left = new Set<ChannelKey>();
+
+	constructor(options: DispatchThreadsOptions) {
+		this.#options = options;
+		const { surfaces, host, ledgerPath } = options;
+		if (surfaces && host)
+			throw new Error(
+				"DispatchThreadsOptions takes surfaces or the deprecated host, not both",
+			);
+		if (surfaces) {
+			this.#threadsOf = (channel) => surfaces.of(channel)?.threads;
+		} else if (host) {
+			const discord = threadsOfHost(host);
+			this.#threadsOf = (channel) =>
+				channel.startsWith(DISCORD_PREFIX) ? discord : undefined;
+		} else {
+			throw new Error(
+				"DispatchThreadsOptions needs surfaces, the chat surfaces that host the threads",
+			);
+		}
+		if (!existsSync(ledgerPath)) return;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(readFileSync(ledgerPath, "utf8"));
+		} catch (error) {
+			throw new Error(`${ledgerPath} is not valid JSON`, { cause: error });
+		}
+		if (typeof parsed !== "object" || parsed === null)
+			throw new Error(`${ledgerPath} must hold a JSON object`);
+		for (const [key, entry] of Object.entries(parsed)) {
+			const channel = this.#keyed(key, entry);
+			if (!channel) continue;
+			this.#open.set(channel, entry as LedgerEntry);
+			this.#left.add(channel);
+		}
+	}
+
+	/**
+	 * The channel key of a ledger entry, or undefined (with a warning) for one that cannot be
+	 * read. Before 0.23 the ledger was keyed by the Discord thread's bare id; the surface then
+	 * follows from the entry's parent, and an entry with no usable parent is skipped.
+	 */
+	#keyed(key: string, entry: unknown): ChannelKey | undefined {
+		const { logger, ledgerPath } = this.#options;
+		const parent = (entry as { parent?: unknown } | null)?.parent;
+		if (typeof parent !== "string" || !parent.includes(":")) {
+			logger.warn(
+				{ ledgerPath, thread: key },
+				"dispatch thread skipped: its ledger entry has no parent channel",
+			);
+			return undefined;
+		}
+		const at = key.indexOf(":");
+		if (at > 0) return channelKey(key.slice(0, at), key.slice(at + 1));
+		return channelKey(parseChannelKey(parent as ChannelKey).surface, key);
+	}
+
+	/** Opens the dispatch's thread under `origin`, posting `intro` first; never rejects. */
+	async open(
+		origin: ChannelKey | undefined,
+		title: string,
+		intro?: string,
+	): Promise<DispatchThread | undefined> {
+		const { excluded, logger } = this.#options;
+		const threads = origin ? this.#threadsOf(origin) : undefined;
+		if (!origin || !threads || excluded?.(origin)) return undefined;
+		const name = threadName(title);
+		let opened: { id: string; mention: string } | undefined;
+		try {
+			opened = await threads.open(origin, name, (mention) =>
+				messages().threadStarted(name, mention),
+			);
+		} catch (error) {
+			logger.warn({ origin, err: error }, "dispatch thread not opened");
+			return undefined;
+		}
+		if (!opened?.id) return undefined;
+		const channel = channelKey(parseChannelKey(origin).surface, opened.id);
+		this.#open.set(channel, {
+			title: name,
+			parent: origin,
+			startedAt: new Date().toISOString(),
+		});
+		this.#write();
+		logger.info({ origin, thread: channel }, "dispatch thread opened");
+		const thread = this.#thread(channel, threads, opened.mention);
+		if (intro) await thread.post(intro);
+		return thread;
+	}
+
+	/**
+	 * Closes the threads an earlier run left open, those the ledger held at construction; their
+	 * dispatches never report. A thread opened since is live and stays. One whose surface is
+	 * absent stays in the ledger for the next start, and one failure does not stop the rest.
+	 */
+	async sweep(): Promise<void> {
+		const { logger } = this.#options;
+		for (const channel of [...this.#left]) {
+			this.#left.delete(channel);
+			const entry = this.#open.get(channel);
+			if (!entry) continue;
+			try {
+				const threads = this.#threadsOf(entry.parent);
+				if (!threads) {
+					logger.warn(
+						{ thread: channel, parent: entry.parent },
+						"dispatch thread kept: its surface hosts no threads at this start",
+					);
+					continue;
+				}
+				// The thread is closed, never mentioned, so its mention stays empty.
+				await this.#thread(channel, threads).close(messages().restartNotice);
+			} catch (error) {
+				logger.warn(
+					{ thread: channel, err: error },
+					"dispatch thread not swept",
+				);
+			}
+		}
+	}
+
+	#thread(
+		channel: ChannelKey,
+		threads: SurfaceThreads,
+		mention = "",
+	): DispatchThread {
+		const { logger } = this.#options;
+		const { id } = parseChannelKey(channel);
+		let closed = false;
+		const send = threads.send?.bind(threads);
+		const post = async (text: string) => {
+			try {
+				await threads.post(id, text);
+			} catch (error) {
+				logger.warn(
+					{ thread: channel, err: error },
+					"dispatch thread post failed",
+				);
+			}
+		};
+		return {
+			id,
+			channel,
+			mention,
+			post,
+			...(send ? { interim: { post: (text: string) => send(id, text) } } : {}),
+			close: async (report) => {
+				if (closed) return;
+				closed = true;
+				if (report) await post(report);
+				try {
+					await threads.close(id);
+				} catch (error) {
+					logger.warn(
+						{ thread: channel, err: error },
+						"dispatch thread not archived",
+					);
+				}
+				this.#open.delete(channel);
+				this.#write();
+			},
+		};
+	}
+
+	#write(): void {
+		const path = this.#options.ledgerPath;
+		try {
+			mkdirSync(dirname(path), { recursive: true });
+			const temporary = `${path}.tmp`;
+			writeFileSync(
+				temporary,
+				`${JSON.stringify(Object.fromEntries(this.#open), null, 2)}\n`,
+				{ mode: 0o600 },
+			);
+			renameSync(temporary, path);
+		} catch (error) {
+			this.#options.logger.warn({ err: error }, "dispatch threads not saved");
+		}
+	}
+}

package/src/core/threads/host-threads.ts

@@ -0,0 +1,19 @@
+import { parseChannelKey, type SurfaceThreads } from "../contract/surface.ts";
+import type { ThreadHost } from "./dispatch-threads.ts";
+
+/**
+ * A Discord `ThreadHost` as the `SurfaceThreads` of the `discord` surface: a thread's id is its
+ * Discord channel id, mentioned as `<#id>`, and a parent is the Discord channel behind its key.
+ */
+export function threadsOfHost(host: ThreadHost): SurfaceThreads {
+	const send = host.send?.bind(host);
+	return {
+		open: async (parent, name, line) => {
+			const id = await host.open(parseChannelKey(parent).id, name, line);
+			return id ? { id, mention: `<#${id}>` } : undefined;
+		},
+		post: (thread, text) => host.post(thread, text),
+		...(send ? { send } : {}),
+		close: (thread) => host.close(thread),
+	};
+}