pi-code 0.1.0

package/extensions/subagent/agents/planner.md

@@ -0,0 +1,37 @@
+---
+name: planner
+description: Creates implementation plans from context and requirements
+tools: read, grep, find, ls
+model: claude-sonnet-4-5
+---
+
+You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.
+
+You must NOT make any changes. Only read, analyze, and plan.
+
+Input format you'll receive:
+- Context/findings from a scout agent
+- Original query or requirements
+
+Output format:
+
+## Goal
+One sentence summary of what needs to be done.
+
+## Plan
+Numbered steps, each small and actionable:
+1. Step one - specific file/function to modify
+2. Step two - what to add/change
+3. ...
+
+## Files to Modify
+- `path/to/file.ts` - what changes
+- `path/to/other.ts` - what changes
+
+## New Files (if any)
+- `path/to/new.ts` - purpose
+
+## Risks
+Anything to watch out for.
+
+Keep the plan concrete. The worker agent will execute it verbatim.

package/extensions/subagent/agents/reviewer.md

@@ -0,0 +1,35 @@
+---
+name: reviewer
+description: Code review specialist for quality and security analysis
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-5
+---
+
+You are a senior code reviewer. Analyze code for quality, security, and maintainability.
+
+Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
+Assume tool permissions are not perfectly enforceable; keep all bash usage strictly read-only.
+
+Strategy:
+1. Run `git diff` to see recent changes (if applicable)
+2. Read the modified files
+3. Check for bugs, security issues, code smells
+
+Output format:
+
+## Files Reviewed
+- `path/to/file.ts` (lines X-Y)
+
+## Critical (must fix)
+- `file.ts:42` - Issue description
+
+## Warnings (should fix)
+- `file.ts:100` - Issue description
+
+## Suggestions (consider)
+- `file.ts:150` - Improvement idea
+
+## Summary
+Overall assessment in 2-3 sentences.
+
+Be specific with file paths and line numbers.

package/extensions/subagent/agents/scout.md

@@ -0,0 +1,50 @@
+---
+name: scout
+description: Fast codebase recon that returns compressed context for handoff to other agents
+tools: read, grep, find, ls, bash
+model: claude-haiku-4-5
+---
+
+You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
+
+Your output will be passed to an agent who has NOT seen the files you explored.
+
+Thoroughness (infer from task, default medium):
+- Quick: Targeted lookups, key files only
+- Medium: Follow imports, read critical sections
+- Thorough: Trace all dependencies, check tests/types
+
+Strategy:
+1. grep/find to locate relevant code
+2. Read key sections (not entire files)
+3. Identify types, interfaces, key functions
+4. Note dependencies between files
+
+Output format:
+
+## Files Retrieved
+List with exact line ranges:
+1. `path/to/file.ts` (lines 10-50) - Description of what's here
+2. `path/to/other.ts` (lines 100-150) - Description
+3. ...
+
+## Key Code
+Critical types, interfaces, or functions:
+
+```typescript
+interface Example {
+  // actual code from the files
+}
+```
+
+```typescript
+function keyFunction() {
+  // actual implementation
+}
+```
+
+## Architecture
+Brief explanation of how the pieces connect.
+
+## Start Here
+Which file to look at first and why.

package/extensions/subagent/agents/worker.md

@@ -0,0 +1,24 @@
+---
+name: worker
+description: General-purpose subagent with full capabilities, isolated context
+model: claude-sonnet-4-5
+---
+
+You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.
+
+Work autonomously to complete the assigned task. Use all available tools as needed.
+
+Output format when finished:
+
+## Completed
+What was done.
+
+## Files Changed
+- `path/to/file.ts` - what changed
+
+## Notes (if any)
+Anything the main agent should know.
+
+If handing off to another agent (e.g. reviewer), include:
+- Exact file paths changed
+- Key functions/types touched (short list)

package/extensions/subagent/agents.ts

