@phi-code-admin/phi-code 0.56.6 → 0.57.0

package/extensions/phi/README.md

@@ -1,228 +1,48 @@
 # Phi Code Extensions
 
-This directory contains the official Phi Code extensions - a collection of TypeScript extensions that enhance the Pi coding agent with specialized capabilities. Each extension follows the Pi extension pattern (`export default function(pi: ExtensionAPI)`) and provides focused functionality for different aspects of AI-assisted development.
+9 TypeScript extensions automatically loaded at startup.
 
-## Available Extensions
+## Extensions
 
-### 1. 🧠 Memory Extension (`memory.ts`)
+| Extension | File | Tools | Commands | Events |
+|-----------|------|-------|----------|--------|
+| **Memory** | `memory.ts` | `memory_search`, `memory_write`, `memory_read`, `memory_status` | — | `session_start` (auto-load AGENTS.md) |
+| **Benchmark** | `benchmark.ts` | — | `/benchmark` | `session_start` (results count) |
+| **Smart Router** | `smart-router.ts` | — | `/routing` | `input` (model suggestion), `session_start` |
+| **Orchestrator** | `orchestrator.ts` | `orchestrate` | `/plan`, `/plans` | — |
+| **Skill Loader** | `skill-loader.ts` | — | `/skills` | `input` (skill matching), `session_start` |
+| **Web Search** | `web-search.ts` | `web_search` | `/search` | `session_start` (key detection) |
+| **Agents** | `agents.ts` | — | `/agents` | `session_start` (agent count) |
+| **Init** | `init.ts` | — | `/phi-init` | — |
 
-Persistent memory management for conversations and context.
+## Benchmark Categories
 
