@fradser/pi-agent-teams 0.5.1 → 0.5.3

package/src/spawner.ts

@@ -8,13 +8,17 @@
  */
 
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { extractTextContent } from "@fradser/pi-kit";
+import { extractTextContent, resolvePiCli } from "@fradser/pi-kit";
 import type { WorkerUsage } from "./types";
 
+/** High default safety cap; explicit task budgets can still be lower. */
+export const DEFAULT_TURN_BUDGET = 100;
+
 /**
  * Build the one-task execution prompt for a spawned worker.
  *
@@ -26,9 +30,12 @@ export function buildAutonomousPrompt(opts: {
   role: string;
   prompt: string;
   taskId?: string;
-  timeoutSec: number;
+  turnBudget?: number;
 }): string {
   const taskLine = `\nAssigned task: [${opts.taskId}].\nWhen finished, you MUST call teammate_message with status="completed" to submit your FULL final deliverable.`;
+  const budgetLine = opts.turnBudget
+    ? `4. You have a maximum of ${opts.turnBudget} assistant turn(s) — manage your turn budget, avoid unnecessary exploration, and deliver your final message before the budget is exhausted.`
+    : `4. There is no turn budget — work until the task is complete. Do not rush or truncate your work.`;
 
   return `You are a FULLY AUTONOMOUS teammate named "${opts.name}" (agent: ${opts.role}) in a pi multi-agent team run.
 
@@ -40,7 +47,7 @@ YOUR ROLE IN THIS RUN:
 1. Work directly on your assigned scope and declared paths. DAG upstream results are ALREADY injected into this prompt below; do not poll for them.
 2. Report plans, progress, and blockers with teammate_message. When finished, call teammate_message with status="completed" and put your FULL deliverable in the body. If blocked or failed, use status="failed" and explain the error.
 3. There is no peer or leader-to-worker message channel. Make decisions within the assigned task and report blockers instead of waiting for a reply.
-4. The hard wall-clock cap is ${opts.timeoutSec}s — manage your time budget, avoid unnecessary exploration, and deliver your final message before the deadline.
+${budgetLine}
 
 BOUND CAPABILITIES:
 - teammate_message reports progress or a final deliverable to the team leader.`;
@@ -59,10 +66,10 @@ export interface SpawnPiWorkerOptions {
   env?: Record<string, string | undefined>;
   /** Working directory for the child (defaults to the parent's cwd). */
   cwd?: string;
-  /** Kill the worker after this many milliseconds (undefined = no timeout). */
-  timeoutMs?: number;
-  /** Output parsing mode. "json" (default) parses usage from JSONL output. */
-  mode?: "json" | "text";
+  /** Maximum assistant turns for this worker (defaults to DEFAULT_TURN_BUDGET). */
+  turnBudget?: number;
+  /** Output parsing mode. RPC keeps stdin available for runtime steering. */
+  mode?: "json" | "rpc" | "text";
   /** Called whenever JSON-mode worker output reveals live model or tool activity. */
   onUpdate?: (update: WorkerProgressUpdate) => void;
   /** Called once with the captured output when the child exits. */
@@ -78,7 +85,7 @@ export interface WorkerProcessResult {
   stdout: string;
   stderr: string;
   usage?: WorkerUsage;
-  timedOut: boolean;
+  turnBudgetExceeded?: boolean;
 }
 
 /** Live state extracted from a spawned worker's JSON-mode output. */
@@ -91,13 +98,13 @@ export interface WorkerProgressUpdate {
 }
 
 /** A worker only succeeds after a normal zero exit; signals are failures. */
