clawmatrix 0.4.2 → 0.5.0

package/src/kanban.ts

@@ -0,0 +1,507 @@
+import * as Automerge from "@automerge/automerge";
+import path from "node:path";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+
+import { nanoid } from "nanoid";
+import { debug } from "./debug.ts";
+import type { PeerManager } from "./peer-manager.ts";
+import type {
+  KanbanBoardDoc,
+  KanbanCard,
+  KanbanSyncFrame,
+  KanbanNotifyFrame,
+  CardStage,
+  CardPriority,
+  CardAnnotation,
+} from "./types.ts";
+
+const TAG = "kanban";
+
+/** Save debounce interval (5 seconds). */
+const SAVE_DEBOUNCE = 5_000;
+
+/** Archive interval: every 24 hours. */
+const ARCHIVE_INTERVAL = 24 * 60 * 60 * 1000;
+
+/** Default archive threshold: 30 days. */
+const DEFAULT_ARCHIVE_MS = 30 * 24 * 60 * 60 * 1000;
+
+const VALID_STAGES: CardStage[] = ["backlog", "claimed", "in_progress", "review", "done", "archived"];
+
+// ── KanbanManager ───────────────────────────────────────────────
+
+export interface KanbanManagerOptions {
+  nodeId: string;
+  peerManager: PeerManager;
+  prefix?: string;
+  autoAssign?: boolean;
+  archiveAfterMs?: number;
+  /** Override state directory (for tests). */
+  stateDir?: string;
+}
+
+export class KanbanManager {
+  private doc: Automerge.Doc<KanbanBoardDoc>;
+  private syncStates = new Map<string, Automerge.SyncState>();
+  private readonly nodeId: string;
+  private readonly peerManager: PeerManager;
+  private readonly prefix: string;
+  private readonly autoAssign: boolean;
+  private readonly archiveAfterMs: number;
+  private readonly docPath: string;
+  private archiveTimer: ReturnType<typeof setInterval> | null = null;
+  private saveTimer: ReturnType<typeof setTimeout> | null = null;
+  private dirty = false;
+  private broadcastTimer: ReturnType<typeof setTimeout> | null = null;
+  private syncRounds = new Map<string, number>();
+  private static readonly MAX_SYNC_ROUNDS = 10;
+  private static readonly BROADCAST_DEBOUNCE = 500;
+
+  constructor(opts: KanbanManagerOptions) {
+    this.nodeId = opts.nodeId;
+    this.peerManager = opts.peerManager;
+    this.prefix = opts.prefix ?? "CM";
+    this.autoAssign = opts.autoAssign ?? true;
+    this.archiveAfterMs = opts.archiveAfterMs ?? DEFAULT_ARCHIVE_MS;
+
+    const stateDir = opts.stateDir ?? path.join(homedir() || tmpdir(), ".openclaw", "clawmatrix");
+    this.docPath = path.join(stateDir, "kanban.automerge");
+
+    // Initialize empty doc
+    this.doc = Automerge.init<KanbanBoardDoc>();
+    this.doc = Automerge.change(this.doc, (d) => {
+      (d as KanbanBoardDoc).cards = {};
+      (d as KanbanBoardDoc).nextSeq = 1;
+      (d as KanbanBoardDoc).config = {
+        prefix: this.prefix,
+        autoAssign: this.autoAssign,
+        stages: [...VALID_STAGES],
+      };
+    });
+  }
+
+  async start() {
+    await this.load();
+    this.archiveOldCards();
+    this.archiveTimer = setInterval(() => this.archiveOldCards(), ARCHIVE_INTERVAL);
+    debug(TAG, `kanban manager started for node "${this.nodeId}"`);
+  }
+
+  async stop() {
+    if (this.archiveTimer) {
+      clearInterval(this.archiveTimer);
+      this.archiveTimer = null;
+    }
+    if (this.broadcastTimer) {
+      clearTimeout(this.broadcastTimer);
+      this.broadcastTimer = null;
+    }
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    await this.save();
+    debug(TAG, "kanban manager stopped");
+  }
+
+  // ── Card operations ─────────────────────────────────────────
+
+  createCard(opts: {
+    title: string;
+    description?: string;
+    priority?: CardPriority;
+    targetNode?: string;
+    targetAgent?: string;
+    cwd?: string;
+    labels?: string[];
+  }): KanbanCard {
+    const now = Date.now();
+    // Use nodeId prefix + seq to avoid CRDT conflicts
+    const nodePrefix = this.nodeId.slice(0, 4);
+    let cardId: string;
+
+    this.doc = Automerge.change(this.doc, (d) => {
+      const seq = d.nextSeq;
+      d.nextSeq = seq + 1;
+      cardId = `${this.prefix}-${nodePrefix}-${seq}`;
+
+      const card: KanbanCard = {
+        id: cardId!,
+        title: opts.title,
+        description: opts.description ?? "",
+        stage: "backlog",
+        priority: opts.priority ?? "medium",
+        targetNode: opts.targetNode,
+        targetAgent: opts.targetAgent,
+        cwd: opts.cwd,
+        annotations: [],
+        createdBy: this.nodeId,
+        createdAt: now,
+        updatedAt: now,
+        labels: opts.labels ?? [],
+      };
+
+      // Strip undefined values for Automerge
+      const clean: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(card)) {
+        if (v !== undefined) clean[k] = v;
+      }
+      d.cards[cardId!] = clean as KanbanCard;
+    });
+
+    this.scheduleSave();
+    this.broadcastSync();
+    this.broadcastNotify("card_created", cardId!, opts.title);
+
+    return this.getCard(cardId!)!;
+  }
+
+  claimCard(cardId: string, nodeId: string, agent: string): KanbanCard | null {
+    const card = this.doc.cards[cardId];
+    if (!card) return null;
+    if (card.stage !== "backlog") return null;
+
+    this.doc = Automerge.change(this.doc, (d) => {
+      const c = d.cards[cardId]!;
+      c.stage = "claimed";
+      c.assignedNode = nodeId;
+      c.assignedAgent = agent;
+      c.claimedAt = Date.now();
+      c.updatedAt = Date.now();
+    });
+
+    this.scheduleSave();
+    this.broadcastSync();
+    this.broadcastNotify("card_claimed", cardId, card.title, "claimed", nodeId, agent);
+
+    return this.getCard(cardId)!;
+  }
+
+  moveCard(cardId: string, stage: CardStage): KanbanCard | null {
+    const card = this.doc.cards[cardId];
+    if (!card) return null;
+    if (!VALID_STAGES.includes(stage)) return null;
+
+    this.doc = Automerge.change(this.doc, (d) => {
+      const c = d.cards[cardId]!;
+      c.stage = stage;
+      c.updatedAt = Date.now();
+      if (stage === "done") {
+        c.completedAt = Date.now();
+      }
+    });
+
+    this.scheduleSave();
+    this.broadcastSync();
+
+    const event = stage === "done" ? "card_completed" : "card_stage_changed";
+    this.broadcastNotify(event, cardId, card.title, stage, card.assignedNode, card.assignedAgent);
+
+    return this.getCard(cardId)!;
+  }
+
+  annotateCard(cardId: string, opts: {
+    nodeId: string;
+    agent: string;
+    type: CardAnnotation["type"];
+    content: string;
+  }): KanbanCard | null {
+    const card = this.doc.cards[cardId];
+    if (!card) return null;
+
+    const annotation: CardAnnotation = {
+      id: nanoid(),
+      nodeId: opts.nodeId,
+      agent: opts.agent,
+      type: opts.type,
+      content: opts.content,
+      ts: Date.now(),
+    };
+
+    this.doc = Automerge.change(this.doc, (d) => {
+      const c = d.cards[cardId]!;
+      c.annotations.push(annotation);
+      c.updatedAt = Date.now();
+    });
+
+    this.scheduleSave();
+    this.broadcastSync();
+    this.broadcastNotify("card_annotated", cardId, card.title, card.stage, opts.nodeId, opts.agent);
+
+    return this.getCard(cardId)!;
+  }
+
+  updateCard(cardId: string, updates: {
+    title?: string;
+    description?: string;
+    priority?: CardPriority;
+    targetNode?: string;
+    targetAgent?: string;
+    cwd?: string;
+    labels?: string[];
+    handoffId?: string;
+    acpSessionId?: string;
+  }): KanbanCard | null {
+    const card = this.doc.cards[cardId];
+    if (!card) return null;
+
+    this.doc = Automerge.change(this.doc, (d) => {
+      const c = d.cards[cardId]!;
+      if (updates.title !== undefined) c.title = updates.title;
+      if (updates.description !== undefined) c.description = updates.description;
+      if (updates.priority !== undefined) c.priority = updates.priority;
+      if (updates.targetNode !== undefined) c.targetNode = updates.targetNode;
+      if (updates.targetAgent !== undefined) c.targetAgent = updates.targetAgent;
+      if (updates.cwd !== undefined) c.cwd = updates.cwd;
+      if (updates.labels !== undefined) c.labels = updates.labels;
+      if (updates.handoffId !== undefined) c.handoffId = updates.handoffId;
+      if (updates.acpSessionId !== undefined) c.acpSessionId = updates.acpSessionId;
+      c.updatedAt = Date.now();
+    });
+
+    this.scheduleSave();
+    this.broadcastSync();
+
+    return this.getCard(cardId)!;
+  }
+
+  deleteCard(cardId: string): boolean {
+    if (!this.doc.cards[cardId]) return false;
+
+    this.doc = Automerge.change(this.doc, (d) => {
+      delete d.cards[cardId];
+    });
+
+    this.scheduleSave();
+    this.broadcastSync();
+    return true;
+  }
+
+  // ── Queries ─────────────────────────────────────────────────
+
+  getCard(cardId: string): KanbanCard | null {
+    const card = this.doc.cards[cardId];
+    return card ? { ...card, annotations: [...card.annotations] } : null;
+  }
+
+  listCards(opts?: {
+    stage?: CardStage;
+    label?: string;
+    assignedNode?: string;
+    priority?: CardPriority;
+  }): KanbanCard[] {
+    let cards = Object.values(this.doc.cards);
+
+    if (opts?.stage) cards = cards.filter((c) => c.stage === opts.stage);
+    if (opts?.label) cards = cards.filter((c) => c.labels.includes(opts.label!));
+    if (opts?.assignedNode) cards = cards.filter((c) => c.assignedNode === opts.assignedNode);
+    if (opts?.priority) cards = cards.filter((c) => c.priority === opts.priority);
+
+    // Sort: urgent first, then by creation date (newest first)
+    const priorityOrder: Record<string, number> = { urgent: 0, high: 1, medium: 2, low: 3 };
+    cards.sort((a, b) => {
+      const pa = priorityOrder[a.priority] ?? 2;
+      const pb = priorityOrder[b.priority] ?? 2;
+      if (pa !== pb) return pa - pb;
+      return b.createdAt - a.createdAt;
+    });
+
+    return cards.map((c) => ({ ...c, annotations: [...c.annotations] }));
+  }
+
+  /** Get cards available for claiming (backlog, optionally matching target). */
+  getClaimableCards(nodeId?: string, agentId?: string): KanbanCard[] {
+    return this.listCards({ stage: "backlog" }).filter((c) => {
+      if (c.targetNode && nodeId && c.targetNode !== nodeId) return false;
+      if (c.targetAgent && agentId) {
+        if (c.targetAgent.startsWith("tags:")) return true; // tag matching deferred
+        if (c.targetAgent !== agentId) return false;
+      }
+      return true;
+    });
+  }
+
+  /** Get board summary. */
+  getSummary(): {
+    total: number;
+    byStage: Record<CardStage, number>;
+    byPriority: Record<CardPriority, number>;
+  } {
+    const cards = Object.values(this.doc.cards);
+    const byStage: Record<string, number> = {};
+    const byPriority: Record<string, number> = {};
+
+    for (const s of VALID_STAGES) byStage[s] = 0;
+    for (const p of ["low", "medium", "high", "urgent"]) byPriority[p] = 0;
+
+    for (const c of cards) {
+      byStage[c.stage] = (byStage[c.stage] ?? 0) + 1;
+      byPriority[c.priority] = (byPriority[c.priority] ?? 0) + 1;
+    }
+
+    return {
+      total: cards.length,
+      byStage: byStage as Record<CardStage, number>,
+      byPriority: byPriority as Record<CardPriority, number>,
+    };
+  }
+
+  // ── Sync protocol ──────────────────────────────────────────
+
+  handleSyncMessage(frame: KanbanSyncFrame) {
+    const peerId = frame.from;
+    const message = new Uint8Array(Buffer.from(frame.payload.data, "base64"));
+
+    const rounds = (this.syncRounds.get(peerId) ?? 0) + 1;
+    if (rounds > KanbanManager.MAX_SYNC_ROUNDS) {
+      debug(TAG, `sync with ${peerId} exceeded ${KanbanManager.MAX_SYNC_ROUNDS} rounds, resetting`);
+      this.syncStates.set(peerId, Automerge.initSyncState());
+      this.syncRounds.delete(peerId);
+      return;
+    }
+    this.syncRounds.set(peerId, rounds);
+
+    try {
+      const syncState = this.syncStates.get(peerId) ?? Automerge.initSyncState();
+      const [newDoc, newSyncState] = Automerge.receiveSyncMessage(this.doc, syncState, message);
+      this.doc = newDoc;
+      this.syncStates.set(peerId, newSyncState);
+      this.scheduleSave();
+      this.sendSyncMessage(peerId);
+    } catch (err) {
+      debug(TAG, `error handling sync from ${peerId}: ${err}`);
+    }
+  }
+
+  initPeerSync(peerId: string) {
+    if (peerId === this.nodeId) return;
+    this.syncStates.set(peerId, Automerge.initSyncState());
+  }
+
+  removePeerSync(peerId: string) {
+    this.syncStates.delete(peerId);
+  }
+
+  private sendSyncMessage(peerId: string) {
+    const syncState = this.syncStates.get(peerId) ?? Automerge.initSyncState();
+    const [newSyncState, message] = Automerge.generateSyncMessage(this.doc, syncState);
+    this.syncStates.set(peerId, newSyncState);
+
+    if (!message) {
+      this.syncRounds.delete(peerId);
+      return;
+    }
+
+    debug(TAG, `sending kanban sync to ${peerId} (${message.byteLength} bytes)`);
+
+    const frame: KanbanSyncFrame = {
+      type: "kanban_sync",
+      from: this.nodeId,
+      to: peerId,
+      timestamp: Date.now(),
+      payload: {
+        data: Buffer.from(message).toString("base64"),
+      },
+    };
+
+    this.peerManager.router.sendTo(peerId, frame);
+  }
+
+  private broadcastSync() {
+    if (this.broadcastTimer) return;
+    this.broadcastTimer = setTimeout(() => {
+      this.broadcastTimer = null;
+      this.syncRounds.clear();
+      const peers = this.peerManager.router.getAllPeers();
+      for (const peer of peers) {
+        this.sendSyncMessage(peer.nodeId);
+      }
+    }, KanbanManager.BROADCAST_DEBOUNCE);
+  }
+
+  private broadcastNotify(
+    event: KanbanNotifyFrame["payload"]["event"],
+    cardId: string,
+    cardTitle: string,
+    stage?: CardStage,
+    nodeId?: string,
+    agent?: string,
+  ) {
+    const payload: KanbanNotifyFrame["payload"] = {
+      event,
+      cardId,
+      cardTitle,
+    };
+    if (stage) payload.stage = stage;
+    if (nodeId) payload.nodeId = nodeId;
+    if (agent) payload.agent = agent;
+
+    const frame: KanbanNotifyFrame = {
+      type: "kanban_notify",
+      from: this.nodeId,
+      timestamp: Date.now(),
+      payload,
+    };
+
+    this.peerManager.router.broadcast(frame);
+  }
+
+  // ── Auto-archive ───────────────────────────────────────────
+
+  private archiveOldCards() {
+    const cutoff = Date.now() - this.archiveAfterMs;
+    let archived = 0;
+
+    this.doc = Automerge.change(this.doc, (d) => {
+      for (const [, card] of Object.entries(d.cards)) {
+        if (card.stage === "done" && card.completedAt && card.completedAt < cutoff) {
+          card.stage = "archived";
+          archived++;
+        }
+      }
+    });
+
+    if (archived > 0) {
+      debug(TAG, `auto-archived ${archived} card(s)`);
+      this.scheduleSave();
+      this.broadcastSync();
+    }
+  }
+
+  // ── Persistence ───────────────────────────────────────────
+
+  private async load() {
+    try {
+      const data = await readFile(this.docPath);
+      this.doc = Automerge.load<KanbanBoardDoc>(new Uint8Array(data));
+      debug(TAG, `loaded kanban doc from ${this.docPath}`);
+    } catch {
+      debug(TAG, "no existing kanban doc, starting fresh");
+    }
+  }
+
+  private async save() {
+    try {
+      const data = Automerge.save(this.doc);
+      await mkdir(path.dirname(this.docPath), { recursive: true });
+      await writeFile(this.docPath, Buffer.from(data));
+    } catch (err) {
+      debug(TAG, `failed to save kanban doc: ${err}`);
+    }
+  }
+
+  private scheduleSave() {
+    this.dirty = true;
+    if (this.saveTimer) return;
+    this.saveTimer = setTimeout(() => {
+      this.saveTimer = null;
+      if (this.dirty) {
+        this.dirty = false;
+        this.save().catch((err) => {
+          debug(TAG, `deferred save error: ${err}`);
+        });
+      }
+    }, SAVE_DEBOUNCE);
+  }
+}