clawmatrix 0.4.2 → 0.5.0

package/README.md

@@ -56,10 +56,7 @@ Edit `openclaw.json` to add the plugin configuration. All nodes share the same `
           "nodeId": "cloud-01",
           "secret": "your-shared-secret-min-16-chars",
           "listen": true,
-          "listenPort": 19000,
-          "agents": [
-            { "id": "reviewer", "description": "Code review", "tags": ["review"] }
-          ]
+          "listenPort": 19000
         }
       }
     }
@@ -73,13 +70,12 @@ Edit `openclaw.json` to add the plugin configuration. All nodes share the same `
 {
   "nodeId": "office-01",
   "secret": "your-shared-secret-min-16-chars",
-  "peers": [{ "nodeId": "cloud-01", "url": "wss://cloud-01.example.com:19000" }],
-  "agents": [{ "id": "coder", "description": "Code development", "tags": ["coding"] }],
+  "peers": ["wss://cloud-01.example.com:19000"],
   "models": [
     { "id": "claude-sonnet", "provider": "anthropic" },
     { "id": "deepseek-coder", "provider": "ollama" }
   ],
-  "toolProxy": { "enabled": true, "allow": ["*"] }
+  "toolProxy": true
 }
 ```
 
@@ -89,17 +85,18 @@ Edit `openclaw.json` to add the plugin configuration. All nodes share the same `
 {
   "nodeId": "home-01",
   "secret": "your-shared-secret-min-16-chars",
-  "peers": [{ "nodeId": "cloud-01", "url": "wss://cloud-01.example.com:19000" }],
-  "agents": [{ "id": "assistant", "description": "Personal assistant", "tags": ["general"] }],
+  "peers": ["wss://cloud-01.example.com:19000"],
   "proxyModels": [
     { "nodeId": "office-01", "models": [{ "id": "claude-sonnet" }] }
   ]
 }
 ```
 
-**Important**: Nodes sharing models only need to declare `{ id, provider }` in `models`. ClawMatrix automatically reads the corresponding `baseUrl` and `apiKey` from OpenClaw's `models.providers` and calls the model API directly (bypassing the OpenClaw Gateway's agent system).
-
-Nodes consuming remote models need to register them in `models.providers` (using the nodeId as the key, with baseUrl pointing to the proxy port). See [BOOTSTRAP.md](BOOTSTRAP.md) for details.
+> **Notes**:
+> - `agents` can be omitted — auto-discovered from OpenClaw's `agents.list` config.
+> - `peers` accepts URL strings — nodeId is resolved from the handshake. Use `{ "nodeId": "x", "url": "wss://..." }` when you need a specific nodeId.
+> - `toolProxy: true` is shorthand for `{ "enabled": true, "allow": ["*"] }`.
+> - Nodes sharing models only need `{ id, provider }` in `models` — ClawMatrix auto-reads `baseUrl`/`apiKey` from OpenClaw's `models.providers`.
 
 To use a cluster model: `/model <nodeId>/<modelId>`.
 
@@ -145,8 +142,8 @@ The target parameter supports nodeId (`"office-01"`) or tag queries (`"tags:codi
 | `listen` | boolean | `false` | Accept inbound WS connections |
 | `listenHost` | string | `"0.0.0.0"` | Listen address |
 | `listenPort` | number | `0` (random) | Inbound WS port |
-| `peers` | array | `[]` | Peers to connect to: `{ nodeId, url }` |
-| `agents` | array | `[]` | Local Agents: `{ id, description, tags }` |
+| `peers` | array | `[]` | Peers: URL string or `{ nodeId, url }` (nodeId auto-resolved from handshake when using string form) |
+| `agents` | array | `[]` | Local Agents: `{ id, description, tags }` (auto-discovered from OpenClaw if omitted) |
 | `models` | array | `[]` | Models shared with the cluster: `{ id, provider }` (auto-reads OpenClaw provider config; optional `baseUrl`/`apiKey` override) |
 | `proxyModels` | array | `[]` | Remote model groups to consume: `{ nodeId, models: [{ id }] }` |
 | `tags` | array | `[]` | Free-form node tags |
