pi-roundtable 0.22.4 → 0.23.0

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

@@ -22,13 +22,14 @@ import { outcome } from "../routing/settle-turn.ts";
 import { systemTurn } from "../routing/system-turns.ts";
 import { addressee, attributed, type Speaker } from "../speakers.ts";
 import type { DiscordAgentTeam } from "./agent-team.ts";
-import { discordIdOf } from "./team-keys.ts";
+import { discordIdOf, roomOf } from "./team-keys.ts";
 
 /**
  * The agent server outranks every other claim on the Discord channels it owns, and its guild's
  * other channels stay silent even when another plugin's mode or a mention would answer there; a claim of a
- * plugin must use a higher priority to answer in that guild. It owns no channel of another
- * surface. It becomes the core's reserved branch once the team moves into the core
+ * plugin must use a higher priority to answer in that guild. Of another surface it owns only
+ * the rooms of an agent or group of the team on a surface that declares `agentRooms`, never
+ * another of its keys. It becomes the core's reserved branch once the team moves into the core
  * (pi-roundtable batch 7).
  */
 export const AGENT_SERVER_PRIORITY = 100;
@@ -58,7 +59,12 @@ export interface AgentClaimOptions {
 		| "startFresh"
 	>;
 	runtime: Pick<AgentRuntime, "steer" | "stop">;
-	surface: Pick<SurfacePort, "react" | "unreact">;
+	/**
+	 * `roomSurfaces` names the surfaces whose agent and group rooms the claim may own, and `of`
+	 * finds the surface that reads a message's attachments; without them the claim is Discord's alone.
+	 */
+	surface: Pick<SurfacePort, "react" | "unreact"> &
+		Partial<Pick<SurfacePort, "roomSurfaces" | "of">>;
 	/** Where a channel's attachments are saved. */
 	attachmentDir: (channel: ChannelKey) => string;
 	/** The downloads' limits: all of a message's files together (default 60 s), and one file without a byte (default 10 s). */
@@ -82,14 +88,24 @@ export interface AgentClaimOptions {
  */
 export function agentClaim(options: AgentClaimOptions): ChannelClaim {
 	const { team, runtime, surface, attachmentDir, logger, fetchImpl } = options;
-	const attachments = (message: InboundMessage) =>
-		attachmentsOf(
+	const attachments = (message: InboundMessage) => {
+		// A surface that made a message's attachments reads them itself; they are never fetched.
+		const surfaceOf = surface.of?.(message.channel);
+		const reader = surfaceOf?.readAttachment?.bind(surfaceOf);
+		return attachmentsOf(
 			message,
 			attachmentDir(message.channel),
 			logger,
 			fetchImpl,
-			options.attachmentDownload,
+			{
+				...options.attachmentDownload,
+				...(surfaceOf?.maxAttachmentBytes === undefined
+					? {}
+					: { maxBytes: surfaceOf.maxAttachmentBytes }),
+				...(reader ? { read: (ref) => reader(message.channel, ref) } : {}),
+			},
 		);
+	};
 	/** The channel context of a message in an agent's channel; none, logged, when it cannot be read. */
 	const around = async (
 		message: InboundMessage,
@@ -148,11 +164,14 @@ export function agentClaim(options: AgentClaimOptions): ChannelClaim {
 	return {
 		name: "agent-server",
 		priority: AGENT_SERVER_PRIORITY,
-		// Only Discord keys: another surface's channel is never the agent server's, whatever its id.
+		// Discord's channels, or the room of an agent or group on a surface that hosts rooms: another
+		// surface's key is never the agent server's, whatever its id, and a room needs a known name.
 		owns: (channel, space) =>
-			discordIdOf(channel) !== undefined &&
-			(team.owns(channel) !== undefined ||
-				(space !== undefined && space === team.guildId)),
+			discordIdOf(channel) !== undefined
+				? team.owns(channel) !== undefined ||
+					(space !== undefined && space === team.guildId)
+				: roomOf(channel, surface.roomSurfaces?.() ?? []) !== undefined &&
+					team.owns(channel) !== undefined,
 		admit: (message) => {
 			const owned = team.owns(message.channel);
 			// The agent server's other channels are the owner's notes: nothing there is answered.

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

@@ -61,7 +61,7 @@ function groupBlock(group: GroupStatus, now: Date): string {
 		? text.dashLastActive(when(group.lastActive, now))
 		: text.dashNotActive;
 	return [
-		`**${group.displayName}** <#${group.channelId}>`,
+		`**${group.displayName}**${group.channelId ? ` <#${group.channelId}>` : ""}`,
 		text.dashGroupMembers(group.members, group.host),
 		state,
 		`-# ${last}`,

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

@@ -1,3 +1,4 @@
+import type { ChannelKey } from "../domain/conversation.ts";
 import { AgentError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
 import { messages } from "../i18n/index.ts";
@@ -12,7 +13,13 @@ import {
 	returnedAnswerPost,
 } from "./agent-prompt.ts";
 import type { Agent } from "./agent-store.ts";
-import { discordKey, homeScope } from "./team-keys.ts";
+import {
+	agentRoomKey,
+	discordKey,
+	homeScope,
+	roomScope,
+	roomSurfaceOf,
+} from "./team-keys.ts";
 import {
 	type Chain,
 	type Exchange,
@@ -34,7 +41,11 @@ export class AgentMessages {
 			throw new AgentError("message_agent is for other agents, not yourself.");
 		const target = store.activeAgent(to);
 		const sender = store.activeAgent(caller.name);
-		if (!target.channelId) throw new AgentError(`${to} has no channel yet.`);
+		// A turn in a room of another surface talks to the other agents' rooms there, never in Discord.
+		const parent = this.#host.turnChannel(caller);
+		const via = roomSurfaceOf(parent);
+		if (via === undefined && !target.channelId)
+			throw new AgentError(`${to} has no channel yet.`);
 		// Every agent turn runs through #turn, which registers its chain; a message from anywhere
 		// else would start an uncounted chain, so it is refused.
 		const chain = this.#host.chains.get(caller.session);
@@ -47,11 +58,13 @@ export class AgentMessages {
 				chainLimitReason(addressee(chain.speaker, this.#host.options.owner)),
 			);
 		chain.messages += 1;
-		const targetChannel = discordKey(target.channelId);
-		const exchange = this.#openExchange(caller, sender, target, text);
+		const targetChannel = this.#home(target, via);
+		// The thread opens in the sender's turn channel, on its surface when that hosts threads; a
+		// surface that hosts none leaves the answer returning to the sender's room.
+		const exchange = this.#openExchange(parent, sender, target, text);
 		void queue
 			.run(targetChannel, async () =>
-				this.#deliver(sender, target, text, chain, await exchange),
+				this.#deliver(sender, target, text, chain, await exchange, via),
 			)
 			.catch((error: unknown) =>
 				logger.error(
@@ -66,17 +79,24 @@ export class AgentMessages {
 		return `Sent to "${target.displayName}". It works in its own channel; its answer comes back to you as a new turn.`;
 	}
 
+	/** The agent's own channel: its Discord channel, or its room on the surface of a room turn. */
+	#home(agent: Agent, via: string | undefined): ChannelKey {
+		return via === undefined
+			? discordKey(agent.channelId ?? "")
+			: agentRoomKey(via, agent.name);
+	}
+
 	/**
-	 * Opens the message's thread in the sender's turn channel and posts the request there under
-	 * the sender's name; undefined where no thread opens. Never rejects.
+	 * Opens the message's thread in the sender's turn channel, a Discord channel or a room, and
+	 * posts the request there under the sender's name; undefined where no thread opens. Never
+	 * rejects.
 	 */
 	async #openExchange(
-		caller: AgentTurnScope,
+		parent: ChannelKey,
 		sender: Agent,
 		target: Agent,
 		text: string,
 	): Promise<Exchange | undefined> {
-		const parent = this.#host.turnChannel(caller);
 		const thread = await this.#host.options.threads?.open(
 			parent,
 			`→ ${target.displayName}`,
@@ -105,9 +125,10 @@ export class AgentMessages {
 		text: string,
 		chain: Chain,
 		exchange: Exchange | undefined,
+		via: string | undefined,
 	): Promise<void> {
 		try {
-			await this.#exchange(sender, target, text, chain, exchange);
+			await this.#exchange(sender, target, text, chain, exchange, via);
 		} finally {
 			await exchange?.thread.close();
 		}
@@ -119,9 +140,10 @@ export class AgentMessages {
 		text: string,
 		chain: Chain,
 		exchange: Exchange | undefined,
+		via: string | undefined,
 	): Promise<void> {
 		const { queue, logger } = this.#host.options;
-		const targetChannel = discordKey(target.channelId ?? "");
+		const targetChannel = this.#home(target, via);
 		await this.#host.post(targetChannel, this.#host.current(sender), {
 			chunks: splitReply(
 				deliveredMessagePost(this.#host.current(target), text),
@@ -129,7 +151,7 @@ export class AgentMessages {
 		});
 		const result = await this.#host.turn(
 			target,
-			homeScope(target),
+			via === undefined ? homeScope(target) : roomScope(target, targetChannel),
 			targetChannel,
 			agentMessageText(
 				this.#host.current(sender),
@@ -142,8 +164,12 @@ export class AgentMessages {
 		if (thread && !result.ok)
 			await thread.close(messages().agentNoReply(result.error.message));
 		const current = this.#host.options.store.agent(sender.name);
-		if (current?.status !== "active" || !current.channelId) return;
-		const senderChannel = discordKey(current.channelId);
+		if (
+			current?.status !== "active" ||
+			(via === undefined && !current.channelId)
+		)
+			return;
+		const senderChannel = this.#home(current, via);
 		// With a thread the answer goes there, leaving the sender's channel its own reply.
 		if (result.ok)
 			await this.#host
@@ -173,7 +199,9 @@ export class AgentMessages {
 			.run(senderChannel, () =>
 				this.#host.turn(
 					current,
-					homeScope(current),
+					via === undefined
+						? homeScope(current)
+						: roomScope(current, senderChannel),
 					senderChannel,
 					followUp,
 					chain,

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

@@ -23,8 +23,6 @@ export function agentSystemPrompt(input: {
 	group?: { group: AgentGroup; members: readonly Agent[] };
 	/** Who the turn is for; without one, or the owner, the prompt speaks to the owner. */
 	speaker?: Speaker;
-	/** Whether agents can redraw avatars; false without an image provider. Default true. */
-	avatars?: boolean;
 	/** Whether the session offers generate_image; true only with an image provider. Default false. */
 	images?: boolean;
 }): string {
@@ -38,7 +36,7 @@ export function agentSystemPrompt(input: {
 		(guest && input.guestShared) || shared,
 		`You are "${agent.displayName}" (agent name \`${agent.name}\`), one of ${o.name}'s agents in ${o.his} Discord agent server. Each agent owns one channel and one conversation; you all share ${o.his} tools and ${o.his} memory.`,
 		roleText(agent, coordinator, who),
-		`The team: agent_list shows every agent and group; agent_get and agent_update read and improve any agent's prompt, display name, model, and thinking level, yours included; agent_create adds an agent with its own channel; ${input.avatars === false ? "" : "agent_avatar redraws an avatar; "}schedule_list with agent reads another agent's schedules. A message marked as coming from another agent is that agent speaking, not ${w.name}; only ${w.name} approves held actions.`,
+		`The team: agent_list shows every agent and group; agent_get and agent_update read and improve any agent's prompt, display name, model, and thinking level, yours included; agent_create adds an agent with its own channel; agent_avatar changes an agent's look (class, colors, parts); schedule_list with agent reads another agent's schedules. A message marked as coming from another agent is that agent speaking, not ${w.name}; only ${w.name} approves held actions.`,
 		`Your shell and file tools run on ${o.his} VPS as the user ${shellUser}, in the shared workspace ${workDir}.${input.scratchDir ? ` Write temporary files under the scratch dir ${input.scratchDir} ($TMPDIR), not elsewhere in /tmp; make them with \`mktemp -p "$TMPDIR"\`, since a bare \`mktemp\` ignores $TMPDIR on some systems.` : ""} Commands that are destructive or change the system, and writes outside the workspace${input.scratchDir ? " and the scratch dir" : ""}, are held for ${w.his} confirmation: tell ${w.him} exactly what will run and ask ${w.him} to confirm. To show a file you have, attach it to your reply with attach_file or give its path to discord_send_message; never read an image or base64 a file to send it.${input.images ? " To make a new picture, describe it to generate_image, which saves it and attaches it to your reply." : ""}`,
 	];
 	if (group) {
@@ -79,7 +77,7 @@ function roleText(
 	if (coordinator?.name === agent.name)
 		return `You are the team's coordinator: ${o.name}'s general requests come to you, and you hand specialist work to the agent that owns it.`;
 	const who = coordinator
-		? `The team's coordinator is "${coordinator.displayName}" (\`${coordinator.name}\`) in <#${coordinator.channelId}>.`
+		? `The team's coordinator is "${coordinator.displayName}" (\`${coordinator.name}\`)${coordinator.channelId ? ` in <#${coordinator.channelId}>` : ""}.`
 		: "The team's coordinator is the agent in the server's entry channel.";
 	return `${who} You are a specialist: speak of yourself only as "${agent.displayName}", never as the coordinator. Team work ${o.name} asks of you directly, such as creating agents or groups, archiving, or arranging channels, you do in your own name. When your role below is empty or only a placeholder, ask ${o.him} what your job is before taking on other work.`;
 }

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

@@ -1,3 +1,8 @@
+import {
+	type CharacterInput,
+	type CharacterSpec,
+	suggestCharacter,
+} from "../../characters/index.ts";
 import { AgentError } from "../domain/errors.ts";
 import { THINKING_LEVELS, type ThinkingLevel } from "../models.ts";
 
@@ -14,7 +19,9 @@ export interface Agent {
 	displayName: string;
 	prompt: string;
 	avatarPrompt: string;
-	/** The drawn picture's content hash, when one exists. */
+	/** What the agent looks like; absent only on a row read before the team assigned one. */
+	character?: CharacterSpec;
+	/** The rendered picture's content hash, when one exists. */
 	avatarHash?: string;
 	/** Its channel in the agent server; a seed agent has none until one is created. */
 	channelId?: string;
@@ -28,7 +35,8 @@ export interface Agent {
 export interface AgentGroup {
 	name: string;
 	displayName: string;
-	channelId: string;
+	/** Its Discord channel; absent in a team without Discord, whose groups live in rooms only. */
+	channelId?: string;
 	/** Agent names in the group's order. */
 	members: string[];
 	host: string;
@@ -39,7 +47,10 @@ export interface AgentSeed {
 	name: string;
 	displayName: string;
 	prompt: string;
-	avatarPrompt: string;
+	/** The agent's look, resolved over the class preset; without one the team suggests it from the role. */
+	character?: CharacterInput;
+	/** @deprecated Agents are composed characters; this is ignored and removed in 1.0. */
+	avatarPrompt?: string;
 	channelId?: string;
 }
 
@@ -104,3 +115,31 @@ export function checkAvatarPrompt(prompt: string): void {
 			`An avatar prompt must have 1 to ${MAX_AVATAR_PROMPT_CHARS} characters; this one has ${prompt.length}.`,
 		);
 }
+
+/** An agent's look: the one it was dressed in, otherwise the one its role suggests. */
+export function characterOf(
+	agent: Pick<Agent, "name" | "displayName" | "prompt" | "character">,
+): CharacterSpec {
+	return agent.character ?? suggestCharacter(agent);
+}
+
+/**
+ * An input read over a base look. A new class alone keeps the base's colors, since the agent's
+ * colors are its own, and a class keeps the base's skin and build unless the input names them, so
+ * two agents of one class still differ.
+ */
+export function overBase(
+	input: CharacterInput,
+	base: CharacterSpec,
+): CharacterInput {
+	if (input === null || typeof input !== "object" || input.class === undefined)
+		return input;
+	return {
+		skin: base.skin,
+		build: base.build,
+		...(input.palette === undefined && input.colors === undefined
+			? { colors: base.colors }
+			: {}),
+		...input,
+	};
+}

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

@@ -1,3 +1,4 @@
+import { readCharacter } from "../../characters/index.ts";
 import { scopeToGuild } from "../db/guild-scope.ts";
 import type { Migration } from "../db/migrations.ts";
 import type { ThinkingLevel } from "../models.ts";
@@ -9,6 +10,8 @@ export interface AgentRow {
 	prompt: string;
 	avatar_prompt: string;
 	avatar_hash: string | null;
+	/** jsonb: the stored spec, an object, or null before the team dressed the agent. */
+	character: unknown | null;
 	channel_id: string | null;
 	model: string | null;
 	thinking: ThinkingLevel | null;
@@ -18,28 +21,32 @@ export interface AgentRow {
 export interface GroupRow {
 	name: string;
 	display_name: string;
-	channel_id: string;
+	channel_id: string | null;
 	members: string;
 	host: string;
 	status: AgentStatus;
 }
 
-export const toAgent = (row: AgentRow): Agent => ({
-	name: row.name,
-	displayName: row.display_name,
-	prompt: row.prompt,
-	avatarPrompt: row.avatar_prompt,
-	...(row.avatar_hash ? { avatarHash: row.avatar_hash } : {}),
-	...(row.channel_id ? { channelId: row.channel_id } : {}),
-	...(row.model ? { model: row.model } : {}),
-	...(row.thinking ? { thinking: row.thinking } : {}),
-	status: row.status,
-});
+export const toAgent = (row: AgentRow): Agent => {
+	const character = readCharacter(row.character);
+	return {
+		name: row.name,
+		displayName: row.display_name,
+		prompt: row.prompt,
+		avatarPrompt: row.avatar_prompt,
+		...(character ? { character } : {}),
+		...(row.avatar_hash ? { avatarHash: row.avatar_hash } : {}),
+		...(row.channel_id ? { channelId: row.channel_id } : {}),
+		...(row.model ? { model: row.model } : {}),
+		...(row.thinking ? { thinking: row.thinking } : {}),
+		status: row.status,
+	};
+};
 
 export const toGroup = (row: GroupRow): AgentGroup => ({
 	name: row.name,
 	displayName: row.display_name,
-	channelId: row.channel_id,
+	...(row.channel_id ? { channelId: row.channel_id } : {}),
 	members: row.members.split(",").filter(Boolean),
 	host: row.host,
 	status: row.status,
@@ -95,8 +102,9 @@ export const agentsMigration: Migration = {
 };
 
 /**
- * The migrations of the store's tables for the guild the process serves: the tables, then
- * each row's guild, with existing rows given `guildId`.
+ * The migrations of the store's tables for the guild the process serves, or the local team
+ * without Discord: the tables, then each row's guild, with existing rows given `guildId`, then
+ * the group channel made optional.
  */
 export function agentMigrations(guildId: string): Migration[] {
 	return [
@@ -111,5 +119,19 @@ export function agentMigrations(guildId: string): Migration[] {
 					{ table: "agent_group_cursors", key: ["group_name", "agent_name"] },
 				]),
 		},
+		// A team without Discord has groups that live in rooms only, with no channel.
+		{
+			name: "agent-groups-channel-optional",
+			up: async (sql) => {
+				await sql`ALTER TABLE agent_groups ALTER COLUMN channel_id DROP NOT NULL`;
+			},
+		},
+		// The composed look, dressed in code at the team's start; rows keep their drawn picture until then.
+		{
+			name: "agents-character",
+			up: async (sql) => {
+				await sql`ALTER TABLE agents ADD COLUMN IF NOT EXISTS character jsonb`;
+			},
+		},
 	];
 }

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

@@ -1,4 +1,5 @@
 import type { SQL } from "bun";
+import type { CharacterSpec } from "../../characters/index.ts";
 import type { Migration } from "../db/migrations.ts";
 import { AgentError } from "../domain/errors.ts";
 import type { ThinkingLevel } from "../models.ts";
@@ -57,6 +58,8 @@ import { isCheckDatabase } from "../db/check-database.ts";
 export class PgAgentStore implements AgentDirectory {
 	readonly #sql: SQL;
 	readonly #agents = new Map<string, Agent>();
+	/** Agents whose character column holds a value, readable or not. */
+	readonly #dressed = new Set<string>();
 	readonly #groups = new Map<string, AgentGroup>();
 	/** The tail of the agent and group writes, which run one at a time so none reads a map another is about to change. */
 	#queue: Promise<unknown> = Promise.resolve();
@@ -93,7 +96,8 @@ export class PgAgentStore implements AgentDirectory {
 			.#sql`SELECT * FROM agent_groups WHERE guild_id = ${this.#guild}`;
 		this.#agents.clear();
 		this.#groups.clear();
-		for (const row of agents) this.#agents.set(row.name, toAgent(row));
+		this.#dressed.clear();
+		for (const row of agents) this.#keepAgentRow(row);
 		for (const row of groups) this.#groups.set(row.name, toGroup(row));
 	}
 
@@ -104,7 +108,7 @@ export class PgAgentStore implements AgentDirectory {
 			for (const seed of seeds) {
 				const rows: AgentRow[] = await this.#sql`
 				INSERT INTO agents (guild_id, name, display_name, prompt, avatar_prompt, channel_id)
-				VALUES (${this.#guild}, ${seed.name}, ${seed.displayName}, ${seed.prompt}, ${seed.avatarPrompt},
+				VALUES (${this.#guild}, ${seed.name}, ${seed.displayName}, ${seed.prompt}, ${seed.avatarPrompt ?? ""},
 					${seed.channelId ?? null})
 				ON CONFLICT DO NOTHING
 				RETURNING *`;
@@ -186,20 +190,25 @@ export class PgAgentStore implements AgentDirectory {
 		name: string;
 		displayName: string;
 		prompt: string;
-		avatarPrompt: string;
-		channelId: string;
+		/** @deprecated Ignored by the team; kept for a store written by an older host. */
+		avatarPrompt?: string;
+		character?: CharacterSpec;
+		avatarHash?: string;
+		/** Absent in a team without Discord, whose agents live in rooms. */
+		channelId?: string;
 	}): Promise<Agent> {
 		return this.#serial(async () => {
 			checkAgentName(agent.name);
 			checkDisplayName(agent.displayName);
 			checkPrompt(agent.prompt);
-			// An agent of a host without an image provider has no avatar prompt.
-			if (agent.avatarPrompt !== "") checkAvatarPrompt(agent.avatarPrompt);
+			const avatarPrompt = agent.avatarPrompt ?? "";
+			if (avatarPrompt !== "") checkAvatarPrompt(avatarPrompt);
 			this.#checkFree(agent.name);
 			const rows: AgentRow[] = await this.#sql`
-			INSERT INTO agents (guild_id, name, display_name, prompt, avatar_prompt, channel_id)
-			VALUES (${this.#guild}, ${agent.name}, ${agent.displayName.trim()}, ${agent.prompt}, ${agent.avatarPrompt},
-				${agent.channelId})
+			INSERT INTO agents (guild_id, name, display_name, prompt, avatar_prompt, channel_id, avatar_hash, character)
+			VALUES (${this.#guild}, ${agent.name}, ${agent.displayName.trim()}, ${agent.prompt}, ${avatarPrompt},
+				${agent.channelId ?? null}, ${agent.avatarHash ?? null},
+				${agent.character ?? null}::jsonb)
 			RETURNING *`;
 			return this.#keepAgent(rows[0]);
 		});
@@ -218,6 +227,7 @@ export class PgAgentStore implements AgentDirectory {
 			prompt?: string;
 			avatarPrompt?: string;
 			avatarHash?: string;
+			character?: CharacterSpec;
 			channelId?: string;
 			/** `null` returns it to the assistant's. */
 			model?: string | null;
@@ -245,6 +255,7 @@ export class PgAgentStore implements AgentDirectory {
 				prompt = ${change.prompt ?? current.prompt},
 				avatar_prompt = ${change.avatarPrompt ?? current.avatarPrompt},
 				avatar_hash = ${change.avatarHash ?? current.avatarHash ?? null},
+				character = CASE WHEN ${change.character !== undefined} THEN ${change.character ?? null}::jsonb ELSE character END,
 				channel_id = ${change.channelId ?? current.channelId ?? null},
 				model = ${model},
 				thinking = ${thinking},
@@ -282,11 +293,43 @@ export class PgAgentStore implements AgentDirectory {
 
 	#keepAgent(row: AgentRow | undefined): Agent {
 		if (!row) throw new AgentError("the agent was not found");
+		return this.#keepAgentRow(row);
+	}
+
+	#keepAgentRow(row: AgentRow): Agent {
 		const agent = toAgent(row);
 		this.#agents.set(agent.name, agent);
+		if (row.character !== null && row.character !== undefined)
+			this.#dressed.add(agent.name);
+		else this.#dressed.delete(agent.name);
 		return agent;
 	}
 
+	/** Whether the stored column holds a character, even one this version cannot read. */
+	hasStoredCharacter(name: string): boolean {
+		return this.#dressed.has(name);
+	}
+
+	/**
+	 * Stores a character and picture only while the agent still has none, so a look chosen in the
+	 * meantime wins. Returns whether it was written.
+	 */
+	async dressIfUndressed(
+		name: string,
+		character: CharacterSpec,
+		avatarHash: string,
+	): Promise<boolean> {
+		return this.#serial(async () => {
+			const rows: AgentRow[] = await this.#sql`
+			UPDATE agents SET character = ${character}::jsonb, avatar_hash = ${avatarHash}, updated_at = now()
+			WHERE guild_id = ${this.#guild} AND name = ${name} AND character IS NULL
+			RETURNING *`;
+			if (!rows[0]) return false;
+			this.#keepAgentRow(rows[0]);
+			return true;
+		});
+	}
+
 	#checkMembers(members: readonly string[], host: string): void {
 		if (
 			new Set(members).size !== members.length ||
@@ -311,7 +354,8 @@ export class PgAgentStore implements AgentDirectory {
 	async createGroup(group: {
 		name: string;
 		displayName: string;
-		channelId: string;
+		/** Absent in a team without Discord, whose groups live in rooms. */
+		channelId?: string;
 		members: string[];
 		host: string;
 	}): Promise<AgentGroup> {
@@ -320,7 +364,7 @@ export class PgAgentStore implements AgentDirectory {
 			checkDisplayName(group.displayName);
 			const rows: GroupRow[] = await this.#sql`
 			INSERT INTO agent_groups (guild_id, name, display_name, channel_id, members, host)
-			VALUES (${this.#guild}, ${group.name}, ${group.displayName.trim()}, ${group.channelId},
+			VALUES (${this.#guild}, ${group.name}, ${group.displayName.trim()}, ${group.channelId ?? null},
 				${group.members.join(",")}, ${group.host})
 			RETURNING *`;
 			return this.#keepGroup(rows[0]);
@@ -406,7 +450,7 @@ export class PgAgentStore implements AgentDirectory {
 	}
 
 	/** Marks every message so far as received by every member, for a group started over. */
-	catchUp(group: AgentGroup): Promise<void> {
-		return this.#messages.catchUp(group);
+	catchUp(group: AgentGroup, log?: string): Promise<void> {
+		return this.#messages.catchUp(group, log);
 	}
 }