pi-recurse 0.1.0

package/names.ts

@@ -0,0 +1,62 @@
+/**
+ * Humanized name generation for subagents
+ * Inspired by pi-messenger's generateMemorableName
+ */
+
+const ADJECTIVES = [
+  "swift", "bright", "clever", "steady", "sharp", "keen", "bold", "calm",
+  "rapid", "silent", "fierce", "gentle", "brave", "wise", "nimble", "quick",
+  "sage", "witty", "brisk", "lively", "eager", "alert", "daring", "smooth",
+  "crisp", "fresh", "grand", "noble", "proud", "tough", "warm", "cool",
+  "neat", "tidy", "vivid", "zesty", "agile", "prime", "slick", "snappy"
+];
+
+const NOUNS = [
+  "fox", "owl", "bear", "wolf", "hawk", "lynx", "puma", "stag",
+  "eagle", "raven", "crow", "swan", "crane", "falcon", "badger", "otter",
+  "seal", "orca", "shark", "tiger", "panda", "moose", "elk", "bison",
+  "cobra", "viper", "gecko", "ibex", "koala", "lemur", "llama", "macaw",
+  "newt", "quail", "robin", "snake", "tapir", "urial", "vole", "wren"
+];
+
+/**
+ * Generate a memorable name like "swift-fox" or "bright-owl"
+ */
+export function generateMemorableName(): string {
+  const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+  const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+  return `${adj}-${noun}`;
+}
+
+/**
+ * Generate a name based on task ID (for consistency)
+ */
+export function generateNameForTask(taskId: string): string {
+  // Use hash of taskId to pick consistent name
+  let hash = 0;
+  for (let i = 0; i < taskId.length; i++) {
+    hash = ((hash << 5) - hash) + taskId.charCodeAt(i);
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  const adjIndex = Math.abs(hash) % ADJECTIVES.length;
+  const nounIndex = Math.abs(hash >> 8) % NOUNS.length;
+  return `${ADJECTIVES[adjIndex]}-${NOUNS[nounIndex]}`;
+}
+
+/**
+ * Create a display label for a subagent
+ * Combines humanized name with task ID for clarity
+ */
+export function formatAgentLabel(taskId: string, useHumanized: boolean = true): string {
+  if (!useHumanized) return taskId;
+  
+  // If taskId is already short and readable, use it directly
+  if (taskId.length <= 20 && !taskId.includes("/") && !taskId.includes("\\")) {
+    return taskId;
+  }
+  
+  // Otherwise, generate a memorable name and append short task hint
+  const name = generateNameForTask(taskId);
+  const shortId = taskId.split(/[/\\]/).pop()?.slice(0, 15) || taskId.slice(0, 15);
+  return `${name} (${shortId})`;
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "pi-recurse",
+  "version": "0.1.0",
+  "description": "Recursive agent extension for Pi — spawn subagents programmatically with depth guardrails",
+  "type": "module",
+  "author": "Tom X Nguyen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/pi-recurse.git"
+  },
+  "homepage": "https://github.com/monotykamary/pi-recurse#readme",
+  "bugs": {
+    "url": "https://github.com/monotykamary/pi-recurse/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "recursion",
+    "subagent",
+    "parallel",
+    "divide-and-conquer"
+  ],
+  "files": [
+    "*.ts",
+    "*.js",
+    "*.d.ts",
+    "lib/**",
+    "tests/**",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "lint:dead": "knip --no-gitignore",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "release": "standard-version",
+    "release:dry-run": "standard-version --dry-run",
+    "postinstall": "simple-git-hooks 2>/dev/null || true"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "21.0.1",
+    "@commitlint/config-conventional": "21.0.1",
+    "@types/node": "25.9.1",
+    "@vitest/coverage-v8": "4.1.7",
+    "knip": "6.14.1",
+    "lint-staged": "17.0.5",
+    "prettier": "3.8.3",
+    "simple-git-hooks": "2.13.1",
+    "standard-version": "9.5.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.7"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-tui": ">=0.74.0",
+    "@sinclair/typebox": "0.34.49"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "simple-git-hooks": {
+    "pre-commit": "npx lint-staged",
+    "pre-push": "npm run typecheck && npm run test",
+    "commit-msg": "npx commitlint --edit ${1}"
+  },
+  "lint-staged": {
+    "*.{ts,js,json,md}": [
+      "prettier --write"
+    ]
+  },
+  "overrides": {
+    "brace-expansion": "5.0.6",
+    "fast-xml-builder": "1.2.0",
+    "protobufjs": "8.4.0",
+    "ws": "8.20.1"
+  }
+}

package/tests/lib.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import * as fs from 'node:fs';
+import {
+  getCurrentDepth,
+  getMaxDepth,
+  getCallCount,
+  checkDepthGuard,
+  checkCallGuard,
+  checkTimeoutGuard,
+  checkBudgetGuard,
+  buildChildEnvironment,
+  generateTraceId,
+  getRecursiveSystemPrompt,
+  DEFAULTS,
+} from '../lib.js';
+
+describe('Guardrail utilities', () => {
+  beforeEach(() => {
+    // Clear environment
+    delete process.env.RLM_DEPTH;
+    delete process.env.RLM_MAX_DEPTH;
+    delete process.env.RLM_CALL_COUNT;
+    delete process.env.RLM_MAX_CALLS;
+    delete process.env.RLM_TIMEOUT;
+    delete process.env.RLM_START_TIME;
+    delete process.env.RLM_BUDGET;
+  });
+
+  describe('getCurrentDepth', () => {
+    it('returns 0 when RLM_DEPTH is not set', () => {
+      expect(getCurrentDepth()).toBe(0);
+    });
+
+    it('returns parsed integer from RLM_DEPTH', () => {
+      process.env.RLM_DEPTH = '3';
+      expect(getCurrentDepth()).toBe(3);
+    });
+
+    it('handles negative values', () => {
+      process.env.RLM_DEPTH = '-1';
+      expect(getCurrentDepth()).toBe(-1);
+    });
+  });
+
+  describe('getMaxDepth', () => {
+    it('returns DEFAULTS.MAX_DEPTH when not set', () => {
+      expect(getMaxDepth()).toBe(DEFAULTS.MAX_DEPTH);
+    });
+
+    it('returns parsed RLM_MAX_DEPTH', () => {
+      process.env.RLM_MAX_DEPTH = '5';
+      expect(getMaxDepth()).toBe(5);
+    });
+  });
+
+  describe('checkDepthGuard', () => {
+    it('allows when depth < max', () => {
+      process.env.RLM_DEPTH = '1';
+      process.env.RLM_MAX_DEPTH = '3';
+      const result = checkDepthGuard();
+      expect(result.allowed).toBe(true);
+      expect(result.reason).toBeUndefined();
+    });
+
+    it('blocks when depth >= max', () => {
+      process.env.RLM_DEPTH = '3';
+      process.env.RLM_MAX_DEPTH = '3';
+      const result = checkDepthGuard();
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain('Max depth exceeded');
+    });
+  });
+
+  describe('checkCallGuard', () => {
+    it('allows when calls < limit', () => {
+      process.env.RLM_CALL_COUNT = '50';
+      process.env.RLM_MAX_CALLS = '100';
+      const result = checkCallGuard();
+      expect(result.allowed).toBe(true);
+    });
+
+    it('blocks when calls >= limit', () => {
+      process.env.RLM_CALL_COUNT = '100';
+      process.env.RLM_MAX_CALLS = '100';
+      const result = checkCallGuard();
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain('Max calls exceeded');
+    });
+
+    it('uses env RLM_MAX_CALLS when not provided', () => {
+      process.env.RLM_CALL_COUNT = '99';
+      process.env.RLM_MAX_CALLS = '100';
+      expect(checkCallGuard().allowed).toBe(true);
+    });
+  });
+
+  describe('checkTimeoutGuard', () => {
+    it('allows when elapsed < timeout', () => {
+      process.env.RLM_START_TIME = String(Date.now() - 5000); // 5 seconds ago
+      process.env.RLM_TIMEOUT = '600'; // 10 minutes
+      const result = checkTimeoutGuard();
+      expect(result.allowed).toBe(true);
+    });
+
+    it('blocks when elapsed > timeout', () => {
+      process.env.RLM_START_TIME = String(Date.now() - 700000); // 700 seconds ago
+      process.env.RLM_TIMEOUT = '600'; // 10 minutes
+      const result = checkTimeoutGuard();
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain('Timeout exceeded');
+    });
+  });
+
+  describe('checkBudgetGuard', () => {
+    it('allows with unlimited budget when RLM_BUDGET not set', () => {
+      const result = checkBudgetGuard();
+      expect(result.allowed).toBe(true);
+      expect(result.remaining).toBe(Infinity);
+    });
+
+    it('calculates remaining correctly', () => {
+      process.env.RLM_BUDGET = '1.00';
+      // Note: loadAccumulatedCost will return 0 since no file set
+      const result = checkBudgetGuard();
+      expect(result.allowed).toBe(true);
+      expect(result.remaining).toBeCloseTo(1.0);
+    });
+
+    it('blocks when budget exhausted', () => {
+      process.env.RLM_BUDGET = '0.01';
+      // Mock spent amount by setting cost file via env
+      const costFile = '/tmp/test-cost-' + Date.now();
+      process.env.RLM_COST_FILE = costFile;
+      fs.writeFileSync(costFile, '0.02', 'utf-8');
+
+      try {
+        const result = checkBudgetGuard();
+        expect(result.allowed).toBe(false);
+      } finally {
+        // Cleanup
+        try {
+          fs.unlinkSync(costFile);
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+    });
+  });
+
+  describe('buildChildEnvironment', () => {
+    it('increments depth', () => {
+      process.env.RLM_DEPTH = '2';
+      const env = buildChildEnvironment();
+      expect(env.RLM_DEPTH).toBe('3');
+    });
+
+    it('increments call count', () => {
+      process.env.RLM_CALL_COUNT = '10';
+      const env = buildChildEnvironment();
+      expect(env.RLM_CALL_COUNT).toBe('11');
+    });
+
+    it('preserves trace ID', () => {
+      process.env.RLM_TRACE_ID = 'abc123';
+      const env = buildChildEnvironment();
+      expect(env.RLM_TRACE_ID).toBe('abc123');
+    });
+
+    it('generates new trace ID if not set', () => {
+      delete process.env.RLM_TRACE_ID;
+      const env = buildChildEnvironment();
+      expect(env.RLM_TRACE_ID).toBeDefined();
+      expect(env.RLM_TRACE_ID!.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('generateTraceId', () => {
+    it('returns a non-empty string', () => {
+      const id = generateTraceId();
+      expect(typeof id).toBe('string');
+      expect(id.length).toBeGreaterThan(0);
+    });
+
+    it('returns different values on subsequent calls', () => {
+      const id1 = generateTraceId();
+      const id2 = generateTraceId();
+      expect(id1).not.toBe(id2);
+    });
+  });
+
+  describe('getRecursiveSystemPrompt', () => {
+    it('includes depth information', () => {
+      process.env.RLM_MAX_DEPTH = '5';
+      const basePrompt = 'You are an AI assistant.';
+      const result = getRecursiveSystemPrompt(basePrompt, 2);
+
+      expect(result).toContain('depth 2');
+      expect(result).toContain('RLM_MAX_DEPTH=5');
+      expect(result).toContain(basePrompt);
+    });
+
+    it('includes sub-agent guidance for depth > 0', () => {
+      const result = getRecursiveSystemPrompt('Base.', 1);
+      expect(result).toContain('sub-agents');
+      expect(result).toContain('Prefer **direct answers**');
+    });
+
+    it('includes root-agent guidance for depth 0', () => {
+      const result = getRecursiveSystemPrompt('Base.', 0);
+      expect(result).toContain('root agents');
+      expect(result).toContain('Decompose large tasks');
+    });
+  });
+});

package/types.ts

@@ -0,0 +1,173 @@
+/**
+ * Type definitions for pi-recurse extension
+ */
+
+import type { Static } from '@sinclair/typebox';
+
+export interface GuardrailConfig {
+  /** Maximum recursion depth (0 = root) */
+  maxDepth: number;
+  /** Maximum total recurse invocations across entire tree */
+  maxCalls?: number;
+  /** Maximum wall-clock seconds for entire recursive tree */
+  timeout?: number;
+  /** Maximum dollar spend for entire tree (e.g., 0.50) */
+  budget?: number;
+  /** Disable recurse tool when depth exceeds this threshold */
+  disableToolAtDepth?: number;
+}
+
+export interface RecurseSingleParams {
+  /** The task/prompt to send to the subagent */
+  prompt: string;
+  /** Optional context data to pipe to subagent */
+  context?: string;
+  /** Use session fork to carry conversation history */
+  fork?: boolean;
+}
+
+export interface RecurseParallelParams {
+  /** Multiple tasks to run in parallel */
+  tasks: Array<{
+    /** Unique id for this task */
+    id: string;
+    /** Prompt for this subagent */
+    prompt: string;
+    /** Optional context for this specific task */
+    context?: string;
+  }>;
+  /** Maximum concurrent subagents (default: 4) */
+  concurrency?: number;
+  /** Timeout per task in seconds */
+  timeoutPerTask?: number;
+}
+
+export interface RecurseChainParams {
+  /** Sequential tasks where each receives output from previous */
+  chain: Array<{
+    id: string;
+    prompt: string;
+    /** Template placeholder {previous} will be replaced with prior output */
+  }>;
+}
+
+export type RecurseParams =
+  | ({ mode: 'single' } & RecurseSingleParams)
+  | ({ mode: 'parallel' } & RecurseParallelParams)
+  | ({ mode: 'chain' } & RecurseChainParams);
+
+export interface SubagentProgress {
+  /** Current status */
+  status: 'running' | 'completed' | 'failed';
+  /** Current tool being executed (if any) */
+  currentTool?: string;
+  /** Arguments for current tool */
+  currentToolArgs?: string;
+  /** Recent output lines (last 50) */
+  recentOutput: string[];
+  /** Recent tools executed */
+  recentTools: Array<{ tool: string; args: string; endMs?: number }>;
+  /** Tool call count */
+  toolCount: number;
+  /** Token count (input + output) */
+  tokens: number;
+  /** Duration in milliseconds */
+  durationMs: number;
+}
+
+export interface SubagentUsage {
+  input: number;
+  output: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  cost?: number;
+  turns?: number;
+}
+
+export interface SubagentResult {
+  /** Task id (for parallel/chain modes) */
+  id: string;
+  /** Exit status */
+  success: boolean;
+  /** Subagent response text */
+  output: string;
+  /** Any error message */
+  error?: string;
+  /** Why the subagent stopped (for debugging) - aligns with pi terminology */
+  stopReason?: 'completed' | 'output-stabilization' | 'timeout' | 'error' | 'stopped';
+  /** Usage statistics (if available in JSON mode) */
+  usage?: SubagentUsage;
+  /** Time taken in milliseconds */
+  durationMs: number;
+  /** Progress information (available during streaming) */
+  progress?: SubagentProgress;
+  /** Nested recurse results if this subagent called recurse */
+  children?: RecurseResult;
+  /** Model used for this subagent */
+  model?: string;
+}
+
+/** Tree node for recursive agent visualization */
+export interface RecurseTreeNode {
+  id: string;
+  mode: 'single' | 'parallel' | 'chain';
+  depth: number;
+  status: 'running' | 'completed' | 'failed';
+  stats: {
+    total: number;
+    succeeded: number;
+    failed: number;
+    totalDurationMs: number;
+    totalCost?: number;
+  };
+  children: RecurseTreeNode[];
+  parentId?: string;
+}
+
+export interface RecurseResult {
+  /** Results from all subagents */
+  results: SubagentResult[];
+  /** Aggregated statistics */
+  stats: {
+    total: number;
+    succeeded: number;
+    failed: number;
+    totalDurationMs: number;
+    totalCost?: number;
+  };
+  /** Current recursion depth */
+  depth: number;
+  /** Mode used for this recurse call */
+  mode?: 'single' | 'parallel' | 'chain';
+  /** Parent recurse result (for tree traversal) */
+  parent?: RecurseResult;
+  /** Unique ID for this recurse invocation */
+  invocationId?: string;
+}
+
+export interface RecurseState {
+  /** Current depth (0 = root agent) */
+  depth: number;
+  /** Call count tracker for this session */
+  callCount: number;
+  /** Trace ID linking all recursive sessions */
+  traceId: string;
+  /** Epoch timestamp when root call started */
+  startTime: number;
+  /** Accumulated cost tracking */
+  accumulatedCost: number;
+}
+
+export interface RecurseEnvironment {
+  RLM_DEPTH: string;
+  RLM_MAX_DEPTH: string;
+  RLM_CALL_COUNT: string;
+  RLM_MAX_CALLS?: string;
+  RLM_TIMEOUT?: string;
+  RLM_START_TIME?: string;
+  RLM_BUDGET?: string;
+  RLM_COST_FILE?: string;
+  RLM_TRACE_ID?: string;
+  RLM_CHILD_MODEL?: string;
+  RLM_CHILD_PROVIDER?: string;
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+  },
+});