@fradser/pi-agent-teams 0.5.3 → 0.7.0

package/src/worker.ts

@@ -1,59 +1,199 @@
+/**
+ * Teammate capabilities. A single addressed send_message primitive covers
+ * leader reports and peer mail. Task-list registration is shared by leader
+ * and worker processes; claiming and submitting remain worker-only.
+ */
+
 import { randomUUID } from "node:crypto";
+import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { appendWorkerEvent } from "./statefile";
-import { TeammateMessageParams, type WorkerEvent } from "./types";
+import { livingTeammates, listTasks } from "./state.ts";
+import { appendInboxMessage, appendWorkerEvent, createTaskIntent, readBoardFile, readRoster } from "./statefile.ts";
+import {
+  LEADER_RECIPIENT,
+  messageTitle,
+  SendMessageParams,
+  TaskClaimParams,
+  TaskListParams,
+  TaskSubmitParams,
+  type BoardTask,
+} from "./types.ts";
 
 export interface WorkerBinding {
   worker: string;
-  taskId: string;
   spawnId: string;
   outbox: string;
+  inbox: string;
+  rosterFile: string;
+  boardFile: string;
+  claimsDir: string;
+  submissionsDir: string;
+}
+
+const REQUIRED_ENV = [
+  "PI_TEAMMATE_WORKER_NAME",
+  "PI_TEAMMATE_SPAWN_ID",
+  "PI_TEAMMATE_OUTBOX_FILE",
+  "PI_TEAMMATE_INBOX_FILE",
+  "PI_TEAMMATE_ROSTER_FILE",
+  "PI_TEAMMATE_BOARD_FILE",
+  "PI_TEAMMATE_CLAIMS_DIR",
+  "PI_TEAMMATE_SUBMISSIONS_DIR",
+] as const;
+
+export function workerBinding(): WorkerBinding | undefined {
+  const values = REQUIRED_ENV.map((name) => process.env[name]);
+  if (values.some((value) => !value)) return undefined;
+  const [worker, spawnId, outbox, inbox, rosterFile, boardFile, claimsDir, submissionsDir] = values as string[];
+  return { worker, spawnId, outbox, inbox, rosterFile, boardFile, claimsDir, submissionsDir };
+}
+
+function livingRecipients(binding: WorkerBinding): Set<string> {
+  return new Set(readRoster(binding.rosterFile)
+    .filter((entry) => entry.status !== "stopped")
+    .map((entry) => entry.name));
+}
+
+function loadBoardTasks(binding: WorkerBinding): BoardTask[] {
+  const board = readBoardFile(binding.boardFile);
+  return Object.values(board?.tasks ?? {}).sort((a, b) => a.id.localeCompare(b.id));
 }
 
