clawmatrix 0.2.4 → 0.2.6

package/package.json

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

package/src/compat.ts

@@ -6,6 +6,7 @@
 
 import { spawn as cpSpawn } from "node:child_process";
 import { readFile, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
 
 export interface SpawnResult {
   exitCode: number;
@@ -97,8 +98,8 @@ let ptyModule: {
 function loadPty() {
   if (ptyModule !== undefined) return ptyModule;
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    ptyModule = require("node-pty");
+    const req = createRequire(import.meta.url);
+    ptyModule = req("node-pty");
   } catch {
     ptyModule = null;
   }

package/src/connection.ts

@@ -29,6 +29,8 @@ const HEARTBEAT_BASE = 12_000;
 const HEARTBEAT_JITTER = 6_000;
 const HEARTBEAT_TIMEOUT_COUNT = 3;
 const AUTH_TIMEOUT = 10_000;
+/** Extended timeout when server signals approval is pending (must survive human review). */
+const AUTH_PENDING_TIMEOUT = 1_200_000; // 20 minutes
 
 export type ConnectionRole = "inbound" | "outbound";
 
@@ -287,7 +289,14 @@ export class Connection extends EventEmitter<ConnectionEvents> {
         this.clearAuthTimer();
 
         if (this.deferAuthOk) {
-          // Don't send auth_ok yet — wait for completeAuth() after approval
+          // Don't send auth_ok yet — wait for completeAuth() after approval.
+          // Signal the outbound that auth is pending so it extends its timer
+          // instead of timing out after AUTH_TIMEOUT (10s).
+          if (this.sessionKey) {
+            this.send({ type: "auth_pending", from: this.nodeId, timestamp: Date.now() } as AnyClusterFrame);
+          } else {
+            this.sendRaw({ p: 1 });
+          }
           this.emit("authenticated", this.remoteCapabilities);
           return;
         }
@@ -325,6 +334,8 @@ export class Connection extends EventEmitter<ConnectionEvents> {
       this.clearAuthTimer();
 
       if (this.deferAuthOk) {
+        // Signal the outbound that auth is pending (legacy plaintext path)
+        this.sendRaw({ p: 1 });
         this.emit("authenticated", this.remoteCapabilities);
       } else {
         this.sendAuthOkAndStart();
@@ -379,6 +390,19 @@ export class Connection extends EventEmitter<ConnectionEvents> {
         return;
       }
 
+      // auth_pending: server verified HMAC but auth_ok is deferred (peer approval).
+      // Extend the auth timer so the connection survives while waiting for human approval.
+      if (frame.type === "auth_pending" || (frame.p === 1 && !frame.type)) {
+        debug("auth", `Received auth_pending from server, extending auth timeout to ${AUTH_PENDING_TIMEOUT}ms`);
+        this.clearAuthTimer();
+        this.authTimer = setTimeout(() => {
+          if (!this.authenticated) {
+            this.close(4003, "auth pending timeout");
+          }
+        }, AUTH_PENDING_TIMEOUT);
+        return;
+      }
+
       // auth_ok (decrypted from binary envelope, or plaintext legacy)
       if (frame.type === "auth_ok") {
         const ok = frame as AuthOk;

package/src/handoff.ts

@@ -137,6 +137,10 @@ export class HandoffManager {
       throw new Error(`No reachable agent for target "${target}"`);
     }
 
+    if (route.nodeId === this.config.nodeId) {
+      throw new Error(`Target "${target}" resolves to self (${this.config.nodeId}). Cannot handoff to own node.`);
+    }
+
     return this.sendHandoff(route.nodeId, target, task, context, MAX_RETRIES, options?.onStream);
   }
 

package/src/identity.ts

@@ -26,6 +26,7 @@
  * ECDH exchange with the peer's key.
  */
 
+import { createPrivateKey } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import {
@@ -82,7 +83,6 @@ export function loadOrCreateIdentity(stateDir: string): KeyPair {
 
 /** Reconstruct a KeyPair from serialized base64 strings. */
 function keyPairFromSerialized(publicKeyB64: string, privateKeyB64: string): KeyPair {
-  const { createPrivateKey } = require("node:crypto");
   const publicKey = Buffer.from(publicKeyB64, "base64");
   const privateKey = Buffer.from(privateKeyB64, "base64");
 

package/src/index.ts

@@ -467,7 +467,9 @@ const plugin = {
         try {
           const runtime = getClusterRuntime();
           const allPeers = runtime.peerManager.router.getAllPeers();
-          respond(true, mergeSentinelPeers(allPeers, runtime));
+          const filtered = mergeSentinelPeers(allPeers, runtime)
+            .filter((p) => (p as { nodeId: string }).nodeId !== config.nodeId);
+          respond(true, filtered);
         } catch {
           respond(true, []);
         }
@@ -633,7 +635,8 @@ const plugin = {
     api.on("before_prompt_build", () => {
       try {
         const runtime = getClusterRuntime();
-        const peerCount = runtime.peerManager.router.getAllPeers().length;
+        const peerCount = runtime.peerManager.router.getAllPeers()
+          .filter((p) => p.nodeId !== config.nodeId).length;
 
         // Rebuild system context only when peer count changes
         if (peerCount !== cachedPeerCount) {
@@ -643,7 +646,7 @@ const plugin = {
             lines.push("[ClawMatrix] No peers online. Use cluster_peers to check cluster status.");
           } else {
             lines.push(
-              `[ClawMatrix Cluster] node="${config.nodeId}"${config.tags.length ? ` tags=${config.tags.join(",")}` : ""}`,
+              `[ClawMatrix Cluster] YOU ARE node="${config.nodeId}"${config.tags.length ? ` tags=${config.tags.join(",")}` : ""}. This is YOUR identity — never target yourself with cluster tools.`,
               ...(config.agents.length > 0 ? [`Role: ${config.agents[0]!.description}`] : []),
               `${peerCount} remote peer(s) online. Use cluster_peers to see topology, agents, and models.`,
               "Prefer cluster_tool for device-specific tools (screenshot, battery, etc.); cluster_exec/read/write for file/shell ops; cluster_handoff for complex multi-step tasks.",

package/src/peer-manager.ts

@@ -28,6 +28,23 @@ import type { KeyPair } from "./crypto.ts";
 const RECONNECT_BASE = 1_000;
 const RECONNECT_MAX = 60_000;
 
+/** Classify WebSocket close code into a human-readable reason. */
+function classifyCloseReason(code: number, reason: string): string {
+  if (reason) return reason;
+  switch (code) {
+    case 1006: return "unreachable (node may be down)";
+    case 1000: return "normal close";
+    case 1001: return "peer going away";
+    case 1002: return "protocol error";
+    case 1003: return "unsupported data";
+    case 1008: return "policy violation";
+    case 1011: return "server error";
+    case 4001: return "auth failed";
+    case 4003: return "auth timeout";
+    default: return `close code ${code}`;
+  }
+}
+
 /** Check if an IP is a loopback address (IPv4 127.x or IPv6 ::1). */
 function isLoopback(ip?: string): boolean {
   if (!ip) return false;
@@ -324,24 +341,27 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     });
 
     let reconnectScheduled = false;
+    let lastError: string | undefined;
     const tryReconnect = () => {
       if (!reconnectScheduled) {
         reconnectScheduled = true;
-        this.scheduleReconnect(peer);
+        this.scheduleReconnect(peer, lastError);
       }
     };
 
     ws.addEventListener("error", (ev) => {
-      debug("peer", `connectToPeer(${peer.nodeId}): ws error: ${(ev as ErrorEvent).message ?? "unknown"}`);
+      lastError = (ev as ErrorEvent).message || undefined;
       tryReconnect();
     });
     ws.addEventListener("close", (ev) => {
-      debug("peer", `connectToPeer(${peer.nodeId}): ws close code=${ev.code} reason=${ev.reason}`);
+      if (!lastError) {
+        lastError = classifyCloseReason(ev.code, ev.reason);
+      }
       tryReconnect();
     });
   }
 
-  private scheduleReconnect(peer: PeerConfig) {
+  private scheduleReconnect(peer: PeerConfig, reason?: string) {
     if (this.stopped) {
       debug("peer", `scheduleReconnect(${peer.nodeId}): skipped (stopped)`);
       return;
@@ -351,7 +371,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     const attempt = this.reconnectAttempts.get(peer.nodeId) ?? 0;
     const delay = Math.min(RECONNECT_BASE * 2 ** attempt, RECONNECT_MAX);
     this.reconnectAttempts.set(peer.nodeId, attempt + 1);
-    debug("peer", `scheduleReconnect(${peer.nodeId}): attempt=${attempt} delay=${delay}ms`);
+    const tag = reason ? ` reason="${reason}"` : "";
+    debug("peer", `scheduleReconnect(${peer.nodeId}): attempt=${attempt} delay=${delay}ms${tag}`);
 
     const timer = setTimeout(() => {
       this.reconnectTimers.delete(peer.nodeId);
@@ -366,6 +387,14 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     // Peer's persistent public key for TOFU identity binding
     const peerPublicKey = conn.remoteIdentityKey ?? undefined;
 
+    // Prevent self-connection: if outbound connection authenticated as our own nodeId
+    // (e.g. peer URL accidentally points to self), close immediately.
+    if (conn.role === "outbound" && nodeId === this.config.nodeId) {
+      debug("peer", `Self-connection detected (outbound to ${nodeId}), closing`);
+      conn.close(4002, "self-connection");
+      return;
+    }
+
     // Peer approval check (inbound only — outbound peers are explicitly configured)
     // Skip approval for same-nodeId connections from localhost (local clients
     // like Mac desktop app / iOS simulator). An attacker would need to already
@@ -519,6 +548,9 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
   // ── Message handling ───────────────────────────────────────────
   private onFrame(frame: AnyClusterFrame, from: Connection) {
+    // Ignore self-echo: frames with our own nodeId that were relayed back to us
+    if (frame.from === this.config.nodeId) return;
+
     // Validate from field: must be the direct peer or a known node (relayed)
     if (frame.from && frame.from !== from.remoteNodeId && !this.router.getRoute(frame.from)) {
       debug("peer", `dropped frame type=${frame.type} from=${frame.from}: unknown origin (via ${from.remoteNodeId})`);
@@ -670,6 +702,9 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
           changed = true;
         }
       } else {
+        // Skip if the remote peer only knows about this node through us —
+        // using them as relay would create a routing loop.
+        if (peer.reachableVia === this.config.nodeId) continue;
         const existing = this.router.getRoute(peer.nodeId);
         if (!existing) changed = true;
         this.router.addRelayPeer(peer, from.remoteNodeId!);

package/src/router.ts

@@ -97,6 +97,9 @@ export class Router {
     const relayRoute = this.routes.get(viaNodeId);
     const estimatedLatency = (relayRoute?.latencyMs ?? 0) + (peer.latencyMs ?? 0);
 
+    // Don't overwrite a better relay route with a worse one (allow equal for capability updates)
+    if (existing?.reachableVia && existing.latencyMs < estimatedLatency) return;
+
     this.routes.set(peer.nodeId, {
       nodeId: peer.nodeId,
       agents: peer.agents,
@@ -164,6 +167,8 @@ export class Router {
 
     let candidates: RouteEntry[] = [];
     for (const entry of this.routes.values()) {
+      // Skip self — never resolve to our own node
+      if (entry.nodeId === this.nodeId) continue;
       if (isTagQuery) {
         if (entry.agents.some((a) => a.tags.includes(tag!)) || entry.tags.includes(tag!)) {
           candidates.push(entry);
@@ -178,7 +183,7 @@ export class Router {
     // Fallback: if no agent ID or tag matched, try matching by nodeId
     if (candidates.length === 0 && !isTagQuery) {
       const byNode = this.routes.get(target);
-      if (byNode) candidates.push(byNode);
+      if (byNode && byNode.nodeId !== this.nodeId) candidates.push(byNode);
     }
 
     if (candidates.length === 0) return undefined;
@@ -201,6 +206,8 @@ export class Router {
       const tag = target.slice(5);
       const candidates: RouteEntry[] = [];
       for (const entry of this.routes.values()) {
+        // Skip self — never resolve to our own node
+        if (entry.nodeId === this.nodeId) continue;
         if (entry.tags.includes(tag)) {
           candidates.push(entry);
         }
@@ -215,6 +222,8 @@ export class Router {
       });
       return candidates[0];
     }
+    // Skip self — never resolve to our own node
+    if (target === this.nodeId) return undefined;
     return this.routes.get(target);
   }
 

package/src/tool-proxy.ts

@@ -180,7 +180,7 @@ export class ToolProxy {
     to: string,
     payload: ToolProxyResponse["payload"],
   ) {
-    this.peerManager.sendTo(to, {
+    const sent = this.peerManager.sendTo(to, {
       type: "tool_res",
       id,
       from: this.config.nodeId,
@@ -188,6 +188,9 @@ export class ToolProxy {
       timestamp: Date.now(),
       payload,
     } as ToolProxyResponse);
+    if (!sent) {
+      this.logger.warn(`[clawmatrix] Tool response dropped: id=${id} to="${to}" (no route)`);
+    }
   }
 
   // ── Gateway tool invocation ────────────────────────────────────