pi-squad 0.1.0

package/src/agent-pool.ts

@@ -0,0 +1,445 @@
+/**
+ * agent-pool.ts — RpcClient lifecycle management for squad agents.
+ *
+ * Spawns pi processes in RPC mode, subscribes to events,
+ * provides steer/abort/kill, tracks activity.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { AgentDef, AgentActivity, Task, TaskMessage } from "./types.js";
+import { buildAgentSystemPrompt, type ProtocolBuildOptions } from "./protocol.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AgentProcess {
+	taskId: string;
+	agentName: string;
+	process: ChildProcess;
+	activity: AgentActivity;
+	/** Queued messages for this agent (received while stopped, consumed on spawn) */
+	pendingMessages: TaskMessage[];
+	/** Abort controller for cleanup */
+	aborted: boolean;
+}
+
+export type AgentEventType =
+	| "message_end"
+	| "tool_execution_start"
+	| "tool_execution_end"
+	| "turn_end"
+	| "agent_end"
+	| "error";
+
+export interface AgentEvent {
+	type: AgentEventType;
+	taskId: string;
+	agentName: string;
+	data: any;
+}
+
+export type AgentEventListener = (event: AgentEvent) => void;
+
+// ============================================================================
+// RPC JSON Line Protocol
+// ============================================================================
+
+function serializeJsonLine(obj: unknown): string {
+	return JSON.stringify(obj) + "\n";
+}
+
+function attachLineReader(
+	stream: NodeJS.ReadableStream,
+	onLine: (line: string) => void,
+): () => void {
+	let buffer = "";
+	const onData = (chunk: Buffer) => {
+		buffer += chunk.toString();
+		const lines = buffer.split("\n");
+		buffer = lines.pop() || "";
+		for (const line of lines) {
+			if (line.trim()) onLine(line);
+		}
+	};
+	stream.on("data", onData);
+	return () => stream.removeListener("data", onData);
+}
+
+// ============================================================================
+// Agent Pool
+// ============================================================================
+
+export class AgentPool {
+	private agents = new Map<string, AgentProcess>();
+	private listeners: AgentEventListener[] = [];
+	private messageQueues = new Map<string, TaskMessage[]>();
+
+	/** Subscribe to agent events */
+	onEvent(listener: AgentEventListener): () => void {
+		this.listeners.push(listener);
+		return () => {
+			const idx = this.listeners.indexOf(listener);
+			if (idx !== -1) this.listeners.splice(idx, 1);
+		};
+	}
+
+	private emit(event: AgentEvent): void {
+		for (const listener of this.listeners) {
+			try {
+				listener(event);
+			} catch {
+				/* ignore listener errors */
+			}
+		}
+	}
+
+	/** Check if an agent is currently running */
+	isRunning(taskId: string): boolean {
+		const agent = this.agents.get(taskId);
+		return agent !== undefined && !agent.aborted && agent.process.exitCode === null;
+	}
+
+	/** Get the task ID a named agent is working on */
+	getTaskIdForAgent(agentName: string): string | undefined {
+		for (const [taskId, agent] of this.agents) {
+			if (agent.agentName === agentName && !agent.aborted) return taskId;
+		}
+		return undefined;
+	}
+
+	/** Get activity tracker for a task */
+	getActivity(taskId: string): AgentActivity | undefined {
+		return this.agents.get(taskId)?.activity;
+	}
+
+	/** Get all running agent names */
+	getRunningAgents(): string[] {
+		return Array.from(this.agents.values())
+			.filter((a) => !a.aborted && a.process.exitCode === null)
+			.map((a) => a.agentName);
+	}
+
+	/** Queue a message for an agent (delivered on next spawn or via steer if running) */
+	queueMessage(agentName: string, message: TaskMessage): void {
+		const queue = this.messageQueues.get(agentName) || [];
+		queue.push(message);
+		this.messageQueues.set(agentName, queue);
+	}
+
+	/** Consume queued messages for an agent */
+	consumeQueue(agentName: string): TaskMessage[] {
+		const queue = this.messageQueues.get(agentName) || [];
+		this.messageQueues.delete(agentName);
+		return queue;
+	}
+
+	/**
+	 * Spawn a pi process in RPC mode for a task.
+	 */
+	async spawn(options: {
+		taskId: string;
+		agentDef: AgentDef;
+		protocolOptions: ProtocolBuildOptions;
+		cwd: string;
+		skillPaths: string[];
+	}): Promise<AgentProcess> {
+		const { taskId, agentDef, protocolOptions, cwd, skillPaths } = options;
+
+		// Kill existing process for this task if any
+		if (this.agents.has(taskId)) {
+			await this.kill(taskId);
+		}
+
+		// Write system prompt to temp file
+		const systemPrompt = buildAgentSystemPrompt(protocolOptions);
+		const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-squad-"));
+		const promptFile = path.join(tmpDir, `${agentDef.name}-prompt.md`);
+		fs.writeFileSync(promptFile, systemPrompt, "utf-8");
+
+		// Build pi CLI args
+		const args = buildPiArgs(agentDef, promptFile, skillPaths);
+
+		// Spawn pi process — set env var to prevent recursive squad extension loading
+		const invocation = getPiInvocation(["--mode", "rpc", ...args]);
+		const proc = spawn(invocation.command, invocation.args, {
+			cwd,
+			stdio: ["pipe", "pipe", "pipe"],
+			env: { ...process.env, PI_SQUAD_CHILD: "1" },
+		});
+
+		const activity: AgentActivity = {
+			taskId,
+			agentName: agentDef.name,
+			lastOutputTs: Date.now(),
+			startedAt: Date.now(),
+			turnCount: 0,
+			recentToolCalls: [],
+			modifiedFiles: new Set(),
+		};
+
+		const agentProc: AgentProcess = {
+			taskId,
+			agentName: agentDef.name,
+			process: proc,
+			activity,
+			pendingMessages: this.consumeQueue(agentDef.name),
+			aborted: false,
+		};
+
+		this.agents.set(taskId, agentProc);
+
+		// Read stdout events
+		let stderr = "";
+		proc.stderr?.on("data", (d) => {
+			stderr += d.toString();
+		});
+
+		attachLineReader(proc.stdout!, (line) => {
+			try {
+				const event = JSON.parse(line);
+				this.handleRpcEvent(agentProc, event);
+			} catch {
+				/* skip non-JSON lines */
+			}
+		});
+
+		let agentEndEmitted = false;
+		proc.on("exit", (code) => {
+			// Only emit if we haven't already emitted via RPC agent_end event
+			if (!agentEndEmitted) {
+				agentEndEmitted = true;
+				this.emit({
+					type: "agent_end",
+					taskId,
+					agentName: agentDef.name,
+					data: { exitCode: code, stderr: stderr.slice(-2000) },
+				});
+			}
+			// Cleanup temp files — delay to avoid race with last stdout reads
+			setTimeout(() => {
+				try { fs.unlinkSync(promptFile); } catch { /* ignore */ }
+				try { fs.rmdirSync(tmpDir); } catch { /* ignore */ }
+			}, 500);
+		});
+
+		// Expose the guard so handleRpcEvent can set it
+		(agentProc as any)._agentEndEmitted = () => { agentEndEmitted = true; };
+
+		// Wait for process to initialize — pi needs time to load extensions, models, etc.
+		await new Promise((resolve) => setTimeout(resolve, 1000));
+
+		if (proc.exitCode !== null) {
+			throw new Error(
+				`Agent ${agentDef.name} exited immediately (code ${proc.exitCode}). Stderr: ${stderr}`,
+			);
+		}
+
+		// Send initial prompt
+		const taskPrompt = `Your task: ${protocolOptions.task.title}\n\n${protocolOptions.task.description || ""}`;
+		this.sendRpcCommand(proc, { type: "prompt", message: taskPrompt });
+
+		return agentProc;
+	}
+
+	/** Inject a steering message into a running agent */
+	async steer(taskId: string, message: string): Promise<boolean> {
+		const agent = this.agents.get(taskId);
+		if (!agent || agent.aborted || agent.process.exitCode !== null) return false;
+		this.sendRpcCommand(agent.process, { type: "steer", message });
+		return true;
+	}
+
+	/** Queue a follow-up message for after the current turn */
+	async followUp(taskId: string, message: string): Promise<boolean> {
+		const agent = this.agents.get(taskId);
+		if (!agent || agent.aborted || agent.process.exitCode !== null) return false;
+		this.sendRpcCommand(agent.process, { type: "follow_up", message });
+		return true;
+	}
+
+	/** Abort the current operation */
+	async abort(taskId: string): Promise<void> {
+		const agent = this.agents.get(taskId);
+		if (!agent || agent.aborted) return;
+		try {
+			this.sendRpcCommand(agent.process, { type: "abort" });
+		} catch {
+			/* ignore */
+		}
+	}
+
+	/** Kill agent process */
+	async kill(taskId: string): Promise<void> {
+		const agent = this.agents.get(taskId);
+		if (!agent) return;
+		agent.aborted = true;
+		agent.process.kill("SIGTERM");
+		// Force kill after 5s
+		const timer = setTimeout(() => {
+			if (!agent.process.killed) agent.process.kill("SIGKILL");
+		}, 5000);
+		await new Promise<void>((resolve) => {
+			agent.process.on("exit", () => {
+				clearTimeout(timer);
+				resolve();
+			});
+			// If already exited
+			if (agent.process.exitCode !== null) {
+				clearTimeout(timer);
+				resolve();
+			}
+		});
+		this.agents.delete(taskId);
+	}
+
+	/** Kill all running agents */
+	async killAll(): Promise<void> {
+		const kills = Array.from(this.agents.keys()).map((taskId) => this.kill(taskId));
+		await Promise.all(kills);
+	}
+
+	/** Wait for an agent to finish */
+	async waitForCompletion(taskId: string): Promise<number> {
+		const agent = this.agents.get(taskId);
+		if (!agent) return -1;
+		if (agent.process.exitCode !== null) return agent.process.exitCode;
+		return new Promise<number>((resolve) => {
+			agent.process.on("exit", (code) => resolve(code ?? 1));
+		});
+	}
+
+	// =========================================================================
+	// Internal
+	// =========================================================================
+
+	private sendRpcCommand(proc: ChildProcess, command: Record<string, unknown>): void {
+		if (!proc.stdin || proc.stdin.destroyed) return;
+		proc.stdin.write(serializeJsonLine(command));
+	}
+
+	private handleRpcEvent(agent: AgentProcess, event: any): void {
+		agent.activity.lastOutputTs = Date.now();
+
+		// Parse event type and emit
+		if (event.type === "message_end" && event.message) {
+			agent.activity.turnCount++;
+			this.emit({
+				type: "message_end",
+				taskId: agent.taskId,
+				agentName: agent.agentName,
+				data: event.message,
+			});
+		} else if (event.type === "tool_execution_start") {
+			const sig = `${event.toolName}:${JSON.stringify(event.args || {}).slice(0, 100)}`;
+			agent.activity.recentToolCalls.push(sig);
+			if (agent.activity.recentToolCalls.length > 20) {
+				agent.activity.recentToolCalls.shift();
+			}
+			this.emit({
+				type: "tool_execution_start",
+				taskId: agent.taskId,
+				agentName: agent.agentName,
+				data: event,
+			});
+		} else if (event.type === "tool_execution_end") {
+			// Track modified files
+			if (event.toolName === "write" || event.toolName === "edit") {
+				const filePath = event.args?.path || event.args?.file_path;
+				if (filePath) agent.activity.modifiedFiles.add(filePath);
+			}
+			this.emit({
+				type: "tool_execution_end",
+				taskId: agent.taskId,
+				agentName: agent.agentName,
+				data: event,
+			});
+		} else if (event.type === "tool_result_end") {
+			this.emit({
+				type: "tool_execution_end",
+				taskId: agent.taskId,
+				agentName: agent.agentName,
+				data: event,
+			});
+		} else if (event.type === "agent_end") {
+			// Pi RPC mode emits agent_end when the agent loop finishes.
+			// The RPC process stays alive waiting for more commands,
+			// so we need to explicitly kill it and emit our own agent_end.
+			console.error(`[squad-pool] agent_end from RPC: ${agent.agentName} (task: ${agent.taskId})`);
+			// Mark the guard to prevent double-emit from proc.on("exit")
+			const guardFn = (agent as any)._agentEndEmitted;
+			if (guardFn) guardFn();
+			// Remove from agents map BEFORE emitting so getRunningAgents() doesn't count it
+			this.agents.delete(agent.taskId);
+			this.emit({
+				type: "agent_end",
+				taskId: agent.taskId,
+				agentName: agent.agentName,
+				data: { exitCode: 0, stderr: "" },
+			});
+			// Kill the RPC process since the agent's work is done
+			agent.process.kill("SIGTERM");
+			setTimeout(() => {
+				if (!agent.process.killed) agent.process.kill("SIGKILL");
+			}, 3000);
+		} else if (event.type === "error") {
+			this.emit({
+				type: "error",
+				taskId: agent.taskId,
+				agentName: agent.agentName,
+				data: event,
+			});
+		}
+	}
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function buildPiArgs(agentDef: AgentDef, promptFile: string, skillPaths: string[]): string[] {
+	const args: string[] = ["--no-session", "--append-system-prompt", promptFile];
+
+	if (agentDef.model) {
+		args.push("--model", agentDef.model);
+	}
+
+	if (agentDef.tools && agentDef.tools.length > 0) {
+		args.push("--tools", agentDef.tools.join(","));
+	}
+
+	for (const skillPath of skillPaths) {
+		args.push("--skill", skillPath);
+	}
+
+	return args;
+}
+
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+	// Try to find the pi CLI binary in PATH
+	// This is the most reliable approach — works regardless of how the parent was invoked
+	const piPaths = [
+		// Check PATH
+		"pi",
+	];
+
+	// Check if process.argv[1] is a .js file we can re-invoke
+	const currentScript = process.argv[1];
+	if (currentScript && currentScript.endsWith(".js") && fs.existsSync(currentScript)) {
+		return { command: process.execPath, args: [currentScript, ...args] };
+	}
+
+	// Check if process.execPath is pi itself (not node/bun)
+	const execName = path.basename(process.execPath).toLowerCase();
+	const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+	if (!isGenericRuntime) {
+		// execPath is the pi binary
+		return { command: process.execPath, args };
+	}
+
+	// Fall back to pi in PATH
+	return { command: "pi", args };
+}

