@fradser/pi-agent-teams 0.5.1 → 0.5.3

package/.memory/follow-up-queue.md

@@ -0,0 +1,17 @@
+---
+name: follow-up-queue
+description: Agent Teams serializes automatic teammate reports through Pi's void sendUserMessage API with lifecycle matching, retry backoff, and session invalidation
+type: project
+---
+
+## Why
+
+Pi's extension `sendUserMessage` API returns `void`; asynchronous preflight failures are routed to the runtime error handler rather than thrown to the caller. Concurrent automatic reports can also race Pi's prompt startup and produce `Agent is already processing a prompt`.
+
+## How to apply
+
+- `packages/agent-teams/src/follow-up-queue.ts` owns a FIFO report queue and one active dispatch.
+- A dispatch is matched by its exact prompt in `before_agent_start`, confirmed by `agent_start`, and released only by the corresponding `agent_settled` path. Reports arriving during an active leader run remain queued.
+- A watchdog restores a batch when no `agent_start` occurs; retries use bounded exponential backoff rather than a microtask spin.
+- `reset()` increments a generation and clears timers, so delayed callbacks from an old session cannot deliver to a replacement session.
+- Keep `sendMainSessionFollowUp` as a synchronous enqueue operation; do not call Pi's void API directly from worker completion paths.

package/.memory/node-terminal-followups.md

@@ -0,0 +1,17 @@
+---
+name: node-terminal-followups
+description: Background Agent Teams runs notify the main session after each non-summary teammate reaches a terminal outcome, including pre-spawn setup failures, then send a separate run summary when all nodes settle
+type: project
+---
+
+## Why
+
+The leader needs incremental results while independent teammates are still working. Waiting for the run-level settle message hides completed work and delays downstream attention. Setup failures must use the same delivery contract as child-process failures.
+
+## How to apply
+
+- `run-machine.ts` sends one node follow-up for each non-summary node in a background run when it reports `completed`/`failed`, when its child process reaches a terminal outcome, or when pre-spawn setup fails (agent/state-file/worktree setup).
+- `Node.nodeFollowUpSent` prevents duplicate follow-ups when a worker report is followed by process-close finalization; retry clears the marker.
+- The node follow-up uses the worker's full terminal report/body and does not stop remaining teammates.
+- The existing run-settled follow-up remains separate and is sent once after all nodes settle; foreground (`background=false`) runs continue to return their result inline without automatic node follow-ups.
+- Worker turn budgets default to 100 assistant turns as a high safety cap; explicit lower budgets remain available for deliberately bounded tasks.

package/README.md

@@ -50,7 +50,8 @@ teammate_run({
 - `access` defaults to `read`; declare `write` explicitly.
 - `dependsOn` edges must form a DAG (duplicate ids, unknown references, and cycles are rejected before any worker starts).
 - `worktree: true` runs every node in its own git worktree and captures each diff for integration review.
-- `background` defaults to `true`: teammates always run in the background — the call returns the run id immediately, the model turn stays free, and workers report their deliverables through the worker-only `teammate_message` capability, delivered automatically as a follow-up turn. The team leader does not sleep or busy-wait while tasks execute. Pass `background=false` to block and gather inline (it detaches after 5 minutes so the turn is never hung).
+- `background` defaults to `true`: teammates always run in the background — the call returns the run id immediately, the model turn stays free, and each teammate's terminal outcome sends its full deliverable in an immediate follow-up while the remaining teammates continue. A final run-completion follow-up is sent after all nodes settle. The team leader does not sleep or busy-wait while tasks execute. Pass `background=false` to block and gather inline (it detaches after 5 minutes so the turn is never hung).
+- `turnBudget` defaults to a high safety cap of 100 assistant turns; use an explicit lower value only when a task needs tighter bounds. This protects against edge cases without interrupting normal work.
 - `timeoutMs` is a run-level hard cap: when exceeded, the run fails and live workers are terminated.
 - A session-wide cap of 8 worker processes applies in addition to each run's `concurrency` limit.
 - Multi-node runs append a `__summary` node by default (`summarize=false` to skip). Single-task runs stay compact unless `summarize=true`.
@@ -86,6 +87,7 @@ State is session-scoped and dies with the session (`~/.pi/agent/teammate/<sessio
 
 ```
 agent-teams/
+├── index.ts           — package-root extension entry point
 ├── package.json       — Pi package manifest
 ├── agents/            — bundled agent definitions (worker/reviewer/specialist/observer)
 ├── src/

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fradser/pi-agent-teams",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Multi-agent team system for Pi — DAG orchestration, leader inbox, and one-way worker reports",
   "keywords": [
     "pi-package",
@@ -22,6 +22,7 @@
     "access": "public"
   },
   "files": [
+    "index.ts",
     "src",
     "agents",
     ".memory",
@@ -34,10 +35,10 @@
   },
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./index.ts"
     ]
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.1.0"
+    "@fradser/pi-kit": "0.1.1"
   }
 }

