pi-roundtable 0.1.0

package/src/core/agents/agent-guild.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { SQL } from "bun";
+import { migrate } from "../db/migrations.ts";
+import { SkillStore } from "../modules/skills/skill-store.ts";
+import {
+	describeDb,
+	migratedPool,
+	TEST_GUILD,
+	testDatabaseUrl,
+} from "../testing/database.ts";
+import { AgentStore } from "./agent-store.ts";
+
+const OTHER_GUILD = "900000000000000002";
+const TABLES = [
+	"agents",
+	"agent_groups",
+	"agent_group_messages",
+	"agent_group_cursors",
+	"agent_skills",
+];
+
+// Runs against a real PostgreSQL, only when ROUNDTABLE_TEST_DATABASE_URL is set.
+describeDb("guild scoping", () => {
+	let sql: SQL;
+
+	beforeEach(async () => {
+		const admin = new SQL(testDatabaseUrl);
+		for (const table of TABLES)
+			await admin.unsafe(`DROP TABLE IF EXISTS ${table}`);
+		await admin.close();
+		// The tables as they were before rows carried a guild, with rows in every one.
+		sql = await migratedPool(AgentStore.migration, SkillStore.migration);
+		await sql`INSERT INTO agents (name, display_name, prompt, avatar_prompt, channel_id)
+			VALUES ('infra', 'Infra', 'p', 'a', '10'), ('doctor', 'Doctor', 'p', 'a', '11')`;
+		await sql`INSERT INTO agent_groups (name, display_name, channel_id, members, host)
+			VALUES ('ops', 'Ops', '20', 'infra,doctor', 'infra')`;
+		await sql`INSERT INTO agent_group_messages (group_name, author, author_name, text)
+			VALUES ('ops', 'owner', 'Riley', 'hi')`;
+		await sql`INSERT INTO agent_group_cursors (group_name, agent_name, last_id)
+			VALUES ('ops', 'infra', 1)`;
+		await sql`INSERT INTO agent_skills (agent, skill) VALUES ('infra', 'ops-skill')`;
+	});
+
+	afterEach(async () => {
+		await sql.close();
+	});
+
+	const upgrade = (guild: string) =>
+		migrate(sql, [
+			...AgentStore.migrations(guild),
+			...SkillStore.migrations(guild),
+		]);
+
+	test("existing rows of every table go to the configured guild", async () => {
+		await upgrade(TEST_GUILD);
+		for (const table of TABLES) {
+			const rows: { guild_id: string }[] = await sql.unsafe(
+				`SELECT guild_id FROM ${table}`,
+			);
+			expect(rows.length).toBeGreaterThan(0);
+			expect(new Set(rows.map((r) => r.guild_id))).toEqual(
+				new Set([TEST_GUILD]),
+			);
+		}
+		const store = await AgentStore.attach(sql, TEST_GUILD);
+		expect(store.agents().map((a) => a.name)).toEqual(["infra", "doctor"]);
+		expect(store.group("ops")?.members).toEqual(["infra", "doctor"]);
+		expect(
+			(await store.recentGroupMessages("ops", 5)).map((m) => m.text),
+		).toEqual(["hi"]);
+		expect((await store.backlog("ops", "doctor", 40)).messages).toHaveLength(1);
+		const skills = await SkillStore.attach(sql, TEST_GUILD);
+		expect(skills.carriedBy("infra")).toEqual(["ops-skill"]);
+	});
+
+	test("running the migration again changes nothing", async () => {
+		await upgrade(TEST_GUILD);
+		const before = await sql`SELECT * FROM agents ORDER BY name`;
+		await upgrade(TEST_GUILD);
+		expect(await sql`SELECT * FROM agents ORDER BY name`).toEqual(before);
+	});
+
+	test("a guild sees only its own rows and may reuse a name of another", async () => {
+		await upgrade(TEST_GUILD);
+		const other = await AgentStore.attach(sql, OTHER_GUILD);
+		expect(other.agents()).toEqual([]);
+		expect(other.groups()).toEqual([]);
+		for (const name of ["infra", "doctor"])
+			await other.createAgent({
+				name,
+				displayName: `Other ${name}`,
+				prompt: "p",
+				avatarPrompt: "a",
+				channelId: `3${name.length}`,
+			});
+		await other.createGroup({
+			name: "ops",
+			displayName: "Other Ops",
+			channelId: "40",
+			members: ["infra", "doctor"],
+			host: "infra",
+		});
+		const mine = await AgentStore.attach(sql, TEST_GUILD);
+		expect(mine.agent("infra")?.displayName).toBe("Infra");
+		const reopened = await AgentStore.attach(sql, OTHER_GUILD);
+		expect(reopened.agent("infra")?.displayName).toBe("Other infra");
+		expect(reopened.group("ops")?.displayName).toBe("Other Ops");
+		// Messages and cursors of one guild's group are not the other's.
+		await other.appendGroupMessage("ops", {
+			author: "owner",
+			authorName: "X",
+			text: "elsewhere",
+		});
+		expect(
+			(await mine.recentGroupMessages("ops", 5)).map((m) => m.text),
+		).toEqual(["hi"]);
+	});
+
+	test("a name is still unique inside its guild", async () => {
+		await upgrade(TEST_GUILD);
+		const store = await AgentStore.attach(sql, TEST_GUILD);
+		expect(() => store.checkNewName("infra")).toThrow(/taken/);
+	});
+});

