pi-recurse 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-03-24
+
+### Added
+- Initial implementation of `pi-recurse` extension
+- Three execution modes: `single`, `parallel`, and `chain`
+- Programmatic parallel spawning (no LLM involvement in loop)
+- Depth-based guardrails (RLM_MAX_DEPTH, RLM_DEPTH)
+- Call count tracking (RLM_MAX_CALLS)
+- Timeout enforcement (RLM_TIMEOUT)
+- Budget tracking (RLM_BUDGET)
+- Tool disabling at configurable depth threshold
+- System prompt injection via `before_agent_start`
+- Status bar indicator showing current depth
+- Custom tool rendering for TUI
+- `/recurse-status` command for debugging
+- Comprehensive test suite

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tom X Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+<div align="center">
+
+# 🔁 pi-recurse
+
+**Programmatic recursive subagent spawning for [pi](https://github.com/earendil-works/pi-coding-agent)**
+
+_LLM makes ONE tool call, extension code handles parallel spawning and result aggregation._
+
+[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+</div>
+
+---
+
+This project is the spiritual successor to **[ypi](https://github.com/rawwerks/ypi)** by [@rawwerks](https://github.com/rawwerks), originally created as a bash wrapper around Pi that enabled recursive LLM calls with guardrails.
+
+**Why the conversion?** The original `ypi` proved that recursive subagents could work effectively, but required the LLM to generate bash scripts for parallelization. By converting to a proper Pi extension, `pi-recurse` achieves:
+
+- **True programmatic looping** — parallel execution happens in TypeScript code, not bash generated by the LLM
+- **Better integration** — hot-reload with `/reload`, automatic tool discovery, native Pi packaging
+- **Structured results** — full TypeScript types instead of bash string manipulation
+- **Single entry point** — just `pi`, no wrapper scripts needed
+
+Thank you to the original `ypi` for pioneering the concept of depth-limited recursive LLM calls in a coding agent context.
+
+---
+
+## Installation
+
+### Via Git URL (Recommended for now)
+
+```bash
+pi install https://github.com/monotykamary/pi-recurse
+```
+
+### Via npm (when published)
+
+```bash
+pi install pi-recurse
+```
+
+### Local Development
+
+```bash
+git clone https://github.com/monotykamary/pi-recurse.git
+cd pi-recurse
+pi install .
+```
+
+The extension will be auto-discovered by Pi on next start, or use `/reload` to load it immediately.
+
+---
+
+## Usage
+
+The extension adds a `recurse` tool to Pi, enabling three execution modes:
+
+### Single Mode — One-off delegation
+
+```typescript
+recurse({
+  mode: 'single',
+  prompt: 'Analyze the error handling in src/auth.ts',
+  context: fileContent, // optional context to pipe
+});
+```
+
+### Parallel Mode — Batch processing
+
+```typescript
+recurse({
+  mode: 'parallel',
+  tasks: [
+    { id: 'auth', prompt: 'Review auth module' },
+    { id: 'db', prompt: 'Review database layer' },
+    { id: 'api', prompt: 'Review API routes' },
+  ],
+  concurrency: 3,
+  timeoutPerTask: 120,
+});
+```
+
+**Key advantage:** All 3 subagents spawn from a **single LLM tool call**. The extension handles `Promise.all()` style concurrency internally — no autoregressive steps between spawns.
+
+### Chain Mode — Sequential dependencies
+
+```typescript
+recurse({
+  mode: 'chain',
+  chain: [
+    { id: 'read', prompt: 'Read README.md and summarize' },
+    { id: 'analyze', prompt: 'Given this summary: {previous} — identify risks' },
+    { id: 'plan', prompt: 'Given these risks: {previous} — suggest mitigations' },
+  ],
+});
+```
+
+---
+
+## Guardrails
+
+Environment variables control recursion limits across the entire call tree:
+
+| Variable              | Default | Description                          |
+| --------------------- | ------- | ------------------------------------ |
+| `RLM_MAX_DEPTH`       | 3       | Maximum recursion depth (0 = root)   |
+| `RLM_MAX_CALLS`       | 100     | Maximum total recurse invocations    |
+| `RLM_TIMEOUT`         | 600     | Wall-clock seconds for entire tree   |
+| `RLM_BUDGET`          | —       | Max dollar spend (e.g., `0.50`)      |
+| `RLM_CHILD_MODEL`     | —       | Model override for depth > 0         |
+| `RLM_DISABLE_TOOL_AT` | 3       | Disable recurse tool at this depth   |
+| `RLM_TRACE_ID`        | auto    | Links all sessions in recursive tree |
+
+At deep depths (≥ `RLM_DISABLE_TOOL_AT`), the recurse tool automatically disables itself and guides agents to work directly instead of delegating.
+
+---
+
+## Architecture: From Bash to Extension
+
+### Original ypi (Bash Wrapper)
+
+```
+ypi "analyze this codebase"
+    ↓
+Launcher sets env, execs pi with custom system prompt
+    ↓
+LLM generates bash loop for parallel tasks:
+    for f in $(find src -name "*.ts"); do
+        rlm_query --async "Review $f"
+    done
+    ↓
+Wait on sentinel files, aggregate in bash
+```
+
+**Limitation:** The LLM had to generate the loop structure, and parallelization required autoregressive generation of bash code.
+
+### pi-recurse (Pi Extension)
+
+```
+pi (with pi-recurse extension loaded)
+    ↓
+LLM calls once: recurse({mode: "parallel", tasks: [...]})
+    ↓
+Extension execute() runs in Node.js:
+    ├── Check guardrails (depth, budget, timeout)
+    ├── runParallel(tasks, spawnFn, concurrency)
+    │   └── Promise.all(concurrent batches)
+    ├── Aggregate structured results
+    └── Return {results, stats, depth}
+    ↓
+LLM receives aggregated data, continues reasoning
+```
+
+**Advantage:** Parallel execution happens in **code**, not in LLM-generated bash. One tool call → many subagents → aggregated result.
+
+---
+
+## Comparison: ypi vs pi-recurse
+
+| Feature               | ypi (Wrapper)            | pi-recurse (Extension)            |
+| --------------------- | ------------------------ | --------------------------------- |
+| Entry point           | `ypi "prompt"`           | `pi` (extension auto-loaded)      |
+| Parallel spawning     | LLM writes bash loop     | **Code executes `Promise.all()`** |
+| Result aggregation    | Bash string manipulation | TypeScript structured objects     |
+| Hot reload            | Restart ypi process      | `/reload` in pi                   |
+| Distribution          | npm global bin           | `pi install` / git URL            |
+| Extension integration | Manual env/PATH setup    | Native auto-discovery             |
+| Tool disabling        | Manual depth checks      | Automatic at configured depth     |
+| Status visibility     | Footer via ypi.ts        | Native Pi status bar              |
+
+---
+
+## Development
+
+```bash
+# Clone and install dependencies
+git clone https://github.com/monotykamary/pi-recurse.git
+cd pi-recurse
+npm install
+
+# Run tests
+npm test
+
+# Type check
+npm run typecheck
+
+# Build (optional - jiti handles TypeScript at runtime)
+npm run build
+```
+
+### Testing the Extension
+
+```bash
+# Install locally
+pi install .
+
+# Or test without installing
+pi -e ./index.ts
+
+# In pi, test recursion
+/recurse-status
+recurse({mode: "single", prompt: "What is 2+2?"})
+```
+
+---
+
+## Design Principles
+
+1. **Single tool call, parallel execution** — The LLM describes intent; code handles concurrency
+2. **Depth-aware degradation** — At deep levels, disable recursion to prevent runaway costs
+3. **Structured over stringly** — Full TypeScript types for inputs and outputs
+4. **Guardrails in code** — Budget, timeout, depth checked programmatically
+5. **Pi-native integration** — Use Pi's extension API, not wrapper scripts
+
+---
+
+## Related Projects
+
+- **[ypi](https://github.com/rawwerks/ypi)** — The original bash wrapper that inspired this extension
+- **[pi-messenger](https://github.com/monotykamary/pi-messenger-swarm)** — Multi-agent coordination for Pi (another extension)
+- **[pi](https://github.com/badlogic/pi-mono)** — The Pi coding agent itself
+
+## License
+
+MIT — See [LICENSE](LICENSE) for details.

package/formatters.ts

@@ -0,0 +1,295 @@
+/**
+ * Formatting helpers for subagent progress display
+ * Following pi-subagents patterns
+ */
+
+/**
+ * Format token count with k/M suffixes
+ */
+export function formatTokens(tokens: number): string {
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`;
+  if (tokens >= 1_000) return `${(tokens / 1_000).toFixed(1)}k`;
+  return `${tokens}`;
+}
+
+/**
+ * Format duration in ms to human readable
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  const mins = Math.floor(ms / 60_000);
+  const secs = ((ms % 60_000) / 1000).toFixed(0);
+  return `${mins}m${secs}s`;
+}
+
+/**
+ * Format usage info line
+ */
+export function formatUsage(usage?: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number; cost?: number }): string {
+  if (!usage) return "";
+  const parts: string[] = [];
+  if (usage.input || usage.output) {
+    parts.push(`${formatTokens(usage.input || 0)}↑ ${formatTokens(usage.output || 0)}↓`);
+  }
+  if (usage.cacheRead) parts.push(`${formatTokens(usage.cacheRead)}↺`);
+  if (usage.cacheWrite) parts.push(`${formatTokens(usage.cacheWrite)}↻`);
+  if (usage.cost !== undefined && usage.cost > 0) {
+    parts.push(`$${usage.cost.toFixed(4)}`);
+  }
+  return parts.join(" · ") || "";
+}
+
+import { formatAgentLabel } from "./names.js";
+import type { RecurseResult, RecurseTreeNode, SubagentResult } from "./types.js";
+
+/**
+ * Truncate text to max length with ellipsis
+ * Uses Intl.Segmenter for proper Unicode handling
+ */
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+export function truncLine(text: string, maxWidth: number): string {
+  if (text.length <= maxWidth) return text;
+  
+  let result = "";
+  let count = 0;
+  for (const seg of segmenter.segment(text)) {
+    if (count >= maxWidth - 1) {
+      return result + "…";
+    }
+    result += seg.segment;
+    count++;
+  }
+  return result;
+}
+
+/**
+ * Get status icon - uses distinct Unicode symbols instead of confusing "..."
+ */
+export function getStatusIcon(status: "running" | "completed" | "failed" | undefined): string {
+  switch (status) {
+    case "running": return "▶";  // Play icon - clearly indicates active
+    case "completed": return "✓";  // Checkmark
+    case "failed": return "✗";  // X mark
+    default: return "○";  // Circle for pending/unknown
+  }
+}
+
+/**
+ * Build a tree structure from a RecurseResult for visualization
+ */
+export function buildRecurseTree(result: RecurseResult, mode: "single" | "parallel" | "chain", parentId?: string): RecurseTreeNode {
+  const invocationId = result.invocationId || Math.random().toString(36).substring(2, 8);
+  
+  const node: RecurseTreeNode = {
+    id: invocationId,
+    mode,
+    depth: result.depth,
+    status: result.stats.failed === 0 ? "completed" : (result.stats.failed < result.stats.total ? "running" : "failed"),
+    stats: result.stats,
+    children: [],
+    parentId,
+  };
+  
+  // Build child nodes from subagent results that have their own recurse calls
+  for (const subagent of result.results) {
+    if (subagent.children) {
+      const childNode = buildRecurseTree(subagent.children, subagent.children.mode || "single", invocationId);
+      node.children.push(childNode);
+    }
+  }
+  
+  return node;
+}
+
+/**
+ * Render a recurse tree with ASCII/Unicode tree drawing characters
+ */
+export function renderRecurseTree(
+  node: RecurseTreeNode,
+  maxWidth: number = 100,
+  prefix: string = "",
+  isLast: boolean = true,
+  isRoot: boolean = true
+): string[] {
+  const lines: string[] = [];
+  
+  // Build the status line
+  const icon = getStatusIcon(node.status);
+  const modeLabel = node.mode;
+  const stats = `${node.stats.succeeded}/${node.stats.total}`;
+  const cost = node.stats.totalCost ? ` · $${node.stats.totalCost.toFixed(4)}` : "";
+  const duration = formatDuration(node.stats.totalDurationMs);
+  
+  // Tree drawing characters
+  const branch = isRoot ? "" : (isLast ? "└─ " : "├─ ");
+  const indent = isRoot ? "" : prefix;
+  
+  const line = `${indent}${branch}${icon} ${modeLabel} [${stats}]${cost} · ${duration} (depth ${node.depth})`;
+  lines.push(truncLine(line, maxWidth));
+  
+  // Render children
+  if (node.children.length > 0) {
+    const childPrefix = isRoot ? "" : prefix + (isLast ? "   " : "│  ");
+    
+    for (let i = 0; i < node.children.length; i++) {
+      const child = node.children[i];
+      const isLastChild = i === node.children.length - 1;
+      const childLines = renderRecurseTree(child, maxWidth, childPrefix, isLastChild, false);
+      lines.push(...childLines);
+    }
+  }
+  
+  return lines;
+}
+
+/**
+ * Format a flat list of recurse results into a forest (multiple trees)
+ */
+export function renderRecurseForest(
+  results: RecurseResult[],
+  modes: ("single" | "parallel" | "chain")[],
+  maxWidth: number = 100
+): string {
+  const allLines: string[] = [];
+  
+  for (let i = 0; i < results.length; i++) {
+    const tree = buildRecurseTree(results[i], modes[i]);
+    const lines = renderRecurseTree(tree, maxWidth);
+    allLines.push(...lines);
+    
+    // Add separator between trees
+    if (i < results.length - 1) {
+      allLines.push("");
+    }
+  }
+  
+  return allLines.join("\n");
+}
+
+/**
+ * Count total nodes in a recurse tree (for stats)
+ */
+export function countTreeNodes(node: RecurseTreeNode): number {
+  let count = 1; // This node
+  for (const child of node.children) {
+    count += countTreeNodes(child);
+  }
+  return count;
+}
+
+/**
+ * Find the deepest depth in a recurse tree
+ */
+export function getTreeMaxDepth(node: RecurseTreeNode): number {
+  if (node.children.length === 0) {
+    return node.depth;
+  }
+  let maxChildDepth = node.depth;
+  for (const child of node.children) {
+    maxChildDepth = Math.max(maxChildDepth, getTreeMaxDepth(child));
+  }
+  return maxChildDepth;
+}
+
+/**
+ * Render subagent progress like pi-subagents
+ */
+export interface ProgressData {
+  status: "running" | "completed" | "failed";
+  currentTool?: string;
+  currentToolArgs?: string;
+  recentTools?: Array<{ tool: string; args: string; endMs?: number }>;
+  recentOutput?: string[];
+  toolCount: number;
+  tokens: number;
+  durationMs: number;
+}
+
+/**
+ * Format progress line: "... | 5 tools, 12.3k tok, 2.4s"
+ */
+export function formatProgressLine(data: ProgressData): string {
+  const parts: string[] = [];
+  if (data.toolCount > 0) parts.push(`${data.toolCount} tools`);
+  if (data.tokens > 0) parts.push(`${formatTokens(data.tokens)} tok`);
+  if (data.durationMs > 0) parts.push(`${formatDuration(data.durationMs)}`);
+  return parts.join(", ");
+}
+
+/**
+ * Render full subagent status with multi-line output
+ * Mimics pi-subagents render.ts output
+ */
+export function renderSubagentStatus(
+  id: string,
+  data: { output: string; progress?: ProgressData },
+  maxWidth: number = 100,
+  useHumanizedName: boolean = true
+): string[] {
+  const lines: string[] = [];
+  const p = data.progress;
+  
+  // Use humanized name for display
+  const displayName = formatAgentLabel(id, useHumanizedName);
+  
+  // Status line: "▶ swift-fox (package.json) | 5 tools, 12.3k tok, 2.4s"
+  const icon = getStatusIcon(p?.status);
+  const metrics = p ? formatProgressLine(p) : "";
+  const header = metrics ? `${icon} ${displayName} | ${metrics}` : `${icon} ${displayName}`;
+  lines.push(truncLine(header, maxWidth));
+  
+  if (p?.status === "running") {
+    // Current tool line: "> read: path: "file.ts"..."
+    if (p.currentTool) {
+      const args = p.currentToolArgs || "";
+      const toolLine = args ? `> ${p.currentTool}: ${truncLine(args, maxWidth - 20)}` : `> ${p.currentTool}`;
+      lines.push(toolLine);
+    }
+    
+    // Recent tools (last 3)
+    if (p.recentTools?.length) {
+      for (const t of p.recentTools.slice(-3)) {
+        const argsPreview = truncLine(t.args, maxWidth - 30);
+        lines.push(`  ${t.tool}: ${argsPreview}`);
+      }
+    }
+    
+    // Recent output (last 5 lines)
+    if (p.recentOutput?.length) {
+      for (const line of p.recentOutput.slice(-5)) {
+        lines.push(`  ${truncLine(line, maxWidth - 4)}`);
+      }
+    }
+  }
+  
+  // If no progress detail but have output, show output preview
+  if ((!p || p.status !== "running") && data.output) {
+    const outputLines = data.output.split("\n").filter(l => l.trim()).slice(-3);
+    for (const line of outputLines) {
+      lines.push(`  ${truncLine(line, maxWidth - 4)}`);
+    }
+  }
+  
+  return lines;
+}
+
+/**
+ * Render parallel task status list
+ */
+export function renderParallelStatus(
+  taskProgress: Map<string, { output: string; progress?: ProgressData }>,
+  maxWidth: number = 100,
+  useHumanizedNames: boolean = true
+): string {
+  const allLines: string[] = [];
+  
+  for (const [id, data] of taskProgress) {
+    const taskLines = renderSubagentStatus(id, data, maxWidth, useHumanizedNames);
+    allLines.push(...taskLines);
+    allLines.push(""); // Blank line between tasks
+  }
+  
+  return allLines.join("\n").trim();
+}