clawmatrix 0.6.1 → 0.6.2

package/cli/skills/clawmatrix/SKILL.md

@@ -3,58 +3,102 @@ name: clawmatrix
 description: Use the clawmatrix CLI to interact with remote devices (phones, computers, servers) in a mesh cluster — run tools, check location, get battery status, read/write files, execute commands, and more on any connected node.
 ---
 
-Use the `clawmatrix` CLI to interact with the ClawMatrix mesh cluster. Remote nodes can be phones (iPhone/Android), computers, or servers.
+Use the `clawmatrix` CLI to interact with the ClawMatrix mesh cluster. Remote nodes can be phones (iPhone/Android), computers, or servers. You can invoke any tool available on remote nodes — including getting device location, battery status, running shell commands, reading/writing files, and more.
 
-Run `clawmatrix --help` or `clawmatrix <command> --help` for detailed usage.
+All commands output LLM-friendly text (no ANSI colors) when stdout is not a TTY.
 
-## Capabilities
+## Quick Start
 
-**Cluster & Discovery**
-- View cluster topology, peer status, node config, and uptime/availability
-- Check reachability of specific nodes with latency
-- Approve/deny/revoke peer connections
+1. Run `clawmatrix status` to see connected nodes and their capabilities
+2. Run `clawmatrix tools <nodeId>` to see what tools a node offers
+3. Run `clawmatrix call <nodeId> <tool> '<params>'` to invoke a tool
 
-**Remote Tool Execution**
-- Discover tools across all nodes (filter by keyword, describe params)
-- Invoke single tools or batch multiple in one round-trip
-- Tools include device-specific capabilities: location, battery, camera, clipboard, contacts, calendar, health data, HomeKit, etc.
+## Cluster Status
 
-**Models**
-- List all LLM models available across the cluster, filterable by node
+```bash
+clawmatrix status          # Cluster topology: peers, agents, models, tags
+clawmatrix status --json   # Structured JSON output
+clawmatrix check <nodeId>  # Quick reachability check with latency
+```
 
-**Agent Delegation**
-- `handoff` — delegate tasks to remote agents with streaming output and failover
-- `send` — fire-and-forget messages to remote nodes
-- `acp` — manage persistent coding agent sessions (Claude Code, Codex, Gemini) with prompt/resume/cancel/close
+Always start with `clawmatrix status` to understand the current topology before performing other operations.
 
-**Events & Automations**
-- Query, consume, and ingest events from external sources (iOS Shortcuts, webhooks, etc.)
-- Manage automation rules: list, create/save, manually trigger, replay historical executions
+## Remote Tools
 
-**Infrastructure**
-- `diagnostic` — sentinel-based diagnostics (works even when gateway is down)
-- `terminal` — interactive PTY sessions on remote nodes
-- `transfer` — push/pull files up to 100MB between nodes with integrity verification
-- `notify` — push Dynamic Island / Live Activity notifications to iOS devices
+```bash
+clawmatrix tools                        # List all remote tools (compact)
+clawmatrix tools <nodeId>               # Tools on a specific node
+clawmatrix tools --describe <tool>      # Full usage and parameter schema
+clawmatrix tools --filter <keyword>     # Search by name or description
+```
 
-**Knowledge Sync (CRDT)**
-- List synced workspace files, view change history, line-by-line blame, read file content
-- All knowledge is CRDT-based and mesh-synced across nodes
+Use `--describe` to understand a tool's parameters before calling it.
 
-**Kanban Board**
-- Distributed task board: create, list, get, update, claim, move, annotate, delete cards
-- Filter by stage/priority/label/node; stages flow from `backlog` → `done` → `archived`
+## Invoke Tools
 
-**Config Management**
-- View runtime config summary
-- Read/write config files under `~/.openclaw/` (for remote node configuration)
+```bash
+clawmatrix call <nodeId> <tool> '<json-params>'    # Single tool invocation
+clawmatrix call <nodeId> <tool> '<json-params>' -t 30000  # With timeout (ms)
+```
 
-## Important Notes
+```bash
+clawmatrix batch <nodeId> '[{"tool":"t1","params":{}},{"tool":"t2","params":{}}]'
+clawmatrix batch <nodeId> --no-stop-on-error '[...]'  # Continue on failure
+```
 
