pi-roundtable 0.22.5 → 0.23.0

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

@@ -1,12 +1,25 @@
+import {
+	type CharacterSpec,
+	resolveCharacter,
+	suggestCharacter,
+} from "../../characters/index.ts";
 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 type { AgentChannels } from "./agent-ports.ts";
+import { overBase } from "./agent-rules.ts";
+import type { Agent, AgentGroup } from "./agent-store.ts";
 import {
-	channelIdOf,
-	discordKey,
+	agentOfChannel,
+	coordinatorOf,
+	discordIdOf,
+	groupLogName,
+	groupOfChannel,
+	groupRoomKey,
 	groupSessionKey,
 	homeScope,
+	keysOf,
+	roomScope,
 } from "./team-keys.ts";
 import { categoryKind, groupTopic } from "./team-layout.ts";
 import type { TeamContext } from "./team-options.ts";
@@ -23,13 +36,23 @@ export class TeamLifecycle {
 
 	/**
 	 * 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.
+	 * whose channels were deleted while the assistant was down, and dresses agents without a
+	 * character in the background. Without Discord channels the agents live in rooms, which need no setup, so
+	 * none is made or checked.
 	 */
 	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");
+		if (channels) await this.#startChannels(channels);
+		this.#ctx.changed();
+		void this.#dressMissing().then((dressed) => {
+			if (dressed) this.#ctx.changed();
+		});
+	}
+
+	async #startChannels(channels: AgentChannels): Promise<void> {
+		const { store, logger } = this.#ctx.options;
 		for (const agent of store.agents()) {
 			if (agent.status !== "active") continue;
 			if (!agent.channelId) {
@@ -49,93 +72,106 @@ export class TeamLifecycle {
 		}
 		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);
+			// A group of a team that once ran without Discord lives in rooms only.
+			if (group.status !== "active" || !group.channelId) continue;
+			const { channelId } = group;
+			if (!(await channels.exists(channelId))) {
+				await this.channelDeleted(channelId);
 				continue;
 			}
 			this.retitle(group);
-			const home = layout.find((c) => c.channelIds.includes(group.channelId));
+			const home = layout.find((c) => c.channelIds.includes(channelId));
 			if (home && categoryKind(home.name) === "Groups") continue;
-			if (await channels.placeIn(group.channelId, "Groups"))
+			if (await channels.placeIn(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;
-		if (studio.canDraw === false) return this.#generateMissingAvatars();
-		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");
-			}
-		}
 	}
 
 	/**
-	 * Without an image provider, gives each active agent that has no picture the one made from
-	 * its display name, and says so once instead of once per agent on every boot.
+	 * Dresses every active agent that has no character: the seed of that name gives it (its fields
+	 * over what the role suggests), otherwise the suggestion for the role, spread over the looks
+	 * already worn. The picture is rendered and replaces the old hash. A failure is logged for that
+	 * agent, which keeps its picture until the next start; a second pass finds nothing to do.
 	 */
-	async #generateMissingAvatars(): Promise<void> {
-		const { store, studio, logger } = this.#ctx.options;
-		if (!studio.fallback) return;
-		let generated = 0;
+	async #dressMissing(): Promise<boolean> {
+		const { store, studio, seeds, logger } = this.#ctx.options;
+		const seeded = new Map(seeds().map((seed) => [seed.name, seed]));
+		const worn: CharacterSpec[] = store
+			.agents()
+			.flatMap((agent) =>
+				agent.status === "active" && agent.character ? [agent.character] : [],
+			);
+		let dressed = false;
 		for (const agent of store.agents()) {
-			if (agent.status !== "active" || agent.avatarHash) continue;
+			if (
+				agent.status !== "active" ||
+				agent.character ||
+				store.hasStoredCharacter(agent.name)
+			)
+				continue;
 			try {
-				const avatarHash = await studio.fallback(agent.displayName, agent.name);
-				await store.updateAgent(agent.name, { avatarHash });
-				generated++;
+				const suggested = suggestCharacter(agent, worn);
+				const wanted = seeded.get(agent.name)?.character;
+				const character = wanted
+					? resolveCharacter(overBase(wanted, suggested), suggested)
+					: suggested;
+				const avatarHash = await studio.render(character);
+				if (!(await store.dressIfUndressed(agent.name, character, avatarHash)))
+					continue;
+				dressed = true;
+				worn.push(character);
+				logger.info(
+					{ agent: agent.name, class: character.class },
+					"agent dressed",
+				);
 			} catch (error) {
-				logger.warn({ agent: agent.name, err: error }, "avatar not generated");
+				logger.warn({ agent: agent.name, err: error }, "agent not dressed");
 			}
 		}