-export function workerOutboxBinding(): WorkerBinding | undefined {
-  const worker = process.env.PI_TEAMMATE_WORKER_NAME;
-  const taskId = process.env.PI_TEAMMATE_TASK_ID;
-  const spawnId = process.env.PI_TEAMMATE_SPAWN_ID;
-  const outbox = process.env.PI_TEAMMATE_OUTBOX_FILE;
-  return worker && taskId && spawnId && outbox ? { worker, taskId, spawnId, outbox } : undefined;
+function dependenciesMet(task: BoardTask, tasks: Map<string, BoardTask>): boolean {
+  return task.dependsOn.every((dep) => tasks.get(dep)?.status === "completed");
 }
 
-export function isWorkerEvent(value: unknown): value is WorkerEvent {
-  if (!value || typeof value !== "object") return false;
-  const event = value as Partial<WorkerEvent>;
-  return typeof event.id === "string"
-    && event.type === "message"
-    && typeof event.worker === "string"
-    && typeof event.spawnId === "string"
-    && typeof event.subject === "string"
-    && typeof event.body === "string"
-    && (event.status === undefined || ["in_progress", "completed", "failed"].includes(event.status))
-    && (event.data === undefined || typeof event.data === "object")
-    ;
+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 deps = task.dependsOn.length > 0
+      ? ` | depends on ${task.dependsOn.join(", ")} (${dependenciesMet(task, byId) ? "met" : "unmet"})`
+      : "";
+    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");
+}
+
+/** One registration shared by leader and worker; binding chooses the data source. */
+export function registerTaskListTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    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.",
+    parameters: TaskListParams,
+    async execute() {
+      const binding = workerBinding();
+      const tasks = binding ? loadBoardTasks(binding) : listTasks();
+      // Both sides get a roster tail: peer discovery is zero-cost for workers.
+      const roster = binding
+        ? readRoster(binding.rosterFile)
+            .filter((entry) => entry.status !== "stopped")
+            .map((entry) => `@${entry.name} (${entry.agent}, ${entry.status})`)
+            .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: {} };
+    },
+  });
 }
 
 export function registerWorkerCapabilities(pi: ExtensionAPI): void {
   pi.registerTool({
-    name: "teammate_message",
-    promptSnippet: "Report progress or a final deliverable to the team leader",
-    label: "Teammate Report",
-    description: "Worker-only report channel. Send progress, blockers, or the final deliverable to the team leader. Set status=\"completed\" or \"failed\" for the terminal report.",
-    parameters: TeammateMessageParams,
+    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,
     async execute(_toolCallId, params) {
-      const binding = workerOutboxBinding();
+      const binding = workerBinding();
       if (!binding) throw new Error("This capability is available only inside a spawned teammate.");
-      appendWorkerEvent(binding.outbox, {
+      if (params.to === LEADER_RECIPIENT) {
+        appendWorkerEvent(binding.outbox, {
+          id: randomUUID(),
+          type: "message",
+          worker: binding.worker,
+          spawnId: binding.spawnId,
+          body: params.message,
+          status: params.status,
+        });
+        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: {} };
+      }
+      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.");
+      if (!livingRecipients(binding).has(params.to)) {
+        throw new Error(`No living teammate named "${params.to}". Check the roster or ask the leader.`);
+      }
+      const recipientInbox = path.join(path.dirname(binding.inbox), `inbox-${encodeURIComponent(params.to)}.jsonl`);
+      appendInboxMessage(recipientInbox, {
         id: randomUUID(),
-        type: "message",
+        from: binding.worker,
+        subject: messageTitle(params.message),
+        body: params.message,
+      });
+      return { content: [{ type: "text", text: `Delivered to @${params.to}'s inbox.` }], details: {} };
+    },
+  });
+
+  registerTaskListTool(pi);
+
+  pi.registerTool({
+    name: "task_claim",
+    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.",
+    parameters: TaskClaimParams,
+    async execute(_toolCallId, params) {
+      const binding = workerBinding();
+      if (!binding) throw new Error("This capability is available only inside a spawned teammate.");
+      const tasks = loadBoardTasks(binding);
+      const byId = new Map(tasks.map((task) => [task.id, task]));
+      const candidates = params.taskId
+        ? tasks.filter((task) => task.id === params.taskId)
+        : tasks.filter((task) => task.status === "pending" && dependenciesMet(task, byId));
+      if (candidates.length === 0) {
+        throw new Error(params.taskId ? `Task "${params.taskId}" was not found on the board.` : "No claimable task right now.");
+      }
+      for (const task of candidates) {
+        if (task.status !== "pending" || !dependenciesMet(task, byId)) continue;
+        const won = createTaskIntent(binding.claimsDir, task.id, {
+          taskId: task.id,
+          worker: binding.worker,
+          spawnId: binding.spawnId,
+          timestamp: Date.now(),
+        });
+        if (won) {
+          return { content: [{ type: "text", text: `You won [${task.id}] "${task.subject}". Submit with task_submit.` }], details: {} };
+        }
+        if (params.taskId) throw new Error(`Task "${task.id}" was claimed by someone else first.`);
+      }
+      throw new Error("All candidate tasks were claimed in the race. Check the board again.");
+    },
+  });
+
+  pi.registerTool({
+    name: "task_submit",
+    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.",
+    parameters: TaskSubmitParams,
+    async execute(_toolCallId, params) {
+      const binding = workerBinding();
+      if (!binding) throw new Error("This capability is available only inside a spawned teammate.");
+      const won = createTaskIntent(binding.submissionsDir, params.taskId, {
+        taskId: params.taskId,
         worker: binding.worker,
         spawnId: binding.spawnId,
-        subject: params.subject,
-        body: params.body,
         status: params.status,
-        data: params.data,
+        result: params.result,
+        timestamp: Date.now(),
       });
-      const statusNote = params.status ? ` with status "${params.status}"` : "";
-      return { content: [{ type: "text", text: `Queued report to team-leader${statusNote}.` }], details: {} };
+      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: {} };
     },
   });
 }

