@fradser/pi-agent-teams 0.5.3 → 0.6.0

package/src/tools.ts

@@ -1,213 +1,217 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { discoverAgents, resolveAgent } from "./agents";
+import { formatAgentMessagePrefix, formatAgentTaskName, formatToolEventLabel } 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 { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import * as fs from "node:fs";
+import * as path from "node:path";
 
-function dispatchContext(ctx: ExtensionContext): DispatchCtx {
-  return { ui: ctx.ui, sessionManager: ctx.sessionManager, cwd: ctx.cwd };
+function isValidAgentName(name: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) && !name.includes("..") && name !== "con";
 }
 
-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)"}.`);
-        }
-      }
-      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();
-      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: {},
-        };
+    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 ((result as { isError?: boolean }).isError) {
+        return new Text(theme.fg("error", text.split("\n")[0] || "Failed to spawn teammate."), 0, 0);
       }
-      return { content: [{ type: "text", text: await gatherForeground(run.id, signal) }], details: {} };
+      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: () => {},
+      };
     },
-  });
-
-  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: {} };
+      const result = spawnTeammate(params);
+      if (!result.ok) throw new Error(result.error);
+      refreshTeamUI(ctx);
+      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_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: "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 ((result as { isError?: boolean }).isError) {
+        return new Text(theme.fg("error", text.split("\n")[0] || "Failed to shut down teammate."), 0, 0);
       }
-      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: {} };
+      const name = String((context.args as { name?: string }).name ?? "");
+      const line = `${theme.fg("toolTitle", theme.bold(formatToolEventLabel("event", `@${name} shut down`).trimEnd()))}`;
+      return {
+        render: (width: number) => [truncateToWidth(line, Math.max(1, width))],
+        invalidate: () => {},
+      };
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      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_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);
+    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,
+    renderCall(args, theme) {
+      const prefix = theme.fg("toolTitle", theme.bold(formatAgentMessagePrefix("to")));
+      const recipient = theme.fg("accent", `@${String(args.to ?? "")}`);
+      return new Text(`${prefix}${recipient}`, 0, 0);
+    },
+    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: {} };
     },
   });
 
   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,
     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);
 }
 
 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 menu: console and create agents from session history",
     handler: async (_args, ctx) => {
-      if (ctx.mode !== "tui") {
-        ctx.ui.notify(getSummary() ?? "No runs yet — dispatch work with teammate_run.", "info");
+      const choice = await ctx.ui.select("agent-teams", ["console", "project", "local"]);
+      if (!choice) return;
+      if (choice === "console") {
+        publishStateSnapshot();
+        if (ctx.mode !== "tui") { ctx.ui.notify(rosterSummary(), "info"); return; }
+        await openTeamConsole(ctx);
+        refreshTeamUI(ctx);
         return;
       }
-      await openTeamConsole(ctx);
-      refreshTeamUI(ctx);
+      await createAgentFromHistory(ctx, choice === "local");
     },
   });
 }
+
+interface GeneratedAgent { name?: string; description?: string; tools?: string[]; prompt?: string; content?: string; }
+
+function parseGeneratedAgents(raw: string): GeneratedAgent[] {
+  const cleaned = raw.trim().replace(/^```(?:json)?\s*|\s*```$/g, "");
+  const start = cleaned.indexOf("[");
+  const end = cleaned.lastIndexOf("]");
+  if (start < 0 || end <= start) return [];
+  try {
+    const value: unknown = JSON.parse(cleaned.slice(start, end + 1));
+    return Array.isArray(value) ? value.filter((item): item is GeneratedAgent => Boolean(item && typeof item === "object")) : [];
+  } catch { return []; }
+}
+
+function renderAgentDefinition(agent: GeneratedAgent): string {
+  const name = agent.name!.trim();
+  const description = (agent.description || "Agent created from session history").replace(/[\r\n]+/g, " ").trim();
+  const tools = Array.isArray(agent.tools) ? agent.tools.filter((tool) => typeof tool === "string" && tool.trim()).join(", ") : "";
+  return `---\nname: ${name}\ndescription: ${description}${tools ? `\ntools: ${tools}` : ""}\n---\n\n${(agent.prompt || "").trim()}`;
+}
+
+async function createAgentFromHistory(ctx: ExtensionContext, local: boolean): Promise<void> {
+  const branch = ctx.sessionManager?.getBranch?.() ?? [];
+  const history = branch.map((entry: any) => {
+    const text = typeof entry?.text === "string" ? entry.text : typeof entry?.content === "string" ? entry.content : "";
+    return text ? text : Array.isArray(entry?.content) ? entry.content.map((part: any) => part?.text ?? "").join("") : "";
+  }).filter(Boolean).slice(-20).join("\n\n");
+  const generated = await generateAgentPrompt(ctx, history);
+  if (!generated) return;
+  const dir = path.join(ctx.cwd || process.cwd(), ".pi", "agents");
+  fs.mkdirSync(dir, { recursive: true });
+  const definitions = parseGeneratedAgents(generated)
+    .filter((item) => typeof item.name === "string" && (item.content?.trim() || item.prompt?.trim()))
+    .map((item) => ({ name: item.name!.trim(), content: item.content?.trim() || renderAgentDefinition(item) }));
+  if (definitions.length === 0) { ctx.ui.notify("Model returned no usable agent definitions", "error"); return; }
+  let created = 0;
+  for (const definition of definitions) {
+    if (!isValidAgentName(definition.name)) continue;
+    const filename = `${definition.name}${local ? ".local" : ""}.md`;
+    try { fs.writeFileSync(path.join(dir, filename), definition.content, { encoding: "utf8", flag: "wx" }); created++; } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+  ctx.ui.notify(`Created ${created} agent definition${created === 1 ? "" : "s"}`, created ? "info" : "warning");
+}
+
+async function generateAgentPrompt(ctx: ExtensionContext, history: string): Promise<string | undefined> {
+  const model = ctx.model;
+  const registry = ctx.modelRegistry;
+  if (!model || !registry?.complete) {
+    ctx.ui.notify("No model available to generate an agent", "error");
+    return undefined;
+  }
+  const response = await registry.complete(model, {
+    systemPrompt: "Design a complementary resident coding agent team from session history. Return a JSON array of 2-4 complementary agent definitions. Each item must have name, description, tools, and prompt fields. Names use letters, digits, dots, dashes, underscores. Return JSON only, with no code fences.",
+    messages: [{ role: "user", content: `Session history:\n${history || "(empty)"}`, timestamp: Date.now() }],
+  }, { maxTokens: 2000, temperature: 0, cacheRetention: "none" });
+  const content = response.content?.filter((part: any) => part.type === "text").map((part: any) => part.text).join("\\n").trim();
+  if (!content) { ctx.ui.notify("Model returned no agent definition", "error"); return undefined; }
+  return content;
+}