pi-roundtable 0.1.0

package/src/core/modules/skills/skill-store.ts

@@ -0,0 +1,285 @@
+import type { SQL } from "bun";
+import { scopeToGuild } from "../../db/guild-scope.ts";
+import type { Migration } from "../../db/migrations.ts";
+import { AgentError } from "../../domain/errors.ts";
+
+/**
+ * A registered skill (repos-and-skills spec behavior 13). A linked skill's name and description
+ * live in its repository's file; an agent-written one keeps them here.
+ */
+export type SkillEntry =
+	| { kind: "linked"; name: string; repo: string; path: string }
+	| { kind: "written"; name: string; description: string; body: string };
+
+export interface SkillGroup {
+	name: string;
+	description: string;
+	skills: string[];
+}
+
+/** Who lost a removed skill (behavior 17). */
+export interface Detached {
+	agents: string[];
+	groups: string[];
+}
+
+interface SkillRow {
+	name: string;
+	kind: "linked" | "written";
+	repo: string | null;
+	path: string | null;
+	description: string | null;
+	body: string | null;
+}
+
+interface GroupRow {
+	name: string;
+	description: string;
+	skills: string;
+}
+
+const toEntry = (row: SkillRow): SkillEntry =>
+	row.kind === "linked"
+		? {
+				kind: "linked",
+				name: row.name,
+				repo: row.repo ?? "",
+				path: row.path ?? "",
+			}
+		: {
+				kind: "written",
+				name: row.name,
+				description: row.description ?? "",
+				body: row.body ?? "",
+			};
+
+const toGroup = (row: GroupRow): SkillGroup => ({
+	name: row.name,
+	description: row.description,
+	skills: row.skills.split(",").filter(Boolean),
+});
+
+/**
+ * The kind an agent-written skill was stored under before it became 'written': the first
+ * consumer's own name, spelled from parts so the public tree names no consumer.
+ */
+export const LEGACY_WRITTEN_KIND = ["mer", "lin"].join("");
+
+/**
+ * Skills, skill groups, and the skills each agent carries, in the database. All of it is
+ * also held in memory, because every agent turn resolves its skills and only this process
+ * changes them.
+ */
+export class SkillStore {
+	readonly #sql: SQL;
+	readonly #skills = new Map<string, SkillEntry>();
+	readonly #groups = new Map<string, SkillGroup>();
+	readonly #carried = new Map<string, string[]>();
+
+	readonly #guild: string;
+
+	private constructor(sql: SQL, guildId: string) {
+		this.#sql = sql;
+		this.#guild = guildId;
+	}
+
+	/** The store's tables; the host runs this before any store attaches. */
+	static readonly migration: Migration = {
+		name: "skills",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS skills (
+					name text PRIMARY KEY,
+					kind text NOT NULL,
+					repo text,
+					path text,
+					description text,
+					body text,
+					created_at timestamptz NOT NULL DEFAULT now(),
+					updated_at timestamptz NOT NULL DEFAULT now()
+				)`;
+			await sql`
+				CREATE TABLE IF NOT EXISTS skill_groups (
+					name text PRIMARY KEY,
+					description text NOT NULL,
+					-- Comma-separated skill names, which never contain a comma.
+					skills text NOT NULL
+				)`;
+			await sql`
+				CREATE TABLE IF NOT EXISTS agent_skills (
+					agent text NOT NULL,
+					skill text NOT NULL,
+					PRIMARY KEY (agent, skill)
+				)`;
+		},
+	};
+
+	/**
+	 * The store's tables, then the guild of each agent's skills, existing rows given `guildId`.
+	 * The skill catalog itself is shared by every guild.
+	 */
+	static migrations(guildId: string): Migration[] {
+		return [
+			SkillStore.migration,
+			{
+				name: "skills-guild",
+				up: (sql) =>
+					scopeToGuild(sql, guildId, [
+						{ table: "agent_skills", key: ["agent", "skill"] },
+					]),
+			},
+			{
+				// Skills an agent wrote were stored under the legacy kind; the kind is now 'written'.
+				name: "skills-written-kind",
+				up: async (sql) => {
+					await sql`UPDATE skills SET kind = 'written' WHERE kind = ${LEGACY_WRITTEN_KIND}`;
+				},
+			},
+		];
+	}
+
+	/** The store over the host's migrated pool; the skills agents carry are those of one guild. */
+	static async attach(sql: SQL, guildId: string): Promise<SkillStore> {
+		const store = new SkillStore(sql, guildId);
+		await store.#reload();
+		return store;
+	}
+
+	async #reload(): Promise<void> {
+		const skills: SkillRow[] = await this.#sql`SELECT * FROM skills`;
+		const groups: GroupRow[] = await this.#sql`SELECT * FROM skill_groups`;
+		const carried: { agent: string; skill: string }[] = await this
+			.#sql`SELECT agent, skill FROM agent_skills
+			WHERE guild_id = ${this.#guild} ORDER BY agent, skill`;
+		this.#skills.clear();
+		this.#groups.clear();
+		this.#carried.clear();
+		for (const row of skills) this.#skills.set(row.name, toEntry(row));
+		for (const row of groups) this.#groups.set(row.name, toGroup(row));
+		for (const row of carried)
+			this.#carried.set(row.agent, [
+				...(this.#carried.get(row.agent) ?? []),
+				row.skill,
+			]);
+	}
+
+	skills(): SkillEntry[] {
+		return [...this.#skills.values()].sort((a, b) =>
+			a.name.localeCompare(b.name),
+		);
+	}
+
+	skill(name: string): SkillEntry | undefined {
+		return this.#skills.get(name);
+	}
+
+	groups(): SkillGroup[] {
+		return [...this.#groups.values()].sort((a, b) =>
+			a.name.localeCompare(b.name),
+		);
+	}
+
+	group(name: string): SkillGroup | undefined {
+		return this.#groups.get(name);
+	}
+
+	/** The registered skills an agent carries, by name. */
+	carriedBy(agent: string): string[] {
+		return this.#carried.get(agent) ?? [];
+	}
+
+	/** The agents carrying a skill. */
+	carriers(skill: string): string[] {
+		return [...this.#carried]
+			.filter(([, skills]) => skills.includes(skill))
+			.map(([agent]) => agent)
+			.sort();
+	}
+
+	/** Registers linked skills together, or none when any name is taken. */
+	async addLinked(
+		entries: readonly { name: string; repo: string; path: string }[],
+	): Promise<void> {
+		const taken = entries.filter((entry) => this.#skills.has(entry.name));
+		if (taken.length > 0)
+			throw new AgentError(
+				`Already registered: ${taken.map((entry) => entry.name).join(", ")}. Nothing was linked.`,
+			);
+		await this.#sql.begin(async (tx) => {
+			for (const entry of entries)
+				await tx`
+					INSERT INTO skills (name, kind, repo, path)
+					VALUES (${entry.name}, 'linked', ${entry.repo}, ${entry.path})`;
+		});
+		for (const entry of entries)
+			this.#skills.set(entry.name, { kind: "linked", ...entry });
+	}
+
+	async addWritten(skill: {
+		name: string;
+		description: string;
+		body: string;
+	}): Promise<void> {
+		if (this.#skills.has(skill.name))
+			throw new AgentError(`A skill named "${skill.name}" already exists.`);
+		await this.#sql`
+			INSERT INTO skills (name, kind, description, body)
+			VALUES (${skill.name}, 'written', ${skill.description}, ${skill.body})`;
+		this.#skills.set(skill.name, { kind: "written", ...skill });
+	}
+
+	async updateWritten(skill: {
+		name: string;
+		description: string;
+		body: string;
+	}): Promise<void> {
+		await this.#sql`
+			UPDATE skills SET description = ${skill.description}, body = ${skill.body},
+				updated_at = now()
+			WHERE name = ${skill.name} AND kind = 'written'`;
+		this.#skills.set(skill.name, { kind: "written", ...skill });
+	}
+
+	/** Removes a skill and detaches it from every agent and group. */
+	async remove(name: string): Promise<Detached> {
+		const agents = this.carriers(name);
+		const groups = this.groups().filter((group) => group.skills.includes(name));
+		await this.#sql.begin(async (tx) => {
+			await tx`DELETE FROM skills WHERE name = ${name}`;
+			await tx`DELETE FROM agent_skills WHERE guild_id = ${this.#guild} AND skill = ${name}`;
+			for (const group of groups)
+				await tx`
+					UPDATE skill_groups
+					SET skills = ${group.skills.filter((s) => s !== name).join(",")}
+					WHERE name = ${group.name}`;
+		});
+		await this.#reload();
+		return { agents, groups: groups.map((group) => group.name) };
+	}
+
+	async setGroup(group: SkillGroup): Promise<void> {
+		await this.#sql`
+			INSERT INTO skill_groups (name, description, skills)
+			VALUES (${group.name}, ${group.description}, ${group.skills.join(",")})
+			ON CONFLICT (name) DO UPDATE
+			SET description = EXCLUDED.description, skills = EXCLUDED.skills`;
+		this.#groups.set(group.name, { ...group, skills: [...group.skills] });
+	}
+
+	async removeGroup(name: string): Promise<void> {
+		await this.#sql`DELETE FROM skill_groups WHERE name = ${name}`;
+		this.#groups.delete(name);
+	}
+
+	/** Replaces the registered skills an agent carries. */
+	async setCarried(agent: string, skills: readonly string[]): Promise<void> {
+		const sorted = [...new Set(skills)].sort();
+		await this.#sql.begin(async (tx) => {
+			await tx`DELETE FROM agent_skills WHERE guild_id = ${this.#guild} AND agent = ${agent}`;
+			for (const skill of sorted)
+				await tx`INSERT INTO agent_skills (guild_id, agent, skill) VALUES (${this.#guild}, ${agent}, ${skill})`;
+		});
+		if (sorted.length > 0) this.#carried.set(agent, sorted);
+		else this.#carried.delete(agent);
+	}
+}

