pi-roundtable 0.21.0 → 0.22.1

package/src/core/i18n/turn-timeout.ts

@@ -0,0 +1,131 @@
+import type { TurnTimeout } from "../domain/turn-timeout.ts";
+
+/** A duration in whole seconds, as "3 min 12 s", "45 s", or "1 h 5 min". */
+function durationEn(ms: number): string {
+	const s = Math.max(0, Math.round(ms / 1000));
+	const h = Math.floor(s / 3600);
+	const m = Math.floor((s % 3600) / 60);
+	const sec = s % 60;
+	if (h > 0) return m > 0 ? `${h} h ${m} min` : `${h} h`;
+	if (m > 0) return sec > 0 ? `${m} min ${sec} s` : `${m} min`;
+	return `${sec} s`;
+}
+
+function durationZh(ms: number): string {
+	const s = Math.max(0, Math.round(ms / 1000));
+	const h = Math.floor(s / 3600);
+	const m = Math.floor((s % 3600) / 60);
+	const sec = s % 60;
+	if (h > 0) return m > 0 ? `${h} 小時 ${m} 分` : `${h} 小時`;
+	if (m > 0) return sec > 0 ? `${m} 分 ${sec} 秒` : `${m} 分`;
+	return `${sec} 秒`;
+}
+
+/** The tools called so far, as the interim tool line shows them. */
+function toolList(tools: TurnTimeout["tools"], separator: string): string {
+	return tools
+		.map(([name, count]) => (count > 1 ? `${name} ×${count}` : name))
+		.join(separator);
+}
+
+/** The timeout card and the notice a turn posts when it ends at a time limit. */
+export function turnTimeoutEn() {
+	const doing = (t: TurnTimeout) =>
+		t.running.length > 0
+			? t.running
+					.map(({ tool, ms }) => `${tool}, running for ${durationEn(ms)}`)
+					.join("; ")
+			: t.compacting
+				? "compacting the conversation"
+				: "waiting on the model";
+	const limit = (t: TurnTimeout) =>
+		t.limit === "turn"
+			? `its time limit of ${durationEn(t.limitMs)} (since it started or since the last message steered into it)`
+			: `its cap of ${durationEn(t.limitMs)} of work in all`;
+	const tools = (t: TurnTimeout) =>
+		t.tools.length > 0 ? `Tools so far: ${toolList(t.tools, " · ")}.` : "";
+	return {
+		turnTimeoutTitle: "⏱️ This turn is taking long",
+		turnTimeoutQuestion: (t: TurnTimeout, budgetMs: number) =>
+			[
+				`It reached ${limit(t)} and has worked ${durationEn(t.workedMs)}.`,
+				`Now: ${doing(t)}.`,
+				tools(t),
+				`It keeps working while this card is open. Continue gives it another ${durationEn(budgetMs)}; Cancel stops it. With no answer in ${durationEn(t.graceMs)} it stops.`,
+			]
+				.filter(Boolean)
+				.join("\n"),
+		turnTimeoutContinue: "Continue",
+		turnTimeoutCancel: "Cancel",
+		turnTimeoutFooter:
+			"The turn is still working; answer whenever you are ready.",
+		turnTimeoutContinued: "▶️ Continued.",
+		turnTimeoutCancelled: "❌ Cancelled; the turn stops.",
+		turnTimeoutFinished: "✅ The turn finished; nothing to answer.",
+		turnTimeoutUnanswered: (t: TurnTimeout) =>
+			`⏱️ No answer in ${durationEn(t.graceMs)}; the turn was stopped.`,
+		turnTimedOutNotice: (t: TurnTimeout) => {
+			const what =
+				t.running.length > 0
+					? `while ${t.running.map(({ tool, ms }) => `${tool} was running (${durationEn(ms)})`).join(" and ")}`
+					: `while ${doing(t)}`;
+			const head =
+				t.end === "cancelled"
+					? `⏱️ Cancelled by the owner after ${durationEn(t.workedMs)} ${what}.`
+					: t.end === "unanswered"
+						? `⏱️ No answer to the timeout card in ${durationEn(t.graceMs)}, so the turn was stopped after ${durationEn(t.workedMs)} ${what}.`
+						: `⏱️ The turn reached ${limit(t)} and was stopped after ${durationEn(t.workedMs)} ${what}.`;
+			return [head, tools(t)].filter(Boolean).join(" ");
+		},
+	};
+}
+
+export function turnTimeoutZhTW(): ReturnType<typeof turnTimeoutEn> {
+	const doing = (t: TurnTimeout) =>
+		t.running.length > 0
+			? t.running
+					.map(({ tool, ms }) => `${tool}，已執行 ${durationZh(ms)}`)
+					.join("；")
+			: t.compacting
+				? "正在壓縮對話"
+				: "正在等模型回應";
+	const limit = (t: TurnTimeout) =>
+		t.limit === "turn"
+			? `時間上限 ${durationZh(t.limitMs)}（從開始或最後一則插入的訊息算起）`
+			: `總工作時間上限 ${durationZh(t.limitMs)}`;
+	const tools = (t: TurnTimeout) =>
+		t.tools.length > 0 ? `目前用過的工具：${toolList(t.tools, " · ")}。` : "";
+	return {
+		turnTimeoutTitle: "⏱️ 這一輪做得比較久",
+		turnTimeoutQuestion: (t: TurnTimeout, budgetMs: number) =>
+			[
+				`已達到${limit(t)}，已工作 ${durationZh(t.workedMs)}。`,
+				`現在：${doing(t)}。`,
+				tools(t),
+				`這張卡片開著時它會繼續工作。按「繼續」再給它 ${durationZh(budgetMs)}；按「取消」停止。${durationZh(t.graceMs)}內沒有回答就會停止。`,
+			]
+				.filter(Boolean)
+				.join("\n"),
+		turnTimeoutContinue: "繼續",
+		turnTimeoutCancel: "取消",
+		turnTimeoutFooter: "這一輪仍在工作；準備好再回答即可。",
+		turnTimeoutContinued: "▶️ 已繼續。",
+		turnTimeoutCancelled: "❌ 已取消，這一輪會停止。",
+		turnTimeoutFinished: "✅ 這一輪已完成，不需要回答。",
+		turnTimeoutUnanswered: (t: TurnTimeout) =>
+			`⏱️ ${durationZh(t.graceMs)}內沒有回答，這一輪已停止。`,
+		turnTimedOutNotice: (t: TurnTimeout) => {
+			const what =
+				t.running.length > 0
+					? `當時 ${t.running.map(({ tool, ms }) => `${tool} 正在執行（${durationZh(ms)}）`).join("、")}`
+					: `當時${doing(t)}`;
+			const head =
+				t.end === "cancelled"
+					? `⏱️ 擁有者在工作 ${durationZh(t.workedMs)} 後取消了這一輪，${what}。`
+					: t.end === "unanswered"
+						? `⏱️ 逾時卡片在 ${durationZh(t.graceMs)}內沒有回答，這一輪在工作 ${durationZh(t.workedMs)} 後停止，${what}。`
+						: `⏱️ 這一輪達到${limit(t)}，在工作 ${durationZh(t.workedMs)} 後停止，${what}。`;
+			return [head, tools(t)].filter(Boolean).join(" ");
+		},
+	};
+}