package/src/console-viewport.ts

@@ -2,7 +2,8 @@ import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 
 /** Leave room for the console borders, title, spacing, and footer. */
 export function maxConsoleBody(rows: number): number {
-  return Math.max(3, rows - 5);
+  // Detail chrome: border, header, spacer, spacer, footer, border.
+  return Math.max(3, rows - 7);
 }
 
 /** Wrap source records before calculating scroll positions. */

package/src/follow-up-queue.ts

@@ -0,0 +1,170 @@
+export interface FollowUpReport {
+  subject: string;
+  body: string;
+  runId?: string;
+}
+
+export interface FollowUpQueueOptions {
+  isIdle: () => boolean;
+  dispatch: (content: string) => void;
+  onFailure?: (message: string) => void;
+  agentStartTimeoutMs?: number;
+  retryBaseDelayMs?: number;
+  retryMaxDelayMs?: number;
+}
+
+interface PendingDispatch {
+  reports: FollowUpReport[];
+  content: string;
+  prepared: boolean;
+  started: boolean;
+}
+
+/**
+ * Serializes automatic reports sent through Pi's void sendUserMessage API.
+ *
+ * The API reports asynchronous preflight failures through the runtime error
+ * channel, so this queue uses agent lifecycle events for success and a bounded
+ * watchdog for attempts that never reach agent_start.
+ */
+export class FollowUpQueue {
+  private readonly isIdle: FollowUpQueueOptions["isIdle"];
+  private readonly dispatch: FollowUpQueueOptions["dispatch"];
+  private readonly onFailure: (message: string) => void;
+  private readonly agentStartTimeoutMs: number;
+  private readonly retryBaseDelayMs: number;
+  private readonly retryMaxDelayMs: number;
+  private pending: FollowUpReport[] = [];
+  private active: PendingDispatch | undefined;
+  private pumpScheduled = false;
+  private retryTimer: ReturnType<typeof setTimeout> | undefined;
+  private watchdogTimer: ReturnType<typeof setTimeout> | undefined;
+  private generation = 0;
+  private failureCount = 0;
+
+  constructor(options: FollowUpQueueOptions) {
+    this.isIdle = options.isIdle;
+    this.dispatch = options.dispatch;
+    this.onFailure = options.onFailure ?? (() => {});
+    this.agentStartTimeoutMs = options.agentStartTimeoutMs ?? 30_000;
+    this.retryBaseDelayMs = options.retryBaseDelayMs ?? 1_000;
+    this.retryMaxDelayMs = options.retryMaxDelayMs ?? 30_000;
+  }
+
+  enqueue(report: FollowUpReport): void {
+    this.pending.push(report);
+    this.schedulePump();
+  }
+
+  /** Match the active dispatch to the prompt that Pi is about to start. */
+  onBeforeAgentStart(prompt: string): void {
+    if (!this.active || this.active.prepared || prompt !== this.active.content) return;
+    this.active.prepared = true;
+  }
+
+  /** Mark the matching dispatch started after before_agent_start completes. */
+  onAgentStart(): void {
+    if (!this.active || !this.active.prepared || this.active.started) return;
+    this.active.started = true;
+    this.clearWatchdog();
+    this.failureCount = 0;
+  }
+
+  /** Release a completed dispatch; unrelated settled events are ignored. */
+  onAgentSettled(): void {
+    if (this.active && !this.active.started) return;
+    if (this.active) {
+      this.active = undefined;
+      this.failureCount = 0;
+    }
+    this.schedulePump();
+  }
+
+  /** Drop all reports and invalidate callbacks from the previous session. */
+  reset(): void {
+    this.generation++;
+    this.pending = [];
+    this.active = undefined;
+    this.pumpScheduled = false;
+    this.failureCount = 0;
+    this.clearRetryTimer();
+    this.clearWatchdog();
+  }
+
+  get pendingCount(): number {
+    return this.pending.length + (this.active?.reports.length ?? 0);
+  }
+
+  private schedulePump(): void {
+    if (this.pumpScheduled) return;
+    this.pumpScheduled = true;
+    const generation = this.generation;
+    setTimeout(() => {
+      this.pumpScheduled = false;
+      if (generation !== this.generation) return;
+      this.pump();
+    }, 0);
+  }
+
+  private pump(): void {
+    if (this.active || this.retryTimer || this.pending.length === 0 || !this.isIdle()) return;
+    const reports = this.pending.splice(0);
+    const content = formatReports(reports);
+    const queuedIntoActiveRun = !this.isIdle();
+    this.active = {
+      reports,
+      content,
+      prepared: queuedIntoActiveRun,
+      started: queuedIntoActiveRun,
+    };
+    const generation = this.generation;
+    try {
+      this.dispatch(content);
+    } catch (error) {
+      this.failActive(generation, error instanceof Error ? error.message : String(error));
+      return;
+    }
+    if (!queuedIntoActiveRun) {
+      this.watchdogTimer = setTimeout(() => {
+        if (generation !== this.generation || !this.active || this.active.started) return;
+        this.failActive(generation, "Pi did not start the automatic teammate follow-up.");
+      }, this.agentStartTimeoutMs);
+    }
+  }
+
+  private failActive(generation: number, message: string): void {
+    if (generation !== this.generation || !this.active) return;
+    const failed = this.active;
+    this.active = undefined;
+    this.pending.unshift(...failed.reports);
+    this.clearWatchdog();
+    this.failureCount++;
+    const delay = Math.min(
+      this.retryMaxDelayMs,
+      this.retryBaseDelayMs * 2 ** Math.max(0, this.failureCount - 1),
+    );
+    this.onFailure(`${message} Retrying in ${Math.ceil(delay / 1000)}s.`);
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = undefined;
+      if (generation === this.generation) this.schedulePump();
+    }, delay);
+  }
+
+  private clearRetryTimer(): void {
+    if (!this.retryTimer) return;
+    clearTimeout(this.retryTimer);
+    this.retryTimer = undefined;
+  }
+
+  private clearWatchdog(): void {
+    if (!this.watchdogTimer) return;
+    clearTimeout(this.watchdogTimer);
+    this.watchdogTimer = undefined;
+  }
+}
+
+function formatReports(reports: FollowUpReport[]): string {
+  return reports
+    .map(({ subject, body }) => `Teammate update: ${subject}\n${body}`)
+    .join("\n\n");
+}

