pi-roundtable 0.1.0 → 0.2.0

package/src/core/define-roundtable.ts

@@ -2,31 +2,24 @@ import { readFileSync } from "node:fs";
 import { userInfo } from "node:os";
 import { join } from "node:path";
 import { ModelRegistry, ModelRuntime } from "@earendil-works/pi-coding-agent";
-import {
-	type AgentServerOptions,
-	agentServerPlugin,
-} from "./builtin/agent-server.ts";
+import { agentServerPlugin } from "./builtin/agent-server.ts";
 import { discordPlugin } from "./builtin/discord.ts";
-import {
-	type ModulesOptions,
-	modulesPlugin,
-	schedulerPlugin,
-} from "./builtin/modules.ts";
+import { discordAdminPlugin } from "./builtin/discord-admin.ts";
+import { modulesPlugin, schedulerPlugin } from "./builtin/modules.ts";
 import { seedsPlugin } from "./builtin/seeds.ts";
-import { storesPlugin } from "./builtin/stores.ts";
+import { skillsPlugin } from "./builtin/skills.ts";
+import { memoryPlugin, scheduleStorePlugin } from "./builtin/stores.ts";
 import { type RoundtableConfig, resolveConfig } from "./config/config.ts";
-import { ownerRootCommand } from "./discord/owner-command.ts";
 import { ConfigError } from "./domain/errors.ts";
 import { JudgeError } from "./errors.ts";
 import type { RoundtableOptions } from "./host.ts";
-import { setLocale } from "./i18n/index.ts";
+import type { ListenerConfig } from "./http/listeners.ts";
 import { type JudgeModel, piJudgeModel } from "./judging/model-judge.ts";
-import { createLogger, type Logger } from "./log.ts";
+import { createLogger, type LogEntry, type Logger } from "./log.ts";
 import { formatModelRef, type ModelRef } from "./models.ts";
 import { ErrorReporter } from "./ops/error-reporter.ts";
 import type { RoundtablePlugin } from "./plugin.ts";
 import { speakerPolicy } from "./speakers.ts";
-import { setTimeZone } from "./time.ts";
 import { toolTiers } from "./tool-tiers.ts";
 
 /** What `defineRoundtable` returns: give both to `new Roundtable(options, plugins)`. */
