@fradser/pi-agent-teams 0.8.3 → 0.9.1

package/src/state.ts

@@ -4,8 +4,10 @@
  * is the sole writer of this snapshot and of board.json.
  */
 
+import { randomUUID } from "node:crypto";
 import {
   messageTitle,
+  TEAM_RUNTIME_VERSION,
   type BoardTask,
   type WorkerAssignment,
   type MailboxMessage,
@@ -18,6 +20,9 @@ import {
 import { nonEmpty } from "@fradser/pi-kit";
 
 export const MAX_LEADER_MAILBOX_MESSAGES = 4096;
+/** Total mailbox body bytes retained for forensics. A count cap alone lets a few
+ *  long reports blow the snapshot up: this keeps the debug artifact bounded. */
+export const MAX_LEADER_MAILBOX_BYTES = 8 * 1024 * 1024;
 /** FIFO cap of remembered peer message ids per inbox (dedup guard). */
 export const MAX_PEER_DELIVERED_IDS = 512;
 /** Bounded forensic routing history; mailbox files retain the full peer transcript. */
@@ -26,6 +31,7 @@ export const MAX_TASK_DEPENDENCIES = 32;
 
 function emptyState(): TeamState {
   return {
+    runtimeVersion: TEAM_RUNTIME_VERSION,
     teammates: {},
     tasks: emptyTaskMap(),
     leaderMailbox: [],
@@ -39,25 +45,6 @@ function emptyState(): TeamState {
 }
 
 let state = emptyState();
-let stateDirty = false;
-
-export function markStateDirty(): void {
-  stateDirty = true;
-}
-
-export function isStateDirty(): boolean {
-  return stateDirty;
-}
-
-export function clearStateDirty(): void {
-  stateDirty = false;
-}
-
-export function consumeStateDirty(): boolean {
-  const dirty = stateDirty;
-  clearStateDirty();
-  return dirty;
-}
 
 function nextMessageId(): string {
   return `msg_${++state.messageCounter}`;
@@ -71,7 +58,47 @@ function emptyTaskMap(): Record<string, BoardTask> {
 
 export function resetState(): void {
   state = emptyState();
-  markStateDirty();
+  rosterRevisionCounter++;
+  boardRevisionCounter++;
+  stateRevisionCounter++;
+}
+
+// ── Persistence revisions ────────────────────────────────────────
+// state.ts owns every in-memory mutation, so it is the one place that can say
+// exactly which artifact changed. Stream progress is counted separately: a
+// running teammate must not force the roster, the board, or the debug snapshot
+// to be rewritten on every token. Every persisted mutation in this module bumps
+// one of these counters, so a mutation that forgets to bump would not be written
+// until something else changed — add the bump with any new mutator.
+let stateRevisionCounter = 0;
+let rosterRevisionCounter = 0;
+let boardRevisionCounter = 0;
+let progressRevisionCounter = 0;
+
+/** Revision of the whole snapshot: roster, board, mailbox, and offsets. */
+export function stateRevision(): number {
+  return stateRevisionCounter;
+}
+
+/** Revision of the worker-readable roster. */
+export function rosterRevision(): number {
+  return rosterRevisionCounter;
+}
+
+/** Revision of the persisted board. */
+export function boardRevision(): number {
+  return boardRevisionCounter;
+}
+
+/** Revision of streamed progress only; never persisted on its own. */
+export function progressRevision(): number {
+  return progressRevisionCounter;
+}
+
+/** Record a board change made outside this module's task mutators. */
+export function markBoardChanged(): void {
+  boardRevisionCounter++;
+  stateRevisionCounter++;
 }
 
 // ── Team default model ──────────────────────────────────────
@@ -84,7 +111,7 @@ export function getTeamDefaultModel(): string | undefined {
 /** Set (or clear with undefined) the unified teammate model for later spawns. */
 export function setTeamDefaultModel(ref: string | undefined): void {
   state.defaultModel = nonEmpty(ref);
-  markStateDirty();
+  stateRevisionCounter++;
 }
 
 // ── Roster queries ────────────────────────────────────────────────
@@ -111,14 +138,6 @@ export function idleTeammates(): Teammate[] {
   return livingTeammates().filter((t) => t.status === "idle");
 }
 
-export function workingTeammates(): Teammate[] {
-  return livingTeammates().filter((t) => t.status === "working" || t.status === "starting");
-}
-
-export function findTeammateBySpawn(spawnId: string): Teammate | undefined {
-  return listTeammates().find((t) => t.spawnId === spawnId && t.status !== "stopped");
-}
-
 export function registerTeammate(teammate: Teammate): { ok: true } | { ok: false; error: string } {
   if (!isValidTeammateName(teammate.name)) {
     return { ok: false, error: `Invalid teammate name "${teammate.name}". Use letters, digits, dots, dashes, underscores.` };
@@ -127,16 +146,41 @@ export function registerTeammate(teammate: Teammate): { ok: true } | { ok: false
     return { ok: false, error: `A living teammate named "${teammate.name}" already exists.` };
   }
   state.teammates[teammate.name] = teammate;
-  markStateDirty();
+  rosterRevisionCounter++;
+  stateRevisionCounter++;
   return { ok: true };
 }
 
+/** Fields whose change is stream progress rather than persisted state. A
+ *  progress tick must not republish the roster or the board. */
+const VOLATILE_TEAMMATE_FIELDS = new Set<string>([
+  "liveText",
+  "liveThinking",
+  "activeTool",
+  "turns",
+  "sequenceEnded",
+  "modelOutputSeen",
+  "usage",
+  "lastOutputAt",
+  "updatedAt",
+  "lastNoticeAt",
+  "noticedTaskIds",
+]);
+
 export function updateTeammate(name: string, patch: Partial<Teammate>): Teammate | undefined {
   const teammate = state.teammates[name];
   if (!teammate) return undefined;
+  const changed = (Object.keys(patch) as Array<keyof Teammate>)
+    .filter((field) => !Object.is(teammate[field], patch[field]));
   Object.assign(teammate, patch, { updatedAt: Date.now() });
   if (patch.status === "stopped") teammate.stoppedAt = Date.now();
-  markStateDirty();
+  // Republishing a roster that only streamed progress is pure write churn.
+  if (changed.some((field) => !VOLATILE_TEAMMATE_FIELDS.has(field as string))) {
+    rosterRevisionCounter++;
+    stateRevisionCounter++;
+  } else if (changed.length > 0) {
+    progressRevisionCounter++;
+  }
   return teammate;
 }
 
@@ -150,7 +194,9 @@ export function assignTeammate(
   if (!teammate) return undefined;
   const lastAssignment = assignment ?? teammate.assignment ?? teammate.lastAssignment;
   const lastTaskId = currentTaskId ?? teammate.currentTaskId ?? teammate.lastTaskId;
-  return updateTeammate(name, { assignment, currentTaskId, lastAssignment, lastTaskId });
+  return updateTeammate(name, { assignment, currentTaskId, lastAssignment, lastTaskId,
+    ...(assignment && assignment.id !== teammate.assignment?.id ? { reportSequenceEnded: false } : {}),
+  });
 }
 
 export function updateTeammateProgress(
@@ -164,6 +210,12 @@ export function updateTeammateProgress(
 ): boolean {
   const teammate = state.teammates[name];
   if (!teammate || teammate.spawnId !== spawnId) return false;
+  const changed = teammate.liveText !== progress.liveText
+    || teammate.activeTool !== progress.activeTool
+    || teammate.liveThinking !== progress.liveThinking
+    || teammate.turns !== progress.turns
+    || (progress.sequenceEnded !== undefined && teammate.sequenceEnded !== progress.sequenceEnded)
+    || (progress.modelOutputSeen === true && teammate.modelOutputSeen !== true);
   teammate.liveText = progress.liveText;
   teammate.activeTool = progress.activeTool;
   teammate.liveThinking = progress.liveThinking;
@@ -173,9 +225,12 @@ export function updateTeammateProgress(
   if (progress.usage) teammate.usage = progress.usage;
   if (teammate.status === "starting") {
     teammate.status = progress.sequenceEnded ? "idle" : "working";
+    // A status transition is roster state, not stream noise.
+    rosterRevisionCounter++;
+    stateRevisionCounter++;
   }
   teammate.updatedAt = Date.now();
-  markStateDirty();
+  if (changed) progressRevisionCounter++;
   return true;
 }
 
@@ -186,7 +241,19 @@ export function clearWorkerRunEvents(workerName: string, spawnId: string): void
   for (const id of Object.keys(state.workerEventIds)) {
     if (id.startsWith(`${spawnId}:`)) delete state.workerEventIds[id];
   }
-  markStateDirty();
+}
+
+/** Drop the oldest mailbox entries until both the count and byte caps hold. */
+function trimLeaderMailbox(): void {
+  if (state.leaderMailbox.length > MAX_LEADER_MAILBOX_MESSAGES) {
+    state.leaderMailbox.splice(0, state.leaderMailbox.length - MAX_LEADER_MAILBOX_MESSAGES);
+  }
+  let bytes = 0;
+  for (const message of state.leaderMailbox) bytes += message.body.length + message.subject.length + 64;
+  while (bytes > MAX_LEADER_MAILBOX_BYTES && state.leaderMailbox.length > 1) {
+    const dropped = state.leaderMailbox.shift()!;
+    bytes -= dropped.body.length + dropped.subject.length + 64;
+  }
 }
 
 // ── Leader inbox ──────────────────────────────────────────────────
@@ -194,10 +261,8 @@ export function clearWorkerRunEvents(workerName: string, spawnId: string): void
 export function deliverToLeader(msg: Omit<MailboxMessage, "id" | "timestamp">): MailboxMessage {
   const full: MailboxMessage = { ...msg, id: nextMessageId(), timestamp: Date.now() };
   state.leaderMailbox.push(full);
-  if (state.leaderMailbox.length > MAX_LEADER_MAILBOX_MESSAGES) {
-    state.leaderMailbox.splice(0, state.leaderMailbox.length - MAX_LEADER_MAILBOX_MESSAGES);
-  }
-  markStateDirty();
+  trimLeaderMailbox();
+  stateRevisionCounter++;
   return full;
 }
 
@@ -209,6 +274,8 @@ export function receiveWorkerMessage(event: WorkerReportEvent, options?: { archi
   state.leaderMailbox.push({
     id: event.id,
     from: event.worker,
+    assignmentId: event.assignmentId,
+    spawnId: event.spawnId,
     subject: messageTitle(event.body),
     body: event.body,
     status: event.status,
@@ -217,10 +284,8 @@ export function receiveWorkerMessage(event: WorkerReportEvent, options?: { archi
     // teammate spoke, not when the leader happened to drain the outbox.
     timestamp: event.timestamp ?? Date.now(),
   });
-  if (state.leaderMailbox.length > MAX_LEADER_MAILBOX_MESSAGES) {
-    state.leaderMailbox.splice(0, state.leaderMailbox.length - MAX_LEADER_MAILBOX_MESSAGES);
-  }
-  markStateDirty();
+  trimLeaderMailbox();
+  stateRevisionCounter++;
   return true;
 }
 
@@ -235,7 +300,7 @@ export function markPeerDelivered(inboxName: string, messageId: string): void {
   ids.push(messageId);
   while (ids.length > MAX_PEER_DELIVERED_IDS) ids.shift();
   state.peerDeliveredIds[inboxName] = ids;
-  markStateDirty();
+  stateRevisionCounter++;
 }
 
 export function getPeerInboxOffset(inboxName: string): number {
@@ -244,11 +309,11 @@ export function getPeerInboxOffset(inboxName: string): number {
 
 export function setPeerInboxOffset(inboxName: string, offset: number): void {
   state.peerInboxOffsets[inboxName] = offset;
-  markStateDirty();
+  stateRevisionCounter++;
 }
 
 /** Record only the harness-controlled routing transition, never recipient read. */
-export function setPeerDeliveryState(messageId: string, routing: "queued" | "routed"): void {
+export function setPeerDeliveryState(messageId: string, routing: "queued" | "routed" | "dropped"): void {
   state.peerDeliveryStates ??= {};
   if (!(messageId in state.peerDeliveryStates)
     && Object.keys(state.peerDeliveryStates).length >= MAX_PEER_DELIVERY_STATES) {
@@ -256,10 +321,10 @@ export function setPeerDeliveryState(messageId: string, routing: "queued" | "rou
     if (oldest) delete state.peerDeliveryStates[oldest];
   }
   state.peerDeliveryStates[messageId] = routing;
-  markStateDirty();
+  stateRevisionCounter++;
 }
 
-export function getPeerDeliveryState(messageId: string): "queued" | "routed" | undefined {
+export function getPeerDeliveryState(messageId: string): "queued" | "routed" | "dropped" | undefined {
   return state.peerDeliveryStates?.[messageId];
 }
 
@@ -352,11 +417,16 @@ export function activeAssignmentConflict(
   return livingTeammates().find((teammate) => {
     if (teammate.name === exceptWorker) return false;
     const assignment = teammate.assignment;
-    return assignment !== undefined && !assignment.closed && resourcesConflict(resources, assignment.resources);
+    const retainsWorkAuthority = teammate.currentTaskId !== undefined
+      && ["claimed", "superseded"].includes(state.tasks[teammate.currentTaskId]?.status ?? "");
+    return assignment !== undefined
+      && (!assignment.closed || retainsWorkAuthority)
+      && resourcesConflict(resources, assignment.resources);
   });
 }
 
 export function createTask(input: {
+  id?: string;
   subject: string;
   description?: string;
   dependsOn?: string[];
@@ -390,7 +460,8 @@ export function createTask(input: {
     return { ok: false, error: `Task cannot both depend on and supersede "${selfReplacement}".` };
   }
 
-  const id = taskIdFromSubject(subject, new Set(Object.keys(state.tasks)));
+  const id = input.id ?? taskIdFromSubject(subject, new Set(Object.keys(state.tasks)));
+  if (state.tasks[id]) return { ok: false, error: `Task id "${id}" already exists.` };
   const migrations = new Map<string, string[]>();
   for (const dependent of Object.values(state.tasks)) {
     if (dependent.status === "completed" || dependent.status === "superseded") continue;
@@ -420,6 +491,8 @@ export function createTask(input: {
     updatedAt: Date.now(),
   };
   state.tasks[id] = task;
+  boardRevisionCounter++;
+  stateRevisionCounter++;
   const superseded: BoardTask[] = [];
   for (const oldId of supersedes) {
     const old = state.tasks[oldId];
@@ -438,7 +511,6 @@ export function createTask(input: {
     dependent.dependsOn = migratedDependencies;
     dependent.updatedAt = Date.now();
   }
-  markStateDirty();
   return { ok: true, task, superseded };
 }
 
@@ -462,9 +534,80 @@ export function taskDependenciesMet(task: BoardTask): boolean {
   return task.status === "pending" && task.dependsOn.every((dep) => state.tasks[dep]?.status === "completed");
 }
 
-/** First claimable task, or undefined. */
-export function firstClaimableTask(): BoardTask | undefined {
-  return claimableTasks()[0];
+export function createDirectWork(input: {
+  id: string;
+  subject: string;
+  description?: string;
+  resources: string[];
+  verify?: string;
+  workerName: string;
+  assignment: WorkerAssignment;
+}): { ok: true; task: BoardTask } | { ok: false; error: string } {
+  const created = createTask({
+    id: input.id,
+    subject: input.subject,
+    description: input.description,
+    resources: input.resources,
+    verify: input.verify,
+  });
+  if (!created.ok) return created;
+  const task = created.task;
+  const worker = getTeammate(input.workerName);
+  if (!worker || worker.assignment || activeAssignmentConflict(task.resources, input.workerName)) {
+    // The Work is rolled back here, so its id would render as an unresolvable
+    // handle: name the work a person can recognize instead.
+    const reason = !worker
+      ? `@${input.workerName} is not a registered teammate`
+      : worker.assignment
+        ? `@${input.workerName} already owns ${worker.assignment.kind} assignment "${worker.assignment.id}"`
+        : `its resources conflict with active Work`;
+    delete state.tasks[task.id];
+    return { ok: false, error: `Cannot bind direct Work "${input.subject}" to @${input.workerName}: ${reason}.` };
+  }
+  task.status = "claimed";
+  task.claimedBy = input.workerName;
+  task.updatedAt = Date.now();
+  boardRevisionCounter++;
+  stateRevisionCounter++;
+  assignTeammate(input.workerName, input.assignment, task.id);
+  return { ok: true, task };
+}
+
+export function discardDirectWork(taskId: string, workerName: string): boolean {
+  const task = state.tasks[taskId];
+  if (!task || task.status !== "claimed" || task.claimedBy !== workerName) return false;
+  delete state.tasks[taskId];
+  boardRevisionCounter++;
+  stateRevisionCounter++;
+  return true;
+}
+
+export function reclaimDirectWork(
+  taskId: string,
+  workerName: string,
+  assignment: WorkerAssignment,
+  expectedState: "pending" | "completed" | "claimed",
+  allowActiveAssignment = false,
+): { ok: true } | { ok: false; error: string } {
+  const task = state.tasks[taskId];
+  const worker = getTeammate(workerName);
+  const retainsSupersededWork = worker?.currentTaskId !== undefined
+    && state.tasks[worker.currentTaskId]?.status === "superseded";
+  if (!task || task.status !== expectedState || !worker || retainsSupersededWork || (!allowActiveAssignment && worker.assignment && !worker.assignment.closed)) {
+    return { ok: false, error: `Unable to reclaim direct Work Item "${taskId}".` };
+  }
+  const conflict = activeAssignmentConflict(task.resources, workerName);
+  if (conflict) return { ok: false, error: `Resource conflict with @${conflict.name}'s active assignment.` };
+  task.status = "claimed";
+  task.claimedBy = workerName;
+  task.result = undefined;
+  task.errorMessage = undefined;
+  task.completedAt = undefined;
+  task.updatedAt = Date.now();
+  boardRevisionCounter++;
+  stateRevisionCounter++;
+  assignTeammate(workerName, assignment, task.id);
+  return { ok: true };
 }
 
 export function setTaskClaimed(taskId: string, workerName: string): BoardTask | undefined {
@@ -476,13 +619,55 @@ export function setTaskClaimed(taskId: string, workerName: string): BoardTask |
   task.status = "claimed";
   task.claimedBy = workerName;
   task.updatedAt = Date.now();
-  assignTeammate(workerName, { id: task.id, kind: "board", resources: task.resources }, task.id);
-  markStateDirty();
+  boardRevisionCounter++;
+  stateRevisionCounter++;
+  assignTeammate(workerName, { id: `board:${randomUUID()}`, kind: "board", resources: task.resources }, task.id);
   return task;
 }
 
 /** Release a claimed task back to pending. A superseded holder instead
  * acknowledges cancellation: the task stays superseded but frees resources. */
+export function claimedDependents(workId: string): BoardTask[] {
+  const reverse = new Map<string, string[]>();
+  for (const task of Object.values(state.tasks)) {
+    for (const dependency of task.dependsOn) {
+      const dependents = reverse.get(dependency) ?? [];
+      dependents.push(task.id);
+      reverse.set(dependency, dependents);
+    }
+  }
+  const visited = new Set<string>();
+  const pending = [...(reverse.get(workId) ?? [])];
+  const claimed: BoardTask[] = [];
+  while (pending.length > 0) {
+    const id = pending.shift()!;
+    if (visited.has(id)) continue;
+    visited.add(id);
+    const task = state.tasks[id];
+    if (!task) continue;
+    if (task.status === "claimed" || (task.status === "superseded" && task.claimedBy !== undefined)) claimed.push(task);
+    pending.push(...(reverse.get(id) ?? []));
+  }
+  return claimed.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function reopenCompletedWork(workId: string): { ok: true; task: BoardTask } | { ok: false; error: string } {
+  const task = state.tasks[workId];
+  if (!task || task.status !== "completed") return { ok: false, error: `Work Item "${workId}" is not completed.` };
+  const blockers = claimedDependents(workId);
+  if (blockers.length > 0) return { ok: false, error: `Work Item "${workId}" has active dependent Work: ${blockers.map((blocker) => blocker.id).join(", ")}.` };
+  task.status = "pending";
+  task.claimedBy = undefined;
+  task.result = undefined;
+  task.deferredMessages = undefined;
+  task.errorMessage = undefined;
+  task.completedAt = undefined;
+  task.updatedAt = Date.now();
+  boardRevisionCounter++;
+  stateRevisionCounter++;
+  return { ok: true, task };
+}
+
 export function releaseTask(taskId: string, errorMessage?: string): BoardTask | undefined {
   const task = state.tasks[taskId];
   if (!task || (task.status !== "claimed" && task.status !== "superseded")) return undefined;
@@ -491,8 +676,9 @@ export function releaseTask(taskId: string, errorMessage?: string): BoardTask |
   task.claimedBy = undefined;
   if (errorMessage !== undefined) task.errorMessage = errorMessage;
   task.updatedAt = Date.now();
+  boardRevisionCounter++;
+  stateRevisionCounter++;
   if (holder) assignTeammate(holder, undefined, undefined);
-  markStateDirty();
   return task;
 }
 
@@ -501,12 +687,14 @@ export function completeTask(taskId: string, result?: string): BoardTask | undef
   if (!task || task.status !== "claimed") return undefined;
   const holder = task.claimedBy;
   task.status = "completed";
+  task.claimedBy = undefined;
   task.result = result;
   task.errorMessage = undefined;
   task.completedAt = Date.now();
   task.updatedAt = Date.now();
+  boardRevisionCounter++;
+  stateRevisionCounter++;
   if (holder) assignTeammate(holder, undefined, undefined);
-  markStateDirty();
   return task;
 }
 
@@ -564,7 +752,7 @@ export function applySubmissionIntent(intent: TaskIntent): { ok: boolean; error?
     return { ok: false, error: `task "${intent.taskId}" was superseded by "${task.supersededBy ?? "a replacement"}"; submit failed to acknowledge cancellation` };
   }
   if (intent.status === "failed") {
-    releaseTask(intent.taskId, intent.result?.trim() || "Teammate reported failure.");
+    releaseTask(intent.taskId, intent.result?.trim() || "Agent reported failure.");
     return { ok: true };
   }
   completeTask(intent.taskId, intent.result?.trim() || undefined);
@@ -594,16 +782,9 @@ export function loadBoard(tasks: Record<string, BoardTask>): number {
     state.tasks[restored.id] = restored;
     reloaded++;
   }
-  if (reloaded > 0) markStateDirty();
-  return reloaded;
-}
-
-export function getSummary(): string | undefined {
-  const alive = livingTeammates();
-  if (alive.length === 0 && listTasks().length === 0) return undefined;
-  const counts = { pending: 0, claimed: 0, completed: 0, superseded: 0 };
-  for (const task of listTasks()) {
-    if (task.status in counts) counts[task.status as keyof typeof counts]++;
+  if (reloaded > 0) {
+    boardRevisionCounter++;
+    stateRevisionCounter++;
   }
-  return `${alive.length} teammate(s) alive | board: ${counts.pending} pending / ${counts.claimed} claimed / ${counts.completed} completed / ${counts.superseded} superseded`;
+  return reloaded;
 }