package/src/core/agents/agent-messages.ts

@@ -0,0 +1,189 @@
+import { AgentError } from "../domain/errors.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import { messages } from "../i18n/index.ts";
+import { splitReply } from "../presentation/reply-splitter.ts";
+import { addressee } from "../speakers.ts";
+import {
+	agentFailureText,
+	agentMessageText,
+	agentReplyText,
+	chainLimitReason,
+	deliveredMessagePost,
+	returnedAnswerPost,
+} from "./agent-prompt.ts";
+import type { Agent } from "./agent-store.ts";
+import { channelKey, homeScope } from "./team-keys.ts";
+import {
+	type Chain,
+	type Exchange,
+	MAX_CHAIN_MESSAGES,
+	type TurnHost,
+} from "./team-turn-types.ts";
+
+/** Messages between agents: each runs the target's turn, then wakes the sender with the answer. */
+export class AgentMessages {
+	readonly #host: TurnHost;
+
+	constructor(host: TurnHost) {
+		this.#host = host;
+	}
+
+	message(caller: AgentTurnScope, to: string, text: string): string {
+		const { store, queue, logger } = this.#host.options;
+		if (to === caller.name)
+			throw new AgentError("message_agent is for other agents, not yourself.");
+		const target = store.activeAgent(to);
+		const sender = store.activeAgent(caller.name);
+		if (!target.channelId) throw new AgentError(`${to} has no channel yet.`);
+		// Every agent turn runs through #turn, which registers its chain; a message from anywhere
+		// else would start an uncounted chain, so it is refused.
+		const chain = this.#host.chains.get(caller.session);
+		if (!chain)
+			throw new AgentError(
+				"message_agent can only be used during an agent turn.",
+			);
+		if (chain.messages >= MAX_CHAIN_MESSAGES)
+			throw new AgentError(
+				chainLimitReason(addressee(chain.speaker, this.#host.options.owner)),
+			);
+		chain.messages += 1;
+		const targetChannel = channelKey(target.channelId);
+		const exchange = this.#openExchange(caller, sender, target, text);
+		void queue
+			.run(targetChannel, async () =>
+				this.#deliver(sender, target, text, chain, await exchange),
+			)
+			.catch((error: unknown) =>
+				logger.error(
+					{ from: sender.name, to: target.name, err: error },
+					"agent message not delivered",
+				),
+			);
+		logger.info(
+			{ from: sender.name, to: target.name, chain: chain.messages },
+			"agent message queued",
+		);
+		return `Sent to "${target.displayName}". It works in its own channel; its answer comes back to you as a new turn.`;
+	}
+
+	/**
+	 * Opens the message's thread in the sender's turn channel and posts the request there under
+	 * the sender's name; undefined where no thread opens. Never rejects.
+	 */
+	async #openExchange(
+		caller: AgentTurnScope,
+		sender: Agent,
+		target: Agent,
+		text: string,
+	): Promise<Exchange | undefined> {
+		const parent = this.#host.turnChannel(caller);
+		const thread = await this.#host.options.threads?.open(
+			parent,
+			`→ ${target.displayName}`,
+		);
+		if (!thread) return undefined;
+		await this.#host
+			.post(parent, this.#host.current(sender), {
+				chunks: splitReply(
+					deliveredMessagePost(this.#host.current(target), text),
+				),
+				threadId: thread.id,
+			})
+			.catch((error: unknown) =>
+				this.#host.options.logger.warn(
+					{ err: error },
+					"agent request not threaded",
+				),
+			);
+		return { parent, thread };
+	}
+
+	/** Runs the target's turn, then posts its answer and wakes the sender; closes the thread either way. */
+	async #deliver(
+		sender: Agent,
+		target: Agent,
+		text: string,
+		chain: Chain,
+		exchange: Exchange | undefined,
+	): Promise<void> {
+		try {
+			await this.#exchange(sender, target, text, chain, exchange);
+		} finally {
+			await exchange?.thread.close();
+		}
+	}
+
+	async #exchange(
+		sender: Agent,
+		target: Agent,
+		text: string,
+		chain: Chain,
+		exchange: Exchange | undefined,
+	): Promise<void> {
+		const { queue, logger } = this.#host.options;
+		const targetChannel = channelKey(target.channelId ?? "");
+		await this.#host.post(targetChannel, this.#host.current(sender), {
+			chunks: splitReply(
+				deliveredMessagePost(this.#host.current(target), text),
+			),
+		});
+		const result = await this.#host.turn(
+			target,
+			homeScope(target),
+			targetChannel,
+			agentMessageText(
+				this.#host.current(sender),
+				text,
+				addressee(chain.speaker, this.#host.options.owner),
+			),
+			chain,
+		);
+		const thread = exchange?.thread;
+		if (thread && !result.ok)
+			await thread.close(messages().agentNoReply(result.error.message));
+		const current = this.#host.options.store.agent(sender.name);
+		if (current?.status !== "active" || !current.channelId) return;
+		const senderChannel = channelKey(current.channelId);
+		// With a thread the answer goes there, leaving the sender's channel its own reply.
+		if (result.ok)
+			await this.#host
+				.post(exchange?.parent ?? senderChannel, this.#host.current(target), {
+					chunks: splitReply(returnedAnswerPost(result.text)),
+					...(thread ? { threadId: thread.id } : {}),
+				})
+				.catch((error: unknown) =>
+					logger.error({ err: error }, "agent answer not posted back"),
+				);
+		await thread?.close();
+		const followUp = result.ok
+			? agentReplyText(
+					addressee(chain.speaker, this.#host.options.owner),
+					this.#host.current(target),
+					result.text,
+					thread?.mention,
+				)
+			: agentFailureText(
+					addressee(chain.speaker, this.#host.options.owner),
+					this.#host.current(target),
+					result.error.message,
+					thread?.mention,
+				);
+		// The answer is a report back to the sender, so its turn may ask the owner on cards.
+		void queue
+			.run(senderChannel, () =>
+				this.#host.turn(
+					current,
+					homeScope(current),
+					senderChannel,
+					followUp,
+					chain,
+					{
+						interactive: true,
+					},
+				),
+			)
+			.catch((error: unknown) =>
+				logger.error({ err: error }, "agent follow-up failed"),
+			);
+	}
+}