package/src/core/modules/skills/skill-tools.ts

@@ -0,0 +1,207 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { AgentError } from "../../domain/errors.ts";
+import {
+	optionalString,
+	requiredString,
+	stringList,
+	textToolsExtension,
+} from "../../runtime/text-tools.ts";
+import { MAX_SKILL_BODY_CHARS, type SkillRegistry } from "./skill-registry.ts";
+
+export const SKILL_LIST_TOOL = "skill_list";
+
+/** The skill tools only agents have; the DM reads the registry with skill_list alone. */
+export const SKILL_TOOLS = [
+	"skill_link",
+	"skill_unlink",
+	"skill_create",
+	"skill_update",
+	"skill_delete",
+	"skill_group_set",
+	"skill_group_delete",
+	"agent_skills",
+] as const;
+
+const SKILL_NAME = Type.String({
+	description: "A skill's name, from skill_list.",
+});
+const SKILL_NAMES = Type.Array(Type.String(), {
+	description: "Skill names, from skill_list.",
+});
+const DESCRIPTION = Type.String({
+	minLength: 1,
+	maxLength: 1024,
+	description:
+		'When to use the skill and nothing else, starting with "Use when": one trigger per distinct way it is used, no summary of its steps.',
+});
+const BODY = Type.String({
+	minLength: 1,
+	maxLength: MAX_SKILL_BODY_CHARS,
+	description:
+		"The Markdown body after the frontmatter, which the tool writes. Follow the writing-skills skill: short, stated positively, steps ending on a checkable completion criterion.",
+});
+
+/** skill_list, for the DM and for agents. */
+export function skillListExtension(registry: SkillRegistry): ExtensionFactory {
+	return textToolsExtension(
+		[
+			{
+				name: SKILL_LIST_TOOL,
+				label: "List skills",
+				description:
+					"List the skill registry: each skill's kind (built in, linked from a repository and read-only, or written by an agent), description, groups, and the agents carrying it, then the skill groups. Filter by a group or a word.",
+				parameters: Type.Object({
+					group: Type.Optional(
+						Type.String({ description: "A skill group's name." }),
+					),
+					query: Type.Optional(
+						Type.String({
+							description: "A word to find in names and descriptions.",
+						}),
+					),
+				}),
+				run: (i) => {
+					const group = optionalString(i, "group");
+					const query = optionalString(i, "query");
+					return registry.list({
+						...(group ? { group } : {}),
+						...(query ? { query } : {}),
+					});
+				},
+			},
+		],
+		AgentError,
+	);
+}
+
+/** The skill tools of an agent session (repos-and-skills spec behaviors 15–19). */
+export function skillToolsExtension(
+	registry: SkillRegistry,
+	/** Throws AgentError unless the name is an active agent. */
+	checkAgent: (name: string) => void,
+): ExtensionFactory {
+	return textToolsExtension(
+		[
+			{
+				name: "skill_link",
+				label: "Link skills",
+				description:
+					"Register a skill that lives in a managed repository: the path of a folder with SKILL.md, or of a folder whose child folders hold skills, all of which are linked. Name and description come from each file. Linked skills are read-only here; they change in their repository.",
+				parameters: Type.Object({
+					repo: Type.String({ description: "<owner>/<repo>, from repo_list." }),
+					path: Type.String({
+						description:
+							"A folder inside the repository, such as skills/plan-work or skills.",
+					}),
+				}),
+				run: (i) =>
+					registry.link(requiredString(i, "repo"), requiredString(i, "path")),
+			},
+			{
+				name: "skill_unlink",
+				label: "Unlink skill",
+				description:
+					"Remove a linked skill from the registry; it is detached from every agent and group. The repository is untouched.",
+				parameters: Type.Object({ name: SKILL_NAME }),
+				run: (i) => registry.unlink(requiredString(i, "name")),
+			},
+			{
+				name: "skill_create",
+				label: "Create skill",
+				description:
+					"Write a new skill into the registry. Read the writing-skills skill first. It does not attach the skill to anyone; use agent_skills.",
+				parameters: Type.Object({
+					name: Type.String({
+						pattern: "^[a-z0-9-]{1,64}$",
+						description:
+							"Permanent: lowercase letters, digits, and single hyphens.",
+					}),
+					description: DESCRIPTION,
+					body: BODY,
+				}),
+				run: (i) =>
+					registry.create({
+						name: requiredString(i, "name"),
+						description: requiredString(i, "description"),
+						body: requiredString(i, "body"),
+					}),
+			},
+			{
+				name: "skill_update",
+				label: "Update skill",
+				description:
+					"Replace a agent-written skill's description or body whole; read its SKILL.md (path in skill_list) first. Its carriers read the new version from their next turn.",
+				parameters: Type.Object({
+					name: SKILL_NAME,
+					description: Type.Optional(DESCRIPTION),
+					body: Type.Optional(BODY),
+				}),
+				run: (i) => {
+					const description = optionalString(i, "description");
+					const body = optionalString(i, "body");
+					return registry.update(requiredString(i, "name"), {
+						...(description !== undefined ? { description } : {}),
+						...(body !== undefined ? { body } : {}),
+					});
+				},
+			},
+			{
+				name: "skill_delete",
+				label: "Delete skill",
+				description:
+					"Delete a agent-written skill; it is detached from every agent and group.",
+				parameters: Type.Object({ name: SKILL_NAME }),
+				run: (i) => registry.delete(requiredString(i, "name")),
+			},
+			{
+				name: "skill_group_set",
+				label: "Set skill group",
+				description:
+					"Create or replace a skill group, a named list that only filters skill_list. Agents carry skills, not groups.",
+				parameters: Type.Object({
+					name: Type.String({ pattern: "^[a-z0-9-]{1,64}$" }),
+					description: Type.String({ minLength: 1, maxLength: 200 }),
+					skills: SKILL_NAMES,
+				}),
+				run: (i) =>
+					registry.setGroup(
+						requiredString(i, "name"),
+						requiredString(i, "description"),
+						stringList(i, "skills") ?? [],
+					),
+			},
+			{
+				name: "skill_group_delete",
+				label: "Delete skill group",
+				description: "Delete a skill group; its skills are untouched.",
+				parameters: Type.Object({ name: Type.String() }),
+				run: (i) => registry.deleteGroup(requiredString(i, "name")),
+			},
+			{
+				name: "agent_skills",
+				label: "Change agent skills",
+				description:
+					"Add and remove skills an agent carries, yours included; it applies from that agent's next turn. Built-in skills stay. An unknown name refuses the whole call.",
+				parameters: Type.Object({
+					agent: Type.String({
+						description: "An agent's name, from agent_list.",
+					}),
+					add: Type.Optional(SKILL_NAMES),
+					remove: Type.Optional(SKILL_NAMES),
+				}),
+				run: async (i) => {
+					const agent = requiredString(i, "agent");
+					checkAgent(agent);
+					const carried = await registry.attach(
+						agent,
+						stringList(i, "add") ?? [],
+						stringList(i, "remove") ?? [],
+					);
+					return `${agent} now carries: ${carried.join(", ") || "only the built-in skills"}.`;
+				},
+			},
+		],
+		AgentError,
+	);
+}