pi-roundtable 0.26.3 → 0.27.0

package/src/core/config/routing.ts

@@ -0,0 +1,296 @@
+import { ConfigError } from "../domain/errors.ts";
+import type { ChannelKey } from "../sessions.ts";
+import {
+	either,
+	type Field,
+	list,
+	oneOf,
+	optional,
+	record,
+	shape,
+	text,
+} from "./schema.ts";
+
+/**
+ * Where an agent's unprompted work lands: how an event that no person is waiting on picks its
+ * conversation. Every key is optional, and a key left out keeps what the host did before `routing`
+ * existed. A surface is named by its key prefix, such as `discord` or `app`; `web` stands for the
+ * one surface that hosts rooms when exactly one does.
+ */
+export interface AgentRoutes {
+	/**
+	 * The agent's primary place, where its unprompted work lands. `"auto"` (default) is its
+	 * Discord channel when it has one, else its room on the first surface that hosts rooms; a
+	 * surface name picks the agent's place there.
+	 */
+	primary?: "auto" | (string & {});
+	/**
+	 * Where a foreign webhook's or integration's post in the agent's place runs its report turn.
+	 * `"origin"` (default) is the conversation the post came in; `"primary"` the agent's primary
+	 * place; a surface name the agent's place there. The raw post stays where it was posted.
+	 */
+	integration?: "origin" | "primary" | (string & {});
+	/**
+	 * The conversation a `message_agent` call reaches when it names none. `"latest"` (default) is
+	 * the one the agent last ran a turn in, never carrying a message from a room out to Discord;
+	 * `"primary"` the agent's primary place; a surface name the agent's place there.
+	 */
+	agentMessage?: "latest" | "primary" | (string & {});
+	/**
+	 * Where an agent's opening task (`agent_create task`) runs. `"origin-surface"` (default) is the
+	 * agent's place on the surface the creation came from, else its primary place; `"primary"`
+	 * always its primary place.
+	 */
+	opening?: "origin-surface" | "primary";
+	/**
+	 * Reserved: surfaces that get a read-only copy of what the agent posts in its primary place.
+	 * Not built yet; a non-empty list stops the start.
+	 */
+	mirror?: string[];
+}
+
+/** A named destination of the host: a conversation, or one agent's primary place. */
+export type PlaceTarget = `${string}:${string}` | { agent: string };
+
+/** What a surface offers agents; both keys are reserved and only the default is accepted today. */
+export interface SurfaceRouting {
+	/** `"all"` (default): every agent has a place on the surface. `"none"` is reserved and stops the start. */
+	agentPlaces?: "all" | "none";
+	/** Reserved: which claim answers the surface's conversations. Not built yet; setting it stops the start. */
+	answeredBy?: string;
+}
+
+/**
+ * The optional `routing` block: one declared table for where events land. Leaving it out keeps
+ * every default as it was before the block existed.
+ */
+export interface RoutingConfig {
+	/**
+	 * Per-agent rules by agent name; `"*"` is the default of every agent. A name applies to the
+	 * agent when it is created later too. A field the agent's entry leaves out falls to `"*"`.
+	 */
+	agents?: { "*"?: AgentRoutes } & Record<string, AgentRoutes | undefined>;
+	/**
+	 * Named destinations of the host. `ops` is the process's error reports: a conversation key
+	 * `<surface>:<id>`, or `{ agent }` for that agent's primary place.
+	 */
+	places?: Record<string, PlaceTarget>;
+	/** Per-surface settings, by surface name. */
+	surfaces?: Record<string, SurfaceRouting>;
+}
+
+/** The places the core declares; a name outside this list is a typo until a plugin declares it. */
+const DECLARED_PLACES: readonly string[] = ["ops"];
+
+/** The agent-rule keys that name a destination, and the words each accepts besides a surface name. */
+export const ROUTE_WORDS = {
+	primary: ["auto"],
+	integration: ["origin", "primary"],
+	agentMessage: ["latest", "primary"],
+	opening: ["origin-surface", "primary"],
+} as const;
+
+type RouteKey = keyof typeof ROUTE_WORDS;
+
+/** Every word with a meaning of its own; none of them may name a surface. */
+const KEYWORDS: readonly string[] = [
+	...new Set(Object.values(ROUTE_WORDS).flat()),
+];
+
+const AGENT_NAME = /^[a-z0-9-]{1,32}$/;
+const CONVERSATION = /^[^:]+:.+$/;
+
+/** A destination of `key`: one of its words, or a surface name; another kind's word is refused. */
+function destination(key: RouteKey): Field<string> {
+	const words = ROUTE_WORDS[key];
+	const describe =
+		key === "opening"
+			? `one of ${words.join(", ")}`
+			: `${words.map((w) => `"${w}"`).join(", ")}, or a surface name`;
+	return {
+		describe,
+		check: (value, path) => {
+			const given = text.check(value, path);
+			const word = given.trim();
+			const own = (words as readonly string[]).includes(word);
+			if (!own && (KEYWORDS.includes(word) || key === "opening"))
+				throw new ConfigError(
+					`config ${path}: ${JSON.stringify(word)} is not a value of ${key}. Use ${describe}.`,
+				);
+			return word;
+		},
+	};
+}
+
+const agentRoutes = shape({
+	primary: optional(destination("primary")),
+	integration: optional(destination("integration")),
+	agentMessage: optional(destination("agentMessage")),
+	opening: optional(destination("opening")),
+	mirror: optional(list(text)),
+});
+
+const placeTarget: Field<PlaceTarget> = either(
+	text as Field<`${string}:${string}`>,
+	shape({ agent: text }),
+);
+
+const surfaceRouting = shape({
+	agentPlaces: optional(oneOf("all" as const, "none" as const)),
+	answeredBy: optional(text),
+});
+
+/** The `routing` key's shape. */
+export const routingShape = optional(
+	shape({
+		agents: optional(record(agentRoutes)),
+		places: optional(record(placeTarget)),
+		surfaces: optional(record(surfaceRouting)),
+	}),
+);
+
+/** The rules of one agent after checking: the reserved keys are gone. */
+export interface ResolvedAgentRoutes {
+	primary?: string;
+	integration?: string;
+	agentMessage?: string;
+	opening?: "origin-surface" | "primary";
+}
+
+/** The checked `routing` block the agent server reads; a host without the key has none. */
+export interface ResolvedRouting {
+	agents: Readonly<Record<string, ResolvedAgentRoutes>>;
+	/** Named destinations: a conversation key, or an agent whose primary place it is. */
+	places: Readonly<Record<string, ChannelKey | { agent: string }>>;
+}
+
+/** What the rest of the configuration says that the block is checked against. */
+export interface RoutingContext {
+	/** Whether Discord is configured, so agents have Discord channels. */
+	withDiscord: boolean;
+	/** Whether the agent server runs: only then do agents and their places exist. */
+	agentServer: boolean;
+	/** Whether the top-level `ops` is set, which the `ops` place replaces. */
+	topLevelOps: boolean;
+}
+
+const refuse = (path: string, problem: string, fix: string): ConfigError =>
+	new ConfigError(`config ${path}: ${problem}. ${fix}`);
+
+function checkReserved(config: RoutingConfig): void {
+	for (const [name, agent] of Object.entries(config.agents ?? {}))
+		if ((agent?.mirror?.length ?? 0) > 0)
+			throw refuse(
+				`routing.agents.${name}.mirror`,
+				"mirroring a place is not built yet, so it would do nothing",
+				"Remove mirror; the term and the key are reserved until a host needs the copies",
+			);
+	for (const [surface, rules] of Object.entries(config.surfaces ?? {})) {
+		if (rules.agentPlaces === "none")
+			throw refuse(
+				`routing.surfaces.${surface}.agentPlaces`,
+				'"none" is not built yet: Discord makes a channel for every agent, and a surface that hosts rooms hosts one for every agent',
+				'Remove agentPlaces or write "all", which is what every surface does',
+			);
+		if (rules.answeredBy !== undefined)
+			throw refuse(
+				`routing.surfaces.${surface}.answeredBy`,
+				"naming the claim that answers a surface is not built yet; claim priorities decide",
+				"Remove answeredBy; give your plugin's claim a priority above the agent server's to answer there",
+			);
+	}
+}
+
+/**
+ * Checks the block against the rest of the configuration, naming the key and the fix. Surfaces
+ * are checked again once the plugins have registered theirs, when the agent server links.
+ */
+export function routingOf(
+	config: RoutingConfig | undefined,
+	context: RoutingContext,
+): ResolvedRouting | undefined {
+	if (!config) return undefined;
+	const agents = config.agents ?? {};
+	const places = config.places ?? {};
+	const surfaces = config.surfaces ?? {};
+	checkReserved(config);
+	for (const name of Object.keys(agents))
+		if (name !== "*" && !AGENT_NAME.test(name))
+			throw refuse(
+				`routing.agents.${name}`,
+				'not an agent name: lowercase letters, digits and dashes, 1 to 32, or "*" for every agent',
+				"Rename the key to the agent's name",
+			);
+	for (const name of Object.keys(places))
+		if (!DECLARED_PLACES.includes(name))
+			throw refuse(
+				`routing.places.${name}`,
+				`no place is called ${JSON.stringify(name)}`,
+				`The places are ${DECLARED_PLACES.join(", ")}`,
+			);
+	for (const [name, target] of Object.entries(places))
+		if (typeof target === "string" && !CONVERSATION.test(target))
+			throw refuse(
+				`routing.places.${name}`,
+				`expected a conversation key <surface>:<id> or { agent }, got ${JSON.stringify(target)}`,
+				"Write the surface's prefix, a colon, and the conversation's id, or name an agent",
+			);
+	if (places.ops !== undefined && context.topLevelOps)
+		throw refuse(
+			"routing.places.ops",
+			"the top-level ops is set as well, and both say where the error reports go",
+			"Keep one: move ops into routing.places.ops and remove the top-level ops",
+		);
+	const needsAgents =
+		Object.keys(agents).length > 0 ||
+		Object.keys(surfaces).length > 0 ||
+		(typeof places.ops === "object" && places.ops !== undefined);
+	if (needsAgents && !context.agentServer)
+		throw refuse(
+			"routing",
+			"agents, per-surface settings and an agent place need the agent server, and this host runs none (agentServer is false, or there is neither discord nor agents)",
+			"Remove those keys from routing, or remove agentServer: false and configure discord or agents",
+		);
+	if (!context.withDiscord) {
+		const named = Object.entries(agents).flatMap(([name, rules]) =>
+			(["primary", "integration", "agentMessage"] as const)
+				.filter((key) => rules?.[key] === "discord")
+				.map((key) => `routing.agents.${name}.${key}`),
+		);
+		if (named[0] || surfaces.discord)
+			throw refuse(
+				named[0] ?? "routing.surfaces.discord",
+				"names the discord surface, and Discord is not configured",
+				"Name a surface that hosts rooms instead, or configure discord",
+			);
+	}
+	return {
+		agents: Object.fromEntries(
+			Object.entries(agents).flatMap(([name, rules]) =>
+				rules === undefined
+					? []
+					: [
+							[
+								name,
+								{
+									...(rules.primary ? { primary: rules.primary } : {}),
+									...(rules.integration
+										? { integration: rules.integration }
+										: {}),
+									...(rules.agentMessage
+										? { agentMessage: rules.agentMessage }
+										: {}),
+									...(rules.opening ? { opening: rules.opening } : {}),
+								},
+							],
+						],
+			),
+		),
+		places: Object.fromEntries(
+			Object.entries(places).map(([name, target]) => [
+				name,
+				typeof target === "string" ? (target as ChannelKey) : target,
+			]),
+		),
+	};
+}

