pi-maestro-teammate 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# pi-teammate
+
+> Teammate dispatch tool for [Pi](https://github.com/earendil-works/pi) — three-axis agent orchestration with P0 decoupling
+
+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
+```
+
+## Quick Start
+
+### Single Agent
+
+```
+{ agent: "delegate", task: "Implement the auth middleware" }
+```
+
+### Parallel Execution
+
+```
+{ tasks: [
+    { agent: "scout", task: "Find all API endpoints" },
+    { agent: "scout", task: "Map database schemas" },
+    { agent: "scout", task: "List external dependencies" }
+  ],
+  concurrency: 3
+}
+```
+
+### Chain Pipeline
+
+```
+{ chain: [
+    { agent: "scout", task: "Find the auth module structure" },
+    { agent: "delegate", task: "Based on this context: {previous}\n\nRefactor the auth module" }
+  ]
+}
+```
+
+### Three-Axis Routing
+
+```
+{ agent: "delegate", task: "...", name: "worker-1", reply_to: "caller", lifecycle: "ephemeral" }
+```
+
+### Structured Output
+
+```
+{ agent: "scout", task: "List all API routes",
+  outputSchema: {
+    type: "object",
+    properties: { routes: { type: "array", items: { type: "string" } } },
+    required: ["routes"]
+  }
+}
+```
+
+## Agent Definition Format
+
+Create `agents/my-agent.md`:
+
+```markdown
+---
+name: my-agent
+description: Short description of what this agent does
+tools: read, grep, find, ls, bash, edit, write
+model: anthropic/claude-sonnet-4
+fallbackModels: google/gemini-2.5-pro, anthropic/claude-haiku-4
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fresh
+---
+
+You are a specialized agent. Your system prompt goes here.
+
+Use the provided tools to accomplish the task.
+```
+
+### Frontmatter Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `name` | string | **required** | Agent identifier |
+| `description` | string | **required** | Short description |
+| `tools` | comma-sep | all | Available tools |
+| `model` | string | parent model | Primary model |
+| `fallbackModels` | comma-sep | — | Fallback model chain |
+| `thinking` | string | — | Thinking level (low/medium/high) |
+| `systemPromptMode` | append\|replace | replace | How system prompt is applied |
+| `inheritProjectContext` | bool | false | Inherit parent project context |
+| `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                   │
+└─────────────────────────────────────────────────┘
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PI_TEAMMATE_PI_BINARY` | Override pi binary path |
+| `PI_TEAMMATE_CHILD` | Set to `"1"` in child processes |
+| `PI_TEAMMATE_DEPTH` | Current nesting depth |
+| `PI_TEAMMATE_CORRELATION_ID` | Correlation ID for routing |
+| `PI_TEAMMATE_REPLY_TO` | Resolved reply target |
+| `PI_TEAMMATE_PARENT_SESSION` | Parent session file path |
+
+## License
+
+MIT

package/agents/coordinator.md

@@ -0,0 +1,19 @@
+---
+name: coordinator
+description: Orchestration-aware teammate agent for multi-step coordination tasks
+systemPromptMode: replace
+inheritProjectContext: true
+thinking: high
+tools: read, grep, find, ls, bash, edit, write
+inheritSkills: false
+---
+
+You are a coordinator agent responsible for orchestrating multi-step tasks. You plan the execution strategy, coordinate between subtasks, and synthesize results.
+
+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
+
+Be methodical and thorough. Document your reasoning for key decisions. If a step fails, attempt recovery before reporting failure.

package/agents/delegate.md

@@ -0,0 +1,16 @@
+---
+name: delegate
+description: Lightweight teammate agent that inherits the parent model for single-task execution
+systemPromptMode: append
+inheritProjectContext: true
+tools: read, grep, find, ls, bash, edit, write
+inheritSkills: false
+---
+
+You are a delegated teammate agent. Execute the assigned task using the provided tools. Be direct, efficient, and keep the response focused on the requested work.
+
+Guidelines:
+- Read existing code before making changes
+- Follow project conventions and patterns
+- Report what was done concisely
+- If blocked, explain what is needed to proceed

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "pi-maestro-teammate",
+  "version": "0.1.0",
+  "description": "Pi extension for teammate dispatch with P0 three-axis decoupling (name, reply_to, lifecycle)",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "teammate",
+    "agents"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "agents/",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/extension/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@earendil-works/pi-tui": "0.74.0",
+    "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"
+  }
+}

package/src/agents/agents.ts

@@ -0,0 +1,186 @@
+/**
+ * Agent discovery and configuration.
+ *
+ * Discovers agent definitions from three locations (in priority order):
+ *   1. Project agents: .pi/agents/ in the nearest project root
+ *   2. User agents: ~/.pi/agent/extensions/teammate/agents/
+ *   3. Builtin agents: bundled agents/ directory in this package
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseFrontmatter } from "./frontmatter.ts";
+
+type SystemPromptMode = "append" | "replace";
+type AgentSource = "builtin" | "user" | "project";
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  tools?: string[];
+  model?: string;
+  fallbackModels?: string[];
+  thinking?: string;
+  systemPromptMode: SystemPromptMode;
+  inheritProjectContext: boolean;
+  inheritSkills: boolean;
+  defaultContext?: "fresh" | "fork";
+  systemPrompt: string;
+  source: AgentSource;
+  filePath: string;
+}
+
+const BUILTIN_AGENTS_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "agents",
+);
+
+function listMarkdownFiles(dir: string): string[] {
+  const files: string[] = [];
+  if (!fs.existsSync(dir)) return files;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+    if (!entry.name.endsWith(".md")) continue;
+    files.push(path.join(dir, entry.name));
+  }
+
+  return files.sort();
+}
+
+function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
+  const agents: AgentConfig[] = [];
+
+  for (const filePath of listMarkdownFiles(dir)) {
+    let content: string;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const { frontmatter, body } = parseFrontmatter(content);
+
+    if (!frontmatter.name || !frontmatter.description) {
+      continue;
+    }
+
+    const rawTools = frontmatter.tools
+      ?.split(",")
+      .map((t) => t.trim())
+      .filter(Boolean);
+
+    const systemPromptMode: SystemPromptMode =
+      frontmatter.systemPromptMode === "replace"
+        ? "replace"
+        : frontmatter.systemPromptMode === "append"
+          ? "append"
+          : frontmatter.name === "delegate"
+            ? "append"
+            : "replace";
+
+    const inheritProjectContext =
+      frontmatter.inheritProjectContext === "true"
+        ? true
+        : frontmatter.inheritProjectContext === "false"
+          ? false
+          : frontmatter.name === "delegate";
+
+    const inheritSkills = frontmatter.inheritSkills === "true";
+
+    const defaultContext =
+      frontmatter.defaultContext === "fork"
+        ? ("fork" as const)
+        : frontmatter.defaultContext === "fresh"
+          ? ("fresh" as const)
+          : undefined;
+
+    const rawFallbackModels = frontmatter.fallbackModels
+      ?.split(",")
+      .map((m: string) => m.trim())
+      .filter(Boolean);
+
+    agents.push({
+      name: frontmatter.name,
+      description: frontmatter.description,
+      tools: rawTools && rawTools.length > 0 ? rawTools : undefined,
+      model: frontmatter.model,
+      fallbackModels: rawFallbackModels && rawFallbackModels.length > 0 ? rawFallbackModels : undefined,
+      thinking: frontmatter.thinking,
+      systemPromptMode,
+      inheritProjectContext,
+      inheritSkills,
+      defaultContext,
+      systemPrompt: body,
+      source,
+      filePath,
+    });
+  }
+
+  return agents;
+}
+
+/**
+ * Discover all agent definitions, merged by priority:
+ * project > user > builtin (name collisions: higher priority wins).
+ */
+export function discoverAgents(cwd: string): AgentConfig[] {
+  const userAgentsDir = path.join(
+    os.homedir(),
+    ".pi",
+    "agent",
+    "extensions",
+    "teammate",
+    "agents",
+  );
+
+  // Find project root (first ancestor with .pi/ directory)
+  let projectAgentsDir: string | null = null;
+  let currentDir = cwd;
+  while (true) {
+    const piDir = path.join(currentDir, ".pi", "agents");
+    if (fs.existsSync(piDir)) {
+      projectAgentsDir = piDir;
+      break;
+    }
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
+  }
+
+  const builtinAgents = loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin");
+  const userAgents = loadAgentsFromDir(userAgentsDir, "user");
+  const projectAgents = projectAgentsDir
+    ? loadAgentsFromDir(projectAgentsDir, "project")
+    : [];
+
+  // Merge: project > user > builtin
+  const agentMap = new Map<string, AgentConfig>();
+  for (const agent of builtinAgents) agentMap.set(agent.name, agent);
+  for (const agent of userAgents) agentMap.set(agent.name, agent);
+  for (const agent of projectAgents) agentMap.set(agent.name, agent);
+
+  return Array.from(agentMap.values());
+}
+
+/**
+ * Resolve a single agent by name.
+ */
+export function resolveAgent(
+  cwd: string,
+  agentName: string,
+): AgentConfig | undefined {
+  const agents = discoverAgents(cwd);
+  return agents.find((a) => a.name === agentName);
+}

package/src/agents/frontmatter.ts

@@ -0,0 +1,121 @@
+/**
+ * Parse markdown files with YAML frontmatter (--- delimited).
+ *
+ * Extracts structured fields from the frontmatter block and returns
+ * the remaining body as the system prompt.
+ */
+
+/**
+ * Escape regex special characters for use in a RegExp constructor.
+ */
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export interface AgentFrontmatter {
+  name?: string;
+  description?: string;
+  tools?: string;
+  thinking?: string;
+  systemPromptMode?: string;
+  inheritProjectContext?: string;
+  inheritSkills?: string;
+  defaultContext?: string;
+  model?: string;
+  fallbackModels?: string;
+  output?: string;
+  defaultReads?: string;
+  skill?: string;
+  skills?: string;
+  extensions?: string;
+  [key: string]: string | undefined;
+}
+
+export function parseFrontmatter(content: string): {
+  frontmatter: AgentFrontmatter;
+  body: string;
+} {
+  const frontmatter: AgentFrontmatter = {};
+  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();
+
+  const lines = frontmatterBlock.split("\n");
+  let currentKey: string | null = null;
+  let currentBlockLines: string[] | null = null;
+  let currentIndent: number | null = null;
+
+  for (const line of lines) {
+    const indent = line.search(/\S|$/);
+    const trimmed = line.trim();
+
+    if (
+      currentKey !== null &&
+      currentBlockLines !== null &&
+      indent > (currentIndent ?? 0)
+    ) {
+      currentBlockLines.push(line);
+      continue;
+    }
+
+    // Flush any pending block value
+    if (currentKey !== null && currentBlockLines !== null) {
+      const rawBlock = currentBlockLines.join("\n");
+      const leadingSpaces = rawBlock.match(/^([ \t]+)/m);
+      const prefix = leadingSpaces?.[1] ?? "";
+      const stripped = prefix
+        ? rawBlock
+            .replace(new RegExp(`^${escapeRegex(prefix)}`, "gm"), "")
+            .replace(/^\n/, "")
+        : rawBlock;
+      frontmatter[currentKey] = stripped;
+      currentKey = null;
+      currentBlockLines = null;
+      currentIndent = null;
+    }
+
+    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);
+      }
+
+      if (value === "") {
+        currentKey = match[1];
+        currentBlockLines = [];
+        currentIndent = indent;
+      } else {
+        frontmatter[match[1]] = value;
+      }
+    }
+  }
+
+  // Flush final block value
+  if (currentKey !== null && currentBlockLines !== null) {
+    const rawBlock = currentBlockLines.join("\n");
+    const leadingSpaces = rawBlock.match(/^([ \t]+)/m);
+    const prefix = leadingSpaces?.[1] ?? "";
+    const stripped = prefix
+      ? rawBlock
+          .replace(new RegExp(`^${escapeRegex(prefix)}`, "gm"), "")
+          .replace(/^\n/, "")
+      : rawBlock;
+    frontmatter[currentKey] = stripped;
+  }
+
+  return { frontmatter, body };
+}