@@ -165,20 +162,23 @@ The target parameter supports nodeId (`"office-01"`) or tag queries (`"tags:codi
 
 ### Tool Proxy
 
+Accepts `true` (enable all), `false` (disable), or an object for fine-grained control.
+
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `toolProxy.enabled` | boolean | `false` | Allow remote tool execution |
+| `toolProxy` | boolean \| object | — | `true` = enable all tools, `false` = disable |
+| `toolProxy.enabled` | boolean | `false` | Allow remote tool execution (object form) |
 | `toolProxy.allow` | array | `[]` | Allowed tool names; `["*"]` or `[]` means all |
 | `toolProxy.deny` | array | `[]` | Denied tools (takes precedence over allow) |
 | `toolProxy.maxOutputBytes` | number | `1048576` | Max tool output size (bytes) |
 
 ### Peer Approval
 
-Peer approval accepts either a boolean shorthand or an object. The default is `true` (required mode enabled).
+Accepts `"required"`, `"notify"`, `"none"`, a boolean, or an object. Default: `true` (required mode).
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `peerApproval` | boolean \| object | `true` | `true` = required mode, `false` = disabled, or object for fine-grained config |
+| `peerApproval` | string \| boolean \| object | `true` | `"required"` / `"notify"` / `"none"`, or `true`/`false`, or object |
 | `peerApproval.enabled` | boolean | `false` | Enable peer approval (object form) |
 | `peerApproval.mode` | string | `"notify"` | `"notify"` (log only) or `"required"` (block until approved) |
 | `peerApproval.timeout` | number | `1200000` | Approval request timeout (ms) |
@@ -235,10 +235,6 @@ Peer approval accepts either a boolean shorthand or an object. The default is `t
 
 ### Web UI
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `web.enabled` | boolean | `false` | Enable HTTP web interface |
-| `web.token` | string | required if enabled | Auth token (>= 8 characters) |
 
 ## Architecture
 

package/cli/bin/clawmatrix.mjs

@@ -607,7 +607,7 @@ async function cmdEvents(args) {
     console.log();
   } catch (err) {
     const msg = err.message || String(err);
-    if (msg.includes("not enabled")) console.log("Events not available (web.enabled = false in config).");
+    if (msg.includes("not available")) console.log("Events not available (listen mode not enabled in config).");
     else console.log("Could not reach gateway. Is it running?");
   }
 }
@@ -664,6 +664,8 @@ function cmdHelpJson() {
     { name: "deny", args: "<approvalId>", options: [], description: "Deny a pending peer" },
     { name: "approval list", args: "", options: [], description: "List approved/pending peers" },
     { name: "approval revoke", args: "<nodeId>", options: [], description: "Revoke an approved peer" },
+    { name: "kb files", args: "", options: ["--json"], description: "List all synced knowledge files" },
+    { name: "kb history", args: "<path>", options: ["--json"], description: "Show change history for a synced file" },
     { name: "install-skill", args: "", options: [], description: "Symlink skill into ~/.claude/skills/" },
   ];
   console.log(jsonOut({ prefix: "clawmatrix", commands }));
@@ -931,6 +933,299 @@ async function cmdTransfer(node, localPath, args) {
   }
 }
 
