pi-agents-switch 0.2.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "pi-agents-switch",
+  "version": "0.2.0",
+  "description": "Tab to switch primary agents in Pi — like OpenCode's agent switching. Each agent gets an isolated profile with its own AGENTS.md, extensions, skills, and settings.",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "^6.0.3"
+  },
+  "files": [
+    "index.ts",
+    "types.ts",
+    "frontmatter.ts",
+    "profile-manager.ts",
+    "README.md"
+  ]
+}

package/profile-manager.ts

@@ -0,0 +1,590 @@
+/**
+ * Profile manager for pi-agents-switch.
+ *
+ * Each agent is defined by a single AGENTS.md file with YAML frontmatter.
+ * No more separate agents.json — metadata lives in the frontmatter,
+ * the system prompt lives in the markdown body.
+ *
+ * Profile dir layout:
+ *   ~/.pi/agents/<name>/          ← user-level agent
+ *   ├── AGENTS.md                 ← YAML frontmatter + system prompt
+ *   ├── extensions/               ← agent-specific extensions
+ *   ├── skills/                   ← agent-specific skills
+ *   └── prompts/                  ← agent-specific prompt templates
+ *
+ *   <cwd>/.pi/agents/<name>/      ← project-level agent (overrides user)
+ *   └── AGENTS.md
+ *
+ * Fallback chain for agent config:
+ *   1. Agent's own ~/.pi/agents/<name>/AGENTS.md
+ *   2. Project's <cwd>/.pi/agents/<name>/AGENTS.md
+ *   3. PI defaults (from running pi environment)
+ *
+ * Last-write-wins: when the same item appears in both tools and
+ * excluded_tools (or extensions/excluded_extensions, skills/excluded_skills),
+ * whichever YAML key was declared LAST in the file wins.
+ * `"*"` in any exclude list removes everything except items explicitly added.
+ */
+
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	writeFileSync,
+	readdirSync,
+	statSync,
+	rmSync,
+} from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { parseFrontmatter, serializeFrontmatter } from "./frontmatter";
+import type {
+	AgentDiskProfile,
+	AgentFrontmatter,
+	AgentsConfig,
+	FrontmatterResult,
+	ResolvedAgentConfig,
+} from "./types";
+
+const NAME_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+const MAX_NAME_LENGTH = 32;
+
+/**
+ * Information about the running PI agent, used for inheritance.
+ * Passed from the extension at resolution time.
+ */
+export interface PIState {
+	/** Active tool names in PI */
+	tools: string[];
+	/** Active extension names in PI */
+	extensions: string[];
+	/** Active skill names in PI */
+	skills: string[];
+}
+
+export class ProfileManager {
+	readonly userAgentsDir: string;
+	readonly configPath: string;
+	readonly piAgentDir: string;
+
+	constructor(private cwd?: string) {
+		const piRoot = join(homedir(), ".pi");
+		this.userAgentsDir = join(piRoot, "agents");
+		this.configPath = join(piRoot, "agent", "agents-switch.json");
+		this.piAgentDir = join(piRoot, "agent");
+	}
+
+	/** Get the project-level agents directory (if cwd is known) */
+	get projectAgentsDir(): string | undefined {
+		return this.cwd ? join(this.cwd, ".pi", "agents") : undefined;
+	}
+
+	agentPath(name: string): string {
+		return join(this.userAgentsDir, name);
+	}
+
+	// ─── Config read/write (simplified) ───────────────────
+
+	loadConfig(): AgentsConfig {
+		if (!existsSync(this.configPath)) {
+			return { version: 1 };
+		}
+
+		try {
+			const raw = readFileSync(this.configPath, "utf8");
+			const cfg = JSON.parse(raw) as AgentsConfig;
+			if (cfg.version !== 1) throw new Error("Unsupported config version");
+			return cfg;
+		} catch (err) {
+			const corruptPath = this.configPath + ".corrupted." + Date.now();
+			try {
+				const raw = readFileSync(this.configPath, "utf8");
+				writeFileSync(corruptPath, raw);
+				console.error(
+					`[agents-switch] Config file corrupted, backed up to ${corruptPath}. Starting with defaults.`,
+				);
+			} catch {
+				console.error(
+					`[agents-switch] Config file unreadable. Starting with defaults.`,
+				);
+			}
+			return { version: 1 };
+		}
+	}
+
+	private ensureConfigDir(): void {
+		const dir = join(homedir(), ".pi", "agent");
+		if (!existsSync(dir)) {
+			mkdirSync(dir, { recursive: true });
+		}
+	}
+
+	saveConfig(config: AgentsConfig): void {
+		this.ensureConfigDir();
+		writeFileSync(this.configPath, JSON.stringify(config, null, 2) + "\n");
+	}
+
+	// ─── Agent discovery ─────────────────────────────────
+
+	/** List agent directories on disk (user + project). */
+	list(): AgentDiskProfile[] {
+		const results: AgentDiskProfile[] = [];
+
+		// User-level agents
+		if (existsSync(this.userAgentsDir)) {
+			for (const entry of readdirSync(this.userAgentsDir)) {
+				const path = join(this.userAgentsDir, entry);
+				try {
+					if (!statSync(path).isDirectory()) continue;
+				} catch {
+					continue;
+				}
+				results.push(this.buildDiskProfile(entry, path, "user"));
+			}
+		}
+
+		// Project-level agents
+		const projectDir = this.projectAgentsDir;
+		if (projectDir && existsSync(projectDir)) {
+			for (const entry of readdirSync(projectDir)) {
+				const path = join(projectDir, entry);
+				try {
+					if (!statSync(path).isDirectory()) continue;
+				} catch {
+					continue;
+				}
+				// Don't duplicate — project overrides user
+				const existing = results.find((r) => r.name === entry);
+				if (existing) {
+					existing.path = path;
+					existing.hasAgentsMd = existsSync(join(path, "AGENTS.md"));
+					existing.hasExtensions = existsSync(join(path, "extensions"));
+					existing.hasSkills = existsSync(join(path, "skills"));
+					existing.source = "project";
+				} else {
+					results.push(this.buildDiskProfile(entry, path, "project"));
+				}
+			}
+		}
+
+		return results.sort((a, b) => a.name.localeCompare(b.name));
+	}
+
+	private buildDiskProfile(
+		name: string,
+		path: string,
+		source: "user" | "project",
+	): AgentDiskProfile {
+		return {
+			name,
+			path,
+			hasAgentsMd: existsSync(join(path, "AGENTS.md")),
+			hasExtensions: existsSync(join(path, "extensions")),
+			hasSkills: existsSync(join(path, "skills")),
+			source,
+		};
+	}
+
+	/** Get agent names from config (legacy) and from disk. */
+	getAgentNames(): string[] {
+		const agents = this.list();
+		return agents.map((a) => a.name).sort();
+	}
+
+	/** Check if an agent exists on disk. */
+	exists(name: string): boolean {
+		if (existsSync(this.agentPath(name))) return true;
+		const projectDir = this.projectAgentsDir;
+		if (projectDir && existsSync(join(projectDir, name))) return true;
+		return false;
+	}
+
+	// ─── Agent resolution (fallback chain) ───────────────
+
+	/**
+	 * Resolve an agent's configuration through the fallback chain:
+	 *  1. Agent's own AGENTS.md
+	 *  2. Project AGENTS.md (if cwd is known)
+	 *  3. PI defaults
+	 *
+	 * Returns undefined if the agent doesn't exist anywhere.
+	 */
+	resolveAgent(
+		name: string,
+		piState?: PIState,
+		cwd?: string,
+	): ResolvedAgentConfig | undefined {
+		const effectiveCwd = cwd ?? this.cwd;
+
+		// Try agent-level first
+		const agentResult = this.readAgentFrontmatter(name);
+		// Try project-level
+		let projectResult: FrontmatterResult | undefined;
+		if (effectiveCwd) {
+			const projectPath = join(
+				effectiveCwd,
+				".pi",
+				"agents",
+				name,
+				"AGENTS.md",
+			);
+			if (existsSync(projectPath)) {
+				projectResult = this.readFrontmatterFrom(projectPath);
+			}
+		}
+
+		// If neither exists, agent doesn't exist
+		if (!agentResult && !projectResult) return undefined;
+
+		// Merge: project overrides agent
+		const fm: AgentFrontmatter = {
+			...(agentResult?.frontmatter ?? {}),
+			...(projectResult?.frontmatter ?? {}),
+		};
+
+		// Merge keyOrder: user first, project second (project wins in lastIndexOf)
+		const keyOrder = [
+			...(agentResult?.keyOrder ?? []),
+			...(projectResult?.keyOrder ?? []),
+		];
+
+		// Build resolved config
+		return this.buildResolvedConfig(
+			name,
+			fm,
+			keyOrder,
+			piState,
+			agentResult ? this.agentPath(name) : undefined,
+			projectResult ? join(effectiveCwd!, ".pi", "agents", name) : undefined,
+		);
+	}
+
+	/**
+	 * Read the frontmatter from an agent's AGENTS.md.
+	 */
+	private readAgentFrontmatter(name: string): FrontmatterResult | undefined {
+		const path = join(this.agentPath(name), "AGENTS.md");
+		return this.readFrontmatterFrom(path);
+	}
+
+	/**
+	 * Read frontmatter from a specific AGENTS.md file path.
+	 * Returns undefined if the file doesn't exist or can't be parsed.
+	 */
+	private readFrontmatterFrom(mdPath: string): FrontmatterResult | undefined {
+		if (!existsSync(mdPath)) return undefined;
+		try {
+			const content = readFileSync(mdPath, "utf8");
+			return parseFrontmatter(content);
+		} catch {
+			return undefined;
+		}
+	}
+
+	/**
+	 * Read the full AGENTS.md content (including system prompt body).
+	 * Follows the fallback chain: agent → project → undefined.
+	 */
+	readAgentsMd(name: string, cwd?: string): string | undefined {
+		const effectiveCwd = cwd ?? this.cwd;
+
+		// Try agent level
+		const agentPath = join(this.agentPath(name), "AGENTS.md");
+		if (existsSync(agentPath)) {
+			try {
+				return readFileSync(agentPath, "utf8");
+			} catch {
+				// fall through
+			}
+		}
+
+		// Try project level
+		if (effectiveCwd) {
+			const projectPath = join(
+				effectiveCwd,
+				".pi",
+				"agents",
+				name,
+				"AGENTS.md",
+			);
+			if (existsSync(projectPath)) {
+				try {
+					return readFileSync(projectPath, "utf8");
+				} catch {
+					// fall through
+				}
+			}
+		}
+
+		return undefined;
+	}
+
+	/**
+	 * Get only the system prompt body (no frontmatter) for an agent.
+	 */
+	getSystemPrompt(name: string, cwd?: string): string | undefined {
+		const md = this.readAgentsMd(name, cwd);
+		if (!md) return undefined;
+		return parseFrontmatter(md).body;
+	}
+
+	// ─── Resolution helpers ──────────────────────────────
+
+	/**
+	 * Build a ResolvedAgentConfig from parsed frontmatter + PI state.
+	 */
+	private buildResolvedConfig(
+		name: string,
+		fm: AgentFrontmatter,
+		keyOrder: string[],
+		piState?: PIState,
+		agentPath?: string,
+		projectPath?: string,
+	): ResolvedAgentConfig {
+		const pi = piState ?? { tools: [], extensions: [], skills: [] };
+
+		// Apply inheritance: start with PI's → respect last-write-wins
+		const tools = this.resolveList(
+			pi.tools,
+			fm.excluded_tools,
+			fm.tools,
+			"tools",
+			"excluded_tools",
+			keyOrder,
+		);
+
+		// Extensions: prefer excluded_extensions, fall back to deprecated noextensions
+		const extExclude = fm.excluded_extensions ?? fm.noextensions;
+		const extExcludeKey =
+			fm.excluded_extensions !== undefined
+				? "excluded_extensions"
+				: fm.noextensions !== undefined
+					? "noextensions"
+					: undefined;
+		const extensionPaths = extExcludeKey
+			? this.resolveList(
+					pi.extensions,
+					extExclude,
+					fm.extensions,
+					"extensions",
+					extExcludeKey,
+					keyOrder,
+				)
+			: [...pi.extensions, ...(fm.extensions ?? [])];
+
+		// Skills: prefer excluded_skills, fall back to deprecated noskills
+		const skillExclude = fm.excluded_skills ?? fm.noskills;
+		const skillExcludeKey =
+			fm.excluded_skills !== undefined
+				? "excluded_skills"
+				: fm.noskills !== undefined
+					? "noskills"
+					: undefined;
+		const skillPaths = skillExcludeKey
+			? this.resolveList(
+					pi.skills,
+					skillExclude,
+					fm.skills,
+					"skills",
+					skillExcludeKey,
+					keyOrder,
+				)
+			: [...pi.skills, ...(fm.skills ?? [])];
+
+		// Add agent-specific folders
+		const agentExtensions: string[] = [];
+		const agentSkills: string[] = [];
+
+		const effectiveAgentDir = projectPath ?? agentPath;
+		if (effectiveAgentDir) {
+			const extDir = join(effectiveAgentDir, "extensions");
+			if (existsSync(extDir)) {
+				agentExtensions.push(extDir);
+			}
+			const skillDir = join(effectiveAgentDir, "skills");
+			if (existsSync(skillDir)) {
+				agentSkills.push(skillDir);
+			}
+		}
+
+		const sourcePath = projectPath ?? agentPath ?? "PI (default)";
+
+		const modelStr =
+			fm.provider && fm.model ? `${fm.provider}/${fm.model}` : undefined;
+
+		return {
+			name,
+			label: fm.name ?? name,
+			description: fm.description ?? "",
+			model: modelStr,
+			thinkingLevel: fm.thinkingLevel,
+			temperature: fm.temperature,
+			topP: fm.topP,
+			systemPrompt: "", // filled in later by caller
+			tools,
+			extensionPaths: [...extensionPaths, ...agentExtensions],
+			skillPaths: [...skillPaths, ...agentSkills],
+			sourcePath,
+			exists: true,
+		};
+	}
+
+	/**
+	 * Resolve a list with inheritance, wildcard support, and last-write-wins.
+	 *
+	 * - `"*"` in the remove list removes ALL items from the base.
+	 * - When the same item is in both add and remove, whichever YAML key
+	 *   was declared LAST wins (determined by `keyOrder`).
+	 *
+	 * @param base       Items inherited from PI
+	 * @param remove     Items to remove (supports "*" wildcard)
+	 * @param add        Items to add
+	 * @param addKey     The YAML key name for the add list (e.g. "tools")
+	 * @param removeKey  The YAML key name for the remove list (e.g. "excluded_tools")
+	 * @param keyOrder   Ordered list of all YAML keys as they appear in the file
+	 */
+	private resolveList(
+		base: string[],
+		remove: string[] | undefined,
+		add: string[] | undefined,
+		addKey: string,
+		removeKey: string,
+		keyOrder: string[],
+	): string[] {
+		const removeSet = new Set(remove ?? []);
+		const addSet = new Set(add ?? []);
+		const wildcardRemove = removeSet.has("*");
+
+		// Last-write-wins: which key was declared later?
+		const addIdx = keyOrder.lastIndexOf(addKey);
+		const removeIdx = keyOrder.lastIndexOf(removeKey);
+		const addWins = addIdx >= 0 && (removeIdx < 0 || addIdx > removeIdx);
+
+		const result = base.filter((item) => {
+			const inRemove = removeSet.has(item);
+			const inAdd = addSet.has(item);
+
+			if (wildcardRemove) {
+				// "*" wildcard — removes everything unless explicitly added
+				if (inAdd) {
+					// Item is in both — last-write-wins decides
+					return addWins;
+				}
+				return false; // Not in add → wildcard removes it
+			}
+
+			if (inRemove) {
+				if (inAdd) {
+					// Item in both — last-write-wins decides
+					return addWins;
+				}
+				return false; // Only in remove
+			}
+
+			return true; // Not in remove → keep from PI base
+		});
+
+		// Add items from addSet that aren't already present
+		for (const item of addSet) {
+			if (!result.includes(item)) {
+				result.push(item);
+			}
+		}
+
+		return result;
+	}
+
+	// ─── Agent creation / deletion ───────────────────────
+
+	validateName(name: string): void {
+		if (!name || name.length > MAX_NAME_LENGTH || !NAME_REGEX.test(name)) {
+			throw new Error(
+				`Invalid agent name "${name}". Must match ${NAME_REGEX} and be ≤ ${MAX_NAME_LENGTH} chars.`,
+			);
+		}
+	}
+
+	/**
+	 * Create a new agent profile directory with an AGENTS.md scaffold.
+	 */
+	create(
+		name: string,
+		frontmatter: AgentFrontmatter,
+		systemPrompt?: string,
+	): void {
+		this.validateName(name);
+		const path = this.agentPath(name);
+		if (existsSync(path)) {
+			throw new Error(`Agent "${name}" already exists at ${path}`);
+		}
+
+		// Build directory structure
+		try {
+			mkdirSync(path, { recursive: true });
+			mkdirSync(join(path, "extensions"));
+			mkdirSync(join(path, "skills"));
+			mkdirSync(join(path, "prompts"));
+		} catch (err) {
+			try {
+				rmSync(path, { recursive: true, force: true });
+			} catch {
+				// Best effort cleanup
+			}
+			throw new Error(
+				`Failed to create agent directory for "${name}": ${(err as Error).message}`,
+			);
+		}
+
+		// Write AGENTS.md with frontmatter + body
+		const fmWithDefaults: AgentFrontmatter = {
+			name: frontmatter.name ?? name,
+			description: frontmatter.description ?? "Custom agent profile",
+			...frontmatter,
+		};
+
+		const defaultBody =
+			systemPrompt ??
+			`# ${fmWithDefaults.name}
+
+${fmWithDefaults.description}
+
+You are the **${fmWithDefaults.name}** agent. Your role and specific instructions go here.
+Edit this file to customize your behavior.
+
+`;
+
+		const content = serializeFrontmatter(fmWithDefaults) + "\n" + defaultBody;
+		writeFileSync(join(path, "AGENTS.md"), content);
+	}
+
+	/**
+	 * Delete an agent profile directory.
+	 */
+	delete(name: string): void {
+		const path = this.agentPath(name);
+		if (!existsSync(path)) {
+			throw new Error(`Agent "${name}" does not exist`);
+		}
+
+		rmSync(path, { recursive: true, force: true });
+
+		const config = this.loadConfig();
+		if (config.active === name) {
+			delete config.active;
+		}
+		this.saveConfig(config);
+	}
+
+	// ─── Active agent ────────────────────────────────────
+
+	/**
+	 * Get the currently active agent name.
+	 * Falls back to "PI" if nothing is set or the configured agent no longer exists.
+	 */
+	getActive(config: AgentsConfig): string {
+		if (config.active && this.exists(config.active)) {
+			return config.active;
+		}
+		return "PI";
+	}
+}