pi-roundtable 0.1.0 → 0.2.1

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

@@ -2,6 +2,7 @@ import type { SQL } from "bun";
 import type { Migration } from "../db/migrations.ts";
 import { AgentError } from "../domain/errors.ts";
 import type { ThinkingLevel } from "../models.ts";
+import type { AgentDirectory } from "../services.ts";
 import {
 	type Agent,
 	type AgentGroup,
@@ -51,7 +52,7 @@ export {
  * Agents, groups, and group messages, in the database. Agents and groups are also held
  * in memory, because every inbound message asks and only this process changes them.
  */
-export class AgentStore {
+export class PgAgentStore implements AgentDirectory {
 	readonly #sql: SQL;
 	readonly #agents = new Map<string, Agent>();
 	readonly #groups = new Map<string, AgentGroup>();
@@ -74,8 +75,8 @@ export class AgentStore {
 	}
 
 	/** The store over the host's migrated pool, holding the rows of one guild. */
-	static async attach(sql: SQL, guildId: string): Promise<AgentStore> {
-		const store = new AgentStore(sql, guildId);
+	static async attach(sql: SQL, guildId: string): Promise<PgAgentStore> {
+		const store = new PgAgentStore(sql, guildId);
 		await store.#reload();
 		return store;
 	}
@@ -178,7 +179,8 @@ export class AgentStore {
 		checkAgentName(agent.name);
 		checkDisplayName(agent.displayName);
 		checkPrompt(agent.prompt);
-		checkAvatarPrompt(agent.avatarPrompt);
+		// An agent of a host without an image provider has no avatar prompt.
+		if (agent.avatarPrompt !== "") checkAvatarPrompt(agent.avatarPrompt);
 		this.#checkFree(agent.name);
 		const rows: AgentRow[] = await this.#sql`
 			INSERT INTO agents (guild_id, name, display_name, prompt, avatar_prompt, channel_id)

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

@@ -0,0 +1,389 @@
+import { beforeEach } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SQL } from "bun";
+import type { ContextUse } from "../contract/runtime.ts";
+import { NO_ATTACHMENTS } from "../domain/attachment.ts";
+import type {
+	ChannelKey,
+	PendingConfirmation,
+	TurnResult,
+} from "../domain/conversation.ts";
+import { AgentRunError } from "../domain/errors.ts";
+import type { TurnRequest } from "../domain/ports.ts";
+import { silentLogger } from "../log.ts";
+import { StoredSkillRegistry as SkillRegistry } from "../modules/skills/skill-registry.ts";
+import { SkillStore } from "../modules/skills/skill-store.ts";
+import type { PromptSection } from "../plugin.ts";
+import { type ChannelQueue, channelQueue } from "../routing/channel-queue.ts";
+import {
+	openTestStore,
+	TEST_GUILD,
+	type TestStore,
+	testDatabaseUrl,
+} from "../testing/database.ts";
+import { useTestLocale } from "../testing/locale.ts";
+import { OWNER_SPEAKER, TEST_OWNER } from "../testing/owner.ts";
+import type {
+	AgentCategory,
+	AgentChannels,
+	AgentPost,
+	AgentTurnRunner,
+	CategoryLayout,
+	ChannelMessage,
+} 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 { discordKey } from "./team-keys.ts";
+
+export const ENTRY = "1000";
+export const USABLE = [
+	"claude-bridge/claude-opus-5-5",
+	"openai-codex/gpt-6-sol",
+];
+
+export class FakeChannels implements AgentChannels {
+	posts: { channelId: string; post: AgentPost }[] = [];
+	created: string[] = [];
+	deleted = new Set<string>();
+	#next = 2000;
+	async post(channelId: string, post: AgentPost) {
+		this.posts.push({ channelId, post });
+	}
+	/** The server's categories in order, each with its channels in order. */
+	categories: CategoryLayout[] = [];
+	#nextCategory = 9000;
+	arranged: { layout: CategoryLayout[]; remove: string[] }[] = [];
+	categoryOf(channelId: string) {
+		return this.categories.find((c) => c.channelIds.includes(channelId))?.name;
+	}
+	/** Moves a channel to the end of the category, made when missing. */
+	put(channelId: string, category: AgentCategory) {
+		for (const c of this.categories)
+			c.channelIds = c.channelIds.filter((id) => id !== channelId);
+		let found = this.categories.find((c) => c.name === category);
+		if (!found) {
+			found = {
+				id: String(this.#nextCategory++),
+				name: category,
+				channelIds: [],
+			};
+			this.categories.push(found);
+		}
+		found.channelIds.push(channelId);
+	}
+	async createChannel(name: string, topic: string, category: AgentCategory) {
+		this.created.push(name);
+		const id = String(this.#next++);
+		this.topics.set(id, topic);
+		this.put(id, category);
+		return id;
+	}
+	async placeIn(channelId: string, category: AgentCategory) {
+		if (this.categoryOf(channelId) === category) return false;
+		this.put(channelId, category);
+		return true;
+	}
+	async layout() {
+		return structuredClone(this.categories);
+	}
+	async arrange(layout: CategoryLayout[], remove: string[]) {
+		this.arranged.push({ layout: structuredClone(layout), remove });
+		this.categories = layout.map((c) => ({
+			id: c.id ?? String(this.#nextCategory++),
+			name: c.name,
+			channelIds: [...c.channelIds],
+		}));
+	}
+	history: ChannelMessage[] = [];
+	reads: { channelId: string; limit: number; around?: string }[] = [];
+	async read(channelId: string, options: { limit: number; around?: string }) {
+		this.reads.push({ channelId, ...options });
+		return this.history;
+	}
+	topics = new Map<string, string>();
+	async setTopic(channelId: string, topic: string) {
+		this.topics.set(channelId, topic);
+	}
+	async exists(channelId: string) {
+		return !this.deleted.has(channelId);
+	}
+	webhooksRemoved: string[] = [];
+	async removeWebhook(channelId: string) {
+		this.webhooksRemoved.push(channelId);
+	}
+	texts(channelId: string) {
+		return this.posts
+			.filter((p) => p.channelId === channelId)
+			.map((p) => `${p.post.name}: ${p.post.chunks.join("")}`);
+	}
+}
+
+/** Answers every turn with a scripted reply; records what each turn received. */
+export class FakeRuntime implements AgentTurnRunner {
+	turns: TurnRequest[] = [];
+	reply: (request: TurnRequest) => string = (r) => `${r.agent?.name} ok`;
+	held = new Map<ChannelKey, PendingConfirmation>();
+	fresh: ChannelKey[] = [];
+	/** Runs inside a turn, like a tool call the model makes. */
+	during?: (request: TurnRequest) => unknown;
+	/** The next turn ends as if the owner pressed stop. */
+	stopNext = false;
+	async runTurn(request: TurnRequest): Promise<TurnResult> {
+		this.turns.push(request);
+		await this.during?.(request);
+		if (this.stopNext) {
+			this.stopNext = false;
+			return {
+				ok: false,
+				error: new AgentRunError("stopped by the owner"),
+				stopped: true,
+			};
+		}
+		return { ok: true, text: this.reply(request) };
+	}
+	async heldActions(session: ChannelKey) {
+		return this.held.get(session);
+	}
+	async startFresh(session: ChannelKey) {
+		this.fresh.push(session);
+	}
+	usage = new Map<ChannelKey, ContextUse>();
+	contextUsage(session: ChannelKey) {
+		return this.usage.get(session);
+	}
+}
+
+// CI runs the setup below about ten times slower than a laptop, and bun's 5 s hook limit
+// left a timed-out hook running while the next test dropped its tables.
+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 runtime: FakeRuntime;
+export interface TeamFixture {
+	store: TestStore<AgentStore>;
+	channels: FakeChannels;
+	runtime: FakeRuntime;
+	queue: ChannelQueue;
+	team: AgentTeam;
+	skillStore: TestStore<SkillStore>;
+	skills: SkillRegistry;
+}
+
+/** The fixture of the running test; set by `useTeamFixture` before each test. */
+export const fx = {} as TeamFixture;
+
+/** What the team reads from its plugins and its scorer; tests set it. */
+export const script: {
+	/** The relevance scores the scorer answers with. */
+	scores: Record<string, number> | undefined;
+	/** The prompt sections plugins add. */
+	prompt: PromptSection[];
+	/** The tools plugins defined for agents. */
+	tools: string[];
+} = { scores: undefined, prompt: [], tools: [] };
+let queue: ChannelQueue;
+let team: AgentTeam;
+let skillStore: TestStore<SkillStore>;
+let skills: SkillRegistry;
+export const removedSchedules: number[] = [];
+export const stops: string[] = [];
+/** The events the team reported, in order, as `turnStarted infra`, `turnEnded infra ok`, or `changed`. */
+export const eventLog: string[] = [];
+
+/** What a plugin adds to every agent's tools: a tool of its own and a group of another server's. */
+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[] {
+	return [
+		{
+			name: "coordinator",
+			displayName: "Coordinator",
+			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.",
+		},
+		{
+			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.",
+		},
+		{
+			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.",
+		},
+	];
+}
+
+/**
+ * Waits until every queued channel task has settled and every active agent has its avatar,
+ * which startup draws in the background; a fixed sleep was too short on a slow runner.
+ */
+export async function settle(): Promise<void> {
+	const deadline = Date.now() + 10_000;
+	const quiet = () =>
+		queue.busy().length === 0 &&
+		store.agents().every((a) => a.status !== "active" || a.avatarHash);
+	while (!quiet() && Date.now() < deadline) await Bun.sleep(5);
+	// Work the last task queued is still finishing.
+	await Bun.sleep(20);
+}
+
+/** Registers the fixture's per-test setup in the describe it is called from. */
+export function useTeamFixture(): void {
+	beforeEach(async () => {
+		// The expected texts are the neutral English catalog's.
+		useTestLocale();
+		await store?.close();
+		await skillStore?.close();
+		const admin = new SQL(testDatabaseUrl);
+		for (const table of [
+			"agents",
+			"agent_groups",
+			"agent_group_messages",
+			"agent_group_cursors",
+			"skills",
+			"skill_groups",
+			"agent_skills",
+		])
+			await admin.unsafe(`DROP TABLE IF EXISTS ${table}`);
+		await admin.close();
+		store = await openTestStore(AgentStore, TEST_GUILD);
+		const skillDir = mkdtempSync(join(tmpdir(), "roundtable-team-skills-"));
+		mkdirSync(join(skillDir, "repos/acme/kit/.git"), { recursive: true });
+		mkdirSync(join(skillDir, "repos/acme/kit/skills/kit-do"), {
+			recursive: true,
+		});
+		writeFileSync(
+			join(skillDir, "repos/acme/kit/skills/kit-do/SKILL.md"),
+			"---\nname: kit-do\ndescription: Use when changing source.\n---\n",
+		);
+		mkdirSync(join(skillDir, "builtin/writing-skills"), { recursive: true });
+		writeFileSync(
+			join(skillDir, "builtin/writing-skills/SKILL.md"),
+			"---\nname: writing-skills\ndescription: Use when creating, editing, or reviewing a skill.\n---\n",
+		);
+		skillStore = await openTestStore(SkillStore, TEST_GUILD);
+		skills = new SkillRegistry({
+			store: skillStore,
+			reposDir: join(skillDir, "repos"),
+			writtenDir: join(skillDir, "skills"),
+			builtinDir: join(skillDir, "builtin"),
+			logger: silentLogger(),
+		});
+		skills.init();
+		await skills.link("acme/kit", "skills");
+		channels = new FakeChannels();
+		runtime = new FakeRuntime();
+		script.scores = undefined;
+		script.prompt = [];
+		script.tools = [];
+		queue = channelQueue();
+		removedSchedules.length = 0;
+		stops.length = 0;
+		eventLog.length = 0;
+		team = new AgentTeam({
+			owner: TEST_OWNER,
+			shellUser: "mcops",
+			guildId: "1",
+			entryChannelId: ENTRY,
+			seeds: () => seeds(ENTRY),
+			store,
+			channels,
+			studio: {
+				url: (hash) => `https://x/avatars/${hash ?? "default"}.png`,
+				draw: async () => "a".repeat(64),
+				edit: async () => "b".repeat(64),
+			},
+			runtime: () => runtime,
+			pluginSelection: () => PLUGIN_SELECTION,
+			confirmations: { approves: async (_p, reply) => reply.includes("yes") },
+			scorer: { score: async () => script.scores },
+			events: {
+				turnStarted: (turn) => eventLog.push(`turnStarted ${turn.agent}`),
+				turnEnded: (turn) =>
+					eventLog.push(`turnEnded ${turn.agent} ${turn.result}`),
+				changed: () => eventLog.push("changed"),
+			},
+			promptSections: () => script.prompt,
+			pluginTools: () => script.tools,
+			models: {
+				defaults: {
+					model: "claude-bridge/claude-opus-5-5",
+					thinking: "medium",
+				},
+				usable: async () => USABLE,
+			},
+			schedules: {
+				forChannel: async (channel) =>
+					channel === discordKey("2000") ? [{ id: 7 }] : [],
+				remove: async (id) => removedSchedules.push(id),
+			},
+			queue,
+			startTyping: () => () => undefined,
+			showStop: (channel) => {
+				stops.push(`show ${channel}`);
+				return () => stops.push(`hide ${channel}`);
+			},
+			workDir: "/tmp/agents/work",
+			sharedPrompt: "Shared rules.",
+			skills,
+			logger: silentLogger(),
+		});
+		await team.start();
+		Object.assign(fx, {
+			store,
+			channels,
+			runtime,
+			queue,
+			team,
+			skillStore,
+			skills,
+		});
+		await settle();
+	}, HOOK_TIMEOUT_MS);
+}
+
+export const opsGroup = () => {
+	const group = store.group("ops");
+	if (!group) throw new Error("no ops group");
+	return group;
+};
+
+export const agentChannel = (name: string) =>
+	discordKey(store.agent(name)?.channelId ?? "");
+
+/** Runs `action` during the coordinator's turn, as a tool the model calls does. */
+export async function duringTurn<T>(action: () => Promise<T>): Promise<T> {
+	let outcome: { value: T } | { error: unknown } | undefined;
+	runtime.during = async () => {
+		// Only the first turn is the model's; the agent it creates starts one of its own.
+		runtime.during = undefined;
+		outcome = await action().then(
+			(value) => ({ value }),
+			(error: unknown) => ({ error }),
+		);
+	};
+	await team.answerOwner(
+		agentChannel("coordinator"),
+		OWNER_SPEAKER,
+		"go",
+		"go",
+		NO_ATTACHMENTS,
+	);
+	runtime.during = undefined;
+	if (!outcome || "error" in outcome)
+		throw (outcome as { error: unknown })?.error;
+	return outcome.value;
+}

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

@@ -5,11 +5,8 @@ import { AgentError, ScheduleError } from "../domain/errors.ts";
 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-registry.ts";
-import {
-	SKILL_TOOLS,
-	skillToolsExtension,
-} from "../modules/skills/skill-tools.ts";
+import type { ResolvedSkill } from "../modules/skills/skill-rules.ts";
+import type { AgentTeam } from "../services.ts";
 import type { TurnSelection } from "../sessions.ts";
 import { type Speaker, THE_SPEAKER } from "../speakers.ts";
 import { agentSystemPrompt } from "./agent-prompt.ts";
@@ -17,12 +14,13 @@ 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 { channelKey, channelOwner } from "./team-keys.ts";
+import { channelOwner, discordKey } from "./team-keys.ts";
 import {
 	layoutText,
 	planArrangement,
@@ -49,7 +47,7 @@ const READ_LIMIT = 50;
  * This team creates, changes, arranges, and archives agents and groups; its TeamTurns runs
  * their turns, group rounds, and messages between agents.
  */
-export class AgentTeam implements AgentOps {
+export class DiscordAgentTeam implements AgentOps, AgentTeam {
 	readonly #options: AgentTeamOptions;
 	readonly #turns: TeamTurns;
 	readonly #listeners: (() => void)[] = [];
@@ -101,7 +99,7 @@ export class AgentTeam implements AgentOps {
 		return channelOwner(this.#options.store, channel);
 	}
 
-	/** The tools every agent turn runs with: the plugins', plus the shell, agent, and skill tools. */
+	/** The tools every agent turn runs with: the plugins', plus the shell and agent tools. */
 	selection(scope?: AgentTurnScope): TurnSelection {
 		const plugged = this.#options.pluginSelection();
 		return {
@@ -112,9 +110,10 @@ export class AgentTeam implements AgentOps {
 					...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) =>
+							!(scope?.group && tool === MESSAGE_AGENT_TOOL) &&
+							!(tool === AVATAR_TOOL && !this.#avatars()),
 					),
-					...SKILL_TOOLS,
 					...(this.#options.pluginTools?.() ?? []),
 				]),
 			],
@@ -147,6 +146,7 @@ export class AgentTeam implements AgentOps {
 			workDir,
 			owner,
 			shellUser,
+			avatars: this.#avatars(),
 			...(group
 				? {
 						group: {
@@ -190,22 +190,22 @@ export class AgentTeam implements AgentOps {
 		return current ? [current, ...usable.filter((m) => m !== current)] : usable;
 	}
 
-	/** The agent and skill tools of one agent session. */
+	/** Whether agents can be offered drawing: an image provider is configured. */
+	#avatars(): boolean {
+		return this.#options.studio.canDraw !== false;
+	}
+
+	/** The agent tools of one agent session. */
 	extension(scope: AgentTurnScope): ExtensionFactory {
-		const { skills, store } = this.#options;
-		const agentTools = agentToolsExtension(this, scope, THE_SPEAKER);
-		const skillTools = skillToolsExtension(skills, (name) => {
-			store.activeAgent(name);
+		return agentToolsExtension(this, scope, THE_SPEAKER, {
+			avatars: this.#avatars(),
+			skills: this.#options.skills !== undefined,
 		});
-		return async (pi) => {
-			await agentTools(pi);
-			await skillTools(pi);
-		};
 	}
 
-	/** The skill files an agent's sessions load, built-in ones included. */
+	/** The skill files an agent's sessions load, built-in ones included; none while the skills addon is off. */
 	skillsOf(name: string): ResolvedSkill[] {
-		return this.#options.skills.carried(name).skills;
+		return this.#options.skills?.carried(name).skills ?? [];
 	}
 
 	/** Another active agent's channel, for schedule_list. */
@@ -213,7 +213,7 @@ export class AgentTeam implements AgentOps {
 		try {
 			const agent = this.#options.store.activeAgent(name);
 			if (!agent.channelId) throw new AgentError(`${name} has no channel yet`);
-			return channelKey(agent.channelId);
+			return discordKey(agent.channelId);
 		} catch (error) {
 			throw new ScheduleError(
 				error instanceof Error ? error.message : String(error),
@@ -254,7 +254,7 @@ export class AgentTeam implements AgentOps {
 
 	/**
 	 * The owner's message in an agent's channel; call inside the channel's queue. `text`
-	 * carries the reference, `replyText` is what he typed.
+	 * carries the reference, `replyText` is what they typed.
 	 */
 	answerOwner(
 		channel: ChannelKey,
@@ -380,7 +380,8 @@ export class AgentTeam implements AgentOps {
 		return agentDetails(
 			agent,
 			models.defaults,
-			skills.describeCarried(agent.name),
+			skills?.describeCarried(agent.name),
+			this.#avatars(),
 		);
 	}
 
@@ -408,7 +409,7 @@ export class AgentTeam implements AgentOps {
 			name: string;
 			displayName: string;
 			prompt: string;
-			avatarPrompt: string;
+			avatarPrompt?: string;
 			task: string;
 			category?: string;
 			skills?: string[];

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

@@ -23,12 +23,15 @@ import {
 /** 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. */
+export const AVATAR_TOOL = "agent_avatar";
+
 export const AGENT_TOOLS = [
 	"agent_list",
 	"agent_get",
 	"agent_update",
 	"agent_create",
-	"agent_avatar",
+	AVATAR_TOOL,
 	MESSAGE_AGENT_TOOL,
 	"group_create",
 	"group_update",
@@ -58,7 +61,8 @@ export interface AgentOps {
 			name: string;
 			displayName: string;
 			prompt: string;
-			avatarPrompt: string;
+			/** Absent on a host without an image provider. */
+			avatarPrompt?: string;
 			task: string;
 			category?: string;
 			skills?: string[];
@@ -120,10 +124,19 @@ const MEMBERS = Type.Array(Type.String(), {
 
 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;
+}
+
 function toolDefs(
 	ops: AgentOps,
 	scope: AgentTurnScope,
 	owner: OwnerIdentity,
+	{ avatars, skills: skillsOn }: AgentToolOptions,
 ): AgentToolDef[] {
 	const o = ownerWords(owner);
 	const defs: AgentToolDef[] = [
@@ -182,8 +195,7 @@ function toolDefs(
 		{
 			name: "agent_create",
 			label: "Create agent",
-			description:
-				"Create a new agent with its own channel and a drawn avatar; 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 ${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.`,
 			parameters: Type.Object({
 				name: Type.String({
 					pattern: "^[a-z0-9-]{1,32}$",
@@ -192,19 +204,23 @@ function toolDefs(
 				}),
 				display_name: DISPLAY,
 				prompt: PROMPT,
-				avatar_prompt: avatarPrompt(),
+				...(avatars ? { avatar_prompt: avatarPrompt() } : {}),
 				task: Type.String({
 					minLength: 1,
 					maxLength: 4000,
 					description: "Its opening task, self-contained.",
 				}),
 				category: Type.Optional(category("Agents")),
-				skills: Type.Optional(
-					Type.Array(Type.String(), {
-						description:
-							"Skills it carries, from skill_list; pick those its role needs. Change them later with agent_skills.",
-					}),
-				),
+				...(skillsOn
+					? {
+							skills: Type.Optional(
+								Type.Array(Type.String(), {
+									description:
+										"Skills it carries, from skill_list; pick those its role needs. Change them later with agent_skills.",
+								}),
+							),
+						}
+					: {}),
 			}),
 			run: (i) => {
 				const category = optionalString(i, "category");
@@ -213,7 +229,9 @@ function toolDefs(
 					name: requiredString(i, "name"),
 					displayName: requiredString(i, "display_name"),
 					prompt: requiredString(i, "prompt"),
-					avatarPrompt: requiredString(i, "avatar_prompt"),
+					...(avatars
+						? { avatarPrompt: requiredString(i, "avatar_prompt") }
+						: {}),
 					task: requiredString(i, "task"),
 					...(category ? { category } : {}),
 					...(skills && skills.length > 0 ? { skills } : {}),
@@ -221,7 +239,7 @@ function toolDefs(
 			},
 		},
 		{
-			name: "agent_avatar",
+			name: AVATAR_TOOL,
 			label: "Redraw avatar",
 			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.",
@@ -373,7 +391,7 @@ function toolDefs(
 			run: (i) =>
 				ops.message(scope, requiredString(i, "to"), requiredString(i, "text")),
 		});
-	return defs;
+	return avatars ? defs : defs.filter((def) => def.name !== AVATAR_TOOL);
 }
 
 /** Registers the agent tools for one agent session. */
@@ -381,6 +399,7 @@ export function agentToolsExtension(
 	ops: AgentOps,
 	scope: AgentTurnScope,
 	owner: OwnerIdentity,
+	options: AgentToolOptions,
 ): ExtensionFactory {
-	return textToolsExtension(toolDefs(ops, scope, owner), AgentError);
+	return textToolsExtension(toolDefs(ops, scope, owner, options), AgentError);
 }