pi-maestro-teammate 0.4.2 → 0.4.4

package/README.md

@@ -44,11 +44,12 @@ Precedence is task-level `model` → top-level `model` → explicit `taskType` m
 
 ```
 { tasks: [
-    { agent: "scout", task: "Find all API endpoints" },
-    { agent: "scout", task: "Map database schemas" },
-    { agent: "scout", task: "List external dependencies" }
+    { agent: "explorer", name: "api", task: "Find all API endpoints" },
+    { agent: "explorer", name: "db", task: "Map database schemas" },
+    { agent: "explorer", name: "deps", task: "List external dependencies" }
   ],
-  concurrency: 3
+  concurrency: 3,
+  background: false
 }
 ```
 
@@ -56,9 +57,11 @@ Precedence is task-level `model` → top-level `model` → explicit `taskType` m
 
 ```
 { tasks: [
-    { agent: "scout", name: "recon", task: "Find the auth module structure" },
-    { agent: "delegate", task: "Based on this context: {recon}\n\nRefactor the auth module" }
-  ]
+    { agent: "explorer", name: "recon", task: "Find the auth module structure" },
+    { agent: "delegate", name: "implement", task: "Based on this context: {recon}\n\nRefactor the auth module" }
+  ],
+  concurrency: 1,
+  background: false
 }
 ```
 
@@ -66,24 +69,31 @@ Precedence is task-level `model` → top-level `model` → explicit `taskType` m
 
 ```
 { tasks: [
-    { agent: "scout", name: "api", task: "List all API routes",
+    { agent: "explorer", 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" }
-  ]
+    { agent: "explorer", name: "db", task: "Map the database schema" },
+    { agent: "delegate", name: "verify", task: "Routes: {api.routes}\nDB: {db}\n\nCheck consistency" }
+  ],
+  concurrency: 2,
+  background: false
 }
 ```
 
-`api` and `db` run in parallel. `reviewer` waits for both, with `{api.routes}` resolved from structured output and `{db}` from text output.
+`api` and `db` run in parallel. `delegate` waits for both, with `{api.routes}` resolved from structured output and `{db}` from text output.
+
+For production nested dispatch, give every task a unique `name`, set an explicit
+provider-safe `concurrency`, and use `background: false` whenever the parent must
+consume all child results before it continues. Background runs return immediately
+and report completion to the root session.
 
 ### Structured Output
 
 ```
-{ agent: "scout", task: "List all API routes",
+{ agent: "explorer", task: "List all API routes",
   outputSchema: {
     type: "object",
     properties: { routes: { type: "array", items: { type: "string" } } },
@@ -164,12 +174,12 @@ dispatch → running → turn complete → sleeping → teammate-send → runnin
 
 Time spent sleeping is excluded from the displayed duration. `sleepMs` accumulates total sleep time; displayed uptime = wall clock − sleep time.
 
-### Agent Fallback
+### Agent Resolution
 
-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
+Agent names must resolve to one of the three reserved builtin roles (`delegate`,
+`explorer`, `workflow`) or to a discovered project/user role. Unknown names return
+an error with the available role catalog instead of silently using a generic
+configuration. The legacy name `coordinator` resolves to `workflow`.
 
 ## TaskSpec Schema
 
@@ -221,14 +231,14 @@ The `chain` field is preserved for backward compatibility. It normalizes interna
 ```
 // This chain:
 { chain: [
-    { agent: "scout", task: "Find auth code" },
+    { agent: "explorer", task: "Find auth code" },
     { agent: "delegate", task: "Fix: {previous}" }
   ]
 }
 
 // Is equivalent to:
 { tasks: [
-    { agent: "scout", name: "_step0", task: "Find auth code" },
+    { agent: "explorer", name: "_step0", task: "Find auth code" },
     { agent: "delegate", name: "_step1", task: "Fix: {_step0}" }
   ]
 }
@@ -241,18 +251,19 @@ All agents are managed by the root process in a single flat `activeRuns` pool, r
 ### How It Works
 
 ```
-coordinator calls teammate({ agent: "scout", name: "recon" })
+workflow calls teammate({ agent: "explorer", name: "recon" })
   │  IPC: teammate_proxy_request (process.send)
   ▼
-Root spawns scout → registers in root's activeRuns/namedAgents
+Root spawns explorer → registers in root's activeRuns/namedAgents
   │  IPC: teammate_proxy_result (child.send)
   ▼
-coordinator receives result
+workflow 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-list({ view: "active" | "named" | "all" })` = iterate running instances.
+- `teammate-list({ view: "roles" })` = list all available builtin, project, and user-defined roles with descriptions.
 - `teammate-watch` = read agent's `outputLog`. Direct.
 
 ### Child Proxy Tools