@@ -39,14 +32,21 @@ export interface DefinedRoundtable {
 export interface DefineOverrides {
 	/** The model login the process shares; by default one is opened in the agent directory. */
 	modelRuntime?: ModelRuntime;
-	/** Your own logger and error reporter, when the process already has them. */
+	/**
+	 * Your own logger, when the process already has one. The host reports errors to `config.ops`'s
+	 * agent and to `errorSink` from the logger it builds, so a logger given here forwards its own
+	 * error lines to them if it should.
+	 */
 	logger?: Logger;
-	errorReporter?: ErrorReporter;
-	/** Host options merged over the built ones, such as more listeners or the record of aborted work. */
-	options?: Partial<RoundtableOptions>;
-	/** What only the plugins after the built-ins can know. */
-	modules?: Pick<ModulesOptions, "agentChannelOf">;
-	agentServer?: Pick<AgentServerOptions, "ownerSessions">;
+	/**
+	 * Also receives every `error` and `fatal` log line of the logger the host builds, after the ops
+	 * agent's report. It must not throw.
+	 */
+	errorSink?: (entry: LogEntry) => void;
+	/** More HTTP listeners than the one `config.http` names, each with its own id. */
+	listeners?: readonly ListenerConfig[];
+	/** Receives the work a shutdown drain gave up on, before any service stops. */
+	aborted?: (left: string[]) => Promise<void>;
 }
 
 const ASSETS = join(import.meta.dir, "assets");
@@ -82,8 +82,9 @@ function judgeThrough(modelRuntime: ModelRuntime, ref: ModelRef): JudgeModel {
 
 /**
  * The host's options and the plugin list of a configured bot: the built-in plugins in their
- * fixed order, then the operator's, then the scheduler, so a due schedule fires only once
- * everything it reaches runs. Configuration mistakes stop here, naming the key and the fix.
+ * fixed order (each service one provides is read by the ones after it), then the operator's, then the scheduler, so a due schedule fires only once
+ * everything it reaches runs. The memory, Discord administration, and skills addons are left out
+ * when the configuration switches them off. Configuration mistakes stop here, naming the key and the fix.
  */
 export async function defineRoundtable(
 	input: RoundtableConfig,
@@ -91,25 +92,27 @@ export async function defineRoundtable(
 ): Promise<DefinedRoundtable> {
 	const config = resolveConfig(input);
 	const { name, owner, discord } = config;
-	setLocale(config.locale, { assistant: name, root: discord.rootCommand });
-	setTimeZone(config.timeZone);
-	// Pi packages such as pi-web-access read their config from the Pi agent directory.
-	process.env.PI_CODING_AGENT_DIR = config.agentDir;
+	// Nothing here touches the process: the host applies the environment when it runs.
 	const modelRuntime =
 		overrides.modelRuntime ??
 		(await ModelRuntime.create({
 			authPath: join(config.agentDir, "auth.json"),
+			modelsPath: join(config.agentDir, "models.json"),
 		}));
-	const errorReporter =
-		overrides.errorReporter ??
-		(config.ops
-			? new ErrorReporter({ opsAgent: config.ops.agent, app: name })
-			: undefined);
+	const errorReporter = config.ops
+		? new ErrorReporter({ opsAgent: config.ops.agent, app: name })
+		: undefined;
+	const { errorSink } = overrides;
 	const logger =
 		overrides.logger ??
 		createLogger(
 			discord.rootCommand,
-			errorReporter ? (entry) => errorReporter.record(entry) : undefined,
+			errorReporter || errorSink
+				? (entry) => {
+						errorReporter?.record(entry);
+						errorSink?.(entry);
+					}
+				: undefined,
 		);
 	const speakers = speakerPolicy({
 		owners: [owner.id],
@@ -125,12 +128,24 @@ export async function defineRoundtable(
 	return {
 		options: {
 			logger,
+			environment: {
+				locale: config.locale,
+				timeZone: config.timeZone,
+				assistant: name,
+				rootCommand: discord.rootCommand,
+				agentDir: config.agentDir,
+			},
 			database: { url: config.databaseUrl },
 			toolTiers: toolTiers(config.toolTiers),
-			commands: { root: ownerRootCommand(discord.rootCommand) },
 			listeners: [
 				config.http.socketPath
-					? { id: "public", socketPath: config.http.socketPath }
+					? {
+							id: "public",
+							socketPath: config.http.socketPath,
+							...(config.http.socketMode === undefined
+								? {}
+								: { mode: config.http.socketMode }),
+						}
 					: {
 							id: "public",
 							port: config.http.port,
@@ -138,12 +153,14 @@ export async function defineRoundtable(
 								? { hostname: config.http.hostname }
 								: {}),
 						},
+				...(overrides.listeners ?? []),
 			],
 			judgeModel: judgeThrough(modelRuntime, config.judge.model),
-			...overrides.options,
+			...(overrides.aborted ? { aborted: overrides.aborted } : {}),
 		},
 		plugins: [
-			storesPlugin({ ownerId: owner.id, guildId: discord.guild }),
+			...(config.memory ? [memoryPlugin({ owner })] : []),
+			scheduleStorePlugin(),
 			discordPlugin({
 				token: discord.token,
 				ownerId: owner.id,
@@ -151,8 +168,9 @@ export async function defineRoundtable(
 				speakers,
 				rootCommand: discord.rootCommand,
 				dataDir: config.dataDir,
-				avatarUrl: config.http.publicUrl,
-				avatarReference: config.avatar ?? join(ASSETS, "neutral.png"),
+				...(discord.refusalHint === undefined
+					? {}
+					: { refusalHint: discord.refusalHint }),
 			}),
 			modulesPlugin({
 				owner,
@@ -161,8 +179,18 @@ export async function defineRoundtable(
 				agentDir: config.agentDir,
 				dataDir: config.dataDir,
 				delegation: config.delegation,
-				...overrides.modules,
 			}),
+			...(discord.admin ? [discordAdminPlugin({ owner })] : []),
+			...(config.skills
+				? [
+						skillsPlugin({
+							guildId: discord.guild,
+							reposDir: config.skills.reposDir ?? join(config.dataDir, "repos"),
+							writtenDir: join(config.dataDir, "skills"),
+							builtinDir: config.skills.builtinDir ?? join(ASSETS, "skills"),
+						}),
+					]
+				: []),
 			agentServerPlugin({
 				guildId: discord.guild,
 				entryChannelId: discord.entryChannel,
@@ -178,14 +206,10 @@ export async function defineRoundtable(
 				workDir: config.workDir,
 				shellUser: userInfo().username,
 				prompts: { shared, guest },
-				skills: {
-					reposDir: config.skills.reposDir ?? join(config.dataDir, "repos"),
-					writtenDir: join(config.dataDir, "skills"),
-					builtinDir: config.skills.builtinDir ?? join(ASSETS, "skills"),
-				},
 				avatarListener: "public",
+				avatarUrl: config.http.publicUrl,
+				avatarReference: config.avatar ?? join(ASSETS, "neutral.png"),
 				...(errorReporter ? { errorReporter } : {}),
-				...overrides.agentServer,
 			}),
 			seedsPlugin(config.agents),
 			...config.plugins,

package/src/core/define.ts

@@ -1,7 +1,7 @@
 import type { Static, TObject } from "typebox";
 import { PluginError } from "./errors.ts";
 import type { HoldRule } from "./holds.ts";
-import type { RoundtablePlugin } from "./plugin.ts";
+import { type RoundtablePlugin, refuseRemovedFields } from "./plugin.ts";
 import type { AgentTurnScope, ChannelKey, SessionTool } from "./sessions.ts";
 import { toolError, toolText } from "./shared/tool-result.ts";
 import { type Speaker, TIERS, type Tier } from "./speakers.ts";
@@ -150,5 +150,6 @@ export function definePlugin(plugin: RoundtablePlugin): RoundtablePlugin {
 		throw new PluginError(
 			`plugin ${plugin.name}: setup is missing. Give the function that returns what the plugin adds.`,
 		);
+	refuseRemovedFields(plugin);
 	return plugin;
 }

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

@@ -22,23 +22,26 @@ import {
 } from "discord.js";
 import {
 	type Agent,
-	type AgentStore,
 	MAX_AVATAR_PROMPT_CHARS,
 	MAX_PROMPT_CHARS,
 } from "../agents/agent-store.ts";
-import type { AgentTeam } from "../agents/agent-team.ts";
 import type { AvatarMode } from "../agents/agent-tools.ts";
-import type { AvatarStudio } from "../agents/avatar-studio.ts";
 import { AgentError } from "../domain/errors.ts";
 import { messages } from "../i18n/index.ts";
 import { THINKING_LEVELS, thinkingLabel } from "../models.ts";
 import {
 	BUILTIN_SKILLS,
-	type SkillRegistry,
 	type SkillSet,
 } from "../modules/skills/skill-registry.ts";
+import type {
+	AgentDirectory,
+	AgentTeam,
+	AvatarStudio,
+	SkillRegistry,
+} from "../services.ts";
 import { OwnerFacingError, ownerPanel } from "./owner-panel.ts";
 
+/** The custom-id prefixes of the panel's buttons and forms; posted panels carry them, so they never change. */
 export const AGENT_BUTTON_PREFIX = "roundtable:agent:";
 export const AGENT_MODAL_PREFIX = "roundtable:agent-modal:";
 /** A prompt this long goes out as a file, so the panel stays inside Discord's text limit. */
@@ -75,13 +78,22 @@ const ACTIONS: readonly Action[] = [
 ];
 
 export interface AgentCommandsOptions {
-	store: Pick<AgentStore, "agentByChannel" | "groupByChannel" | "agent">;
+	store: Pick<AgentDirectory, "agentByChannel" | "groupByChannel" | "agent">;
 	team: Pick<
 		AgentTeam,
 		"redrawAvatar" | "update" | "modelOf" | "usableModels" | "defaultModel"
 	>;
-	studio: Pick<AvatarStudio, "url">;
-	skills: Pick<SkillRegistry, "carried">;
+	studio: Pick<AvatarStudio, "url" | "canDraw">;
+	/** The skills an agent carries; without the skills addon the panel lists none. */
+	skills?: Pick<SkillRegistry, "carried">;
+}
+
+/** An agent's panel as a message: one Components V2 container, with the prompt attached as a file when it is long. */
+export interface AgentPanelMessage {
+	components: ContainerBuilder[];
+	flags: MessageFlags.IsComponentsV2;
+	allowedMentions: { parse: never[] };
+	files: AttachmentBuilder[];
 }
 
 /** The skills line of the panel: built-in ones marked, missing ones with their reason. */
@@ -107,7 +119,7 @@ export class AgentCommands {
 	}
 
 	/** The panel for the agent of a channel; an error when the channel has none. */
-	panel(channelId: string, note?: string) {
+	panel(channelId: string, note?: string): AgentPanelMessage {
 		const { store } = this.#options;
 		const agent = store.agentByChannel(channelId);
 		if (!agent)
@@ -119,8 +131,10 @@ export class AgentCommands {
 		return this.#panel(agent, note);
 	}
 
-	#panel(agent: Agent, note?: string) {
+	#panel(agent: Agent, note?: string): AgentPanelMessage {
 		const text = messages();
+		// Without an image provider nothing can be drawn, so the avatar buttons are not offered.
+		const drawing = this.#options.studio.canDraw;
 		const inline = agent.prompt.length <= INLINE_PROMPT_CHARS;
 		const { model, thinking } = this.#options.team.modelOf(agent.name);
 		const follows =
@@ -136,7 +150,12 @@ export class AgentCommands {
 						model,
 						thinking: thinkingLabel(thinking),
 						follows,
-						skills: skillsText(this.#options.skills.carried(agent.name)),
+						skills: skillsText(
+							this.#options.skills?.carried(agent.name) ?? {
+								skills: [],
+								missing: [],
+							},
+						),
 					}),
 				),
 			)
@@ -149,7 +168,9 @@ export class AgentCommands {
 			)
 			.addTextDisplayComponents(
 				new TextDisplayBuilder().setContent(
-					text.agentAvatarPromptText(agent.avatarPrompt),
+					drawing
+						? text.agentAvatarPromptText(agent.avatarPrompt)
+						: text.agentNoImageProvider,
 				),
 				new TextDisplayBuilder().setContent(
 					inline
@@ -177,9 +198,13 @@ export class AgentCommands {
 			.addActionRowComponents(
 				new ActionRowBuilder<ButtonBuilder>().addComponents(
 					button("edit", text.agentEditPromptLabel, ButtonStyle.Primary),
-					button("redraw", text.agentRedrawLabel),
-					button("newprompt", text.agentNewAvatarPromptLabel),
-					button("editavatar", text.agentEditAvatarLabel),
+					...(drawing
+						? [
+								button("redraw", text.agentRedrawLabel),
+								button("newprompt", text.agentNewAvatarPromptLabel),
+								button("editavatar", text.agentEditAvatarLabel),
+							]
+						: []),
 					button("model", text.agentModelLabel),
 				),
 			)

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

@@ -0,0 +1,66 @@
+import { type Interaction, MessageFlags } from "discord.js";
+import type { AgentServer, SkillRegistry } from "../services.ts";
+import {
+	AGENT_BUTTON_PREFIX,
+	AGENT_MODAL_PREFIX,
+	AgentCommands,
+	type AgentPanelMessage,
+} from "./agent-commands.ts";
+import type { CommandGuard } from "./interaction-module.ts";
+
+export interface AgentPanelOptions {
+	/** Who may press the panel's buttons and submit its forms. */
+	guard: CommandGuard;
+	/** The agent server whose agents the panel shows and edits. */
+	agents: AgentServer;
+	/** The skills an agent carries, listed in the panel; without it the panel lists none. */
+	skills?: Pick<SkillRegistry, "carried">;
+}
+
+/** An agent's panel: its prompt, picture, model, and skills, with buttons and forms to change them. */
+export interface AgentPanel {
+	/**
+	 * The panel of the agent whose channel this is. Throws OwnerFacingError, which a command run
+	 * through the guard answers as a panel, when the channel belongs to no agent.
+	 */
+	open(channelId: string): AgentPanelMessage;
+	/**
+	 * Answers the panel's own buttons and form, for the owner only and deferred as Discord needs;
+	 * true when it handled the interaction. The custom ids are fixed, so panels already posted keep working.
+	 */
+	handles(interaction: Interaction): Promise<boolean>;
+}
+
+/** Builds the agent panel of `/<root> profile`; the caller adds the subcommand and routes the panel's components here. */
+export function agentPanel(options: AgentPanelOptions): AgentPanel {
+	const { guard, agents } = options;
+	const commands = new AgentCommands({
+		store: agents.directory,
+		team: agents.team,
+		studio: agents.avatars,
+		...(options.skills ? { skills: options.skills } : {}),
+	});
+	return {
+		open: (channelId) => commands.panel(channelId),
+		async handles(interaction) {
+			if (
+				interaction.isButton() &&
+				interaction.customId.startsWith(AGENT_BUTTON_PREFIX)
+			) {
+				if (!guard.isOwner(interaction)) return true;
+				await guard.run(interaction, () => commands.button(interaction));
+				return true;
+			}
+			if (
+				interaction.isModalSubmit() &&
+				interaction.customId.startsWith(AGENT_MODAL_PREFIX)
+			) {
+				if (!guard.isOwner(interaction)) return true;
+				await interaction.deferReply({ flags: MessageFlags.Ephemeral });
+				await guard.run(interaction, () => commands.submit(interaction));
+				return true;
+			}
+			return false;
+		},
+	};
+}

package/src/core/discord/channel-executor.ts

@@ -11,6 +11,7 @@ import {
 	type PermissionResolvable,
 	type TextChannel,
 } from "discord.js";
+import { freeze } from "../freeze.ts";
 import type { ChannelOperation } from "./channel-operations.ts";
 import {
 	type ChannelExecutor,
@@ -18,7 +19,9 @@ import {
 } from "./channel-operations.ts";
 
 /** Discord permissions the bot (and the owner granting it) needs for each operation. */
-export const OPERATION_PERMISSIONS: Record<ChannelOperation, bigint[]> = {
+export const OPERATION_PERMISSIONS: Readonly<
+	Record<ChannelOperation, readonly bigint[]>
+> = freeze({
 	read: [
 		PermissionFlagsBits.ViewChannel,
 		PermissionFlagsBits.ReadMessageHistory,
@@ -47,7 +50,7 @@ export const OPERATION_PERMISSIONS: Record<ChannelOperation, bigint[]> = {
 		PermissionFlagsBits.ViewChannel,
 		PermissionFlagsBits.ManageRoles,
 	],
-};
+});
 
 export type ManagedChannel = TextChannel | NewsChannel;
 /** What the owner's own agent may also reach: threads of those channels. */
@@ -93,7 +96,7 @@ export function operationPermissions(
 					? PermissionFlagsBits.SendMessagesInThreads
 					: flag,
 			)
-		: needed;
+		: [...needed];
 }
 
 interface ChannelFile {

package/src/core/discord/channel-operations.ts

@@ -1,9 +1,10 @@
-import { type TObject, Type } from "typebox";
+import { type TSchema, Type } from "typebox";
 import Value from "typebox/value";
+import { freeze } from "../freeze.ts";
 import { type Messages, messages } from "../i18n/index.ts";
 
 /** What a call may do in one channel, with the owner-facing label; grants and permission checks name these. */
-export const CHANNEL_OPERATIONS = [
+export const CHANNEL_OPERATIONS = Object.freeze([
 	"read",
 	"send",
 	"edit",
@@ -11,7 +12,7 @@ export const CHANNEL_OPERATIONS = [
 	"delete",
 	"channel",
 	"permissions",
-] as const;
+] as const);
 export type ChannelOperation = (typeof CHANNEL_OPERATIONS)[number];
 
 export const isChannelOperation = (value: string): value is ChannelOperation =>
@@ -37,7 +38,7 @@ const message = { channelId: id, messageId: id };
 const strict = { additionalProperties: false } as const;
 
 /** One upload may carry at most this much, in all files together. */
-export const CHANNEL_UPLOAD_MAX_BYTES = 8 * 1024 * 1024;
+const CHANNEL_UPLOAD_MAX_BYTES = 8 * 1024 * 1024;
 
 const file = Type.Object(
 	{
@@ -69,14 +70,16 @@ const files = Type.Optional(
 	}),
 );
 
-interface ChannelTool {
-	operation: ChannelOperation;
-	schema: TObject;
-	description: string;
+export interface ChannelTool {
+	readonly operation: ChannelOperation;
+	readonly schema: Readonly<TSchema>;
+	readonly description: string;
 }
 
-/** The Discord tools a bundle can expose, each gated by one operation. */
-export const CHANNEL_TOOLS: Record<string, ChannelTool> = {
+/** Discord tool descriptions and schemas, each gated by one channel operation. */
+export const CHANNEL_TOOLS: Readonly<Record<string, ChannelTool>> = freeze<
+	Record<string, ChannelTool>
+>({
 	discord_get_channel_info: {
 		operation: "read",
 		schema: Type.Object(channel, strict),
@@ -246,7 +249,7 @@ export const CHANNEL_TOOLS: Record<string, ChannelTool> = {
 		description:
 			"Remove a role's or member's permission overwrite in this channel.",
 	},
-};
+});
 
 /** A tool call that cannot be run as asked; the code is safe to show the caller. */
 export class ChannelToolError extends Error {

package/src/core/discord/command-collection.ts

@@ -0,0 +1,46 @@
+import { PluginError } from "../errors.ts";
+import { type ComposedCommands, composeCommands } from "./compose-commands.ts";
+import type {
+	CommandRegistrar,
+	CommandRoot,
+	InteractionContribution,
+} from "./interaction-module.ts";
+
+/**
+ * The commands the plugins add while they set up, composed once under the root command. Adding
+ * after the composition is refused, because Discord registers the commands as it connects and a
+ * late one would never reach it.
+ */
+export class CommandCollection {
+	readonly #contributions: InteractionContribution[] = [];
+	#closed = false;
+
+	/** What plugins reach as `DISCORD.commands`. */
+	readonly registrar: CommandRegistrar = {
+		add: (contribution) => {
+			if (this.#closed)
+				throw new PluginError(
+					"commands can be added only while plugins set up: the Discord plugin composed them in its preflight, before any service started. Call commands.add from setup.",
+				);
+			if (
+				typeof contribution?.module?.commands !== "function" ||
+				typeof contribution.module.handle !== "function"
+			)
+				throw new PluginError(
+					"commands.add takes { module, rootOptions? }, where the module has commands() and handle(interaction).",
+				);
+			this.#contributions.push(contribution);
+		},
+	};
+
+	/** Every contribution added so far, in the order added. */
+	added(): readonly InteractionContribution[] {
+		return this.#contributions;
+	}
+
+	/** Composes every added contribution, in the order added; closes the collection to later additions. */
+	compose(root: CommandRoot): ComposedCommands {
+		this.#closed = true;
+		return composeCommands(root, this.#contributions);
+	}
+}

package/src/core/{registry/interactions.ts → discord/compose-commands.ts}

@@ -2,15 +2,15 @@ import {
 	type RESTPostAPIChatInputApplicationCommandsJSONBody,
 	SlashCommandBuilder,
 } from "discord.js";
+import { PluginError } from "../errors.ts";
 import type {
 	CommandRoot,
 	InteractionContribution,
 	InteractionModule,
-} from "../contract/discord.ts";
-import { PluginError } from "../errors.ts";
+} from "./interaction-module.ts";
 
 /** Every command to register with Discord, and the modules that answer them in order. */
-export interface ComposedInteractions {
+export interface ComposedCommands {
 	commands: RESTPostAPIChatInputApplicationCommandsJSONBody[];
 	modules: InteractionModule[];
 }
@@ -20,10 +20,10 @@ export interface ComposedInteractions {
  * the modules' own commands. Refuses a module that registers the root itself, and any command or
  * subcommand name used twice.
  */
-export function composeInteractions(
+export function composeCommands(
 	root: CommandRoot,
 	contributions: readonly InteractionContribution[],
-): ComposedInteractions {
+): ComposedCommands {
 	const commands = contributions.flatMap(({ module }) => module.commands());
 	const names = new Set<string>();
 	for (const command of commands) {

package/src/core/discord/connection.ts

@@ -0,0 +1,35 @@
+import type { AgentChannels, DashboardBoard } from "../agents/agent-ports.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { OwnerOperations } from "../modules/discord-admin/discord-admin.ts";
+import type { ChannelExecutor } from "./channel-operations.ts";
+import type { ThreadHost } from "./dispatch-threads.ts";
+
+/** What Discord calls a channel, for the web app's lists. */
+export type ChannelInfo =
+	| { kind: "dm"; name: string }
+	| { kind: "guild"; name: string; guild: string; guildId: string };
+
+/** The Discord connection as plugins use it, apart from the chat surface the host drives. */
+export interface DiscordConnection {
+	/** The owner's direct-message channel. */
+	ownerChannel(): Promise<ChannelKey>;
+	/** Sends the owner a direct message. */
+	notifyOwner(text: string): Promise<void>;
+	/**
+	 * What a channel is called: undefined when Discord no longer knows it; throws while the
+	 * connection is not ready or Discord cannot be reached.
+	 */
+	channelInfo(channelId: string): Promise<ChannelInfo | undefined>;
+	/** Channel operations for outside agents; undefined until the connection is ready. */
+	channelExecutor(): ChannelExecutor | undefined;
+	/** Reports deleted server channels by id; register before the connection starts. */
+	onChannelDeleted(listener: (channelId: string) => void): void;
+	/** The agent server's channels and webhooks. */
+	agentChannels(guildId: string): AgentChannels;
+	/** The agent server's `#dashboard` and its pinned status message. */
+	agentDashboard(guildId: string): DashboardBoard;
+	/** Threads for background dispatches, in the channel that started each. */
+	threadHost(): ThreadHost;
+	/** Discord reading and management for the owner's agent; calls fail until the connection is ready. */
+	ownerOperations(): OwnerOperations;
+}