package/src/guidance.ts

@@ -43,8 +43,10 @@ ${agents}
 ### Dispatch a run in one call
 
 Use teammate_run with a tasks array: each task has id, agent, prompt, paths,
-access (read default, write explicit), optional dependsOn, model, and
-timeoutMs. The scheduler starts root nodes immediately, bounds concurrency,
+access (read default, write explicit), optional dependsOn, model, turnBudget
+(default 100 assistant turns), forkContext, and inputBindings. Use teammate_fanout only from the leader after
+validating a completed node's bounded structured array output. The scheduler
+starts root nodes immediately, bounds concurrency,
 defers overlapping shared-workspace writes — advisory coordination across all
 runs, not file-access isolation — unless worktree=true, and auto-starts
 downstream nodes when their dependencies complete. access and paths coordinate
@@ -52,13 +54,14 @@ scheduling only; a worker's real capabilities come from its agent definition's
 tools list.
 
 Teammates run in the background by default: the call returns the run id
-immediately, and the main session is free. When a teammate finishes, it sends
-its final deliverable to team-leader through its append-only outbox. The
-harness delivers the run completion automatically as a follow-up turn. Pass
-background=false only when you strictly need inline synchronous blocking (it
-detaches after 5 minutes so the turn is never hung). A session-wide cap of 8
-worker processes applies in addition to each run's concurrency. Multi-node runs
-append a __summary node by default; pass summarize=false to skip it.
+immediately, and the main session is free. When any teammate reaches a
+terminal outcome, its full final deliverable is sent in an immediate follow-up;
+the remaining teammates continue running. The harness also delivers one run
+completion follow-up after all nodes settle. Pass background=false only when
+you strictly need inline synchronous blocking (it detaches after 5 minutes so
+the turn is never hung). A session-wide cap of 8 worker processes applies in
+addition to each run's concurrency. Multi-node runs append a __summary node by
+default; pass summarize=false to skip it.
 
 ### DO NOT poll status
 

