pi-agents-switch 0.2.0

package/README.md

@@ -0,0 +1,186 @@
+# pi-agents-switch
+
+OpenCode-style primary agent switching for [Pi](https://pi.dev).  
+
+Press **F9** to cycle agents — just like Tab in OpenCode.
+
+## Install
+
+```bash
+pi install ~/project/agents-switch
+```
+
+Then `/reload` in pi.
+
+## Usage
+
+| Action | How |
+|--------|-----|
+| **Cycle agents** | Press `F9` (configurable) |
+| **Pick agent** | `/switch` → select from list |
+| **Configure** | `/switch-config` → create/delete/set hotkey/init builder agent |
+
+## How it works
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ PI (default)  ←F9→  🔨 Builder  ←F9→  (your agents...) │
+│                      │                                   │
+│ Uses your standard    AGENTS.md in                       │
+│ ~/.pi/agent/          ~/.pi/agents/                      │
+│                       builder/ + your custom agents      │
+└──────────────────────────────────────────────────────────┘
+```
+
+## 🔨 Builder Agent
+
+The extension ships with a **Builder** agent. Initialize it with:
+
+```
+/switch-config → "🎨 Initialize default agent (builder)"
+```
+
+The Builder understands the AGENTS.md format inside and out. Switch to it and ask:
+
+> "Create a new agent for code review that only has read access"
+
+The Builder will design the agent, write the AGENTS.md, and set everything up.
+
+## Anatomy
+
+- **`PI`** — default. No changes to your existing config. Inherits `~/.pi/agent/AGENTS.md` and everything.
+- **Custom agents** — each is a single `AGENTS.md` with **YAML frontmatter** (metadata) + Markdown body (system prompt):
+  ```
+  ~/.pi/agents/<name>/
+  ├── AGENTS.md       ← YAML frontmatter + system prompt (all-in-one)
+  ├── extensions/     ← agent-specific extensions (optional)
+  ├── skills/         ← agent-specific skills (optional)
+  └── prompts/        ← agent-specific prompt templates (optional)
+  ```
+
+When you switch to an agent, its `AGENTS.md` body is injected into the system prompt. You can also configure model, thinking level, and tools per agent via the frontmatter.
+
+## Agent Config (AGENTS.md frontmatter)
+
+```yaml
+---
+name: 🎯 My Agent
+description: Analyze and plan without making changes
+provider: anthropic
+model: claude-sonnet-4-5
+thinkingLevel: medium
+temperature: 0.7
+topP: 0.9
+
+# Tools: inherit from PI, then remove excluded_tools, then add tools
+tools:
+  - read
+  - grep
+excluded_tools:
+  - edit
+  - write
+
+# Extensions / skills (same inheritance pattern)
+extensions:
+  - my-custom-ext
+noextensions:
+  - annoying-ext
+skills:
+  - my-skill
+noskills:
+  - noisy-skill
+---
+
+# 📋 Plan
+
+You are the **📋 Plan** agent.
+Your role and specific instructions go here.
+```
+
+### Inheritance Rules
+
+Each agent starts with PI's current config, then applies:
+
+1. **Remove** items listed in `excluded_tools` / `noextensions` / `noskills`
+2. **Add** items listed in `tools` / `extensions` / `skills`
+3. If an item appears in **both** `tools` and `excluded_tools`, `tools` wins (explicit include beats exclude)
+
+Agent-specific folders (`extensions/`, `skills/`, `prompts/`) are always included in addition to inherited items.
+
+### Fallback Chain
+
+When resolving an agent's config:
+
+1. **Agent-level**: `~/.pi/agents/<name>/AGENTS.md`
+2. **Project-level**: `<cwd>/.pi/agents/<name>/AGENTS.md` — overrides agent-level fields
+3. **PI defaults**: tools/extensions/skills from your running PI config
+
+## Creating agents
+
+```bash
+/switch-config → "➕ Create a new agent"
+```
+
+Or create files directly:
+
+```bash
+mkdir -p ~/.pi/agents/debug
+
+cat > ~/.pi/agents/debug/AGENTS.md << 'EOF'
+---
+name: 🐛 Debug
+description: Debugging specialist
+tools:
+  - read
+  - bash
+  - grep
+---
+
+# 🐛 Debug
+
+You are a debugging specialist. Focus on:
+- Root cause analysis
+- Reproducing bugs
+- Minimal fixes
+EOF
+```
+
+Agents are auto-discovered from the filesystem — no registration needed.
+
+## Config
+
+`~/.pi/agent/agents-switch.json` (minimal — only tracks hotkey + active agent):
+
+```json
+{
+  "version": 1,
+  "hotkey": "f9",
+  "active": "PI"
+}
+```
+
+## Frontmatter Reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Display name (e.g. `"🔨 Builder"`) |
+| `description` | string | Short description shown in picker |
+| `provider` | string | Model provider (e.g. `"anthropic"`) |
+| `model` | string | Model ID (e.g. `"claude-sonnet-4-5"`) |
+| `thinkingLevel` | string | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `temperature` | number | Sampling temperature (0-2). Lower = more deterministic |
+| `topP` | number | Nucleus sampling threshold (0-1) |
+| `tools` | string[] | Tools to ADD after inheritance |
+| `excluded_tools` | string[] | Tools to REMOVE from PI's inherited set |
+| `extensions` | string[] | Extensions to ADD |
+| `noextensions` | string[] | Extensions to REMOVE |
+| `skills` | string[] | Skills to ADD |
+| `noskills` | string[] | Skills to REMOVE |
+
+The Markdown body (everything after the last `---`) is the **system prompt** injected before each agent turn.
+
+## Inspired by
+
+- [OpenCode agents](https://opencode.ai/docs/agents) — Tab cycling + primary agents
+- [pi-profiles](https://github.com/chaychoong/pi-profiles) — Profile isolation pattern
+- [pi-cycle](https://github.com/jerryfan/pi-cycle) — Hotkey + model switching pattern

package/frontmatter.ts

@@ -0,0 +1,172 @@
+/**
+ * Minimal YAML frontmatter parser.
+ *
+ * Parses the `---` delimited block at the start of a markdown file.
+ * Handles the subset of YAML we need: string values, arrays of strings,
+ * and the special `true`/`false` booleans.
+ *
+ * Also tracks the order of top-level keys for last-write-wins
+ * conflict resolution between include/exclude lists.
+ */
+
+import type { AgentFrontmatter, FrontmatterResult } from "./types";
+
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n?/;
+
+/**
+ * Parse a markdown string with optional YAML frontmatter.
+ * If no frontmatter block is found, returns an empty frontmatter
+ * and the entire content as the body.
+ */
+export function parseFrontmatter(content: string): FrontmatterResult {
+	const match = content.match(FRONTMATTER_RE);
+
+	if (!match) {
+		return {
+			frontmatter: {},
+			body: content.trimStart(),
+			keyOrder: [],
+		};
+	}
+
+	const yamlBlock = match[1];
+	const body = content.slice(match[0].length).trimStart();
+
+	// Parse the YAML subset
+	const fm: AgentFrontmatter = {};
+	const keyOrder: string[] = [];
+	const lines = yamlBlock.split("\n");
+
+	let currentKey: string | null = null;
+	let currentArray: string[] = [];
+
+	function flushArray(): void {
+		if (currentKey && currentArray.length > 0) {
+			(fm as any)[currentKey] = currentArray;
+		}
+		currentKey = null;
+		currentArray = [];
+	}
+
+	for (const rawLine of lines) {
+		const line = rawLine.trimEnd();
+
+		// Empty lines: flush current array
+		if (line.trim() === "") {
+			flushArray();
+			continue;
+		}
+
+		// Array item: `  - value` or `- value`
+		const arrayMatch = line.match(/^\s*-\s+(.+)$/);
+		if (arrayMatch) {
+			currentArray.push(arrayMatch[1].trim());
+			continue;
+		}
+
+		// Key-value: `key: value`
+		const kvMatch = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)$/);
+		if (kvMatch) {
+			flushArray();
+			currentKey = kvMatch[1];
+			keyOrder.push(currentKey); // Track key order for last-write-wins
+			const value = kvMatch[2].trim();
+
+			if (value === "") {
+				// Key with no value — might be the start of an array
+				currentArray = [];
+			} else {
+				// Scalar value
+				(fm as any)[currentKey] = parseScalar(value);
+				currentKey = null;
+			}
+			continue;
+		}
+
+		// Comment: `# ...` — ignore
+		if (line.trim().startsWith("#")) {
+		}
+	}
+
+	// Flush any remaining array
+	flushArray();
+
+	return { frontmatter: fm, body, keyOrder };
+}
+
+/**
+ * Parse a scalar YAML value.
+ * Handles: unquoted strings, quoted strings, booleans, numbers.
+ */
+function parseScalar(value: string): string | boolean | number {
+	// Quoted strings
+	if (
+		(value.startsWith('"') && value.endsWith('"')) ||
+		(value.startsWith("'") && value.endsWith("'"))
+	) {
+		return value.slice(1, -1);
+	}
+
+	// Booleans
+	const lower = value.toLowerCase();
+	if (lower === "true") return true;
+	if (lower === "false") return false;
+
+	// Numbers
+	if (/^-?\d+(\.\d+)?$/.test(value) && !value.startsWith("0")) {
+		return Number(value);
+	}
+
+	// Empty / null
+	if (lower === "null" || lower === "~" || value === "") {
+		return "";
+	}
+
+	return value;
+}
+
+/**
+ * Serialize frontmatter back to a YAML block (for creating agents).
+ * Uses the preferred key names: `excluded_tools`, `excluded_extensions`, `excluded_skills`.
+ */
+export function serializeFrontmatter(fm: AgentFrontmatter): string {
+	const lines: string[] = ["---"];
+
+	if (fm.name) lines.push(`name: ${quoteIfNeeded(fm.name)}`);
+	if (fm.description)
+		lines.push(`description: ${quoteIfNeeded(fm.description)}`);
+	if (fm.provider) lines.push(`provider: ${fm.provider}`);
+	if (fm.model) lines.push(`model: ${fm.model}`);
+	if (fm.thinkingLevel) lines.push(`thinkingLevel: ${fm.thinkingLevel}`);
+	if (fm.temperature !== undefined)
+		lines.push(`temperature: ${fm.temperature}`);
+	if (fm.topP !== undefined) lines.push(`topP: ${fm.topP}`);
+
+	function writeArray(key: string, items: string[] | undefined): void {
+		if (!items || items.length === 0) return;
+		lines.push(`${key}:`);
+		for (const item of items) {
+			lines.push(`  - ${item}`);
+		}
+	}
+
+	writeArray("tools", fm.tools);
+	writeArray("excluded_tools", fm.excluded_tools);
+	writeArray("extensions", fm.extensions);
+	writeArray("excluded_extensions", fm.excluded_extensions ?? fm.noextensions);
+	writeArray("skills", fm.skills);
+	writeArray("excluded_skills", fm.excluded_skills ?? fm.noskills);
+
+	lines.push("---");
+	lines.push(""); // blank line before body
+
+	return lines.join("\n");
+}
+
+function quoteIfNeeded(value: string): string {
+	// If the value contains `:` or `#` or starts with special chars, quote it
+	if (/[:#]/.test(value) || /^["'{[-]/.test(value)) {
+		return `"${value.replace(/"/g, '\\"')}"`;
+	}
+	return value;
+}