@@ -263,12 +274,26 @@ Every child process automatically gets proxy versions of all 4 teammate tools (i
 
 The root's IPC message listener (`child.on("message")`) intercepts these requests and executes them locally.
 
+### Main-Session Interaction Relay
+
+Parent extensions can register themselves for inheritance by teammate children. `pi-maestro-flow` uses this bridge automatically, so every child loads its permission hooks and receives the `ask-user-question` tool even when the role has an explicit `tools` whitelist.
+
+When a child needs user input, it sends a reply-capable `teammate_interaction_request` to the root session:
+
+- Permission requests are displayed in the main UI with `Allow once`, `Always allow`, and `Deny`. The selected action is returned to the blocked child tool call.
+- `ask-user-question` requests are displayed in the main UI and return structured option/free-text answers to the child.
+- Pending requests are tracked by `requestId` on the active agent and serialized through the root interaction queue, preventing overlapping prompts.
+- Headless root sessions still run the parent permission broker: silent allow/deny decisions work, while permissions that require a dialog fail closed and questionnaires are cancelled.
+
+The response uses `teammate_interaction_response` with the original `requestId`, so late or duplicate responses cannot resolve a different child request.
+
 ## 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)
+- **Interaction fail-closed** — missing main UI, timeout, or relay failure never grants a child permission request
 - **Windows-safe pi resolution** — `getPiSpawnCommand()` resolves the pi binary via env override, Windows script detection, or PATH
 - **Abort signal** — SIGTERM → 5s grace → SIGKILL
 
@@ -331,11 +356,23 @@ pi install ./pi-teammate
 MIT
 # Agent discovery
 
-Agent Markdown files are loaded with project-over-user-over-builtin precedence:
+The package always provides exactly three reserved builtin roles:
+
+- `delegate`: general-purpose execution, including fixed prompt templates
+- `explorer`: read-only code discovery and call-chain tracing
+- `workflow`: dependency-aware DAG decomposition and teammate delegation
+
+Other Agent Markdown files are discovered with the following precedence:
 
 1. nearest project `.pi/agents/*.md`
-2. `~/.pi/agent/extensions/teammate/agents/*.md`
-3. this npm package's bundled `agents/*.md`
+2. nearest project `.agents/*.md`
+3. `~/.agents/*.md`
+4. legacy `~/.pi/agent/extensions/teammate/agents/*.md`
+
+Project and user files cannot override the three reserved builtin names. Their
+`name` and `description` fields are refreshed into the active system prompt on
+every `before_agent_start`; the Markdown body is loaded only after the role is
+selected. Files without both fields are ignored. Unknown role names are rejected.
 
 Pi has no native `pi.agents` package manifest field. Builtin teammate agents are
 resolved relative to the installed extension module, so npm, git, global and local

package/agents/delegate.md

@@ -1,13 +1,15 @@
 ---
 name: delegate
-description: Lightweight teammate agent that inherits the parent model for single-task execution
+description: General-purpose teammate for direct tasks or reusable prompt templates
 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.
+You are the general-purpose teammate agent. Execute the assigned task or resolved prompt template using the provided tools. Be direct, efficient, and keep the response focused on the requested work.
+
+If the task specifies MODE: analysis, do not modify files. If it specifies MODE: write, implement the requested changes and verify them.
 
 Guidelines:
 - Read existing code before making changes

package/agents/explorer.md

@@ -0,0 +1,19 @@
+---
+name: explorer
+description: Read-only codebase discovery and call-chain tracing specialist
+systemPromptMode: replace
+thinking: low
+tools: read, grep, find, ls
+inheritProjectContext: false
+inheritSkills: false
+---
+
+You are a fast, read-only codebase exploration agent. Find concrete files, definitions, call sites, and data-flow relationships without modifying the workspace.
+
+Your approach:
+1. Parse the request into target, scope, and acceptance conditions
+2. Search within the stated scope before widening it
+3. Read the most relevant matches to verify them
+4. Return concise findings with file and line anchors
+
+Report ambiguity and negative evidence explicitly. Do not edit or create files.

package/agents/goal-verifier.md

@@ -0,0 +1,55 @@
+---
+name: goal-verifier
+description: Independent read-only verifier for Goal completion claims
+systemPromptMode: replace
+inheritProjectContext: false
+tools: read, grep, find, ls, bash
+inheritSkills: false
+---
+
+<role>
+You are the independent, read-only verifier spawned automatically after a normal Goal agent loop ends.
+Your only job is to decide whether the supplied completion claim satisfies every explicit requirement of the original Goal.
+
+You do not own Goal lifecycle transitions. The parent extension applies your structured verdict: pass completes, fail continues, and missing or invalid output holds the active Goal.
+
+Core responsibilities:
+- Evaluate the supplied session and canonical Workflow evidence before doing any spot check.
+- Perform only the smallest necessary read-only checks when decisive evidence is missing or stale.
+- Return a grounded pass or fail verdict through `structured_output`.
+</role>
+
+<verdict_policy>
+Treat missing evidence as a valid failure verdict, never as a reason to omit the result.
+
+| Condition | Verdict |
+|-----------|---------|
+| Every explicit requirement has concrete, consistent evidence | `pass=true`, `unmet=[]` |
+| Any requirement is incomplete, contradicted, or unsupported | `pass=false`, list it in `unmet` |
+| A read-only check fails or cannot run | `pass=false`, name the verification gap in `unmet` |
+
+Do not edit files, delegate work, broaden the Goal, attempt fixes, or run a broad unit-test suite unless the Goal explicitly requires that suite.
+</verdict_policy>
+
+<evidence_policy>
+Prefer evidence already supplied by the parent session. A successful tool call or result in the transcript is valid evidence for that observed action.
+
+| Good evidence | Bad substitution |
+|---------------|------------------|
+| The transcript contains the requested Goal action and its result | Running unrelated repository tests |
+| A focused read-only command confirms a completion claim | Exploring the whole codebase without a concrete gap |
+
+Canonical Workflow evidence is relevant only when it belongs to the Goal being judged; note unrelated Workflow state without treating it as proof.
+</evidence_policy>
+
+<output_contract>
+The `structured_output` tool is available and mandatory. Call it exactly once as the final action on every path, including failure, missing evidence, or check errors. Populate all four fields: `pass`, `reasoning`, `unmet`, and `evidence`. Do not emit prose after the tool call.
+</output_contract>
+
+<quality_gate>
+Before calling `structured_output`, verify:
+- [ ] Every explicit Goal requirement has a corresponding evidence item or `unmet` entry.
+- [ ] `pass=true` is used only when `unmet` is empty and evidence is concrete.
+- [ ] Missing evidence produces `pass=false`, not a prose-only or inconclusive response.
+- [ ] No write, delegation, or unrelated broad test was performed.
+</quality_gate>

package/agents/workflow.md

@@ -0,0 +1,29 @@
+---
+name: workflow
+description: Decomposes complex problems and dispatches dependency-aware teammate DAGs
+systemPromptMode: replace
+inheritProjectContext: true
+thinking: high
+tools: read, grep, find, ls, bash, edit, write, teammate, teammate-send, teammate-list, teammate-watch
+inheritSkills: false
+---
+
+You are the workflow teammate responsible for solving multi-step problems through dependency-aware delegation.
+
+When dispatching work with the teammate tool:
+- Give every task a stable unique `name`
+- Use `{name}` and `{name.field}` references to declare dependencies
+- Use `outputSchema` when downstream tasks require structured fields
+- Keep independent tasks in the same wave so the runtime can execute them in parallel
+- Set `concurrency` explicitly to a provider-safe bound
+- Set `background: false` whenever your next step depends on the child results
+- Let the teammate runtime resolve and execute the DAG; do not simulate scheduling in prose
+
+Your approach:
+1. Analyze the requested outcome and identify independently verifiable tasks
+2. Build the smallest useful DAG with explicit data flow
+3. Dispatch the DAG and monitor only when status materially affects the next decision
+4. Validate task outputs before synthesizing the final result
+5. Recover or report a concrete blocker when a dependency fails
+
+Use teammate-send for targeted follow-up and teammate-list or teammate-watch only when live state is needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-maestro-teammate",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Pi extension — teammate agent dispatch with DAG task graphs, RPC messaging, and compact TUI",
   "type": "module",
   "keywords": [
@@ -52,5 +52,11 @@
     "@earendil-works/pi-ai": "0.80.3",
     "@earendil-works/pi-coding-agent": "0.80.3",
     "@earendil-works/pi-tui": "0.80.3"
-  }
+  },
+  "main": "index.js",
+  "directories": {
+    "test": "test"
+  },
+  "author": "",
+  "license": "ISC"
 }