package/src/index.ts

@@ -15,22 +15,16 @@ import { ensureTeamWidget, refreshTeamUI, stopUiTimers } from "./ui";
 import { registerLeaderTools, registerTeamCommand } from "./tools";
 import { registerWorkerCapabilities, workerOutboxBinding } from "./worker";
 import { terminateAllWorkers } from "./spawner";
+import { FollowUpQueue } from "./follow-up-queue";
 
 const STATE_DIR_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 
 let leaderPi: ExtensionAPI | undefined;
+let leaderCtx: ExtensionContext | undefined;
+let followUpQueue: FollowUpQueue | undefined;
 
-function sendMainSessionUpdate(subject: string, body: string, runId?: string): void {
-  try {
-    leaderPi?.sendMessage({
-      customType: "teammate-update",
-      content: `Teammate update — ${subject}${runId ? ` [${runId}]` : ""}\n${body}`,
-      display: true,
-      details: { runId },
-    }, { triggerTurn: true, deliverAs: "followUp" });
-  } catch {
-    // Late run events must not prevent shutdown.
-  }
+function sendMainSessionFollowUp(subject: string, body: string, runId?: string): void {
+  followUpQueue?.enqueue({ subject, body, runId });
 }
 
 function dispatchContext(ctx: ExtensionContext): DispatchCtx {
@@ -52,28 +46,51 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("session_start", async (_event, ctx) => {
     resetState();
+    followUpQueue?.reset();
+    leaderCtx = ctx;
+    const sessionQueue = new FollowUpQueue({
+      isIdle: () => Boolean(leaderCtx?.isIdle()),
+      dispatch: (content) => leaderPi?.sendUserMessage(content, { deliverAs: "followUp" }),
+      onFailure: (message) => leaderCtx?.ui.notify(message, "warning"),
+    });
+    followUpQueue = sessionQueue;
     const dispatchCtx = dispatchContext(ctx);
     ensureTeamWidget(ctx);
     const stateFile = stateFilePath(ctx.sessionManager.getSessionFile(), ctx.cwd || process.cwd());
     initRunMachine(dispatchCtx, stateFile, {
-      sendUpdate: sendMainSessionUpdate,
-      notifyChange: () => refreshTeamUI(),
+      sendUpdate: sendMainSessionFollowUp,
+      notifyChange: () => refreshTeamUI(leaderCtx),
     });
     ctx.ui.setStatus("teammate", undefined);
     refreshTeamUI(ctx);
     void cleanupExpiredStateDirs(STATE_DIR_MAX_AGE_MS);
   });
 
+  pi.on("before_agent_start", async (event, ctx) => {
+    followUpQueue?.onBeforeAgentStart(event.prompt);
+    return {
+      systemPrompt: event.systemPrompt + buildTeamLeaderGuidance(ctx?.cwd ?? process.cwd()),
+    };
+  });
+
+  pi.on("agent_start", async () => {
+    followUpQueue?.onAgentStart();
+  });
+
+  pi.on("agent_settled", async () => {
+    followUpQueue?.onAgentSettled();
+  });
+
   pi.on("session_shutdown", async (_event, ctx) => {
     stopUiTimers();
     await terminateAllWorkers();
     shutdownRunMachine();
     removeSessionStateDir(ctx.sessionManager.getSessionFile(), ctx.cwd || process.cwd());
+    followUpQueue?.reset();
+    followUpQueue = undefined;
     leaderPi = undefined;
+    leaderCtx = undefined;
     resetState();
   });
 
-  pi.on("before_agent_start", async (event, ctx) => ({
-    systemPrompt: event.systemPrompt + buildTeamLeaderGuidance(ctx?.cwd ?? process.cwd()),
-  }));
 }