package/src/core/agents/agent-ports.ts

@@ -0,0 +1,103 @@
+import type {
+	ChannelKey,
+	PendingConfirmation,
+	TurnResult,
+} from "../domain/conversation.ts";
+import type { TurnRequest } from "../domain/ports.ts";
+import type { ThinkingSetting } from "../models.ts";
+
+/** The part of the Pi runtime the agent team drives. */
+export interface AgentTurnRunner {
+	runTurn(request: TurnRequest): Promise<TurnResult>;
+	heldActions(session: ChannelKey): Promise<PendingConfirmation | undefined>;
+	startFresh(session: ChannelKey): Promise<void>;
+	/** Undefined until the conversation has run a turn since startup. */
+	contextUsage(session: ChannelKey): ContextUse | undefined;
+}
+
+/** One agent's message in a channel, posted under its name and avatar. */
+export interface AgentPost {
+	name: string;
+	avatarUrl: string;
+	/** The turn's thinking, posted first as a quiet line. */
+	thinking?: string;
+	chunks: string[];
+	files?: { name: string; data: Uint8Array }[];
+	/** A thread of the channel to post in instead, such as a dispatch's. */
+	threadId?: string;
+}
+
+/**
+ * A category's name. Agents live under `Agents` or `Agents-<suffix>`, groups under `Groups` or
+ * `Groups-<suffix>`, and archived ones, kept with their history, under `Archive`.
+ */
+export type AgentCategory = string;
+
+/** A category of the agent server and its channels, in server order. */
+export interface CategoryLayout {
+	/** Absent for a category still to be made. */
+	id?: string;
+	name: string;
+	channelIds: string[];
+}
+
+/** A message of the agent server as `channel_read` returns it. */
+export interface ChannelMessage {
+	id: string;
+	author: string;
+	at: Date;
+	text: string;
+	attachments: string[];
+}
+
+/** The agent server's channels as the agent team needs them. */
+export interface AgentChannels {
+	post(channelId: string, post: AgentPost): Promise<void>;
+	/** Creates a text channel under the category, made when missing; returns its id. */
+	createChannel(
+		name: string,
+		topic: string,
+		category: AgentCategory,
+	): Promise<string>;
+	/** Moves a channel into the category when it sits elsewhere; true when it moved. */
+	placeIn(channelId: string, category: AgentCategory): Promise<boolean>;
+	/** Every category of the server in order, each with its channels in order. */
+	layout(): Promise<CategoryLayout[]>;
+	/**
+	 * Puts the categories, and the channels in each, in this order, making categories without an
+	 * id; then deletes the categories of `remove` that hold no channel.
+	 */
+	arrange(layout: CategoryLayout[], remove: string[]): Promise<void>;
+	setTopic(channelId: string, topic: string): Promise<void>;
+	/** Deletes the assistant's webhook in the channel, when it has one; its past messages stay. */
+	removeWebhook(channelId: string): Promise<void>;
+	exists(channelId: string): Promise<boolean>;
+	/**
+	 * Up to `limit` messages of a text channel or thread of the agent server, oldest first: the
+	 * latest, or those around `around`. Other servers' channels are refused.
+	 */
+	read(
+		channelId: string,
+		options: { limit: number; around?: string },
+	): Promise<ChannelMessage[]>;
+}
+
+/** A conversation's context use after its latest turn, as Pi estimates it. */
+export interface ContextUse {
+	/** Null right after a compaction, until the next model response. */
+	tokens: number | null;
+	contextWindow: number;
+}
+
+/** The dashboard channel's one pinned message, made when missing and edited in place. */
+export interface DashboardBoard {
+	show(sections: string[]): Promise<void>;
+}
+
+/** The models an agent can run on, and the assistant's own, which unset agents follow. */
+export interface AgentModels {
+	/** The assistant's thinking is `auto`: the judge picks each turn's level. */
+	defaults: { model: string; thinking: ThinkingSetting };
+	/** Every model the host can run, as `<provider>/<id>`. */
+	usable(): Promise<string[]>;
+}