-		if (generated > 0)
-			logger.info(
-				{ generated },
-				"no image provider is configured; agents without a picture got one generated from their display name",
-			);
+		return dressed;
 	}
 
 	/** 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 { store, surfaces } = 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);
+		// A Discord channel and each room are conversations of their own: a room starts over alone.
+		const agent = agentOfChannel(store, surfaces, channel);
+		if (agent?.status === "active") {
+			await runtime.startFresh(
+				discordIdOf(channel) === undefined
+					? roomScope(agent, channel).session
+					: homeScope(agent).session,
+			);
 			this.#ctx.changed();
 			return;
 		}
-		const group = store.groupByChannel(id);
-		if (!group) return;
+		const group = groupOfChannel(store, surfaces, channel);
+		if (group?.status !== "active") return;
 		for (const member of group.members)
-			await runtime.startFresh(groupSessionKey(group, member));
-		await store.catchUp(group);
+			await runtime.startFresh(groupSessionKey(group, member, channel));
+		await store.catchUp(group, groupLogName(group, channel));
 	}
 
 	// ── Archive ────────────────────────────────────────────────────────────
 
 	/** A deleted channel archives the agent or group that owned it. */
-	channelDeleted(channelId: string): Promise<void> {
-		return this.#archive(channelId);
+	async channelDeleted(channelId: string): Promise<void> {
+		const { store } = this.#ctx.options;
+		const agent = store.agentByChannel(channelId);
+		if (agent) return this.#archiveAgent(agent);
+		const group = store.groupByChannel(channelId);
+		if (group) await this.#archiveGroup(group);
 	}
 
 	/**
 	 * 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.
+	 * 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.
 	 */
 	async archive(caller: AgentTurnScope, name: string): Promise<string> {
-		const { store, entryChannelId, channels, logger } = this.#ctx.options;
+		const { store, channels, logger } = this.#ctx.options;
 		const agent = store.agent(name);
 		const group = agent ? undefined : store.group(name);
 		const target = agent ?? group;
@@ -145,13 +181,15 @@ export class TeamLifecycle {
 			);
 		if (target.status !== "active")
 			throw new AgentError(`"${name}" is already archived.`);
-		if (agent && agent.channelId === entryChannelId)
+		if (agent && coordinatorOf(store, this.#ctx.options)?.name === name)
 			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);
+		const { channelId } = target;
+		if (agent) await this.#archiveAgent(agent);
+		else if (group) await this.#archiveGroup(group);
+		if (!channelId || !channels)
+			return `Archived "${target.displayName}"; it no longer answers anywhere.`;
 		try {
 			await channels.removeWebhook(channelId);
 		} catch (error) {
@@ -169,41 +207,70 @@ export class TeamLifecycle {
 		return `Archived "${target.displayName}"; its channel <#${channelId}> is kept under Archive.`;
 	}
 
-	async #archive(channelId: string): Promise<void> {
+	async #archiveAgent(agent: Agent): 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 = discordKey(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 rooms = this.#rooms();
+		const left = await store.archiveAgent(agent.name);
+		// The agent's Discord channel and each of its rooms are conversations of their own.
+		for (const key of keysOf(store, agent.name, rooms)) {
+			for (const schedule of await schedules.forChannel(key))
+				await schedules.remove(schedule.id, key);
+			await runtime.startFresh(key);
 		}
-		const group = store.groupByChannel(channelId);
-		if (!group) return;
+		for (const group of left) {
+			for (const seat of this.#seats(group, agent.name, rooms))
+				await runtime.startFresh(seat);
+			if (group.status === "active") this.retitle(group);
+		}
+		logger.info(
+			{ agent: agent.name, groups: left.map((g) => g.name) },
+			"agent archived",
+		);
+		this.#ctx.changed();
+	}
+
+	async #archiveGroup(group: AgentGroup): Promise<void> {
+		const { store, logger } = this.#ctx.options;
+		const runtime = this.#ctx.options.runtime();
+		const rooms = this.#rooms();
 		await store.archiveGroup(group.name);
 		for (const member of group.members)
-			await runtime.startFresh(groupSessionKey(group, member));
+			for (const seat of this.#seats(group, member, rooms))
+				await runtime.startFresh(seat);
 		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. */
+	/** The surfaces that host rooms; none for a team without a surface port. */
+	#rooms(): readonly string[] {
+		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;
+		const { channelId } = group;
+		if (!channels || !channelId) return;
 		channels
-			.setTopic(group.channelId, groupTopic(group, store))
+			.setTopic(channelId, groupTopic(group, store))
 			.catch((error: unknown) =>
 				logger.warn(
 					{ group: group.name, err: error },

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

@@ -9,7 +9,10 @@ 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. */
+	/**
+	 * The team's id: the Discord guild, or `LOCAL_TEAM_ID` on a host without Discord. It scopes the
+	 * rows the team keeps.
+	 */
 	guildId: string;
 	/** The first team, read and inserted once on start; an agent already stored is never overwritten. */
 	seeds: () => readonly AgentSeed[];
@@ -17,13 +20,17 @@ export interface AgentTeamOptions
 	promptSections?: () => readonly PromptSection[];
 	/** The tools plugins defined for agents, read before each agent turn. */
 	pluginTools?: () => readonly string[];
-	channels: AgentChannels;
 	/**
-	 * `canDraw: false` marks a host without an image provider: agents are offered no drawing and
-	 * get `fallback` pictures. A studio that leaves `canDraw` out draws.
+	 * The Discord channels the agents live in; absent on a host without Discord. Then no channel is
+	 * made, arranged or read, and the agents live in the rooms of the surfaces that host them.
+	 */
+	channels?: AgentChannels;
+	/**
+	 * Agents are composed characters, rendered by `render`. `canDraw: false` marks a host without
+	 * an image provider, which is not told about generate_image; a studio that leaves it out has one.
 	 */
-	studio: Pick<AvatarStudio, "url" | "draw" | "edit"> &
-		Partial<Pick<AvatarStudio, "canDraw" | "fallback">>;
+	studio: Pick<AvatarStudio, "url" | "render" | "draw" | "edit"> &
+		Partial<Pick<AvatarStudio, "canDraw">>;
 	/** The tools and groups the plugins give every agent, read before each agent turn. */
 	pluginSelection: () => ToolSelection;
 	models: AgentModels;

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

@@ -1,6 +1,6 @@
 import type { ThinkingSetting } from "../models.ts";
 import type { ContextUse } from "./agent-ports.ts";
-import { channelIdOf, discordKey } from "./team-keys.ts";
+import { discordIdOf, keysOf } from "./team-keys.ts";
 import type { TeamContext } from "./team-options.ts";
 
 /** An active agent as the dashboard shows it. */
@@ -12,10 +12,12 @@ export interface AgentStatus {
 	thinking: ThinkingSetting;
 	/** The channel of its running turn: its own, a group's, or where it answers a message. */
 	workingIn?: string;
-	/** Turns waiting in its own channel. */
+	/** Turns waiting in its own channel and in each of its rooms. */
 	waiting: number;
+	/** The context use of its conversation that has one: its Discord channel's, else the first room's. */
 	context?: ContextUse;
 	lastActive?: Date;
+	/** Its schedules, across its Discord channel and its rooms. */
 	schedules: number;
 }
 
@@ -23,10 +25,11 @@ export interface AgentStatus {
 export interface GroupStatus {
 	name: string;
 	displayName: string;
-	channelId: string;
+	/** Its Discord channel; absent in a team without Discord. */
+	channelId?: string;
 	members: string[];
 	host: string;
-	/** Messages of its channel running or waiting, a round counting as one. */
+	/** Messages of its channel and rooms running or waiting, a round counting as one. */
 	busy: number;
 	lastActive?: Date;
 }
@@ -41,24 +44,36 @@ export async function teamStatus(ctx: TeamContext): Promise<TeamStatus> {
 	const { options, turns } = ctx;
 	const { store, queue, schedules } = options;
 	const runtime = options.runtime();
+	const rooms = options.surfaces?.roomSurfaces() ?? [];
 	const agents: AgentStatus[] = [];
 	for (const agent of store.agents()) {
 		if (agent.status !== "active") continue;
-		const home = agent.channelId ? discordKey(agent.channelId) : undefined;
-		const workingIn = turns.workingIn(agent.name);
-		const queued = home ? queue.size(home) : 0;
-		const context = home ? runtime.contextUsage?.(home) : undefined;
+		// Its Discord channel and each room are conversations of their own, and all count.
+		const keys = keysOf(store, agent.name, rooms);
+		const working = turns.workingIn(agent.name);
+		// The board links Discord channels; a turn in a room has none to link.
+		const workingIn = working === undefined ? undefined : discordIdOf(working);
+		const queued = keys.reduce((sum, key) => sum + queue.size(key), 0);
+		const context = keys
+			.map((key) => runtime.contextUsage?.(key))
+			.find((use) => use !== undefined);
+		let scheduled = 0;
+		for (const key of keys)
+			scheduled += (await schedules.forChannel(key)).length;
 		const lastActive = turns.lastActive(agent.name);
 		agents.push({
 			name: agent.name,
 			displayName: agent.displayName,
 			...(agent.channelId ? { channelId: agent.channelId } : {}),
 			...ctx.modelOf(agent.name),
-			...(workingIn ? { workingIn: channelIdOf(workingIn) } : {}),
-			waiting: Math.max(0, queued - (workingIn === home ? 1 : 0)),
+			...(workingIn ? { workingIn } : {}),
+			waiting: Math.max(
+				0,
+				queued - (working !== undefined && keys.includes(working) ? 1 : 0),
+			),
 			...(context ? { context } : {}),
 			...(lastActive ? { lastActive } : {}),
-			schedules: home ? (await schedules.forChannel(home)).length : 0,
+			schedules: scheduled,
 		});
 	}
 	const groups: GroupStatus[] = store.groups().flatMap((group) => {
@@ -68,10 +83,13 @@ export async function teamStatus(ctx: TeamContext): Promise<TeamStatus> {
 			{
 				name: group.name,
 				displayName: group.displayName,
-				channelId: group.channelId,
+				...(group.channelId ? { channelId: group.channelId } : {}),
 				members: group.members.map((m) => store.agent(m)?.displayName ?? m),
 				host: store.agent(group.host)?.displayName ?? group.host,
-				busy: queue.size(discordKey(group.channelId)),
+				busy: keysOf(store, group.name, rooms).reduce(
+					(sum, key) => sum + queue.size(key),
+					0,
+				),
 				...(lastActive ? { lastActive } : {}),
 			},
 		];

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

@@ -1,12 +1,18 @@
+import { CATALOG, type CharacterSpec } from "../../characters/index.ts";
 import { AgentError } from "../domain/errors.ts";
 import { assistantName } from "../i18n/index.ts";
 import type { ThinkingSetting } from "../models.ts";
 import type { AgentDirectory } from "../services.ts";
 import { zonedStamp } from "../time.ts";
 import type { ChannelMessage } from "./agent-ports.ts";
+import { characterOf } from "./agent-rules.ts";
 import { describeThinking } from "./agent-settings.ts";
 import type { Agent } from "./agent-store.ts";
 
+/** Said by the tools that work on Discord channels when the team has none. */
+export const NO_CHANNELS =
+	"This host has no Discord channels: the agents live in rooms of a chat surface, so there is nothing to arrange or read here.";
+
 /** One message as channel_read shows it: id, local time, author, text, attachments. */
 export function messageLine(message: ChannelMessage): string {
 	const files =
@@ -36,17 +42,21 @@ export function teamListText(store: Pick<AgentDirectory, "agents" | "groups">) {
 		.groups()
 		.map(
 			(g) =>
-				`- ${g.name} "${g.displayName}" — <#${g.channelId}>, ${g.status}; members ${g.members.join(", ")}; host ${g.host}`,
+				`- ${g.name} "${g.displayName}" — ${g.channelId ? `<#${g.channelId}>` : "no channel"}, ${g.status}; members ${g.members.join(", ")}; host ${g.host}`,
 		);
 	return `Agents:\n${agents.join("\n") || "none"}\n\nGroups:\n${groups.join("\n") || "none"}`;
 }
 
+/** A look in a few words: the class label, then the palette or the primary color. */
+export function lookText(character: CharacterSpec): string {
+	return `${CATALOG.classes[character.class].label}, ${character.palette ?? character.colors.primary}`;
+}
+
 /** One agent as agent_get shows it; unset settings name the assistant's, and no skills line while the skills addon is off. */
 export function agentDetails(
 	agent: Agent,
 	defaults: { model: string; thinking: ThinkingSetting },
 	skills: string | undefined,
-	avatars = true,
 ): string {
 	return [
 		`Name: ${agent.name}`,
@@ -56,7 +66,7 @@ export function agentDetails(
 		`Model: ${agent.model ?? `${assistantName()}'s (${defaults.model})`}`,
 		`Thinking: ${agent.thinking ?? `${assistantName()}'s (${describeThinking(defaults.thinking)})`}`,
 		...(skills === undefined ? [] : [`Skills: ${skills}`]),
-		...(avatars ? [`Avatar prompt: ${agent.avatarPrompt}`] : []),
+		`Look: ${lookText(characterOf(agent))}`,
 		`Prompt:\n${agent.prompt}`,
 	].join("\n");
 }

package/src/core/agents/team-turn-types.ts

@@ -1,8 +1,5 @@
 import type { QueuePort } from "../contract/channels.ts";
-import type {
-	DispatchThread,
-	DispatchThreads,
-} from "../discord/dispatch-threads.ts";
+import type { SurfacePort } from "../contract/surface.ts";
 import type { TurnAttachments } from "../domain/attachment.ts";
 import type {
 	ChannelKey,
@@ -16,6 +13,10 @@ import type { EventSink } from "../plugin.ts";
 import type { AvatarStudio } from "../services.ts";
 import type { TurnSelection } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
+import type {
+	DispatchThread,
+	DispatchThreads,
+} from "../threads/dispatch-threads.ts";
 import type { ToolTiers } from "../tool-tiers.ts";
 import type { AgentChannels, AgentTurnRunner } from "./agent-ports.ts";
 import type { Agent, PgAgentStore } from "./agent-store.ts";
@@ -39,12 +40,29 @@ export interface Exchange {
 }
 
 export interface TeamTurnsOptions {
-	/** The agent server's entry channel, where the coordinator lives. */
-	entryChannelId: string;
+	/** The agent server's entry channel, where the coordinator lives; absent on a host without Discord. */
+	entryChannelId?: string;
+	/**
+	 * The coordinator's name on a host without Discord, where there is no entry channel to find it
+	 * by; a function is asked each time, for a name that is only known once the plugins linked.
+	 * Ignored when `entryChannelId` is set.
+	 */
+	coordinator?: string | (() => string | undefined);
 	/** Who the agents work for, as their prompts and group history name them. */
 	owner: OwnerIdentity;
 	store: PgAgentStore;
-	channels: Pick<AgentChannels, "post" | "interim">;
+	/** The Discord channels the agents post in; absent on a host without Discord, where every reply goes through a room's surface. */
+	channels?: Pick<AgentChannels, "post" | "interim">;
+	/**
+	 * The surfaces that host agent rooms. A reply in a room goes through `sendReply` with the
+	 * agent as author, and its interim posts through `interim`, never through the Discord
+	 * channels; without it no key but Discord's is the team's. `of` tells whether the room's
+	 * surface carries reply files.
+	 */
+	surfaces?: Pick<
+		SurfacePort,
+		"sendReply" | "interim" | "roomSurfaces" | "of" | "progress"
+	>;
 	studio: Pick<AvatarStudio, "url">;
 	/** Set once the runtime exists, which itself needs the team's tools. */
 	runtime: () => AgentTurnRunner;