pi-roundtable 0.22.4 → 0.23.0

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

@@ -4,10 +4,13 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { SQL } from "bun";
 import type { ContextUse } from "../contract/runtime.ts";
+import type { ChatSurface } from "../contract/surface.ts";
 import { NO_ATTACHMENTS } from "../domain/attachment.ts";
 import type {
 	ChannelKey,
+	OutboundReply,
 	PendingConfirmation,
+	PostAuthor,
 	TurnResult,
 } from "../domain/conversation.ts";
 import { AgentRunError } from "../domain/errors.ts";
@@ -36,7 +39,10 @@ import type {
 } from "./agent-ports.ts";
 import type { AgentSeed } from "./agent-rules.ts";
 import { PgAgentStore as AgentStore } from "./agent-store.ts";
-import { DiscordAgentTeam as AgentTeam } from "./agent-team.ts";
+import {
+	DiscordAgentTeam as AgentTeam,
+	type AgentTeamOptions,
+} from "./agent-team.ts";
 import { discordKey } from "./team-keys.ts";
 
 export const ENTRY = "1000";
@@ -124,6 +130,50 @@ export class FakeChannels implements AgentChannels {
 	}
 }
 
+/**
+ * The surfaces a team replies through in rooms. `rooms` names the surfaces that host rooms and
+ * starts empty, so the Discord suites run as if no surface did; a room suite sets it.
+ */
+class FakeSurfaces {
+	rooms: string[] = [];
+	replies: { channel: ChannelKey; reply: OutboundReply }[] = [];
+	/** Interim posts as `channel name/agent: text`, edits included. */
+	interims: string[] = [];
+	roomSurfaces() {
+		return this.rooms;
+	}
+	/** A room's surface carries no files, as a surface that does not declare `supportsFiles`. */
+	of(_channel: ChannelKey): ChatSurface | undefined {
+		return undefined;
+	}
+	async sendReply(channel: ChannelKey, reply: OutboundReply) {
+		this.replies.push({ channel, reply });
+	}
+	interim(channel: ChannelKey, as?: PostAuthor) {
+		if (!as) return undefined;
+		return {
+			post: async (text: string) => {
+				this.interims.push(`${channel} ${as.name}/${as.agent}: ${text}`);
+				return {
+					edit: async (change: string) => {
+						this.interims.push(
+							`${channel} ${as.name}/${as.agent}: edit ${change}`,
+						);
+					},
+				};
+			},
+		};
+	}
+	/** What the room was told, as `agent: text`. */
+	texts(channel: ChannelKey) {
+		return this.replies.flatMap((r) =>
+			r.channel === channel
+				? [`${r.reply.author?.agent}: ${r.reply.chunks.join("")}`]
+				: [],
+		);
+	}
+}
+
 /** Answers every turn with a scripted reply; records what each turn received. */
 export class FakeRuntime implements AgentTurnRunner {
 	turns: TurnRequest[] = [];
@@ -166,10 +216,12 @@ export const HOOK_TIMEOUT_MS = 30_000;
 // Runs against a real PostgreSQL, only when ROUNDTABLE_TEST_DATABASE_URL is set.
 let store: TestStore<AgentStore>;
 let channels: FakeChannels;
+let surfaces: FakeSurfaces;
 let runtime: FakeRuntime;
 export interface TeamFixture {
 	store: TestStore<AgentStore>;
 	channels: FakeChannels;
+	surfaces: FakeSurfaces;
 	runtime: FakeRuntime;
 	queue: ChannelQueue;
 	team: AgentTeam;
@@ -206,29 +258,29 @@ export const eventLog: string[] = [];
 const PLUGIN_SELECTION = { tools: ["memory_add"], groups: ["workspace"] };
 
 /** The team a fresh database starts with: a coordinator in the entry channel, then two specialists. */
-function seeds(entryChannelId: string): AgentSeed[] {
+function seeds(entryChannelId: string | undefined): AgentSeed[] {
 	return [
 		{
 			name: "coordinator",
 			displayName: "Coordinator",
-			channelId: entryChannelId,
+			...(entryChannelId ? { channelId: entryChannelId } : {}),
 			prompt:
 				"You are the chief of staff of the owner's agent team. You hand work that belongs to a specialist to that agent with message_agent, one owner per task, and propose a new agent when a lasting responsibility has no owner.",
-			avatarPrompt: "A chief of staff mid-command, pointing the way.",
+			character: { class: "navigator", palette: "amber" },
 		},
 		{
 			name: "doctor",
 			displayName: "Doctor",
 			prompt:
 				"You keep the owner's agents healthy: read an agent's prompt with agent_get, find the instruction that caused a misbehavior, and fix it with agent_update.",
-			avatarPrompt: "A bot doctor holding up a giant stethoscope.",
+			character: { class: "healer", palette: "rose" },
 		},
 		{
 			name: "infra",
 			displayName: "Infra",
 			prompt:
 				"You manage the owner's servers. Check before you change: read state first, state what you will change and why, then act.",
-			avatarPrompt: "An infra engineer battling a server rack.",
+			character: { class: "engineer", palette: "purpure" },
 		},
 	];
 }
@@ -247,8 +299,19 @@ export async function settle(): Promise<void> {
 	await Bun.sleep(20);
 }
 
-/** Registers the fixture's per-test setup in the describe it is called from. */
-export function useTeamFixture(): void {
+/**
+ * Registers the fixture's per-test setup in the describe it is called from. With `local`, the team
+ * runs as on a host without Discord: no channels and no entry channel, the coordinator named by
+ * the configuration, and the rooms of surface `app`.
+ */
+export function useTeamFixture(
+	options: {
+		local?: boolean;
+		/** The studio the team renders with, called each test; the default fakes pictures. */
+		studio?: () => AgentTeamOptions["studio"];
+	} = {},
+): void {
+	const { local = false } = options;
 	beforeEach(async () => {
 		// The expected texts are the neutral English catalog's.
 		useTestLocale();
@@ -292,6 +355,8 @@ export function useTeamFixture(): void {
 		skills.init();
 		await skills.link("acme/kit", "skills");
 		channels = new FakeChannels();
+		surfaces = new FakeSurfaces();
+		if (local) surfaces.rooms = ["app"];
 		runtime = new FakeRuntime();
 		script.scores = undefined;
 		script.prompt = [];
@@ -304,13 +369,19 @@ export function useTeamFixture(): void {
 			owner: TEST_OWNER,
 			toolTiers: FIXTURE_TIERS,
 			shellUser: "mcops",
-			guildId: "1",
-			entryChannelId: ENTRY,
-			seeds: () => seeds(ENTRY),
+			guildId: local ? "local" : "1",
+			...(local
+				? { coordinator: "coordinator" }
+				: { entryChannelId: ENTRY, channels }),
+			seeds: () => seeds(local ? undefined : ENTRY),
 			store,
-			channels,
-			studio: {
+			surfaces,
+			studio: options.studio?.() ?? {
 				url: (hash) => `https://x/avatars/${hash ?? "default"}.png`,
+				render: async (spec) =>
+					new Bun.CryptoHasher("sha256")
+						.update(JSON.stringify(spec))
+						.digest("hex"),
 				draw: async () => "a".repeat(64),
 				edit: async () => "b".repeat(64),
 			},
@@ -335,7 +406,11 @@ export function useTeamFixture(): void {
 			},
 			schedules: {
 				forChannel: async (channel) =>
-					channel === discordKey("2000") ? [{ id: 7 }] : [],
+					channel === discordKey("2000")
+						? [{ id: 7 }]
+						: channel === "app:agent.doctor"
+							? [{ id: 8 }]
+							: [],
 				remove: async (id) => removedSchedules.push(id),
 			},
 			queue,
@@ -353,6 +428,7 @@ export function useTeamFixture(): void {
 		Object.assign(fx, {
 			store,
 			channels,
+			surfaces,
 			runtime,
 			queue,
 			team,

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

@@ -1,4 +1,5 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { CharacterInput } from "../../characters/index.ts";
 import type { TurnAttachments } from "../domain/attachment.ts";
 import type { ChannelKey, TurnResult } from "../domain/conversation.ts";
 import { AgentError, ScheduleError } from "../domain/errors.ts";
@@ -6,7 +7,7 @@ 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 { ResolvedSkill } from "../modules/skills/skill-rules.ts";
-import type { AgentTeam } from "../services.ts";
+import type { AgentChange, AgentTeam } from "../services.ts";
 import type { TurnSelection } from "../sessions.ts";
 import { type Speaker, THE_SPEAKER } from "../speakers.ts";
 import { agentSystemPrompt } from "./agent-prompt.ts";
@@ -14,13 +15,20 @@ import type { Agent } from "./agent-store.ts";
 import {
 	AGENT_TOOLS,
 	type AgentOps,
-	AVATAR_TOOL,
 	type AvatarMode,
 	agentToolsExtension,
 	MESSAGE_AGENT_TOOL,
 } from "./agent-tools.ts";
 import { TeamEditing } from "./team-editing.ts";
-import { channelOwner, discordKey } from "./team-keys.ts";
+import {
+	agentRoomKey,
+	channelOwner,
+	coordinatorOf,
+	discordIdOf,
+	discordKey,
+	keysOf,
+	roomSurfaceOf,
+} from "./team-keys.ts";
 import {
 	layoutText,
 	planArrangement,
@@ -33,6 +41,7 @@ import {
 	agentDetails,
 	channelIdFromRef,
 	messageLine,
+	NO_CHANNELS,
 	teamListText,
 } from "./team-text.ts";
 import { TeamTurns } from "./team-turns.ts";
@@ -94,9 +103,36 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		return teamStatus(this.#context);
 	}
 
-	/** 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
+	 * a surface that hosts rooms.
+	 */
 	owns(channel: ChannelKey): "agent" | "group" | undefined {
-		return channelOwner(this.#options.store, channel);
+		const { store, surfaces } = this.#options;
+		return channelOwner(
+			store,
+			channel,
+			discordIdOf(channel) === undefined
+				? (surfaces?.roomSurfaces() ?? [])
+				: [],
+		);
+	}
+
+	/**
+	 * The name of the coordinator: the agent in the entry channel, or, on a host without Discord,
+	 * the one the configuration names; undefined while none is active.
+	 */
+	coordinator(): string | undefined {
+		return coordinatorOf(this.#options.store, this.#options)?.name;
+	}
+
+	/**
+	 * Every key an agent or group is addressed by: its Discord channel when it has one, then its
+	 * room on each surface that hosts rooms; empty for an unknown name.
+	 */
+	roomsOf(name: string): ChannelKey[] {
+		const { store, surfaces } = this.#options;
+		return keysOf(store, name, surfaces?.roomSurfaces() ?? []);
 	}
 
 	/** The tools every agent turn runs with: the plugins', plus the shell and agent tools. */
@@ -110,9 +146,7 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 					...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) &&
-							!(tool === AVATAR_TOOL && !this.#avatars()),
+						(tool) => !(scope?.group && tool === MESSAGE_AGENT_TOOL),
 					),
 					...(this.#options.pluginTools?.() ?? []),
 				]),
@@ -128,7 +162,6 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 			workDir,
 			sharedPrompt,
 			guestPrompt,
-			entryChannelId,
 			owner,
 			shellUser,
 			scratchDir,
@@ -136,7 +169,7 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		const agent = store.agent(scope.name);
 		if (!agent) throw new AgentError(`no agent ${scope.name}`);
 		const group = scope.group ? store.group(scope.group) : undefined;
-		const coordinator = store.agentByChannel(entryChannelId);
+		const coordinator = coordinatorOf(store, this.#options);
 		const speaker = this.#turns.speakerOf(scope);
 		const base = agentSystemPrompt({
 			agent,
@@ -148,8 +181,7 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 			owner,
 			shellUser,
 			...(scratchDir ? { scratchDir } : {}),
-			avatars: this.#avatars(),
-			images: this.#avatars(),
+			images: this.#images(),
 			...(group
 				? {
 						group: {
@@ -193,15 +225,14 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		return current ? [current, ...usable.filter((m) => m !== current)] : usable;
 	}
 
-	/** Whether agents can be offered drawing: an image provider is configured. */
-	#avatars(): boolean {
+	/** Whether agents can be offered generate_image: an image provider is configured. */
+	#images(): boolean {
 		return this.#options.studio.canDraw !== false;
 	}
 
 	/** The agent tools of one agent session. */
 	extension(scope: AgentTurnScope): ExtensionFactory {
 		return agentToolsExtension(this, scope, THE_SPEAKER, {
-			avatars: this.#avatars(),
 			skills: this.#options.skills !== undefined,
 		});
 	}
@@ -211,12 +242,23 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		return this.#options.skills?.carried(name).skills ?? [];
 	}
 
-	/** Another active agent's channel, for schedule_list. */
-	channelOf(name: string): ChannelKey {
+	/**
+	 * Another active agent's channel, for schedule_list: its room on the surface `near` is on when
+	 * that surface hosts rooms, otherwise its Discord channel, otherwise its room on the first
+	 * surface that hosts rooms.
+	 */
+	channelOf(name: string, near?: ChannelKey): ChannelKey {
 		try {
 			const agent = this.#options.store.activeAgent(name);
-			if (!agent.channelId) throw new AgentError(`${name} has no channel yet`);
-			return discordKey(agent.channelId);
+			const rooms = this.#options.surfaces?.roomSurfaces() ?? [];
+			const surface = near === undefined ? undefined : roomSurfaceOf(near);
+			if (surface !== undefined && rooms.includes(surface))
+				return agentRoomKey(surface, name);
+			if (agent.channelId) return discordKey(agent.channelId);
+			const room = rooms[0];
+			if (room === undefined)
+				throw new AgentError(`${name} has no channel yet`);
+			return agentRoomKey(room, name);
 		} catch (error) {
 			throw new ScheduleError(
 				error instanceof Error ? error.message : String(error),
@@ -228,8 +270,8 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 
 	/**
 	 * 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.
 	 */
 	start(): Promise<void> {
 		return this.#lifecycle.start();
@@ -331,8 +373,10 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		around: string | undefined,
 		limit: number | undefined,
 	): Promise<string> {
+		const { channels } = this.#options;
+		if (!channels) throw new AgentError(NO_CHANNELS);
 		const id = channelIdFromRef(channel);
-		const messages = await this.#options.channels.read(id, {
+		const messages = await channels.read(id, {
 			limit: Math.min(Math.max(limit ?? 20, 1), READ_LIMIT),
 			...(around ? { around } : {}),
 		});
@@ -344,12 +388,11 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 	// ── AgentOps ───────────────────────────────────────────────────────────
 
 	async list(): Promise<string> {
-		return `${teamListText(this.#options.store)}\n\n${await this.#layoutText()}`;
-	}
-
-	async #layoutText(): Promise<string> {
 		const { store, channels } = this.#options;
-		return layoutText(await channels.layout(), store);
+		const list = teamListText(store);
+		return channels
+			? `${list}\n\n${layoutText(await channels.layout(), store)}`
+			: list;
 	}
 
 	/**
@@ -361,6 +404,7 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		entries: { category: string; names: string[] }[],
 	): Promise<string> {
 		const { store, channels, logger } = this.#options;
+		if (!channels) throw new AgentError(NO_CHANNELS);
 		const listed = resolveArrangement(entries, store);
 		const { layout, remove } = planArrangement(listed, await channels.layout());
 		await channels.arrange(layout, remove);
@@ -372,7 +416,7 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 			remove.length > 0
 				? ` ${remove.length} empty team categories were deleted.`
 				: "";
-		return `Arranged the channels.${removed}\n\n${await this.#layoutText()}`;
+		return `Arranged the channels.${removed}\n\n${layoutText(await channels.layout(), store)}`;
 	}
 
 	get(name: string): string {
@@ -384,7 +428,6 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 			agent,
 			models.defaults,
 			skills?.describeCarried(agent.name),
-			this.#avatars(),
 		);
 	}
 
@@ -394,38 +437,28 @@ 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: {
-			displayName?: string;
-			prompt?: string;
-			model?: string;
-			thinking?: string;
-		},
-	): Promise<string> {
+	update(name: string, change: AgentChange): Promise<string> {
 		return this.#editing.update(name, change);
 	}
 
 	create(
 		caller: AgentTurnScope,
-		input: {
-			name: string;
-			displayName: string;
-			prompt: string;
-			avatarPrompt?: string;
-			task: string;
-			category?: string;
-			skills?: string[];
-		},
+		input: Parameters<TeamEditing["create"]>[1],
 	): Promise<string> {
 		return this.#editing.create(caller, input);
 	}
 
-	avatar(name: string, mode: AvatarMode, text?: string): Promise<string> {
-		return this.#editing.avatar(name, mode, text);
+	/** Changes an agent's look; see `AgentTeam.dress`. */
+	dress(name: string, input: CharacterInput): Promise<Agent> {
+		return this.#editing.dress(name, input);
+	}
+
+	/** The agent tool that changes a look; see `AgentTeam.dress`. */
+	avatar(name: string, look: CharacterInput): Promise<string> {
+		return this.#editing.avatar(name, look);
 	}
 
-	/** Draws and stores a new picture; the owner's panel and the agent tool both use it. */
+	/** @deprecated Use `dress`; removed in 1.0. Draws and stores a new picture. */
 	redrawAvatar(name: string, mode: AvatarMode, text?: string): Promise<Agent> {
 		return this.#editing.redrawAvatar(name, mode, text);
 	}