package/src/core/agents/agent-prompt.ts

@@ -0,0 +1,163 @@
+import { messages } from "../i18n/index.ts";
+import { type OwnerIdentity, ownerWords } from "../identity.ts";
+import { addressee, type Speaker } from "../speakers.ts";
+import type { Agent, AgentGroup, Backlog } from "./agent-store.ts";
+
+/**
+ * The base every agent turn starts with, followed by the agent's own prompt. `shared` is the
+ * prompt every persona shares, the assistant's included (persona/shared.md).
+ */
+export function agentSystemPrompt(input: {
+	agent: Agent;
+	/** The agent in the entry channel. */
+	coordinator?: Agent;
+	shared: string;
+	/** The shared prompt for a speaker who is not the owner, where `shared` speaks to the owner. */
+	guestShared?: string;
+	workDir: string;
+	owner: OwnerIdentity;
+	/** The host account the shell and file tools run as. */
+	shellUser: string;
+	group?: { group: AgentGroup; members: readonly Agent[] };
+	/** Who the turn is for; without one, or the owner, the prompt speaks to the owner. */
+	speaker?: Speaker;
+}): string {
+	const { agent, coordinator, shared, workDir, owner, shellUser, group } =
+		input;
+	const who = addressee(input.speaker, owner);
+	const o = ownerWords(owner);
+	const w = ownerWords(who);
+	const guest = input.speaker && input.speaker.tier !== "owner";
+	const parts = [
+		(guest && input.guestShared) || shared,
+		`You are "${agent.displayName}" (agent name \`${agent.name}\`), one of ${o.name}'s agents in ${o.his} Discord agent server. Each agent owns one channel and one conversation; you all share ${o.his} tools and ${o.his} memory.`,
+		roleText(agent, coordinator, who),
+		`The team: agent_list shows every agent and group; agent_get and agent_update read and improve any agent's prompt, display name, model, and thinking level, yours included; agent_create adds an agent with its own channel; agent_avatar redraws an avatar; schedule_list with agent reads another agent's schedules. A message marked as coming from another agent is that agent speaking, not ${w.name}; only ${w.name} approves held actions.`,
+		`Your shell and file tools run on ${o.his} VPS as the user ${shellUser}, in the shared workspace ${workDir}. Commands that are destructive or change the system, and writes outside the workspace, are held for ${w.his} confirmation: tell ${w.him} exactly what will run and ask ${w.him} to confirm.`,
+	];
+	if (group) {
+		const others = group.members
+			.filter((m) => m.name !== agent.name)
+			.map((m) => `"${m.displayName}"`)
+			.join(", ");
+		parts.push(
+			`You are now speaking in the group chat "${group.group.displayName}" with ${w.name} and ${others}. Each of your turns shows the group messages since your last turn. Speak only for yourself and add what your role brings; do not repeat what others said. To hand the next word to a member, mention them as @display name.`,
+		);
+	} else {
+		parts.push(
+			"message_agent hands a self-contained request to another agent; it answers later, and its answer comes back to you as a new turn.",
+		);
+	}
+	parts.push(`## Your role\n${agent.prompt}`);
+	if (input.speaker && input.speaker.tier !== "owner")
+		parts.push(speakerText(input.speaker, owner));
+	return parts.join("\n\n");
+}
+
+/**
+ * Says whom the turn is for when it is not the owner, after every operator text that names the
+ * owner, so those texts read as the owner's and this one decides who is addressed.
+ */
+function speakerText(speaker: Speaker, owner: OwnerIdentity): string {
+	const o = ownerWords(owner);
+	const w = ownerWords(addressee(speaker, owner));
+	return `## The current speaker\nYou are talking with ${speaker.name} (Discord user ${speaker.id}), who speaks at the ${speaker.tier} tier of this server, not with ${o.name}. The text above describes the server's owner, ${o.name}. Address ${w.name}, take ${w.his} answers and approvals, and read a tool description that names ${o.name} as ${w.name}. Your memory is ${w.his} own, not ${o.name}'s, and other people's memory is not yours to share. Tools above the ${speaker.tier} tier are not available to you this turn.`;
+}
+
+/** Who coordinates the team, so a specialist never takes that role (spec behavior 55). */
+function roleText(
+	agent: Agent,
+	coordinator: Agent | undefined,
+	addressed: OwnerIdentity,
+): string {
+	const o = ownerWords(addressed);
+	if (coordinator?.name === agent.name)
+		return `You are the team's coordinator: ${o.name}'s general requests come to you, and you hand specialist work to the agent that owns it.`;
+	const who = coordinator
+		? `The team's coordinator is "${coordinator.displayName}" (\`${coordinator.name}\`) in <#${coordinator.channelId}>.`
+		: "The team's coordinator is the agent in the server's entry channel.";
+	return `${who} You are a specialist: speak of yourself only as "${agent.displayName}", never as the coordinator. Team work ${o.name} asks of you directly, such as creating agents or groups, archiving, or arranging channels, you do in your own name. When your role below is empty or only a placeholder, ask ${o.him} what your job is before taking on other work.`;
+}
+
+/** What a target agent receives from message_agent. */
+export function agentMessageText(
+	from: Agent,
+	text: string,
+	who: OwnerIdentity,
+): string {
+	return `(Message from the agent "${from.displayName}" (\`${from.name}\`), not from ${who.name}. Answer it; your answer is posted in your channel and sent back to "${from.displayName}".)\n\n${text}`;
+}
+
+/** What the sender receives when the target has answered. */
+export function agentReplyText(
+	who: OwnerIdentity,
+	from: Agent,
+	text: string,
+	thread?: string,
+): string {
+	return `(The agent "${from.displayName}" (\`${from.name}\`) answered your message. Continue with it and tell ${who.name} what matters; your reply is posted in your channel.${threadNote(thread)})\n\n${text}`;
+}
+
+/** Where the exchange was posted, when it had a thread. */
+function threadNote(thread: string | undefined): string {
+	return thread
+		? ` The exchange is in the thread ${thread}, now archived; link it when useful.`
+		: "";
+}
+
+/** What the sender receives when the target could not answer. */
+export function agentFailureText(
+	who: OwnerIdentity,
+	from: Agent,
+	reason: string,
+	thread?: string,
+): string {
+	return `(The agent "${from.displayName}" (\`${from.name}\`) could not answer your message: ${reason}. Tell ${who.name} briefly, or try again later.${threadNote(thread)})`;
+}
+
+/** A new agent's first turn. */
+export function openingTaskText(
+	creator: Agent | undefined,
+	task: string,
+	who: OwnerIdentity,
+): string {
+	const by = creator ? `the agent "${creator.displayName}"` : who.name;
+	return `(You were just created by ${by}, and this is your channel. Introduce yourself in one or two sentences, then start on this task.)\n\n${task}`;
+}
+
+/**
+ * A group member's turn: the messages since its last turn, oldest first. The closing line
+ * names the speaker, so a message that addresses it is not read as its own.
+ */
+export function groupTurnText(
+	group: AgentGroup,
+	self: Agent,
+	backlog: Backlog,
+): string {
+	const skipped =
+		backlog.skipped > 0
+			? `; ${backlog.skipped} earlier messages are not shown`
+			: "";
+	const lines = backlog.messages.map((m) => `[${m.authorName}] ${m.text}`);
+	const body =
+		lines.length > 0
+			? lines.join("\n\n")
+			: "(No new messages since your last turn.)";
+	return `(Group chat "${group.displayName}": messages since your last turn, oldest first${skipped}.)\n\n${body}\n\n(You are ${self.displayName}, and it is your turn to speak in the group. Each bracketed name above is another speaker; a message mentioning @${self.displayName} is addressed to you.)`;
+}
+
+/** How a message_agent request appears in the target's channel. */
+export function deliveredMessagePost(to: Agent, text: string): string {
+	return messages().messageDelivered(to.displayName, text);
+}
+
+/** How the target's answer appears in the sender's channel. */
+export function returnedAnswerPost(text: string): string {
+	return messages().answerReturned(text);
+}
+
+/** Why a chain of agent messages stops without the owner in between. */
+export function chainLimitReason(who: OwnerIdentity): string {
+	const o = ownerWords(who);
+	return `This chain of agent messages has reached 8 messages without ${o.name} in between, so it is stopped. Tell ${o.him} what was done and ask whether to continue.`;
+}