-export function isSuccessfulWorkerExit(result: Pick<WorkerProcessResult, "exitCode" | "signal" | "timedOut">): boolean {
-  return result.exitCode === 0 && result.signal === null && !result.timedOut;
+export function isSuccessfulWorkerExit(result: Pick<WorkerProcessResult, "exitCode" | "signal">): boolean {
+  return result.exitCode === 0 && result.signal === null;
 }
 
-/** A reported completion remains successful when the harness closes it or teardown observes a signal/timeout. */
+/** A reported completion remains successful when the harness closes it or teardown observes a signal. */
 export function isCompletedWorkerExit(
-  result: Pick<WorkerProcessResult, "exitCode" | "signal" | "timedOut">,
+  result: Pick<WorkerProcessResult, "exitCode" | "signal">,
   reportedCompleted = false,
 ): boolean {
   return isSuccessfulWorkerExit(result) || reportedCompleted;
@@ -152,6 +159,14 @@ export class CancellationIntents {
 /** Live workers by teammate name — lets the panel interrupt/stop a running worker. */
 const workers = new Map<string, ReturnType<typeof spawn>>();
 
+/** Send a steering message to an RPC worker without adding a peer mailbox. */
+export function sendWorkerSteer(name: string, message: string): boolean {
+  const child = workers.get(name);
+  if (!child?.stdin || child.stdin.destroyed || !child.stdin.writable) return false;
+  child.stdin.write(`${JSON.stringify({ type: "steer", message })}\n`);
+  return true;
+}
+
 function isChildRunning(child: ReturnType<typeof spawn>): boolean {
   return child.exitCode === null && child.signalCode === null;
 }
@@ -230,9 +245,20 @@ export async function terminateAllWorkers(graceMs = CANCEL_GRACE_MS): Promise<vo
 const TASK_ARG_LIMIT = 8000;
 const OUTPUT_CAP = 16_000;
 
+function appendCapped(chunks: string[], chunk: string, cap: number): void {
+  chunks.push(chunk);
+  let total = chunks.reduce((sum, value) => sum + value.length, 0);
+  while (total > cap && chunks.length > 1) {
+    total -= chunks.shift()?.length ?? 0;
+  }
+  if (total > cap && chunks.length === 1) chunks[0] = chunks[0].slice(-cap);
+}
+
 type JsonEvent = {
   type?: string;
+  toolCallId?: string;
   toolName?: string;
+  args?: unknown;
   assistantMessageEvent?: {
     type?: string;
     delta?: string;
@@ -262,18 +288,53 @@ export function parseWorkerOutput(stdout: string): { text: string; usage?: Worke
   return { text: state.text.trim(), usage: state.usage };
 }
 
+/** Parse the latest live progress state from a worker JSON stream. */
+export function parseWorkerProgress(stdout: string): WorkerProgressUpdate {
+  const state = createWorkerStreamState();
+  for (const line of stdout.split("\n")) applyWorkerJsonLine(state, line);
+  return {
+    text: truncate(state.text, OUTPUT_CAP),
+    activeTool: state.activeTool,
+    liveThinking: truncate(state.thinking, OUTPUT_CAP),
+    turns: state.turns,
+    finalResponse: state.finalResponse,
+  };
+}
+
 interface WorkerStreamState {
   text: string;
   thinking: string;
   toolcallArgs: string;
   activeTool?: string;
+  activeToolCallId?: string;
+  activeTools: Map<string, string>;
   turns: number;
   finalResponse?: boolean;
   usage?: WorkerUsage;
 }
 
 function createWorkerStreamState(): WorkerStreamState {
-  return { text: "", thinking: "", toolcallArgs: "", turns: 0 };
+  return { text: "", thinking: "", toolcallArgs: "", activeTools: new Map(), turns: 0 };
+}
+
+function setActiveTool(state: WorkerStreamState, toolCallId: string | undefined, label: string): void {
+  const key = toolCallId ?? `tool-${state.activeTools.size}`;
+  state.activeTools.set(key, label);
+  state.activeToolCallId = key;
+  state.activeTool = label;
+}
+
+function clearActiveTool(state: WorkerStreamState, toolCallId: string | undefined): void {
+  if (toolCallId) state.activeTools.delete(toolCallId);
+  else state.activeTools.clear();
+  const next = [...state.activeTools.entries()].at(-1);
+  state.activeToolCallId = next?.[0];
+  state.activeTool = next?.[1];
+}
+
+function toolExecutionLabel(toolName: string | undefined, args: unknown): string {
+  const serialized = typeof args === "string" ? args : JSON.stringify(args ?? {});
+  return toolcallLabel(serialized) ?? toolName ?? "tool";
 }
 
 /** Human-readable label from a partially streamed tool-call argument JSON. */
@@ -304,9 +365,31 @@ function applyWorkerJsonLine(state: WorkerStreamState, line: string): boolean {
   } catch {
     return false;
   }
+  if (event.type === "message_start" && event.message?.role === "assistant") {
+    state.thinking = "";
+    state.activeTool = undefined;
+    state.activeToolCallId = undefined;
+    state.activeTools.clear();
+    return true;
+  }
+  if (event.type === "tool_execution_start") {
+    setActiveTool(state, event.toolCallId, toolExecutionLabel(event.toolName, event.args));
+    return true;
+  }
+  if (event.type === "tool_execution_end") {
+    if (!event.toolCallId || state.activeTools.has(event.toolCallId)) {
+      clearActiveTool(state, event.toolCallId);
+      return true;
+    }
+    return false;
+  }
   if (event.type !== "message_update") {
     if (event.type !== "message_end" || event.message?.role !== "assistant") return false;
     state.turns++;
+    state.activeTool = undefined;
+    state.activeToolCallId = undefined;
+    state.activeTools.clear();
+    state.thinking = "";
     if (event.message.stopReason === "stop") state.finalResponse = true;
     const parts = extractTextContent(event.message.content, "");
     if (parts.trim()) state.text = parts;
@@ -327,14 +410,18 @@ function applyWorkerJsonLine(state: WorkerStreamState, line: string): boolean {
   if (!sub) return false;
   switch (sub.type) {
     case "text_delta":
+      state.activeTool = undefined;
       state.text += sub.delta ?? "";
       return true;
     case "thinking_delta":
+      state.activeTool = undefined;
       state.thinking += sub.delta ?? "";
       return true;
     case "toolcall_start":
       state.toolcallArgs = "";
       state.activeTool = undefined;
+      state.activeToolCallId = undefined;
+      state.activeTools.clear();
       return true;
     case "toolcall_delta": {
       state.toolcallArgs += sub.delta ?? "";
@@ -342,14 +429,14 @@ function applyWorkerJsonLine(state: WorkerStreamState, line: string): boolean {
       if (label) state.activeTool = label;
       return true;
     }
-    case "toolcall_end": {
-      const tc = (sub as { toolCall?: { name?: string } }).toolCall;
-      // Prefer the richer delta-derived label (e.g. "bash: echo hello");
-      // fall back to the bare tool name only when no label could be parsed.
-      if (tc?.name && !state.activeTool) state.activeTool = tc.name;
+    case "toolcall_end":
+      // The tool call has been emitted; execution events now own the current
+      // activity label until the tool result arrives.
       state.toolcallArgs = "";
+      state.activeTool = undefined;
+      state.activeToolCallId = undefined;
+      state.activeTools.clear();
       return true;
-    }
     default:
       return false;
   }
@@ -366,61 +453,11 @@ function truncate(text: string, cap: number): string {
   return `${text.slice(0, cap)}\n... [truncated ${text.length - cap} chars]`;
 }
 
-export interface PiCliResolution {
-  /** Command to execute — either a runtime (node/bun) or a `pi` binary. */
-  command: string;
-  /** Leading args: the CLI script path when running via a runtime, else empty. */
-  args: string[];
-}
-
-/** Whether a file is the pi coding-agent CLI script (verified against its package manifest). */
-function isPiPackageScript(filePath: string): boolean {
-  try {
-    const resolved = fs.realpathSync(filePath);
-    if (!/\.(mjs|cjs|js)$/.test(resolved)) return false;
-    let dir = path.dirname(resolved);
-    while (dir !== path.dirname(dir)) {
-      const pkgPath = path.join(dir, "package.json");
-      if (fs.existsSync(pkgPath)) {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { name?: unknown };
-        return pkg.name === "@earendil-works/pi-coding-agent";
-      }
-      dir = path.dirname(dir);
-    }
-  } catch {
-    // Unreadable paths are simply not candidates.
-  }
-  return false;
-}
-
 /**
- * Resolve how to launch a worker Pi process.
- *
- * Resolution order:
- *   1. `process.argv[1]` — the current Pi process entry, verified against the
- *      package manifest (avoids mistaking unrelated scripts for the CLI).
- *   2. The installed `@earendil-works/pi-coding-agent` package's `dist/cli.js`.
- *   3. A `pi` binary on PATH (best effort).
+ * Resolve how to launch a Pi CLI process.
+ * Re-exported from pi-kit for backward compatibility.
  */
-export function resolvePiCli(): PiCliResolution {
-  const argv1 = process.argv[1];
-  if (argv1 && isPiPackageScript(argv1)) {
-    return { command: process.execPath, args: [path.resolve(argv1)] };
-  }
-
-  try {
-    const entry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
-    const packageRoot = path.dirname(path.dirname(entry));
-    const cliPath = path.join(packageRoot, "dist", "cli.js");
-    if (fs.existsSync(cliPath)) {
-      return { command: process.execPath, args: [cliPath] };
-    }
-  } catch {
-    // Package resolution is best-effort; fall through to PATH.
-  }
-
-  return { command: "pi", args: [] };
-}
+export { resolvePiCli } from "@fradser/pi-kit";
 
 /**
  * Spawn a child Pi process that executes the task description in
@@ -431,7 +468,16 @@ export function spawnPiWorker(options: SpawnPiWorkerOptions): SpawnedWorker | {
   // resolvePiCli always resolves (worst case a "pi" binary on PATH); a missing
   // binary surfaces later as a child "error" event through onError.
   const cli = resolvePiCli();
-  const args: string[] = [...cli.args, "--print", "--mode", "json", "--no-session"];
+  const workerExtension = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "index.ts");
+  const mode = options.mode ?? "json";
+  const args: string[] = [
+    ...cli.args,
+    ...(mode === "rpc" ? ["--mode", "rpc"] : ["--print", "--mode", mode]),
+    "--no-session",
+    "--no-extensions",
+    "--extension",
+    workerExtension,
+  ];
   if (options.model) args.push("--model", options.model);
   // Capability tools cannot be removed; execution tools are selected by the
   // leader from the teammate's explicit configuration or role default.
@@ -455,14 +501,14 @@ export function spawnPiWorker(options: SpawnPiWorkerOptions): SpawnedWorker | {
     error: error instanceof Error ? error.message : String(error),
   });
 
+  let taskText = `Task: ${options.description}`;
   try {
-    const taskText = `Task: ${options.description}`;
-    if (taskText.length > TASK_ARG_LIMIT) {
+    if (mode !== "rpc" && taskText.length > TASK_ARG_LIMIT) {
       tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "teammate-"));
       const taskFile = path.join(tempDir, "task.md");
       fs.writeFileSync(taskFile, taskText, { mode: 0o600 });
       args.push(`@${taskFile}`);
-    } else {
+    } else if (mode !== "rpc") {
       args.push(taskText);
     }
   } catch (error) {
@@ -475,7 +521,7 @@ export function spawnPiWorker(options: SpawnPiWorkerOptions): SpawnedWorker | {
     child = spawn(cli.command, args, {
       cwd: options.cwd,
       env: { ...process.env, ...options.env },
-      stdio: ["ignore", "pipe", "pipe"],
+      stdio: [mode === "rpc" ? "pipe" : "ignore", "pipe", "pipe"],
     });
   } catch (error) {
     cleanupTempDir();
@@ -483,12 +529,16 @@ export function spawnPiWorker(options: SpawnPiWorkerOptions): SpawnedWorker | {
   }
   if (options.workerName) workers.set(options.workerName, child);
 
+  if (mode === "rpc") {
+    child.stdin?.write(`${JSON.stringify({ type: "prompt", id: randomUUID(), message: taskText })}\n`);
+  }
+
   const stdoutChunks: string[] = [];
   const stderrChunks: string[] = [];
   const streamState = createWorkerStreamState();
   let stdoutBuffer = "";
-  let timedOut = false;
   let settled = false;
+  let turnBudgetExceeded = false;
   const emitProgress = () => options.onUpdate?.({
     text: truncate(streamState.text, OUTPUT_CAP),
     activeTool: streamState.activeTool,
@@ -496,29 +546,25 @@ export function spawnPiWorker(options: SpawnPiWorkerOptions): SpawnedWorker | {
     turns: streamState.turns,
     finalResponse: streamState.finalResponse,
   });
-  child.stdout.on("data", (chunk: Buffer) => {
+  child.stdout?.on("data", (chunk: Buffer) => {
     const text = chunk.toString();
-    stdoutChunks.push(text);
+    appendCapped(stdoutChunks, text, OUTPUT_CAP * 2);
     stdoutBuffer += text;
     const lines = stdoutBuffer.split("\n");
     stdoutBuffer = lines.pop() ?? "";
     let changed = false;
-    for (const line of lines) changed = applyWorkerJsonLine(streamState, line) || changed;
+    for (const line of lines) {
+      changed = applyWorkerJsonLine(streamState, line) || changed;
+      if (options.turnBudget && streamState.turns >= options.turnBudget && !streamState.finalResponse && !turnBudgetExceeded) {
+        turnBudgetExceeded = true;
+        void terminateChildProcess(child);
+      }
+    }
     if (changed) emitProgress();
   });
-  child.stderr.on("data", (chunk: Buffer) => stderrChunks.push(chunk.toString()));
-
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  if (options.timeoutMs) {
-    timer = setTimeout(() => {
-      timedOut = true;
-      child.kill("SIGKILL");
-    }, options.timeoutMs);
-    timer.unref?.();
-  }
+  child.stderr?.on("data", (chunk: Buffer) => appendCapped(stderrChunks, chunk.toString(), OUTPUT_CAP * 2));
 
   child.on("error", (error) => {
-    if (timer) clearTimeout(timer);
     cleanupTempDir();
     settled = true;
     if (options.workerName && workers.get(options.workerName) === child) workers.delete(options.workerName);
@@ -526,7 +572,6 @@ export function spawnPiWorker(options: SpawnPiWorkerOptions): SpawnedWorker | {
   });
 
   child.on("close", (code, signal) => {
-    if (timer) clearTimeout(timer);
     cleanupTempDir();
     // A spawn failure already reported via onError (Node fires error then
     // close) — do not double-report through onExit, which would let a failed
@@ -534,12 +579,12 @@ export function spawnPiWorker(options: SpawnPiWorkerOptions): SpawnedWorker | {
     if (settled) return;
     if (options.workerName && workers.get(options.workerName) === child) workers.delete(options.workerName);
     const rawStdout = stdoutChunks.join("");
-    const parsed = (options.mode ?? "json") === "json"
-      ? parseWorkerOutput(rawStdout)
-      : { text: rawStdout.trim(), usage: undefined };
+    const parsed = mode === "text"
+      ? { text: rawStdout.trim(), usage: undefined }
+      : parseWorkerOutput(rawStdout);
     const stdout = truncate(parsed.text, OUTPUT_CAP);
     const stderr = truncate(stderrChunks.join("").trim(), OUTPUT_CAP);
-    options.onExit({ pid: child.pid ?? 0, exitCode: code, signal, stdout, stderr, usage: parsed.usage, timedOut });
+    options.onExit({ pid: child.pid ?? 0, exitCode: code, signal, stdout, stderr, usage: parsed.usage, turnBudgetExceeded });
   });
 
   return { pid: child.pid ?? 0 };

package/src/state.ts

@@ -84,6 +84,28 @@ export function normalizeNodePaths(paths: string[]): { ok: true; paths: string[]
 
 // ── Run creation ──────────────────────────────────────────────────
 
+export const MAX_STRUCTURED_OUTPUT_BYTES = 64 * 1024;
+export const MAX_STRUCTURED_OUTPUT_DEPTH = 8;
+export const MAX_FANOUT_ITEMS = 32;
+
+export function structuredOutputSize(value: unknown): number {
+  return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+
+export function structuredOutputDepth(value: unknown): number {
+  if (!value || typeof value !== "object") return 0;
+  if (Array.isArray(value)) return 1 + Math.max(0, ...value.map(structuredOutputDepth));
+  return 1 + Math.max(0, ...Object.values(value as Record<string, unknown>).map(structuredOutputDepth));
+}
+
+export function validateStructuredOutput(value: unknown): string | undefined {
+  let serialized: string;
+  try { serialized = JSON.stringify(value); } catch { return "Structured output must be JSON-serializable."; }
+  if (Buffer.byteLength(serialized, "utf8") > MAX_STRUCTURED_OUTPUT_BYTES) return `Structured output exceeds ${MAX_STRUCTURED_OUTPUT_BYTES} bytes.`;
+  if (structuredOutputDepth(value) > MAX_STRUCTURED_OUTPUT_DEPTH) return `Structured output exceeds depth ${MAX_STRUCTURED_OUTPUT_DEPTH}.`;
+  return undefined;
+}
+
 export interface RunNodeInput {
   id: string;
   agent: string;
@@ -91,7 +113,10 @@ export interface RunNodeInput {
   paths: string[];
   access: Node["access"];
   model?: string;
-  timeoutMs?: number;
+  mode?: Node["mode"];
+  turnBudget?: number;
+  forkContext?: string[];
+  inputBindings?: Record<string, string>;
   dependsOn: string[];
 }
 
@@ -122,7 +147,6 @@ export function createRun(
     concurrency: number;
     worktree: boolean;
     background?: boolean;
-    timeoutMs?: number;
     summarize?: boolean;
     summaryAgent?: string;
     nodes: RunNodeInput[];
@@ -146,6 +170,15 @@ export function createRun(
         return { ok: false, error: `Node "${node.id}" depends on unknown node "${dep}".` };
       }
     }
+    for (const source of Object.values(node.inputBindings ?? {})) {
+      const dependencyId = source.split("#", 1)[0];
+      if (!node.dependsOn.includes(dependencyId)) {
+        return { ok: false, error: `Node "${node.id}" input binding must reference a dependency: "${source}".` };
+      }
+    }
+    if (node.forkContext?.some((dependencyId) => !node.dependsOn.includes(dependencyId))) {
+      return { ok: false, error: `Node "${node.id}" forkContext must reference dependencies only.` };
+    }
     normalized.push({
       id: node.id,
       workerKey: "", // filled after the run id is assigned
@@ -154,7 +187,10 @@ export function createRun(
       paths: normalizedPaths.paths,
       access: node.access,
       model: node.model,
-      timeoutMs: node.timeoutMs,
+      mode: node.mode,
+      turnBudget: node.turnBudget,
+      forkContext: node.forkContext ? [...new Set(node.forkContext)] : undefined,
+      inputBindings: node.inputBindings ? { ...node.inputBindings } : undefined,
       dependsOn: [...new Set(node.dependsOn)],
       status: "pending",
       createdAt: Date.now(),
@@ -208,8 +244,6 @@ export function createRun(
     concurrency: input.concurrency,
     worktree: input.worktree,
     background: input.background ?? true,
-    timeoutMs: input.timeoutMs,
-    deadlineAt: input.timeoutMs ? Date.now() + input.timeoutMs : undefined,
     nodes: {},
     createdAt: Date.now(),
     updatedAt: Date.now(),
@@ -526,40 +560,6 @@ export function cancelNode(runId: string, nodeId: string): { ok: boolean; runnin
   return { ok: true, runningNodeIds };
 }
 
-/**
- * Fail a run for exceeding its hard wall-clock cap: pending nodes are
- * cancelled and the run is marked failed; live workers must be terminated by
- * the caller.
- */
-export function failRunTimeout(runId: string, errorMessage: string): { ok: boolean; runningNodeIds: string[]; error?: string } {
-  const run = state.runs[runId];
-  if (!run) return { ok: false, runningNodeIds: [], error: `Run "${runId}" not found.` };
-  if (run.status !== "running") return { ok: false, runningNodeIds: [], error: `Run "${runId}" is already ${run.status}.` };
-  const runningNodeIds: string[] = [];
-  for (const node of Object.values(run.nodes)) {
-    if (node.status === "running") {
-      // The node's worker is terminated by the caller; clearing the spawn means
-      // its late close event cannot pollute a retried (reset) node.
-      node.status = "failed";
-      node.errorMessage = errorMessage;
-      node.completedAt = Date.now();
-      node.spawn = undefined;
-      node.updatedAt = Date.now();
-      runningNodeIds.push(node.id);
-    } else if (node.status === "pending") {
-      node.status = "cancelled";
-      node.completedAt = Date.now();
-      node.updatedAt = Date.now();
-    }
-  }
-  run.status = "failed";
-  run.errorMessage = errorMessage;
-  run.finishedAt = Date.now();
-  run.updatedAt = Date.now();
-  markStateDirty();
-  return { ok: true, runningNodeIds };
-}
-
 /**
  * Reset failed and cancelled nodes of a settled run back to pending so the
  * run can be re-dispatched. Completed nodes are retained. The run returns to
@@ -612,6 +612,7 @@ export function retryRun(runId: string, nodeIds?: string[]): { ok: boolean; rese
     node.errorMessage = undefined;
     node.completedAt = undefined;
     node.spawn = undefined;
+    node.nodeFollowUpSent = undefined;
     node.updatedAt = Date.now();
   }
   const reset = [...resetSet];
@@ -620,9 +621,6 @@ export function retryRun(runId: string, nodeIds?: string[]): { ok: boolean; rese
   run.finishedAt = undefined;
   run.completionNotified = false;
   run.settledMessageSent = false;
-  // Re-arm the run-level cap: a stale deadline would re-fail the retried run
-  // on the very next poll.
-  run.deadlineAt = run.timeoutMs ? Date.now() + run.timeoutMs : undefined;
   run.updatedAt = Date.now();
   markStateDirty();
   return { ok: true, reset };

package/src/tools.ts

@@ -10,8 +10,9 @@ import {
   scheduleRun,
   type DispatchCtx,
 } from "./run-machine";
-import { createRun, getRun, getSummary, markRunCompletionDelivered, retryRun } from "./state";
-import { TeammateCancelParams, TeammateRetryParams, TeammateRunParams } from "./types";
+import { createRun, getRun, getSummary, listNodes, markRunCompletionDelivered, retryRun, MAX_FANOUT_ITEMS } from "./state";
+import { TeammateCancelParams, TeammateFanoutParams, TeammateLeaderMessageParams, TeammateRetryParams, TeammateRunParams } from "./types";
+import { sendWorkerSteer } from "./spawner";
 import { ensureTeamWidget, openTeamConsole, refreshTeamUI } from "./ui";
 
 function dispatchContext(ctx: ExtensionContext): DispatchCtx {
@@ -48,6 +49,10 @@ async function gatherForeground(runId: string, signal: AbortSignal | undefined):
   return buildRunSummary(runId);
 }
 
+function resolveTargetNode(target: string): { node: import("./types").Node } | undefined {
+  return listNodes().map((node) => ({ node })).find(({ node }) => node.id === target || node.workerKey === target);
+}
+
 export function registerLeaderTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "teammate_run",
@@ -71,7 +76,6 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
         concurrency: params.concurrency ?? 4,
         worktree: params.worktree ?? false,
         background: params.background ?? true,
-        timeoutMs: params.timeoutMs,
         summarize: params.summarize,
         summaryAgent: params.summaryAgent,
         nodes: params.tasks.map((task) => ({
@@ -81,7 +85,10 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
           paths: task.paths,
           access: task.access ?? "read",
           model: task.model,
-          timeoutMs: task.timeoutMs,
+          mode: task.mode,
+          turnBudget: task.turnBudget,
+          forkContext: task.forkContext,
+          inputBindings: task.inputBindings,
           dependsOn: task.dependsOn ?? [],
         })),
       });
@@ -101,6 +108,58 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerTool({
+    name: "teammate_fanout",
+    promptSnippet: "Fan out a completed node's structured array output",
+    label: "Fan Out Tasks",
+    description: "Leader-only bounded fanout. Validates a completed structured array before creating a separate child run.",
+    parameters: TeammateFanoutParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const source = getRun(params.runId)?.nodes[params.nodeId];
+      if (!source || source.status !== "completed") throw new Error("Fanout source must be a completed node.");
+      if (!Array.isArray(source.structuredOutput)) throw new Error("Fanout source must be a structured array.");
+      if (source.structuredOutput.length > MAX_FANOUT_ITEMS) throw new Error(`Fanout is limited to ${MAX_FANOUT_ITEMS} items.`);
+      const cwd = ctx.cwd ?? process.cwd();
+      const dctx = dispatchContext(ctx);
+      ensureRunContext(dctx);
+      const tasks = source.structuredOutput.map((item, index) => ({
+        id: `${params.nodeId}-${index + 1}`,
+        agent: params.agent,
+        prompt: `${params.prompt}\n\nFanout item:\n${JSON.stringify(item)}`,
+        paths: params.paths,
+        access: params.access ?? "read" as const,
+        model: params.model,
+        mode: "json" as const,
+        turnBudget: params.turnBudget,
+        dependsOn: [],
+      }));
+      if (!resolveAgent(params.agent, cwd)) throw new Error(`Agent "${params.agent}" not found.`);
+      const created = createRun({ cwd, concurrency: params.concurrency ?? 4, worktree: false, background: params.background ?? true, summarize: true, nodes: tasks });
+      if (!created.ok) throw new Error(created.error ?? "Failed to create fanout run.");
+      publishStateSnapshot();
+      scheduleRun(created.run.id, dctx);
+      return { content: [{ type: "text", text: `Started fanout run [${created.run.id}] with ${tasks.length} item(s).` }], details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "teammate_message",
+    promptSnippet: "Send a runtime steer to a running RPC teammate",
+    label: "Message Teammate",
+    description: "Leader-only runtime steer. Sends through the existing teammate_message protocol to a running RPC worker; no message is available for JSON-mode workers.",
+    parameters: TeammateLeaderMessageParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      if (!params.target.includes(":")) throw new Error("Target must be a run-qualified worker key.");
+      const target = resolveTargetNode(params.target);
+      if (!target?.node.spawn || target.node.status !== "running" || target.node.spawn.mode !== "rpc") {
+        throw new Error("Target worker is not a running RPC teammate.");
+      }
+      const sent = sendWorkerSteer(target.node.workerKey, params.body);
+      if (!sent) throw new Error("Target worker steering stream is unavailable.");
+      return { content: [{ type: "text", text: `Steer sent to ${target.node.workerKey}.` }], details: {} };
+    },
+  });
+
   pi.registerTool({
     name: "teammate_cancel",
     promptSnippet: "Cancel a run and stop its workers",