pi-soly 0.2.1 → 0.4.0

package/switch/index.ts

@@ -0,0 +1,345 @@
+// =============================================================================
+// index.ts — pi-switch extension entry
+// =============================================================================
+//
+// Wires the agent switcher into pi:
+//   - Header bar above chat (Claude Code-style, dim, persistent)
+//   - Ctrl+Shift+S to cycle (Shift+Tab is taken by pi's thinking-level cycler)
+//   - /agent slash command: show current + available, or set explicitly
+//   - Persists current agent to .soly/agent (shared with soly) or ~/.pi-switch/agent
+//   - Exposes `globalThis.__PI_SWITCH_AGENT__` for other extensions to read
+//   - Injects a system-prompt section so the LLM knows when to use which agent
+// =============================================================================
+
+import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+	DEFAULT_AGENT,
+	BUILTIN_AGENTS,
+	availableAgents,
+	nextAgent,
+	parseAgentName,
+	formatAgentBadge,
+	formatAgentSwitchNotify,
+	formatHeaderLine,
+	groupedAvailableAgents,
+	getAgentMeta,
+	loadAgent,
+	saveAgent,
+} from "./core.ts";
+import { buildPiSwitchSection, recommendAgent } from "./prompt.ts";
+
+const GLOBAL_KEY = "__PI_SWITCH_AGENT__";
+
+export default function piSwitchExtension(pi: ExtensionAPI) {
+	let cwd = "";
+	let currentAgent: string = DEFAULT_AGENT;
+	let cycle: string[] = [DEFAULT_AGENT];
+	let lastUi: ExtensionUIContext | null = null;
+
+	function refreshCycle(): void {
+		cycle = availableAgents();
+		if (!cycle.includes(currentAgent)) {
+			currentAgent = DEFAULT_AGENT;
+		}
+	}
+
+	function publish(): void {
+		(globalThis as Record<string, unknown>)[GLOBAL_KEY] = currentAgent;
+	}
+
+	function rerender(): void {
+		if (!lastUi) return;
+		try {
+			setHeaderBar(lastUi, () => formatHeaderLine(currentAgent));
+			const badge = formatAgentBadge(currentAgent);
+			lastUi.setStatus("pi-switch", badge ?? undefined);
+		} catch { /* no ui yet */ }
+	}
+
+	function setAgent(next: string): void {
+		const prev = currentAgent;
+		if (next === prev) return;
+		currentAgent = next;
+		publish();
+		if (cwd) saveAgent(cwd, next);
+		rerender();
+		if (lastUi) {
+			lastUi.notify(formatAgentSwitchNotify(prev, next), "info");
+		}
+	}
+
+	// ----- session_start: load persisted agent + set initial header -----
+	pi.on("session_start", async (_event, ctx) => {
+		cwd = ctx.cwd;
+		lastUi = ctx.ui;
+		publish();
+		const restored = loadAgent(cwd);
+		if (restored) currentAgent = restored;
+		refreshCycle();
+		publish();
+		rerender();
+	});
+
+	// ----- before_agent_start: inject system-prompt section -----
+	pi.on("before_agent_start", async (event, ctx) => {
+		lastUi = ctx.ui;
+		// Re-render the header on each turn (in case agent was changed via /agent)
+		rerender();
+		return {
+			systemPrompt: event.systemPrompt + buildPiSwitchSection(),
+		};
+	});
+
+	// ----- Ctrl+Shift+S: cycle to next agent -----
+	pi.registerShortcut("ctrl+shift+s", {
+		description: "Cycle pi-switch agent: worker → oracle → user-defined…",
+		handler: (sctx) => {
+			lastUi = sctx.ui;
+			refreshCycle();
+			const next = nextAgent(currentAgent, cycle);
+			setAgent(next);
+		},
+	});
+
+	// ----- /agent slash command (also handles subcommands: create, doctor) -----
+	pi.registerCommand("agent", {
+		description: "show or set the active subagent, or `create <name>` to scaffold, or `doctor` to diagnose",
+		handler: async (args, ctx) => {
+			lastUi = ctx.ui;
+			refreshCycle();
+			const parts = args.trim().split(/\s+/);
+			const subcommand = parts[0]?.toLowerCase();
+			const arg = parts[1];
+
+			// Subcommand: create
+			if (subcommand === "create") {
+				if (!arg) {
+					ctx.ui.notify("pi-switch: usage — `/agent create <name>`", "info");
+					return;
+				}
+				createAgent(arg, { ui: ctx.ui, cwd });
+				return;
+			}
+
+			// Subcommand: doctor
+			if (subcommand === "doctor") {
+				ctx.ui.notify(doctorReport(), "info");
+				return;
+			}
+
+			// Subcommand: recommend
+			if (subcommand === "recommend") {
+				const task = parts.slice(1).join(" ");
+				if (!task) {
+					ctx.ui.notify("pi-switch: usage — `/agent recommend <task description>`", "info");
+					return;
+				}
+				const rec = recommendAgent(task);
+				if (!rec) {
+					ctx.ui.notify(`pi-switch: no clear agent match for: "${task}"`, "info");
+					return;
+				}
+				ctx.ui.notify(
+					`pi-switch recommendation: ${rec.emoji} ${rec.agent}\n  why: ${rec.why}\n  → /agent ${rec.agent} to switch`,
+					"info",
+				);
+				return;
+			}
+
+			// Direct agent name → set (handles `/agent <name>` as a single-arg shortcut).
+			// Check FIRST: if parts[0] is a valid agent name, treat as set even
+			// if it happens to be a "subcommand-looking" word. This way
+			// `/agent researcher` always sets to researcher, never falls
+			// through to the listing branch.
+			if (subcommand && cycle.includes(subcommand)) {
+				setAgent(subcommand);
+				return;
+			}
+			// Optional second arg: also set, for explicit `/agent <name>` syntax.
+			if (arg) {
+				const target = parseAgentName(arg);
+				if (!target) {
+					ctx.ui.notify(`pi-switch: invalid name "${arg}".`, "error");
+					return;
+				}
+				if (!cycle.includes(target)) {
+					ctx.ui.notify(
+						`pi-switch: unknown "${target}". available: ${cycle.join(", ")}`,
+						"error",
+					);
+					return;
+				}
+				setAgent(target);
+				return;
+			}
+
+			// No arg: show current + grouped available
+			const curMeta = getAgentMeta(currentAgent);
+			const groups = groupedAvailableAgents();
+			const lines: string[] = [
+				`current: ${curMeta.emoji} ${currentAgent}  (${curMeta.description})`,
+				"",
+				"available:",
+				"",
+			];
+			for (const g of groups) {
+				lines.push(`─── ${g.header} ${"─".repeat(Math.max(0, 40 - g.header.length))}`);
+				for (const a of g.agents) {
+					const meta = getAgentMeta(a);
+					const marker = a === currentAgent ? "→" : " ";
+					lines.push(`  ${marker} ${meta.emoji} ${a.padEnd(16)}  ${meta.description}`);
+				}
+				lines.push("");
+			}
+			lines.push("cycle with Ctrl+Shift+S, or `/agent <name>`");
+			lines.push("subcommands: `/agent create <name>`, `/agent doctor`, `/agent recommend <task>`");
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Header bar (Claude Code-style, persistent above chat)
+// ---------------------------------------------------------------------------
+
+function setHeaderBar(ui: ExtensionUIContext, getLine: () => string): void {
+	// ui.setHeader takes a factory. The factory is called fresh on each
+	// render of the TUI. We return a Text whose content is read on each
+	// render, so updating `currentAgent` automatically reflects in the header.
+	ui.setHeader((_tui, _theme) => {
+		// The Text component reads getLine() at render time.
+		// We use a closure over a getter to read the current value.
+		const text = new Text(getLine(), 1, 0);
+		// Text satisfies Component & { dispose?() } — cast to satisfy TS.
+		return text as unknown as Parameters<typeof ui.setHeader>[0] extends ((t: infer T, th: infer Th) => infer R) ? R : never;
+	});
+}
+
+// ---------------------------------------------------------------------------
+// /agent create — scaffold a new agent .md file
+// ---------------------------------------------------------------------------
+
+/** Template for a new user agent. User edits the system prompt to specialize. */
+function agentTemplate(name: string, description: string): string {
+	return `---
+name: ${name}
+description: ${description}
+thinking: medium
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write
+defaultContext: fork
+---
+
+You are \`${name}\`. Describe what you specialize in, your process, and
+what you should NOT do. Keep the rest of this frontmatter as-is unless
+you have a specific reason to change it.
+
+# Your role
+
+<!-- Replace with a one-paragraph description of what you're for. -->
+
+# Process
+
+1. Read the user's request carefully.
+2. Form a hypothesis about the right approach.
+3. Verify with tools (read, grep, bash) before writing.
+4. Commit changes in narrow, reviewable diffs.
+
+# What you should NOT do
+
+- Edit other agents' files
+- Run subagents yourself (you're already a subagent)
+- Skip verification ("trust me bro" is not a process)
+`;
+}
+
+function createAgent(
+	name: string,
+	ctx: {
+		ui: {
+			notify: (t: string, k?: "info" | "warning" | "error") => void;
+			input: (t: string, p?: string) => Promise<string | undefined>;
+		};
+		cwd: string;
+	},
+): void {
+	if (!parseAgentName(name)) {
+		ctx.ui.notify(`pi-switch: invalid name "${name}". Use letters/digits/dashes/underscores, ≤64 chars.`, "error");
+		return;
+	}
+	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
+	fs.mkdirSync(userDir, { recursive: true });
+	const file = path.join(userDir, `${name}.md`);
+	if (fs.existsSync(file)) {
+		ctx.ui.notify(`pi-switch: ${file} already exists. edit it directly.`, "warning");
+		return;
+	}
+	// Ask for description
+	void ctx.ui.input(`description for "${name}":`, "one-liner that shows in the picker")?.then((desc) => {
+		const description = desc?.trim() || `custom agent (${name})`;
+		fs.writeFileSync(file, agentTemplate(name, description), "utf-8");
+		ctx.ui.notify(
+			`pi-switch: created ${file}\n  → next Ctrl+Shift+S to see it in the cycle\n  → edit the system prompt to specialize`,
+			"info",
+		);
+	});
+}
+
+function doctorReport(): string {
+	const cycle = availableAgents();
+	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
+	const lines: string[] = ["pi-switch doctor:", ""];
+
+	// Cycle stats
+	const builtins = cycle.filter((a) => BUILTIN_AGENTS.includes(a));
+	const users = cycle.filter((a) => !BUILTIN_AGENTS.includes(a));
+	lines.push(`cycle: ${cycle.length} agents (${builtins.length} built-in, ${users.length} user)`);
+	lines.push("");
+
+	// User dir check
+	if (!fs.existsSync(userDir)) {
+		lines.push(`user dir: ${userDir} (does not exist — user agents won't be discovered)`);
+	} else {
+		const files = fs.readdirSync(userDir).filter((f) => f.endsWith(".md"));
+		lines.push(`user dir: ${userDir} (${files.length} file(s))`);
+
+		// Validate each user agent
+		const issues: string[] = [];
+		for (const f of files) {
+			try {
+				const raw = fs.readFileSync(path.join(userDir, f), "utf-8");
+				if (!raw.startsWith("---\n")) {
+					issues.push(`${f}: no YAML frontmatter`);
+					continue;
+				}
+				const m = raw.match(/^---\n([\s\S]*?)\n---/);
+				if (!m) { issues.push(`${f}: malformed frontmatter`); continue; }
+				const fm = m[1] ?? "";
+				if (!/^name:\s*\S/m.test(fm)) issues.push(`${f}: missing 'name:' in frontmatter`);
+				else if (!/^description:\s*\S/m.test(fm)) issues.push(`${f}: missing 'description:' in frontmatter`);
+			} catch (e) {
+				issues.push(`${f}: read error: ${(e as Error).message}`);
+			}
+		}
+		if (issues.length === 0) {
+			lines.push("validation: all user agents OK ✓");
+		} else {
+			lines.push("validation issues:");
+			for (const i of issues) lines.push(`  - ${i}`);
+		}
+	}
+
+	// Persistence check
+	const persisted = process.env.PI_SWITCH_HOME || os.homedir();
+	const fallbackFile = path.join(persisted, ".pi-switch", "agent");
+	lines.push("");
+	lines.push(`persistence: ${fs.existsSync(fallbackFile) ? fallbackFile : "no standalone persistence (uses .soly/agent if soly project)"}`);
+
+	return lines.join("\n");
+}

package/switch/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "pi-agented",
+  "version": "0.2.0",
+  "description": "Generic subagent switcher for pi. Header bar above chat, Ctrl+Shift+S to cycle, /agent slash command. Works with any agent in ~/.pi/agent/agents/.",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bun x tsc --noEmit"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.78.1",
+    "@earendil-works/pi-tui": "0.78.1",
+    "@types/node": "^25.9.1",
+    "bun-types": "^1.3.14",
+    "typebox": "1.1.38",
+    "typescript": "^6.0.3"
+  },
+  "files": [
+    "index.ts",
+    "core.ts",
+    "prompt.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "subagent",
+    "agent-switcher",
+    "task-routing"
+  ],
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "http://git.local.stbl/lowern1ght/pi-soly.framework.git",
+    "directory": "packages/pi-switch"
+  }
+}

package/switch/prompt.ts

@@ -0,0 +1,134 @@
+// =============================================================================
+// prompt.ts — System-prompt section for the pi-switch extension
+// =============================================================================
+
+/** Task-pattern → recommended agent. The LLM reads this and decides
+ *  whether to invoke /agent before launching subagent(...). Match is
+ *  by keyword (case-insensitive). First match wins; ties broken by order. */
+export const TASK_AGENT_HINTS: ReadonlyArray<{
+	pattern: RegExp;
+	agent: string;
+	emoji: string;
+	why: string;
+}> = [
+	// English keywords (use \b — ASCII word boundary works for English)
+	{ pattern: /\b(research|investigate|look\s*up|find\s*out|explore|survey|compare\s+libraries|what\s+is\s+the\s+best)\b/i,
+	  agent: "researcher", emoji: "\ud83d\udcda",
+	  why: "external docs, ecosystem behavior, primary sources" },
+	{ pattern: /\b(scout|scan|map|find\s+all|where\s+is|locate|explore\s+codebase|skim)\b/i,
+	  agent: "scout", emoji: "\ud83d\udd0d",
+	  why: "codebase recon, patterns, file locations" },
+	{ pattern: /\b(plan|design|architect|outline|structure|break\s*down|steps|order)\b/i,
+	  agent: "planner", emoji: "\ud83d\udccb",
+	  why: "decompose into ordered steps, identify risks" },
+	{ pattern: /\b(review|audit|check|adversarial|critique|find\s+bugs|qa)\b/i,
+	  agent: "reviewer", emoji: "\ud83d\udc40",
+	  why: "adversarial review of correctness, security, style" },
+	{ pattern: /\b(oracle|decision|tradeoff|compare|which\s+approach|is\s+this\s+wise|drift)\b/i,
+	  agent: "oracle", emoji: "\ud83d\udd2e",
+	  why: "decision consistency, hidden assumptions, drift detection" },
+	{ pattern: /\b(debug|bug|fix|crash|error|stack\s*trace|repro|why\s+is\s+this\s+broken)\b/i,
+	  agent: "soly-debugger", emoji: "\ud83d\udc1e",
+	  why: "isolated bug investigation with minimal repro" },
+	{ pattern: /\b(test|tests|coverage|spec|assert)\b/i,
+	  agent: "soly-tester", emoji: "\ud83e\uddea",
+	  why: "test-only work, never modifies prod code" },
+	{ pattern: /\b(refactor|clean\s*up|simplify|extract|rename|restructure|no\s+behavior\s+change)\b/i,
+	  agent: "soly-refactor", emoji: "\ud83d\udd04",
+	  why: "pure refactoring, behavior-preserving" },
+	{ pattern: /\b(document|docs|readme|jsdoc|comment|annotate)\b/i,
+	  agent: "soly-documenter", emoji: "\ud83d\udcdd",
+	  why: "doc updates, READMEs, inline annotations" },
+	{ pattern: /\b(implement|build|write\s+code|add\s+feature|create\s+the)\b/i,
+	  agent: "worker", emoji: "\u26a1",
+	  why: "generic implementation with all tools" },
+	{ pattern: /\b(orchestrate|coordinate|dispatch|chain|run\s+in\s+parallel|first\s+.+\s+then)\b/i,
+	  agent: "delegate", emoji: "\ud83e\udd1d",
+	  why: "multi-agent orchestration" },
+	// Russian keywords (loose match — Russian words inflect heavily; we match
+	// word stems, accepting some false positives as the cost of broader coverage)
+	{ pattern: /(изуч|исслед|разузн|найди\s+инфу|research|investigate|find\s+out)/i,
+	  agent: "researcher", emoji: "\ud83d\udcda",
+	  why: "external docs, ecosystem behavior, primary sources" },
+	{ pattern: /(где\s+это|где\s+находит|find\s+all|locate)/i,
+	  agent: "scout", emoji: "\ud83d\udd0d",
+	  why: "codebase recon, patterns, file locations" },
+	{ pattern: /(спланир|plan|design|architect)/i,
+	  agent: "planner", emoji: "\ud83d\udccb",
+	  why: "decompose into ordered steps, identify risks" },
+	{ pattern: /(проверь|ревью|аудит|review|audit)/i,
+	  agent: "reviewer", emoji: "\ud83d\udc40",
+	  why: "adversarial review of correctness, security, style" },
+	{ pattern: /(решени|выбор|decision|tradeoff|drift)/i,
+	  agent: "oracle", emoji: "\ud83d\udd2e",
+	  why: "decision consistency, hidden assumptions, drift detection" },
+	{ pattern: /(баг|ошибк|почему\s+(?:падает|ломает)|debug|bug|crash|stack\s*trace|repro)/i,
+	  agent: "soly-debugger", emoji: "\ud83d\udc1e",
+	  why: "isolated bug investigation with minimal repro" },
+	{ pattern: /(тест|покрыт|test|coverage|spec|assert)/i,
+	  agent: "soly-tester", emoji: "\ud83e\uddea",
+	  why: "test-only work, never modifies prod code" },
+	{ pattern: /(рефактор|упрост|refactor|simplify|extract|restructure)/i,
+	  agent: "soly-refactor", emoji: "\ud83d\udd04",
+	  why: "pure refactoring, behavior-preserving" },
+	{ pattern: /(документ|описани|document|readme|jsdoc)/i,
+	  agent: "soly-documenter", emoji: "\ud83d\udcdd",
+	  why: "doc updates, READMEs, inline annotations" },
+	{ pattern: /(реализуй|сделай|напиши|создай|implement|build|add\s+feature|create\s+the)/i,
+	  agent: "worker", emoji: "\u26a1",
+	  why: "generic implementation with all tools" },
+	{ pattern: /(оркестрируй|координируй|orchestrate|coordinate|dispatch|chain)/i,
+	  agent: "delegate", emoji: "\ud83e\udd1d",
+	  why: "multi-agent orchestration" },
+];
+
+/** Heuristic: which agent does the task look like? Returns null if no
+ *  pattern matches (caller should leave the current agent as-is). */
+export function recommendAgent(taskText: string): { agent: string; emoji: string; why: string } | null {
+	for (const hint of TASK_AGENT_HINTS) {
+		if (hint.pattern.test(taskText)) {
+			return { agent: hint.agent, emoji: hint.emoji, why: hint.why };
+		}
+	}
+	return null;
+}
+
+export function buildPiSwitchSection(): string {
+	return `
+
+## pi-switch — when to use \`/agent\`
+
+The \`/agent\` slash command + \`Ctrl+Shift+S\` shortcut cycle through available subagents. Use the right agent for the job:
+
+- **Read-only / no edits** (oracle, scout, researcher, planner, reviewer): for analysis, planning, review. They won't modify files.
+- **Write tools** (worker, context-builder, delegate): for implementation.
+- **User-defined** in \`~/.pi/agent/agents/\`: any agent the user has added — drop a markdown file with YAML frontmatter (name, description) and it joins the cycle automatically.
+
+The current agent is shown in a header bar above the chat (with emoji + description) and in the footer status line as \`[emoji name]\`. When the agent changes, a multi-line notification appears with the old → new diff and capability summary.
+
+When you need a specialist for a sub-task, use the right agent via the parent LLM's \`subagent(...)\` call — the system will use the currently active agent. You can also use \`/agent <name>\` to switch explicitly, but in most cases the orchestrator picks the right agent for each step.
+
+**Task → agent heuristics.** Before launching a generic \`subagent(...)\`, scan the request for these keywords and call \`/agent <name>\` first if it matches:
+
+| Keywords in request | Suggested agent | Why |
+|---|---|---|
+| research, investigate, look up, find out, explore, compare libraries, what is the best | 📚 researcher | external docs, ecosystem behavior |
+| scout, scan, map, find all, where is, locate, explore codebase, skim | 🔍 scout | codebase recon, patterns, file locations |
+| plan, design, architect, outline, structure, break down, steps, order | 📋 planner | decompose into ordered steps, identify risks |
+| review, audit, check, adversarial, critique, find bugs, qa | 👀 reviewer | adversarial correctness, security, style review |
+| oracle, decision, tradeoff, compare, which approach, is this wise, drift | 🔮 oracle | decision consistency, hidden assumptions |
+| debug, bug, fix, crash, error, stack trace, repro, why is this broken | 🐞 soly-debugger | isolated bug investigation with minimal repro |
+| test, tests, coverage, spec, assert | 🧪 soly-tester | test-only work, never modifies prod code |
+| refactor, clean up, simplify, extract, rename, restructure, no behavior change | 🔄 soly-refactor | pure refactoring, behavior-preserving |
+| document, docs, readme, jsdoc, comment, annotate | 📝 soly-documenter | doc updates, READMEs, inline annotations |
+| implement, build, write code, add feature, create the | ⚡ worker | generic implementation with all tools |
+| orchestrate, coordinate, dispatch, chain, run in parallel | 🤝 delegate | multi-agent orchestration |
+
+For multi-step tasks, the orchestrator (you) decides which agents run and in what order. You can chain agents via \`subagent({ chain: [...] })\` or run them in parallel via parallel tasks.
+
+DON'T:
+- Launch a worker for analysis (use oracle/scout)
+- Launch an oracle for implementation (it has no write tools)
+- Manually edit \`.soly/agent\` or \`~/.pi-switch/agent\` — use the slash command
+`;
+}