@fradser/pi-agent-teams 0.5.0

package/src/statefile.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared session files for the leader-owned debug snapshot and worker outboxes.
+ *
+ * Layout: `~/.pi/agent/teammate/<sessionKey>/state.json`, sessionKey derived
+ * from the session file (or cwd for ephemeral sessions) so different sessions
+ * never share a board file.
+ *
+ * Concurrency: the parent is the sole writer of state.json (atomic tmp+rename).
+ * Workers append requests only to their own JSONL outbox; the state snapshot is
+ * not a worker inbox or a communication channel.
+ */
+
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import type { TeammateState, WorkerEvent } from "./types";
+
+const MAX_WORKER_EVENT_BYTES = 64 * 1024;
+const MAX_OUTBOX_READ_BYTES = 256 * 1024;
+
+export function sessionStateDir(sessionFile: string | undefined, cwd: string): string {
+  const key = crypto
+    .createHash("sha256")
+    .update(sessionFile ?? cwd)
+    .digest("hex")
+    .slice(0, 16);
+  return path.join(os.homedir(), CONFIG_DIR_NAME, "agent", "teammate", key);
+}
+
+export function stateFilePath(sessionFile: string | undefined, cwd: string): string {
+  return path.join(sessionStateDir(sessionFile, cwd), "state.json");
+}
+
+/** Write the leader-owned debug snapshot atomically (tmp + rename). */
+export function writeStateFile(file: string, state: TeammateState): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+/** Per-run append-only event log. Its filename cannot escape the session dir. */
+export function workerOutboxPath(stateFile: string, workerName: string, runId: string): string {
+  return path.join(path.dirname(stateFile), "events", `${encodeURIComponent(workerName)}.${encodeURIComponent(runId)}.jsonl`);
+}
+
+/** Delete a drained per-run outbox after its final snapshot is safely published. */
+export function removeWorkerOutbox(stateFile: string, workerName: string, runId: string): void {
+  fs.rmSync(workerOutboxPath(stateFile, workerName, runId), { force: true });
+}
+
+/** Append one worker event. Workers never replace the leader-owned state snapshot. */
+export function appendWorkerEvent(file: string, event: WorkerEvent): void {
+  const record = `${JSON.stringify(event)}\n`;
+  if (Buffer.byteLength(record, "utf-8") > MAX_WORKER_EVENT_BYTES) {
+    throw new Error(`Worker event exceeds ${MAX_WORKER_EVENT_BYTES} bytes.`);
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.appendFileSync(file, record, { encoding: "utf-8", mode: 0o600 });
+}
+
+/** Read a bounded batch of complete JSONL records after byteOffset. */
+export function readWorkerEvents(file: string, byteOffset: number): { events: unknown[]; nextOffset: number } {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(file, "r");
+    const size = fs.fstatSync(fd).size;
+    // A truncated/recreated outbox starts at zero; event IDs make replay safe.
+    const offset = byteOffset > size ? 0 : Math.max(0, byteOffset);
+    const toRead = Math.min(MAX_OUTBOX_READ_BYTES, size - offset);
+    if (toRead === 0) return { events: [], nextOffset: offset };
+    const raw = Buffer.allocUnsafe(toRead);
+    const bytesRead = fs.readSync(fd, raw, 0, toRead, offset);
+    const unread = raw.subarray(0, bytesRead);
+    const lastNewline = unread.lastIndexOf(0x0a);
+    if (lastNewline < 0) {
+      // A line larger than the batch cap is malformed for this protocol; skip
+      // this chunk so one worker cannot block event draining indefinitely.
+      return { events: [], nextOffset: bytesRead === MAX_OUTBOX_READ_BYTES ? offset + bytesRead : offset };
+    }
+    const complete = unread.subarray(0, lastNewline).toString("utf-8");
+    const events: unknown[] = [];
+    for (const line of complete.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        events.push(JSON.parse(line));
+      } catch {
+        // Malformed records are consumed, not retried forever.
+      }
+    }
+    return { events, nextOffset: offset + lastNewline + 1 };
+  } catch {
+    return { events: [], nextOffset: 0 };
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+// ── Expired state-dir cleanup ───────────────────────────────────────
+
+/** Root of all per-session teammate state dirs (`~/.pi/agent/teammate/`). */
+export function stateDirsRoot(): string {
+  return path.join(os.homedir(), CONFIG_DIR_NAME, "agent", "teammate");
+}
+
+/** Remove the current session's state dir (called on session_shutdown). */
+export function removeSessionStateDir(sessionFile: string | undefined, cwd: string): void {
+  fs.rmSync(sessionStateDir(sessionFile, cwd), { recursive: true, force: true });
+}
+
+/**
+ * Sweep state dirs whose last write is older than maxAgeMs. Returns how many
+ * were removed. Called on session_start so abandoned sessions never pile up.
+ */
+export function cleanupExpiredStateDirs(maxAgeMs: number): number {
+  const root = stateDirsRoot();
+  let entries: string[] = [];
+  try {
+    entries = fs.readdirSync(root);
+  } catch {
+    return 0; // root missing — nothing to clean
+  }
+  const now = Date.now();
+  let removed = 0;
+  for (const name of entries) {
+    const full = path.join(root, name);
+    try {
+      const st = fs.statSync(full);
+      if (st.isDirectory() && now - st.mtimeMs > maxAgeMs) {
+        fs.rmSync(full, { recursive: true, force: true });
+        removed++;
+      }
+    } catch {
+      // Unreadable entries are skipped, not fatal.
+    }
+  }
+  return removed;
+}

package/src/terminal.ts

@@ -0,0 +1,34 @@
+export interface NodeTerminalResultInput {
+  runId: string;
+  nodeId: string;
+  agent: string;
+  result: {
+    stdout: string;
+    stderr: string;
+    signal: NodeJS.Signals | null;
+    timedOut: boolean;
+  };
+  nodeResult?: string;
+  nodeError?: string;
+  cancelled: boolean;
+  completedAfterShutdown?: boolean;
+  patchText: string;
+}
+
+export function buildNodeTerminalResult(input: NodeTerminalResultInput): string {
+  const status = input.cancelled
+    ? "cancelled"
+    : input.completedAfterShutdown
+      ? "completed"
+      : input.result.timedOut
+        ? "timed out"
+        : input.result.signal
+          ? `terminated by ${input.result.signal}`
+          : input.nodeError
+            ? "failed"
+            : "completed";
+  const summary = [input.nodeResult, input.nodeError, input.result.stdout, input.result.stderr]
+    .find((value) => value?.trim()) ?? "No worker summary was produced.";
+  const worktree = input.patchText ? "\nWorktree diff captured; inspect the node result before integration." : "";
+  return `Node [${input.runId}/${input.nodeId}] ${status} — agent ${input.agent}.\n${summary}${worktree}`;
+}

package/src/tools.ts

@@ -0,0 +1,154 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { discoverAgents, resolveAgent } from "./agents";
+import {
+  applyWorkerEvents,
+  buildRunSummary,
+  cancelNodeAndTerminate,
+  cancelRunAndTerminate,
+  ensureRunContext,
+  publishStateSnapshot,
+  scheduleRun,
+  type DispatchCtx,
+} from "./run-machine";
+import { createRun, getRun, getSummary, markRunCompletionDelivered, retryRun } from "./state";
+import { TeammateCancelParams, TeammateRetryParams, TeammateRunParams } from "./types";
+import { ensureTeamWidget, openTeamConsole, refreshTeamUI } from "./ui";
+
+function dispatchContext(ctx: ExtensionContext): DispatchCtx {
+  return { ui: ctx.ui, sessionManager: ctx.sessionManager, cwd: ctx.cwd };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function gatherForeground(runId: string, signal: AbortSignal | undefined): Promise<string> {
+  const foregroundTimeoutMs = 5 * 60 * 1000;
+  const deadline = Date.now() + foregroundTimeoutMs;
+  while (true) {
+    applyWorkerEvents();
+    const run = getRun(runId);
+    if (!run || run.status !== "running") break;
+    if (signal?.aborted) {
+      run.background = true;
+      run.completionNotified = false;
+      publishStateSnapshot();
+      throw new Error(`Run [${runId}] continues in the background — workers will message team-leader upon completion.`);
+    }
+    if (Date.now() >= deadline) {
+      run.background = true;
+      run.completionNotified = false;
+      publishStateSnapshot();
+      return `Run [${runId}] is still running after ${Math.round(foregroundTimeoutMs / 1000)}s — detached to background. Workers will message team-leader upon completion.`;
+    }
+    await sleep(150);
+  }
+  markRunCompletionDelivered(runId);
+  publishStateSnapshot();
+  return buildRunSummary(runId);
+}
+
+export function registerLeaderTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "teammate_run",
+    promptSnippet: "Dispatch a dependency-aware task graph in one call",
+    label: "Run Tasks",
+    description: "Dispatch a dependency-aware task graph in one call. Root nodes start immediately; downstream nodes auto-start after dependencies complete. Concurrency is bounded per run and across the session. Teammates run in the background by default and deliver completion through a follow-up. Do not sleep to wait.",
+    parameters: TeammateRunParams,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const cwd = params.cwd ?? ctx.cwd ?? process.cwd();
+      const dctx = dispatchContext(ctx);
+      ensureRunContext(dctx);
+      ensureTeamWidget(ctx);
+      for (const task of params.tasks) {
+        if (!resolveAgent(task.agent, cwd)) {
+          const available = [...discoverAgents(cwd).keys()].join(", ");
+          throw new Error(`Agent "${task.agent}" not found in any scope. Available agents: ${available || "(none)"}.`);
+        }
+      }
+      const created = createRun({
+        cwd,
+        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) => ({
+          id: task.id,
+          agent: task.agent,
+          prompt: task.prompt,
+          paths: task.paths,
+          access: task.access ?? "read",
+          model: task.model,
+          timeoutMs: task.timeoutMs,
+          dependsOn: task.dependsOn ?? [],
+        })),
+      });
+      if (!created.ok) throw new Error(created.error ?? "Failed to create run.");
+      const run = created.run;
+      publishStateSnapshot();
+      refreshTeamUI(ctx);
+      scheduleRun(run.id, dctx);
+
+      if (run.background) {
+        return {
+          content: [{ type: "text", text: `Started run [${run.id}] "${Object.keys(run.nodes).length} node(s)" — background.\nConcurrency: ${run.concurrency} | Worktree: ${run.worktree ? "yes" : "no"}\n\nWorkers will report their deliverables through the automatic completion follow-up. Do not sleep to wait.` }],
+          details: {},
+        };
+      }
+      return { content: [{ type: "text", text: await gatherForeground(run.id, signal) }], details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "teammate_cancel",
+    promptSnippet: "Cancel a run and stop its workers",
+    label: "Cancel Run",
+    description: "Cancel a run or one node. Running workers receive SIGTERM with bounded SIGKILL escalation; pending nodes are cancelled.",
+    parameters: TeammateCancelParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const dctx = dispatchContext(ctx);
+      ensureRunContext(dctx);
+      const result = params.nodeId
+        ? await cancelNodeAndTerminate(params.runId, params.nodeId, dctx)
+        : await cancelRunAndTerminate(params.runId, dctx);
+      if (!result.ok) throw new Error(result.error);
+      return { content: [{ type: "text", text: params.nodeId
+        ? `Node [${params.runId}/${params.nodeId}] cancelled — the rest of the run continues.`
+        : `Run [${params.runId}] cancelled — pending nodes were cancelled and running workers were stopped.` }], details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "teammate_retry",
+    promptSnippet: "Retry the failed or cancelled nodes of a settled run",
+    label: "Retry Run Nodes",
+    description: "Retry failed and cancelled nodes of a settled run without re-running completed nodes.",
+    parameters: TeammateRetryParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const dctx = dispatchContext(ctx);
+      ensureRunContext(dctx);
+      const retried = retryRun(params.runId, params.nodeIds);
+      if (!retried.ok) throw new Error(retried.error ?? "Failed to retry run.");
+      publishStateSnapshot();
+      scheduleRun(params.runId, dctx);
+      refreshTeamUI(ctx);
+      return { content: [{ type: "text", text: `Run [${params.runId}] retried — reset ${retried.reset.length} node(s): ${retried.reset.join(", ")}. Completed nodes are retained.` }], details: {} };
+    },
+  });
+}
+
+export function registerTeamCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("teammate", {
+    description: "Open the full-screen teammate team console: run/node status, node details, interrupt/stop",
+    handler: async (_args, ctx) => {
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify(getSummary() ?? "No runs yet — dispatch work with teammate_run.", "info");
+        return;
+      }
+      await openTeamConsole(ctx);
+      refreshTeamUI(ctx);
+    },
+  });
+}

