pi-maestro-teammate 0.2.0 → 0.3.0

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
 
-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,147 @@ 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.
+
+## TaskSpec Schema
+
+```typescript
+interface TaskSpec {
+  agent: string;        // Agent name (matches agents/*.md filename)
+  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, which spawns the new agent as a peer — not a nested subprocess.
+
+### How It Works
+
+```
+coordinator calls teammate({ agent: "scout", name: "recon" })
+  │  stdout: teammate_proxy_request
+  ▼
+Root spawns scout → registers in root's activeRuns/namedAgents
+  │  IPC: teammate_proxy_result
+  ▼
+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
+
+Child processes register proxy versions of all teammate tools. Each proxy:
+1. Writes a `teammate_proxy_request` JSON line to stdout
+2. Awaits the result via Node.js IPC (`process.on("message")`)
+
+The root's event parser intercepts these requests and executes them locally. The IPC channel is established via `stdio: ["pipe","pipe","pipe","ipc"]` at spawn time.
+
+## 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
+- **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 +223,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 +240,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,24 @@
 ---
 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
 
 Be methodical and thorough. Document your reasoning for key decisions. If a step fails, attempt recovery before reporting failure.

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.3.0",
+  "description": "Pi extension for teammate dispatch with P0 three-axis decoupling (name, reply_to)",
   "type": "module",
   "keywords": [
     "pi-package",