@fradser/pi-agent-teams 0.5.3 → 0.6.0

package/src/statefile.ts

@@ -1,32 +1,44 @@
 /**
- * Shared session files for the leader-owned debug snapshot and worker outboxes.
+ * Shared session files for the leader-owned snapshot, teammate outboxes and
+ * inboxes, and the persistent task board.
  *
- * Layout: `~/.pi/agent/teammate/<sessionKey>/state.json`, sessionKey derived
- * from the session file (or cwd for ephemeral sessions) so different sessions
- * never share a board file.
+ * Runtime layout (removed at session shutdown):
+ *   ~/.pi/agent/teammate/<sessionKey>/state.json      leader-owned snapshot
+ *   ~/.pi/agent/teammate/<sessionKey>/events/*.jsonl  per-spawn report outboxes
+ *   ~/.pi/agent/teammate/<sessionKey>/mail/*.jsonl    peer inbox files
+ *   ~/.pi/agent/teammate/<sessionKey>/roster.json     living teammates, worker-readable
  *
- * Concurrency: the parent is the sole writer of state.json (atomic tmp+rename).
- * Workers append requests only to their own JSONL outbox; the state snapshot is
- * not a worker inbox or a communication channel.
+ * Board layout (persists across restarts, never auto-cleaned):
+ *   ~/.pi/agent/tasks/<sessionKey>/board.json         leader-owned board file
+ *   ~/.pi/agent/tasks/<sessionKey>/claims/*.json      exclusive-create claim intents
+ *   ~/.pi/agent/tasks/<sessionKey>/submissions/*.json exclusive-create submit intents
+ *
+ * Concurrency: the parent is the sole writer of state.json and board.json
+ * (atomic tmp+rename). Teammates append only to their own outbox, append to
+ * recipient inboxes, and express board intent through exclusive-create files.
  */
 
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
-import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
-import type { TeammateState, WorkerEvent } from "./types";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { TaskIntent, TeamState, WorkerEvent } from "./types.ts";
 
 const MAX_WORKER_EVENT_BYTES = 64 * 1024;
+const MAX_INBOX_MESSAGE_BYTES = 64 * 1024;
 const MAX_OUTBOX_READ_BYTES = 256 * 1024;
+const MAX_INTENT_BYTES = 16 * 1024;
 
