pi-subagents 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+## [0.3.0] - 2026-01-24
+
+### Added
+- **Full edit mode for chain TUI** - Press `e`, `o`, or `r` to enter a full-screen editor with:
+  - Word wrapping for long text that spans multiple display lines
+  - Scrolling viewport (12 lines visible) with scroll indicators (↑↓)
+  - Full cursor navigation: Up/Down move by display line, Page Up/Down by viewport
+  - Home/End go to start/end of current display line, Ctrl+Home/End for start/end of text
+  - Auto-scroll to keep cursor visible
+  - Esc saves, Ctrl+C discards changes
+
+### Improved
+- **Tool description now explicitly shows the three modes** (SINGLE, CHAIN, PARALLEL) with syntax - helps agents pick the right mode when user says "scout → planner"
+- **Chain execution observability** - Now shows:
+  - Chain visualization with status icons: `✓scout → ●planner` (✓=done, ●=running, ○=pending, ✗=failed) - sequential chains only
+  - Accurate step counter: "step 1/2" instead of misleading "1/1"
+  - Current tool and recent output for running step
+
+## [0.2.0] - 2026-01-24
+
+### Changed
+- **Rebranded to `pi-subagents`** (was `pi-async-subagents`)
+- Now installable via `npx pi-subagents`
+
+### Added
+- Chain TUI now supports editing output paths, reads lists, and toggling progress per step
+- New keybindings: `o` (output), `r` (reads), `p` (progress toggle)
+- Output and reads support full file paths, not just relative to chain_dir
+- Each step shows all editable fields: task, output, reads, progress
+
+### Fixed
+- Chain clarification TUI edit mode now properly re-renders after state changes (was unresponsive)
+- Changed edit shortcut from Tab to 'e' (Tab can be problematic in terminals)
+- Edit mode cursor now starts at beginning of first line for better UX
+- Footer shows context-sensitive keybinding hints for navigation vs edit mode
+- Edit mode is now single-line only (Enter disabled) - UI only displays first line, so multi-line was confusing
+- Added Ctrl+C in edit mode to discard changes (Esc saves, Ctrl+C discards)
+- Footer now shows "Done" instead of "Save" for clarity
+- Absolute paths for output/reads now work correctly (were incorrectly prepended with chainDir)
+
+### Added
+- Parallel-in-chain execution with `{ parallel: [...] }` step syntax for fan-out/fan-in patterns
+- Configurable concurrency and fail-fast options for parallel steps
+- Output aggregation with clear separators (`=== Parallel Task N (agent) ===`) for `{previous}`
+- Namespaced artifact directories for parallel tasks (`parallel-{step}/{index}-{agent}/`)
+- Pre-created progress.md for parallel steps to avoid race conditions
+
+### Changed
+- TUI clarification skipped for chains with parallel steps (runs directly in sync mode)
+- Async mode rejects chains with parallel steps with clear error message
+- Chain completion now returns summary blurb with progress.md and artifacts paths instead of raw output
+
+### Added
+- Live progress display for sync subagents (single and chain modes)
+- Shows current tool, recent output lines, token count, and duration during execution
+- Ctrl+O hint during sync execution to expand full streaming view
+- Throttled updates (150ms) for smoother progress display
+- Updates on tool_execution_start/end events for more responsive feedback
+
+### Fixed
+- Async widget elapsed time now freezes when job completes instead of continuing to count up
+- Progress data now correctly linked to results during execution (was showing "ok" instead of "...")
+
+### Added
+- Extension API support (registerTool) with `subagent` tool name
+- Session logs (JSONL + HTML export) and optional share links via GitHub Gist
+- `share` and `sessionDir` parameters for session retention control
+- Async events: `subagent:started`/`subagent:complete` (legacy events still emitted)
+- Share info surfaced in TUI and async notifications
+- Async observability folder with `status.json`, `events.jsonl`, and `subagent-log-*.md`
+- `subagent_status` tool for inspecting async run state
+- Async TUI widget for background runs
+
+### Changed
+- Parallel mode auto-downgrades to sync when async:true is passed (with note in output)
+- TUI now shows "parallel (no live progress)" label to set expectations
+- Tools passed via agent config can include extension paths (forwarded via `--extension`)
+
+### Fixed
+- Chain mode now sums step durations instead of taking max (was showing incorrect total time)
+- Async notifications no longer leak across pi sessions in different directories
+
+## [0.1.0] - 2026-01-03
+
+Initial release forked from async-subagent example.
+
+### Added
+- Output truncation with configurable byte/line limits
+- Real-time progress tracking (tools, tokens, duration)
+- Debug artifacts (input, output, JSONL, metadata)
+- Session-tied artifact storage for sync mode
+- Per-step duration tracking for chains

