@fradser/pi-agent-teams 0.5.3 → 0.7.0

package/src/tools.ts

@@ -1,213 +1,198 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { discoverAgents, resolveAgent } from "./agents";
+import { keyHint, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { formatAgentMessagePrefix, formatAgentTaskName, formatExpandHint, formatToolEventLabel, safeDisplayText } from "@fradser/pi-kit";
 import {
-  applyWorkerEvents,
-  buildRunSummary,
-  cancelNodeAndTerminate,
-  cancelRunAndTerminate,
-  ensureRunContext,
+  createBoardTask,
+  formatSilenceDuration,
   publishStateSnapshot,
-  scheduleRun,
-  type DispatchCtx,
-} from "./run-machine";
-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";
+  sendLeaderMessage,
+  shutdownTeammate,
+  spawnTeammate,
+} from "./team-machine.ts";
+import { listTasks, livingTeammates } from "./state.ts";
+import { LEADER_RECIPIENT, SendMessageParams, TeammateShutdownParams, TeammateSpawnParams, TaskCreateParams } from "./types.ts";
+import { registerTaskListTool } from "./worker.ts";
+import { openTeamConsole, refreshTeamUI } from "./ui.ts";
+import { discoverAgents } from "./agents.ts";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 
-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);
-}
-
-function resolveTargetNode(target: string): { node: import("./types").Node } | undefined {
-  return listNodes().map((node) => ({ node })).find(({ node }) => node.id === target || node.workerKey === target);
+function rosterSummary(): string {
+  const alive = livingTeammates();
+  if (alive.length === 0) return "No living teammates.";
+  return alive.map((t) => `@${t.name} (${t.agent}, ${t.status}${t.currentTaskId ? `, task ${t.currentTaskId}` : ""})`).join("\n");
 }
 
 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)"}.`);
-        }
+    name: "teammate_spawn",
+    promptSnippet: "Spawn a named resident teammate",
+    label: "Spawn Teammate",
+    description: "Spawn one named resident teammate. Model and worktree behavior come from its declarative agent definition; the kickoff prompt is optional.",
+    parameters: TeammateSpawnParams,
+    // Canonical lifecycle rows (same as packages/monitor): empty renderCall,
+    // ONE startup row owned by renderResult.
+    renderShell: "self",
+    renderCall: () => new Text("", 0, 0),
+    renderResult(result, _options, theme, context) {
+      const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
+      if (context.isError) {
+        return new Text(theme.fg("error", text.split("\n")[0] || "Failed to spawn teammate."), 0, 0);
       }
-      const created = createRun({
-        cwd,
-        concurrency: params.concurrency ?? 4,
-        worktree: params.worktree ?? false,
-        background: params.background ?? true,
-        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,
-          mode: task.mode,
-          turnBudget: task.turnBudget,
-          forkContext: task.forkContext,
-          inputBindings: task.inputBindings,
-          dependsOn: task.dependsOn ?? [],
-        })),
-      });
-      if (!created.ok) throw new Error(created.error ?? "Failed to create run.");
-      const run = created.run;
-      publishStateSnapshot();
+      const params = context.args as { name: string; agent: string; prompt?: string };
+      const line = `${theme.fg("toolTitle", theme.bold(formatToolEventLabel("started", "", "agent").trimEnd()))} ${theme.fg("accent", `@${params.name}`)} ${theme.fg("dim", "·")} ${theme.fg("customMessageText", theme.bold(formatAgentTaskName(params.prompt ?? "", params.name)))}`;
+      return {
+        render: (width: number) => width > 0 ? [truncateToWidth(line, width)] : [],
+        invalidate: () => {},
+      };
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const result = spawnTeammate(params);
+      if (!result.ok) throw new Error(result.error);
       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: {} };
+      const kickoffNote = params.prompt?.trim()
+        ? "It received your kickoff prompt and is working on it."
+        : "It is idle: it wakes for inbox messages and claimable board tasks.";
+      return {
+        content: [{ type: "text", text: `@${params.name} is alive as ${params.agent}.\n${kickoffNote}\n\n${rosterSummary()}` }],
+        details: { started: true },
+      };
     },
   });
 
   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,
+    name: "teammate_shutdown",
+    promptSnippet: "Shut down a resident teammate",
+    label: "Shutdown Teammate",
+    description: "Gracefully stop one named teammate. Its claimed task returns to the board; its worktree diff is captured before teardown.",
+    parameters: TeammateShutdownParams,
+    renderShell: "self",
+    renderCall: () => new Text("", 0, 0),
+    renderResult(result, options, theme, context) {
+      const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
+      if (context.isError) {
+        return new Text(theme.fg("error", text.split("\n")[0] || "Failed to shut down teammate."), 0, 0);
+      }
+      const name = String((context.args as { name?: string }).name ?? "");
+      const title = theme.fg("toolTitle", theme.bold(formatToolEventLabel("event", `@${name} shut down`, "agent")));
+      const render = (width: number) => {
+        if (width <= 0) return [];
+        if (!options.expanded) {
+          return [truncateToWidth(`${title}${formatExpandHint(keyHint("app.tools.expand", "to expand"), theme)}`, width)];
+        }
+        return [
+          truncateToWidth(title, width),
+          ...text.split("\n").map((line) => truncateToWidth(theme.fg("customMessageText", safeDisplayText(line)), width)),
+        ];
+      };
+      return { render, invalidate: () => {} };
+    },
     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: {} };
