pi-roundtable 0.24.2 → 0.26.0

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

@@ -5,7 +5,7 @@ import type { ChannelKey, TurnResult } from "../domain/conversation.ts";
 import { AgentError, ScheduleError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
 import type { ThinkingSetting } from "../models.ts";
-import { SHELL_TOOLS } from "../modules/host-shell/shell-policy.ts";
+import type { PromptVersion } from "../modules/prompts/prompt-history.ts";
 import type { ResolvedSkill } from "../modules/skills/skill-rules.ts";
 import type { AgentChange, AgentTeam } from "../services.ts";
 import type { TurnSelection } from "../sessions.ts";
@@ -13,11 +13,9 @@ import { type Speaker, THE_SPEAKER } from "../speakers.ts";
 import { agentSystemPrompt } from "./agent-prompt.ts";
 import type { Agent } from "./agent-store.ts";
 import {
-	AGENT_TOOLS,
 	type AgentOps,
 	type AvatarMode,
 	agentToolsExtension,
-	MESSAGE_AGENT_TOOL,
 } from "./agent-tools.ts";
 import { TeamEditing } from "./team-editing.ts";
 import {
@@ -36,6 +34,7 @@ import {
 } from "./team-layout.ts";
 import { TeamLifecycle } from "./team-lifecycle.ts";
 import type { AgentTeamOptions, TeamContext } from "./team-options.ts";
+import { teamSelection } from "./team-selection.ts";
 import { type TeamStatus, teamStatus } from "./team-status.ts";
 import {
 	agentDetails,
@@ -137,22 +136,7 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 
 	/** The tools every agent turn runs with: the plugins', plus the shell and agent tools. */
 	selection(scope?: AgentTurnScope): TurnSelection {
-		const plugged = this.#options.pluginSelection();
-		return {
-			id: "agent",
-			tools: [
-				...new Set([
-					...plugged.tools,
-					...SHELL_TOOLS,
-					// Group members hand off by mentioning each other, so a group seat has no message_agent.
-					...AGENT_TOOLS.filter(
-						(tool) => !(scope?.group && tool === MESSAGE_AGENT_TOOL),
-					),
-					...(this.#options.pluginTools?.() ?? []),
-				]),
-			],
-			groups: plugged.groups,
-		};
+		return teamSelection(this.#options, scope);
 	}
 
 	/** The system prompt addition of an agent session, read before each of its runs. */
@@ -165,9 +149,14 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 			owner,
 			shellUser,
 			scratchDir,
+			agentTools,
 		} = this.#options;
 		const agent = store.agent(scope.name);
 		if (!agent) throw new AgentError(`no agent ${scope.name}`);
+		const shared =
+			typeof sharedPrompt === "function" ? sharedPrompt() : sharedPrompt;
+		const guest =
+			typeof guestPrompt === "function" ? guestPrompt() : guestPrompt;
 		const group = scope.group ? store.group(scope.group) : undefined;
 		const coordinator = coordinatorOf(store, this.#options);
 		const speaker = this.#turns.speakerOf(scope);
@@ -175,13 +164,14 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 			agent,
 			...(speaker ? { speaker } : {}),
 			...(coordinator ? { coordinator } : {}),
-			shared: sharedPrompt,
-			...(guestPrompt ? { guestShared: guestPrompt } : {}),
+			shared,
+			...(guest ? { guestShared: guest } : {}),
 			workDir,
 			owner,
 			shellUser,
 			...(scratchDir ? { scratchDir } : {}),
 			images: this.#images(),
+			...(agentTools ? { agentTools } : {}),
 			...(group
 				? {
 						group: {
@@ -292,14 +282,21 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		return this.#lifecycle.channelDeleted(channelId);
 	}
 
-	/**
-	 * Archives an agent or group like a deleted channel, then keeps its channel under Archive,
-	 * where no one owns it and so nothing answers.
-	 */
-	archive(caller: AgentTurnScope, name: string): Promise<string> {
+	/** Archives an agent or group like a deleted channel, keeping its channel under Archive. */
+	archive(caller: AgentTurnScope | undefined, name: string): Promise<string> {
 		return this.#lifecycle.archive(caller, name);
 	}
 
+	/** Returns an archived agent or group to the active ones; see `AgentTeam.restore`. */
+	restore(name: string): Promise<string> {
+		return this.#lifecycle.restore(name);
+	}
+
+	/** Deletes an archived agent or group for good; see `AgentTeam.remove`. */
+	remove(name: string, cleanup?: () => Promise<void>): Promise<string> {
+		return this.#lifecycle.remove(name, cleanup);
+	}
+
 	// ── Turns, run by TeamTurns ────────────────────────────────────────────
 
 	/**
@@ -442,8 +439,15 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 	 * Changes an agent's display name, prompt, model, or thinking level; `default` returns the
 	 * model or thinking level to the assistant's. A model must be one the host runs.
 	 */
-	update(name: string, change: AgentChange): Promise<string> {
-		return this.#editing.update(name, change);
+	update(name: string, change: AgentChange, by?: string): Promise<string> {
+		return this.#editing.update(name, change, by);
+	}
+
+	/** The changes of an agent's prompt, newest first. */
+	async promptHistory(name: string, limit?: number): Promise<PromptVersion[]> {
+		if (!this.#options.store.agent(name))
+			throw new AgentError(`There is no agent "${name}".`);
+		return this.#options.store.promptHistory(name, limit);
 	}
 
 	create(
@@ -453,6 +457,14 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		return this.#editing.create(caller, input);
 	}
 
+	/** An owner creates an agent outside any agent turn; see `AgentTeam.createAgent`. */
+	createAgent(
+		by: Speaker,
+		input: Parameters<TeamEditing["createFor"]>[1],
+	): Promise<Agent> {
+		return this.#editing.createFor(by, input);
+	}
+
 	/** Changes an agent's look; see `AgentTeam.dress`. */
 	dress(name: string, input: CharacterInput): Promise<Agent> {
 		return this.#editing.dress(name, input);
@@ -468,19 +480,15 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		return this.#editing.redrawAvatar(name, mode, text);
 	}
 
-	createGroup(input: {
-		name: string;
-		displayName: string;
-		members: string[];
-		host?: string;
-		category?: string;
-	}): Promise<string> {
+	createGroup(
+		input: Parameters<TeamEditing["createGroup"]>[0],
+	): Promise<string> {
 		return this.#editing.createGroup(input);
 	}
 
 	updateGroup(
 		name: string,
-		change: { displayName?: string; members?: string[]; host?: string },
+		change: Parameters<TeamEditing["updateGroup"]>[1],
 	): Promise<string> {
 		return this.#editing.updateGroup(name, change);
 	}

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

@@ -65,6 +65,8 @@ export interface AgentOps {
 			model?: string;
 			thinking?: string;
 		},
+		/** Who changes it: the agent whose turn asks, for the prompt history. */
+		by?: string,
 	): Promise<string>;
 	create(
 		caller: AgentTurnScope,
@@ -245,12 +247,16 @@ function toolDefs(
 				const prompt = optionalString(i, "prompt");
 				const model = optionalString(i, "model");
 				const thinking = optionalString(i, "thinking");
-				return ops.update(requiredString(i, "name"), {
-					...(displayName !== undefined ? { displayName } : {}),
-					...(prompt !== undefined ? { prompt } : {}),
-					...(model !== undefined ? { model } : {}),
-					...(thinking !== undefined ? { thinking } : {}),
-				});
+				return ops.update(
+					requiredString(i, "name"),
+					{
+						...(displayName !== undefined ? { displayName } : {}),
+						...(prompt !== undefined ? { prompt } : {}),
+						...(model !== undefined ? { model } : {}),
+						...(thinking !== undefined ? { thinking } : {}),
+					},
+					scope.name,
+				);
 			},
 		},
 		{

package/src/core/agents/team-editing.ts

@@ -5,16 +5,17 @@ import {
 	resolveCharacter,
 	suggestCharacter,
 } from "../../characters/index.ts";
+import { parseChannelKey } from "../contract/surface.ts";
 import { AgentError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
 import type { AgentChange } from "../services.ts";
-import { addressee } from "../speakers.ts";
+import { addressee, type Speaker } from "../speakers.ts";
 import { openingTaskText } from "./agent-prompt.ts";
 import { characterOf, overBase } from "./agent-rules.ts";
 import { modelSetting, thinkingSetting } from "./agent-settings.ts";
 import type { Agent } from "./agent-store.ts";
 import type { AvatarMode } from "./agent-tools.ts";
-import { discordKey, keysOf } from "./team-keys.ts";
+import { agentRoomKey, discordKey, keysOf, seatsOf } from "./team-keys.ts";
 import { groupTopic, teamCategory } from "./team-layout.ts";
 import type { TeamContext } from "./team-options.ts";
 
@@ -34,7 +35,11 @@ export class TeamEditing {
 	 * Changes an agent's display name, prompt, model, or thinking level; `default` returns the
 	 * model or thinking level to the assistant's. A model must be one the host runs.
 	 */
-	async update(name: string, change: AgentChange): Promise<string> {
+	async update(
+		name: string,
+		change: AgentChange,
+		by?: string,
+	): Promise<string> {
 		const { store, logger } = this.#ctx.options;
 		if (Object.values(change).every((value) => value === undefined))
 			throw new AgentError(
@@ -44,14 +49,18 @@ export class TeamEditing {
 			this.#ctx.options.models.usable(),
 		);
 		const thinking = thinkingSetting(change.thinking);
-		const agent = await store.updateAgent(name, {
-			...(change.displayName !== undefined
-				? { displayName: change.displayName }
-				: {}),
-			...(change.prompt !== undefined ? { prompt: change.prompt } : {}),
-			...(model !== undefined ? { model } : {}),
-			...(thinking !== undefined ? { thinking } : {}),
-		});
+		const agent = await store.updateAgent(
+			name,
+			{
+				...(change.displayName !== undefined
+					? { displayName: change.displayName }
+					: {}),
+				...(change.prompt !== undefined ? { prompt: change.prompt } : {}),
+				...(model !== undefined ? { model } : {}),
+				...(thinking !== undefined ? { thinking } : {}),
+			},
+			by,
+		);
 		logger.info(
 			{
 				agent: name,
@@ -72,6 +81,7 @@ export class TeamEditing {
 		return `Updated "${agent.displayName}" (${agent.name}); it applies from its next turn. It runs ${runs} with thinking ${level}.`;
 	}
 
+	/** The agent tool: an agent creates another, which starts on the opening task at once. */
 	async create(
 		caller: AgentTurnScope,
 		input: {
@@ -87,27 +97,109 @@ export class TeamEditing {
 			skills?: string[];
 		},
 	): Promise<string> {
-		const { store, studio, channels, queue, skills, surfaces, logger } =
-			this.#ctx.options;
-		if (input.skills && input.skills.length > 0 && !skills)
-			throw new AgentError(
-				"Skills are off on this host, so an agent cannot carry any. Create it without skills.",
-			);
+		this.#refuseSkillsOff(input.skills);
 		const speaker = this.#ctx.turns.speakerOf(caller);
 		if (!speaker)
 			throw new AgentError(
 				"agent_create can only be used during an agent turn.",
 			);
+		// The opening task starts on the surface the caller's turn runs on, as the web form's does.
+		const working = this.#ctx.turns.workingIn(caller.name);
+		const made = await this.#create(
+			{
+				speaker,
+				by: caller.name,
+				creator: this.#ctx.options.store.agent(caller.name),
+				openIn: working ? parseChannelKey(working).surface : undefined,
+			},
+			input,
+		);
+		return made.text;
+	}
+
+	/**
+	 * An owner creates an agent from outside any agent turn (the web app's form; any other tier is
+	 * refused, since the opening task runs as `speaker`): the same checks,
+	 * picture, channel and opening task as `create`, and the model and thinking level the owner
+	 * picked. Without a task the agent only exists, waiting in its room. Returns the new agent.
+	 */
+	async createFor(
+		speaker: Speaker,
+		input: {
+			name: string;
+			displayName: string;
+			prompt: string;
+			character?: CharacterInput;
+			task?: string;
+			openIn?: string;
+			category?: string;
+			skills?: string[];
+			model?: string;
+			thinking?: string;
+		},
+	): Promise<Agent> {
+		if (speaker.tier !== "owner")
+			throw new AgentError("Only an owner may create an agent here.");
+		const { model, thinking, task, openIn, ...rest } = input;
+		const made = await this.#create(
+			{ speaker, by: speaker.name, creator: undefined, openIn },
+			{ ...rest, ...(task ? { task } : {}) },
+			{ model, thinking },
+		);
+		return made.agent;
+	}
+
+	/** An agent cannot carry skills on a host with skills switched off. */
+	#refuseSkillsOff(carried: string[] | undefined): void {
+		if (carried && carried.length > 0 && !this.#ctx.options.skills)
+			throw new AgentError(
+				"Skills are off on this host, so an agent cannot carry any. Create it without skills.",
+			);
+	}
+
+	async #create(
+		who: {
+			speaker: Speaker;
+			by: string;
+			creator: Agent | undefined;
+			/** The surface whose room runs the opening task. */
+			openIn?: string | undefined;
+		},
+		input: {
+			name: string;
+			displayName: string;
+			prompt: string;
+			/** @deprecated Ignored: agents are composed characters. */
+			avatarPrompt?: string;
+			character?: CharacterInput;
+			task?: string;
+			category?: string;
+			skills?: string[];
+		},
+		settings: {
+			model?: string | undefined;
+			thinking?: string | undefined;
+		} = {},
+	): Promise<{ agent: Agent; text: string }> {
+		const { store, studio, channels, queue, skills, surfaces, logger } =
+			this.#ctx.options;
+		this.#refuseSkillsOff(input.skills);
 		const {
 			category,
 			skills: carried = [],
 			character: wanted,
 			avatarPrompt: _ignored,
+			task,
 			...fields
 		} = input;
 		const parent = teamCategory(category, "Agents");
 		store.checkNewName(input.name);
 		skills?.checkRegistered(carried);
+		// A model or thinking level the host cannot run fails the create, before anything is made.
+		const model = await modelSetting(settings.model, () =>
+			this.#ctx.options.models.usable(),
+		);
+		const thinking = thinkingSetting(settings.thinking);
 		// The picture comes before the row and the channel: a render failure fails the create.
 		const taken = store
 			.agents()
@@ -123,49 +215,69 @@ export class TeamEditing {
 			input.displayName,
 			parent,
 		);
-		const agent = await store.createAgent({
+		let agent = await store.createAgent({
 			...fields,
 			character,
 			avatarHash,
 			...(channelId ? { channelId } : {}),
 		});
+		if (model || thinking)
+			agent = await store.updateAgent(agent.name, {
+				...(model ? { model } : {}),
+				...(thinking ? { thinking } : {}),
+			});
 		if (skills && carried.length > 0)
 			await skills.attach(agent.name, carried, []);
 		logger.info(
-			{ agent: agent.name, by: caller.name, class: character.class },
+			{ agent: agent.name, by: who.by, class: character.class },
 			"agent created",
 		);
 		this.#ctx.changed();
 		const avatar = `its picture is the ${character.class} look`;
-		// The opening task runs where the agent is first reached: its channel, else its first room.
-		const home = channelId
-			? discordKey(channelId)
-			: keysOf(store, agent.name, surfaces?.roomSurfaces() ?? [])[0];
-		const creator = store.agent(caller.name);
 		const where = channelId ? ` in <#${channelId}>` : "";
+		if (!task)
+			return {
+				agent,
+				text: `Created "${agent.displayName}" (${agent.name})${where}; ${avatar}.`,
+			};
+		// The opening task runs in the room of the surface that asked, else where the agent is first
+		// reached: its channel, else its first room.
+		const rooms = surfaces?.roomSurfaces() ?? [];
+		const home =
+			who.openIn !== undefined && rooms.includes(who.openIn)
+				? agentRoomKey(who.openIn, agent.name)
+				: channelId
+					? discordKey(channelId)
+					: keysOf(store, agent.name, rooms)[0];
 		if (!home) {
 			logger.warn(
 				{ agent: agent.name },
 				"opening turn skipped: the agent has no channel or room",
 			);
-			return `Created "${agent.displayName}" (${agent.name})${where}; ${avatar}. It has no room to start its opening task in yet.`;
+			return {
+				agent,
+				text: `Created "${agent.displayName}" (${agent.name})${where}; ${avatar}. It has no room to start its opening task in yet.`,
+			};
 		}
 		void queue
 			.run(home, () =>
 				this.#ctx.turns.answerBackground(
 					home,
-					speaker,
+					who.speaker,
 					openingTaskText(
-						creator,
-						input.task,
-						addressee(speaker, this.#ctx.options.owner),
+						who.creator,
+						task,
+						addressee(who.speaker, this.#ctx.options.owner),
 					),
 				),
 			)
 			.catch((error: unknown) =>
 				logger.error({ agent: agent.name, err: error }, "opening turn failed"),
 			);
-		return `Created "${agent.displayName}" (${agent.name})${where}; ${avatar}. It is starting on its opening task now.`;
+		return {
+			agent,
+			text: `Created "${agent.displayName}" (${agent.name})${where}; ${avatar}. It is starting on its opening task now.`,
+		};
 	}
 
 	/** The agent tool: changes a look, then says what the owner sees. */
@@ -260,7 +372,7 @@ export class TeamEditing {
 			(input.members.includes("coordinator")
 				? "coordinator"
 				: (input.members[0] ?? ""));
-		store.checkNewGroup(input.name, input.members, host);
+		store.checkNewGroup(input.name, input.members, host, input.displayName);
 		const topic = groupTopic({ ...fields, host, status: "active" }, store);
 		const channelId = await channels?.createChannel(input.name, topic, parent);
 		const group = await store.createGroup({
@@ -277,7 +389,17 @@ export class TeamEditing {
 		name: string,
 		change: { displayName?: string; members?: string[]; host?: string },
 	): Promise<string> {
-		const group = await this.#ctx.options.store.updateGroup(name, change);
+		const { store, surfaces } = this.#ctx.options;
+		const before = store.group(name);
+		const group = await store.updateGroup(name, change);
+		// A member taken out starts its seat over, so an agent of that name that joins later
+		// does not resume the old conversation.
+		const runtime = this.#ctx.options.runtime();
+		const rooms = surfaces?.roomSurfaces() ?? [];
+		for (const left of before?.members ?? [])
+			if (!group.members.includes(left))
+				for (const seat of seatsOf(group, left, rooms))
+					await runtime.startFresh(seat);
 		this.#ctx.retitle(group);
 		this.#ctx.changed();
 		return `Updated the group "${group.displayName}": members ${group.members.join(", ")}; host ${group.host}.`;

package/src/core/agents/team-keys.ts

@@ -217,3 +217,20 @@ export function keysOf(
 		];
 	return [];
 }
+
+/**
+ * Every conversation of an agent's seat in a group: the Discord channel's, when the group has
+ * one, then each room's on `roomSurfaces`.
+ */
+export function seatsOf(
+	group: AgentGroup,
+	agent: string,
+	roomSurfaces: readonly string[],
+): ChannelKey[] {
+	return [
+		...(group.channelId ? [groupSessionKey(group, agent)] : []),
+		...roomSurfaces.map((surface) =>
+			groupSessionKey(group, agent, groupRoomKey(surface, group.name)),
+		),
+	];
+}

package/src/core/agents/team-lifecycle.ts

@@ -6,6 +6,7 @@ import {
 import type { ChannelKey } from "../domain/conversation.ts";
 import { AgentError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
+import { messages } from "../i18n/index.ts";
 import type { AgentChannels } from "./agent-ports.ts";
 import { overBase } from "./agent-rules.ts";
 import type { Agent, AgentGroup } from "./agent-store.ts";
@@ -16,11 +17,11 @@ import {
 	discordIdOf,
 	groupLogName,
 	groupOfChannel,
-	groupRoomKey,
 	groupSessionKey,
 	homeScope,
 	keysOf,
 	roomScope,
+	seatsOf,
 } from "./team-keys.ts";
 import { categoryKind, groupTopic } from "./team-layout.ts";
 import type { TeamContext } from "./team-options.ts";
@@ -193,9 +194,13 @@ export class TeamLifecycle {
 	 * Archives an agent or group like a deleted channel, then keeps its channel under Archive,
 	 * where no one owns it and so nothing answers; an agent or group without a Discord channel
 	 * only stops answering in its rooms. Runs at once, not in the target's queue: the caller may be
-	 * a member of the group it archives, and the round stops at its next turn.
+	 * a member of the group it archives, and the round stops at its next turn. An owner's call from
+	 * outside any turn has no `caller`, so no agent is protected from archiving itself.
 	 */
-	async archive(caller: AgentTurnScope, name: string): Promise<string> {
+	async archive(
+		caller: AgentTurnScope | undefined,
+		name: string,
+	): Promise<string> {
 		const { store, channels, logger } = this.#ctx.options;
 		const agent = store.agent(name);
 		const group = agent ? undefined : store.group(name);
@@ -208,7 +213,7 @@ export class TeamLifecycle {
 			throw new AgentError(`"${name}" is already archived.`);
 		if (agent && coordinatorOf(store, this.#ctx.options)?.name === name)
 			throw new AgentError("The coordinator cannot be archived.");
-		if (agent && name === caller.name)
+		if (agent && name === caller?.name)
 			throw new AgentError("You cannot archive yourself; ask another agent.");
 		const { channelId } = target;
 		if (agent) await this.#archiveAgent(agent);
@@ -232,6 +237,91 @@ export class TeamLifecycle {
 		return `Archived "${target.displayName}"; its channel <#${channelId}> is kept under Archive.`;
 	}
 
+	/**
+	 * Returns an archived agent or group to the active ones: its channel leaves Archive for its
+	 * category (a new channel replaces one deleted meanwhile), and it answers again from its next
+	 * message. An agent does not rejoin the groups it left; a group needs all its members active.
+	 */
+	async restore(name: string): Promise<string> {
+		const { store, channels, logger } = this.#ctx.options;
+		const agent = store.agent(name);
+		const group = agent ? undefined : store.group(name);
+		const target = agent ?? group;
+		if (!target)
+			throw new AgentError(
+				`There is no agent or group "${name}"; see agent_list.`,
+			);
+		if (target.status === "active")
+			throw new AgentError(`"${name}" is not archived.`);
+		if (group) store.checkRestorableGroup(name);
+		// The store checks again when it restores. A member archived, or a second restore of the
+		// same name, between the two checks leaves the channel moved or made with no owner; it
+		// then waits under its category until the next restore claims it or an owner deletes it.
+		let { channelId } = target;
+		if (channels) {
+			const category = agent ? "Agents" : "Groups";
+			if (channelId && (await channels.exists(channelId)))
+				await channels.placeIn(channelId, category);
+			else if (agent || channelId)
+				channelId = await channels.createChannel(
+					name,
+					agent ? agent.displayName : groupTopic(target as AgentGroup, store),
+					category,
+				);
+		}
+		if (agent) await store.restoreAgent(name, channelId);
+		else {
+			const restored = await store.restoreGroup(name, channelId);
+			this.retitle(restored);
+		}
+		logger.info({ name, kind: agent ? "agent" : "group" }, "restored");
+		this.#ctx.changed();
+		return `Restored "${target.displayName}"; it answers again.${agent ? " It is in no group until it is added to one." : ""}`;
+	}
+
+	/**
+	 * Deletes an archived agent or group for good, its name free again. Its carried skills are
+	 * detached, and the runtime forgets its conversations (an agent's own, its seats in every
+	 * group, a group's members' seats), so nothing is left for a later agent or group of that name;
+	 * a Discord channel it had stays under Archive with its history, since Discord is never asked
+	 * to delete one. An active agent or group is refused: archive it first, and so is an
+	 * agent the host's seeds name, since the next start would seed it again.
+	 */
+	async remove(name: string, cleanup?: () => Promise<void>): Promise<string> {
+		const { store, skills, seeds, logger } = this.#ctx.options;
+		const agent = store.agent(name);
+		const group = agent ? undefined : store.group(name);
+		const target = agent ?? group;
+		if (!target)
+			throw new AgentError(
+				`There is no agent or group "${name}"; see agent_list.`,
+			);
+		// Every start seeds the configured agents that are missing, so a deleted one would return.
+		if (agent && seeds().some((seed) => seed.name === name))
+			throw new AgentError(messages().agentSeededNotDeleted);
+		if (target.status === "active")
+			throw new AgentError(
+				`"${name}" is active; archive it before deleting it.`,
+			);
+		await cleanup?.();
+		// What a name keeps in the runtime would be picked up by the next agent or group made under it.
+		const runtime = this.#ctx.options.runtime();
+		const rooms = this.#rooms();
+		const seats = group
+			? group.members.flatMap((member) => seatsOf(group, member, rooms))
+			: store.groups().flatMap((other) => seatsOf(other, name, rooms));
+		const kept = [...keysOf(store, name, rooms), ...seats];
+		for (const key of kept) await runtime.deleteConversation(key);
+		if (agent) {
+			await store.deleteAgent(name);
+			const carried = skills?.carriedNames(name) ?? [];
+			if (skills && carried.length > 0) await skills.attach(name, [], carried);
+		} else await store.deleteGroup(name);
+		logger.info({ name, kind: agent ? "agent" : "group" }, "deleted");
+		this.#ctx.changed();
+		return `Deleted "${target.displayName}"; the name "${name}" is free again.`;
+	}
+
 	async #archiveAgent(agent: Agent): Promise<void> {
 		const { store, schedules, logger } = this.#ctx.options;
 		const runtime = this.#ctx.options.runtime();
@@ -244,7 +334,7 @@ export class TeamLifecycle {
 			await runtime.startFresh(key);
 		}
 		for (const group of left) {
-			for (const seat of this.#seats(group, agent.name, rooms))
+			for (const seat of seatsOf(group, agent.name, rooms))
 				await runtime.startFresh(seat);
 			if (group.status === "active") this.retitle(group);
 		}
@@ -261,7 +351,7 @@ export class TeamLifecycle {
 		const rooms = this.#rooms();
 		await store.archiveGroup(group.name);
 		for (const member of group.members)
-			for (const seat of this.#seats(group, member, rooms))
+			for (const seat of seatsOf(group, member, rooms))
 				await runtime.startFresh(seat);
 		logger.info({ group: group.name }, "group archived");
 		this.#ctx.changed();
@@ -272,23 +362,6 @@ export class TeamLifecycle {
 		return this.#ctx.options.surfaces?.roomSurfaces() ?? [];
 	}
 
-	/**
-	 * Every conversation of an agent's seat in a group: the Discord channel's, when the group has
-	 * one, then each room's.
-	 */
-	#seats(
-		group: AgentGroup,
-		agent: string,
-		rooms: readonly string[],
-	): ChannelKey[] {
-		return [
-			...(group.channelId ? [groupSessionKey(group, agent)] : []),
-			...rooms.map((surface) =>
-				groupSessionKey(group, agent, groupRoomKey(surface, group.name)),
-			),
-		];
-	}
-
 	/** Writes a group's members and host into its channel topic, without waiting on Discord; a group without a channel has no topic. */
 	retitle(group: AgentGroup): void {
 		const { channels, store, logger } = this.#ctx.options;