pi-roundtable 0.1.0

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

@@ -0,0 +1,205 @@
+import { AgentError } from "../domain/errors.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import { assistantName } from "../i18n/index.ts";
+import { addressee } from "../speakers.ts";
+import { openingTaskText } from "./agent-prompt.ts";
+import { modelSetting, thinkingSetting } from "./agent-settings.ts";
+import type { Agent } from "./agent-store.ts";
+import type { AvatarMode } from "./agent-tools.ts";
+import { channelKey } from "./team-keys.ts";
+import { groupTopic, teamCategory } from "./team-layout.ts";
+import type { TeamContext } from "./team-options.ts";
+
+/** Creating and changing agents, their avatars, and groups. */
+export class TeamEditing {
+	readonly #ctx: TeamContext;
+
+	constructor(ctx: TeamContext) {
+		this.#ctx = ctx;
+	}
+
+	/**
+	 * 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: {
+			displayName?: string;
+			prompt?: string;
+			model?: string;
+			thinking?: string;
+		},
+	): Promise<string> {
+		const { store, logger } = this.#ctx.options;
+		if (Object.values(change).every((value) => value === undefined))
+			throw new AgentError(
+				"Give display_name, prompt, model, or thinking to change.",
+			);
+		const model = await modelSetting(change.model, () =>
+			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 } : {}),
+		});
+		logger.info(
+			{
+				agent: name,
+				fields: Object.keys(change).filter(
+					(key) => change[key as keyof typeof change] !== undefined,
+				),
+				...(model !== undefined ? { model } : {}),
+				...(thinking !== undefined ? { thinking } : {}),
+			},
+			"agent updated",
+		);
+		if (change.displayName !== undefined)
+			for (const group of store.groups())
+				if (group.status === "active" && group.members.includes(name))
+					this.#ctx.retitle(group);
+		this.#ctx.changed();
+		const { model: runs, thinking: level } = this.#ctx.modelOf(name);
+		return `Updated "${agent.displayName}" (${agent.name}); it applies from its next turn. It runs ${runs} with thinking ${level}.`;
+	}
+
+	async create(
+		caller: AgentTurnScope,
+		input: {
+			name: string;
+			displayName: string;
+			prompt: string;
+			avatarPrompt: string;
+			task: string;
+			category?: string;
+			skills?: string[];
+		},
+	): Promise<string> {
+		const speaker = this.#ctx.turns.speakerOf(caller);
+		if (!speaker)
+			throw new AgentError(
+				"agent_create can only be used during an agent turn.",
+			);
+		const { store, channels, queue, skills, logger } = this.#ctx.options;
+		const { category, skills: carried = [], ...fields } = input;
+		const parent = teamCategory(category, "Agents");
+		store.checkNewName(input.name);
+		skills.checkRegistered(carried);
+		const channelId = await channels.createChannel(
+			input.name,
+			input.displayName,
+			parent,
+		);
+		const agent = await store.createAgent({ ...fields, channelId });
+		if (carried.length > 0) await skills.attach(agent.name, carried, []);
+		logger.info({ agent: agent.name, by: caller.name }, "agent created");
+		this.#ctx.changed();
+		const avatar = await this.#redraw(agent.name, "redraw").then(
+			() => "its avatar is drawn",
+			(error: unknown) =>
+				`its avatar could not be drawn (${error instanceof Error ? error.message : String(error)}), so it uses ${assistantName()}'s for now`,
+		);
+		const home = channelKey(channelId);
+		const creator = store.agent(caller.name);
+		void queue
+			.run(home, () =>
+				this.#ctx.turns.answerBackground(
+					home,
+					speaker,
+					openingTaskText(
+						creator,
+						input.task,
+						addressee(speaker, this.#ctx.options.owner),
+					),
+				),
+			)
+			.catch((error: unknown) =>
+				logger.error({ agent: agent.name, err: error }, "opening turn failed"),
+			);
+		return `Created "${agent.displayName}" (${agent.name}) in <#${channelId}>; ${avatar}. It is starting on its opening task now.`;
+	}
+
+	async avatar(name: string, mode: AvatarMode, text?: string): Promise<string> {
+		await this.#redraw(name, mode, text);
+		return `The new avatar of "${this.#ctx.options.store.agent(name)?.displayName ?? name}" shows from its next message.`;
+	}
+
+	/** Draws and stores a new picture; the owner's panel and the agent tool both use it. */
+	async redrawAvatar(
+		name: string,
+		mode: AvatarMode,
+		text?: string,
+	): Promise<Agent> {
+		return this.#redraw(name, mode, text);
+	}
+
+	async #redraw(name: string, mode: AvatarMode, text?: string): Promise<Agent> {
+		const { store, studio, logger } = this.#ctx.options;
+		const agent = store.activeAgent(name);
+		if (mode !== "redraw" && !text?.trim())
+			throw new AgentError(
+				mode === "edit"
+					? "Give the edit instruction as text."
+					: "Give the new avatar prompt as text.",
+			);
+		const avatarPrompt =
+			mode === "new_prompt" ? (text as string) : agent.avatarPrompt;
+		if (mode === "new_prompt") await store.updateAgent(name, { avatarPrompt });
+		let hash: string;
+		try {
+			hash =
+				mode === "edit"
+					? await studio.edit(agent.avatarHash, text as string)
+					: await studio.draw(avatarPrompt);
+		} catch (error) {
+			logger.warn({ agent: name, mode, err: error }, "avatar drawing failed");
+			throw new AgentError(
+				`The avatar could not be drawn: ${error instanceof Error ? error.message : String(error)}. The previous picture stays.`,
+			);
+		}
+		logger.info({ agent: name, mode }, "avatar redrawn");
+		return store.updateAgent(name, { avatarHash: hash });
+	}
+
+	async createGroup(input: {
+		name: string;
+		displayName: string;
+		members: string[];
+		host?: string;
+		category?: string;
+	}): Promise<string> {
+		const { store, channels, logger } = this.#ctx.options;
+		const { category, ...fields } = input;
+		const parent = teamCategory(category, "Groups");
+		const host =
+			input.host ??
+			(input.members.includes("coordinator")
+				? "coordinator"
+				: (input.members[0] ?? ""));
+		store.checkNewGroup(input.name, input.members, host);
+		const topic = groupTopic(
+			{ ...fields, host, channelId: "", status: "active" },
+			store,
+		);
+		const channelId = await channels.createChannel(input.name, topic, parent);
+		const group = await store.createGroup({ ...fields, host, channelId });
+		logger.info({ group: group.name, members: group.members }, "group created");
+		this.#ctx.changed();
+		return `Created the group "${group.displayName}" in <#${channelId}> with ${group.members.join(", ")}; host ${group.host}.`;
+	}
+
+	async updateGroup(
+		name: string,
+		change: { displayName?: string; members?: string[]; host?: string },
+	): Promise<string> {
+		const group = await this.#ctx.options.store.updateGroup(name, change);
+		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

@@ -0,0 +1,40 @@
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import type { Agent, AgentGroup, AgentStore } from "./agent-store.ts";
+
+export const channelKey = (channelId: string): ChannelKey =>
+	`discord:${channelId}`;
+
+export const channelIdOf = (channel: ChannelKey) =>
+	channel.slice("discord:".length);
+
+/** An agent's conversation inside a group, apart from its own. */
+export const groupSessionKey = (group: AgentGroup, agent: string): ChannelKey =>
+	`agentgroup:${group.channelId}.${agent}`;
+
+/** An agent's own conversation. */
+export function homeScope(agent: Agent): AgentTurnScope {
+	const home = channelKey(agent.channelId ?? "");
+	return { name: agent.name, session: home, home };
+}
+
+/** An agent's conversation inside a group. */
+export function groupScope(agent: Agent, group: AgentGroup): AgentTurnScope {
+	return {
+		name: agent.name,
+		session: groupSessionKey(group, agent.name),
+		home: channelKey(agent.channelId ?? ""),
+		group: group.name,
+	};
+}
+
+/** The agent or group that owns a channel of the agent server. */
+export function channelOwner(
+	store: Pick<AgentStore, "agentByChannel" | "groupByChannel">,
+	channel: ChannelKey,
+): "agent" | "group" | undefined {
+	const id = channelIdOf(channel);
+	if (store.agentByChannel(id)) return "agent";
+	if (store.groupByChannel(id)) return "group";
+	return undefined;
+}

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

@@ -0,0 +1,135 @@
+import { AgentError } from "../domain/errors.ts";
+import { messages } from "../i18n/index.ts";
+import type { CategoryLayout } from "./agent-ports.ts";
+import type { AgentGroup, AgentStore } from "./agent-store.ts";
+
+type TeamStore = Pick<
+	AgentStore,
+	"agent" | "group" | "agentByChannel" | "groupByChannel"
+>;
+
+/** The two kinds of team category (spec behavior 56). */
+export type CategoryKind = "Agents" | "Groups";
+const TEAM_CATEGORY = /^(Agents|Groups)(?:-[^\r\n]{1,32})?$/u;
+
+/** A team category's kind, or undefined for any other category. */
+export function categoryKind(name: string): CategoryKind | undefined {
+	return TEAM_CATEGORY.exec(name)?.[1] as CategoryKind | undefined;
+}
+
+/** The category a tool names for a channel of this kind, the plain one when absent. */
+export function teamCategory(
+	name: string | undefined,
+	kind: CategoryKind,
+): string {
+	if (name === undefined) return kind;
+	const found = categoryKind(name);
+	if (!found)
+		throw new AgentError(
+			`"${name}" is not a team category: use ${kind} or ${kind}-<suffix>, the suffix 1 to 32 characters on one line.`,
+		);
+	if (found !== kind)
+		throw new AgentError(
+			`"${name}" holds ${found === "Agents" ? "agents" : "groups"}; ${kind === "Agents" ? "an agent" : "a group"} goes under ${kind} or ${kind}-<suffix>.`,
+		);
+	return name;
+}
+
+/** A group channel's topic: who is in it and who hosts. */
+export function groupTopic(
+	group: AgentGroup,
+	store: Pick<AgentStore, "agent">,
+): string {
+	const shown = (name: string) => store.agent(name)?.displayName ?? name;
+	return messages().groupTopic(
+		group.displayName,
+		group.members.map(shown),
+		shown(group.host),
+	);
+}
+
+/** The team categories in server order, each with its channels by agent or group name. */
+export function layoutText(
+	layout: readonly CategoryLayout[],
+	store: TeamStore,
+): string {
+	const lines = layout
+		.filter((c) => categoryKind(c.name))
+		.map((c) => {
+			const shown = c.channelIds.map(
+				(id) =>
+					store.agentByChannel(id)?.name ??
+					store.groupByChannel(id)?.name ??
+					`<#${id}>`,
+			);
+			return `- ${c.name}: ${shown.join(", ") || "empty"}`;
+		});
+	return `Categories, in server order:\n${lines.join("\n") || "none"}`;
+}
+
+/** An arrange request's categories with the channels of the named agents and groups. */
+export function resolveArrangement(
+	entries: readonly { category: string; names: string[] }[],
+	store: TeamStore,
+): { category: string; channelIds: string[] }[] {
+	if (entries.length === 0) throw new AgentError("List at least one category.");
+	const categories = new Set<string>();
+	const names = new Set<string>();
+	return entries.map(({ category, names: members }) => {
+		if (categories.has(category))
+			throw new AgentError(`The category "${category}" is listed twice.`);
+		categories.add(category);
+		if (members.length === 0)
+			throw new AgentError(
+				`List at least one agent or group under "${category}".`,
+			);
+		const channelIds = members.map((name) => {
+			if (names.has(name)) throw new AgentError(`"${name}" is listed twice.`);
+			names.add(name);
+			const agent = store.agent(name);
+			const target = agent ?? store.group(name);
+			if (!target)
+				throw new AgentError(
+					`There is no agent or group "${name}"; see agent_list.`,
+				);
+			if (target.status !== "active")
+				throw new AgentError(`"${name}" is archived.`);
+			teamCategory(category, agent ? "Agents" : "Groups");
+			if (!target.channelId) throw new AgentError(`${name} has no channel.`);
+			return target.channelId;
+		});
+		return { category, channelIds };
+	});
+}
+
+/**
+ * The server layout after an arrangement: the listed categories and channels first, everything
+ * else after in its current order; and the team categories left empty, to delete.
+ */
+export function planArrangement(
+	listed: readonly { category: string; channelIds: string[] }[],
+	current: readonly CategoryLayout[],
+): { layout: CategoryLayout[]; remove: string[] } {
+	const moved = new Set(listed.flatMap((l) => l.channelIds));
+	const stay = (c: CategoryLayout) =>
+		c.channelIds.filter((id) => !moved.has(id));
+	const ahead: CategoryLayout[] = listed.map(({ category, channelIds }) => {
+		const existing = current.find((c) => c.name === category);
+		return {
+			...(existing?.id ? { id: existing.id } : {}),
+			name: category,
+			channelIds: [...channelIds, ...(existing ? stay(existing) : [])],
+		};
+	});
+	const rest = current
+		.filter((c) => !ahead.some((a) => a.id === c.id))
+		.map((c) => ({ ...c, channelIds: stay(c) }));
+	const layout = [...ahead, ...rest];
+	const remove = layout.flatMap((c) =>
+		c.id && c.channelIds.length === 0 && categoryKind(c.name) ? [c.id] : [],
+	);
+	return {
+		layout: layout.filter((c) => !c.id || !remove.includes(c.id)),
+		remove,
+	};
+}

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

@@ -0,0 +1,188 @@
+import type { ChannelKey } from "../domain/conversation.ts";
+import { AgentError } from "../domain/errors.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import type { AgentGroup } from "./agent-store.ts";
+import {
+	channelIdOf,
+	channelKey,
+	groupSessionKey,
+	homeScope,
+} from "./team-keys.ts";
+import { categoryKind, groupTopic } from "./team-layout.ts";
+import type { TeamContext } from "./team-options.ts";
+
+/** The team's startup, fresh starts, and archiving of agents and groups. */
+export class TeamLifecycle {
+	readonly #ctx: TeamContext;
+
+	constructor(ctx: TeamContext) {
+		this.#ctx = ctx;
+	}
+
+	// ── Startup ────────────────────────────────────────────────────────────
+
+	/**
+	 * Inserts the seed agents, gives every active agent a channel, archives agents and groups
+	 * whose channels were deleted while the assistant was down, and draws missing avatars in the
+	 * background.
+	 */
+	async start(): Promise<void> {
+		const { store, channels, seeds, logger } = this.#ctx.options;
+		const added = await store.seed(seeds());
+		if (added.length > 0) logger.info({ added }, "seed agents added");
+		for (const agent of store.agents()) {
+			if (agent.status !== "active") continue;
+			if (!agent.channelId) {
+				const id = await channels.createChannel(
+					agent.name,
+					agent.displayName,
+					"Agents",
+				);
+				await store.updateAgent(agent.name, { channelId: id });
+				logger.info(
+					{ agent: agent.name, channel: id },
+					"agent channel created",
+				);
+			} else if (!(await channels.exists(agent.channelId))) {
+				await this.channelDeleted(agent.channelId);
+			}
+		}
+		const layout = await channels.layout();
+		for (const group of store.groups()) {
+			if (group.status !== "active") continue;
+			if (!(await channels.exists(group.channelId))) {
+				await this.channelDeleted(group.channelId);
+				continue;
+			}
+			this.retitle(group);
+			const home = layout.find((c) => c.channelIds.includes(group.channelId));
+			if (home && categoryKind(home.name) === "Groups") continue;
+			if (await channels.placeIn(group.channelId, "Groups"))
+				logger.info({ group: group.name }, "group channel moved to Groups");
+		}
+		this.#ctx.changed();
+		void this.#drawMissingAvatars();
+	}
+
+	async #drawMissingAvatars(): Promise<void> {
+		const { store, studio, logger } = this.#ctx.options;
+		for (const agent of store.agents()) {
+			if (agent.status !== "active" || agent.avatarHash) continue;
+			try {
+				const hash = await studio.draw(agent.avatarPrompt);
+				await store.updateAgent(agent.name, { avatarHash: hash });
+				logger.info({ agent: agent.name }, "avatar drawn");
+			} catch (error) {
+				logger.warn({ agent: agent.name, err: error }, "avatar not drawn");
+			}
+		}
+	}
+
+	/** Starts an agent's or every group member's conversation over; call inside the channel's queue. */
+	async startFresh(channel: ChannelKey): Promise<void> {
+		const { store } = this.#ctx.options;
+		const runtime = this.#ctx.options.runtime();
+		const id = channelIdOf(channel);
+		const agent = store.agentByChannel(id);
+		if (agent) {
+			await runtime.startFresh(homeScope(agent).session);
+			this.#ctx.changed();
+			return;
+		}
+		const group = store.groupByChannel(id);
+		if (!group) return;
+		for (const member of group.members)
+			await runtime.startFresh(groupSessionKey(group, member));
+		await store.catchUp(group);
+	}
+
+	// ── Archive ────────────────────────────────────────────────────────────
+
+	/** A deleted channel archives the agent or group that owned it. */
+	channelDeleted(channelId: string): Promise<void> {
+		return this.#archive(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. 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.
+	 */
+	async archive(caller: AgentTurnScope, name: string): Promise<string> {
+		const { store, entryChannelId, 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 already archived.`);
+		if (agent && agent.channelId === entryChannelId)
+			throw new AgentError("The coordinator cannot be archived.");
+		if (agent && name === caller.name)
+			throw new AgentError("You cannot archive yourself; ask another agent.");
+		const channelId = target.channelId;
+		if (!channelId) throw new AgentError(`${name} has no channel.`);
+		await this.#archive(channelId);
+		try {
+			await channels.removeWebhook(channelId);
+		} catch (error) {
+			logger.warn(
+				{ name, err: error },
+				"archived channel's webhook not removed",
+			);
+		}
+		try {
+			await channels.placeIn(channelId, "Archive");
+		} catch (error) {
+			logger.error({ name, err: error }, "archived channel not moved");
+			return `Archived "${target.displayName}", but its channel <#${channelId}> could not be moved to Archive (${error instanceof Error ? error.message : String(error)}); it stays silent where it is.`;
+		}
+		return `Archived "${target.displayName}"; its channel <#${channelId}> is kept under Archive.`;
+	}
+
+	async #archive(channelId: string): Promise<void> {
+		const { store, schedules, logger } = this.#ctx.options;
+		const runtime = this.#ctx.options.runtime();
+		const agent = store.agentByChannel(channelId);
+		if (agent) {
+			const left = await store.archiveAgent(agent.name);
+			const home = channelKey(channelId);
+			for (const schedule of await schedules.forChannel(home))
+				await schedules.remove(schedule.id, home);
+			await runtime.startFresh(home);
+			for (const group of left) {
+				await runtime.startFresh(groupSessionKey(group, agent.name));
+				if (group.status === "active") this.retitle(group);
+			}
+			logger.info(
+				{ agent: agent.name, groups: left.map((g) => g.name) },
+				"agent archived",
+			);
+			this.#ctx.changed();
+			return;
+		}
+		const group = store.groupByChannel(channelId);
+		if (!group) return;
+		await store.archiveGroup(group.name);
+		for (const member of group.members)
+			await runtime.startFresh(groupSessionKey(group, member));
+		logger.info({ group: group.name }, "group archived");
+		this.#ctx.changed();
+	}
+
+	/** Writes a group's members and host into its channel topic, without waiting on Discord. */
+	retitle(group: AgentGroup): void {
+		const { channels, store, logger } = this.#ctx.options;
+		channels
+			.setTopic(group.channelId, groupTopic(group, store))
+			.catch((error: unknown) =>
+				logger.warn(
+					{ group: group.name, err: error },
+					"group topic not updated",
+				),
+			);
+	}
+}

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