-- **Always start with `clawmatrix status`** to understand the cluster topology before other operations
-- **Use `clawmatrix tools --describe <tool>`** to check a tool's parameter schema before calling it
-- **Use `clawmatrix notify` proactively during long tasks** (builds, tests, large refactors) so the user can track progress on their phone without watching the terminal
-- Output is **LLM-optimized**: no ANSI colors and compact format when stdout is not a TTY; add `--json` for structured output
-- Target nodes by exact `nodeId` or by tag expression `tags:<tag>`
-- Most commands support `--json` for structured output
-- `batch` and `automations save` support stdin for piping data
+Batch supports stdin: `echo '<json>' | clawmatrix batch <nodeId>`
+
+## Models
+
+```bash
+clawmatrix models                   # All cluster models
+clawmatrix models --node <nodeId>   # Filter by node
+```
+
+## Events
+
+```bash
+clawmatrix events                       # Unconsumed events
+clawmatrix events --type <type>         # Filter by type
+clawmatrix events --source <nodeId>     # Filter by source node
+clawmatrix events --consume <id1,id2>   # Mark events as consumed
+clawmatrix events --all                 # Include consumed events
+```
+
+## Peer Approval
+
+```bash
+clawmatrix approve <approvalId>         # Approve a pending peer
+clawmatrix deny <approvalId>            # Deny a pending peer
+clawmatrix approval list                # List pending/approved/denied peers
+clawmatrix approval revoke <nodeId>     # Revoke an approved peer
+```
+
+## Notifications (Dynamic Island / Live Activity)
+
+Push progress notifications to the user's iPhone via `clawmatrix notify`. This triggers the Dynamic Island and lock screen Live Activity.
+
+**Use this proactively when running long tasks** (iOS builds, large refactors, test suites, batch operations) so the user can track progress without watching the terminal.
+
+```bash
+# Start a notification
+clawmatrix notify "iOS 构建" --detail "正在编译..."
+# Returns: {"taskId":"<id>", "action":"start", "targets":1}
+
+# Update progress
+clawmatrix notify "iOS 构建" --action update --task-id <id> --detail "链接中..." --progress 80
+
+# End (success)
+clawmatrix notify "iOS 构建" --action end --task-id <id>
+```
+
+Options: `--detail <text>`, `--progress <0-100>`, `--action start|update|end`, `--task-id <id>`, `--tool <name>`
+
+## Workflow
+
+1. Run `clawmatrix status` to see the cluster topology
+2. Use `clawmatrix tools --filter <keyword>` to find relevant tools
+3. Use `clawmatrix tools --describe <tool>` to check parameters
+4. Use `clawmatrix call` or `clawmatrix batch` to invoke tools
+5. If a call fails, run `clawmatrix check <nodeId>` to verify connectivity
+6. For long-running tasks, use `clawmatrix notify` to push progress to the user's phone

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",

package/src/connection.ts

