@fradser/pi-agent-teams 0.7.0 → 0.8.2

package/src/worker.ts

@@ -6,7 +6,9 @@
 
 import { randomUUID } from "node:crypto";
 import * as path from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { detailField, eventToolLifecycle } from "@fradser/pi-kit";
+import { emptyToolCall, renderLifecycleResult } from "./tool-render.ts";
 import { livingTeammates, listTasks } from "./state.ts";
 import { appendInboxMessage, appendWorkerEvent, createTaskIntent, readBoardFile, readRoster } from "./statefile.ts";
 import {
@@ -19,6 +21,46 @@ import {
   type BoardTask,
 } from "./types.ts";
 
+const BOARD_DISCLOSURE_TOOLS = ["task_list", "task_claim", "task_submit"] as const;
+type BoardDisclosure = "none" | "notice" | "claimed";
+
+export interface WorkerToolDisclosure {
+  update(prompt: string): void;
+  reset(): void;
+}
+
+function createWorkerToolDisclosure(pi: ExtensionAPI): WorkerToolDisclosure {
+  let state: BoardDisclosure = "none";
+  const apply = () => {
+    if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+    const active = pi.getActiveTools();
+    const withoutBoardControls = active.filter((tool) => !BOARD_DISCLOSURE_TOOLS.includes(tool as typeof BOARD_DISCLOSURE_TOOLS[number]));
+    const revealed = state === "notice"
+      ? ["task_list", "task_claim"]
+      : state === "claimed"
+        ? ["task_submit"]
+        : [];
+    pi.setActiveTools([...withoutBoardControls, ...revealed]);
+  };
+  return {
+    update(prompt) {
+      const binding = workerBinding();
+      const rosterEntry = binding
+        ? readRoster(binding.rosterFile).find((entry) => entry.name === binding.worker)
+        : undefined;
+      const assignment = rosterEntry?.assignment;
+      if (assignment?.kind === "board" && !assignment.closed) state = "claimed";
+      else if (!assignment && prompt.includes("=== BOARD NOTICE ===")) state = "notice";
+      else state = "none";
+      apply();
+    },
+    reset() {
+      state = "none";
+      apply();
+    },
+  };
+}
+
 export interface WorkerBinding {
   worker: string;
   spawnId: string;
@@ -63,18 +105,54 @@ function dependenciesMet(task: BoardTask, tasks: Map<string, BoardTask>): boolea
   return task.dependsOn.every((dep) => tasks.get(dep)?.status === "completed");
 }
 
+function taskCounts(tasks: BoardTask[], byId: Map<string, BoardTask>): string {
+  const counts = { pending: 0, claimed: 0, completed: 0, superseded: 0 };
+  for (const task of tasks) counts[task.status] += 1;
+  const claimable = tasks.filter((task) => task.status === "pending" && dependenciesMet(task, byId)).length;
+  return `tasks=${tasks.length} · pending=${counts.pending} (${claimable} claimable) · claimed=${counts.claimed} · completed=${counts.completed} · superseded=${counts.superseded}`;
+}
+
+function resourcesConflict(left: readonly string[] | undefined, right: readonly string[] | undefined): boolean {
+  return (left ?? []).some((a) => (right ?? []).some((b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`)));
+}
+
+function claimRejection(binding: WorkerBinding, task: BoardTask): string | undefined {
+  const self = readRoster(binding.rosterFile).find((entry) => entry.name === binding.worker);
+  if (self?.assignment) {
+    const state = self.assignment.closed ? "closed pending leader reopen" : "active";
+    return `You already own ${state} ${self.assignment.kind} assignment "${self.assignment.id}". Finish it through its matching protocol before claiming board work.`;
+  }
+  const conflict = readRoster(binding.rosterFile).find((entry) => entry.name !== binding.worker
+    && entry.assignment && !entry.assignment.closed
+    && resourcesConflict(task.resources, entry.assignment.resources));
+  if (conflict) {
+    return `Task "${task.id}" conflicts with @${conflict.name}'s ${conflict.assignment?.kind} assignment "${conflict.assignment?.id}".`;
+  }
+  return undefined;
+}
+
+function taskStatusLabel(task: BoardTask, tasks: Map<string, BoardTask>): string {
+  if (task.status === "pending") return dependenciesMet(task, tasks) ? "pending/claimable" : "pending/blocked";
+  return task.status;
+}
+
 export function renderTaskBoard(tasks: BoardTask[]): string {
-  if (tasks.length === 0) return "(the task board is empty)";
   const byId = new Map(tasks.map((task) => [task.id, task]));
-  return tasks.map((task) => {
+  const lines = [`BOARD · current session`, `SUMMARY · ${taskCounts(tasks, byId)}`];
+  if (tasks.length === 0) return `${lines.join("\n")}\nTASKS\n(no tasks)`;
+  lines.push("TASKS");
+  for (const task of tasks) {
     const deps = task.dependsOn.length > 0
-      ? ` | depends on ${task.dependsOn.join(", ")} (${dependenciesMet(task, byId) ? "met" : "unmet"})`
+      ? ` · depends=${task.dependsOn.join(",")} (${dependenciesMet(task, byId) ? "met" : "blocked"})`
       : "";
-    const holder = task.claimedBy ? ` by @${task.claimedBy}` : "";
-    const verify = task.verify ? ` | verify: ${task.verify}` : "";
-    const description = task.description ? `\n    ${task.description.slice(0, 2000)}` : "";
-    return `- [${task.id}] ${task.status}${holder}: ${task.subject}${deps}${verify}${description}`;
-  }).join("\n");
+    const holder = task.claimedBy ? ` · claimant=@${task.claimedBy}` : "";
+    lines.push(`- ${task.id} · ${taskStatusLabel(task, byId)} · ${task.subject}${holder}${deps}`);
+  }
+  return lines.join("\n");
+}
+
+function renderRoster(roster: string): string {
+  return `ROSTER\n${roster || "(none)"}`;
 }
 
 /** One registration shared by leader and worker; binding chooses the data source. */
@@ -83,8 +161,18 @@ export function registerTaskListTool(pi: ExtensionAPI): void {
     name: "task_list",
     promptSnippet: "Read the shared task board",
     label: "Task Board",
-    description: "Read board tasks with status, dependencies, and verify gates. Pending tasks with met dependencies are claimable.",
+    description: "Read the current session board as grouped task state plus a compact roster. Pending tasks with met dependencies are claimable.",
     parameters: TaskListParams,
+    renderShell: "self",
+    renderCall: emptyToolCall,
+    renderResult(result, options, theme, context) {
+      const count = detailField<number>(result.details, "count") ?? 0;
+      return renderLifecycleResult(result, options, theme, context, eventToolLifecycle(
+        "board",
+        `${count} task${count === 1 ? "" : "s"}`,
+        { label: "listed" },
+      ));
+    },
     async execute() {
       const binding = workerBinding();
       const tasks = binding ? loadBoardTasks(binding) : listTasks();
@@ -92,21 +180,41 @@ export function registerTaskListTool(pi: ExtensionAPI): void {
       const roster = binding
         ? readRoster(binding.rosterFile)
             .filter((entry) => entry.status !== "stopped")
-            .map((entry) => `@${entry.name} (${entry.agent}, ${entry.status})`)
+            .map((entry) => `@${entry.name} (${entry.agent}, ${entry.status}${entry.assignment ? `, ${entry.assignment.kind} ${entry.assignment.id}` : ""})`)
             .join("\n")
         : livingTeammates().map((t) => `@${t.name} (${t.agent}, ${t.status}${t.currentTaskId ? `, task ${t.currentTaskId}` : ""})`).join("\n");
-      return { content: [{ type: "text", text: `${renderTaskBoard(tasks)}\n\nRoster:\n${roster || "(none)"}` }], details: {} };
+      const leaderHint = !binding && !roster && tasks.some((task) => task.status === "pending")
+        ? "NEXT · leader: teammate_spawn; workers then use task_claim"
+        : tasks.some((task) => task.status === "pending")
+          ? "NEXT · workers use task_claim for pending/claimable tasks"
+          : "NEXT · no claimable work";
+      return {
+        content: [{ type: "text", text: `${renderTaskBoard(tasks)}\n${leaderHint}\n\n${renderRoster(roster)}` }],
+        details: { count: tasks.length },
+      };
     },
   });
 }
 
-export function registerWorkerCapabilities(pi: ExtensionAPI): void {
+export function registerWorkerCapabilities(pi: ExtensionAPI): WorkerToolDisclosure {
+  const disclosure = createWorkerToolDisclosure(pi);
   pi.registerTool({
     name: "send_message",
     promptSnippet: "Send a message to the leader or a teammate",
     label: "Send Message",
     description: "The only messaging primitive. Use to=\"leader\" for reports; use a teammate name for direct peer mail. status is valid only for leader reports.",
     parameters: SendMessageParams,
+    renderShell: "self",
+    renderCall: emptyToolCall,
+    renderResult(result, options, theme, context) {
+      const to = String((context.args as { to?: string }).to ?? "");
+
+      return renderLifecycleResult(result, options, theme, context, eventToolLifecycle(
+        "message",
+        detailField<"steered" | "queued">(result.details, "outcome") ?? "queued",
+        { label: `to @${to}` },
+      ));
+    },
     async execute(_toolCallId, params) {
       const binding = workerBinding();
       if (!binding) throw new Error("This capability is available only inside a spawned teammate.");
@@ -118,10 +226,15 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): void {
           spawnId: binding.spawnId,
           body: params.message,
           status: params.status,
+          timestamp: Date.now(),
         });
-        return { content: [{ type: "text", text: params.status
-          ? "Queued message to leader."
-          : 'Queued message to leader. Note: without status="completed" or status="failed" this report does not end your assignment.' }], details: {} };
+        return {
+          content: [{ type: "text", text: params.status
+            ? `MESSAGING\nREPORT · to=leader · status=${params.status}\nNEXT · harness will deliver this report`
+            : 'MESSAGING\nREPORT · to=leader · status=in_progress\nNEXT · send status="completed" or status="failed" to end the assignment' }],
+          details: { to: LEADER_RECIPIENT, status: params.status ?? "in_progress", outcome: "queued" },
+          terminate: params.status === "completed" || params.status === "failed",
+        };
       }
       if (params.status) throw new Error('status is valid only when to="leader".');
       if (params.to === binding.worker) throw new Error("You are already the recipient — no need to message yourself.");
@@ -135,7 +248,10 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): void {
         subject: messageTitle(params.message),
         body: params.message,
       });
-      return { content: [{ type: "text", text: `Delivered to @${params.to}'s inbox.` }], details: {} };
+      return {
+        content: [{ type: "text", text: `MESSAGING\nQUEUED · to=@${params.to}\nNEXT · harness will route the inbox message into a recipient turn` }],
+        details: { to: params.to, outcome: "queued" },
+      };
     },
   });
 
