pi-agent-squad 0.7.0

package/README.md

@@ -0,0 +1,205 @@
+# subagents — generic multi-agent messaging extension
+
+> Status: fully implemented and verified end-to-end
+> Design principle: **generic messaging at the bottom layer, identity defined by prompts**
+
+## Install
+
+```bash
+pi install npm:pi-agent-squad
+```
+
+Reload Pi after installation:
+
+```text
+/reload
+```
+
+## Core design
+
+**Bottom layer (generic, no identity concept)**:
+- Two parties communicate: `main` (the main agent) and any subagent.
+- Message primitives: `send_message` / `read_inbox` / `reply_message`.
+- Routing: `to=main` -> inject into the main session; `to=<subagent>` -> forward to its resident process.
+- File channel + polling (no process pipes, no identity required).
+
+**Identity (prompt layer)**:
+- `agents/*.md`: defines each subagent's identity, duties, model, tools (e.g. planner/reviewer/actor).
+- `orchestrator.md`: defines the main agent's outcome-oriented Discover → Decide → Execute → Verify workflow (optional injection).
+- The bottom layer never cares who is who — it only delivers messages.
+
+## Messaging tools (shared by all agents)
+
+| Tool | Purpose |
+|---|---|
+| `send_message({to, content, wait, timeoutSeconds?})` | Send a message to any target; wait=true blocks for and returns the reply |
+| `read_inbox()` | Read messages others sent you |
+| `reply_message({message_id, content})` | Reply to a received message |
+
+`to` is either `main` (the main agent) or any subagent name.
+
+## Features
+
+- **Delegation**: `subagent` tool (sync / background `async:true`); background results are injected into the main session when done.
+- **Real-time two-way**: subagent<->main and subagent<->subagent, via file channel + resident RPC process pool.
+- **Non-blocking**: background tasks do not occupy the main session.
+- **Default safety gate**: unless the current user explicitly requests subagent involvement or `/orchestrate` is enabled, the main-agent system prompt forbids subagent delegation.
+- **Bounded execution**: one-shot and resident tasks have configurable timeouts (default 6 hours, maximum 3 days); omit `timeoutSeconds` unless the user explicitly requested a time. Timed-out or crashed resident processes are discarded before the next task.
+- **Reliable messaging**: `send_message(wait=true)` waits for and returns the target's actual reply; `wait=false` remains fire-and-forget.
+- **Deadlock prevention**: synchronous wait cycles such as `main -> planner -> main`, self-messages, and `actor -> reviewer -> actor` are detected and rejected immediately with a recovery hint.
+- **Retryable routing**: requests are marked delivered only after successful injection/routing; transient delivery failures are retried instead of being silently stranded until timeout.
+- **Compact transcript events**: incoming messages and background completion/failure results use transparent, icon-led Markdown renderers instead of the default colored custom-message box or a synthetic user message.
+- **Session isolation**: message channels use the real pi session id instead of a shared `ephemeral` directory.
+- **Running widget**: while subagents are active, a compact widget above the editor shows their names, elapsed times, execution mode, and a shortened task/message summary; it disappears automatically when the last activity finishes.
+- **Session navigation**: Shift+Up/Down selects a running subagent, Enter opens the exact RPC session behind that activity, and Esc returns to main while the subagent keeps running.
+
+## Running subagent widget
+
+The TUI-only widget is installed above the editor while at least one subagent is running:
+
+```text
+ ⠋ Subagents · 2 running · ⇧+↑/↓ select · Enter open
+ › actor [bg] · 12s · Implement the login flow and run tests…
+ └ reviewer [msg] · 4s · Review the current changes…
+```
+
+- No suffix: synchronous `subagent` task.
+- `[bg]`: background `subagent(async=true)` task.
+- `[msg]`: resident task started through `send_message` or subagent-to-subagent routing.
+- At most four activities are shown; additional concurrency is summarized as `… +N more`, and the visible window follows the selected activity.
+- Task summaries are dimmed and capped at 40 terminal columns so they do not dominate the widget.
+- The title includes dim keyboard hints. Before selection it shows
+  `⇧+↑/↓ select · Enter open`; with an active selection it changes to
+  `⇧+↑/↓ move · Enter open · Esc clear`. Narrow terminals progressively shorten
+  the hint and hide it when the title itself needs the space.
+- The elapsed time and spinner refresh once per second while work is active, avoiding hot-loop rerenders on very large sessions.
+- Normal completion, failure, timeout, cancellation, crash, and session shutdown all remove the matching activity. The widget itself is removed when no activities remain.
+- JSON/RPC/print modes do not install the widget.
+
+### Keyboard navigation
+
+- `Shift+Down`: select the first activity, then move down (wraps).
+- `Shift+Up`: select the last activity, then move up (wraps).
+- `Enter`: open the selected subagent session.
+- `Esc`: clear widget selection.
+- Without a selected activity, normal Enter/arrow input remains owned by the main editor.
+- Duplicate Shift+arrow reports arriving within 150ms are coalesced, preventing terminals that emit the same physical keypress more than once from skipping activities.
+
+The session view is a focused overlay connected to the exact process/session
+that is running the selected task—not a new conversation with another copy of
+the same agent.
+
+The overlay uses 96% of the terminal width and 85% of its height (with no outer margin).
+Its transcript viewport grows with terminal height instead of being fixed to a
+small number of rows.
+
+```text
+╭──────────────────────── actor session · working… ────────────────────────╮
+│ Initial delegated task                                                    │
+│                                                                            │
+│ ⠋ tool calling...                                                         │
+│ └  ⠋ bash npm test (4.2s)                                                 │
+│                                                                            │
+│ Working on the implementation…                                            │
+│                                                                            │
+│ › additional instruction                                                   │
+│ Enter send · Esc main · Ctrl+O expand · PgUp/PgDn scroll                  │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+- Enter sends a prompt when idle or a steering message while streaming.
+- Esc closes only the overlay and returns focus to main; the subagent continues.
+- Ctrl+X aborts the selected subagent's current operation.
+- Ctrl+O expands/collapses every compact thinking/tool block.
+- PageUp/PageDown scroll the transcript; End returns to live output.
+- History is loaded on entry and early streaming events are buffered to avoid a startup race.
+- Tool calls show their arguments, streaming output, and final `[done]`/`[error]` status. Accumulated progress updates are converted to new output only, so previously shown lines are not duplicated.
+- User and assistant messages use pi's normal Markdown styling. Assistant fenced code blocks use compact-mode's bordered syntax-highlighted rendering.
+- Thinking and consecutive tool calls are merged into isolated compact-mode blocks with the same rails, colors, token estimates, collapsed limits, expanded result previews, and visible-text boundaries as the main transcript.
+- If Enter is pressed before the RPC process is ready, the requested session opens automatically as soon as its handle becomes available.
+
+## Main transcript message rendering
+
+Subagent-originated events use transparent backgrounds with one column of left
+padding. Protocol metadata stays in the underlying model message but is hidden
+from the visible transcript:
+
+```text
+ ← reviewer [msg] • reply requested
+ │ Please verify the cancellation behavior.
+ └ Include the timeout recovery case.
+
+ ✓ actor [bg] • completed · 42s
+ │ Implemented and tested the requested changes.
+ └ All checks pass.
+
+ ✗ planner [bg] • failed · 10s
+ └ Subagent timed out after 10 seconds.
+```
+
+- `←` marks a message entering the main session.
+- `✓` and `✗` mark background completion and failure.
+- A dim `│` rail marks every body row and changes to `└` on the final row,
+  making each subagent event's exact transcript range immediately visible.
+- Agent names are emphasized; `[msg]` / `[bg]`, status, and elapsed time remain compact.
+- Message bodies render as Markdown and reuse compact-mode's bordered,
+  syntax-highlighted fenced-code style.
+- Visible rows omit message IDs, routing paths, run IDs, and
+  `reply_message` protocol instructions.
+- Fire-and-forget messages do not ask the main agent to call `reply_message`;
+  their request files are removed immediately after successful injection.
+- Background results are delivered as custom messages with
+  `triggerTurn: true` and `deliverAs: "steer"`, preserving the former
+  synthetic-user-message behavior without inheriting `userMessageBg`.
+
+## Architecture
+
+```
+Main agent (primary outcome owner; optional specialist workflow defined by prompt)
+  |
+  |-- subagent tool (sync/background spawns an RPC-backed run session)
+  |     `-- widget selection / interactive overlay attach to that exact session
+  |-- RPC resident process pool (receives inter-subagent messages)
+  |-- message router (500ms poll)
+  |     |-- to=main     -> inject into main session -> reply_message replies
+  |     |-- to=subagent -> route to its resident process -> reply written back
+  |
+Subagents (separate processes, child mode):
+  |-- send_message / read_inbox / reply_message tools
+  |-- file channel: /tmp/pi-subagents-messages/<session>/<run>/<agent>/<idx>/{requests,replies}/
+```
+
+## Layout
+
+```
+subagents/
+|-- package.json
+|-- index.ts        # main (subagent tool + message router + background) / child (messaging tools)
+|-- agents.ts       # agent discovery (frontmatter parsing)
+|-- agents/*.md     # subagent identity definitions (planner / reviewer / actor)
+|-- spawn.ts        # RPC-backed interactive runs + legacy JSON one-shot compatibility
+|-- pool.ts         # RPC resident process pool (inter-subagent message routing)
+|-- message.ts      # generic messaging (file channel + send/reply/read + main-side router)
+|-- session.ts      # common interactive session-handle interface
+|-- session-ui.ts   # focused overlay for live transcript + interactive input
+|-- orchestrator.md # main-agent outcome/workflow prompt (optional injection)
+`-- README.md
+```
+
+## Usage
+
+```bash
+# optional: inject the main-agent specialist-workflow identity
+pi --append-system-prompt ~/.pi/agent/extensions/subagents/orchestrator.md
+
+# or in-session
+/orchestrate            # enable orchestrator mode (injects the triage identity every turn)
+/orchestrate off        # disable
+/orchestrate status     # check state
+
+# in conversation
+"Resolve this architecture decision, then implement it" # planner is used when a Decision Brief is needed
+"Use subagent async=true, agent=actor, task=..."     # explicit background delegation
+"Use subagent agent=reviewer timeoutSeconds=120 ..." # override the default 6h task timeout (only when the user asked)
+"Have reviewer review the recent changes"            # main agent delegates to reviewer
+```

package/agents/actor.md

@@ -0,0 +1,51 @@
+---
+thinking: max
+name: actor
+description: Implement a clear Task Brief or Decision Record and verify the resulting change
+tools: read, write, edit, bash, grep, find, ls
+model: opencode-go-responses/deepseek-v4-flash
+---
+
+You are the implementation specialist.
+
+You receive either a direct Task Brief from main or an implementation outline
+derived from a design decision. A separate planner result is optional. Form the
+local execution steps needed to complete the brief, then implement and verify
+the change.
+
+## Task Brief
+
+Use the supplied brief as the working contract:
+
+- Desired outcome
+- Relevant subsystem or files
+- Required behavior
+- Constraints
+- Verification criteria
+
+## Responsibilities
+
+1. Inspect the relevant code and translate the brief into concrete local steps.
+2. Implement the requested behavior with focused changes.
+3. Verify the result using the supplied criteria and appropriate tests.
+4. Report blockers or newly discovered decisions with the evidence that exposed them.
+
+When a consequential decision remains unresolved, return a concise Decision
+Brief candidate to main. When the direction is clear, make the local
+implementation judgment needed to complete the task.
+
+## Implementation quality
+
+- Preserve project conventions and existing boundaries.
+- Keep changes small, direct, and relevant to the requested outcome.
+- Use proportionate handling for real edge cases and failure modes.
+- Read back changed files and run relevant verification.
+
+## Output
+
+Report:
+
+- Files changed
+- Per-file summary
+- Verification performed and results
+- Remaining blockers, decisions, or assumptions

package/agents/planner.md

@@ -0,0 +1,57 @@
+---
+thinking: xhigh
+name: planner
+description: Resolve a concrete design decision from a Decision Brief and produce an actor-ready decision record
+tools: read, bash, grep, find, ls
+model: mvp-anthropic/glm-5.3
+---
+
+You are the design-decision specialist.
+
+You receive a Decision Brief describing a consequential implementation choice
+that remains unresolved after initial discovery. Your distinct contribution is
+to resolve that choice and make the downstream implementation direction clear.
+
+## Decision Brief
+
+Use the supplied brief as the working contract:
+
+- Decision to make
+- Why the decision matters
+- Known facts and evidence
+- Constraints
+- Candidate approaches or unresolved boundary
+- Downstream use by the executor
+
+## Responsibilities
+
+1. Validate the relevant facts and constraints using read-only inspection.
+2. Compare the viable approaches against those constraints.
+3. Select a direction and explain why it best serves the requested outcome.
+4. Identify consequences for interfaces, data, migration, compatibility, testing, and rollout where relevant.
+5. Produce an implementation outline specific enough for actor to execute without guessing.
+
+## Evidence gathering
+
+Use `read`, `grep`, `find`, and `ls` for source inspection. Use `bash` for
+read-only evidence gathering such as `git status`, `git diff`, `git log`,
+package metadata, and non-mutating verification commands.
+
+When additional evidence is needed, return the smallest concrete evidence
+request in the final result so main can gather it and update the Decision
+Brief.
+
+## Output
+
+Return structured Markdown with:
+
+1. **Decision**
+2. **Rationale**
+3. **Evidence**
+4. **Alternatives considered**
+5. **Consequences and risks**
+6. **Actor-ready implementation outline**
+7. **Verification strategy**
+8. **Assumptions to confirm**
+
+End with a one-line `Decision complete` summary.

package/agents/reviewer.md

@@ -0,0 +1,40 @@
+---
+thinking: xhigh
+name: reviewer
+description: Independently verify completed work against the user outcome, brief, code, and test evidence
+tools: read, grep, find, ls, bash
+model: mvp-openai/gpt-5.6-sol
+---
+
+You are the independent verification specialist.
+
+Evaluate completed work against the user's requested outcome and the supplied
+Verification Brief. A planner document is optional; when a Decision Record
+exists, verify that the implementation preserves it.
+
+## Verification Brief
+
+Use the supplied evidence:
+
+- User outcome
+- Task Brief
+- Decision Record, when one exists
+- Relevant diff or files
+- Verification already performed
+
+## Responsibilities
+
+1. Establish the intended behavior from the outcome and brief.
+2. Inspect the actual changes and relevant surrounding code.
+3. Check correctness, requirement coverage, regressions, edge cases, and project conventions.
+4. Run proportionate read-only tests or diagnostics when they add evidence.
+5. Distinguish concrete defects from optional improvements.
+
+## Output
+
+Return one of:
+
+- `Approved` with a concise evidence-based reason.
+- `Rejected` with a prioritized issue list containing file/line, impact, evidence, and a concrete correction.
+
+Focus review depth on the risk and consequence of the completed change.

package/agents.ts

@@ -0,0 +1,87 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	thinking?: string;
+	systemPrompt: string;
+	source: string;
+}
+
+/** Parse YAML frontmatter + markdown body */
+function parseFrontmatter(
+	content: string,
+): { frontmatter: Record<string, string>; body: string } {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+	if (!match) return { frontmatter: {}, body: content };
+	const raw = match[1] ?? "";
+	const body = match[2] ?? "";
+	const frontmatter: Record<string, string> = {};
+	for (const line of raw.split("\n")) {
+		const idx = line.indexOf(":");
+		if (idx <= 0) continue;
+		const key = line.slice(0, idx).trim();
+		const value = line.slice(idx + 1).trim().replace(/^["']|["']$/g, "");
+		if (key) frontmatter[key] = value;
+	}
+	return { frontmatter, body: body.trim() };
+}
+
+function loadAgentsFromDir(dir: string): AgentConfig[] {
+	if (!fs.existsSync(dir)) return [];
+	const agents: AgentConfig[] = [];
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+		const filePath = path.join(dir, entry.name);
+		const content = fs.readFileSync(filePath, "utf-8");
+		const { frontmatter, body } = parseFrontmatter(content);
+		if (!frontmatter.name || !frontmatter.description) continue;
+		const tools = frontmatter.tools
+			?.split(",")
+			.map((t) => t.trim())
+			.filter(Boolean);
+		agents.push({
+			name: frontmatter.name,
+			description: frontmatter.description,
+			tools: tools && tools.length > 0 ? tools : undefined,
+			model: frontmatter.model || undefined,
+			thinking: frontmatter.thinking || undefined,
+			systemPrompt: body,
+			source: dir,
+		});
+	}
+	return agents;
+}
+
+/** Built-in agent directory (the extension's own agents/) */
+function builtinAgentsDir(): string {
+	const here = path.dirname(fileURLToPath(import.meta.url));
+	return path.join(here, "agents");
+}
+
+/** User-level agent directory ~/.pi/agent/agents */
+export function userAgentsDir(home = process.env.HOME ?? ""): string {
+	return path.join(home, ".pi", "agent", "agents");
+}
+
+/**
+ * Discover agents: built-in agents/ + user-level ~/.pi/agent/agents.
+ * A user-level agent with the same name overrides the built-in one.
+ */
+export function discoverAgents(cwd?: string): AgentConfig[] {
+	const dirs = [builtinAgentsDir()];
+	if (cwd) {
+		// project-level .pi/agents is intentionally not enabled (safety)
+	}
+	const byName = new Map<string, AgentConfig>();
+	for (const dir of dirs) {
+		for (const agent of loadAgentsFromDir(dir)) {
+			byName.set(agent.name, agent);
+		}
+	}
+	return [...byName.values()];
+}