pi-roundtable 0.22.5 → 0.23.0

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

@@ -1,12 +1,20 @@
+import {
+	CharacterError,
+	type CharacterInput,
+	type CharacterSpec,
+	resolveCharacter,
+	suggestCharacter,
+} from "../../characters/index.ts";
 import { AgentError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
-import { assistantName } from "../i18n/index.ts";
+import type { AgentChange } from "../services.ts";
 import { addressee } 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 } from "./team-keys.ts";
+import { discordKey, keysOf } from "./team-keys.ts";
 import { groupTopic, teamCategory } from "./team-layout.ts";
 import type { TeamContext } from "./team-options.ts";
 
@@ -26,15 +34,7 @@ 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: {
-			displayName?: string;
-			prompt?: string;
-			model?: string;
-			thinking?: string;
-		},
-	): Promise<string> {
+	async update(name: string, change: AgentChange): Promise<string> {
 		const { store, logger } = this.#ctx.options;
 		if (Object.values(change).every((value) => value === undefined))
 			throw new AgentError(
@@ -78,14 +78,16 @@ export class TeamEditing {
 			name: string;
 			displayName: string;
 			prompt: string;
-			/** Required when an image provider is configured, ignored otherwise. */
+			/** @deprecated Ignored: agents are composed characters. */
 			avatarPrompt?: string;
+			/** Fields of its look; any left out come from the look its role suggests. */
+			character?: CharacterInput;
 			task: string;
 			category?: string;
 			skills?: string[];
 		},
 	): Promise<string> {
-		const { store, studio, channels, queue, skills, logger } =
+		const { store, studio, channels, queue, skills, surfaces, logger } =
 			this.#ctx.options;
 		if (input.skills && input.skills.length > 0 && !skills)
 			throw new AgentError(
@@ -96,45 +98,58 @@ export class TeamEditing {
 			throw new AgentError(
 				"agent_create can only be used during an agent turn.",
 			);
-		const drawing = studio.canDraw !== false;
 		const {
 			category,
 			skills: carried = [],
-			avatarPrompt = "",
+			character: wanted,
+			avatarPrompt: _ignored,
 			...fields
 		} = input;
-		if (drawing && avatarPrompt.trim() === "")
-			throw new AgentError("Give avatar_prompt: the avatar is drawn from it.");
 		const parent = teamCategory(category, "Agents");
 		store.checkNewName(input.name);
 		skills?.checkRegistered(carried);
-		const channelId = await channels.createChannel(
+		// The picture comes before the row and the channel: a render failure fails the create.
+		const taken = store
+			.agents()
+			.flatMap((other) =>
+				other.status === "active" && other.character ? [other.character] : [],
+			);
+		const suggested = suggestCharacter(input, taken);
+		const character = this.#resolve(wanted ?? {}, suggested);
+		const avatarHash = await studio.render(character);
+		// Without Discord channels the agent lives in its rooms, which exist as soon as it does.
+		const channelId = await channels?.createChannel(
 			input.name,
 			input.displayName,
 			parent,
 		);
 		const agent = await store.createAgent({
 			...fields,
-			avatarPrompt: drawing ? avatarPrompt : "",
-			channelId,
+			character,
+			avatarHash,
+			...(channelId ? { channelId } : {}),
 		});
 		if (skills && 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 (drawing
-			? this.#redraw(agent.name, "redraw")
-			: this.#generate(agent)
-		).then(
-			() =>
-				drawing
-					? "its avatar is drawn"
-					: "its avatar is generated from its display name",
-			(error: unknown) =>
-				`its avatar could not be drawn (${error instanceof Error ? error.message : String(error)}), so it uses ${assistantName()}'s for now`,
+		logger.info(
+			{ agent: agent.name, by: caller.name, class: character.class },
+			"agent created",
 		);
-		const home = discordKey(channelId);
+		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 (!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.`;
+		}
 		void queue
 			.run(home, () =>
 				this.#ctx.turns.answerBackground(
@@ -150,33 +165,45 @@ export class TeamEditing {
 			.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.`;
+		return `Created "${agent.displayName}" (${agent.name})${where}; ${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.`;
+	/** The agent tool: changes a look, then says what the owner sees. */
+	async avatar(name: string, look: CharacterInput): Promise<string> {
+		const agent = await this.dress(name, look);
+		return `"${agent.displayName}" now looks like a ${characterOf(agent).class}; the new picture shows from its next message.`;
 	}
 
-	/** Draws and stores a new picture; the owner's panel and the agent tool both use it. */
+	/**
+	 * Changes an agent's look. The input is resolved over the agent's current character; a new
+	 * class keeps the agent's colors unless the input names a palette or colors. The picture is
+	 * rendered before anything is stored, and the character and picture are stored together.
+	 */
+	async dress(name: string, input: CharacterInput): Promise<Agent> {
+		const { store, studio, logger } = this.#ctx.options;
+		const agent = store.activeAgent(name);
+		const base = characterOf(agent);
+		const character = this.#resolve(input, base);
+		let avatarHash: string;
+		try {
+			avatarHash = await studio.render(character);
+		} catch (error) {
+			throw new AgentError(
+				`The picture could not be rendered: ${error instanceof Error ? error.message : String(error)}. The previous look stays.`,
+			);
+		}
+		const dressed = await store.updateAgent(name, { character, avatarHash });
+		logger.info({ agent: name, class: character.class }, "agent dressed");
+		this.#ctx.changed();
+		return dressed;
+	}
+
+	/** @deprecated Use `dress`; removed in 1.0. Draws and stores a new picture. */
 	async redrawAvatar(
 		name: string,
 		mode: AvatarMode,
 		text?: string,
 	): Promise<Agent> {
-		return this.#redraw(name, mode, text);
-	}
-
-	/** Gives an agent the picture made from its display name; a host without an image provider has no other. */
-	async #generate(agent: Agent): Promise<Agent> {
-		const { store, studio } = this.#ctx.options;
-		if (!studio.fallback)
-			throw new AgentError("The avatar studio has no generated avatars.");
-		const avatarHash = await studio.fallback(agent.displayName, agent.name);
-		return store.updateAgent(agent.name, { avatarHash });
-	}
-
-	async #redraw(name: string, mode: AvatarMode, text?: string): Promise<Agent> {
 		const { store, studio, logger } = this.#ctx.options;
 		const agent = store.activeAgent(name);
 		if (studio.canDraw === false) throw new AgentError(NO_IMAGE_PROVIDER);
@@ -205,6 +232,19 @@ export class TeamEditing {
 		return store.updateAgent(name, { avatarHash: hash });
 	}
 
+	/**
+	 * An input over a base look (see overBase); a bad field is an AgentError that names it.
+	 */
+	#resolve(input: CharacterInput, base: CharacterSpec): CharacterSpec {
+		try {
+			return resolveCharacter(overBase(input, base), base);
+		} catch (error) {
+			if (error instanceof CharacterError)
+				throw new AgentError(`The look is not usable: ${error.message}.`);
+			throw error;
+		}
+	}
+
 	async createGroup(input: {
 		name: string;
 		displayName: string;
@@ -221,15 +261,16 @@ export class TeamEditing {
 				? "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 });
+		const topic = groupTopic({ ...fields, host, status: "active" }, store);
+		const channelId = await channels?.createChannel(input.name, topic, parent);
+		const group = await store.createGroup({
+			...fields,
+			host,
+			...(channelId ? { 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}.`;
+		return `Created the group "${group.displayName}"${channelId ? ` in <#${channelId}>` : ""} with ${group.members.join(", ")}; host ${group.host}.`;
 	}
 
 	async updateGroup(

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

@@ -1,5 +1,6 @@
 import { channelKey, parseChannelKey } from "../contract/surface.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
+import { AgentError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
 import type { AgentDirectory } from "../services.ts";
 import type { Agent, AgentGroup } from "./agent-store.ts";
@@ -20,34 +21,199 @@ export function discordIdOf(channel: ChannelKey): string | undefined {
 /** The id part of a key the caller already knows is a Discord one, because the agent server owns it. */
 export const channelIdOf = (channel: ChannelKey) => parseChannelKey(channel).id;
 
-/** An agent's conversation inside a group, apart from its own. */
-export const groupSessionKey = (group: AgentGroup, agent: string): ChannelKey =>
-	`agentgroup:${group.channelId}.${agent}`;
+/** The key of an agent's room on a surface that serves agent rooms. */
+export const agentRoomKey = (surface: string, agent: string): ChannelKey =>
+	channelKey(surface, `agent.${agent}`);
 
-/** An agent's own conversation. */
+/** The key of a group's room on a surface that serves agent rooms. */
+export const groupRoomKey = (surface: string, group: string): ChannelKey =>
+	channelKey(surface, `group.${group}`);
+
+const ROOM_ID = /^(agent|group)\.([a-z0-9-]{1,32})$/;
+
+/**
+ * Which agent's or group's room a key is, when its surface is one of `roomSurfaces` and its id has
+ * the exact shape of a room; undefined for anything else, so no other key is ever taken for one.
+ * Discord never hosts rooms.
+ */
+export function roomOf(
+	key: ChannelKey,
+	roomSurfaces: readonly string[],
+): { kind: "agent" | "group"; name: string } | undefined {
+	const at = typeof key === "string" ? key.indexOf(":") : -1;
+	if (at <= 0) return undefined;
+	const surface = key.slice(0, at);
+	if (surface === DISCORD_SURFACE || !roomSurfaces.includes(surface))
+		return undefined;
+	const match = ROOM_ID.exec(key.slice(at + 1));
+	if (!match) return undefined;
+	return { kind: match[1] as "agent" | "group", name: match[2] as string };
+}
+
+/** What the surfaces say of rooms: which of them host agent rooms, asked only for a key that is not a Discord one. */
+interface RoomHosts {
+	roomSurfaces(): readonly string[];
+}
+
+/** The agent whose Discord channel or room the key is; an archived one is returned too. */
+export function agentOfChannel(
+	store: Pick<AgentDirectory, "agent" | "agentByChannel">,
+	hosts: RoomHosts | undefined,
+	channel: ChannelKey,
+): Agent | undefined {
+	const id = discordIdOf(channel);
+	if (id !== undefined) return store.agentByChannel(id);
+	const room = roomOf(channel, hosts?.roomSurfaces() ?? []);
+	return room?.kind === "agent" ? store.agent(room.name) : undefined;
+}
+
+/** The group whose Discord channel or room the key is; an archived one is returned too. */
+export function groupOfChannel(
+	store: Pick<AgentDirectory, "group" | "groupByChannel">,
+	hosts: RoomHosts | undefined,
+	channel: ChannelKey,
+): AgentGroup | undefined {
+	const id = discordIdOf(channel);
+	if (id !== undefined) return store.groupByChannel(id);
+	const room = roomOf(channel, hosts?.roomSurfaces() ?? []);
+	return room?.kind === "group" ? store.group(room.name) : undefined;
+}
+
+/** The surface of a key that is not a Discord channel's; undefined for a Discord channel. */
+export const roomSurfaceOf = (room: ChannelKey): string | undefined => {
+	const at = typeof room === "string" ? room.indexOf(":") : -1;
+	if (at <= 0) return undefined;
+	const surface = room.slice(0, at);
+	return surface === DISCORD_SURFACE ? undefined : surface;
+};
+
+/**
+ * An agent's conversation inside a group, apart from its own. In a Discord group channel, or
+ * without a room, it is keyed by the channel; in a room of another surface, by the surface and the
+ * group's name, so the room's seats are conversations of their own.
+ */
+export function groupSessionKey(
+	group: AgentGroup,
+	agent: string,
+	room?: ChannelKey,
+): ChannelKey {
+	const surface = room === undefined ? undefined : roomSurfaceOf(room);
+	if (surface !== undefined)
+		return `agentgroup:${surface}.group.${group.name}.${agent}`;
+	// A group of a team without Discord has rooms only, so it never has a seat of its own to key.
+	if (!group.channelId)
+		throw new AgentError(`the group ${group.name} has no Discord channel`);
+	return `agentgroup:${group.channelId}.${agent}`;
+}
+
+/**
+ * The name a group's messages are logged under: the group's own in its Discord channel, and
+ * `<group>@<surface>` in a room, so each conversation keeps its own history and cursors.
+ */
+export function groupLogName(group: AgentGroup, room: ChannelKey): string {
+	const surface = roomSurfaceOf(room);
+	return surface === undefined ? group.name : `${group.name}@${surface}`;
+}
+
+/**
+ * The coordinator: with Discord, the agent in the entry channel; without it, the agent the
+ * configuration names. Undefined while none is active.
+ */
+export function coordinatorOf(
+	store: Pick<AgentDirectory, "agent" | "agentByChannel">,
+	team: {
+		entryChannelId?: string;
+		coordinator?: string | (() => string | undefined);
+	},
+): Agent | undefined {
+	if (team.entryChannelId !== undefined)
+		return store.agentByChannel(team.entryChannelId);
+	const name =
+		typeof team.coordinator === "function"
+			? team.coordinator()
+			: team.coordinator;
+	const named = name ? store.agent(name) : undefined;
+	return named?.status === "active" ? named : undefined;
+}
+
+/** An agent's own channel conversation. */
 export function homeScope(agent: Agent): AgentTurnScope {
 	const home = discordKey(agent.channelId ?? "");
 	return { name: agent.name, session: home, home };
 }
 
-/** An agent's conversation inside a group. */
-export function groupScope(agent: Agent, group: AgentGroup): AgentTurnScope {
+/** An agent's conversation in its room: the room is its session and its home. */
+export function roomScope(agent: Agent, room: ChannelKey): AgentTurnScope {
+	return { name: agent.name, session: room, home: room };
+}
+
+/**
+ * An agent's conversation inside a group: in a Discord group channel, or without a room, as
+ * before; in a room, the room's seat, whose home is the agent's own room on that surface.
+ */
+export function groupScope(
+	agent: Agent,
+	group: AgentGroup,
+	room?: ChannelKey,
+): AgentTurnScope {
+	const surface = room === undefined ? undefined : roomSurfaceOf(room);
 	return {
 		name: agent.name,
-		session: groupSessionKey(group, agent.name),
-		home: discordKey(agent.channelId ?? ""),
+		session: groupSessionKey(group, agent.name, room),
+		home:
+			surface === undefined
+				? discordKey(agent.channelId ?? "")
+				: agentRoomKey(surface, agent.name),
 		group: group.name,
 	};
 }
 
-/** The agent or group that owns a channel of the agent server. */
+/**
+ * The agent or group that owns a channel of the agent server: by Discord channel, or by room on
+ * one of `roomSurfaces`. An archived agent or group owns nothing.
+ */
 export function channelOwner(
-	store: Pick<AgentDirectory, "agentByChannel" | "groupByChannel">,
+	store: Pick<AgentDirectory, "agentByChannel" | "groupByChannel"> &
+		Partial<Pick<AgentDirectory, "agent" | "group">>,
 	channel: ChannelKey,
+	roomSurfaces: readonly string[] = [],
 ): "agent" | "group" | undefined {
 	const id = discordIdOf(channel);
-	if (id === undefined) return undefined;
+	if (id === undefined) {
+		const room = roomOf(channel, roomSurfaces);
+		if (!room) return undefined;
+		if (room.kind === "agent")
+			return store.agent?.(room.name)?.status === "active"
+				? "agent"
+				: undefined;
+		return store.group?.(room.name)?.status === "active" ? "group" : undefined;
+	}
 	if (store.agentByChannel(id)) return "agent";
 	if (store.groupByChannel(id)) return "group";
 	return undefined;
 }
+
+/**
+ * Every key an agent or group is addressed by: its Discord channel, when it has one, then its
+ * room on each of `roomSurfaces`; none for a name the team does not know. Archived ones count,
+ * so what they left behind can be cleared.
+ */
+export function keysOf(
+	store: Pick<AgentDirectory, "agent" | "group">,
+	name: string,
+	roomSurfaces: readonly string[],
+): ChannelKey[] {
+	const agent = store.agent(name);
+	if (agent)
+		return [
+			...(agent.channelId ? [discordKey(agent.channelId)] : []),
+			...roomSurfaces.map((surface) => agentRoomKey(surface, name)),
+		];
+	const group = store.group(name);
+	if (group)
+		return [
+			...(group.channelId ? [discordKey(group.channelId)] : []),
+			...roomSurfaces.map((surface) => groupRoomKey(surface, name)),
+		];
+	return [];
+}