pi-roundtable 0.23.1 → 0.24.0

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

@@ -0,0 +1,77 @@
+import type { CharacterSpec } from "../../characters/index.ts";
+import type { Logger } from "../log.ts";
+import type { Agent } from "./agent-store.ts";
+
+/** What the refresh needs of the team: the agents, a render, and a way to set the picture. */
+export interface AvatarRefreshDeps {
+	agents(): readonly Agent[];
+	/** Renders a look to its picture and returns the content hash; the same look gives the same hash. */
+	render(character: CharacterSpec): Promise<string>;
+	/**
+	 * Sets the picture only while the agent is active and still wears `character`; false when it
+	 * does not, which leaves the newer look's picture alone.
+	 */
+	setAvatar(
+		name: string,
+		character: CharacterSpec,
+		avatarHash: string,
+	): Promise<boolean>;
+	/** Set when the team stops: no further render, write or log happens. */
+	signal?: AbortSignal;
+	logger: Logger;
+}
+
+export interface AvatarRefreshResult {
+	rendered: number;
+	unchanged: number;
+	/** Archived, or given another look, while it rendered. */
+	skipped: number;
+	failed: number;
+}
+
+/**
+ * Renders every active agent that has a character again and sets the picture when its hash
+ * differs from the stored one, so a restart with nothing changed writes nothing. One agent's
+ * failure is counted and does not stop the others. An agent archived or given another look while
+ * it rendered is skipped, so the newer picture stays. Stops at once when the signal aborts, with
+ * no further write or log. Logs one summary line.
+ */
+export async function refreshAvatars(
+	deps: AvatarRefreshDeps,
+): Promise<AvatarRefreshResult> {
+	const { agents, render, setAvatar, signal, logger } = deps;
+	const result: AvatarRefreshResult = {
+		rendered: 0,
+		unchanged: 0,
+		skipped: 0,
+		failed: 0,
+	};
+	const reasons: string[] = [];
+	for (const agent of agents()) {
+		if (signal?.aborted) return result;
+		if (agent.status !== "active" || !agent.character) continue;
+		try {
+			const avatarHash = await render(agent.character);
+			if (signal?.aborted) return result;
+			if (avatarHash === agent.avatarHash) {
+				result.unchanged++;
+				continue;
+			}
+			if (await setAvatar(agent.name, agent.character, avatarHash))
+				result.rendered++;
+			else result.skipped++;
+		} catch (error) {
+			if (signal?.aborted) return result;
+			result.failed++;
+			reasons.push(
+				`${agent.name}: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+	if (signal?.aborted) return result;
+	const summary = { ...result, ...(reasons.length > 0 ? { reasons } : {}) };
+	const line = `avatars refreshed: re-rendered ${result.rendered}, unchanged ${result.unchanged}, skipped ${result.skipped}, failed ${result.failed}`;
+	if (result.failed > 0) logger.warn(summary, line);
+	else logger.info(summary, line);
+	return result;
+}

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

@@ -1,7 +1,7 @@
 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 type { CharacterSpec, Hex } from "../../characters/index.ts";
 import { resolveCharacter } from "../../characters/index.ts";
 import { squarePng } from "../attachments/square-png.ts";
 import type { ImageDrawer } from "../contract/providers.ts";
@@ -35,6 +35,8 @@ export interface AvatarStudioOptions {
 	neutralPath?: string;
 	/** Told the error code of a reference that was replaced by `neutralPath`. */
 	onReferenceFailed?: (code: string) => void;
+	/** The skin tones the pictures are drawn with; default the package's own. */
+	skins?: readonly Hex[];
 	/** 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. */
@@ -59,6 +61,12 @@ export class FileAvatarStudio implements AvatarStudio {
 		mkdirSync(options.dir, { recursive: true });
 	}
 
+	/** The host's skin tones as a compose option; nothing when it has none, which draws the package's own. */
+	#skins(): { skins?: readonly Hex[] } {
+		const { skins } = this.#options;
+		return skins ? { skins } : {};
+	}
+
 	/**
 	 * 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),
@@ -68,6 +76,7 @@ export class FileAvatarStudio implements AvatarStudio {
 		try {
 			await this.#rasterize(resolveCharacter({ class: "wizard" }), {
 				size: 32,
+				...this.#skins(),
 			});
 		} catch (error) {
 			throw new ConfigError(
@@ -111,7 +120,9 @@ export class FileAvatarStudio implements AvatarStudio {
 
 	/** 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 }));
+		return this.#keep(
+			await this.#rasterize(spec, { size: AVATAR_SIDE, ...this.#skins() }),
+		);
 	}
 
 	/**

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

@@ -9,6 +9,7 @@ import type { AgentTurnScope } from "../domain/ports.ts";
 import type { AgentChannels } from "./agent-ports.ts";
 import { overBase } from "./agent-rules.ts";
 import type { Agent, AgentGroup } from "./agent-store.ts";
+import { refreshAvatars } from "./avatar-refresh.ts";
 import {
 	agentOfChannel,
 	coordinatorOf,
@@ -27,17 +28,24 @@ import type { TeamContext } from "./team-options.ts";
 /** The team's startup, fresh starts, and archiving of agents and groups. */
 export class TeamLifecycle {
 	readonly #ctx: TeamContext;
+	readonly #stopped = new AbortController();
 
 	constructor(ctx: TeamContext) {
 		this.#ctx = ctx;
 	}
 
+	/** Ends the background avatar refresh: nothing is rendered, written or logged after it. */
+	stop(): void {
+		this.#stopped.abort();
+	}
+
 	// ── Startup ────────────────────────────────────────────────────────────
 
 	/**
 	 * Inserts the seed agents, gives every active agent a channel, archives agents and groups
 	 * 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
+	 * character in the background, then, with `refreshAvatars`, renders every agent's picture
+	 * again. Without Discord channels the agents live in rooms, which need no setup, so
 	 * none is made or checked.
 	 */
 	async start(): Promise<void> {
@@ -46,8 +54,25 @@ export class TeamLifecycle {
 		if (added.length > 0) logger.info({ added }, "seed agents added");
 		if (channels) await this.#startChannels(channels);
 		this.#ctx.changed();
-		void this.#dressMissing().then((dressed) => {
+		void this.#dressMissing().then(async (dressed) => {
+			if (this.#stopped.signal.aborted) return;
 			if (dressed) this.#ctx.changed();
+			if (!this.#ctx.options.refreshAvatars) return;
+			// Never throws: a failure is counted per agent, and the start has already finished.
+			const { store, studio, logger } = this.#ctx.options;
+			const result = await refreshAvatars({
+				agents: () => store.agents(),
+				render: (character) => studio.render(character),
+				setAvatar: (name, character, avatarHash) =>
+					store.setAvatarIfLook(name, character, avatarHash),
+				signal: this.#stopped.signal,
+				logger,
+			}).catch((error: unknown) => {
+				logger.warn({ err: error }, "avatars not refreshed");
+				return undefined;
+			});
+			if (result && !this.#stopped.signal.aborted && result.rendered > 0)
+				this.#ctx.changed();
 		});
 	}
 

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

@@ -31,6 +31,12 @@ export interface AgentTeamOptions
 	 */
 	studio: Pick<AvatarStudio, "url" | "render" | "draw" | "edit"> &
 		Partial<Pick<AvatarStudio, "canDraw">>;
+	/**
+	 * Render every active agent that has a character again when the team starts, and set the
+	 * picture of those whose hash changed; default false. Runs in the background after the agents
+	 * are dressed.
+	 */
+	refreshAvatars?: boolean;
 	/** The tools and groups the plugins give every agent, read before each agent turn. */
 	pluginSelection: () => ToolSelection;
 	models: AgentModels;

package/src/core/builtin/agent-server.ts

@@ -101,6 +101,11 @@ export interface AgentServerOptions {
 	 * `/avatars/<hash>.png`, which the surface that serves the pictures resolves against its origin.
 	 */
 	avatarUrl?: string;
+	/**
+	 * Render every agent's picture again at start (`characters.refreshAvatars`) and set it where
+	 * its hash differs from the stored one; default false.
+	 */
+	refreshAvatars?: boolean;
 	/** The assistant's neutral avatar: the style reference and the picture of an agent without one. */
 	avatarReference: string;
 	/** The picture used instead when `avatarReference` cannot be read as one; the failure is logged. */
@@ -202,6 +207,7 @@ export function agentServerPlugin(
 			if (!connection) hostsRooms = () => surfaces.roomSurfaces().length > 0;
 			const studio = new FileAvatarStudio({
 				dir: join(options.dataDir, "avatars"),
+				skins: context.env.characterSkins,
 				...(options.avatarUrl ? { publicUrl: options.avatarUrl } : {}),
 				referencePath: options.avatarReference,
 				...(options.avatarNeutral
@@ -255,6 +261,7 @@ export function agentServerPlugin(
 					? { channels: connection.agentChannels(options.guildId) }
 					: {}),
 				studio,
+				...(options.refreshAvatars ? { refreshAvatars: true } : {}),
 				runtime: () => running,
 				confirmations,
 				scorer: new RelevanceScorer(judge, logger, options.owner),
@@ -313,6 +320,12 @@ export function agentServerPlugin(
 				runtime: running,
 				approvals: confirmations,
 				avatars: studio,
+				workspace: {
+					workDir: options.workDir,
+					...(agentSessions.scratchDir
+						? { scratchDir: agentSessions.scratchDir }
+						: {}),
+				},
 			});
 			const attachmentDir = (channel: ChannelKey) =>
 				ownerAttachmentDir(options.dataDir, channel);
@@ -348,6 +361,7 @@ export function agentServerPlugin(
 						: []),
 					{
 						name: AGENT_TEAM_SERVICE,
+						stop: () => built.stop(),
 						// The dashboard shows the team, so it starts once the team has; the error
 						// reporter connects whether or not the team did, since it reports the failure.
 						startInBackground: async () => {

package/src/core/config/adapters.ts

@@ -18,8 +18,8 @@ export interface DiscordConfig {
 	token: string;
 	/** The agent server's guild id. */
 	guild: string;
-	/** The channel the coordinator lives in. */
-	entryChannel: string;
+	/** The channel the coordinator lives in. Required unless the configuration says `agentServer: false`, which has no coordinator. */
+	entryChannel?: string;
 	/** The root slash command, without the slash; default the lowercase assistant name. */
 	rootCommand?: string;
 	/**
@@ -92,7 +92,8 @@ export interface DiscordConfig {
 export interface ResolvedDiscord {
 	token: string;
 	guild: string;
-	entryChannel: string;
+	/** Undefined only with `agentServer: false`. */
+	entryChannel?: string;
 	rootCommand: string;
 	admin: boolean;
 	refusalHint?: string;
@@ -117,7 +118,9 @@ export function resolvedDiscord(
 	return {
 		token: discord.token,
 		guild: discord.guild,
-		entryChannel: discord.entryChannel,
+		...(discord.entryChannel === undefined
+			? {}
+			: { entryChannel: discord.entryChannel }),
 		rootCommand,
 		admin: discord.admin ?? true,
 		...(discord.refusalHint === undefined
@@ -170,7 +173,7 @@ const channelContextShape = shape({
 export const discordShape = shape({
 	token: text,
 	guild: text,
-	entryChannel: text,
+	entryChannel: optional(text),
 	rootCommand: optional(text),
 	admin: optional(bool),
 	refusalHint: optional(text),

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

@@ -41,3 +41,39 @@ export function checkAgentTeamKeys(
 			"config skills: the skills are the agents', and this host has none: without discord they need agents. Configure agents or discord, or remove skills.",
 		);
 }
+
+/** The keys of the configuration, as written, that only the agent server uses. */
+interface AgentOnlyKeys {
+	agents?: readonly unknown[];
+	skills?: unknown;
+	ops?: { agent?: string; conversation?: string };
+	discord?: {
+		agentMemory?: unknown;
+		agentSpeakers?: unknown;
+		attachmentDownload?: unknown;
+	};
+}
+
+/**
+ * Refuses, for `agentServer: false`, what only the agent server uses, as the configuration
+ * writes it (not as defaults fill it): the seeds need the server to create them. An empty `agents`
+ * list and `skills: false` say nothing, so they pass.
+ */
+export function checkAgentServerOff(config: AgentOnlyKeys): void {
+	const used: [string, boolean][] = [
+		["agents", (config.agents?.length ?? 0) > 0],
+		["skills", config.skills !== undefined && config.skills !== false],
+		["ops.agent", config.ops?.agent !== undefined],
+		["discord.agentMemory", config.discord?.agentMemory !== undefined],
+		["discord.agentSpeakers", config.discord?.agentSpeakers !== undefined],
+		[
+			"discord.attachmentDownload",
+			config.discord?.attachmentDownload !== undefined,
+		],
+	];
+	const found = used.find(([, set]) => set);
+	if (found)
+		throw new ConfigError(
+			`config ${found[0]}: only the agent server uses it, and agentServer is false. Remove ${found[0]}, or remove agentServer to keep the agent server.`,
+		);
+}

package/src/core/config/config-schema.ts

@@ -0,0 +1,138 @@
+import type { InterimTextMode } from "../domain/interim.ts";
+import { isLocale, type Locale } from "../i18n/index.ts";
+import { type EffortPolicy, THINKING_LEVELS } from "../models.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import type { Tier } from "../speakers.ts";
+import { accessShape } from "./access.ts";
+import { discordShape } from "./adapters.ts";
+import { attachmentsShape } from "./attachments.ts";
+import type { Pronouns } from "./config.ts";
+import { limitsShape } from "./limits.ts";
+import {
+	bool,
+	characterInput,
+	guarded,
+	integer,
+	list,
+	number,
+	oneOf,
+	optional,
+	record,
+	shape,
+	skinTones,
+	text,
+} from "./schema.ts";
+import { skillsField } from "./skills-config.ts";
+
+/** The shape `roundtable.config.ts` is checked against: every key, its type and its bounds. */
+const tierMembers = shape({
+	users: optional(list(text)),
+	roles: optional(list(text)),
+	everyone: optional(bool),
+});
+
+const isPolicy = (value: unknown): value is EffortPolicy =>
+	typeof value === "function";
+const isPlugin = (value: unknown): value is RoundtablePlugin =>
+	typeof value === "object" &&
+	value !== null &&
+	typeof (value as { name?: unknown }).name === "string" &&
+	typeof (value as { setup?: unknown }).setup === "function";
+
+export const configSchema = shape({
+	name: optional(text),
+	owner: optional(
+		shape({
+			id: text,
+			name: text,
+			pronouns: optional(oneOf<Pronouns>("he", "she", "they")),
+		}),
+	),
+	discord: optional(discordShape),
+	agentServer: optional(
+		guarded(
+			"false, to leave the agent server out (leave the key out to keep it)",
+			(value): value is false => value === false,
+		),
+	),
+	database: shape({ url: text }),
+	dataDir: text,
+	attachments: attachmentsShape,
+	agentDir: optional(text),
+	model: text,
+	thinking: optional(oneOf(...THINKING_LEVELS)),
+	judge: optional(
+		shape({ model: optional(text), threshold: optional(number(0, 1)) }),
+	),
+	effortPolicy: optional(
+		guarded("a function from a turn to its effort rule", isPolicy),
+	),
+	delegation: optional(
+		shape({
+			model: optional(text),
+			thinking: optional(oneOf(...THINKING_LEVELS)),
+		}),
+	),
+	locale: optional(
+		guarded("a locale, en or zh-TW", (value): value is Locale =>
+			isLocale(value),
+		),
+	),
+	timeZone: optional(text),
+	speakers: optional(
+		shape({ admins: optional(tierMembers), members: optional(tierMembers) }),
+	),
+	access: optional(accessShape),
+	background: optional(
+		shape({
+			perPrincipal: optional(
+				shape({
+					schedules: optional(integer(1, 10_000)),
+					delegations: optional(integer(1, 1_000)),
+				}),
+			),
+		}),
+	),
+	toolTiers: optional(record(oneOf<Tier>("owner", "admin", "member"))),
+	prompts: optional(shape({ shared: text, guest: optional(text) })),
+	agents: optional(
+		list(
+			shape({
+				name: text,
+				displayName: text,
+				prompt: text,
+				character: optional(characterInput),
+				avatarPrompt: optional(text),
+				channelId: optional(text),
+			}),
+		),
+	),
+	coordinator: optional(text),
+	characters: optional(
+		shape({ skins: optional(skinTones), refreshAvatars: optional(bool) }),
+	),
+	http: optional(
+		shape({
+			publicUrl: optional(text),
+			port: optional(integer(1, 65535)),
+			hostname: optional(text),
+			socketPath: optional(text),
+			socketMode: optional(integer(0, 0o777)),
+		}),
+	),
+	avatar: optional(text),
+	workDir: optional(text),
+	scratchDir: optional(text),
+	skills: optional(skillsField),
+	memory: optional(bool),
+	ops: optional(shape({ agent: optional(text), conversation: optional(text) })),
+	drainSeconds: optional(integer(1, 3_600)),
+	...limitsShape,
+	interimText: optional(oneOf<InterimTextMode>("on", "off")),
+	interimPrimaryChars: optional(integer(1, 100_000)),
+	plugins: optional(
+		list(
+			guarded("a plugin, an object with a name and a setup function", isPlugin),
+		),
+	),
+});