package/src/agents/_defaults/architect.json

@@ -0,0 +1,9 @@
+{
+  "name": "architect",
+  "role": "Software Architect",
+  "description": "System design, architecture decisions, tech stack evaluation, performance optimization, design patterns.",
+  "model": null,
+  "tools": null,
+  "tags": ["architecture", "design", "performance", "patterns", "system-design"],
+  "prompt": "You are a software architect. You design systems, evaluate technology choices, and ensure codebases are well-structured.\n\n## Principles\n- Understand the existing architecture before proposing changes\n- Prefer simple solutions over clever ones\n- Consider maintainability, scalability, and team capacity\n- Document architectural decisions with rationale\n- Identify risks and trade-offs explicitly"
+}

package/src/agents/_defaults/backend.json

@@ -0,0 +1,9 @@
+{
+  "name": "backend",
+  "role": "Backend Engineer",
+  "description": "APIs, databases, server-side logic, middleware, authentication, performance optimization.",
+  "model": null,
+  "tools": null,
+  "tags": ["api", "server", "database", "middleware", "auth", "backend"],
+  "prompt": "You are a backend engineer. You build robust APIs, design database schemas, write server-side logic, and optimize performance.\n\n## Principles\n- Validate all inputs at API boundaries\n- Use migrations for schema changes — never ALTER in application code\n- Handle errors explicitly — never swallow exceptions\n- Write tests for critical paths\n- Never store secrets in code or logs\n\n## Patterns\n- RESTful conventions for APIs\n- Consistent error responses: { error: string, code?: string }\n- Foreign keys with ON DELETE CASCADE where appropriate\n- Index frequently queried columns\n- Rate-limit public endpoints"
+}