package/src/core/i18n/zh-tw.ts

@@ -8,6 +8,7 @@ import type { Messages } from "./en.ts";
 import { ownerZhTW } from "./owner.ts";
 import { schedulesZhTW } from "./schedules.ts";
 import { timeZonesZhTW } from "./time-zones.ts";
+import { turnTimeoutZhTW } from "./turn-timeout.ts";
 import type { CatalogContext } from "./types.ts";
 
 /** The Traditional Chinese catalog. */
@@ -22,5 +23,6 @@ export function createZhTW(ctx: CatalogContext): Messages {
 		...dashboardZhTW(ctx),
 		...channelsZhTW(ctx),
 		...discordZhTW(ctx),
+		...turnTimeoutZhTW(),
 	};
 }

package/src/core/interactions/prompts.ts

@@ -128,6 +128,23 @@ export interface ApprovalOptions {
 	 * withdrawn call whatever the card answers.
 	 */
 	supersede?: AbortSignal;
+	/**
+	 * The card's own words, for a card that asks something other than whether to run an action,
+	 * such as a turn's timeout card; a surface that cannot show them keeps its own.
+	 */
+	wording?: ApprovalWording;
+}
+
+/** A card's words in place of an approval's; see `ApprovalOptions.wording`. */
+export interface ApprovalWording {
+	/** The labels of the controls that answer approved and declined. */
+	approve: string;
+	decline: string;
+	/** The footer while the card is open. */
+	footer: string;
+	/** The footer once it was answered approved, or declined. */
+	approved: string;
+	declined: string;
 }
 
 /** The longest footer a withdrawn card shows, in characters. */

