@fradser/pi-agent-teams 0.8.3 → 0.9.0

package/src/tools.ts

@@ -1,222 +1,242 @@
-import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
-import { detailField, eventToolLifecycle, formatAgentTaskName, formatToolLifecycleTitle, notifyPi } from "@fradser/pi-kit";
+import { truncateHead, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { notifyPi } from "@fradser/pi-kit";
 import {
+  assignExistingWork,
+  releaseExistingWork,
+  reopenExistingWork,
   createBoardTask,
-  formatBoardTaskCreation,
-  hasAnnouncedFinish,
-  hasTerminalReport,
   publishStateSnapshot,
   sendLeaderMessage,
-  shutdownTeammate,
+  shutdownTeammateExact,
   spawnTeammate,
 } from "./team-machine.ts";
 import { listTasks, livingTeammates } from "./state.ts";
 
-const DYNAMIC_LEADER_TOOLS = ["teammate_shutdown", "send_message", "task_list"] as const;
-let leaderToolApi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools"> | undefined;
-
-/** Keep spawn as the entry point; reveal follow-on controls only when relevant. */
-export function refreshLeaderToolDisclosure(): void {
-  if (!leaderToolApi || typeof leaderToolApi.getActiveTools !== "function" || typeof leaderToolApi.setActiveTools !== "function") return;
-  const active = leaderToolApi.getActiveTools();
-  const withoutDynamic = active.filter((tool) => !DYNAMIC_LEADER_TOOLS.includes(tool as typeof DYNAMIC_LEADER_TOOLS[number]));
-  const revealed = [
-    ...(livingTeammates().length > 0 ? ["teammate_shutdown", "send_message"] : []),
-    ...(listTasks().length > 0 ? ["task_list"] : []),
-  ];
-  leaderToolApi.setActiveTools([...withoutDynamic, ...revealed]);
-}
-
-import { LEADER_RECIPIENT, SendMessageParams, TeammateShutdownParams, TeammateSpawnParams, TaskCreateParams } from "./types.ts";
-import { registerTaskListTool } from "./worker.ts";
+import { AgentActionParams, LEADER_RECIPIENT, AgentEventParams, WorkToolParams } from "./types.ts";
 import { openTeamConsole, refreshTeamUI } from "./ui.ts";
 import { discoverAgents } from "./agents.ts";
-import { emptyToolCall, renderLifecycleResult } from "./tool-render.ts";
+import { agentRow, leaderWorkRow, messageRow, type AgentRowArgs } from "./tool-copy.ts";
+import { emptyToolCall, renderCoordinationRow } from "./tool-render.ts";
+import { runAgentAction, type AgentActionRuntime } from "./agent-actions.ts";
+import { resolveRecipient } from "./recipient.ts";
 
-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");
+function formatWorkList(tasks: ReturnType<typeof listTasks>): string {
+  const works = tasks.map((task) => {
+    const dependencies = task.dependsOn.length > 0 ? ` · depends=${task.dependsOn.join(",")}` : "";
+    const holder = task.claimedBy ? ` · owner=@${task.claimedBy}` : "";
+    const result = task.result ? truncateHead(task.result, { maxBytes: 4096, maxLines: 40 }) : undefined;
+    const evidence = result ? `\n  RESULT · ${result.content}${result.truncated ? "\n  [Result preview truncated; complete evidence is retained in Work details.]" : ""}` : "";
+    return `- ${task.id} · ${task.status} · ${task.subject}${holder}${dependencies}${evidence}`;
+  });
+  return [
+    "WORK · current session",
+    `SUMMARY · ${tasks.length} work item${tasks.length === 1 ? "" : "s"}`,
+    "WORK ITEMS",
+    ...(works.length > 0 ? works : ["(none)"]),
+  ].join("\n");
 }
 
-function spawnAssignment(params: { name: string; agent: string; prompt?: string }): string {
-  const prompt = params.prompt?.trim();
-  if (!prompt) return "check task board";
-  const normalizedPrompt = prompt.replace(/^@/, "").trim().toLowerCase();
-  const name = params.name.replace(/^@/, "").toLowerCase();
-  const agent = params.agent.replace(/^@/, "").toLowerCase();
-  if (normalizedPrompt === name || normalizedPrompt === agent) {
-    return "check task board";
-  }
-  return formatAgentTaskName(prompt, "check task board");
+function formatWorkCreation(subject: string, created: {
+  id: string;
+  claimable: boolean;
+  resourceBlocked: boolean;
+  notifiedTeammates: string[];
+}): string {
+  const availability = created.claimable ? "pending/claimable" : "pending/blocked";
+  const routing = created.notifiedTeammates.length > 0
+    ? `eligible residents notified: ${created.notifiedTeammates.map((name) => `@${name}`).join(", ")}`
+    : created.resourceBlocked
+      ? "resource conflict blocks assignment"
+      : "no eligible resident notified";
+  return [
+    "WORK · current session",
+    `CREATED · ${created.id} · ${availability} · ${subject}`,
+    `ROUTING · ${routing}`,
+  ].join("\n");
 }
 
-export function registerLeaderTools(pi: ExtensionAPI): void {
-  pi.registerTool({
-    name: "teammate_spawn",
-    promptSnippet: "Spawn a named resident teammate or sub-agent",
-    label: "Spawn Teammate",
-    description: "Spawn one named resident teammate / sub-agent. Use this tool whenever instructions, third-party skills, or workflows ask to launch or delegate work to an agent, sub-agent (subagent), worker, or teammate. Generated role definitions stay in memory by default; persist one only when the user explicitly asks to keep it for future sessions.",
-    parameters: TeammateSpawnParams,
-    renderShell: "self",
-    renderCall: emptyToolCall,
-    renderResult(result, _options, theme, context) {
-      const text = result.content.find((part) => part.type === "text")?.text ?? "";
-      if (context.isError) return new Text(theme.fg("error", text.split("\n")[0] || "Failed to spawn teammate."), 0, 0);
-      const params = context.args as { name: string; agent: string; prompt?: string };
-      const title = formatToolLifecycleTitle({
-        kind: "started",
-        tool: "agent",
-        subject: `@${params.name} started · ${spawnAssignment(params)}`,
-      }).replace(/^\[agent\]\s*/, "");
-      const prefix = theme.fg("customMessageLabel", theme.bold("[agent]"));
-      return new Text(`${prefix} ${title}`, 0, 0);
-    },
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const result = spawnTeammate(params);
-      if (!result.ok) throw new Error(result.error);
-      refreshTeamUI(ctx);
-      refreshLeaderToolDisclosure();
-      const kickoffNote = params.prompt?.trim()
-        ? "It received your kickoff prompt and is working on it."
-        : "It received the standard board-check kickoff and is running its first turn; it idles once that settles.";
-      return {
-        content: [{ type: "text", text: `@${params.name} is alive as ${params.agent}.\n${kickoffNote}\n\n${rosterSummary()}` }],
-        details: { started: true },
-      };
-    },
-  });
-
+export function registerLeaderTools(pi: ExtensionAPI, runtime: AgentActionRuntime & { sendLeaderMessage: typeof sendLeaderMessage } = { spawnTeammate, shutdownTeammateExact, sendLeaderMessage }): void {
   pi.registerTool({
-    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,
+    name: "agent",
+    promptSnippet: "Delegate, start, inspect, or stop an Agent session",
+    label: "Agent",
+    description: "Strict Agent lifecycle interface. Delegate creates independent Work; start creates an unassigned resident; inspect and stop use incarnation-bound session handles. Results arrive automatically; inspect is for deliberate diagnosis, not waiting.",
+    promptGuidelines: ["After agent delegation, results arrive automatically. Continue independent work or end the turn; do not wait with sleep, repeated agent inspect, or work list polling."],
+    parameters: AgentActionParams,
     renderShell: "self",
     renderCall: emptyToolCall,
     renderResult(result, options, theme, context) {
-      const name = String((context.args as { name?: string }).name ?? "");
-      // The finish entry already announced this end of life (or its terminal
-      // report is queued to); a second event row is noise.
-      if (hasAnnouncedFinish(name) || hasTerminalReport(name)) return { render: () => [], invalidate: () => {} };
-      return renderLifecycleResult(result, options, theme, context, eventToolLifecycle(
+      return renderCoordinationRow(
+        result, options, theme, context,
         "agent",
-        `@${name} shut down`,
-        {},
-      ));
+        agentRow(context.args as AgentRowArgs, result.details, { isError: context.isError, isPartial: options.isPartial }),
+      );
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const result = await shutdownTeammate(params.name);
-      if (!result.ok) throw new Error(result.error);
-      refreshTeamUI(ctx);
-      refreshLeaderToolDisclosure();
-      return { content: [{ type: "text", text: result.body }], details: {} };
+      const result = await runAgentAction(params, ctx.cwd, runtime, ctx.sessionManager);
+      if (params.action !== "inspect") {
+        refreshTeamUI(ctx);
+      }
+      return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
     },
   });
 
   pi.registerTool({
-    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.",
-    parameters: SendMessageParams,
-    // Canonical lifecycle rows (same as packages/monitor): empty call slot,
-    // ONE delivery row owned by renderResult.
+    name: "agent_event",
+    promptSnippet: "Send an event or message to a participant",
+    label: "Agent Event",
+    description: "Shared communication interface across Leader, Worker, and Peers. Leader-to-Agent messages carry only new evidence, changed constraints, or decisions — never kickoff echoes, progress requests, completion requests, or confirmation probes.",
+    parameters: AgentEventParams,
     renderShell: "self",
     renderCall: emptyToolCall,
     renderResult(result, options, theme, context) {
-      const to = String((context.args as { to?: string }).to ?? "");
-      const outcome = detailField<"steered" | "queued" | "not-sent">(result.details, "outcome") ?? "queued";
-      const subject = outcome === "not-sent" ? "terminal report available" : outcome;
-      return renderLifecycleResult(result, options, theme, context, eventToolLifecycle(
+      return renderCoordinationRow(
+        result, options, theme, context,
         "message",
-        subject,
-        { label: `to @${to}`, detailLimit: outcome === "not-sent" ? "all" : undefined },
-      ));
+        messageRow(context.args as { to?: string; message?: string }, result.details, { isError: context.isError }),
+      );
     },
     async execute(_toolCallId, params) {
-      if (params.to === LEADER_RECIPIENT) throw new Error('The leader cannot send a message to itself.');
-      const result = sendLeaderMessage(params.to, params.message, {
-        reopen: params.reopen,
-        resources: params.resources,
-      });
-      if (!result.ok) throw new Error(result.error);
-      if (result.outcome === "not-sent") {
-        return {
-          content: [{
-            type: "text",
-            text: [
-              "ROUTING · not sent",
-              "NEXT · No new message was delivered. Read the recorded report below; use reopen=true only for a distinct new assignment.",
-              `NOTE · @${params.to} already sent a terminal report. Delivery to your context is automatic; asking it to resend produces a duplicate leader turn.`,
-              `RECORDED TERMINAL REPORT · ${result.terminalReport}`,
-            ].join("\n"),
-          }],
-          details: { outcome: "not-sent", terminalReportAvailable: true },
-        };
-      }
-      const action = result.outcome === "steered"
-        ? "active control stream accepted the steer"
-        : "harness will deliver the queued message on the next wake-up";
-      let text = `MESSAGING\n${result.outcome.toUpperCase()} · to=@${params.to}\nNEXT · ${action}`;
-      // A stray status field (copied from worker report patterns) must not
-      // block delivery — it carries no meaning on leader-sent messages.
-      if (params.status) text += `\nNOTE · status ignored for leader-directed steering`;
-      if (result.priorTerminalReport) {
-        text += `\nNOTE · @${params.to} already sent a terminal report (below); it reaches your context automatically. A steer asking it to repeat that report produces a duplicate delivery — use reopen only for a distinct new assignment.`;
-        text += `\nPRIOR TERMINAL REPORT · ${result.priorTerminalReport}`;
+      if (!params.to) {
+        throw new Error("No bound reply route exists. Please specify 'to' explicitly.");
       }
+      if (params.to === LEADER_RECIPIENT) throw new Error("The leader cannot send an event to itself.");
+      const to = resolveRecipient(params.to, livingTeammates()).name;
+      const result = runtime.sendLeaderMessage(to, params.message, {});
+      if (!result.ok) throw new Error(result.error);
+      const recorded = result.outcome === "not-sent" ? `\nRECORDED TERMINAL REPORT · ${result.terminalReport}` : "";
+      const next = "";
       return {
-        content: [{ type: "text", text }],
-        details: { outcome: result.outcome },
+        content: [{ type: "text", text: `EVENT ROUTING · ${result.outcome} · to=@${to}\nINTENT · ${params.intent ?? "inform"}${recorded}${next}` }],
+        details: { to, outcome: result.outcome, intent: params.intent ?? "inform" },
       };
     },
   });
 
   pi.registerTool({
-    name: "task_create",
-    promptSnippet: "Create a shared board task",
-    label: "Create Task",
-    description: "Create one pending task on the current session board. Existing idle teammates are notified immediately and may self-claim it; this tool never spawns teammates. An optional verify prompt gates completion through a fresh reviewer.",
-    parameters: TaskCreateParams,
-    // Canonical lifecycle rows (same as packages/monitor): empty call slot,
-    // ONE created row owned by renderResult.
+    name: "work",
+    promptSnippet: "Create, list, assign, release, reopen, or supersede Work Items",
+    label: "Work",
+    description: "Manage Work Items: create (subject), list, assign (id, target.session), release (id, reason), reopen (id, reason), or supersede (subject, supersedes). Creation uses the session's single-writer Work state and never starts a resident.",
+    parameters: WorkToolParams,
     renderShell: "self",
     renderCall: emptyToolCall,
     renderResult(result, options, theme, context) {
-      const subject = String((context.args as { subject?: string }).subject ?? "");
-      return renderLifecycleResult(result, options, theme, context, eventToolLifecycle(
-        "board",
-        subject,
-        { label: "created" },
-      ));
+      return renderCoordinationRow(
+        result, options, theme, context,
+        "work",
+        leaderWorkRow(context.args as Record<string, unknown>, result.details, { isError: context.isError }),
+      );
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      if (params.action === "supersede") {
+        const tasks = listTasks();
+        const referenced = [...(params.dependsOn ?? []), ...params.supersedes];
+        if (referenced.some((id) => !tasks.some((task) => task.id === id))) {
+          throw new Error(`Unknown work id in [${referenced.join(", ")}].`);
+        }
+        const created = createBoardTask(params);
+        if (!created.ok) throw new Error(created.error);
+        const work = listTasks().find((task) => task.id === created.id);
+        if (!work) throw new Error(`Replacement Work Item "${created.id}" is unavailable.`);
+        refreshTeamUI(ctx);
+        return {
+          content: [{ type: "text", text: `WORK · current session\nSUPERSEDED · ${work.id} · ${work.status}\nREPLACED · ${created.supersededTaskIds.join(", ")}\nROUTING · ${created.notifiedTeammates.length > 0 ? `eligible residents notified: ${created.notifiedTeammates.map((name) => `@${name}`).join(", ")}` : "no eligible resident notified"}` }],
+          details: {
+            action: "supersede", outcome: "superseded", state: work.status,
+            work: { id: work.id, subject: work.subject, ...(work.description ? { description: work.description } : {}), dependsOn: work.dependsOn, resources: work.resources, ...(work.verify ? { verify: work.verify } : {}), state: work.status },
+            supersededWorkIds: created.supersededTaskIds, notifiedTeammates: created.notifiedTeammates, claimable: created.claimable,
+          },
+        };
+      }
+      if (params.action === "reopen") {
+        const reopened = reopenExistingWork(params.id);
+        if (!reopened.ok) throw new Error(reopened.error);
+        refreshTeamUI(ctx);
+        return {
+          content: [{ type: "text", text: `WORK · current session\nREOPENED · ${reopened.workId} · pending\nREASON · ${params.reason}` }],
+          details: { action: "reopen", outcome: "reopened", state: "pending", work: { id: reopened.workId, subject: reopened.subject, resources: reopened.resources, state: "pending" }, reason: params.reason },
+        };
+      }
+      if (params.action === "release") {
+        const released = releaseExistingWork(params.id, params.reason);
+        if (!released.ok) throw new Error(released.error);
+        refreshTeamUI(ctx);
+        const residual = released.holderStillRunning
+          ? `\nRISK · @${released.holderStillRunning} was still working; an in-flight tool batch may still write inside ${released.resources.join(", ") || "the released scope"}.`
+          : "";
+        return {
+          content: [{ type: "text", text: `WORK · current session\nRELEASED · ${released.workId} · pending\nREASON · ${params.reason}${residual}` }],
+          details: { action: "release", outcome: "released", state: "pending", work: { id: released.workId, subject: released.subject, resources: released.resources, state: "pending" }, reason: params.reason, ...(released.holderStillRunning ? { holderStillRunning: released.holderStillRunning } : {}) },
+        };
+      }
+      if (params.action === "assign") {
+        const assigned = assignExistingWork(params.id, params.target.session);
+        if (!assigned.ok) throw new Error(assigned.error);
+        const task = listTasks().find((entry) => entry.id === assigned.workId);
+        if (!task) throw new Error(`Assigned Work Item "${assigned.workId}" is unavailable.`);
+        refreshTeamUI(ctx);
+        return {
+          content: [{ type: "text", text: `WORK · current session\nASSIGNED · ${task.id} · claimed · owner=@${assigned.owner}\nATTEMPT · ${assigned.assignmentId} · fresh-session-pending` }],
+          details: {
+            action: "assign", outcome: "assigned", state: task.status,
+            work: { id: task.id, subject: task.subject, resources: task.resources, state: task.status, claimedBy: task.claimedBy },
+            assignment: { id: assigned.assignmentId, owner: assigned.owner, kind: "direct" },
+            target: params.target, delivery: "fresh-session-pending",
+          },
+        };
+      }
+      if (params.action === "list") {
+        const works = listTasks().map((task) => ({
+          id: task.id,
+          subject: task.subject,
+          ...(task.description ? { description: task.description } : {}),
+          dependsOn: task.dependsOn,
+          resources: task.resources,
+          ...(task.verify ? { verify: task.verify } : {}),
+          state: task.status,
+          ...(task.claimedBy ? { claimedBy: task.claimedBy } : {}),
+          ...(task.result ? { result: task.result } : {}),
+        }));
+        return {
+          content: [{ type: "text", text: formatWorkList(listTasks()) }],
+          details: { action: "list", outcome: "listed", works, count: works.length },
+        };
+      }
       const tasks = listTasks();
-      const referenced = [...(params.dependsOn ?? []), ...(params.supersedes ?? [])];
+      const referenced = params.dependsOn ?? [];
       if (referenced.some((id) => !tasks.some((task) => task.id === id))) {
-        throw new Error(`Unknown task id in [${referenced.join(", ")}].`);
+        throw new Error(`Unknown work id in [${referenced.join(", ")}].`);
       }
       const created = createBoardTask(params);
       if (!created.ok) throw new Error(created.error);
+      const work = listTasks().find((task) => task.id === created.id);
+      if (!work) throw new Error(`Created Work Item "${created.id}" is unavailable.`);
       refreshTeamUI(ctx);
-      refreshLeaderToolDisclosure();
       return {
-        content: [{ type: "text", text: formatBoardTaskCreation(params.subject, created) }],
+        content: [{ type: "text", text: formatWorkCreation(params.subject, created) }],
         details: {
+          action: "create",
+          outcome: "created",
+          state: work.status,
+          work: {
+            id: work.id,
+            subject: work.subject,
+            ...(work.description ? { description: work.description } : {}),
+            dependsOn: work.dependsOn,
+            resources: work.resources,
+            ...(work.verify ? { verify: work.verify } : {}),
+            state: work.status,
+          },
           notifiedTeammates: created.notifiedTeammates,
-          livingTeammates: created.livingTeammates,
           claimable: created.claimable,
-          supersededTaskIds: created.supersededTaskIds,
+          supersededWorkIds: created.supersededTaskIds,
         },
       };
     },
   });
 
-  registerTaskListTool(pi);
-  leaderToolApi = pi;
+
 }
 
 function teamStatusSummary(): string {
@@ -224,7 +244,8 @@ function teamStatusSummary(): string {
   const rolesLine = roles.length > 0
     ? `${roles.length} persistent agent role${roles.length === 1 ? "" : "s"}: ${roles.join(", ")}`
     : "No agent roles discovered.";
-  return `${rosterSummary()}\n${rolesLine}`;
+  const roster = livingTeammates().map((t) => `@${t.name} (${t.agent}, ${t.status})`).join("\n") || "No living sessions.";
+  return `${roster}\n${rolesLine}`;
 }
 
 export function registerTeamCommand(pi: ExtensionAPI): void {