-**Features:**
-- `memory_search(query)` - Full-text search across memory files
-- `memory_write(content, file?)` - Write to memory files (defaults to today's date)
-- `memory_read(file?)` - Read specific files or list all available
-- Auto-loads `AGENTS.md` on session start
-- Creates memory directories automatically (`~/.phi/memory/`, `.phi/memory/`)
+The `/benchmark` command tests models across 6 weighted categories:
 
-**Usage:**
-```typescript
-// The extension automatically provides these tools to the LLM
-memory_search("previous bug fixes")
-memory_write("Important lesson learned about React hooks", "react-notes.md")
-memory_read("2024-03-07.md")
-```
+| Category | Weight | Test |
+|----------|--------|------|
+| Code Generation | ×2 | Write a TypeScript function from spec |
+| Debugging | ×2 | Find and fix a mutation bug |
+| Planning | ×2 | Create JWT auth implementation plan |
+| Tool Calling | ×1 | Parse natural language to structured JSON |
+| Speed | ×1 | Response latency (simple instruction following) |
+| Orchestration | ×2 | Multi-step memory leak analysis |
 
-### 2. 🎯 Smart Router Extension (`smart-router.ts`)
+Scoring: S (80+), A (65+), B (50+), C (35+), D (<35)
 
-Intelligent model routing based on task analysis.
+## Memory Auto-Recall
 
-**Features:**
-- Analyzes user input to detect task types
-- Suggests appropriate models via notifications
-- Configurable routing rules via `~/.phi/agent/routing.json`
-- `/routing` command for configuration management
+The memory extension adds prompt guidelines that instruct the model to:
+1. Search memory before answering questions about prior work or decisions
+2. Search memory when starting work on a topic
+3. Write to memory after completing important work
 
-**Task Categories:**
-- **Code tasks** (implement, create, refactor) → Coder model
-- **Debug tasks** (fix, bug, error) → Reasoning model  
-- **Exploration** (read, analyze, explain) → Fast model
-- **Planning** (plan, design, architect) → Reasoning model
+This is not forced via code — it's a prompt guideline that well-trained models follow naturally.
 
-**Commands:**
-- `/routing` - Show current configuration
-- `/routing enable|disable` - Toggle smart routing
-- `/routing notify-on|notify-off` - Toggle notifications
-- `/routing test` - Test routing on sample inputs
+## Setup Wizard Modes
 
-### 3. 📋 Orchestrator Extension (`orchestrator.ts`)
+`/phi-init` offers 3 configuration modes:
 
-High-level project planning and task management.
-
-**Features:**
-- `/plan <description>` - Create structured project plans
-- `orchestrate(description)` - LLM-callable planning tool
-- Generates spec files and TODO lists with timestamps
-- Automatic task breakdown and status tracking
-
-**File Output:**
-- `.phi/plans/spec-TIMESTAMP.md` - Project specifications
-- `.phi/plans/todo-TIMESTAMP.md` - Task lists with checkboxes
-
-**Commands:**
-- `/plan <description>` - Create a new project plan
-- `/plans` - List existing project plans
-
-### 4. 🧩 Skill Loader Extension (`skill-loader.ts`)
-
-Dynamic loading and injection of specialized skills.
-
-**Features:**
-- Scans `~/.phi/agent/skills/` and `.phi/skills/` for skills
-- Keyword-based skill detection and auto-loading
-- `/skills` command to browse available skills
-- Automatic context injection when skills are relevant
-
-**Skill Structure:**
-```
-skill-name/
-├── SKILL.md          # Main skill content
-└── (other files)     # Optional supporting files
-```
-
-**Commands:**
-- `/skills` - List all available skills
-- `/skills <name>` - View specific skill details
-
-### 5. 🌐 Web Search Extension (`web-search.ts`)
-
-Internet search capabilities with multiple providers.
-
-**Features:**
-- `web_search(query, count?)` - LLM-accessible web search
-- Brave Search API integration (with `BRAVE_API_KEY`)
-- DuckDuckGo HTML fallback when API unavailable
-- `/search` command for quick searches
-
-**Setup:**
-```bash
-# Optional: Set Brave Search API key for better results
-export BRAVE_API_KEY="your-api-key"
-```
-
-**Commands:**
-- `/search <query>` - Quick web search from chat
-
-### 6. 🏆 Benchmark Extension (`benchmark.ts`)
-
-Integrated AI model performance testing and comparison.
-
-**Features:**
-- `/benchmark` command for interactive testing
-- Fibonacci code generation test (more categories planned)
-- Performance metrics: time, quality, token usage
-- Results persistence in `~/.phi/benchmark/results.json`
-- Model ranking and comparison
-
-**Test Categories (V1):**
-- **Fibonacci** - Iterative function implementation with test cases
-
-**Commands:**
-- `/benchmark` - Show available options
-- `/benchmark <model>` - Test specific model
-- `/benchmark results` - View benchmark report
-- `/benchmark clear` - Clear all results
-
-## Installation
-
-1. Copy the desired extensions to your extensions directory:
-   ```bash
-   # Global installation
-   cp -r packages/coding-agent/extensions/phi ~/.pi/agent/extensions/
-   
-   # Project-specific installation  
-   cp -r packages/coding-agent/extensions/phi .pi/extensions/
-   ```
-
-2. Extensions will automatically load on next Pi session start.
-
-## Configuration
-
-### Memory Extension
-- Memory files stored in `~/.phi/memory/` (global) and `.phi/memory/` (local)
-- No configuration required - creates directories automatically
-
-### Smart Router Extension
-- Configuration: `~/.phi/agent/routing.json`
-- Auto-creates default config on first run
-- Modify patterns and model assignments as needed
-
-### Skill Loader Extension
-- Skills directory: `~/.phi/agent/skills/` (global) and `.phi/skills/` (local)
-- Each skill is a folder containing `SKILL.md`
-
-### Web Search Extension
-- Optional: Set `BRAVE_API_KEY` environment variable
-- Falls back to DuckDuckGo if no API key provided
-
-### Benchmark Extension
-- Results saved to `~/.phi/benchmark/results.json`
-- No configuration required
-
-## Development
-
-Each extension follows these conventions:
-
-```typescript
-import { Type } from "@sinclair/typebox";
-import type { ExtensionAPI, ExtensionContext } from "phi-code";
-
-export default function extensionName(pi: ExtensionAPI) {
-  // Register tools
-  pi.registerTool({
-    name: "tool_name",
-    description: "Tool description",
-    parameters: Type.Object({
-      param: Type.String({ description: "Parameter description" })
-    }),
-    async execute(toolCallId, params, signal, onUpdate, ctx) {
-      // Implementation
-    }
-  });
-
-  // Register commands
-  pi.registerCommand("command", {
-    description: "Command description", 
-    handler: async (args, ctx) => {
-      // Implementation
-    }
-  });
-
-  // Event listeners
-  pi.on("session_start", async (event, ctx) => {
-    // Session initialization
-  });
-}
-```
-
-### Guidelines
-- Use `@sinclair/typebox` for parameter schemas
-- Prefer Node.js built-in modules over external dependencies
-- Include JSDoc comments for all functions
-- Handle errors gracefully with user-friendly messages
-- Use `ctx.ui.notify()` for user feedback
-
-## Future Extensions
-
-Planned extensions for future releases:
-
-- **Git Integration** - Advanced Git operations and workflow automation
-- **Code Review** - Automated code review and quality checking  
-- **Documentation** - Auto-generation of docs from code
-- **Testing** - Test generation and coverage analysis
-- **Deployment** - CI/CD pipeline integration
-- **Monitoring** - Real-time system monitoring and alerting
-
-## Contributing
-
-To add new extensions:
-
-1. Create a new `.ts` file in this directory
-2. Follow the existing pattern and conventions
-3. Add comprehensive JSDoc documentation
-4. Update this README with the new extension details
-5. Test thoroughly before submitting
-
-## License
-
-Same license as the main Phi Code project.
+- **auto**: Assigns models based on public rankings and specializations (instant)
+- **benchmark**: Tests available models with `/benchmark all`, then assigns best-per-category
+- **manual**: Interactive prompts to choose each model assignment

package/extensions/phi/agents.ts

@@ -0,0 +1,202 @@
+/**
+ * Agents Extension - Sub-agent management and visibility
+ *
+ * Provides:
+ * - /agents command to list all configured sub-agents
+ * - /agents <name> to show detailed agent info
+ * - Agent definitions loaded from ~/.phi/agent/agents/ and .phi/agents/
+ * - Model assignment visibility
+ */
+
+import type { ExtensionAPI } from "phi-code";
+import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+
+interface AgentDefinition {
+	name: string;
+	description: string;
+	tools: string[];
+	model: string;
+	source: string; // "global", "project", "bundled"
+	filePath: string;
+	systemPrompt: string;
+}
+
+/**
+ * Parse YAML frontmatter from agent .md file
+ */
+function parseAgentFile(filePath: string): AgentDefinition | null {
+	try {
+		const content = readFileSync(filePath, "utf-8");
+		const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+
+		if (!fmMatch) return null;
+
+		const frontmatter = fmMatch[1];
+		const body = fmMatch[2].trim();
+
+		// Simple YAML parser for our frontmatter
+		const fields: Record<string, string> = {};
+		for (const line of frontmatter.split("\n")) {
+			const match = line.match(/^(\w+):\s*(.*)$/);
+			if (match) {
+				fields[match[1]] = match[2].trim();
+			}
+		}
+
+		if (!fields.name) return null;
+
+		return {
+			name: fields.name,
+			description: fields.description || "No description",
+			tools: (fields.tools || "").split(",").map(t => t.trim()).filter(Boolean),
+			model: fields.model || "default",
+			source: "unknown",
+			filePath,
+			systemPrompt: body,
+		};
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Scan a directory for agent .md files
+ */
+function scanAgentDir(dir: string, source: string): AgentDefinition[] {
+	const agents: AgentDefinition[] = [];
+
+	if (!existsSync(dir)) return agents;
+
+	try {
+		const entries = readdirSync(dir);
+		for (const entry of entries) {
+			if (!entry.endsWith(".md")) continue;
+			const fullPath = join(dir, entry);
+			if (!statSync(fullPath).isFile()) continue;
+
+			const agent = parseAgentFile(fullPath);
+			if (agent) {
+				agent.source = source;
+				agents.push(agent);
+			}
+		}
+	} catch {
+		// Directory not readable
+	}
+
+	return agents;
+}
+
+export default function agentsExtension(pi: ExtensionAPI) {
+	/**
+	 * Discover all agent definitions from all sources
+	 */
+	function discoverAgents(): AgentDefinition[] {
+		const seen = new Set<string>();
+		const allAgents: AgentDefinition[] = [];
+
+		const addAgents = (agents: AgentDefinition[]) => {
+			for (const agent of agents) {
+				if (!seen.has(agent.name)) {
+					seen.add(agent.name);
+					allAgents.push(agent);
+				}
+			}
+		};
+
+		// 1. Project-local agents
+		addAgents(scanAgentDir(join(process.cwd(), ".phi", "agents"), "project"));
+
+		// 2. Global agents
+		addAgents(scanAgentDir(join(homedir(), ".phi", "agent", "agents"), "global"));
+
+		// 3. Bundled agents (shipped with package)
+		const bundledDir = join(__dirname, "..", "..", "..", "agents");
+		if (existsSync(bundledDir)) {
+			addAgents(scanAgentDir(bundledDir, "bundled"));
+		}
+
+		return allAgents;
+	}
+
+	/**
+	 * /agents command
+	 */
+	pi.registerCommand("agents", {
+		description: "List and inspect sub-agent definitions",
+		handler: async (args, ctx) => {
+			const agents = discoverAgents();
+			const arg = args.trim().toLowerCase();
+
+			if (agents.length === 0) {
+				ctx.ui.notify("No agent definitions found.\n\nCreate agent files in:\n- `.phi/agents/` (project)\n- `~/.phi/agent/agents/` (global)\n\nFormat: Markdown with YAML frontmatter (name, description, tools, model).", "info");
+				return;
+			}
+
+			// Show specific agent details
+			if (arg && arg !== "list") {
+				const agent = agents.find(a => a.name.toLowerCase() === arg);
+				if (!agent) {
+					ctx.ui.notify(`Agent "${arg}" not found. Available: ${agents.map(a => a.name).join(", ")}`, "warning");
+					return;
+				}
+
+				const detail = `**Agent: ${agent.name}**
+
+📝 ${agent.description}
+🤖 Model: \`${agent.model}\`
+🔧 Tools: ${agent.tools.map(t => `\`${t}\``).join(", ")}
+📁 Source: ${agent.source} (\`${agent.filePath}\`)
+
+**System Prompt:**
+\`\`\`
+${agent.systemPrompt.substring(0, 800)}${agent.systemPrompt.length > 800 ? "\n..." : ""}
+\`\`\``;
+
+				ctx.ui.notify(detail, "info");
+				return;
+			}
+
+			// List all agents
+			let output = `**🤖 Sub-Agents (${agents.length})**\n\n`;
+
+			// Group by source
+			const bySource: Record<string, AgentDefinition[]> = {};
+			for (const agent of agents) {
+				const key = agent.source;
+				if (!bySource[key]) bySource[key] = [];
+				bySource[key].push(agent);
+			}
+
+			const sourceLabels: Record<string, string> = {
+				project: "📁 Project (.phi/agents/)",
+				global: "🏠 Global (~/.phi/agent/agents/)",
+				bundled: "📦 Bundled (shipped with Phi Code)",
+			};
+
+			for (const [source, sourceAgents] of Object.entries(bySource)) {
+				output += `**${sourceLabels[source] || source}**\n`;
+				for (const agent of sourceAgents) {
+					output += `  • **${agent.name}** → \`${agent.model}\`\n`;
+					output += `    ${agent.description}\n`;
+					output += `    Tools: ${agent.tools.join(", ")}\n`;
+				}
+				output += "\n";
+			}
+
+			output += `Use \`/agents <name>\` for detailed info on a specific agent.`;
+
+			ctx.ui.notify(output, "info");
+		},
+	});
+
+	// Session start: show agent count
+	pi.on("session_start", async (_event, ctx) => {
+		const agents = discoverAgents();
+		if (agents.length > 0) {
+			ctx.ui.notify(`🤖 ${agents.length} sub-agents available. /agents to list.`, "info");
+		}
+	});
+}