package/src/types.ts

@@ -0,0 +1,231 @@
+import type { Static } from "typebox";
+import { Type } from "typebox";
+
+// ── Run / Node ────────────────────────────────────────────────────
+
+export const NodeStatus = Type.Union(
+  [
+    Type.Literal("pending"),
+    Type.Literal("running"),
+    Type.Literal("completed"),
+    Type.Literal("failed"),
+    Type.Literal("cancelled"),
+  ],
+  { description: "Current status of a run node" },
+);
+export type NodeStatus = Static<typeof NodeStatus>;
+
+export const RunStatus = Type.Union(
+  [
+    Type.Literal("running"),
+    Type.Literal("completed"),
+    Type.Literal("failed"),
+    Type.Literal("cancelled"),
+  ],
+  { description: "Current status of a run" },
+);
+export type RunStatus = Static<typeof RunStatus>;
+
+/** One task in a dispatched run: a bounded child-process unit of work. */
+export interface Node {
+  /** User-chosen id, unique within the run. */
+  id: string;
+  /** Stable node identity: `${runId}:${nodeId}`. */
+  workerKey: string;
+  /** Resolved agent definition name. */
+  agent: string;
+  /** The specific task text handed to the worker. */
+  prompt: string;
+  /** Repository-relative paths used to coordinate this node. */
+  paths: string[];
+  /** Read nodes may overlap; write nodes need shared-workspace conflict protection. */
+  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;
+  /** Node ids that must complete before this node may start. */
+  dependsOn: string[];
+  status: NodeStatus;
+  result?: string;
+  errorMessage?: string;
+  /** Real child-process execution info when this node was spawned. */
+  spawn?: SpawnInfo;
+  createdAt: number;
+  updatedAt: number;
+  completedAt?: number;
+}
+
+/** A dispatched dependency-aware task graph. */
+export interface Run {
+  id: string;
+  cwd: string;
+  status: RunStatus;
+  concurrency: number;
+  /** Every node runs in its own git worktree when true. */
+  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). */
+  errorMessage?: string;
+  nodes: Record<string, Node>;
+  createdAt: number;
+  updatedAt: number;
+  finishedAt?: number;
+  /** True once the run-completion follow-up was delivered, or claimed by wait/foreground gather. */
+  completionNotified?: boolean;
+  /** True once the run-settled leader summary was sent (onRunSettled is idempotent). */
+  settledMessageSent?: boolean;
+  /** Synthesized final summary produced by the optional __summary node. */
+  summary?: string;
+}
+
+// ── Spawn ─────────────────────────────────────────────────────────
+
+/** Lifecycle of a spawned child Pi process running a node. */
+export type SpawnStatus = "running" | "completed" | "failed";
+
+/** Token/cost usage reported by a finished worker (from JSON-mode output). */
+export interface WorkerUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: number;
+}
+
+export interface SpawnInfo {
+  /** Per-spawn capability identity, regenerated for every worker process. */
+  spawnId: string;
+  pid: number;
+  status: SpawnStatus;
+  startedAt: number;
+  /** Live assistant text assembled from JSON-mode stream events. */
+  liveText?: string;
+  /** Current child tool name, if a tool is executing. */
+  activeTool?: string;
+  /** Live assistant reasoning streamed from the child (shown while no tool runs). */
+  liveThinking?: string;
+  /** Number of assistant turns observed from the child JSON stream. */
+  turns?: number;
+  /** The child emitted a final successful assistant response and should close promptly. */
+  finalResponse?: boolean;
+  finishedAt?: number;
+  exitCode?: number;
+  /** Truncated stdout of the child process. */
+  stdout?: string;
+  /** Truncated stderr of the child process. */
+  stderr?: string;
+  /** Spawn-level error (e.g. CLI resolution failure). */
+  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";
+}
+
+// ── Mailbox ───────────────────────────────────────────────────────
+
+export interface MailboxMessage {
+  id: string;
+  from: string;
+  subject: string;
+  body: string;
+  runId?: string;
+  timestamp: number;
+}
+
+/** Append-only event emitted by a worker and applied by the team leader. */
+export interface WorkerMessageEvent {
+  id: string;
+  type: "message";
+  worker: string;
+  spawnId: string;
+  subject: string;
+  body: string;
+  status?: "in_progress" | "completed" | "failed";
+}
+
+export type WorkerEvent = WorkerMessageEvent;
+
+// ── Tool parameter schemas (typebox) ──────────────────────────────
+
+const NodeAccess = Type.Union(
+  [Type.Literal("read"), Type.Literal("write")],
+  { description: "read permits overlapping analysis; write protects overlapping shared-workspace changes. Default: read." },
+);
+
+/** One task inside teammate_run. */
+export const RunTaskSpec = Type.Object({
+  id: Type.String({ description: "Node id, unique within this run" }),
+  agent: Type.String({ description: "Agent definition name (bundled, user, or project scope)" }),
+  prompt: Type.String({ minLength: 1, description: "The specific task text handed to this worker" }),
+  dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Node ids that must complete before this node starts" })),
+  paths: Type.Array(Type.String({ description: "Repository-relative path this node may inspect or modify" }), {
+    minItems: 1,
+    description: "Repository-relative paths used to coordinate this node",
+  }),
+  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)" })),
+});
+
+/** Dispatch a dependency-aware task graph in one call. */
+export const TeammateRunParams = Type.Object({
+  tasks: Type.Array(RunTaskSpec, {
+    minItems: 1,
+    maxItems: 32,
+    description: "Task graph to dispatch; dependsOn edges must form a DAG",
+  }),
+  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)" })),
+});
+
+/** Explicit cancel of a run or single node. */
+export const TeammateCancelParams = Type.Object({
+  runId: Type.String({ description: "Run id to cancel" }),
+  nodeId: Type.Optional(Type.String({ description: "Cancel one node (and its not-yet-started dependents) instead of the whole run; the run continues" })),
+});
+
+/** Retry the failed/cancelled nodes of a settled run. */
+export const TeammateRetryParams = Type.Object({
+  runId: Type.String({ description: "Run id of a settled (failed/cancelled/completed) run" }),
+  nodeIds: Type.Optional(Type.Array(Type.String(), { description: "Node ids to reset and re-run; defaults to all failed and cancelled nodes" })),
+});
+
+/** Worker progress message or final report to the team leader. */
+export const TeammateMessageParams = Type.Object({
+  subject: Type.String({ description: "Concise report subject" }),
+  body: Type.String({ description: "Progress note or full final deliverable for the team leader" }),
+  status: Type.Optional(Type.Union([
+    Type.Literal("in_progress"),
+    Type.Literal("completed"),
+    Type.Literal("failed"),
+  ], { description: "Optional worker status; use completed or failed for the final deliverable" })),
+});
+
+// ── State snapshot for persistence ────────────────────────────────
+
+export interface TeammateState {
+  runs: Record<string, Run>;
+  /** Single leader inbox for worker terminal reports and leader-bound messages. */
+  leaderMailbox: MailboxMessage[];
+  messageCounter: number;
+  runCounter: number;
+  /** Byte offsets consumed by the parent from each worker's append-only outbox. */
+  workerEventOffsets: Record<string, number>;
+  /** Event IDs already applied by the parent, keyed to their worker spawn for compaction. */
+  workerEventIds: Record<string, string>;
+}