pi-maestro-teammate 0.2.0 → 0.4.1

package/README.md

@@ -1,52 +1,8 @@
 # pi-teammate
 
-> Teammate dispatch tool for [Pi](https://github.com/earendil-works/pi) — three-axis agent orchestration with P0 decoupling
+> Teammate dispatch tool for [Pi](https://github.com/earendil-works/pi) — unified TaskSpec with DAG variable referencing + resident agent model
 
-Pi extension implementing teammate dispatch with **P0 three-axis decoupling** (name × reply_to × lifecycle). Spawn isolated pi subprocesses as teammates with protocol-versioned routing, parallel/chain execution, and structured output.
-
-## Features
-
-### Three-Axis Control
-
-| Axis | Field | Values | Purpose |
-|------|-------|--------|---------|
-| Addressability | `name` | string \| omit | Cross-agent routing via name |
-| Result Routing | `reply_to` | `"caller"` \| `"main"` | Where results go |
-| Lifecycle | `lifecycle` | `"ephemeral"` \| `"resident"` | One-shot or persistent |
-
-**Protocol version gate** — v2 (default) routes results to `caller`; v1 compat routes named agents to `main`. Explicit `reply_to` always wins.
-
-### Execution Modes
-
-- **Single** — dispatch one agent with a task
-- **Parallel** — `tasks[]` runs multiple agents concurrently with configurable `concurrency`
-- **Chain** — `chain[]` sequential pipeline where each step receives `{previous}` result
-
-### Reliability
-
-- **Model fallback chain** — primary model → `fallbackModels[]` from agent config → automatic retry on model failures
-- **Nesting depth guard** — `PI_TEAMMATE_DEPTH` env tracking with configurable max (default: 3) prevents fork bombs
-- **Windows-safe pi resolution** — `getPiSpawnCommand()` resolves the pi binary via env override, Windows script detection, or PATH
-- **Abort signal** — SIGTERM → 5s grace → SIGKILL
-
-### Output & Tracking
-
-- **Structured output** — `outputSchema` validates child output against JSON Schema, returns parsed `structuredOutput`
-- **Rich progress** — `AgentProgress` with `recentTools[]`, `toolCount`, `tokens`, `durationMs`, `lastActivityAt`
-- **Session management** — derives child session directory from parent session, supports `context: "fork"`
-- **Correlation ID** — auto-generated per dispatch for result routing
-
-### Agent Definitions
-
-Agents are markdown files with YAML frontmatter — discovered from project (`.pi/agents/`), user (`~/.pi/agent/extensions/teammate/agents/`), or builtin locations. Project overrides user overrides builtin.
-
-## Install
-
-```bash
-pi install npm:@pi-maestro/teammate
-# or from local path
-pi install ./pi-teammate
-```
+Pi extension implementing teammate dispatch with **unified TaskSpec model**. Single agent, parallel fan-out, sequential chains, and arbitrary DAGs all use the same schema — execution order is determined by `{name}` variable references between tasks.
 
 ## Quick Start
 
@@ -56,7 +12,7 @@ pi install ./pi-teammate
 { agent: "delegate", task: "Implement the auth middleware" }
 ```
 
-### Parallel Execution
+### Parallel (no references = concurrent)
 
 ```
 { tasks: [
@@ -68,22 +24,34 @@ pi install ./pi-teammate
 }
 ```
 
-### Chain Pipeline
+### Chain (linear references = sequential)
 
 ```
-{ chain: [
-    { agent: "scout", task: "Find the auth module structure" },
-    { agent: "delegate", task: "Based on this context: {previous}\n\nRefactor the auth module" }
+{ tasks: [
+    { agent: "scout", name: "recon", task: "Find the auth module structure" },
+    { agent: "delegate", task: "Based on this context: {recon}\n\nRefactor the auth module" }
   ]
 }
 ```
 
-### Three-Axis Routing
+### DAG (mixed references = auto-scheduling)
 
 ```
-{ agent: "delegate", task: "...", name: "worker-1", reply_to: "caller", lifecycle: "ephemeral" }
+{ tasks: [
+    { agent: "scout", name: "api", task: "List all API routes",
+      outputSchema: {
+        type: "object",
+        properties: { routes: { type: "array", items: { type: "string" } } },
+        required: ["routes"]
+      } },
+    { agent: "scout", name: "db", task: "Map the database schema" },
+    { agent: "reviewer", task: "Routes: {api.routes}\nDB: {db}\n\nCheck consistency" }
+  ]
+}
 ```
 
+`api` and `db` run in parallel. `reviewer` waits for both, with `{api.routes}` resolved from structured output and `{db}` from text output.
+
 ### Structured Output
 
 ```
@@ -96,6 +64,186 @@ pi install ./pi-teammate
 }
 ```
 
+In multi-task mode, structured outputs are aggregated by task `name` in the result's `structuredOutput` field.
+
+## Core Concepts
+
+### Two Rules
+
+1. **Reference = dependency**: `{name}` in a task's description means "wait for the task named `name` to complete, then inject its output here"
+2. **No reference = parallel**: tasks with no dependencies run concurrently (bounded by `concurrency`)
+
+No `mode` field needed — the execution engine infers parallel, chain, or graph from the reference topology.
+
+### Variable References
+
+| Syntax | Resolves to |
+|--------|-------------|
+| `{name}` | Full text output; or JSON string if the task has `outputSchema` |
+| `{name.field}` | Field from structured output |
+| `{name.arr[0].path}` | Nested field with array indexing |
+
+Only tasks with a `name` field can be referenced. Non-task `{braces}` (JSON, format strings) are left untouched.
+
+### Default Inheritance
+
+Top-level fields serve as defaults for all tasks:
+
+| Field | Scope | Override |
+|-------|-------|----------|
+| `model` | Default model for all tasks | Per-task `model` wins |
+| `cwd` | Default working directory | Per-task `cwd` wins |
+| `outputSchema` | Default schema for all tasks | Per-task `outputSchema` wins |
+| `timeoutMs` | Default timeout | Per-task `timeoutMs` wins |
+
+### Three-Axis Control
+
+| Axis | Field | Values | Purpose |
+|------|-------|--------|---------|
+| Addressability | `name` | string \| omit | Variable referencing + teammate-send routing |
+| Result Routing | `reply_to` | `"caller"` \| `"main"` | Where results go |
+| Lifecycle | `lifecycle` | `"ephemeral"` \| `"resident"` | One-shot or persistent |
+
+**Protocol version gate** — v2 (default) routes results to `caller`; v1 compat routes named agents to `main`. Explicit `reply_to` always wins.
+
+## Resident Agent Model
+
+Agents don't exit after completing a task. Instead they enter a **sleeping** state and can be woken up for follow-up work.
+
+### Lifecycle
+
+```
+dispatch → running → turn complete → sleeping → teammate-send → running → ...
+                                                                         ↓
+                                                              abort → terminated
+```
+
+| Status | Description |
+|--------|-------------|
+| `running` | Agent is actively processing a task |
+| `sleeping` | Turn complete, process alive, waiting for `teammate-send` to wake |
+| `completed` | Agent terminated (via abort or session shutdown) |
+
+### How It Works
+
+1. Agent completes its turn → `agent_end` event fires
+2. Result is reported to the main session (background notification)
+3. Agent enters **sleeping** state — RPC process stays alive, stdin open
+4. `teammate-send({ to: "name", message: "new task" })` sends a `follow_up` → agent wakes up and processes the new message
+5. `teammate-send({ to: "name", mode: "abort" })` terminates the agent
+
+### Active Time Tracking
+
+Time spent sleeping is excluded from the displayed duration. `sleepMs` accumulates total sleep time; displayed uptime = wall clock − sleep time.
+
+### Agent Fallback
+
+Any agent name works — if no `.md` definition file exists, a generic config is used:
+- `tools`: read, grep, find, ls, bash, edit, write (+ teammate proxy tools)
+- `systemPromptMode`: append (inherits pi default system prompt)
+- `inheritProjectContext`: true
+
+## TaskSpec Schema
+
+```typescript
+interface TaskSpec {
+  agent: string;        // Agent name (matches agents/*.md, or any name with fallback)
+  task?: string;        // Task description with {name} variable support
+  name?: string;        // Identifier for referencing and teammate-send
+  model?: string;       // Model override
+  cwd?: string;         // Working directory
+  outputSchema?: object; // JSON Schema for structured output
+  timeoutMs?: number;   // Timeout in milliseconds
+}
+```
+
+## Full Parameters
+
+```typescript
+interface TeammateParams extends TaskSpec {
+  // Multi-task
+  tasks?: TaskSpec[];     // Multiple tasks with {name} references
+  concurrency?: number;   // Max concurrent tasks (default: 4)
+
+  // Execution control (applies to ALL modes)
+  background?: boolean;   // Run in background (default: true)
+  context?: "fresh" | "fork";
+
+  // P0 three-axis
+  reply_to?: "caller" | "main";
+  protocol_version?: number;
+
+  // Deprecated
+  chain?: Array<{ agent, task?, model? }>; // Use tasks with {name} references
+}
+```
+
+## Validation & Error Handling
+
+- **Duplicate names**: detected before execution, all tasks fail with error
+- **Circular dependencies**: detected before execution via cycle detection
+- **Missing reference**: `{unknown}` left as literal text (not a task name)
+- **Field access without schema**: error when `{name.field}` used but task has no `outputSchema`
+- **Upstream failure**: dependent tasks are skipped with "upstream dependency failed"
+
+## Deprecated: chain[]
+
+The `chain` field is preserved for backward compatibility. It normalizes internally to `tasks` with sequential `{_stepN}` references:
+
+```
+// This chain:
+{ chain: [
+    { agent: "scout", task: "Find auth code" },
+    { agent: "delegate", task: "Fix: {previous}" }
+  ]
+}
+
+// Is equivalent to:
+{ tasks: [
+    { agent: "scout", name: "_step0", task: "Find auth code" },
+    { agent: "delegate", name: "_step1", task: "Fix: {_step0}" }
+  ]
+}
+```
+
+## Flat Agent Model
+
+All agents are managed by the root process in a single flat `activeRuns` pool, regardless of who requested the spawn. Child agents that call the teammate tool send a proxy request to the root via IPC, which spawns the new agent as a peer — not a nested subprocess.
+
+### How It Works
+
+```
+coordinator calls teammate({ agent: "scout", name: "recon" })
+  │  IPC: teammate_proxy_request (process.send)
+  ▼
+Root spawns scout → registers in root's activeRuns/namedAgents
+  │  IPC: teammate_proxy_result (child.send)
+  ▼
+coordinator receives result
+```
+
+All agents are flat peers:
+- `teammate-send({ to: "name" })` = one lookup in `namedAgents` → stdin. Direct delivery.
+- `teammate-list` = iterate `activeRuns`. Flat, simple.
+- `teammate-watch` = read agent's `outputLog`. Direct.
+
+### Child Proxy Tools
+
+Every child process automatically gets proxy versions of all 4 teammate tools (injected into `--tools` whitelist regardless of agent definition). Each proxy:
+1. Sends a `teammate_proxy_request` via Node.js IPC (`process.send()`)
+2. Awaits the result via IPC (`process.on("message")`)
+
+The root's IPC message listener (`child.on("message")`) intercepts these requests and executes them locally.
+
+## Reliability
+
+- **Model fallback chain** — primary model → `fallbackModels[]` from agent config → automatic retry
+- **Flat agent pool** — all agents managed by root process; child proxy tools forward spawn requests to root; depth guard (`PI_TEAMMATE_DEPTH`) prevents runaway recursion
+- **Resident lifecycle** — agents sleep after turn completion; process stays alive for follow-up; only killed on explicit abort or session shutdown
+- **IPC disconnect guard** — child proxy resolves all pending requests with error on disconnect (root crash / agent abort)
+- **Windows-safe pi resolution** — `getPiSpawnCommand()` resolves the pi binary via env override, Windows script detection, or PATH
+- **Abort signal** — SIGTERM → 5s grace → SIGKILL
+
 ## Agent Definition Format
 
 Create `agents/my-agent.md`:
@@ -114,8 +262,6 @@ defaultContext: fresh
 ---
 
 You are a specialized agent. Your system prompt goes here.
-
-Use the provided tools to accomplish the task.
 ```
 
 ### Frontmatter Fields
@@ -133,37 +279,12 @@ Use the provided tools to accomplish the task.
 | `inheritSkills` | bool | false | Inherit parent skills |
 | `defaultContext` | fresh\|fork | fresh | Default context mode |
 
-## Architecture
-
-```
-┌─────────────────────────────────────────────────┐
-│  Parent Pi Session                              │
-│                                                 │
-│  teammate tool call                             │
-│       │                                         │
-│       ├── resolve agent (project > user > built) │
-│       ├── resolve reply_to (protocol gate)      │
-│       ├── check depth guard                     │
-│       ├── build model candidates                │
-│       │                                         │
-│       ▼                                         │
-│  ┌─────────────────────────────────────┐        │
-│  │  spawn("pi", ["--mode","json","-p"])│        │
-│  │  env: PI_TEAMMATE_CHILD=1           │        │
-│  │       PI_TEAMMATE_DEPTH=N           │        │
-│  │       PI_TEAMMATE_CORRELATION_ID=…  │        │
-│  │       PI_TEAMMATE_REPLY_TO=caller   │        │
-│  │                                     │        │
-│  │  stdout: JSON lines ──────────────► │ parse  │
-│  │  (message_end, tool_result_end,     │ events │
-│  │   usage, error)                     │        │
-│  └─────────────────────────────────────┘        │
-│       │                                         │
-│       ├── accumulate usage                      │
-│       ├── track progress (AgentProgress)        │
-│       ├── model fallback on failure             │
-│       └── return SingleResult                   │
-└─────────────────────────────────────────────────┘
+## Install
+
+```bash
+pi install npm:pi-maestro-teammate
+# or from local path
+pi install ./pi-teammate
 ```
 
 ## Environment Variables

package/agents/coordinator.md

@@ -1,19 +1,26 @@
 ---
 name: coordinator
-description: Orchestration-aware teammate agent for multi-step coordination tasks
+description: Orchestration-aware teammate agent for multi-step task coordination with DAG variable referencing
 systemPromptMode: replace
 inheritProjectContext: true
 thinking: high
-tools: read, grep, find, ls, bash, edit, write
+tools: read, grep, find, ls, bash, edit, write, teammate, teammate-send, teammate-list, teammate-watch
 inheritSkills: false
 ---
 
-You are a coordinator agent responsible for orchestrating multi-step tasks. You plan the execution strategy, coordinate between subtasks, and synthesize results.
+You are a coordinator agent responsible for orchestrating multi-step tasks.
+
+When dispatching subtasks via the teammate tool, use the unified TaskSpec model:
+- Give each task a `name` so downstream tasks can reference its output via `{name}`
+- Use `outputSchema` when a task's output needs to be consumed as structured data by dependents via `{name.field}`
+- Tasks with no `{name}` references run in parallel; tasks that reference others wait automatically
 
 Your approach:
-1. Analyze the task requirements and break them into steps
-2. Execute steps in the correct order, respecting dependencies
-3. Verify each step's output before proceeding
-4. Synthesize a coherent result from all steps
+1. Analyze the task requirements and decompose into named subtasks
+2. Define data flow between subtasks using `{name}` variable references
+3. Let the execution engine resolve the dependency graph — no need to manually order
+4. Verify results and synthesize a coherent output
+
+After an agent completes its turn, it enters sleeping state. Use teammate-send to wake it for follow-up work. Use teammate-list to check agent status (● running / ◉ sleeping). Use teammate-send with mode "abort" to terminate an agent.
 
 Be methodical and thorough. Document your reasoning for key decisions. If a step fails, attempt recovery before reporting failure.

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "pi-maestro-teammate",
-  "version": "0.2.0",
-  "description": "Pi extension for teammate dispatch with P0 three-axis decoupling (name, reply_to, lifecycle)",
+  "version": "0.4.1",
+  "description": "Pi extension — teammate agent dispatch with DAG task graphs, RPC messaging, and compact TUI",
   "type": "module",
   "keywords": [
     "pi-package",
+    "pi-extension",
     "pi",
-    "pi-coding-agent",
     "teammate",
     "agents"
   ],
+  "scripts": {
+    "test": "node --experimental-transform-types --test \"test/*.test.ts\""
+  },
   "files": [
     "src/**/*.ts",
     "agents/",
@@ -23,7 +26,8 @@
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-agent-core": {
@@ -34,15 +38,18 @@
     },
     "@earendil-works/pi-coding-agent": {
       "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
     }
   },
   "dependencies": {
-    "@earendil-works/pi-tui": "0.74.0",
-    "typebox": "1.1.24"
+    "typebox": "^1.1.24"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.74.0",
-    "@earendil-works/pi-ai": "0.74.0",
-    "@earendil-works/pi-coding-agent": "0.74.0"
+    "@earendil-works/pi-agent-core": "0.80.3",
+    "@earendil-works/pi-ai": "0.80.3",
+    "@earendil-works/pi-coding-agent": "0.80.3",
+    "@earendil-works/pi-tui": "0.80.3"
   }
 }

package/src/agents/agents.ts

@@ -14,7 +14,7 @@ import { fileURLToPath } from "node:url";
 import { parseFrontmatter } from "./frontmatter.ts";
 
 type SystemPromptMode = "append" | "replace";
-type AgentSource = "builtin" | "user" | "project";
+export type AgentSource = "builtin" | "user" | "project";
 
 export interface AgentConfig {
   name: string;
@@ -32,6 +32,12 @@ export interface AgentConfig {
   filePath: string;
 }
 
+export interface AgentSummary {
+  name: string;
+  description: string;
+  source: AgentSource;
+}
+
 const BUILTIN_AGENTS_DIR = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
   "..",
@@ -184,3 +190,35 @@ export function resolveAgent(
   const agents = discoverAgents(cwd);
   return agents.find((a) => a.name === agentName);
 }
+
+/** Return resolved role metadata without exposing the role prompt body. */
+export function listAgentSummaries(cwd: string): AgentSummary[] {
+  return discoverAgents(cwd)
+    .map(({ name, description, source }) => ({ name, description, source }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/** Format a compact, deterministic role catalog for teammate tool metadata. */
+export function formatAgentCatalog(
+  cwd: string,
+  maxRoles = 32,
+  maxDescriptionLength = 120,
+): string {
+  const summaries = listAgentSummaries(cwd);
+  if (summaries.length === 0) return "(no discovered teammate roles)";
+
+  const visible = summaries.slice(0, maxRoles);
+  const lines = visible.map((agent) => {
+    const normalized = agent.description.replace(/\s+/g, " ").trim();
+    const description = normalized.length > maxDescriptionLength
+      ? `${normalized.slice(0, Math.max(1, maxDescriptionLength - 1)).trimEnd()}…`
+      : normalized;
+    return `- ${agent.name} [${agent.source}]: ${description}`;
+  });
+
+  if (summaries.length > visible.length) {
+    lines.push(`- … ${summaries.length - visible.length} more role(s) discovered`);
+  }
+
+  return lines.join("\n");
+}