package/README.md

@@ -0,0 +1,300 @@
+<p>
+  <img src="banner.png" alt="pi-subagents" width="1100">
+</p>
+
+# pi-subagents
+
+Pi extension for delegating tasks to subagents with chains, parallel execution, TUI clarification, and async support.
+
+## Installation
+
+```bash
+npx pi-subagents
+```
+
+This clones the extension to `~/.pi/agent/extensions/subagent/`. To update, run the same command. To remove:
+
+```bash
+npx pi-subagents --remove
+```
+
+## Features (beyond base)
+
+- **Parallel-in-Chain**: Fan-out/fan-in patterns with `{ parallel: [...] }` steps within chains
+- **Chain Clarification TUI**: Interactive preview/edit of chain templates and behaviors before execution
+- **Agent Frontmatter Extensions**: Agents declare default chain behavior (`output`, `defaultReads`, `defaultProgress`)
+- **Chain Artifacts**: Shared directory at `/tmp/pi-chain-runs/{runId}/` for inter-step files
+- **Solo Agent Output**: Agents with `output` write to temp dir and return path to caller
+- **Live Progress Display**: Real-time visibility during sync execution showing current tool, recent output, tokens, and duration
+- **Output Truncation**: Configurable byte/line limits via `maxOutput`
+- **Debug Artifacts**: Input/output/JSONL/metadata files per task
+- **Session Logs**: JSONL session files with paths shown in output
+- **Async Status Files**: Durable `status.json`, `events.jsonl`, and markdown logs for async runs
+- **Async Widget**: Lightweight TUI widget shows background run progress
+- **Session-scoped Notifications**: Async completions only notify the originating session
+
+## Modes
+
+| Mode | Async Support | Notes |
+|------|---------------|-------|
+| Single | Yes | `{ agent, task }` - agents with `output` write to temp dir |
+| Chain | Yes* | `{ chain: [{agent, task}...] }` with `{task}`, `{previous}`, `{chain_dir}` variables |
+| Parallel | Sync only | `{ tasks: [{agent, task}...] }` - auto-downgrades if async requested |
+
+*Chain defaults to sync with TUI clarification. Use `clarify: false` to enable async (sequential-only chains; parallel-in-chain requires sync mode).
+
+**Chain clarification TUI keybindings:**
+
+*Navigation mode:*
+- `Enter` - Run the chain
+- `Esc` - Cancel
+- `↑↓` - Navigate between steps
+- `e` - Edit task/template
+- `o` - Edit output path
+- `r` - Edit reads list
+- `p` - Toggle progress tracking on/off
+
+*Edit mode (full-screen editor with word wrapping):*
+- `Esc` - Save changes and exit
+- `Ctrl+C` - Discard changes and exit
+- `←→` - Move cursor left/right
+- `↑↓` - Move cursor up/down by display line (auto-scrolls)
+- `Page Up/Down` or `Shift+↑↓` - Move cursor by viewport (12 lines)
+- `Home/End` - Start/end of current display line
+- `Ctrl+Home/End` - Start/end of text
+
+## Agent Frontmatter
+
+Agents can declare default chain behavior in their frontmatter:
+
+```yaml
+---
+name: scout
+description: Fast codebase recon
+tools: read, grep, find, ls, bash
+model: claude-haiku-4-5
+output: context.md           # writes to {chain_dir}/context.md
+defaultReads: context.md     # comma-separated files to read
+defaultProgress: true        # maintain progress.md
+interactive: true            # (parsed but not enforced in v1)
+---
+```
+
+**Resolution priority:** step override > agent frontmatter > disabled
+
+## Usage
+
+**subagent tool:**
+```typescript
+// Single agent
+{ agent: "worker", task: "refactor auth" }
+{ agent: "scout", task: "find todos", maxOutput: { lines: 1000 } }
+{ agent: "scout", task: "investigate", output: false }  // disable file output
+
+// Parallel (sync only)
+{ tasks: [{ agent: "scout", task: "a" }, { agent: "scout", task: "b" }] }
+
+// Chain with TUI clarification (default)
+{ chain: [
+  { agent: "scout", task: "Gather context for auth refactor" },
+  { agent: "planner" },  // task defaults to {previous}
+  { agent: "worker" },   // uses agent defaults for reads/progress
+  { agent: "reviewer" }
+]}
+
+// Chain without TUI (enables async)
+{ chain: [...], clarify: false, async: true }
+
+// Chain with behavior overrides
+{ chain: [
+  { agent: "scout", task: "find issues", output: false },  // text-only, no file
+  { agent: "worker", progress: false }  // disable progress tracking
+]}
+
+// Chain with parallel step (fan-out/fan-in)
+{ chain: [
+  { agent: "scout", task: "Gather context for the codebase" },
+  { parallel: [
+    { agent: "worker", task: "Implement auth based on {previous}" },
+    { agent: "worker", task: "Implement API based on {previous}" }
+  ]},
+  { agent: "reviewer", task: "Review all changes from {previous}" }
+]}
+
+// Parallel step with options
+{ chain: [
+  { agent: "scout", task: "Find all modules" },
+  { parallel: [
+    { agent: "worker", task: "Refactor module A" },
+    { agent: "worker", task: "Refactor module B" },
+    { agent: "worker", task: "Refactor module C" }
+  ], concurrency: 2, failFast: true }  // limit concurrency, stop on first failure
+]}
+```
+
+**subagent_status tool:**
+```typescript
+{ id: "a53ebe46" }
+{ dir: "/tmp/pi-async-subagent-runs/a53ebe46-..." }
+```
+
+## Parameters
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `agent` | string | - | Agent name (single mode) |
+| `task` | string | - | Task string (single mode) |
+| `output` | `string \| false` | agent default | Override output file for single agent |
+| `tasks` | `{agent, task, cwd?}[]` | - | Parallel tasks (sync only) |
+| `chain` | ChainItem[] | - | Sequential steps with behavior overrides (see below) |
+| `clarify` | boolean | true (chains) | Show TUI to preview/edit chain; implies sync mode |
+| `agentScope` | `"user" \| "project" \| "both"` | `user` | Agent discovery scope |
+| `async` | boolean | false | Background execution (requires `clarify: false` for chains) |
+| `cwd` | string | - | Override working directory |
+| `maxOutput` | `{bytes?, lines?}` | 200KB, 5000 lines | Truncation limits for final output |
+| `artifacts` | boolean | true | Write debug artifacts |
+| `includeProgress` | boolean | false | Include full progress in result |
+| `share` | boolean | true | Create shareable session log |
+| `sessionDir` | string | temp | Directory to store session logs |
+
+**ChainItem** can be either a sequential step or a parallel step:
+
+*Sequential step fields:*
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `agent` | string | required | Agent name |
+| `task` | string | `{task}` or `{previous}` | Task template (required for first step) |
+| `cwd` | string | - | Override working directory |
+| `output` | `string \| false` | agent default | Override output filename or disable |
+| `reads` | `string[] \| false` | agent default | Override files to read from chain dir |
+| `progress` | boolean | agent default | Override progress.md tracking |
+
+*Parallel step fields:*
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `parallel` | ParallelTask[] | required | Array of tasks to run concurrently |
+| `concurrency` | number | 4 | Max concurrent tasks |
+| `failFast` | boolean | false | Stop remaining tasks on first failure |
+
+*ParallelTask fields:* (same as sequential step)
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `agent` | string | required | Agent name |
+| `task` | string | `{previous}` | Task template |
+| `cwd` | string | - | Override working directory |
+| `output` | `string \| false` | agent default | Override output (namespaced to parallel-N/M-agent/) |
+| `reads` | `string[] \| false` | agent default | Override files to read |
+| `progress` | boolean | agent default | Override progress tracking |
+
+Status tool:
+
+| Tool | Description |
+|------|-------------|
+| `subagent_status` | Inspect async run status by id or dir |
+
+## Chain Variables
+
+Templates support three variables:
+
+| Variable | Description |
+|----------|-------------|
+| `{task}` | Original task from first step (use in subsequent steps) |
+| `{previous}` | Output from prior step (or aggregated outputs from parallel step) |
+| `{chain_dir}` | Path to chain artifacts directory |
+
+**Parallel output aggregation:** When a parallel step completes, all outputs are concatenated with clear separators:
+
+```
+=== Parallel Task 1 (worker) ===
+[output from first task]
+
+=== Parallel Task 2 (worker) ===
+[output from second task]
+```
+
+This aggregated output becomes `{previous}` for the next step.
+
+## Chain Directory
+
+Each chain run creates `/tmp/pi-chain-runs/{runId}/` containing:
+- `context.md` - Scout/context-builder output
+- `plan.md` - Planner output  
+- `progress.md` - Worker/reviewer shared progress
+- `parallel-{stepIndex}/` - Subdirectories for parallel step outputs
+  - `0-{agent}/output.md` - First parallel task output
+  - `1-{agent}/output.md` - Second parallel task output
+- Additional files as written by agents
+
+Directories older than 24 hours are cleaned up on extension startup.
+
+## Artifacts
+
+Location: `{sessionDir}/subagent-artifacts/` or `/tmp/pi-subagent-artifacts/`
+
+Files per task:
+- `{runId}_{agent}_input.md` - Task prompt
+- `{runId}_{agent}_output.md` - Full output (untruncated)
+- `{runId}_{agent}.jsonl` - Event stream (sync only)
+- `{runId}_{agent}_meta.json` - Timing, usage, exit code
+
+## Session Logs
+
+Session files (JSONL) are stored under a per-run session dir (temp by default). The session file path is shown in output. Set `sessionDir` to keep session logs outside `/tmp`.
+
+## Live progress (sync mode)
+
+During sync execution, the collapsed view shows:
+- Header: `... chain 1/2 | 8 tools, 1.4k tok, 38s`
+- Chain visualization with status: `✓scout → ●planner` (✓=done, ●=running, ○=pending, ✗=failed)
+- Current tool: `> read: packages/tui/src/...`
+- Recent output lines (last 2-3 lines)
+- Hint: `(ctrl+o to expand)`
+
+Press **Ctrl+O** to expand the full streaming view with complete output per step.
+
+> **Note:** Chain visualization is only shown for sequential chains. Chains with parallel steps show the header and progress but not the step-by-step visualization.
+
+## Async observability
+
+Async runs write a dedicated observability folder:
+
+```
+/tmp/pi-async-subagent-runs/<id>/
+  status.json
+  events.jsonl
+  subagent-log-<id>.md
+```
+
+`status.json` is the source of truth for async progress and powers the TUI widget. If you already use
+`/status <id>` you can keep doing that; otherwise use:
+
+```typescript
+subagent_status({ id: "<id>" })
+subagent_status({ dir: "/tmp/pi-async-subagent-runs/<id>" })
+```
+
+## Events
+
+Async events:
+- `subagent:started`
+- `subagent:complete`
+
+Legacy events (still emitted):
+- `subagent_enhanced:started`
+- `subagent_enhanced:complete`
+
+## Files
+
+```
+├── index.ts           # Main extension (registerTool)
+├── agents.ts          # Agent discovery + frontmatter parsing
+├── settings.ts        # Chain behavior resolution, templates, chain dir
+├── chain-clarify.ts   # TUI component for chain clarification
+├── artifacts.ts       # Artifact management
+├── types.ts           # Shared types
+├── subagent-runner.ts # Async runner
+└── notify.ts          # Async completion notifications
+```