@@ -147,7 +147,17 @@ export class Connection extends EventEmitter<ConnectionEvents> {
 
   /** Bind standard WebSocket event listeners. Call this for outbound connections. */
   bindWebSocket(ws: WebSocket) {
-    ws.addEventListener("message", (ev) => this.onRawMessage(ev.data));
+    // Node.js 22+ built-in WebSocket defaults binaryType to "blob", which
+    // onRawMessage cannot handle (Blob is async-only).  Set "arraybuffer"
+    // so binary frames arrive as ArrayBuffer, then normalize to Buffer below.
+    if ("binaryType" in ws) {
+      (ws as any).binaryType = "arraybuffer";
+    }
+    ws.addEventListener("message", (ev) => {
+      // Normalize ArrayBuffer → Buffer for consistent handling across runtimes
+      const data = ev.data instanceof ArrayBuffer ? Buffer.from(ev.data) : ev.data;
+      this.onRawMessage(data);
+    });
     ws.addEventListener("close", (ev) => {
       this.close(ev.code, ev.reason);
     });
@@ -208,11 +218,19 @@ export class Connection extends EventEmitter<ConnectionEvents> {
 
   /** Send raw data. Buffers sent as binary frames; strings as-is; objects JSON-encoded. */
   private sendRaw(data: unknown) {
-    if (this.transport.readyState === WebSocket.OPEN) {
-      if (Buffer.isBuffer(data)) {
-        this.transport.send(data);
-      } else {
-        this.transport.send(typeof data === "string" ? data : JSON.stringify(data));
+    try {
+      if (this.transport.readyState === WebSocket.OPEN) {
+        if (Buffer.isBuffer(data)) {
+          this.transport.send(data);
+        } else {
+          this.transport.send(typeof data === "string" ? data : JSON.stringify(data));
+        }
+      }
+    } catch (err) {
+      debug("send", `sendRaw failed for ${this.remoteNodeId ?? "unknown"}: ${err}`);
+      // Transport is broken — schedule close on next tick to avoid re-entrancy
+      if (!this.closed) {
+        queueMicrotask(() => this.close(4002, "send failed"));
       }
     }
   }
@@ -269,25 +287,6 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private async onRawMessage(data: unknown) {
     this.lastReceivedAt = Date.now();
 
-    // Debug: log data type for unauthenticated connections to diagnose auth issues
-    if (!this.authenticated && this.role === "outbound") {
-      const dtype = Buffer.isBuffer(data) ? `Buffer(${(data as Buffer).length})` :
-        data instanceof ArrayBuffer ? `ArrayBuffer(${data.byteLength})` :
-        typeof data === "string" ? `string(${data.length})` :
-        `${data?.constructor?.name ?? typeof data}`;
-      debug("auth", `onRawMessage[outbound] dataType=${dtype}`);
-    }
-
-    // Normalize non-Buffer binary types to Buffer.
-    // Node.js 24+'s built-in WebSocket (undici) delivers binary frames as Blob
-    // (binaryType "blob") or ArrayBuffer (binaryType "arraybuffer").
-    // The ws package delivers Buffer (binaryType "nodebuffer").
-    if (data instanceof ArrayBuffer) {
-      data = Buffer.from(data);
-    } else if (typeof Blob !== "undefined" && data instanceof Blob) {
-      data = Buffer.from(await data.arrayBuffer());
-    }
-
     let frame: AnyClusterFrame | undefined;
 
     // Binary frame (Buffer) — decrypt directly without base64
@@ -403,7 +402,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
     }
 
     if (frame.type === "ping") {
-      this.send({ type: "pong", from: this.nodeId, timestamp: Date.now() } as AnyClusterFrame);
+      this.sendDirect({ type: "pong", from: this.nodeId, timestamp: Date.now() } as AnyClusterFrame);
       return;
     }
     if (frame.type === "pong") {
@@ -579,7 +578,6 @@ export class Connection extends EventEmitter<ConnectionEvents> {
       }
 
       // auth_ok (decrypted from binary envelope, or plaintext legacy)
-      debug("auth", `Outbound received frame type=${frame.type} (authenticated=${this.authenticated})`);
       if (frame.type === "auth_ok") {
         const ok = frame as AuthOk;
         this.remoteNodeId = ok.payload.nodeId;
@@ -718,7 +716,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
         return;
       }
       this.lastPingSentAt = Date.now();
-      this.send({
+      this.sendDirect({
         type: "ping",
         from: this.nodeId,
         timestamp: this.lastPingSentAt,
@@ -755,7 +753,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   close(code = 1000, reason = "normal") {
     if (this.closed) return;
     // Flush any pending batch before closing
-    this.flushBatch();
+    try { this.flushBatch(); } catch { /* transport may already be dead */ }
     this.closed = true;
     this.clearAuthTimer();
     if (this.heartbeatTimer) {

package/src/index.ts

@@ -1537,291 +1537,6 @@ const plugin = {
       },
     );
 
-    // ── Availability gateway method ──────────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.availability",
-      ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          const { range } = (params ?? {}) as { range?: string };
-          const validRanges = ["24h", "7d", "90d"];
-          const r = validRanges.includes(range ?? "") ? (range as "24h" | "7d" | "90d") : "24h";
-          const result = runtime.healthTracker.getAvailability(r);
-          respond(true, result);
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    // ── Automation gateway methods ──────────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.automations.rules",
-      ({ respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.automationManager) {
-            respond(true, { rules: [] });
-            return;
-          }
-          respond(true, { rules: runtime.automationManager.getRules() });
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    api.registerGatewayMethod(
-      "clawmatrix.automations.save",
-      async ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.automationManager) {
-            respond(false, { error: "Automations not available" });
-            return;
-          }
-          const { rules } = (params ?? {}) as { rules?: unknown[] };
-          if (!Array.isArray(rules)) {
-            respond(false, { error: "Missing required param: rules (array)" });
-            return;
-          }
-          await runtime.automationManager.saveRules(rules as Parameters<typeof runtime.automationManager.saveRules>[0]);
-          respond(true, { ok: true, count: rules.length });
-        } catch (err) {
-          respond(false, { error: String(err) });
-        }
-      },
-    );
-
-    api.registerGatewayMethod(
-      "clawmatrix.automations.history",
-      ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.automationManager) {
-            respond(true, { executions: [] });
-            return;
-          }
-          const { limit } = (params ?? {}) as { limit?: number };
-          respond(true, { executions: runtime.automationManager.getExecutions(limit ?? 50) });
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    api.registerGatewayMethod(
-      "clawmatrix.automations.run",
-      async ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.automationManager) {
-            respond(false, { error: "Automations not available" });
-            return;
-          }
-          const { ruleId, event } = (params ?? {}) as { ruleId?: string; event?: Record<string, unknown> };
-          if (!ruleId) {
-            respond(false, { error: "Missing required param: ruleId" });
-            return;
-          }
-          const evt = event ? {
-            id: nanoid(),
-            source: String(event.source || "cli"),
-            type: String(event.type || "manual"),
-            data: (event.data ?? {}) as Record<string, unknown>,
-            ts: typeof event.ts === "number" ? event.ts : Date.now(),
-            consumed: false,
-          } as import("./types.ts").IngestedEvent : undefined;
-          const execution = await runtime.automationManager.runRuleById(ruleId, evt);
-          respond(true, { ok: true, execution });
-        } catch (err) {
-          respond(false, { error: String(err) });
-        }
-      },
-    );
-
-    api.registerGatewayMethod(
-      "clawmatrix.automations.replay",
-      async ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.automationManager) {
-            respond(false, { error: "Automations not available" });
-            return;
-          }
-          const { executionId } = (params ?? {}) as { executionId?: string };
-          if (!executionId) {
-            respond(false, { error: "Missing required param: executionId" });
-            return;
-          }
-          const execution = await runtime.automationManager.replayExecution(executionId);
-          respond(true, { ok: true, execution });
-        } catch (err) {
-          respond(false, { error: String(err) });
-        }
-      },
-    );
-
-    // ── Events ingest gateway method ──────────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.events.ingest",
-      ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.apiHandler) {
-            respond(false, { error: "API handler not available (listen mode required)" });
-            return;
-          }
-          const { events } = (params ?? {}) as { events?: unknown[] };
-          if (!Array.isArray(events) || events.length === 0) {
-            respond(false, { error: "Missing required param: events (non-empty array)" });
-            return;
-          }
-          const result = runtime.apiHandler.ingestEvents(events as Array<Record<string, unknown>>);
-          respond(true, { ok: true, ...result });
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    // ── Board update gateway method ──────────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.board.update",
-      ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.kanbanManager) {
-            respond(false, { error: "Kanban not enabled" });
-            return;
-          }
-          const { cardId, ...updates } = (params ?? {}) as {
-            cardId?: string; title?: string; description?: string;
-            priority?: string; targetNode?: string; targetAgent?: string;
-            cwd?: string; labels?: string[];
-          };
-          if (!cardId) {
-            respond(false, { error: "Missing required param: cardId" });
-            return;
-          }
-          const card = runtime.kanbanManager.updateCard(cardId, updates as Parameters<typeof runtime.kanbanManager.updateCard>[1]);
-          if (!card) {
-            respond(false, { error: `Card not found: ${cardId}` });
-            return;
-          }
-          respond(true, card);
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    // ── Config gateway method ──────────────────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.config.get",
-      ({ respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          const c = runtime.config;
-          respond(true, {
-            nodeId: c.nodeId,
-            listen: c.listen,
-            tags: c.tags,
-            agents: c.agents.map((a) => ({ id: a.id, model: a.model })),
-            models: c.models.map((m) => ({ id: m.id, provider: m.provider })),
-            e2ee: c.e2ee,
-            toolProxy: c.toolProxy ? { enabled: c.toolProxy.enabled, allow: c.toolProxy.allow, deny: c.toolProxy.deny } : undefined,
-            terminal: c.terminal,
-            acp: c.acp ? { enabled: c.acp.enabled } : undefined,
-            knowledge: c.knowledge ? { enabled: c.knowledge.enabled } : undefined,
-            proxyModels: c.proxyModels?.length ?? 0,
-            peers: c.peers?.length ?? 0,
-          });
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    // ── Config file read/write gateway methods ──────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.config.read",
-      async ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.apiHandler) {
-            respond(false, { error: "API handler not available" });
-            return;
-          }
-          const { path: configPath } = (params ?? {}) as { path?: string };
-          if (!configPath) {
-            respond(false, { error: "Missing required param: path" });
-            return;
-          }
-          const result = await runtime.apiHandler.readConfigFile(configPath);
-          respond(result.success, result);
-        } catch (err) {
-          respond(false, { error: String(err) });
-        }
-      },
-    );
-
-    api.registerGatewayMethod(
-      "clawmatrix.config.write",
-      async ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.apiHandler) {
-            respond(false, { error: "API handler not available" });
-            return;
-          }
-          const { path: configPath, content } = (params ?? {}) as { path?: string; content?: string };
-          if (!configPath || typeof content !== "string") {
-            respond(false, { error: "Missing required params: path, content" });
-            return;
-          }
-          const result = await runtime.apiHandler.writeConfigFile(configPath, content);
-          respond(result.success, result);
-        } catch (err) {
-          respond(false, { error: String(err) });
-        }
-      },
-    );
-
-    // ── Knowledge content gateway method ──────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.kb.content",
-      ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.knowledgeSync) {
-            respond(false, { error: "Knowledge sync not enabled" });
-            return;
-          }
-          const { path } = (params ?? {}) as { path?: string };
-          if (!path) {
-            respond(false, { error: "Missing required param: path" });
-            return;
-          }
-          const content = runtime.knowledgeSync.getFileContent(path);
-          if (content === null) {
-            respond(false, { error: "File not found or content not yet synced" });
-            return;
-          }
-          respond(true, { path, content });
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
     // Log model selection on each LLM call (fire-and-forget)
     api.on("llm_input", (event) => {
       api.logger.debug(`[clawmatrix] llm_input: provider=${event.provider} model=${event.model}`);

package/src/knowledge-sync.ts

@@ -191,6 +191,11 @@ export class KnowledgeSync {
 
   // ── Public API ─────────────────────────────────────────────────
 
+  /** The resolved workspace directory that knowledge files are synced under. */
+  get workspacePath(): string {
+    return this.opts.workspacePath;
+  }
+
   async start() {
     debug(TAG, `starting knowledge sync: workspace=${this.opts.workspacePath}`);
 
@@ -536,7 +541,7 @@ export class KnowledgeSync {
   }
 
   /** List all synced files with metadata. */
-  listSyncedFiles(): Array<{ path: string; version: number; updatedAt: number; deleted: boolean }> {
+  listSyncedFiles(): Array<{ path: string; version: number; updatedAt: number; deleted: boolean; synced: boolean }> {
     const files = this.registry.files;
     if (!files) return [];
     return Object.entries(files).map(([path, meta]) => ({
@@ -544,6 +549,7 @@ export class KnowledgeSync {
       version: meta.version,
       updatedAt: meta.updatedAt,
       deleted: meta.deleted,
+      synced: this.fileDocs.has(path) && this.fileDocs.get(path)!.content !== undefined,
     })).filter(f => !f.deleted);
   }
 

package/src/peer-manager.ts

@@ -719,9 +719,15 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         debug("peer", `connectToChannel(${nodeId}): self-connection, will not reconnect`);
         return;
       }
-      // Don't reconnect warm-up pruned channels
-      if (ev.reason === "warm-up pruned") {
-        debug("peer", `connectToChannel(${nodeId}): warm-up pruned, will not reconnect`);
+      // Don't reconnect deliberate closures that shouldn't trigger reconnection
+      const skipReasons = ["warm-up pruned", "route switch", "replaced by new connection"];
+      if (skipReasons.includes(ev.reason)) {
+        debug("peer", `connectToChannel(${nodeId}): ${ev.reason}, will not reconnect`);
+        return;
+      }
+      // Don't reconnect when peer approval was denied — retrying is futile
+      if (ev.code === 4005) {
+        debug("peer", `connectToChannel(${nodeId}): approval denied, will not reconnect`);
         return;
       }
       // Record close code for adaptive backoff

package/src/sentinel.ts

@@ -177,7 +177,7 @@ function buildCapabilities(): NodeCapabilities {
 }
 
 function connectToPeer(peer: { nodeId: string; url: string }) {
-  const ws = new WsWebSocket(peer.url, ["graphql-transport-ws"]);
+  const ws = new WebSocket(peer.url, ["graphql-transport-ws"]);
   const e2eeOpts: ConnectionE2eeOptions = {
     e2ee: config.e2ee,
     compression: config.compression,