@@ -143,6 +259,16 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): void {
 
   pi.registerTool({
     name: "task_claim",
+    renderShell: "self",
+    renderCall: emptyToolCall,
+    renderResult(result, options, theme, context) {
+      const taskId = String((context.args as { taskId?: string }).taskId ?? "first claimable");
+      return renderLifecycleResult(result, options, theme, context, eventToolLifecycle(
+        "board",
+        taskId,
+        { label: "claim queued" },
+      ));
+    },
     promptSnippet: "Self-claim a pending board task",
     label: "Claim Task",
     description: "Atomically claim a pending task whose dependencies are met. Omit taskId to claim the first claimable task.",
@@ -160,6 +286,11 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): void {
       }
       for (const task of candidates) {
         if (task.status !== "pending" || !dependenciesMet(task, byId)) continue;
+        const rejected = claimRejection(binding, task);
+        if (rejected) {
+          if (params.taskId) throw new Error(rejected);
+          continue;
+        }
         const won = createTaskIntent(binding.claimsDir, task.id, {
           taskId: task.id,
           worker: binding.worker,
@@ -167,7 +298,10 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): void {
           timestamp: Date.now(),
         });
         if (won) {
-          return { content: [{ type: "text", text: `You won [${task.id}] "${task.subject}". Submit with task_submit.` }], details: {} };
+          return {
+            content: [{ type: "text", text: `BOARD · current session\nCLAIM INTENT QUEUED · ${task.id} · ${task.subject}\nREQUESTER · @${binding.worker}\nNEXT · wait for harness Claim accepted feedback; do not start work until it arrives` }],
+            details: { taskId: task.id, subject: task.subject, worker: binding.worker },
+          };
         }
         if (params.taskId) throw new Error(`Task "${task.id}" was claimed by someone else first.`);
       }
@@ -177,6 +311,17 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): void {
 
   pi.registerTool({
     name: "task_submit",
+    renderShell: "self",
+    renderCall: emptyToolCall,
+    renderResult(result, options, theme, context) {
+      const taskId = String((context.args as { taskId?: string }).taskId ?? "task");
+      const status = String((context.args as { status?: string }).status ?? "submitted");
+      return renderLifecycleResult(result, options, theme, context, eventToolLifecycle(
+        "board",
+        taskId,
+        { label: status },
+      ));
+    },
     promptSnippet: "Submit a claimed task outcome",
     label: "Submit Task",
     description: "Submit a task you claimed. completed runs its verify gate; failed releases the task back to the board.",
@@ -193,7 +338,25 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): void {
         timestamp: Date.now(),
       });
       if (!won) throw new Error(`A submission for "${params.taskId}" is already pending.`);
-      return { content: [{ type: "text", text: `Submitted ${params.status} for [${params.taskId}].` }], details: {} };
+      disclosure.reset();
+      const task = loadBoardTasks(binding).find((candidate) => candidate.id === params.taskId);
+      const roleVerify = process.env.PI_TEAMMATE_VERIFY_DEFAULT?.trim();
+      const verify = params.status === "completed"
+        ? task?.verify
+          ? "VERIFY · queued (task gate)"
+          : roleVerify
+            ? "VERIFY · queued (role gate)"
+            : "VERIFY · none configured"
+        : "VERIFY · skipped (failed submission)";
+      const next = params.status === "completed"
+        ? "NEXT · wait for the harness result"
+        : "NEXT · task returns to pending";
+      return {
+        content: [{ type: "text", text: `BOARD · current session\nSUBMITTED · ${params.taskId} · ${params.status}\n${verify}\n${next}` }],
+        details: { taskId: params.taskId, status: params.status, verify: Boolean(task?.verify || roleVerify) },
+      };
     },
   });