package/agents.ts

@@ -0,0 +1,172 @@
+/**
+ * Agent discovery and configuration
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export type AgentScope = "user" | "project" | "both";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	systemPrompt: string;
+	source: "user" | "project";
+	filePath: string;
+	// Chain behavior fields
+	output?: string;
+	defaultReads?: string[];
+	defaultProgress?: boolean;
+	interactive?: boolean;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+	const frontmatter: Record<string, string> = {};
+	const normalized = content.replace(/\r\n/g, "\n");
+
+	if (!normalized.startsWith("---")) {
+		return { frontmatter, body: normalized };
+	}
+
+	const endIndex = normalized.indexOf("\n---", 3);
+	if (endIndex === -1) {
+		return { frontmatter, body: normalized };
+	}
+
+	const frontmatterBlock = normalized.slice(4, endIndex);
+	const body = normalized.slice(endIndex + 4).trim();
+
+	for (const line of frontmatterBlock.split("\n")) {
+		const match = line.match(/^([\w-]+):\s*(.*)$/);
+		if (match) {
+			let value = match[2].trim();
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+			frontmatter[match[1]] = value;
+		}
+	}
+
+	return { frontmatter, body };
+}
+
+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(content);
+
+		if (!frontmatter.name || !frontmatter.description) {
+			continue;
+		}
+
+		const tools = frontmatter.tools
+			?.split(",")
+			.map((t) => t.trim())
+			.filter(Boolean);
+
+		// Parse defaultReads as comma-separated list (like tools)
+		const defaultReads = frontmatter.defaultReads
+			?.split(",")
+			.map((f) => f.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,
+			// Chain behavior fields
+			output: frontmatter.output,
+			defaultReads: defaultReads && defaultReads.length > 0 ? defaultReads : undefined,
+			defaultProgress: frontmatter.defaultProgress === "true",
+			interactive: frontmatter.interactive === "true",
+		});
+	}
+
+	return agents;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, ".pi", "agents");
+		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(os.homedir(), ".pi", "agent", "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "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 };
+}
+
+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/artifacts.ts

@@ -0,0 +1,70 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ArtifactPaths } from "./types.js";
+
+const TEMP_ARTIFACTS_DIR = "/tmp/pi-subagent-artifacts";
+const CLEANUP_MARKER_FILE = ".last-cleanup";
+
+export function getArtifactsDir(sessionFile: string | null): string {
+	if (sessionFile) {
+		const sessionDir = path.dirname(sessionFile);
+		return path.join(sessionDir, "subagent-artifacts");
+	}
+	return TEMP_ARTIFACTS_DIR;
+}
+
+export function getArtifactPaths(artifactsDir: string, runId: string, agent: string, index?: number): ArtifactPaths {
+	const suffix = index !== undefined ? `_${index}` : "";
+	const safeAgent = agent.replace(/[^\w.-]/g, "_");
+	const base = `${runId}_${safeAgent}${suffix}`;
+	return {
+		inputPath: path.join(artifactsDir, `${base}_input.md`),
+		outputPath: path.join(artifactsDir, `${base}_output.md`),
+		jsonlPath: path.join(artifactsDir, `${base}.jsonl`),
+		metadataPath: path.join(artifactsDir, `${base}_meta.json`),
+	};
+}
+
+export function ensureArtifactsDir(dir: string): void {
+	fs.mkdirSync(dir, { recursive: true });
+}
+
+export function writeArtifact(filePath: string, content: string): void {
+	fs.writeFileSync(filePath, content, "utf-8");
+}
+
+export function writeMetadata(filePath: string, metadata: object): void {
+	fs.writeFileSync(filePath, JSON.stringify(metadata, null, 2), "utf-8");
+}
+
+export function appendJsonl(filePath: string, line: string): void {
+	fs.appendFileSync(filePath, `${line}\n`);
+}
+
+export function cleanupOldArtifacts(dir: string, maxAgeDays: number): void {
+	if (!fs.existsSync(dir)) return;
+
+	const markerPath = path.join(dir, CLEANUP_MARKER_FILE);
+	const now = Date.now();
+
+	if (fs.existsSync(markerPath)) {
+		const stat = fs.statSync(markerPath);
+		if (now - stat.mtimeMs < 24 * 60 * 60 * 1000) return;
+	}
+
+	const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+	const cutoff = now - maxAgeMs;
+
+	for (const file of fs.readdirSync(dir)) {
+		if (file === CLEANUP_MARKER_FILE) continue;
+		const filePath = path.join(dir, file);
+		try {
+			const stat = fs.statSync(filePath);
+			if (stat.mtimeMs < cutoff) {
+				fs.unlinkSync(filePath);
+			}
+		} catch {}
+	}
+
+	fs.writeFileSync(markerPath, String(now));
+}