+      const result = await shutdownTeammate(params.name);
+      if (!result.ok) throw new Error(result.error);
+      refreshTeamUI(ctx);
+      return { content: [{ type: "text", text: result.body }], 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.");
+    name: "send_message",
+    promptSnippet: "Send a message to a teammate",
+    label: "Send Message",
+    description: "The only messaging primitive. Address a living teammate by name; working teammates receive a steer immediately and idle teammates wake with the message. status is reserved for worker reports to leader.",
+    parameters: SendMessageParams,
+    // Canonical lifecycle rows (same as packages/monitor): empty call slot,
+    // ONE delivery row owned by renderResult.
+    renderShell: "self",
+    renderCall: () => new Text("", 0, 0),
+    renderResult(result, _options, theme, context) {
+      const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
+      if (context.isError) {
+        return new Text(theme.fg("error", text.split("\n")[0] || "Failed to send message."), 0, 0);
+      }
+      const to = String((context.args as { to?: string }).to ?? "");
+      const details = result.details as { queued?: boolean; stalledMs?: number } | undefined;
+      const suffix = details?.queued ? "queued" : "delivered";
+      let line = `${theme.fg("toolTitle", theme.bold(formatAgentMessagePrefix("to")))}${theme.fg("accent", `@${to}`)}${theme.fg("dim", ` · ${suffix}`)}`;
+      if (!details?.queued && details?.stalledMs !== undefined) {
+        line += theme.fg("dim", ` · stalled ${formatSilenceDuration(details.stalledMs)}`);
       }
-      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: {} };
+      return {
+        render: (width: number) => width > 0 ? [truncateToWidth(line, width)] : [],
+        invalidate: () => {},
+      };
     },
-  });
-
-  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);
+    async execute(_toolCallId, params) {
+      if (params.to === LEADER_RECIPIENT) throw new Error('The leader cannot send a message to itself.');
+      if (params.status) throw new Error('status is reserved for worker reports to="leader".');
+      const result = sendLeaderMessage(params.to, params.message);
       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: {} };
+      const disposition = result.queued ? "Queued for its next wake-up." : "Delivered to its running turn.";
+      let text = `Message to @${params.to}: ${disposition}`;
+      if (!result.queued && result.stalledMs !== undefined) {
+        text += `\nWarning: @${params.to} has been stalled with no output for ${formatSilenceDuration(result.stalledMs)} — the control-stream write succeeded, but the teammate may be wedged. Consider teammate_shutdown if it stays silent.`;
+      }
+      return {
+        content: [{ type: "text", text }],
+        details: result.stalledMs !== undefined && !result.queued
+          ? { queued: result.queued, stalledMs: result.stalledMs }
+          : { queued: result.queued },
+      };
     },
   });
 
   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,
+    name: "task_create",
+    promptSnippet: "Create a shared board task",
+    label: "Create Task",
+    description: "Create one shared board task. Resident teammates self-claim it when dependencies are met; an optional verify command gates completion.",
+    parameters: TaskCreateParams,
+    // Canonical lifecycle rows (same as packages/monitor): empty call slot,
+    // ONE created row owned by renderResult.
+    renderShell: "self",
+    renderCall: () => new Text("", 0, 0),
+    renderResult(result, _options, theme, context) {
+      const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
+      if (context.isError) {
+        return new Text(theme.fg("error", text.split("\n")[0] || "Failed to create task."), 0, 0);
+      }
+      const subject = String((context.args as { subject?: string }).subject ?? "");
+      const line = theme.fg("toolTitle", theme.bold(formatToolEventLabel("created", subject, "board")));
+      return {
+        render: (width: number) => width > 0 ? [truncateToWidth(line, width)] : [],
+        invalidate: () => {},
+      };
+    },
     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);
+      const tasks = listTasks();
+      if (params.dependsOn?.some((dep) => !tasks.some((task) => task.id === dep))) {
+        throw new Error(`Unknown dependency id in [${params.dependsOn.join(", ")}].`);
+      }
+      const created = createBoardTask(params);
+      if (!created.ok) throw new Error(created.error);
       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: {} };
+      return { content: [{ type: "text", text: `Created [${created.id}] "${params.subject}". Idle teammates are notified automatically.` }], details: {} };
     },
   });
+
+  registerTaskListTool(pi);
+}
+
+function teamStatusSummary(): string {
+  const roles = [...discoverAgents().keys()].map((name) => `@${name}`);
+  const rolesLine = roles.length > 0
+    ? `${roles.length} persistent agent role${roles.length === 1 ? "" : "s"}: ${roles.join(", ")}`
+    : "No agent roles discovered.";
+  return `${rosterSummary()}\n${rolesLine}`;
 }
 
 export function registerTeamCommand(pi: ExtensionAPI): void {
-  pi.registerCommand("teammate", {
-    description: "Open the full-screen teammate team console: run/node status, node details, interrupt/stop",
+  pi.registerCommand("agent-teams", {
+    description: "Agent Teams management console: session teammates and persistent agent roles",
     handler: async (_args, ctx) => {
-      if (ctx.mode !== "tui") {
-        ctx.ui.notify(getSummary() ?? "No runs yet — dispatch work with teammate_run.", "info");
-        return;
-      }
+      publishStateSnapshot();
+      if (ctx.mode !== "tui") { ctx.ui.notify(teamStatusSummary(), "info"); return; }
       await openTeamConsole(ctx);
       refreshTeamUI(ctx);
     },
   });
 }
+