@@ -0,0 +1,147 @@
+/**
+ * Agent discovery and configuration
+ */
+
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { getAgentDir, parseFrontmatter } from '@earendil-works/pi-coding-agent'
+
+// Claude Code tool names -> pi tool names; unmapped names pass through lowercased
+const CLAUDE_TOOL_MAP: Record<string, string> = {
+  read: 'read',
+  write: 'write',
+  edit: 'edit',
+  bash: 'bash',
+  grep: 'grep',
+  glob: 'find',
+  ls: 'ls',
+}
+
+function normalizeToolName(tool: string): string {
+  const lower = tool.toLowerCase()
+  return CLAUDE_TOOL_MAP[lower] ?? lower
+}
+
+export type AgentScope = 'user' | 'project' | 'both'
+
+export interface AgentConfig {
+  name: string
+  description: string
+  tools?: string[]
+  model?: string
+  systemPrompt: string
+  source: 'user' | 'project'
+  filePath: string
+}
+
+export interface AgentDiscoveryResult {
+  agents: AgentConfig[]
+  projectAgentsDir: string | null
+}
+
+function loadAgentsFromDir(dir: string, source: 'user' | 'project'): AgentConfig[] {
+  const agents: AgentConfig[] = []
+
+  if (!fs.existsSync(dir)) {
+    return agents
+  }
+
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return agents
+  }
+
+  for (const entry of entries) {
+    if (!entry.name.endsWith('.md')) continue
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue
+
+    const filePath = path.join(dir, entry.name)
+    let content: string
+    try {
+      content = fs.readFileSync(filePath, 'utf-8')
+    } catch {
+      continue
+    }
+
+    const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content)
+
+    if (!frontmatter.name || !frontmatter.description) {
+      continue
+    }
+
+    const tools = frontmatter.tools
+      ?.split(',')
+      .map((t: string) => normalizeToolName(t.trim()))
+      .filter(Boolean)
+
+    agents.push({
+      name: frontmatter.name,
+      description: frontmatter.description,
+      tools: tools && tools.length > 0 ? tools : undefined,
+      model: frontmatter.model,
+      systemPrompt: body,
+      source,
+      filePath,
+    })
+  }
+
+  return agents
+}
+
+function isDirectory(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function findNearestDir(cwd: string, relative: string): string | null {
+  let currentDir = cwd
+  while (true) {
+    const candidate = path.join(currentDir, relative)
+    if (isDirectory(candidate)) return candidate
+
+    const parentDir = path.dirname(currentDir)
+    if (parentDir === currentDir) return null
+    currentDir = parentDir
+  }
+}
+
+export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
+  const userDir = path.join(getAgentDir(), 'agents')
+  const claudeUserDir = path.join(os.homedir(), '.claude', 'agents')
+  const projectPiDir = findNearestDir(cwd, path.join('.pi', 'agents'))
+  const projectClaudeDir = findNearestDir(cwd, path.join('.claude', 'agents'))
+
+  // ~/.claude/agents loads first so ~/.pi/agent/agents wins on name conflicts
+  const userAgents = scope === 'project' ? [] : [...loadAgentsFromDir(claudeUserDir, 'user'), ...loadAgentsFromDir(userDir, 'user')]
+  // project .claude/agents loads first so project .pi/agents wins on name conflicts
+  const projectAgents = scope === 'user' ? [] : [...(projectClaudeDir ? loadAgentsFromDir(projectClaudeDir, 'project') : []), ...(projectPiDir ? loadAgentsFromDir(projectPiDir, 'project') : [])]
+
+  const agentMap = new Map<string, AgentConfig>()
+
+  if (scope === 'both') {
+    for (const agent of userAgents) agentMap.set(agent.name, agent)
+    for (const agent of projectAgents) agentMap.set(agent.name, agent)
+  } else if (scope === 'user') {
+    for (const agent of userAgents) agentMap.set(agent.name, agent)
+  } else {
+    for (const agent of projectAgents) agentMap.set(agent.name, agent)
+  }
+
+  return { agents: Array.from(agentMap.values()), projectAgentsDir: projectPiDir }
+}
+
+export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {
+  if (agents.length === 0) return { text: 'none', remaining: 0 }
+  const listed = agents.slice(0, maxItems)
+  const remaining = agents.length - listed.length
+  return {
+    text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join('; '),
+    remaining,
+  }
+}

package/extensions/subagent/background.ts

@@ -0,0 +1,89 @@
+/**
+ * Background subagent runs: fire-and-forget children whose completion wakes
+ * the parent agent via a notification message. Session-scoped (children die
+ * with pi); state lives in an in-memory registry queried via {action:"status"}.
+ */
+
+import { spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+
+export interface BackgroundRun {
+  id: string
+  agent: string
+  task: string
+  state: 'running' | 'done' | 'failed'
+  exitCode?: number
+  output?: string
+  turns: number
+}
+
+export interface BackgroundSpawn {
+  command: string
+  args: string[]
+  cwd: string
+}
+
+const runs = new Map<string, BackgroundRun>()
+
+/** Extract the final assistant text and turn count from a pi --mode json stdout stream. */
+export function parseFinalOutputFromJsonl(jsonl: string): { text: string; turns: number } {
+  let text = ''
+  let turns = 0
+  for (const line of jsonl.split('\n')) {
+    if (!line.trim()) continue
+    let event: { type?: string; message?: { role?: string; content?: Array<{ type: string; text?: string }> } }
+    try {
+      event = JSON.parse(line)
+    } catch {
+      continue
+    }
+    if (event.type !== 'message_end' || event.message?.role !== 'assistant') continue
+    turns++
+    for (const part of event.message.content ?? []) {
+      if (part.type === 'text' && part.text) text = part.text
+    }
+  }
+  return { text, turns }
+}
+
+export function formatStatus(all: Iterable<BackgroundRun>): string {
+  const lines = [...all].map((run) => {
+    const label = run.state === 'running' ? 'running' : `${run.state} (exit ${run.exitCode ?? '?'}, ${run.turns} turns)`
+    return `${run.id} ${run.agent}: ${label} - ${run.task.slice(0, 60)}`
+  })
+  return lines.length > 0 ? lines.join('\n') : 'No background runs in this session.'
+}
+
+export function backgroundStatusText(): string {
+  return formatStatus(runs.values())
+}
+
+export function startBackgroundRun(agent: string, task: string, invocation: BackgroundSpawn, onComplete: (run: BackgroundRun) => void): string {
+  const id = `bg-${randomUUID().slice(0, 8)}`
+  const run: BackgroundRun = { id, agent, task, state: 'running', turns: 0 }
+  runs.set(id, run)
+
+  const proc = spawn(invocation.command, invocation.args, {
+    cwd: invocation.cwd,
+    shell: false,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  })
+  let stdout = ''
+  proc.stdout.on('data', (data) => {
+    stdout += data.toString()
+  })
+  proc.on('close', (code) => {
+    const { text, turns } = parseFinalOutputFromJsonl(stdout)
+    run.state = code === 0 ? 'done' : 'failed'
+    run.exitCode = code ?? 0
+    run.output = text
+    run.turns = turns
+    onComplete(run)
+  })
+  proc.on('error', () => {
+    run.state = 'failed'
+    run.exitCode = 1
+    onComplete(run)
+  })
+  return id
+}