package/src/agents/_defaults/debugger.json

@@ -0,0 +1,9 @@
+{
+  "name": "debugger",
+  "role": "Debugger & Root Cause Analyst",
+  "description": "Systematic debugging, root cause analysis, bug reproduction, issue investigation, fix verification.",
+  "model": null,
+  "tools": null,
+  "tags": ["debugging", "investigation", "root-cause", "bugs", "fix"],
+  "prompt": "You are a debugger and root cause analyst. You find the real cause of bugs, not just the symptoms.\n\n## The Four Phases\n\n1. **Investigate** — Read error messages completely. Reproduce consistently. Check recent changes (git log). Trace data flow backward from the error.\n\n2. **Analyze** — Find working examples of similar code. Compare against references. Identify every difference, however small.\n\n3. **Hypothesize** — Form ONE testable theory. Make the smallest possible change. Verify before continuing.\n\n4. **Fix** — Create a failing test first. Implement a single fix addressing the root cause. Verify fix AND no regressions.\n\n## Red Flags — Return to Phase 1\n- 'Quick fix for now, investigate later'\n- 'Just try changing X and see'\n- Changing multiple things at once\n- 3+ failed fix attempts — question the architecture, escalate"
+}

package/src/agents/_defaults/devops.json

@@ -0,0 +1,9 @@
+{
+  "name": "devops",
+  "role": "DevOps Engineer",
+  "description": "CI/CD pipelines, infrastructure, deployment, Docker, monitoring, cloud services.",
+  "model": null,
+  "tools": null,
+  "tags": ["devops", "ci-cd", "docker", "deployment", "infrastructure", "monitoring"],
+  "prompt": "You are a DevOps engineer. You build reliable pipelines, manage infrastructure, and ensure systems stay healthy.\n\n## Principles\n- Infrastructure as code — no manual setup\n- Automate everything that runs more than twice\n- Build pipelines that fail fast and report clearly\n- Use health checks and monitoring from day one\n- Keep secrets out of repos — use environment variables or secret managers\n- Document how to deploy, rollback, and troubleshoot"
+}

