pi-roundtable 0.22.5 → 0.23.1

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

@@ -1,5 +1,11 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import {
+	CATALOG,
+	type CharacterInput,
+	CLASS_IDS,
+	type PaletteName,
+} from "../../characters/index.ts";
 import { AgentError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
 import { assistantName, messages } from "../i18n/index.ts";
@@ -14,16 +20,17 @@ import {
 } from "../runtime/text-tools.ts";
 import { timeZone } from "../time.ts";
 import {
-	MAX_AVATAR_PROMPT_CHARS,
 	MAX_GROUP_MEMBERS,
 	MAX_PROMPT_CHARS,
 	MIN_GROUP_MEMBERS,
 } from "./agent-store.ts";
 
+const PALETTE_NAMES = Object.keys(CATALOG.palettes) as PaletteName[];
+
 /** The tool that hands a request to another agent; a group seat has none. */
 export const MESSAGE_AGENT_TOOL = "message_agent";
 
-/** The tool that redraws an avatar; a host without an image provider does not offer it. */
+/** The tool that changes an agent's look; every host offers it. */
 export const AVATAR_TOOL = "agent_avatar";
 
 export const AGENT_TOOLS = [
@@ -40,6 +47,10 @@ export const AGENT_TOOLS = [
 	"channel_read",
 ] as const;
 
+/**
+ * @deprecated Agents are composed characters and no longer drawn; use `AgentTeam.dress`.
+ * Removed in 1.0.
+ */
 export type AvatarMode = "redraw" | "new_prompt" | "edit";
 
 /** What the agent tools do; the agent team implements it. Each returns text for the model. */
@@ -61,14 +72,15 @@ export interface AgentOps {
 			name: string;
 			displayName: string;
 			prompt: string;
-			/** Absent on a host without an image provider. */
-			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>;
-	avatar(name: string, mode: AvatarMode, text?: string): Promise<string>;
+	/** Changes an agent's look; a field left out stays as it is. */
+	avatar(name: string, look: CharacterInput): Promise<string>;
 	/** Queues the message and returns at once. */
 	message(caller: AgentTurnScope, to: string, text: string): string;
 	createGroup(input: {
@@ -106,12 +118,35 @@ const PROMPT = Type.String({
 	description:
 		"The agent's role prompt, in English: its job, sources, boundaries, and how it reports. Short and stated positively.",
 });
-const avatarPrompt = () =>
-	Type.String({
-		minLength: 1,
-		maxLength: MAX_AVATAR_PROMPT_CHARS,
-		description: `The avatar is ${assistantName()}'s face drawn as an anime character; describe the role's exaggerated pose and expression, one telling prop, the outfit colours, and the background colour. Pick outfit and background colours unlike the other agents' (their avatar prompts are in agent_get).`,
-	});
+const enumOf = (ids: readonly string[], description?: string) =>
+	Type.String({ enum: [...ids], ...(description ? { description } : {}) });
+const CLASS = enumOf(
+	CLASS_IDS,
+	`The agent's character class, which sets its outfit, hat, and prop. ${CLASS_IDS.map((id) => `${id}: ${CATALOG.classes[id].jobs}`).join("; ")}.`,
+);
+const COLOR = enumOf(
+	PALETTE_NAMES,
+	"The agent's color palette. Pick one unlike the other agents' (agent_get shows each look).",
+);
+const PARTS = Type.Object(
+	{
+		outfit: Type.Optional(enumOf(CATALOG.outfits)),
+		hat: Type.Optional(enumOf(CATALOG.hats)),
+		prop: Type.Optional(enumOf(CATALOG.props)),
+		hair: Type.Optional(enumOf(CATALOG.hair)),
+		beard: Type.Optional(enumOf([...CATALOG.beards, "none"])),
+		accessory: Type.Optional(enumOf([...CATALOG.accessories, "none"])),
+		build: Type.Optional(enumOf(["slim", "regular", "stout"])),
+		skin: Type.Optional(Type.Integer({ minimum: 0, maximum: 5 })),
+		hair_color: Type.Optional(
+			Type.String({
+				pattern: "^#[0-9a-fA-F]{6}$",
+				description: "A hex color such as #3b2a1a.",
+			}),
+		),
+	},
+	{ description: "Single parts to change; any left out stay as they are." },
+);
 const category = (kind: "Agents" | "Groups") =>
 	Type.String({
 		description: `The category its channel opens under: ${kind} (the default) or ${kind}-<suffix>, such as ${kind}-work; made when missing. Keep to the categories agent_list shows unless a new one fits better.`,
@@ -122,12 +157,38 @@ const MEMBERS = Type.Array(Type.String(), {
 	description: "Agent names in speaking-tie order.",
 });
 
+const PART_FIELDS = {
+	outfit: "outfit",
+	hat: "hat",
+	prop: "prop",
+	hair: "hair",
+	beard: "beard",
+	accessory: "accessory",
+	build: "build",
+	skin: "skin",
+	hair_color: "hairColor",
+} as const;
+
+/** The look a tool call names: class, color as palette, and parts; nothing it leaves out. */
+function lookOf(input: Record<string, unknown>): CharacterInput {
+	const look: Record<string, unknown> = {};
+	const klass = optionalString(input, "class");
+	const color = optionalString(input, "color");
+	if (klass) look.class = klass;
+	if (color) look.palette = color;
+	const parts = input.parts;
+	if (parts !== null && typeof parts === "object")
+		for (const [key, field] of Object.entries(PART_FIELDS)) {
+			const value = (parts as Record<string, unknown>)[key];
+			if (value !== undefined) look[field] = value;
+		}
+	return look as CharacterInput;
+}
+
 type AgentToolDef = TextToolDef<(typeof AGENT_TOOLS)[number]>;
 
 /** What the agent tools offer, by what the host can do. */
 export interface AgentToolOptions {
-	/** Whether an image provider is configured; without one there is no avatar prompt and no agent_avatar. */
-	avatars: boolean;
 	/** Whether the skills addon is on; without it agent_create takes no skills. */
 	skills: boolean;
 }
@@ -136,7 +197,7 @@ function toolDefs(
 	ops: AgentOps,
 	scope: AgentTurnScope,
 	owner: OwnerIdentity,
-	{ avatars, skills: skillsOn }: AgentToolOptions,
+	{ skills: skillsOn }: AgentToolOptions,
 ): AgentToolDef[] {
 	const o = ownerWords(owner);
 	const defs: AgentToolDef[] = [
@@ -152,7 +213,7 @@ function toolDefs(
 			name: "agent_get",
 			label: "Read agent",
 			description:
-				"Read an agent's display name, status, channel, model, thinking level, skills, prompt, and avatar prompt.",
+				"Read an agent's display name, status, channel, model, thinking level, skills, look, and prompt.",
 			parameters: Type.Object({ name: NAME }),
 			run: (i) => ops.get(requiredString(i, "name")),
 		},
@@ -195,7 +256,8 @@ function toolDefs(
 		{
 			name: "agent_create",
 			label: "Create agent",
-			description: `Create a new agent with its own channel and ${avatars ? "a drawn avatar" : "an avatar generated from its display name"}; it starts at once on the opening task in its channel. Its name is permanent.`,
+			description:
+				"Create a new agent with its own channel and a character picture; its look follows its role unless class and color are given. It starts at once on the opening task in its channel. Its name is permanent.",
 			parameters: Type.Object({
 				name: Type.String({
 					pattern: "^[a-z0-9-]{1,32}$",
@@ -204,7 +266,8 @@ function toolDefs(
 				}),
 				display_name: DISPLAY,
 				prompt: PROMPT,
-				...(avatars ? { avatar_prompt: avatarPrompt() } : {}),
+				class: Type.Optional(CLASS),
+				color: Type.Optional(COLOR),
 				task: Type.String({
 					minLength: 1,
 					maxLength: 4000,
@@ -225,13 +288,12 @@ function toolDefs(
 			run: (i) => {
 				const category = optionalString(i, "category");
 				const skills = stringList(i, "skills");
+				const look = lookOf(i);
 				return ops.create(scope, {
 					name: requiredString(i, "name"),
 					displayName: requiredString(i, "display_name"),
 					prompt: requiredString(i, "prompt"),
-					...(avatars
-						? { avatarPrompt: requiredString(i, "avatar_prompt") }
-						: {}),
+					...(Object.keys(look).length > 0 ? { character: look } : {}),
 					task: requiredString(i, "task"),
 					...(category ? { category } : {}),
 					...(skills && skills.length > 0 ? { skills } : {}),
@@ -240,30 +302,21 @@ function toolDefs(
 		},
 		{
 			name: AVATAR_TOOL,
-			label: "Redraw avatar",
+			label: "Change look",
 			description:
-				"Redraw an agent's avatar: redraw from its stored avatar prompt; new_prompt with a new avatar prompt, which replaces the stored one; or edit the current picture by an instruction.",
+				"Change an agent's look: its class, color, or single parts. What you leave out stays as it is; a new class keeps the agent's colors unless you give a color. The new picture shows from its next message.",
 			parameters: Type.Object({
 				name: NAME,
-				mode: Type.Union([
-					Type.Literal("redraw"),
-					Type.Literal("new_prompt"),
-					Type.Literal("edit"),
-				]),
-				text: Type.Optional(
-					Type.String({
-						maxLength: MAX_AVATAR_PROMPT_CHARS,
-						description:
-							"The new avatar prompt for new_prompt, or the instruction for edit.",
-					}),
-				),
+				class: Type.Optional(CLASS),
+				color: Type.Optional(COLOR),
+				parts: Type.Optional(PARTS),
 			}),
-			run: (i) =>
-				ops.avatar(
-					requiredString(i, "name"),
-					requiredString(i, "mode") as AvatarMode,
-					optionalString(i, "text"),
-				),
+			run: (i) => {
+				const look = lookOf(i);
+				if (Object.keys(look).length === 0)
+					throw new AgentError("Give a class, a color, or parts to change.");
+				return ops.avatar(requiredString(i, "name"), look);
+			},
 		},
 		{
 			name: "group_create",
@@ -391,7 +444,7 @@ function toolDefs(
 			run: (i) =>
 				ops.message(scope, requiredString(i, "to"), requiredString(i, "text")),
 		});
-	return avatars ? defs : defs.filter((def) => def.name !== AVATAR_TOOL);
+	return defs;
 }
 
 /** Registers the agent tools for one agent session. */

package/src/core/agents/avatar-studio.ts

@@ -1,11 +1,15 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import type { CharacterSpec } from "../../characters/index.ts";
+import { resolveCharacter } from "../../characters/index.ts";
 import { squarePng } from "../attachments/square-png.ts";
 import type { ImageDrawer } from "../contract/providers.ts";
+import { ConfigError } from "../domain/errors.ts";
 import { ProviderError } from "../errors.ts";
 import type { HttpRoute } from "../http/listeners.ts";
 import type { AvatarStudio } from "../services.ts";
+import { characterPng } from "./character-png.ts";
 import { fallbackAvatar } from "./fallback-avatar.ts";
 
 const AVATAR_SIDE = 512;
@@ -19,14 +23,20 @@ export type { ImageDrawer };
 export interface AvatarStudioOptions {
 	/** Where pictures are kept, one `<sha256>.png` each. */
 	dir: string;
-	/** Origin the pictures are served from, such as https://assistant.example.com. */
-	publicUrl: string;
+	/**
+	 * Origin the pictures are served from, such as https://assistant.example.com. Without one a
+	 * picture's URL is the path `/avatars/<hash>.png`, which a surface that serves the pictures
+	 * itself, through `serve`, resolves against its own origin.
+	 */
+	publicUrl?: string;
 	/** The assistant's neutral avatar: the style reference and the picture of an agent without one. */
 	referencePath: string;
 	/** The neutral avatar shipped with the package; the reference is replaced by it when the reference cannot be read as a picture. */
 	neutralPath?: string;
 	/** Told the error code of a reference that was replaced by `neutralPath`. */
 	onReferenceFailed?: (code: string) => void;
+	/** Rasterizes a character to a PNG; canvas with librsvg by default. A seam for tests. */
+	rasterize?: typeof characterPng;
 	/** Draws the pictures. Without one, the studio only makes each agent a picture from its name. */
 	draw?: ImageDrawer;
 }
@@ -40,15 +50,30 @@ export class FileAvatarStudio implements AvatarStudio {
 	readonly #options: AvatarStudioOptions;
 	#defaultHash: string | undefined;
 	#referencePath: string;
+	readonly #rasterize: typeof characterPng;
 
 	constructor(options: AvatarStudioOptions) {
 		this.#options = options;
+		this.#rasterize = options.rasterize ?? characterPng;
 		this.#referencePath = options.referencePath;
 		mkdirSync(options.dir, { recursive: true });
 	}
 
-	/** Stores the assistant's neutral avatar, the picture of an agent that has none yet. */
+	/**
+	 * Stores the assistant's neutral avatar, the picture of an agent that has none yet. First
+	 * rasterizes a probe character: the agents' pictures need canvas with SVG support (librsvg),
+	 * and a host without it refuses to start instead of failing on the first agent.
+	 */
 	async init(): Promise<void> {
+		try {
+			await this.#rasterize(resolveCharacter({ class: "wizard" }), {
+				size: 32,
+			});
+		} catch (error) {
+			throw new ConfigError(
+				`the agent server needs canvas with SVG support (librsvg) to draw the agents' pictures: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
 		try {
 			this.#defaultHash = await this.#referenceStore();
 		} catch (error) {
@@ -81,10 +106,17 @@ export class FileAvatarStudio implements AvatarStudio {
 	url(hash: string | undefined): string {
 		const chosen = hash ?? this.#defaultHash;
 		if (!chosen) throw new Error("the avatar studio was not initialized");
-		return `${this.#options.publicUrl}/avatars/${chosen}.png`;
+		return `${this.#options.publicUrl ?? ""}/avatars/${chosen}.png`;
+	}
+
+	/** Renders a character as the agent's picture and stores it by content hash; the same spec gives the same hash. */
+	async render(spec: CharacterSpec): Promise<string> {
+		return this.#keep(await this.#rasterize(spec, { size: AVATAR_SIDE }));
 	}
 
 	/**
+	 * @deprecated Agents are composed characters and no longer drawn; removed in 1.0.
+	 *
 	 * Draws a new picture from an avatar prompt: the assistant's face as an anime character in the
 	 * role's pose; returns its hash. Outfit and background colours come from the avatar prompt,
 	 * so agents stay easy to tell apart.
@@ -180,6 +212,10 @@ export class FileAvatarStudio implements AvatarStudio {
 			size: AVATAR_SIDE,
 			...(maxSide === undefined ? {} : { maxSide }),
 		});
+		return this.#keep(png);
+	}
+
+	#keep(png: Uint8Array): string {
 		const hash = createHash("sha256").update(png).digest("hex");
 		const path = this.#path(hash);
 		if (!existsSync(path)) writeFileSync(path, png);

package/src/core/agents/character-png.ts

@@ -0,0 +1,40 @@
+import { createCanvas, loadImage } from "canvas";
+import {
+	type CharacterSpec,
+	type ComposeOptions,
+	composeSvg,
+	STATE_EXPRESSION,
+} from "../../characters/index.ts";
+
+const PNG_SIDE = 512;
+
+/** What a Discord avatar shows: the idle face on the modern light disc. */
+const AVATAR_OPTIONS: ComposeOptions = {
+	look: "modern-light",
+	frame: "disc",
+	expr: STATE_EXPRESSION.idle,
+	state: "idle",
+	still: true,
+};
+
+/**
+ * A character as a PNG: the composer's SVG, rasterized by canvas (librsvg). The SVG is composer
+ * output only, never text from a user or an agent. Each picture on a page needs its own `uid`,
+ * so this passes one explicitly.
+ */
+export async function characterPng(
+	spec: CharacterSpec,
+	options: ComposeOptions = {},
+): Promise<Uint8Array> {
+	const size = options.size ?? PNG_SIDE;
+	const svg = composeSvg(spec, {
+		...AVATAR_OPTIONS,
+		uid: "png",
+		...options,
+		size,
+	});
+	const image = await loadImage(Buffer.from(svg));
+	const canvas = createCanvas(size, size);
+	canvas.getContext("2d").drawImage(image, 0, 0, size, size);
+	return canvas.toBuffer("image/png");
+}

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

@@ -75,15 +75,18 @@ export class GroupMessages {
 			DO UPDATE SET last_id = GREATEST(agent_group_cursors.last_id, EXCLUDED.last_id)`;
 	}
 
-	/** Marks every message so far as received by every member, for a group started over. */
-	async catchUp(group: AgentGroup): Promise<void> {
+	/**
+	 * Marks every message so far as received by every member, for a group started over; `log` is
+	 * the conversation's log, the group's own name unless it is a room's.
+	 */
+	async catchUp(group: AgentGroup, log: string = group.name): Promise<void> {
 		const rows: { id: string | number | null }[] = await this.#sql`
 			SELECT max(id) AS id FROM agent_group_messages
-			WHERE guild_id = ${this.#guild} AND group_name = ${group.name}`;
+			WHERE guild_id = ${this.#guild} AND group_name = ${log}`;
 		const last = rows[0]?.id;
 		if (last === null || last === undefined) return;
 		for (const member of group.members)
-			await this.advanceCursor(group.name, member, Number(last));
+			await this.advanceCursor(log, member, Number(last));
 	}
 
 	/**

package/src/core/agents/group-turns.ts

@@ -4,14 +4,19 @@ import { AgentError } from "../domain/errors.ts";
 import { messages } from "../i18n/index.ts";
 import type { Speaker } from "../speakers.ts";
 import { groupTurnText } from "./agent-prompt.ts";
-import type { Agent } from "./agent-store.ts";
+import type { Agent, AgentGroup } from "./agent-store.ts";
 import {
 	MAX_ROUND_REPLIES,
 	mentionedMembers,
 	planRound,
 	RECENT_FOR_SCORING,
 } from "./group-round.ts";
-import { channelIdOf, groupScope, groupSessionKey } from "./team-keys.ts";
+import {
+	groupLogName,
+	groupOfChannel,
+	groupScope,
+	groupSessionKey,
+} from "./team-keys.ts";
 import {
 	BACKLOG_LIMIT,
 	type Chain,
@@ -27,6 +32,15 @@ export class GroupTurns {
 		this.#host = host;
 	}
 
+	/** The active group whose Discord channel or room the key is. */
+	#groupOf(channel: ChannelKey): AgentGroup {
+		const { store, surfaces } = this.#host.options;
+		const group = groupOfChannel(store, surfaces, channel);
+		if (group?.status !== "active")
+			throw new AgentError(`no group owns ${channel}`);
+		return group;
+	}
+
 	/**
 	 * One owner message in a group channel: scored, then answered by the chosen members one at
 	 * a time, each seeing every group message since its last turn. Call inside the queue.
@@ -41,16 +55,15 @@ export class GroupTurns {
 	): Promise<void> {
 		const { store, scorer, confirmations, logger } = this.#host.options;
 		const runtime = this.#host.options.runtime();
-		const group = store.groupByChannel(channelIdOf(channel));
-		if (!group) throw new AgentError(`no group owns ${channel}`);
+		const group = this.#groupOf(channel);
+		// Each conversation of a group keeps its own log: the Discord channel's under the group's
+		// name, a room's under `<group>@<surface>`.
+		const log = groupLogName(group, channel);
 		const members = group.members
 			.map((name) => store.agent(name))
 			.filter((m): m is Agent => m?.status === "active");
-		const recent = await store.recentGroupMessages(
-			group.name,
-			RECENT_FOR_SCORING,
-		);
-		await store.appendGroupMessage(group.name, {
+		const recent = await store.recentGroupMessages(log, RECENT_FOR_SCORING);
+		await store.appendGroupMessage(log, {
 			author: speaker.tier === "owner" ? "owner" : `human:${speaker.id}`,
 			authorName:
 				speaker.tier === "owner" ? this.#host.options.owner.name : speaker.name,
@@ -63,7 +76,7 @@ export class GroupTurns {
 		const approvals = new Map<string, boolean>();
 		for (const member of members) {
 			const pending = await runtime.heldActions(
-				groupSessionKey(group, member.name),
+				groupSessionKey(group, member.name, channel),
 			);
 			// Only a speaker whose tier holds the held tools may approve or wake a seat for them.
 			if (!pending || !this.#host.mayApprove(speaker, pending)) continue;
@@ -100,10 +113,10 @@ export class GroupTurns {
 			if (member?.status !== "active") continue;
 			const first = !spoken.has(name);
 			spoken.add(name);
-			const backlog = await store.backlog(group.name, name, BACKLOG_LIMIT);
+			const backlog = await store.backlog(log, name, BACKLOG_LIMIT);
 			// Delivered once the session has the text, so a message never comes twice.
 			if (backlog.lastId !== undefined)
-				await store.advanceCursor(group.name, name, backlog.lastId);
+				await store.advanceCursor(log, name, backlog.lastId);
 			// Attachments and a confirmation belong to a member's first turn of the round only.
 			const extra: TurnExtra = { interactive: true };
 			if (first) {
@@ -112,7 +125,7 @@ export class GroupTurns {
 			}
 			const result = await this.#host.turn(
 				member,
-				groupScope(member, group),
+				groupScope(member, group, channel),
 				channel,
 				groupTurnText(group, member, backlog),
 				chain,
@@ -121,7 +134,7 @@ export class GroupTurns {
 			replies += 1;
 			last = member;
 			if (!result.ok) continue;
-			await store.appendGroupMessage(group.name, {
+			await store.appendGroupMessage(log, {
 				author: name,
 				authorName: this.#host.current(member).displayName,
 				text: result.text,