package/src/core/agents/agent-rules.ts

@@ -0,0 +1,106 @@
+import { AgentError } from "../domain/errors.ts";
+import { THINKING_LEVELS, type ThinkingLevel } from "../models.ts";
+
+export const MAX_PROMPT_CHARS = 4_000;
+export const MAX_AVATAR_PROMPT_CHARS = 1_000;
+export const MIN_GROUP_MEMBERS = 2;
+export const MAX_GROUP_MEMBERS = 6;
+
+export type AgentStatus = "active" | "archived";
+
+/** One agent of the agent server. `name` never changes; `displayName` is what Discord shows. */
+export interface Agent {
+	name: string;
+	displayName: string;
+	prompt: string;
+	avatarPrompt: string;
+	/** The drawn picture's content hash, when one exists. */
+	avatarHash?: string;
+	/** Its channel in the agent server; a seed agent has none until one is created. */
+	channelId?: string;
+	/** `<provider>/<id>`; unset follows the assistant's model. */
+	model?: string;
+	/** Unset follows the assistant's thinking level. */
+	thinking?: ThinkingLevel;
+	status: AgentStatus;
+}
+
+export interface AgentGroup {
+	name: string;
+	displayName: string;
+	channelId: string;
+	/** Agent names in the group's order. */
+	members: string[];
+	host: string;
+	status: AgentStatus;
+}
+
+export interface AgentSeed {
+	name: string;
+	displayName: string;
+	prompt: string;
+	avatarPrompt: string;
+	channelId?: string;
+}
+
+export interface GroupMessage {
+	id: number;
+	/** `owner` or an agent name. */
+	author: string;
+	authorName: string;
+	text: string;
+	at: Date;
+}
+
+export interface Backlog {
+	messages: GroupMessage[];
+	/** Waiting messages older than the ones carried. */
+	skipped: number;
+	/** The newest waiting id, which the cursor moves to once they are delivered. */
+	lastId: number | undefined;
+}
+
+const RESERVED = /discord|clyde/i;
+
+export function checkAgentName(name: string): void {
+	if (!/^[a-z0-9-]{1,32}$/.test(name) || RESERVED.test(name))
+		throw new AgentError(
+			`"${name}" is not a usable name: use 1 to 32 lowercase letters, digits, and dashes, without "discord" or "clyde".`,
+		);
+}
+
+export function checkDisplayName(displayName: string): void {
+	const length = [...displayName.trim()].length;
+	if (length < 1 || length > 32 || RESERVED.test(displayName))
+		throw new AgentError(
+			`"${displayName}" is not a usable display name: use 1 to 32 characters, without "discord" or "clyde".`,
+		);
+}
+
+export function checkPrompt(prompt: string): void {
+	if (!prompt.trim() || prompt.length > MAX_PROMPT_CHARS)
+		throw new AgentError(
+			`A prompt must have 1 to ${MAX_PROMPT_CHARS} characters; this one has ${prompt.length}.`,
+		);
+}
+
+export function checkModelRef(model: string): void {
+	if (!/^[\w.-]+\/[\w.:/-]+$/.test(model))
+		throw new AgentError(
+			`"${model}" is not a model: write it as <provider>/<model>, such as openai-codex/gpt-6-sol.`,
+		);
+}
+
+export function checkThinking(level: string): asserts level is ThinkingLevel {
+	if (!THINKING_LEVELS.includes(level as ThinkingLevel))
+		throw new AgentError(
+			`"${level}" is not a thinking level; use one of ${THINKING_LEVELS.join(", ")}.`,
+		);
+}
+
+export function checkAvatarPrompt(prompt: string): void {
+	if (!prompt.trim() || prompt.length > MAX_AVATAR_PROMPT_CHARS)
+		throw new AgentError(
+			`An avatar prompt must have 1 to ${MAX_AVATAR_PROMPT_CHARS} characters; this one has ${prompt.length}.`,
+		);
+}