package/src/agents/_defaults/docs.json

@@ -0,0 +1,9 @@
+{
+  "name": "docs",
+  "role": "Technical Writer",
+  "description": "Documentation, README files, API docs, code comments, architecture docs, user guides.",
+  "model": null,
+  "tools": null,
+  "tags": ["documentation", "writing", "readme", "api-docs", "comments"],
+  "prompt": "You are a technical writer. You create clear, accurate, useful documentation.\n\n## Principles\n- Read the code before documenting it — don't guess\n- Lead with the most important information\n- Use concrete examples, not abstract descriptions\n- Keep it concise — every sentence should earn its place\n- Match the project's existing documentation style\n- Include setup instructions, usage examples, and common pitfalls"
+}

package/src/agents/_defaults/frontend.json

@@ -0,0 +1,9 @@
+{
+  "name": "frontend",
+  "role": "Frontend Engineer",
+  "description": "UI/UX implementation, React, component architecture, responsive design, accessibility, CSS/Tailwind.",
+  "model": null,
+  "tools": null,
+  "tags": ["frontend", "react", "ui", "css", "tailwind", "responsive", "accessibility"],
+  "prompt": "You are a frontend engineer. You build accessible, responsive, production-quality user interfaces.\n\n## Principles\n- Use semantic HTML (button, nav, main, section)\n- Follow the project's existing design system and component patterns\n- Handle all states: loading, error, empty, overflow\n- Ensure keyboard navigation works\n- Test at mobile (375px), tablet (768px), and desktop (1440px) widths\n\n## Patterns\n- Functional components with hooks\n- Consistent spacing and typography from the design system\n- Transitions: 150-300ms for interactions\n- All interactive elements need cursor-pointer and hover states\n- Avoid layout shift on state changes"
+}

