clawmatrix 0.4.2 → 0.5.0

package/src/tools/cluster-events.ts

@@ -8,7 +8,7 @@ export function createClusterEventsTool(): AnyAgentTool {
     description:
       "Query and consume events from external sources (iOS Shortcuts, webhooks, etc.). " +
       "Common types: message_received, location_change, battery_status. " +
-      "Events are persistent until consumed. Requires web.enabled in config.",
+      "Events are persistent until consumed. Requires listen mode (listen: true).",
     parameters: {
       type: "object",
       properties: {
@@ -58,10 +58,10 @@ export function createClusterEventsTool(): AnyAgentTool {
 
       try {
         const runtime = getClusterRuntime();
-        const webHandler = runtime.webHandler;
-        if (!webHandler) {
+        const apiHandler = runtime.apiHandler;
+        if (!apiHandler) {
           return {
-            content: [{ type: "text" as const, text: "Event ingestion requires web dashboard to be enabled (web.enabled = true)" }],
+            content: [{ type: "text" as const, text: "Event ingestion requires listen mode (listen: true in config)" }],
             details: { error: true },
           };
         }
@@ -73,7 +73,7 @@ export function createClusterEventsTool(): AnyAgentTool {
               details: { error: true },
             };
           }
-          const consumed = webHandler.consumeEvents(ids);
+          const consumed = apiHandler.consumeEvents(ids);
           return {
             content: [{ type: "text" as const, text: `Consumed ${consumed} event(s)` }],
             details: { consumed },
@@ -81,7 +81,7 @@ export function createClusterEventsTool(): AnyAgentTool {
         }
 
         // action === "query"
-        const events = webHandler.queryEvents({
+        const events = apiHandler.queryEvents({
           type,
           source,
           since,

package/src/tools/cluster-kanban.ts

@@ -0,0 +1,345 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+import type { CardStage, CardPriority, CardAnnotation } from "../types.ts";
+
+export function createClusterKanbanTool(): AnyAgentTool {
+  return {
+    name: "cluster_kanban",
+    label: "Cluster Kanban Board",
+    description:
+      "Manage the distributed kanban board for tracking work items across the cluster. " +
+      "Actions: " +
+      '"create" — create a new card. ' +
+      '"list" — list cards (optionally filtered by stage, label, node, priority). ' +
+      '"get" — get card details by ID. ' +
+      '"claim" — claim a backlog card for execution. ' +
+      '"move" — move a card to a different stage. ' +
+      '"annotate" — add a note, progress update, artifact link, or error to a card. ' +
+      '"update" — update card fields (title, description, priority, labels, etc.). ' +
+      '"delete" — delete a card. ' +
+      '"summary" — get board summary with counts by stage and priority.',
+    parameters: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["create", "list", "get", "claim", "move", "annotate", "update", "delete", "summary"],
+          description: 'Action to perform. Default: "list"',
+        },
+        cardId: {
+          type: "string",
+          description: "Card ID (e.g. CM-abc1-1) for get, claim, move, annotate, update, delete",
+        },
+        title: {
+          type: "string",
+          description: "Card title (for create or update)",
+        },
+        description: {
+          type: "string",
+          description: "Card description in Markdown (for create or update)",
+        },
+        stage: {
+          type: "string",
+          enum: ["backlog", "claimed", "in_progress", "review", "done", "archived"],
+          description: "Target stage (for move) or filter (for list)",
+        },
+        priority: {
+          type: "string",
+          enum: ["low", "medium", "high", "urgent"],
+          description: "Card priority (for create, update, or list filter)",
+        },
+        targetNode: {
+          type: "string",
+          description: "Preferred node ID for execution (for create or update)",
+        },
+        targetAgent: {
+          type: "string",
+          description: 'Preferred agent ID or "tags:<tag>" (for create or update)',
+        },
+        cwd: {
+          type: "string",
+          description: "Working directory for the task (for create or update)",
+        },
+        labels: {
+          type: "array",
+          items: { type: "string" },
+          description: "Labels for filtering (for create, update, or list filter)",
+        },
+        assignedNode: {
+          type: "string",
+          description: "Filter by assigned node (for list)",
+        },
+        agent: {
+          type: "string",
+          description: "Agent name (for claim or annotate)",
+        },
+        annotationType: {
+          type: "string",
+          enum: ["note", "session_link", "artifact", "progress", "error"],
+          description: "Type of annotation (for annotate action)",
+        },
+        content: {
+          type: "string",
+          description: "Annotation content (for annotate action)",
+        },
+        handoffId: {
+          type: "string",
+          description: "Associated handoff ID (for update)",
+        },
+        acpSessionId: {
+          type: "string",
+          description: "Associated ACP session ID (for update)",
+        },
+      },
+      required: [],
+    },
+    async execute(_toolCallId, params) {
+      const {
+        action = "list",
+        cardId,
+        title,
+        description,
+        stage,
+        priority,
+        targetNode,
+        targetAgent,
+        cwd,
+        labels,
+        assignedNode,
+        agent,
+        annotationType,
+        content,
+        handoffId,
+        acpSessionId,
+      } = params as {
+        action?: string;
+        cardId?: string;
+        title?: string;
+        description?: string;
+        stage?: CardStage;
+        priority?: CardPriority;
+        targetNode?: string;
+        targetAgent?: string;
+        cwd?: string;
+        labels?: string[];
+        assignedNode?: string;
+        agent?: string;
+        annotationType?: CardAnnotation["type"];
+        content?: string;
+        handoffId?: string;
+        acpSessionId?: string;
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+        const km = runtime.kanbanManager;
+
+        if (!km) {
+          return {
+            content: [{ type: "text" as const, text: "Kanban board not available (kanban.enabled is false in config)" }],
+            details: { error: true },
+          };
+        }
+
+        if (action === "summary") {
+          const summary = km.getSummary();
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(summary) }],
+            details: summary,
+          };
+        }
+
+        if (action === "list") {
+          const cards = km.listCards({
+            stage,
+            label: labels?.[0],
+            assignedNode,
+            priority,
+          });
+          // Return compact list (no annotations to save tokens)
+          const compact = cards.map((c) => ({
+            id: c.id,
+            title: c.title,
+            stage: c.stage,
+            priority: c.priority,
+            assignedNode: c.assignedNode,
+            assignedAgent: c.assignedAgent,
+            labels: c.labels,
+            createdAt: c.createdAt,
+            updatedAt: c.updatedAt,
+          }));
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(compact) }],
+            details: compact,
+          };
+        }
+
+        if (action === "create") {
+          if (!title) {
+            return {
+              content: [{ type: "text" as const, text: "title is required for create action" }],
+              details: { error: true },
+            };
+          }
+          const card = km.createCard({
+            title,
+            description,
+            priority,
+            targetNode,
+            targetAgent,
+            cwd,
+            labels,
+          });
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(card) }],
+            details: card,
+          };
+        }
+
+        if (action === "get") {
+          if (!cardId) {
+            return {
+              content: [{ type: "text" as const, text: "cardId is required for get action" }],
+              details: { error: true },
+            };
+          }
+          const card = km.getCard(cardId);
+          if (!card) {
+            return {
+              content: [{ type: "text" as const, text: `Card not found: ${cardId}` }],
+              details: { error: true },
+            };
+          }
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(card) }],
+            details: card,
+          };
+        }
+
+        if (action === "claim") {
+          if (!cardId) {
+            return {
+              content: [{ type: "text" as const, text: "cardId is required for claim action" }],
+              details: { error: true },
+            };
+          }
+          const card = km.claimCard(
+            cardId,
+            runtime.config.nodeId,
+            agent ?? runtime.config.agents[0]?.id ?? "unknown",
+          );
+          if (!card) {
+            return {
+              content: [{ type: "text" as const, text: `Cannot claim card ${cardId} (not found or not in backlog)` }],
+              details: { error: true },
+            };
+          }
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(card) }],
+            details: card,
+          };
+        }
+
+        if (action === "move") {
+          if (!cardId || !stage) {
+            return {
+              content: [{ type: "text" as const, text: "cardId and stage are required for move action" }],
+              details: { error: true },
+            };
+          }
+          const card = km.moveCard(cardId, stage);
+          if (!card) {
+            return {
+              content: [{ type: "text" as const, text: `Cannot move card ${cardId} (not found or invalid stage)` }],
+              details: { error: true },
+            };
+          }
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(card) }],
+            details: card,
+          };
+        }
+
+        if (action === "annotate") {
+          if (!cardId || !content) {
+            return {
+              content: [{ type: "text" as const, text: "cardId and content are required for annotate action" }],
+              details: { error: true },
+            };
+          }
+          const card = km.annotateCard(cardId, {
+            nodeId: runtime.config.nodeId,
+            agent: agent ?? runtime.config.agents[0]?.id ?? "unknown",
+            type: annotationType ?? "note",
+            content,
+          });
+          if (!card) {
+            return {
+              content: [{ type: "text" as const, text: `Card not found: ${cardId}` }],
+              details: { error: true },
+            };
+          }
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(card) }],
+            details: card,
+          };
+        }
+
+        if (action === "update") {
+          if (!cardId) {
+            return {
+              content: [{ type: "text" as const, text: "cardId is required for update action" }],
+              details: { error: true },
+            };
+          }
+          const card = km.updateCard(cardId, {
+            title,
+            description,
+            priority,
+            targetNode,
+            targetAgent,
+            cwd,
+            labels,
+            handoffId,
+            acpSessionId,
+          });
+          if (!card) {
+            return {
+              content: [{ type: "text" as const, text: `Card not found: ${cardId}` }],
+              details: { error: true },
+            };
+          }
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(card) }],
+            details: card,
+          };
+        }
+
+        if (action === "delete") {
+          if (!cardId) {
+            return {
+              content: [{ type: "text" as const, text: "cardId is required for delete action" }],
+              details: { error: true },
+            };
+          }
+          const ok = km.deleteCard(cardId);
+          const result = { deleted: ok, cardId };
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+            details: result,
+          };
+        }
+
+        return {
+          content: [{ type: "text" as const, text: `Unknown action: ${action}` }],
+          details: { error: true },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Kanban error: ${err instanceof Error ? err.message : String(err)}` }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-peers.ts

@@ -82,7 +82,7 @@ export function createClusterPeersTool(): AnyAgentTool {
         }
 
         // Include satellite nodes (minimal fields — no agents/models)
-        const satellites = runtime.webHandler?.getSatelliteContexts() ?? runtime.peerManager.satelliteContexts;
+        const satellites = runtime.apiHandler?.getSatelliteContexts() ?? runtime.peerManager.satelliteContexts;
         for (const sat of satellites) {
           if (Date.now() - sat.ts >= 600_000) continue;
           peers.push({

package/src/tools/cluster-query.ts

@@ -0,0 +1,145 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterQueryTool(): AnyAgentTool {
+  return {
+    name: "cluster_query",
+    label: "Cluster Query",
+    description:
+      "Query replicated data from the local SQLite store: audit_log (security events), " +
+      "health_events (node lifecycle & peer connectivity), handoff_history (task execution records). " +
+      "Data is replicated across peers via log sync, so each node has a cluster-wide view.",
+    parameters: {
+      type: "object",
+      properties: {
+        table: {
+          type: "string",
+          enum: ["audit_log", "health_events", "handoff_history"],
+          description: "Which replicated table to query",
+        },
+        since: {
+          type: "number",
+          description: "Events after this unix timestamp (ms). Shorthand: use negative values for relative offsets, e.g. -3600000 for last hour",
+        },
+        node_id: {
+          type: "string",
+          description: "Filter by originating node ID",
+        },
+        event: {
+          type: "string",
+          description: "Filter audit_log by event type (conn_open, auth_failure, peer_join, etc.)",
+        },
+        type: {
+          type: "string",
+          description: "Filter health_events by type (start, stop, peer_online, peer_offline)",
+        },
+        peer: {
+          type: "string",
+          description: "Filter health_events by peer node ID",
+        },
+        agent: {
+          type: "string",
+          description: "Filter handoff_history by agent name",
+        },
+        status: {
+          type: "string",
+          description: "Filter handoff_history by status (completed, failed)",
+        },
+        limit: {
+          type: "number",
+          description: "Max rows to return (default 50)",
+        },
+      },
+      required: ["table"],
+    },
+    async execute(_toolCallId, params) {
+      const {
+        table, since, node_id, event, type, peer, agent, status, limit,
+      } = params as {
+        table: "audit_log" | "health_events" | "handoff_history";
+        since?: number;
+        node_id?: string;
+        event?: string;
+        type?: string;
+        peer?: string;
+        agent?: string;
+        status?: string;
+        limit?: number;
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+        const store = runtime.store;
+        if (!store) {
+          return {
+            content: [{ type: "text" as const, text: "Store not initialized" }],
+            details: { error: true },
+          };
+        }
+
+        // Handle relative since values (negative = offset from now)
+        const resolvedSince = since != null && since < 0 ? Date.now() + since : since;
+        const maxRows = Math.max(1, Math.min(limit ?? 50, 500));
+
+        let rows: unknown[];
+        let summary: string;
+
+        switch (table) {
+          case "audit_log": {
+            const result = store.queryAudit({
+              since: resolvedSince,
+              nodeId: node_id,
+              event,
+              limit: maxRows,
+            });
+            rows = result;
+            summary = `${result.length} audit event(s)`;
+            break;
+          }
+          case "health_events": {
+            const result = store.queryHealth({
+              since: resolvedSince,
+              nodeId: node_id,
+              type,
+              peer,
+              limit: maxRows,
+            });
+            rows = result;
+            summary = `${result.length} health event(s)`;
+            break;
+          }
+          case "handoff_history": {
+            const result = store.queryHandoff({
+              since: resolvedSince,
+              nodeId: node_id,
+              agent,
+              status,
+              limit: maxRows,
+            });
+            rows = result;
+            summary = `${result.length} handoff record(s)`;
+            break;
+          }
+        }
+
+        if (rows.length === 0) {
+          return {
+            content: [{ type: "text" as const, text: `No ${table} records found matching filters` }],
+            details: { count: 0, table },
+          };
+        }
+
+        const text = `${summary}\n${JSON.stringify(rows, null, 2)}`;
+        return {
+          content: [{ type: "text" as const, text }],
+          details: { count: rows.length, table },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/types.ts

@@ -89,6 +89,14 @@ export interface PeerSync extends ClusterFrame {
   payload: {
     peers: PeerInfo[];
     satellites?: SatelliteContext[];
+    /** Sync version number for delta sync. */
+    version?: number;
+    /** Delta: newly added or changed peers since last sync. */
+    added?: PeerInfo[];
+    /** Delta: removed nodeIds since last sync. */
+    removed?: string[];
+    /** Delta: peers with updated capabilities. */
+    updated?: PeerInfo[];
   };
 }
 
@@ -173,12 +181,6 @@ export interface ImageContent {
 // ── Handoff ────────────────────────────────────────────────────────
 export type HandoffStatus = "working" | "input_required" | "completed" | "failed" | "canceled";
 
-export interface Artifact {
-  name: string;
-  mimeType: string;
-  data: string; // text content or base64-encoded binary
-}
-
 export interface HandoffRequest extends ClusterFrame {
   type: "handoff_req";
   id: string;
@@ -197,7 +199,6 @@ export interface HandoffStreamChunk extends ClusterFrame {
   payload: {
     delta: string;
     done: boolean;
-    artifacts?: Artifact[];
     sessionId?: string;     // included for session watchers (multi-device sync)
   };
 }
@@ -211,7 +212,6 @@ export interface HandoffResponse extends ClusterFrame {
     agent?: string;
     result?: string;
     error?: string;
-    artifacts?: Artifact[];
     inputRequired?: boolean;
     handoffId?: string;
     sessionId?: string;  // For multi-turn conversation reuse
@@ -388,6 +388,8 @@ export interface DeviceInfo {
   totalMemoryMB: number; // total system memory in MB
   hostname: string; // machine hostname
   openclawVersion?: string; // e.g. "2026.3.7"
+  cwd?: string; // process.cwd() at gateway startup
+  workspace?: string; // OpenClaw workspace dir (agents.defaults.workspace)
 }
 
 // ── Shared info types ──────────────────────────────────────────────
@@ -955,6 +957,87 @@ export interface TerminalCloseResponse extends ClusterFrame {
   };
 }
 
+// ── Kanban board ─────────────────────────────────────────────────
+
+export type CardStage = "backlog" | "claimed" | "in_progress" | "review" | "done" | "archived";
+export type CardPriority = "low" | "medium" | "high" | "urgent";
+
+export interface CardAnnotation {
+  id: string;
+  nodeId: string;
+  agent: string;
+  type: "note" | "session_link" | "artifact" | "progress" | "error";
+  content: string;
+  ts: number;
+}
+
+export interface KanbanCard {
+  id: string;
+  title: string;
+  description: string;
+  stage: CardStage;
+  priority: CardPriority;
+  targetNode?: string;
+  targetAgent?: string;
+  cwd?: string;
+  assignedNode?: string;
+  assignedAgent?: string;
+  claimedAt?: number;
+  handoffId?: string;
+  acpSessionId?: string;
+  annotations: CardAnnotation[];
+  createdBy: string;
+  createdAt: number;
+  updatedAt: number;
+  completedAt?: number;
+  labels: string[];
+}
+
+export interface KanbanBoardDoc {
+  cards: Record<string, KanbanCard>;
+  nextSeq: number;
+  config: {
+    prefix: string;
+    autoAssign: boolean;
+    stages: CardStage[];
+  };
+}
+
+export interface KanbanSyncFrame extends ClusterFrame {
+  type: "kanban_sync";
+  payload: { data: string };
+}
+
+export interface KanbanNotifyFrame extends ClusterFrame {
+  type: "kanban_notify";
+  payload: {
+    event: "card_created" | "card_claimed" | "card_stage_changed" | "card_completed" | "card_annotated";
+    cardId: string;
+    cardTitle: string;
+    stage?: CardStage;
+    nodeId?: string;
+    agent?: string;
+  };
+}
+
+// ── Log replication ──────────────────────────────────────────────
+
+export interface LogSyncFrame extends ClusterFrame {
+  type: "log_sync";
+  payload: {
+    /** Which replicated table this sync concerns. */
+    table: "audit_log" | "health_events" | "handoff_history";
+    /** Sender's vector clock for this table: { nodeId: maxSourceSeq }. */
+    vector?: Record<string, number>;
+    /** Delta rows for the receiver to apply. */
+    rows?: Array<Record<string, unknown>>;
+    /** True when this is a sync request (receiver should compute and send delta). */
+    request?: boolean;
+    /** True when more batches follow (receiver should expect continuation). */
+    hasMore?: boolean;
+  };
+}
+
 // ── Union of all frame types ───────────────────────────────────────
 export type AnyClusterFrame =
   | AuthChallenge
@@ -1029,4 +1112,7 @@ export type AnyClusterFrame =
   | FileTransferAck
   | FileTransferChunk
   | FileTransferChunkAck
-  | FileTransferComplete;
+  | FileTransferComplete
+  | KanbanSyncFrame
+  | KanbanNotifyFrame
+  | LogSyncFrame;