@fradser/pi-agent-teams 0.5.1 → 0.5.3

package/src/types.ts

@@ -42,13 +42,25 @@ export interface Node {
   access: "read" | "write";
   /** Optional per-node model pin (provider/model). */
   model?: string;
-  /** Optional per-node hard wall-clock cap before the worker is killed. */
-  timeoutMs?: number;
+  /** RPC mode keeps stdin available for runtime steering. */
+  mode?: "json" | "rpc";
+  /** Optional maximum number of assistant turns before the worker is stopped. */
+  turnBudget?: number;
   /** Node ids that must complete before this node may start. */
   dependsOn: string[];
+  /** Named upstream node ids whose results are included as fork context. */
+  forkContext?: string[];
+  /** Named input bindings using `nodeId#/json/pointer` sources. */
+  inputBindings?: Record<string, string>;
   status: NodeStatus;
   result?: string;
+  /** Named structured outputs emitted through teammate_message. */
+  namedOutputs?: Record<string, string>;
+  /** Bounded JSON output emitted through teammate_message for downstream data flow. */
+  structuredOutput?: unknown;
   errorMessage?: string;
+  /** True once the terminal node follow-up has been delivered. */
+  nodeFollowUpSent?: boolean;
   /** Real child-process execution info when this node was spawned. */
   spawn?: SpawnInfo;
   createdAt: number;
@@ -66,11 +78,7 @@ export interface Run {
   worktree: boolean;
   /** background=true returns immediately; false gathers in the tool call. */
   background: boolean;
-  /** Optional run-level hard wall-clock cap before the run fails. */
-  timeoutMs?: number;
-  /** Absolute deadline for timeoutMs, when set. */
-  deadlineAt?: number;
-  /** Run-level failure detail (e.g. run timeout). */
+  /** Run-level failure detail. */
   errorMessage?: string;
   nodes: Record<string, Node>;
   createdAt: number;
@@ -102,6 +110,7 @@ export interface WorkerUsage {
 export interface SpawnInfo {
   /** Per-spawn capability identity, regenerated for every worker process. */
   spawnId: string;
+  mode?: "json" | "rpc";
   pid: number;
   status: SpawnStatus;
   startedAt: number;
@@ -125,7 +134,6 @@ export interface SpawnInfo {
   error?: string;
   /** Token/cost usage reported by the worker, when available. */
   usage?: WorkerUsage;
-  /** True when the worker was killed by the spawn timeout. */
   timedOut?: boolean;
   /** Whether this spawn owns a dedicated Git worktree. */
   isolation?: "worktree" | "none";
@@ -151,6 +159,13 @@ export interface WorkerMessageEvent {
   subject: string;
   body: string;
   status?: "in_progress" | "completed" | "failed";
+  data?: {
+    kind?: "named_output" | "output";
+    name?: string;
+    value?: string;
+    output?: unknown;
+    message?: string;
+  };
 }
 
 export type WorkerEvent = WorkerMessageEvent;
@@ -174,7 +189,10 @@ export const RunTaskSpec = Type.Object({
   }),
   access: Type.Optional(NodeAccess),
   model: Type.Optional(Type.String({ description: "Optional per-node provider/model pin" })),
-  timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Optional per-node hard wall-clock cap before the worker is killed (default: 30 minutes; do not set overly short timeouts for multi-file or reasoning tasks)" })),
+  mode: Type.Optional(Type.Union([Type.Literal("json"), Type.Literal("rpc")], { description: "Worker process mode; rpc enables runtime steering" })),
+  turnBudget: Type.Optional(Type.Integer({ minimum: 1, description: "Optional maximum assistant turns before the worker is stopped (default: 100; high safety cap for edge cases)" })),
+  forkContext: Type.Optional(Type.Array(Type.String(), { description: "Named upstream node ids whose results are included as fork context" })),
+  inputBindings: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Named inputs bound from dependency outputs using nodeId#/json/pointer" })),
 });
 
 /** Dispatch a dependency-aware task graph in one call. */
@@ -187,7 +205,6 @@ export const TeammateRunParams = Type.Object({
   concurrency: Type.Optional(Type.Integer({ minimum: 1, maximum: 32, description: "Max nodes running at once (default: 4)" })),
   worktree: Type.Optional(Type.Boolean({ description: "Run every node in its own git worktree (default: false)" })),
   background: Type.Optional(Type.Boolean({ default: true, description: "Return immediately and deliver one completion follow-up. Default: true — teammates always run in the background; workers message team-leader with deliverables upon completion." })),
-  timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Run-level hard wall-clock cap; the run fails when exceeded (default: none, nodes have their own caps)" })),
   summarize: Type.Optional(Type.Boolean({ description: "Append a __summary node after all leaf nodes. Default: true when the run has more than one user task, false for a single task." })),
   summaryAgent: Type.Optional(Type.String({ description: "Agent used for the summary node when summarize is on (default: observer)" })),
   cwd: Type.Optional(Type.String({ description: "Working directory for this run (default: the session cwd)" })),
@@ -214,6 +231,27 @@ export const TeammateMessageParams = Type.Object({
     Type.Literal("completed"),
     Type.Literal("failed"),
   ], { description: "Optional worker status; use completed or failed for the final deliverable" })),
+  data: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Structured teammate data: named_output or output" })),
+});
+
+/** Leader-only operation that fans out a completed node's structured array output. */
+export const TeammateFanoutParams = Type.Object({
+  runId: Type.String({ description: "Source run id" }),
+  nodeId: Type.String({ description: "Completed source node whose structured output is an array" }),
+  agent: Type.String({ description: "Agent to run for each item" }),
+  prompt: Type.String({ minLength: 1, description: "Task prompt; each item is appended as JSON" }),
+  paths: Type.Array(Type.String(), { minItems: 1, description: "Repository-relative paths for each child run" }),
+  access: Type.Optional(NodeAccess),
+  model: Type.Optional(Type.String()),
+  turnBudget: Type.Optional(Type.Integer({ minimum: 1 })),
+  concurrency: Type.Optional(Type.Integer({ minimum: 1, maximum: 32 })),
+  background: Type.Optional(Type.Boolean({ default: true })),
+});
+
+/** Leader-only runtime steer sent through the existing teammate_message name. */
+export const TeammateLeaderMessageParams = Type.Object({
+  target: Type.String({ description: "Run-qualified worker key, for example run_1:inspect" }),
+  body: Type.String({ minLength: 1, description: "Steering message for the running RPC worker" }),
 });
 
 // ── State snapshot for persistence ────────────────────────────────

package/src/ui.ts

@@ -2,7 +2,7 @@
 
 import { truncateToWidth, Key, matchesKey } from "@earendil-works/pi-tui";
 import { createPiThemeStyle, PI_SPINNER_FRAMES, PI_SPINNER_INTERVAL_MS } from "@fradser/pi-kit";
-import type { ExtensionUIContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import { truncateTail, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from "@earendil-works/pi-coding-agent";
 import {
   clampConsoleScroll, consoleScrollRange, maxConsoleBody, scrollConsoleDetail, wrapConsoleDetail,
@@ -19,18 +19,12 @@ function cap(text: string | undefined, maxBytes = DEFAULT_MAX_BYTES): string {
 }
 
 // ── Team UI: passive widget + full-screen console ──────────────────
-// The widget above the editor is DISPLAY-ONLY. ALL interaction happens in the
+// The widget below the editor is DISPLAY-ONLY. ALL interaction happens in the
 // full-screen Team Console (/teammate), which owns input via ctx.ui.custom.
 
-const TEAM_COLORS = ["accent", "success", "warning", "error", "toolTitle", "mdLink"] as const;
-const PANEL_IDLE_COLLAPSE_MS = 30_000;
-
-let panelRequestRender: (() => void) | undefined;
+const TEAM_COLORS = ["success", "warning", "error", "mdLink"] as const;
 let spinnerTimer: ReturnType<typeof setInterval> | undefined;
 let spinnerFrame = 0;
-let panelLastActivity = 0;
-let panelCollapseTimer: ReturnType<typeof setTimeout> | undefined;
-let widgetRegistered = false;
 
 /** Stable per-node color (independent of row order). */
 function hashName(name: string): number {
@@ -56,14 +50,10 @@ function runningTeammateLabel(node: Node): string {
   // Like the memory package's activity line: show what the worker is doing
   // right now — current tool when one is executing, else its live reasoning,
   // else the latest assistant text.
-  const detail = tool
-    ? ` ${tool}`
-    : thinking
-      ? ` ${truncateToWidth(thinking, 48)}`
-      : live
-        ? ` ${truncateToWidth(live, 48)}`
-        : " working...";
-  return `${frame}${detail}`;
+  const activity = tool
+    ?? (thinking ? truncateToWidth(thinking, 48) : undefined)
+    ?? (live ? truncateToWidth(live, 48) : "Working...");
+  return `${frame} ${activity}`;
 }
 
 function ensureSpinner(): void {
@@ -71,7 +61,6 @@ function ensureSpinner(): void {
   if (running && !spinnerTimer) {
     spinnerTimer = setInterval(() => {
       spinnerFrame = (spinnerFrame + 1) % PI_SPINNER_FRAMES.length;
-      panelRequestRender?.();
     }, PI_SPINNER_INTERVAL_MS);
     spinnerTimer.unref?.();
   } else if (!running && spinnerTimer) {
@@ -80,79 +69,73 @@ function ensureSpinner(): void {
   }
 }
 
-function isPanelCollapsed(): boolean {
-  return Date.now() - panelLastActivity > PANEL_IDLE_COLLAPSE_MS;
-}
-
-function scheduleIdleCollapse(): void {
-  if (panelCollapseTimer) clearTimeout(panelCollapseTimer);
-  panelCollapseTimer = setTimeout(() => panelRequestRender?.(), PANEL_IDLE_COLLAPSE_MS);
-  panelCollapseTimer.unref?.();
-}
-
 export function stopUiTimers(): void {
   if (spinnerTimer) {
     clearInterval(spinnerTimer);
     spinnerTimer = undefined;
   }
-  if (panelCollapseTimer) {
-    clearTimeout(panelCollapseTimer);
-    panelCollapseTimer = undefined;
-  }
 }
 
 export function ensureTeamWidget(ctx?: { ui?: ExtensionUIContext; mode?: string }): void {
-  if (widgetRegistered || !ctx?.ui?.setWidget) return;
+  if (!ctx?.ui?.setWidget) return;
   if (ctx.mode && ctx.mode !== "tui") return;
-  try {
-    ctx.ui.setWidget("teammate", (tui, theme) => {
-      panelRequestRender = () => tui.requestRender();
-      ensureSpinner();
-      return {
-        render: (width) => panelRows(theme, width),
-        invalidate: () => {},
-        dispose: () => {
-          stopUiTimers();
-          panelRequestRender = undefined;
-          widgetRegistered = false;
-        },
-      };
-    });
-    widgetRegistered = true;
-  } catch {
-    // Best effort if widget registration is unavailable in the current mode.
+
+  const running = listNodes().filter((node) => node.status === "running");
+  if (running.length === 0) {
+    ctx.ui.setWidget("teammate", undefined);
+    return;
   }
+
+  ctx.ui.setWidget("teammate", (tui, theme) => {
+    const timer = setInterval(() => tui.requestRender(), PI_SPINNER_INTERVAL_MS);
+    timer.unref?.();
+    const style = createPiThemeStyle(theme);
+    const assignedColors = new Map<string, (typeof TEAM_COLORS)[number]>();
+    return {
+      placement: "belowEditor",
+      render: (width: number) => {
+        const running = listNodes().filter((n) => n.status === "running");
+        if (running.length === 0) return [];
+        const runningKeys = new Set(running.map((node) => node.workerKey));
+        for (const key of assignedColors.keys()) {
+          if (!runningKeys.has(key)) assignedColors.delete(key);
+        }
+        const usedColors = new Set(assignedColors.values());
+        for (const node of running) {
+          if (!assignedColors.has(node.workerKey)) {
+            const start = hashName(node.workerKey) % TEAM_COLORS.length;
+            const color = TEAM_COLORS.find((_, offset) => !usedColors.has(TEAM_COLORS[(start + offset) % TEAM_COLORS.length]));
+            assignedColors.set(node.workerKey, color ?? TEAM_COLORS[start]);
+            usedColors.add(color ?? TEAM_COLORS[start]);
+          }
+        }
+        const lines: string[] = [];
+        for (const node of running) {
+          const label = runningTeammateLabel(node);
+          const color = assignedColors.get(node.workerKey) ?? TEAM_COLORS[hashName(node.workerKey) % TEAM_COLORS.length];
+          const name = style.fg(color, node.id);
+          const role = style.dim(`(${node.agent})`);
+          const separator = label.indexOf(" ");
+          const spinner = separator === -1 ? label : label.slice(0, separator);
+          const activityText = separator === -1 ? "Working..." : label.slice(separator + 1).trim();
+          const activity = theme.bold(style.fg("accent", activityText));
+          const line = ` ${spinner} ${name} ${role} · ${activity}`;
+          lines.push(truncateToWidth(line, Math.max(10, width - 1)));
+        }
+        return lines;
+      },
+      invalidate: () => {},
+      dispose: () => clearInterval(timer),
+    };
+  });
 }
 
 export function refreshTeamUI(ctx?: { ui?: ExtensionUIContext; mode?: string }): void {
   ensureTeamWidget(ctx);
-  panelLastActivity = Date.now();
-  scheduleIdleCollapse();
   ensureLivePoll();
   ensureSpinner();
-  panelRequestRender?.();
 }
 
-/** Passive widget rows (display only — no selection, no key handling). */
-function panelRows(theme: Theme, width?: number): string[] {
-  const fg = (color: ThemeColor, s: string): string => theme.fg(color, s);
-  const bold = (s: string): string => theme.bold(s);
-  const fit = (line: string): string =>
-    typeof width === "number" && width > 0 ? truncateToWidth(line, Math.max(10, width - 1)) : line;
-  const running = listNodes().filter((node) => node.status === "running");
-  // Stay out of the way until a teammate is actually working.
-  if (running.length === 0) return [];
-  if (isPanelCollapsed()) {
-    return [` ${fit(fg("dim", `${running.length} teammate${running.length === 1 ? "" : "s"} working — /teammate`))}`];
-  }
-  const lines: string[] = [];
-  for (const node of running) {
-    const color = TEAM_COLORS[hashName(node.workerKey) % TEAM_COLORS.length];
-    lines.push(` ${fit(`${bold(fg(color, node.id))} ${fg("muted", `(${node.agent})`)} ${fg("warning", runningTeammateLabel(node))}`)}`);
-  }
-  lines.push(` ${fit(fg("dim", "/teammate — open console"))}`);
-  return lines;
-}
 
 /** Full content of a node as shown on its detail page: spawn lifecycle, live
  * worker text, captured output, result and error. */

package/src/worker.ts

@@ -27,7 +27,9 @@ export function isWorkerEvent(value: unknown): value is WorkerEvent {
     && typeof event.spawnId === "string"
     && typeof event.subject === "string"
     && typeof event.body === "string"
-    && (event.status === undefined || ["in_progress", "completed", "failed"].includes(event.status));
+    && (event.status === undefined || ["in_progress", "completed", "failed"].includes(event.status))
+    && (event.data === undefined || typeof event.data === "object")
+    ;
 }
 
 export function registerWorkerCapabilities(pi: ExtensionAPI): void {
@@ -48,6 +50,7 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): void {
         subject: params.subject,
         body: params.body,
         status: params.status,
+        data: params.data,
       });
       const statusNote = params.status ? ` with status "${params.status}"` : "";
       return { content: [{ type: "text", text: `Queued report to team-leader${statusNote}.` }], details: {} };