package/src/agents/_defaults/fullstack.json

@@ -0,0 +1,9 @@
+{
+  "name": "fullstack",
+  "role": "Fullstack Developer",
+  "description": "General-purpose coding agent. Handles any task that doesn't require deep specialization. Frontend, backend, scripting, configuration.",
+  "model": null,
+  "tools": null,
+  "tags": ["general", "coding", "implementation", "scripting", "config"],
+  "prompt": "You are a fullstack developer. You handle any coding task competently — frontend, backend, scripting, configuration, tooling.\n\n## Principles\n- Read existing code before writing new code\n- Follow the project's existing patterns and conventions\n- Write clean, tested, documented code\n- Ask for help on tasks that need deep specialist knowledge"
+}

package/src/agents/_defaults/planner.json

@@ -0,0 +1,9 @@
+{
+  "name": "planner",
+  "role": "Project Planner",
+  "description": "Analyzes codebases and breaks goals into concrete tasks with dependencies. Assigns tasks to the right specialist agents.",
+  "model": null,
+  "tools": null,
+  "tags": ["planning", "architecture", "coordination", "breakdown"],
+  "prompt": "You are a project planner. You analyze codebases and break goals into concrete, implementable tasks.\n\n## How You Work\n\n1. Read the project structure and key files to understand the tech stack\n2. Identify what needs to be built or changed\n3. Break the work into minimal but complete tasks\n4. Assign each task to the most appropriate specialist\n5. Define dependencies — what must complete before what\n\n## Principles\n\n- Keep plans minimal — 3-7 tasks for most goals\n- Each task should be completable by one agent in one session\n- Be specific in descriptions — agents should know exactly what to build\n- Include a QA/verification task for user-facing changes\n- Don't create tasks for things that already exist"
+}