+// ── Knowledge sync command ─────────────────────────────────────────
+
+async function cmdKb(args) {
+  const isJson = args.includes("--json");
+  const subCmd = args[0];
+  const subArgs = args.slice(1);
+
+  if (!subCmd || subCmd === "--help" || subCmd === "-h") {
+    console.log(`Usage: clawmatrix kb [subcommand]
+
+Subcommands:
+  files [--json]          List all synced files with metadata
+  history <path> [--json] Show change history for a synced file`);
+    return;
+  }
+
+  try {
+    if (subCmd === "files") {
+      const files = await callGateway("clawmatrix.kb.files", {});
+      if (isJson) { console.log(jsonOut(files)); return; }
+      if (!Array.isArray(files) || files.length === 0) {
+        console.log("No synced files.");
+        return;
+      }
+
+      if (!isTTY) {
+        for (const f of files) {
+          console.log(`${f.path} | v${f.version} | ${new Date(f.updatedAt).toISOString()}${f.deleted ? " | deleted" : ""}`);
+        }
+        return;
+      }
+
+      console.log();
+      console.log(`  ${cyan("◆")}  ${bold("Synced Files")}  ${dim(`${files.length} file(s)`)}`);
+      console.log(`  ${bar}`);
+      for (const f of files) {
+        const ts = new Date(f.updatedAt).toLocaleString();
+        const del = f.deleted ? red(" [deleted]") : "";
+        console.log(`  ${bar}  ${bold(f.path)}  ${dim(`v${f.version}`)}  ${dim(ts)}${del}`);
+      }
+      console.log();
+      return;
+    }
+
+    if (subCmd === "history") {
+      const filePath = subArgs.filter((a) => !a.startsWith("--"))[0];
+      if (!filePath) { console.error("Usage: clawmatrix kb history <path>"); process.exit(1); }
+      const result = await callGateway("clawmatrix.kb.history", { path: filePath });
+      if (isJson) { console.log(jsonOut(result)); return; }
+
+      const history = result?.history;
+      if (!Array.isArray(history) || history.length === 0) {
+        console.log(`No history for: ${filePath}`);
+        return;
+      }
+
+      if (!isTTY) {
+        for (const h of history) {
+          const parts = [new Date(h.timestamp).toISOString()];
+          if (h.nodeId) parts.push(`node=${h.nodeId}`);
+          if (h.agentId) parts.push(`agent=${h.agentId}`);
+          if (!h.nodeId && !h.agentId && h.message) parts.push(h.message);
+          parts.push(`actor=${h.actor}`);
+          console.log(parts.join(" | "));
+        }
+        return;
+      }
+
+      console.log();
+      console.log(`  ${cyan("◆")}  ${bold("File History")}  ${dim(filePath)}  ${dim(`${history.length} change(s)`)}`);
+      console.log(`  ${bar}`);
+      for (const h of history) {
+        const ts = new Date(h.timestamp).toLocaleString();
+        const attribution = [];
+        if (h.nodeId) attribution.push(`node: ${h.nodeId}`);
+        if (h.agentId) attribution.push(`agent: ${h.agentId}`);
+        const attrStr = attribution.length > 0 ? yellow(attribution.join(", ")) : dim(h.message || h.actor);
+        console.log(`  ${bar}  ${dim(ts)}  ${attrStr}`);
+      }
+      console.log();
+      return;
+    }
+
+    console.error(`Unknown kb subcommand: ${subCmd}`);
+    process.exit(1);
+  } catch (e) {
+    console.error(`kb ${subCmd} failed: ${e.message}`);
+    process.exitCode = 1;
+  }
+}
+
+// ── Board (Kanban) command ─────────────────────────────────────────
+
+async function cmdBoard(args) {
+  const isJson = args.includes("--json");
+  const subCmd = args[0];
+  const subArgs = args.slice(1);
+
+  if (!subCmd || subCmd === "--help" || subCmd === "-h") {
+    console.log(`Usage: clawmatrix board [subcommand]
+
+Subcommands:
+  (no args)                     Board summary
+  list [--stage <s>] [--label <l>] [--priority <p>] [--json]
+                                List cards
+  create <title> [--desc <text>] [--priority <p>] [--labels <l1,l2>]
+                                Create a new card
+  get <cardId>                  Get card details
+  claim <cardId> [--agent <a>]  Claim a backlog card
+  move <cardId> <stage>         Move card to a stage (backlog|claimed|in_progress|review|done|archived)
+  annotate <cardId> <text> [--type <t>]
+                                Add annotation (note|session_link|artifact|progress|error)
+  delete <cardId>               Delete a card`);
+    return;
+  }
+
+  try {
+    if (subCmd === "list") {
+      const params = {};
+      const stageIdx = subArgs.indexOf("--stage");
+      if (stageIdx !== -1) params.stage = subArgs[stageIdx + 1];
+      const labelIdx = subArgs.indexOf("--label");
+      if (labelIdx !== -1) params.label = subArgs[labelIdx + 1];
+      const prioIdx = subArgs.indexOf("--priority");
+      if (prioIdx !== -1) params.priority = subArgs[prioIdx + 1];
+      const nodeIdx = subArgs.indexOf("--node");
+      if (nodeIdx !== -1) params.assignedNode = subArgs[nodeIdx + 1];
+
+      const cards = await callGateway("clawmatrix.board.list", params);
+      if (isJson) { console.log(jsonOut(cards)); return; }
+      if (!Array.isArray(cards) || cards.length === 0) {
+        console.log("No cards found.");
+        return;
+      }
+
+      if (!isTTY) {
+        for (const c of cards) {
+          const labels = c.labels?.length ? ` [${c.labels.join(",")}]` : "";
+          const assigned = c.assignedNode ? ` → ${c.assignedNode}` : "";
+          console.log(`${c.id} | ${c.stage} | ${c.priority} | ${c.title}${labels}${assigned}`);
+        }
+        return;
+      }
+
+      console.log();
+      console.log(`  ${cyan("◆")}  ${bold("Kanban Board")}  ${dim(`${cards.length} card(s)`)}`);
+      console.log(`  ${bar}`);
+      const priorityColor = { urgent: red, high: yellow, medium: (s) => s, low: dim };
+      for (const c of cards) {
+        const pc = (priorityColor[c.priority] ?? ((s) => s));
+        const labels = c.labels?.length ? dim(` [${c.labels.join(",")}]`) : "";
+        const assigned = c.assignedNode ? dim(` → ${c.assignedNode}`) : "";
+        console.log(`  ${bar}  ${pc(c.priority.padEnd(7))} ${bold(c.id)} ${c.title}${labels}${assigned}  ${dim(c.stage)}`);
+      }
+      console.log();
+      return;
+    }
+
+    if (subCmd === "create") {
+      const title = subArgs.filter((a) => !a.startsWith("--"))[0];
+      if (!title) { console.error("Usage: clawmatrix board create <title>"); process.exit(1); }
+      const params = { title };
+      const descIdx = subArgs.indexOf("--desc");
+      if (descIdx !== -1) params.description = subArgs[descIdx + 1];
+      const prioIdx = subArgs.indexOf("--priority");
+      if (prioIdx !== -1) params.priority = subArgs[prioIdx + 1];
+      const labelsIdx = subArgs.indexOf("--labels");
+      if (labelsIdx !== -1) params.labels = subArgs[labelsIdx + 1]?.split(",");
+      const nodeIdx = subArgs.indexOf("--node");
+      if (nodeIdx !== -1) params.targetNode = subArgs[nodeIdx + 1];
+      const agentIdx = subArgs.indexOf("--agent");
+      if (agentIdx !== -1) params.targetAgent = subArgs[agentIdx + 1];
+
+      const card = await callGateway("clawmatrix.board.create", params);
+      if (isJson) { console.log(jsonOut(card)); return; }
+      console.log(`Created: ${card.id} — ${card.title}`);
+      return;
+    }
+
+    if (subCmd === "get") {
+      const cardId = subArgs.filter((a) => !a.startsWith("--"))[0];
+      if (!cardId) { console.error("Usage: clawmatrix board get <cardId>"); process.exit(1); }
+      const card = await callGateway("clawmatrix.board.get", { cardId });
+      if (isJson) { console.log(jsonOut(card)); return; }
+
+      if (!isTTY) {
+        console.log(`${card.id} | ${card.stage} | ${card.priority} | ${card.title}`);
+        if (card.description) console.log(`Description: ${card.description}`);
+        if (card.assignedNode) console.log(`Assigned: ${card.assignedNode} / ${card.assignedAgent || "?"}`);
+        if (card.annotations?.length) {
+          console.log(`Annotations: ${card.annotations.length}`);
+          for (const a of card.annotations) {
+            console.log(`  [${a.type}] ${a.agent}@${a.nodeId}: ${a.content}`);
+          }
+        }
+        return;
+      }
+
+      console.log();
+      console.log(`  ${cyan("◆")}  ${bold(card.id)} — ${card.title}`);
+      console.log(`  ${bar}`);
+      console.log(`  ${bar}  ${lbl("Stage")} ${card.stage}`);
+      console.log(`  ${bar}  ${lbl("Priority")} ${card.priority}`);
+      if (card.description) console.log(`  ${bar}  ${lbl("Description")} ${card.description}`);
+      if (card.assignedNode) console.log(`  ${bar}  ${lbl("Assigned")} ${card.assignedNode} / ${card.assignedAgent || "?"}`);
+      if (card.labels?.length) console.log(`  ${bar}  ${lbl("Labels")} ${card.labels.join(", ")}`);
+      if (card.annotations?.length) {
+        console.log(`  ${bar}`);
+        console.log(`  ${bar}  ${bold("Annotations")} (${card.annotations.length})`);
+        for (const a of card.annotations) {
+          console.log(`  ${bar}    ${dim(`[${a.type}]`)} ${a.agent}: ${a.content}`);
+        }
+      }
+      console.log();
+      return;
+    }
+
+    if (subCmd === "claim") {
+      const cardId = subArgs.filter((a) => !a.startsWith("--"))[0];
+      if (!cardId) { console.error("Usage: clawmatrix board claim <cardId>"); process.exit(1); }
+      const params = { cardId };
+      const agentIdx = subArgs.indexOf("--agent");
+      if (agentIdx !== -1) params.agent = subArgs[agentIdx + 1];
+      const card = await callGateway("clawmatrix.board.claim", params);
+      if (isJson) { console.log(jsonOut(card)); return; }
+      console.log(`Claimed: ${card.id} → ${card.assignedNode} / ${card.assignedAgent}`);
+      return;
+    }
+
+    if (subCmd === "move") {
+      const positionals = subArgs.filter((a) => !a.startsWith("--"));
+      const cardId = positionals[0];
+      const stage = positionals[1];
+      if (!cardId || !stage) { console.error("Usage: clawmatrix board move <cardId> <stage>"); process.exit(1); }
+      const card = await callGateway("clawmatrix.board.move", { cardId, stage });
+      if (isJson) { console.log(jsonOut(card)); return; }
+      console.log(`Moved: ${card.id} → ${card.stage}`);
+      return;
+    }
+
+    if (subCmd === "annotate") {
+      const positionals = subArgs.filter((a) => !a.startsWith("--"));
+      const cardId = positionals[0];
+      const content = positionals.slice(1).join(" ");
+      if (!cardId || !content) { console.error("Usage: clawmatrix board annotate <cardId> <text>"); process.exit(1); }
+      const params = { cardId, content };
+      const typeIdx = subArgs.indexOf("--type");
+      if (typeIdx !== -1) params.annotationType = subArgs[typeIdx + 1];
+      const card = await callGateway("clawmatrix.board.annotate", params);
+      if (isJson) { console.log(jsonOut(card)); return; }
+      console.log(`Annotated: ${card.id} (${card.annotations?.length ?? 0} annotations)`);
+      return;
+    }
+
+    if (subCmd === "delete") {
+      const cardId = subArgs.filter((a) => !a.startsWith("--"))[0];
+      if (!cardId) { console.error("Usage: clawmatrix board delete <cardId>"); process.exit(1); }
+      const result = await callGateway("clawmatrix.board.delete", { cardId });
+      if (isJson) { console.log(jsonOut(result)); return; }
+      console.log(result.deleted ? `Deleted: ${cardId}` : `Card not found: ${cardId}`);
+      return;
+    }
+
+    // Default: board summary
+    const summary = await callGateway("clawmatrix.board.summary", {});
+    if (isJson) { console.log(jsonOut(summary)); return; }
+
+    if (!isTTY) {
+      console.log(`Total: ${summary.total}`);
+      for (const [stage, count] of Object.entries(summary.byStage || {})) {
+        if (count > 0) console.log(`  ${stage}: ${count}`);
+      }
+      return;
+    }
+
+    console.log();
+    console.log(`  ${cyan("◆")}  ${bold("Kanban Board Summary")}  ${dim(`${summary.total} card(s)`)}`);
+    console.log(`  ${bar}`);
+    const stageLabels = { backlog: "Backlog", claimed: "Claimed", in_progress: "In Progress", review: "Review", done: "Done", archived: "Archived" };
+    for (const [stage, label] of Object.entries(stageLabels)) {
+      const count = summary.byStage?.[stage] ?? 0;
+      if (count > 0 || stage !== "archived") {
+        console.log(`  ${bar}  ${lbl(label)} ${count}`);
+      }
+    }
+    console.log();
+
+  } catch (e) {
+    console.error(e.message);
+    process.exitCode = 1;
+  }
+}
+
 const HELP = `ClawMatrix - Decentralized mesh cluster CLI
 
 Usage: clawmatrix <command> [options]
@@ -952,6 +1247,8 @@ Commands:
   transfer <node> <path>  Transfer files to/from a remote node
   approve <approvalId>    Approve a pending peer join request
   deny <approvalId>       Deny a pending peer join request
+  kb [subcommand]         Knowledge sync (files|history)
+  board [subcommand]      Kanban board (list|create|get|claim|move|annotate|delete)
   approval list|revoke    Manage approved peers
   install-skill           Symlink skill into ~/.claude/skills/
   help-json               Structured command reference (JSON)
@@ -984,6 +1281,8 @@ try {
     case "notify":        await cmdNotify(rest[0], rest.slice(1)); break;
     case "terminal":      await cmdTerminal(rest[0], rest.slice(1)); break;
     case "transfer":      await cmdTransfer(rest[0], rest[1], rest.slice(2)); break;
+    case "kb": case "knowledge": await cmdKb(rest); break;
+    case "board":          await cmdBoard(rest); break;
     case "approve":       await cmdApprove(rest[0]); break;
     case "deny":          await cmdDeny(rest[0]); break;
     case "approval":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",
@@ -36,13 +36,20 @@
     "@agentclientprotocol/sdk": "^0.16.1",
     "@automerge/automerge": "^3.2.4",
     "@mariozechner/pi-coding-agent": ">=0.55.0",
+    "async-mutex": "^0.5.0",
+    "better-sqlite3": "^12.8.0",
+    "cockatiel": "^3.2.1",
+    "eventemitter3": "^5.0.4",
     "ignore": "^7.0.5",
+    "lru-cache": "^11.2.7",
+    "nanoid": "^5.1.7",
     "node-pty": "^1.0.0",
     "picomatch": "^4.0.3",
     "ws": "^8.19.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/bun": "latest",
     "@types/picomatch": "^4.0.2",
     "@types/ws": "^8.18.1"