package/src/agents/agents.ts

@@ -1,10 +1,8 @@
 /**
  * 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
+ * Discovers agent definitions from compatible project and user locations.
+ * Precedence: project .pi/agents > project .agents > ~/.agents > legacy user > builtin.
  */
 
 import * as fs from "node:fs";
@@ -12,17 +10,28 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseFrontmatter } from "./frontmatter.ts";
+import { parseTeammateThinkingLevel, type TeammateThinkingLevel } from "../shared/thinking.ts";
 
 type SystemPromptMode = "append" | "replace";
 export type AgentSource = "builtin" | "user" | "project";
 
+export const BUILTIN_AGENT_NAMES = ["delegate", "explorer", "goal-verifier", "workflow"] as const;
+export type BuiltinAgentName = (typeof BUILTIN_AGENT_NAMES)[number];
+
+const LEGACY_AGENT_ALIASES: Readonly<Record<string, BuiltinAgentName>> = {
+  coordinator: "workflow",
+};
+
+const AGENT_CATALOG_START_MARKER = "<!-- teammate-agent-catalog:start -->";
+const AGENT_CATALOG_END_MARKER = "<!-- teammate-agent-catalog:end -->";
+
 export interface AgentConfig {
   name: string;
   description: string;
   tools?: string[];
   model?: string;
   fallbackModels?: string[];
-  thinking?: string;
+  thinking?: TeammateThinkingLevel;
   systemPromptMode: SystemPromptMode;
   inheritProjectContext: boolean;
   inheritSkills: boolean;
@@ -38,6 +47,11 @@ export interface AgentSummary {
   source: AgentSource;
 }
 
+export interface AgentCatalogSnapshot {
+  signature: string;
+  systemPrompt: string;
+}
+
 const BUILTIN_AGENTS_DIR = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
   "..",
@@ -123,7 +137,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
       tools: rawTools && rawTools.length > 0 ? rawTools : undefined,
       model: frontmatter.model,
       fallbackModels: rawFallbackModels && rawFallbackModels.length > 0 ? rawFallbackModels : undefined,
-      thinking: frontmatter.thinking,
+      thinking: parseTeammateThinkingLevel(frontmatter.thinking),
       systemPromptMode,
       inheritProjectContext,
       inheritSkills,
@@ -137,27 +151,43 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
   return agents;
 }
 