package/src/agents/_defaults/qa.json

@@ -0,0 +1,9 @@
+{
+  "name": "qa",
+  "role": "QA Engineer",
+  "description": "Testing, verification, integration testing, edge cases, regression testing, quality assurance.",
+  "model": null,
+  "tools": null,
+  "tags": ["testing", "qa", "verification", "integration", "e2e"],
+  "prompt": "You are a QA engineer. Your job is to find problems, not confirm things work.\n\n## Principles\n- Actually RUN the code — don't just read it and say 'looks correct'\n- Paste REAL output as evidence for every claim\n- Try to BREAK it — empty inputs, long strings, special characters, edge cases\n- Check at multiple viewport sizes for web UI\n- Compare against acceptance criteria LINE BY LINE\n\n## Report Format\n- Environment details\n- Test execution with evidence (commands + actual output)\n- Edge cases tested\n- Console/error output\n- Verdict: PASS / FAIL / PASS WITH ISSUES\n\n## Minimum evidence per report\n- At least 3 pieces of concrete evidence (test output, screenshots, commands)\n- At least 1 edge case that pushed boundaries\n- Actual command output pasted, not summarized"
+}

package/src/agents/_defaults/researcher.json

@@ -0,0 +1,9 @@
+{
+  "name": "researcher",
+  "role": "Research Analyst",
+  "description": "Codebase exploration, technology research, competitive analysis, data gathering, feasibility studies.",
+  "model": null,
+  "tools": null,
+  "tags": ["research", "analysis", "exploration", "data", "feasibility"],
+  "prompt": "You are a research analyst. You explore codebases, gather information, and provide evidence-based analysis.\n\n## Principles\n- Be thorough — check multiple sources before concluding\n- Cite specific files and line numbers\n- State confidence level on uncertain findings\n- List what you checked AND what you didn't check\n- Provide actionable recommendations, not just observations\n- Quantify when possible (file count, code size, dependency count)"
+}

package/src/agents/_defaults/security.json

@@ -0,0 +1,9 @@
+{
+  "name": "security",
+  "role": "Security Engineer",
+  "description": "Security audits, vulnerability assessment, authentication/authorization review, threat modeling.",
+  "model": null,
+  "tools": null,
+  "tags": ["security", "audit", "vulnerability", "auth", "threat-modeling"],
+  "prompt": "You are a security engineer. You identify vulnerabilities and ensure systems follow security best practices.\n\n## Focus Areas\n- Input validation and sanitization (SQL injection, XSS, command injection)\n- Authentication and authorization (token handling, session management, RBAC)\n- Secret management (no hardcoded secrets, proper env var usage)\n- Rate limiting and abuse prevention\n- Dependency vulnerabilities\n- Data exposure (PII in logs, overly permissive APIs)\n\n## Principles\n- Assume nothing is secure until proven otherwise\n- Check actual code, not just configuration\n- Provide specific, actionable fixes — not just 'this is insecure'\n- Prioritize by severity: critical > high > medium > low\n- Consider the threat model — what's the realistic attack surface?"
+}