package/src/core/modules/delegation/web-research-worker.ts

@@ -1,20 +1,12 @@
-import { mkdirSync } from "node:fs";
-import {
-	createAgentSession,
-	DefaultResourceLoader,
-	type ModelRuntime,
-	SessionManager,
-	SettingsManager,
-} from "@earendil-works/pi-coding-agent";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { PluginError } from "../../errors.ts";
 import {
 	formatModelRef,
 	type ModelRef,
 	type ThinkingLevel,
 } from "../../models.ts";
-import { runWorkerTask } from "../../runtime/worker-task.ts";
-import { activeToolsExtension } from "../../shared/active-tools.ts";
 import { packageDir } from "../../shared/package-dir.ts";
+import { runWorkerSession } from "./worker-session.ts";
 
 const WEB_TOOLS = ["web_search", "fetch_content", "get_search_content"];
 
@@ -50,39 +42,19 @@ export class WebResearchWorker {
 	constructor(options: WebResearchWorkerOptions) {
 		this.#options = options;
 		this.#webAccessPath = webAccessDir();
-		mkdirSync(options.workDir, { recursive: true });
 	}
 
-	async run(task: string, signal: AbortSignal): Promise<string> {
+	run(task: string, signal: AbortSignal): Promise<string> {
 		const { modelRuntime, agentDir, workDir, model, thinking } = this.#options;
-		const resourceLoader = new DefaultResourceLoader({
-			cwd: workDir,
-			agentDir,
-			noExtensions: true,
-			noSkills: true,
-			noPromptTemplates: true,
-			noThemes: true,
-			noContextFiles: true,
-			additionalExtensionPaths: [this.#webAccessPath],
-			extensionFactories: [
-				{ name: "web-only", factory: activeToolsExtension(() => WEB_TOOLS) },
-			],
-			appendSystemPrompt: [WORKER_PROMPT],
-		});
-		await resourceLoader.reload();
-		const { session } = await createAgentSession({
-			cwd: workDir,
-			agentDir,
-			thinkingLevel: thinking,
-			modelRuntime,
-			resourceLoader,
-			sessionManager: SessionManager.inMemory(workDir),
-			settingsManager: SettingsManager.inMemory({}),
-			noTools: "builtin",
-		});
-		return runWorkerTask(session, {
+		return runWorkerSession({
 			modelRuntime,
+			agentDir,
+			workDir,
 			model: formatModelRef(model),
+			thinking,
+			prompt: WORKER_PROMPT,
+			extensionPaths: [this.#webAccessPath],
+			toolNames: WEB_TOOLS,
 			task,
 			signal,
 			aborted: "the worker ran out of time",

package/src/core/modules/delegation/worker-session.ts

@@ -0,0 +1,111 @@
+import { mkdirSync } from "node:fs";
+import {
+	createAgentSession,
+	DefaultResourceLoader,
+	type ExtensionFactory,
+	type ModelRuntime,
+	SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { ThinkingLevel } from "../../models.ts";
+import { runWorkerTask } from "../../runtime/worker-task.ts";
+import type { WorkerSessionRequest, WorkerSessions } from "../../services.ts";
+import { activeToolsExtension } from "../../shared/active-tools.ts";
+
+export interface WorkerSessionOptions {
+	/** Shared with the rest of the host, so the Codex login refreshes in one place. */
+	modelRuntime: ModelRuntime;
+	agentDir: string;
+	workDir: string;
+	/** `<provider>/<id>`. */
+	model: string;
+	thinking: ThinkingLevel;
+	prompt: string;
+	/** Installed Pi extension packages that register tools. */
+	extensionPaths?: readonly string[];
+	/** Extensions that register tools. */
+	extensions?: readonly { name: string; factory: ExtensionFactory }[];
+	/** The only tools active in the session; no built-in tool is. */
+	toolNames: readonly string[];
+	task: string;
+	signal: AbortSignal;
+	aborted: string;
+}
+
+/**
+ * Runs one task in a fresh, unsaved session with no built-in tool, no skills, no context files and
+ * only the named tools active, and returns the worker's report.
+ */
+export async function runWorkerSession(
+	options: WorkerSessionOptions,
+): Promise<string> {
+	const { modelRuntime, agentDir, workDir, model, thinking } = options;
+	mkdirSync(workDir, { recursive: true });
+	const resourceLoader = new DefaultResourceLoader({
+		cwd: workDir,
+		agentDir,
+		noExtensions: true,
+		noSkills: true,
+		noPromptTemplates: true,
+		noThemes: true,
+		noContextFiles: true,
+		additionalExtensionPaths: [...(options.extensionPaths ?? [])],
+		extensionFactories: [
+			...(options.extensions ?? []),
+			// Last, so it undoes any tool another extension re-activates.
+			{
+				name: "worker-tools-only",
+				factory: activeToolsExtension(() => options.toolNames),
+			},
+		],
+		appendSystemPrompt: [options.prompt],
+	});
+	await resourceLoader.reload();
+	options.signal.throwIfAborted();
+	const { session } = await createAgentSession({
+		cwd: workDir,
+		agentDir,
+		thinkingLevel: thinking,
+		modelRuntime,
+		resourceLoader,
+		sessionManager: SessionManager.inMemory(workDir),
+		settingsManager: SettingsManager.inMemory({}),
+		noTools: "builtin",
+	});
+	return runWorkerTask(session, {
+		modelRuntime,
+		model,
+		task: options.task,
+		signal: options.signal,
+		aborted: options.aborted,
+	});
+}
+
+/** The `WORKER_SESSIONS` service: worker sessions on the host's model runtime and delegation settings. */
+export function workerSessions(options: {
+	modelRuntime: ModelRuntime;
+	agentDir: string;
+	workDir: string;
+	delegation: { model: string; thinking: ThinkingLevel };
+}): WorkerSessions {
+	return {
+		delegation: options.delegation,
+		run: (request: WorkerSessionRequest) =>
+			runWorkerSession({
+				modelRuntime: options.modelRuntime,
+				agentDir: options.agentDir,
+				workDir: options.workDir,
+				model: request.model ?? options.delegation.model,
+				thinking: request.thinking ?? options.delegation.thinking,
+				prompt: request.prompt,
+				extensions: request.extensions.map((factory, index) => ({
+					name: `worker-tools-${index}`,
+					factory,
+				})),
+				toolNames: request.toolNames,
+				task: request.task,
+				signal: request.signal,
+				aborted: request.aborted ?? "the worker ran out of time",
+			}),
+	};
+}

package/src/core/modules/skills/package-skills-fixture.ts

@@ -0,0 +1,33 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { packageDir } from "../../shared/package-dir.ts";
+
+/**
+ * Installs a fake npm package under `<root>/node_modules` with the layout of `pi-workflow-skills`:
+ * `"pi": { "skills": ["./skills"] }` and one folder with a SKILL.md per skill.
+ */
+export function installPackage(
+	root: string,
+	name: string,
+	skills: Record<string, string>,
+	manifest: Record<string, unknown> = { pi: { skills: ["./skills"] } },
+): void {
+	const dir = join(root, "node_modules", name);
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(
+		join(dir, "package.json"),
+		JSON.stringify({ name, version: "1.0.0", ...manifest }),
+	);
+	for (const [skill, description] of Object.entries(skills)) {
+		mkdirSync(join(dir, "skills", skill, "playbooks"), { recursive: true });
+		writeFileSync(
+			join(dir, "skills", skill, "SKILL.md"),
+			`---\nname: ${skill}\ndescription: ${description}\n---\n\n# ${skill}\n`,
+		);
+	}
+}
+
+/** Looks packages up from `<root>`, the way a host finds its own dependencies. */
+export const packageDirIn = (root: string) => (name: string) =>
+	packageDir(name, pathToFileURL(join(root, "host.js")));

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

@@ -0,0 +1,121 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative as relativePath, resolve } from "node:path";
+import { PluginError } from "../../errors.ts";
+import { packageDir } from "../../shared/package-dir.ts";
+import {
+	BUILTIN_SKILLS,
+	checkSkillName,
+	type PackageSkill,
+	readSkillFile,
+} from "./skill-rules.ts";
+
+/** The SKILL.md files under `path`: the file itself, or each skill folder found below a directory. */
+function skillFilesAt(path: string): string[] {
+	if (statSync(path).isFile()) return [path];
+	if (existsSync(join(path, "SKILL.md"))) return [join(path, "SKILL.md")];
+	return readdirSync(path, { withFileTypes: true })
+		.filter(
+			(entry) =>
+				entry.isDirectory() &&
+				!entry.name.startsWith(".") &&
+				entry.name !== "node_modules",
+		)
+		.flatMap((entry) => skillFilesAt(join(path, entry.name)));
+}
+
+/** The `pi.skills` entries of a package manifest, or undefined when it declares none. */
+function manifestSkills(manifest: unknown): string[] | undefined {
+	const skills = (manifest as { pi?: { skills?: unknown } } | null)?.pi?.skills;
+	return Array.isArray(skills) &&
+		skills.length > 0 &&
+		skills.every((entry) => typeof entry === "string")
+		? skills
+		: undefined;
+}
+
+function packageSkillsOf(
+	name: string,
+	resolveDir: (name: string) => string,
+): PackageSkill[] {
+	let dir: string;
+	try {
+		dir = resolveDir(name);
+	} catch {
+		throw new PluginError(
+			`config skills.packages: the package "${name}" is not installed. Install it next to the host, or remove it from skills.packages.`,
+		);
+	}
+	let manifest: unknown;
+	try {
+		manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+	} catch (error) {
+		throw new PluginError(
+			`config skills.packages: the package "${name}" has no readable package.json (${(error as Error).message}). Reinstall it, or remove it from skills.packages.`,
+		);
+	}
+	const entries = manifestSkills(manifest);
+	if (!entries)
+		throw new PluginError(
+			`config skills.packages: the package "${name}" lists no skills in its package.json "pi.skills". Remove it from skills.packages, or use a package that ships skills.`,
+		);
+	const files = entries.flatMap((entry) => {
+		const path = resolve(dir, entry);
+		const relative = relativePath(dir, path);
+		if (relative.startsWith("..") || isAbsolute(relative))
+			throw new PluginError(
+				`config skills.packages: "${name}" lists the skills path "${entry}" outside the package. Use a package whose pi.skills stay inside it.`,
+			);
+		if (!existsSync(path))
+			throw new PluginError(
+				`config skills.packages: "${name}" lists the skills path "${entry}", which is not in the installed package. Reinstall the package, or remove it from skills.packages.`,
+			);
+		return skillFilesAt(path);
+	});
+	if (files.length === 0)
+		throw new PluginError(
+			`config skills.packages: the package "${name}" has no SKILL.md under its pi.skills. Remove it from skills.packages, or use a package that ships skills.`,
+		);
+	return files.map((file) => {
+		const read = readSkillFile(file);
+		if ("error" in read)
+			throw new PluginError(
+				`config skills.packages: the skill file ${relativePath(dir, file)} of "${name}" cannot be read (${read.error}). Reinstall the package, or remove it from skills.packages.`,
+			);
+		try {
+			checkSkillName(read.name);
+		} catch (error) {
+			throw new PluginError(
+				`config skills.packages: "${name}" holds a skill that cannot be offered. ${(error as Error).message} Use another version of the package, or remove it from skills.packages.`,
+			);
+		}
+		return { name: read.name, package: name, file };
+	});
+}
+
+/**
+ * The skills of installed npm packages, read from each package's `pi.skills` folders (Pi's
+ * manifest). Throws a PluginError naming the fix when a package is not installed or has no
+ * skills, or when two packages (or one package twice) offer the same name or a built-in name.
+ * A clash with a linked or written skill is found by the registry, which holds those.
+ */
+export function discoverPackageSkills(
+	packages: readonly string[],
+	resolveDir: (name: string) => string = packageDir,
+): PackageSkill[] {
+	const found = new Map<string, PackageSkill>();
+	for (const name of new Set(packages))
+		for (const skill of packageSkillsOf(name, resolveDir)) {
+			const earlier = found.get(skill.name);
+			if (earlier)
+				throw new PluginError(
+					`config skills.packages: the skill "${skill.name}" comes from both "${earlier.package}" and "${skill.package}". Drop one of the packages from skills.packages.`,
+				);
+			if ((BUILTIN_SKILLS as readonly string[]).includes(skill.name))
+				throw new PluginError(
+					`config skills.packages: the skill "${skill.name}" of "${skill.package}" has the name of a built-in skill. Drop the package from skills.packages.`,
+				);
+			found.set(skill.name, skill);
+		}
+	// pi-lens-ignore: no-sort-without-comparator — skill names sort by code unit, the same order on every machine
+	return [...found.values()].sort((a, b) => (a.name < b.name ? -1 : 1));
+}

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

@@ -3,6 +3,7 @@ import {
 	BUILTIN_SKILLS,
 	cut,
 	MAX_LIST_DESCRIPTION_CHARS,
+	type PackageSkill,
 	type ResolvedSkill,
 	type SkillCatalogEntry,
 	type SkillSource,
@@ -17,6 +18,7 @@ export type SkillResolver = (
 /** Every skill, built-in ones first, with what `list` shows as text (web app spec behavior 15). */
 export function skillCatalog(
 	store: SkillStore,
+	packageSkills: readonly PackageSkill[],
 	resolveOne: SkillResolver,
 ): SkillCatalogEntry[] {
 	const sources: { name: string; source: SkillSource }[] = [
@@ -24,6 +26,10 @@ export function skillCatalog(
 			name,
 			source: { kind: "builtin" } as const,
 		})),
+		...packageSkills.map((skill) => ({
+			name: skill.name,
+			source: { kind: "package", package: skill.package } as const,
+		})),
 		...store.skills().map((entry) => ({
 			name: entry.name,
 			source:
@@ -51,6 +57,7 @@ export function skillCatalog(
 /** Every skill, or those of a group or matching a query (behavior 14). */
 export function skillListText(
 	store: SkillStore,
+	packageSkills: readonly PackageSkill[],
 	resolveOne: SkillResolver,
 	filter: { group?: string; query?: string } = {},
 ): string {
@@ -72,6 +79,10 @@ export function skillListText(
 	}));
 	const entries = [
 		...builtins,
+		...packageSkills.map((skill) => ({
+			name: skill.name,
+			source: `from the package ${skill.package}`,
+		})),
 		...store.skills().map((entry) => ({
 			name: entry.name,
 			source:

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

@@ -1,6 +1,7 @@
 import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { AgentError } from "../../domain/errors.ts";
+import { PluginError } from "../../errors.ts";
 import type { SkillRegistry } from "../../services.ts";
 import { planLinkedSkills } from "./skill-link.ts";
 import { skillCatalog, skillListText } from "./skill-listing.ts";
@@ -9,6 +10,7 @@ import {
 	checkBody,
 	checkDescription,
 	checkSkillName,
+	type PackageSkill,
 	type ResolvedSkill,
 	readSkillFile,
 	type SkillCatalogEntry,
@@ -22,6 +24,7 @@ export {
 	BUILTIN_SKILLS,
 	checkSkillName,
 	MAX_SKILL_BODY_CHARS,
+	type PackageSkill,
 	type ResolvedSkill,
 	type SkillCatalogEntry,
 	type SkillRegistryOptions,
@@ -32,9 +35,19 @@ export {
 /** The skill registry and what each agent carries. */
 export class StoredSkillRegistry implements SkillRegistry {
 	readonly #options: SkillRegistryOptions;
+	readonly #packageSkills = new Map<string, PackageSkill>();
 
+	/** Throws a PluginError when a package skill has the name of a linked or written one. */
 	constructor(options: SkillRegistryOptions) {
 		this.#options = options;
+		for (const skill of options.packageSkills ?? []) {
+			const stored = options.store.skill(skill.name);
+			if (stored)
+				throw new PluginError(
+					`The skill "${skill.name}" of the package "${skill.package}" clashes with a ${stored.kind} skill of the same name. Drop the package from skills.packages and start, remove the ${stored.kind} skill (${stored.kind === "linked" ? "skill_unlink" : "skill_delete"}), then list the package again.`,
+				);
+			this.#packageSkills.set(skill.name, skill);
+		}
 	}
 
 	/** Writes every agent-written skill for Pi and removes folders left by deleted ones. */
@@ -105,13 +118,18 @@ export class StoredSkillRegistry implements SkillRegistry {
 
 	/** Every skill, built-in ones first, with what `list` shows as text (web app spec behavior 15). */
 	catalog(): SkillCatalogEntry[] {
-		return skillCatalog(this.#options.store, (name) => this.#resolveOne(name));
+		return skillCatalog(
+			this.#options.store,
+			[...this.#packageSkills.values()],
+			(name) => this.#resolveOne(name),
+		);
 	}
 
 	/** Every skill, or those of a group or matching a query (behavior 14). */
 	list(filter: { group?: string; query?: string } = {}): string {
 		return skillListText(
 			this.#options.store,
+			[...this.#packageSkills.values()],
 			(name) => this.#resolveOne(name),
 			filter,
 		);
@@ -119,7 +137,7 @@ export class StoredSkillRegistry implements SkillRegistry {
 
 	/** Throws when a name is not registered; built-in names are carried already. */
 	checkRegistered(names: readonly string[]): void {
-		const unknown = names.filter((name) => !this.#options.store.skill(name));
+		const unknown = names.filter((name) => !this.#registered(name));
 		if (unknown.length > 0)
 			throw new AgentError(
 				`Unknown skills: ${unknown.join(", ")}. Find names with skill_list.${unknown.some((n) => (BUILTIN_SKILLS as readonly string[]).includes(n)) ? " Built-in skills are always carried." : ""}`,
@@ -142,6 +160,7 @@ export class StoredSkillRegistry implements SkillRegistry {
 	}
 
 	async unlink(name: string): Promise<string> {
+		this.#refusePackage(name);
 		const entry = this.#entry(name);
 		if (entry.kind !== "linked")
 			throw new AgentError(
@@ -206,7 +225,7 @@ export class StoredSkillRegistry implements SkillRegistry {
 			throw new AgentError("A skill group needs a description.");
 		const unknown = skills.filter(
 			(skill) =>
-				!this.#options.store.skill(skill) &&
+				!this.#registered(skill) &&
 				!(BUILTIN_SKILLS as readonly string[]).includes(skill),
 		);
 		if (unknown.length > 0)
@@ -270,6 +289,8 @@ export class StoredSkillRegistry implements SkillRegistry {
 		const { store, reposDir, writtenDir, builtinDir } = this.#options;
 		if ((BUILTIN_SKILLS as readonly string[]).includes(name))
 			return join(builtinDir, name, "SKILL.md");
+		const fromPackage = this.#packageSkills.get(name);
+		if (fromPackage) return fromPackage.file;
 		const entry = store.skill(name);
 		if (!entry) return undefined;
 		return entry.kind === "linked"
@@ -288,7 +309,24 @@ export class StoredSkillRegistry implements SkillRegistry {
 		return entry;
 	}
 
+	#registered(name: string): boolean {
+		return (
+			this.#packageSkills.has(name) ||
+			this.#options.store.skill(name) !== undefined
+		);
+	}
+
+	/** Package skills change with their package, never here. */
+	#refusePackage(name: string): void {
+		const fromPackage = this.#packageSkills.get(name);
+		if (fromPackage)
+			throw new AgentError(
+				`${name} comes from the package ${fromPackage.package} and is read-only here. It changes when the package is upgraded.`,
+			);
+	}
+
 	#writable(name: string): Extract<SkillEntry, { kind: "written" }> {
+		this.#refusePackage(name);
 		const entry = this.#entry(name);
 		if (entry.kind !== "written")
 			throw new AgentError(
@@ -298,8 +336,14 @@ export class StoredSkillRegistry implements SkillRegistry {
 	}
 
 	#checkFreeName(name: string): void {
+		const fromPackage = this.#packageSkills.get(name);
+		if (fromPackage)
+			throw new AgentError(
+				`A skill named "${name}" already exists: it comes from the package ${fromPackage.package}.`,
+			);
 		if (
 			(BUILTIN_SKILLS as readonly string[]).includes(name) ||
+			this.#packageSkills.has(name) ||
 			this.#options.store.skill(name)
 		)
 			throw new AgentError(`A skill named "${name}" already exists.`);