-export function sessionStateDir(sessionFile: string | undefined, cwd: string): string {
-  const key = crypto
+export function sessionKey(sessionFile: string | undefined, cwd: string): string {
+  return crypto
     .createHash("sha256")
     .update(sessionFile ?? cwd)
     .digest("hex")
     .slice(0, 16);
-  return path.join(os.homedir(), CONFIG_DIR_NAME, "agent", "teammate", key);
+}
+
+export function sessionStateDir(sessionFile: string | undefined, cwd: string): string {
+  return path.join(getAgentDir(), "teammate", sessionKey(sessionFile, cwd));
 }
 
 export function stateFilePath(sessionFile: string | undefined, cwd: string): string {
@@ -34,85 +46,236 @@ export function stateFilePath(sessionFile: string | undefined, cwd: string): str
 }
 
 /** Write the leader-owned debug snapshot atomically (tmp + rename). */
-export function writeStateFile(file: string, state: TeammateState): void {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = `${file}.${process.pid}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
-  fs.renameSync(tmp, file);
+export function writeStateFile(file: string, state: TeamState): void {
+  writeJsonAtomic(file, state);
 }
 
-/** Per-run append-only event log. Its filename cannot escape the session dir. */
-export function workerOutboxPath(stateFile: string, workerName: string, runId: string): string {
-  return path.join(path.dirname(stateFile), "events", `${encodeURIComponent(workerName)}.${encodeURIComponent(runId)}.jsonl`);
+// ── Peer mail ─────────────────────────────────────────────────────
+
+function safeName(name: string): string {
+  return encodeURIComponent(name);
 }
 
-/** Delete a drained per-run outbox after its final snapshot is safely published. */
-export function removeWorkerOutbox(stateFile: string, workerName: string, runId: string): void {
-  fs.rmSync(workerOutboxPath(stateFile, workerName, runId), { force: true });
+export function mailDir(stateFile: string): string {
+  return path.join(path.dirname(stateFile), "mail");
 }
 
-/** Append one worker event. Workers never replace the leader-owned state snapshot. */
-export function appendWorkerEvent(file: string, event: WorkerEvent): void {
-  const record = `${JSON.stringify(event)}\n`;
-  if (Buffer.byteLength(record, "utf-8") > MAX_WORKER_EVENT_BYTES) {
-    throw new Error(`Worker event exceeds ${MAX_WORKER_EVENT_BYTES} bytes.`);
+export function inboxPath(stateFile: string, teammateName: string): string {
+  return path.join(mailDir(stateFile), `inbox-${safeName(teammateName)}.jsonl`);
+}
+
+export function rosterPath(stateFile: string): string {
+  return path.join(path.dirname(stateFile), "roster.json");
+}
+
+/** Append one message to a teammate inbox. Sent means this write succeeded. */
+export function appendInboxMessage(file: string, message: { id: string; from: string; subject: string; body: string }): void {
+  const record = `${JSON.stringify(message)}\n`;
+  if (Buffer.byteLength(record, "utf-8") > MAX_INBOX_MESSAGE_BYTES) {
+    throw new Error(`Message exceeds ${MAX_INBOX_MESSAGE_BYTES} bytes.`);
   }
   fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
   fs.appendFileSync(file, record, { encoding: "utf-8", mode: 0o600 });
 }
 
-/** Read a bounded batch of complete JSONL records after byteOffset. */
-export function readWorkerEvents(file: string, byteOffset: number): { events: unknown[]; nextOffset: number } {
+/** Publish the worker-readable roster of living teammates. */
+export function writeRoster(file: string, teammates: Array<{ name: string; agent: string; status: string }>): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  writeJsonAtomic(file, { teammates });
+}
+
+/** Read the roster from inside a teammate process; unknown roster = empty. */
+export function readRoster(file: string): Array<{ name: string; agent: string; status: string }> {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as { teammates?: Array<{ name: string; agent: string; status: string }> };
+    return Array.isArray(parsed.teammates) ? parsed.teammates : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Read complete JSONL records after byteOffset (shared by outboxes and inboxes). */
+export function readJsonlBatch(file: string, byteOffset: number): {
+  records: unknown[];
+  nextOffset: number;
+  diagnostics: string[];
+} {
   let fd: number | undefined;
   try {
     fd = fs.openSync(file, "r");
     const size = fs.fstatSync(fd).size;
-    // A truncated/recreated outbox starts at zero; event IDs make replay safe.
+    // A truncated/recreated file starts at zero; message ids make replay safe.
     const offset = byteOffset > size ? 0 : Math.max(0, byteOffset);
     const toRead = Math.min(MAX_OUTBOX_READ_BYTES, size - offset);
-    if (toRead === 0) return { events: [], nextOffset: offset };
+    if (toRead === 0) return { records: [], nextOffset: offset, diagnostics: [] };
     const raw = Buffer.allocUnsafe(toRead);
     const bytesRead = fs.readSync(fd, raw, 0, toRead, offset);
     const unread = raw.subarray(0, bytesRead);
     const lastNewline = unread.lastIndexOf(0x0a);
     if (lastNewline < 0) {
       // A line larger than the batch cap is malformed for this protocol; skip
-      // this chunk so one worker cannot block event draining indefinitely.
-      return { events: [], nextOffset: bytesRead === MAX_OUTBOX_READ_BYTES ? offset + bytesRead : offset };
+      // this chunk so one sender cannot block draining indefinitely.
+      return {
+        records: [],
+        nextOffset: bytesRead === MAX_OUTBOX_READ_BYTES ? offset + bytesRead : offset,
+        diagnostics: ["malformed or unterminated record was consumed"],
+      };
     }
     const complete = unread.subarray(0, lastNewline).toString("utf-8");
-    const events: unknown[] = [];
+    const records: unknown[] = [];
+    const diagnostics: string[] = [];
     for (const line of complete.split("\n")) {
       if (!line.trim()) continue;
       try {
-        events.push(JSON.parse(line));
+        records.push(JSON.parse(line));
       } catch {
-        // Malformed records are consumed, not retried forever.
+        diagnostics.push("malformed JSON record was consumed");
       }
     }
-    return { events, nextOffset: offset + lastNewline + 1 };
+    return { records, nextOffset: offset + lastNewline + 1, diagnostics };
   } catch {
-    return { events: [], nextOffset: 0 };
+    return { records: [], nextOffset: 0, diagnostics: [] };
   } finally {
     if (fd !== undefined) fs.closeSync(fd);
   }
 }
 
-// ── Expired state-dir cleanup ───────────────────────────────────────
+// ── Report outboxes ───────────────────────────────────────────────
+
+/** Per-teammate append-only report log. Its filename cannot escape the dir. */
+export function workerOutboxPath(stateFile: string, workerName: string, spawnId: string): string {
+  return path.join(path.dirname(stateFile), "events", `${safeName(workerName)}.${safeName(spawnId)}.jsonl`);
+}
+
+/** Delete a drained per-spawn outbox after its final snapshot is published. */
+export function removeWorkerOutbox(stateFile: string, workerName: string, spawnId: string): void {
+  fs.rmSync(workerOutboxPath(stateFile, workerName, spawnId), { force: true });
+}
+
+/** Append one teammate report event. Workers never replace leader state. */
+export function appendWorkerEvent(file: string, event: WorkerEvent): void {
+  const record = `${JSON.stringify(event)}\n`;
+  if (Buffer.byteLength(record, "utf-8") > MAX_WORKER_EVENT_BYTES) {
+    throw new Error(`Worker event exceeds ${MAX_WORKER_EVENT_BYTES} bytes.`);
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.appendFileSync(file, record, { encoding: "utf-8", mode: 0o600 });
+}
+
+// ── Persistent task board ─────────────────────────────────────────
+
+/** Root of all per-session board dirs (`~/.pi/agent/tasks/`). */
+export function tasksRoot(): string {
+  return path.join(getAgentDir(), "tasks");
+}
+
+export function boardDir(sessionFile: string | undefined, cwd: string): string {
+  return path.join(tasksRoot(), sessionKey(sessionFile, cwd));
+}
+
+export function boardFilePath(sessionFile: string | undefined, cwd: string): string {
+  return path.join(boardDir(sessionFile, cwd), "board.json");
+}
+
+export function claimsDir(boardDirectory: string): string {
+  return path.join(boardDirectory, "claims");
+}
+
+export function submissionsDir(boardDirectory: string): string {
+  return path.join(boardDirectory, "submissions");
+}
+
+export function readBoardFile(file: string): { tasks: Record<string, import("./types").BoardTask> } | undefined {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as { tasks?: Record<string, import("./types").BoardTask> };
+    return parsed.tasks ? { tasks: parsed.tasks } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeBoardFile(file: string, tasks: Record<string, import("./types").BoardTask>): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  writeJsonAtomic(file, { tasks });
+}
+
+/**
+ * Express a board intent through an exclusive-create marker file. Returns
+ * true exactly when this caller won the race for the taskId.
+ */
+export function createTaskIntent(dir: string, taskId: string, intent: TaskIntent): boolean {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, `${safeName(taskId)}.json`);
+  const payload = JSON.stringify(intent);
+  if (Buffer.byteLength(payload, "utf-8") > MAX_INTENT_BYTES) {
+    throw new Error(`Task intent exceeds ${MAX_INTENT_BYTES} bytes.`);
+  }
+  try {
+    fs.writeFileSync(file, payload, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "EEXIST") return false;
+    throw error;
+  }
+}
+
+/**
+ * Drain one pending intent file. Malformed records are consumed and reported
+ * so one broken file can never block the queue.
+ */
+export function takeTaskIntent(dir: string): { intent?: TaskIntent; diagnostic?: string } {
+  let entries: string[] = [];
+  try {
+    entries = fs.readdirSync(dir).filter((name) => name.endsWith(".json")).sort();
+  } catch {
+    return {};
+  }
+  for (const name of entries) {
+    const file = path.join(dir, name);
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as Partial<TaskIntent>;
+      fs.rmSync(file, { force: true });
+      if (
+        typeof parsed.taskId !== "string"
+        || typeof parsed.worker !== "string"
+        || typeof parsed.spawnId !== "string"
+      ) {
+        return { diagnostic: `malformed task intent "${name}" was consumed (missing taskId/worker/spawnId)` };
+      }
+      return { intent: parsed as TaskIntent };
+    } catch {
+      fs.rmSync(file, { force: true });
+      return { diagnostic: `unreadable task intent "${name}" was consumed` };
+    }
+  }
+  return {};
+}
+
+// ── Atomic JSON IO ────────────────────────────────────────────────
+
+function writeJsonAtomic(file: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+// ── Expired runtime-dir cleanup ───────────────────────────────────
 
-/** Root of all per-session teammate state dirs (`~/.pi/agent/teammate/`). */
+/** Root of all per-session teammate runtime dirs (`~/.pi/agent/teammate/`). */
 export function stateDirsRoot(): string {
-  return path.join(os.homedir(), CONFIG_DIR_NAME, "agent", "teammate");
+  return path.join(getAgentDir(), "teammate");
 }
 
-/** Remove the current session's state dir (called on session_shutdown). */
+/** Remove the current session's runtime dir (called on session_shutdown). */
 export function removeSessionStateDir(sessionFile: string | undefined, cwd: string): void {
   fs.rmSync(sessionStateDir(sessionFile, cwd), { recursive: true, force: true });
 }
 
 /**
- * Sweep state dirs whose last write is older than maxAgeMs. Returns how many
- * were removed. Called on session_start so abandoned sessions never pile up.
+ * Sweep runtime dirs whose last write is older than maxAgeMs. Board dirs are
+ * never swept. Called on session_start so abandoned sessions never pile up.
  */
 export function cleanupExpiredStateDirs(maxAgeMs: number): number {
   const root = stateDirsRoot();