+
+  return disclosure;
 }

package/src/worktree.ts

@@ -4,7 +4,8 @@
  *
  * Layout: `<repoRoot>/.pi/worktrees/teammate-<taskId>/`, branch
  * `teammate/<taskId>`. On completion the worker's diff is captured against
- * the base commit, then the worktree and branch are removed.
+ * the base commit, then the worktree directory is removed while the branch
+ * stays so captured work remains retrievable.
  */
 
 import { execFileSync, spawnSync } from "node:child_process";
@@ -104,15 +105,50 @@ export function captureWorktreeDiff(setup: WorktreeSetup): WorktreeDiffResult {
 }
 
 /**
- * Remove the worktree and its branch. Errors are returned rather than thrown
- * so task completion is never blocked by cleanup failure.
+ * Commit any remaining worktree changes onto the branch. Staging alone dies
+ * with the worktree directory; only a commit makes the kept branch carry the
+ * captured work. A clean tree succeeds without a commit.
  */
-export function cleanupWorktree(setup: WorktreeSetup): { ok: boolean; error?: string } {
-  const remove = runGit(setup.repoRoot, ["worktree", "remove", "--force", setup.path]);
-  const branch = runGit(setup.repoRoot, ["branch", "-D", setup.branch]);
+function commitRemainingWork(setup: WorktreeSetup): { ok: boolean; error?: string } {
+  const add = runGit(setup.path, ["add", "-A"]);
+  if (add.status !== 0) return { ok: false, error: add.stderr.trim() || "git add failed" };
+  const result = spawnSync("git", ["-C", setup.path, "commit", "-m", "agent-teams: capture teammate work"], { encoding: "utf-8" });
+  if (result.status === 0) return { ok: true };
+  const output = `${result.stderr ?? ""}${result.stdout ?? ""}`;
+  if (/nothing to commit/i.test(output)) return { ok: true };
+  return { ok: false, error: output.trim() || "git commit failed" };
+}
+
+/**
+ * Remove the worktree directory but keep the branch: remaining changes are
+ * committed first so the captured diff stays retrievable with
+ * `git diff <baseCommit>..<branch>` after cleanup. Pass `{ deleteBranch: true }`
+ * for teardowns where no work was captured (a failed spawn). When the commit
+ * fails in keep-branch mode the directory is PRESERVED and returned in the
+ * error — removing it would destroy the only copy of the work. Errors are
+ * returned rather than thrown so task completion is never blocked by cleanup
+ * failure.
+ */
+export function cleanupWorktree(
+  setup: WorktreeSetup,
+  options?: { deleteBranch?: boolean },
+): { ok: boolean; error?: string } {
   const errors: string[] = [];
+  if (!options?.deleteBranch) {
+    const commit = commitRemainingWork(setup);
+    if (!commit.ok) {
+      return {
+        ok: false,
+        error: `commit: ${commit.error}; worktree left in place at ${setup.path} so the work is not lost`,
+      };
+    }
+  }
+  const remove = runGit(setup.repoRoot, ["worktree", "remove", "--force", setup.path]);
   if (remove.status !== 0) errors.push(`worktree remove: ${remove.stderr.trim()}`);
-  if (branch.status !== 0) errors.push(`branch delete: ${branch.stderr.trim()}`);
+  if (options?.deleteBranch) {
+    const branch = runGit(setup.repoRoot, ["branch", "-D", setup.branch]);
+    if (branch.status !== 0) errors.push(`branch delete: ${branch.stderr.trim()}`);
+  }
   try {
     runGit(setup.repoRoot, ["worktree", "prune"]);
   } catch {
@@ -121,7 +157,8 @@ export function cleanupWorktree(setup: WorktreeSetup): { ok: boolean; error?: st
   return errors.length > 0 ? { ok: false, error: errors.join("; ") } : { ok: true };
 }
 
-/** Best-effort cleanup used when a spawn fails before the worker starts. */
+/** Best-effort cleanup used when a spawn fails before the worker starts:
+ *  nothing was captured, so the empty branch goes too. */
 export function discardWorktree(setup: WorktreeSetup): void {
-  cleanupWorktree(setup);
+  cleanupWorktree(setup, { deleteBranch: true });
 }