package/src/core/contract/channels.ts

@@ -47,8 +47,12 @@ export interface InboundMessage {
 	/**
 	 * Who the author is, with their principal and tier, as the router resolved them before any
 	 * claim admits the message: undefined when the access rules serve no one by them, and for a bot
-	 * or an integration, which are not resolved. Only the router sets it; a surface's own value is
-	 * dropped. A claim that serves only people the host serves answers only when it is set.
+	 * the host does not list as a peer (`peerBot`) and for an integration, which are not resolved.
+	 * A listed peer bot is resolved too, so a claim that checks only `speaker` answers it; use
+	 * `answersAuthor` to tell a person from a peer. A peer is served by the access rules through its
+	 * identity and `everyone`, never through its server roles. Only the router sets it; a surface's
+	 * own value is dropped. A claim that serves only people the host serves answers only when it is
+	 * set.
 	 */
 	speaker?: Speaker;
 	/** The id the surface knows the author by; who they are to the host is `speaker`. */
@@ -56,6 +60,14 @@ export interface InboundMessage {
 	/** How the author appears in the channel, for example a server nickname. */
 	authorName: string;
 	authorIsBot: boolean;
+	/**
+	 * Set by the router when a bot wrote the message and the host lists that bot as a peer
+	 * (`discord.peerBots`) for this channel, with its rounds not used up. Such a message is
+	 * resolved to a `speaker` like a person's, and a claim that answers people may answer it too;
+	 * a claim that answers a peer should still ask for a mention or a reply to the bot. Only the
+	 * router sets it; a surface's own value is dropped.
+	 */
+	peerBot?: true;
 	/** The roles the author holds in the message's space; absent in direct messages. */
 	authorRoleIds?: readonly string[];
 	/**
@@ -231,6 +243,25 @@ export interface ChannelClaim {
 	backgroundRefusal?(
 		turn: BackgroundTurn & { speaker: Speaker },
 	): string | undefined;
+	/**
+	 * A message in an owned channel was deleted, as its surface reports it (Discord does; a
+	 * surface that cannot tell never does). It carries only the id, and also arrives for the
+	 * assistant's own messages, since the surface cannot tell whose an uncached message was: a
+	 * claim ignores an id it does not know. Delivered as it comes, not inside the channel's queue,
+	 * so it is not held up behind a running turn; a throw or rejection is logged and isolated.
+	 */
+	onMessageDeleted?(
+		channel: ChannelKey,
+		messageId: string,
+	): Promise<void> | void;
+	/**
+	 * A message in an owned channel was edited, as it reads now. The assistant's own edits are
+	 * never reported, as its own messages never reach `admit`; an edit that changes neither the
+	 * text, the embeds nor the attachments, such as a pin, is not either. The message carries no
+	 * `speaker` and no `peerBot`, since an edit is never admitted and resolves nobody, and the
+	 * router applies no peer rule to it. Delivered like `onMessageDeleted`.
+	 */
+	onMessageEdited?(message: InboundMessage): Promise<void> | void;
 	/** Starts the channel's conversation over, saying whose it was. */
 	startFresh(channel: ChannelKey): Promise<string>;
 	/**
@@ -285,8 +316,48 @@ export interface ConversationPort {
 	takesBackground(channel: ChannelKey): boolean;
 	/** Whether the claim that owns the channel takes the host's own turns; false when none owns it. */
 	takesSystemReports(channel: ChannelKey): boolean;
+	/**
+	 * Tells the claim that owns the channel a message was deleted (`ChannelClaim.onMessageDeleted`);
+	 * never rejects. Optional so a port written before 0.27 still type-checks; the host's has it.
+	 */
+	messageDeleted?(
+		channel: ChannelKey,
+		messageId: string,
+		space?: string,
+	): Promise<void>;
+	/** Tells the claim that owns the channel a message was edited (`ChannelClaim.onMessageEdited`); never rejects. */
+	messageEdited?(message: InboundMessage): Promise<void>;
+}
+
+/**
+ * Which inbound messages an observer hears. Every field narrows; an empty filter hears every
+ * message in a channel some claim owns, in a server or workspace, never in a direct conversation
+ * and never in the rooms of a surface that hosts agent rooms (`agentRooms`), which are one
+ * person's or one team's. A filter that names that surface in `surface` hears them.
+ */
+export interface ObserveFilter {
+	/**
+	 * Only this surface's channels, by its key prefix, such as "discord". Naming a surface that
+	 * hosts agent rooms is how an observer opts in to hearing those rooms; without it they are
+	 * left out.
+	 */
+	surface?: string;
+	/** Only this server or workspace, in the surface's own id. */
+	space?: string;
+	/** Only these channels. */
+	channels?: readonly ChannelKey[];
+	/**
+	 * Also hear direct conversations. Off by default: a direct message is private to its two
+	 * sides, and an observer that sees it must be one the people there would expect.
+	 */
+	includeDirect?: boolean;
 }
 
+/** Hears a message; a return is not read, and a throw or rejection is logged and isolated. */
+export type MessageObserver = (
+	message: Readonly<InboundMessage>,
+) => Promise<void> | void;
+
 /** The host's channel queue, as plugins use it. */
 export interface QueuePort {
 	run<T>(channel: ChannelKey, task: () => Promise<T>): Promise<T>;

package/src/core/contract/surface.ts

@@ -1,6 +1,7 @@
 import type { OutboundReply, PostAuthor } from "../domain/conversation.ts";
 import type { InterimMessage, InterimPosts } from "../domain/interim.ts";
 import type { TurnProgress } from "../domain/progress.ts";
+import type { RoundProgress } from "../domain/round.ts";
 import { PluginError } from "../errors.ts";
 import type { PromptScope, Prompts } from "../interactions/prompts.ts";
 import type { ChannelKey } from "../sessions.ts";
@@ -71,6 +72,18 @@ export interface SurfaceThreads {
 	close(thread: string): Promise<void>;
 }
 
+/**
+ * What a surface tells the host about messages already delivered, so the claim that owns the
+ * channel hears of it (`ChannelClaim.onMessageDeleted`, `onMessageEdited`). A surface that cannot
+ * tell, such as a web chat that keeps every message, never calls them.
+ */
+export interface SurfaceMessageEvents {
+	/** A message was deleted; `space` is its server or workspace, when the surface has one. */
+	deleted(channel: ChannelKey, messageId: string, space?: string): void;
+	/** A message's text or attachments changed; the message is as it reads now. */
+	edited(message: InboundMessage): void;
+}
+
 /**
  * One chat network the host talks through. The host ships Discord's; a plugin may contribute
  * another with `surfaces`. A surface serves the channels whose key starts with its `surface`
@@ -122,7 +135,10 @@ export interface ChatSurface {
 	 * Connects and delivers every incoming message; the host passes its conversation router. A
 	 * message whose channel key has another prefix is logged and dropped.
 	 */
-	start(deliver: (message: InboundMessage) => void): Promise<void>;
+	start(
+		deliver: (message: InboundMessage) => void,
+		events?: SurfaceMessageEvents,
+	): Promise<void>;
 	/** Runs when the host stops, after the services started later have stopped. */
 	stop?(): Promise<void>;
 	sendReply(channel: ChannelKey, reply: OutboundReply): Promise<void>;
@@ -186,6 +202,13 @@ export interface ChatSurface {
 	 * turn goes on. Absent = the surface shows only the final reply.
 	 */
 	progress?(channel: ChannelKey, event: TurnProgress): Promise<void> | void;
+	/**
+	 * Shows where a group's round stands: who speaks now, who is next, who has spoken. Called when
+	 * the round is planned, before and after each member's turn, on a handoff, and when it ends;
+	 * each call carries the whole state. A rejection is logged and the round goes on. Absent = the
+	 * surface shows no rounds, as Discord does not.
+	 */
+	groupRound?(channel: ChannelKey, round: RoundProgress): Promise<void> | void;
 }
 
 /**
@@ -214,6 +237,11 @@ export interface SurfacePort {
 	): Prompts | undefined;
 	/** The surfaces that serve agent rooms (`agentRooms: true`); read after link. */
 	roomSurfaces(): readonly string[];
+	/**
+	 * Every registered surface, by name; read after link. The host's port always has it; optional
+	 * so a port written before 0.27 still type-checks.
+	 */
+	names?(): readonly string[];
 	/** The channel's interim posts, under `as` when given; undefined when its surface has none. */
 	interim(channel: ChannelKey, as?: PostAuthor): InterimPosts | undefined;
 	/**
@@ -222,4 +250,6 @@ export interface SurfacePort {
 	 * type-checks, and a turn run over one without it shows no progress.
 	 */
 	progress?(channel: ChannelKey, event: TurnProgress): Promise<void>;
+	/** Shows where a group's round stands; a no-op when no surface serves the channel or its surface shows none. */
+	groupRound?(channel: ChannelKey, round: RoundProgress): Promise<void>;
 }

package/src/core/define-roundtable.ts

@@ -245,6 +245,8 @@ function agentAssembly(
 			...(config.characters.refreshAvatars ? { refreshAvatars: true } : {}),
 			avatarReference: join(ASSETS, "neutral.png"),
 			avatarNeutral: join(ASSETS, "neutral.png"),
+			...(config.routing ? { routing: config.routing } : {}),
+			helpers: config.helpers,
 			// An ops agent's reports are the agent server's to deliver.
 			...(errorReporter && "agent" in errorReporter.destination
 				? { errorReporter }
@@ -280,7 +282,11 @@ export async function defineRoundtable(
 		}));
 	const registry = new ModelRegistry(modelRuntime);
 	const errorReporter = config.ops
-		? new ErrorReporter({ destination: config.ops, app: name })
+		? new ErrorReporter({
+				destination: config.ops,
+				app: name,
+				configKey: config.opsKey === "ops" ? "ops.conversation" : config.opsKey,
+			})
 		: undefined;
 	const { errorSink } = overrides;
 	const logger: Logger =
@@ -334,6 +340,7 @@ export async function defineRoundtable(
 			judgeModel: judgeThrough(modelRuntime, config.judge.model),
 			apiKey: (provider) => registry.getApiKeyForProvider(provider),
 			drain: { limitMs: config.drainMs },
+			...(discord?.peerBots ? { peerBots: discord.peerBots } : {}),
 			...(overrides.aborted ? { aborted: overrides.aborted } : {}),
 		},
 		plugins: [

package/src/core/discord/agent-discord.ts

@@ -13,6 +13,7 @@ import {
 	SeparatorSpacingSize,
 	type TextChannel,
 	TextDisplayBuilder,
+	ThreadAutoArchiveDuration,
 	type Webhook,
 } from "discord.js";
 import type {
@@ -39,19 +40,41 @@ export class DiscordAgentChannels implements AgentChannels {
 	readonly #client: Client;
 	readonly #guildId: string;
 	readonly #webhooks = new Map<string, Promise<Webhook>>();
+	/** The parent channel of each thread the agents live in, and null for a channel that is none. */
+	readonly #parents = new Map<string, string | null>();
 
 	constructor(client: Client, guildId: string) {
 		this.#client = client;
 		this.#guildId = guildId;
 	}
 
+	/**
+	 * Where a post to `channelId` is sent: the channel whose webhook speaks, and the thread it
+	 * speaks into. A temp knight's place is a thread, which has no webhook of its own.
+	 */
+	async #route(
+		channelId: string,
+		threadId: string | undefined,
+	): Promise<{ hook: string; threadId?: string }> {
+		let parent = this.#parents.get(channelId);
+		if (parent === undefined) {
+			const channel = await this.#client.channels.fetch(channelId);
+			parent = channel?.isThread() ? (channel.parentId ?? null) : null;
+			this.#parents.set(channelId, parent);
+		}
+		if (parent === null)
+			return { hook: channelId, ...(threadId ? { threadId } : {}) };
+		return { hook: parent, threadId: channelId };
+	}
+
 	async post(channelId: string, post: AgentPost): Promise<void> {
-		const webhook = await this.#webhook(channelId);
+		const route = await this.#route(channelId, post.threadId);
+		const webhook = await this.#webhook(route.hook);
 		const as = {
 			username: post.name,
 			avatarURL: post.avatarUrl,
 			allowedMentions: { parse: ["users" as const] },
-			...(post.threadId ? { threadId: post.threadId } : {}),
+			...(route.threadId ? { threadId: route.threadId } : {}),
 		};
 		try {
 			if (post.thinking) await webhook.send({ ...as, content: post.thinking });
@@ -66,7 +89,7 @@ export class DiscordAgentChannels implements AgentChannels {
 				});
 		} catch (error) {
 			// A webhook deleted by hand is found or made again on the next post.
-			this.#webhooks.delete(channelId);
+			this.#webhooks.delete(route.hook);
 			throw error;
 		}
 	}
@@ -75,10 +98,11 @@ export class DiscordAgentChannels implements AgentChannels {
 		channelId: string,
 		as: Omit<AgentPost, "thinking" | "chunks" | "files">,
 	): InterimPosts {
-		const threadId = as.threadId ? { threadId: as.threadId } : {};
 		return {
 			post: async (text) => {
-				const webhook = await this.#webhook(channelId);
+				const route = await this.#route(channelId, as.threadId);
+				const threadId = route.threadId ? { threadId: route.threadId } : {};
+				const webhook = await this.#webhook(route.hook);
 				try {
 					const message = await webhook.send({
 						username: as.name,
@@ -96,13 +120,43 @@ export class DiscordAgentChannels implements AgentChannels {
 						},
 					};
 				} catch (error) {
-					this.#webhooks.delete(channelId);
+					this.#webhooks.delete(route.hook);
 					throw error;
 				}
 			},
 		};
 	}
 
+	async createThread(parentChannelId: string, name: string): Promise<string> {
+		const parent = await this.#text(parentChannelId);
+		const thread = await parent.threads.create({
+			name: name.slice(0, 100),
+			// The longest a thread stays open untouched, so a quiet helper's place is not archived under it.
+			autoArchiveDuration: ThreadAutoArchiveDuration.OneWeek,
+		});
+		this.#parents.set(thread.id, parentChannelId);
+		return thread.id;
+	}
+
+	async closeThread(threadId: string): Promise<void> {
+		const thread = await this.#thread(threadId);
+		// Locking needs Manage Threads; without it the thread is only archived.
+		try {
+			await thread.edit({ archived: true, locked: true });
+		} catch {
+			await thread.setArchived(true);
+		}
+	}
+
+	async openThread(threadId: string): Promise<void> {
+		const thread = await this.#thread(threadId);
+		try {
+			await thread.edit({ archived: false, locked: false });
+		} catch {
+			await thread.setArchived(false);
+		}
+	}
+
 	async createChannel(
 		name: string,
 		topic: string,
@@ -239,6 +293,13 @@ export class DiscordAgentChannels implements AgentChannels {
 		);
 	}
 
+	async #thread(threadId: string) {
+		const channel = await this.#client.channels.fetch(threadId);
+		if (!channel?.isThread())
+			throw new AgentError(`channel ${threadId} is not a thread`);
+		return channel;
+	}
+
 	async #text(channelId: string): Promise<TextChannel> {
 		const channel = await this.#client.channels.fetch(channelId);
 		if (channel?.type !== ChannelType.GuildText)