+export function isBuiltinAgentName(name: string): name is BuiltinAgentName {
+  return (BUILTIN_AGENT_NAMES as readonly string[]).includes(name);
+}
+
+function isReservedAgentName(name: string): boolean {
+  return isBuiltinAgentName(name) || Object.hasOwn(LEGACY_AGENT_ALIASES, name);
+}
+
+function canonicalAgentName(name: string): string {
+  return LEGACY_AGENT_ALIASES[name] ?? name;
+}
+
 /**
  * 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(),
+export function discoverAgents(cwd: string, homeDir = os.homedir()): AgentConfig[] {
+  const legacyUserAgentsDir = path.join(
+    homeDir,
     ".pi",
     "agent",
     "extensions",
     "teammate",
     "agents",
   );
+  const userAgentsDir = path.join(homeDir, ".agents");
 
-  // Find project root (first ancestor with .pi/ directory)
-  let projectAgentsDir: string | null = null;
+  // Find the nearest ancestor containing either supported project directory.
+  let projectPiAgentsDir: string | null = null;
+  let projectCompatAgentsDir: string | null = null;
   let currentDir = cwd;
   while (true) {
-    const piDir = path.join(currentDir, ".pi", "agents");
-    if (fs.existsSync(piDir)) {
-      projectAgentsDir = piDir;
+    const piAgentsDir = path.join(currentDir, ".pi", "agents");
+    const compatAgentsDir = path.join(currentDir, ".agents");
+    if (fs.existsSync(piAgentsDir) || fs.existsSync(compatAgentsDir)) {
+      projectPiAgentsDir = fs.existsSync(piAgentsDir) ? piAgentsDir : null;
+      projectCompatAgentsDir = fs.existsSync(compatAgentsDir) ? compatAgentsDir : null;
       break;
     }
     const parentDir = path.dirname(currentDir);
@@ -165,17 +195,36 @@ export function discoverAgents(cwd: string): AgentConfig[] {
     currentDir = parentDir;
   }
 
-  const builtinAgents = loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin");
-  const userAgents = loadAgentsFromDir(userAgentsDir, "user");
-  const projectAgents = projectAgentsDir
-    ? loadAgentsFromDir(projectAgentsDir, "project")
+  const builtinByName = new Map(
+    loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin")
+      .filter((agent) => isBuiltinAgentName(agent.name))
+      .map((agent) => [agent.name, agent]),
+  );
+  const builtinAgents = BUILTIN_AGENT_NAMES
+    .map((name) => builtinByName.get(name))
+    .filter((agent): agent is AgentConfig => agent !== undefined);
+  const loadCustomAgents = (dir: string, source: AgentSource): AgentConfig[] =>
+    loadAgentsFromDir(dir, source)
+    .filter((agent) => !isReservedAgentName(agent.name));
+
+  // Builtin names are reserved so project/user definitions cannot silently
+  // replace the stable general, exploration, and DAG orchestration roles.
+  const legacyUserAgents = loadCustomAgents(legacyUserAgentsDir, "user");
+  const userAgents = loadCustomAgents(userAgentsDir, "user");
+  const projectCompatAgents = projectCompatAgentsDir
+    ? loadCustomAgents(projectCompatAgentsDir, "project")
+    : [];
+  const projectPiAgents = projectPiAgentsDir
+    ? loadCustomAgents(projectPiAgentsDir, "project")
     : [];
 
-  // Merge: project > user > builtin
+  // Merge from lowest to highest priority.
   const agentMap = new Map<string, AgentConfig>();
   for (const agent of builtinAgents) agentMap.set(agent.name, agent);
+  for (const agent of legacyUserAgents) 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);
+  for (const agent of projectCompatAgents) agentMap.set(agent.name, agent);
+  for (const agent of projectPiAgents) agentMap.set(agent.name, agent);
 
   return Array.from(agentMap.values());
 }
@@ -188,7 +237,8 @@ export function resolveAgent(
   agentName: string,
 ): AgentConfig | undefined {
   const agents = discoverAgents(cwd);
-  return agents.find((a) => a.name === agentName);
+  const canonicalName = canonicalAgentName(agentName);
+  return agents.find((a) => a.name === canonicalName);
 }
 
 /** Return resolved role metadata without exposing the role prompt body. */