@@ -0,0 +1,52 @@
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { ThinkingSetting } from "../models.ts";
+import type { SkillRegistry } from "../modules/skills/skill-registry.ts";
+import type { PromptSection } from "../plugin.ts";
+import type { ToolSelection } from "../sessions.ts";
+import type { AgentChannels, AgentModels } from "./agent-ports.ts";
+import type { AgentGroup, AgentSeed } from "./agent-store.ts";
+import type { AvatarStudio } from "./avatar-studio.ts";
+import type { TeamTurns, TeamTurnsOptions } from "./team-turns.ts";
+
+export interface AgentTeamOptions
+	extends Omit<TeamTurnsOptions, "selection" | "changed"> {
+	/** The agent server; its entry channel is where the coordinator lives. */
+	guildId: string;
+	/** The first team, read and inserted once on start; an agent already stored is never overwritten. */
+	seeds: () => readonly AgentSeed[];
+	/** Sections the plugins add to every agent turn's system prompt, read before each run. */
+	promptSections?: () => readonly PromptSection[];
+	/** The tools plugins defined for agents, read before each agent turn. */
+	pluginTools?: () => readonly string[];
+	channels: AgentChannels;
+	studio: Pick<AvatarStudio, "url" | "draw" | "edit">;
+	/** The tools and groups the plugins give every agent, read before each agent turn. */
+	pluginSelection: () => ToolSelection;
+	models: AgentModels;
+	schedules: {
+		forChannel(channel: ChannelKey): Promise<{ id: number }[]>;
+		remove(id: number, channel?: ChannelKey): Promise<unknown>;
+	};
+	/** The shell's shared working directory. */
+	workDir: string;
+	/** The host account the agents' shell and file tools run as. */
+	shellUser: string;
+	/** The prompt every persona shares, the assistant's included; each agent's starts with it. */
+	sharedPrompt: string;
+	/** The shared prompt for speakers other than the owner, when `sharedPrompt` speaks to the owner. */
+	guestPrompt?: string;
+	/** The skill registry: what each agent carries and the skill tools. */
+	skills: SkillRegistry;
+}
+
+/** What the team's collaborators share: its options, its turns, and its change signal. */
+export interface TeamContext {
+	readonly options: AgentTeamOptions;
+	readonly turns: TeamTurns;
+	/** Called when a turn starts or ends and when an agent or group changes. */
+	changed(): void;
+	/** The model and thinking setting of an agent's next run. */
+	modelOf(name: string): { model: string; thinking: ThinkingSetting };
+	/** Writes a group's members and host into its channel topic, without waiting on Discord. */
+	retitle(group: AgentGroup): void;
+}