package/src/worktree.ts

@@ -27,6 +27,8 @@ export interface WorktreeDiff {
   diffStat: string;
 }
 
+export type WorktreeDiffResult = { ok: true; diff: WorktreeDiff } | { ok: false; error: string };
+
 function runGit(cwd: string, args: string[]): { status: number | null; stdout: string; stderr: string } {
   const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf-8" });
   return {
@@ -81,14 +83,24 @@ export function createWorktree(
  * Capture the worker's changes in the worktree as a patch against the base
  * commit. The worktree is left untouched; call cleanupWorktree afterwards.
  */
-export function captureWorktreeDiff(setup: WorktreeSetup): WorktreeDiff {
-  execFileSync("git", ["-C", setup.path, "add", "-A"], { stdio: "ignore" });
-  const stat = runGit(setup.path, ["diff", "--cached", "--stat", setup.baseCommit]);
-  const patch = runGit(setup.path, ["diff", "--cached", setup.baseCommit]);
-  return {
-    patch: patch.stdout ?? "",
-    diffStat: stat.stdout?.trim() ?? "",
-  };
+export function captureWorktreeDiff(setup: WorktreeSetup): WorktreeDiffResult {
+  try {
+    execFileSync("git", ["-C", setup.path, "add", "-A"], { stdio: "ignore" });
+    const stat = runGit(setup.path, ["diff", "--cached", "--stat", setup.baseCommit]);
+    const patch = runGit(setup.path, ["diff", "--cached", setup.baseCommit]);
+    if (stat.status !== 0 || patch.status !== 0) {
+      return { ok: false, error: patch.stderr.trim() || stat.stderr.trim() || "git diff failed" };
+    }
+    return {
+      ok: true,
+      diff: {
+        patch: patch.stdout ?? "",
+        diffStat: stat.stdout?.trim() ?? "",
+      },
+    };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
 }
 
 /**

package/.memory/run-centric-design.md

@@ -1,22 +0,0 @@
----
-name: teammate-autonomous-and-tui
-description: Agent Teams (packages/agent-teams) — run-centric: declarative agent files, single-call DAG dispatch, bounded child-process nodes, one-way leader inbox reports, session-wide worker cap, per-spawn identity validation
-type: project
----
-
-`packages/agent-teams` (0.3.0) is a run-centric multi-agent system: the Pi session is the leader; agents are declarative Markdown files; each run is a dependency-aware task graph dispatched in one call, where each node is a bounded child Pi process and a session-wide cap limits total workers to 8.
-
-**Why:**
-The teammate-registry model (runtime `teammate_register`/`create_task`/`start_task` ceremony, session-scoped identities, read receipts) was replaced after a design review. The ceremony critique: a one-off delegation cost 4 tool calls (list/register/create/start), identities were session-ephemeral so registration cost was paid per session, and both competitor packages (pi-maestro-teammate, @gcoder1991/pi-mesh) proved single-call DAG dispatch + declarative markdown agents. The later simplification removed the remaining half-channels: workers report only to the leader, upstream DAG results replace peer delivery, and live run status is not injected into every system prompt.
-
-**How to apply:**
-1. **Agents are declarative files** (`src/agents.ts`): frontmatter `name`/`description`/`tools`/`model` (inline `#` comments stripped), body = role prompt. Discovery precedence per name: project `.pi/agents/` > user `~/.pi/agent/agents/` > bundled `agents/`. Bundled: worker/reviewer/specialist/observer.
-2. **Single-call DAG dispatch** (`teammate_run`): `tasks` with `id`/`agent`/`prompt`/`paths`/`access` (default read)/`dependsOn`/`model`/`timeoutMs`, plus `concurrency` (default 4), `worktree`, `background`, `timeoutMs`, `summarize`, and `summaryAgent`. Validates dup ids, unknown dependsOn, cycles, bad paths before any spawn. Root nodes start immediately; `scheduleRun` auto-starts dependents on completion; write nodes with overlapping paths are deferred across all runs in the session unless worktree-isolated (`findSharedWorkspaceWriteConflict`).
-3. **Leader tools (3)**: `teammate_run`, `teammate_cancel` (run or `nodeId` node-level cancel; marks cancelled BEFORE terminating workers; SIGTERM→SIGKILL; console `x` reuses `cancelNodeAndTerminate`), and `teammate_retry` (retries failed/cancelled nodes without re-running completed ones). No leader message tool exists.
-4. **Worker protocol (1 capability tool)**: worker-only `teammate_message` has only `subject`/`body`/optional `status` and always reports to the leader. Per-spawn identity: `PI_TEAMMATE_WORKER_NAME` = `runId:nodeId`, `PI_TEAMMATE_SPAWN_ID` = fresh UUID; `applyWorkerEvents` rejects stale-spawn events. Reports enter one leader inbox; there are no peer mailboxes, worker inboxes, or leader broadcasts. Upstream DAG results are injected into downstream prompts (`=== UPSTREAM HANDOFF ===`).
-
-5. **Outcomes authoritative & non-polling leader**: workers message `team-leader` (`teammate_message`) with their deliverables upon completion, delivered automatically as a follow-up turn. The team leader does not sleep while tasks execute. One canonical terminal result per node built by the harness after child close; reported completion + SIGTERM close stays completed; failed node cancels its transitive pending dependents (`cancelBlockedDependents`) and fails the run. Worktree per node (`createWorktree(run.cwd, "${runId}-${nodeId}")`), diff captured for integration review. State snapshots are dirty-gated and worker task temp files are removed after close. Background runs deliver one run-completion follow-up; foreground gather (`background: false`) blocks the tool call (detaches after 5 min so turn is never hung).
-6. **UI**: passive widget (display-only) + `/teammate` full-screen console (owns input via `ctx.ui.custom`, no global interception) — rows are nodes, detail = node lifecycle + leader reports, live activity streams tool calls and thinking deltas, SGR mouse-wheel scrolling. Follows `@packages/btw` style language.
-7. **Testing**: BDD in `features/agent-teams.feature`, package tests in `tests/test_teammate_package.py` including node-eval runtime tests of state.ts/spawner.ts; typecheck via `npx tsc --noEmit --strict ... src/*.ts`.
-
-**Related:** [[pi-cli-print-json-usage]] [[no-global-input-interception]] [[pi-kitty-csi-u-keys]] [[pi-custom-component-rendering]] [[pi-package-conventions]]

package/agents/observer.md

@@ -1,10 +0,0 @@
----
-name: observer
-description: Read-only monitor of activity, logs, or processes; use when the task is to observe, watch, or report state rather than change it
-tools: read
----
-You are an observer agent. Observe and report on the assigned scope without
-changing anything. Take the required snapshots or readings, summarize what you
-observed, and report notable events or anomalies with timestamps and evidence
-via teammate_message to team-leader with status="completed". You have no edit,
-write, or command tools.

package/agents/reviewer.md

@@ -1,11 +0,0 @@
----
-name: reviewer
-description: Read-only code or content reviewer; use after implementation or plan changes to check for correctness, regressions, and security
-tools: read,bash
----
-You are a reviewer agent. Read the relevant code and tests first, then review
-the assigned scope for correctness, regressions, and security problems. Do not
-edit files. Report only confirmed findings with severity, evidence, exact
-paths, and a minimal fix recommendation via teammate_message to team-leader with
-status="completed". When no issue is confirmed, say so and list the checks
-you performed.

package/agents/specialist.md

@@ -1,10 +0,0 @@
----
-name: specialist
-description: Read-only domain expert for a specific technical area (security, performance, data, platform); use when a task needs deep domain judgment rather than broad implementation
-tools: read,bash
----
-You are a specialist agent. Apply deep domain judgment to the assigned scope:
-investigate, analyze, and produce findings or recommendations with evidence via
-teammate_message to team-leader with status="completed". Do not edit files.
-State your assumptions, the evidence you used, and the bounds of your expertise
-for this task.

package/agents/worker.md

@@ -1,11 +0,0 @@
----
-name: worker
-description: General executor that implements changes and verifies them; use when a task needs code or file modifications, or when no more specific agent fits
-tools: read,bash,edit,write
----
-You are a worker agent. Implement the assigned task end to end within the
-declared paths and access scope, then verify your own work by running the
-relevant tests or commands. Follow the task's ordered procedure. Report what
-you changed, what you verified, and any risks or follow-up work via
-teammate_message to team-leader with status="completed". Do not touch
-files outside the assigned scope.