@@ -222,3 +272,60 @@ export function formatAgentCatalog(
 
   return lines.join("\n");
 }
+
+/** Build the compact role directory appended to the active parent prompt. */
+export function createAgentCatalogSnapshot(
+  cwd: string,
+  maxDescriptionLength = 160,
+): AgentCatalogSnapshot {
+  const summaries = listAgentSummaries(cwd);
+  const byName = new Map(summaries.map((agent) => [agent.name, agent]));
+  const builtins = BUILTIN_AGENT_NAMES
+    .map((name) => byName.get(name))
+    .filter((agent): agent is AgentSummary => agent !== undefined);
+  const discovered = summaries
+    .filter((agent) => !isBuiltinAgentName(agent.name));
+
+  const formatLine = (agent: AgentSummary): string => {
+    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}: ${description}`;
+  };
+
+  const lines = [
+    AGENT_CATALOG_START_MARKER,
+    "# Available Teammate Agents",
+    "",
+    "Built-in roles:",
+    ...builtins.map(formatLine),
+    "",
+    "Discovered project and user roles:",
+    ...(discovered.length > 0 ? discovered.map(formatLine) : ["(none)"]),
+  ];
+
+  lines.push(
+    "",
+    "Use the exact agent name. Unknown names are invalid. Agent prompt bodies are loaded only after a role is selected.",
+    AGENT_CATALOG_END_MARKER,
+  );
+
+  return {
+    signature: summaries
+      .map((agent) => `${agent.name}:${agent.source}:${agent.description}`)
+      .join("\n"),
+    systemPrompt: lines.join("\n"),
+  };
+}
+
+/** Replace an existing role directory or append a fresh one to the prompt. */
+export function appendAgentCatalog(systemPrompt: string, cwd: string): string {
+  const snapshot = createAgentCatalogSnapshot(cwd);
+  const start = systemPrompt.indexOf(AGENT_CATALOG_START_MARKER);
+  const end = systemPrompt.indexOf(AGENT_CATALOG_END_MARKER);
+  if (start >= 0 && end >= start) {
+    return `${systemPrompt.slice(0, start)}${snapshot.systemPrompt}${systemPrompt.slice(end + AGENT_CATALOG_END_MARKER.length)}`;
+  }
+  return `${systemPrompt}\n\n${snapshot.systemPrompt}`;
+}