clawmatrix 0.2.5 → 0.2.7

package/package.json

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

package/src/acp-proxy.ts

@@ -1614,7 +1614,7 @@ export class AcpProxy {
   }
 
   /** Built-in ACP agent commands (same as OpenClaw's acpx backend). */
-  private static readonly BUILTIN_ACP_COMMANDS: Record<string, string[]> = {
+  static readonly BUILTIN_ACP_COMMANDS: Record<string, string[]> = {
     claude: ["npx", "-y", "@zed-industries/claude-agent-acp"],
     codex: ["npx", "-y", "@zed-industries/codex-acp"],
     gemini: ["gemini"],
@@ -1622,6 +1622,69 @@ export class AcpProxy {
     pi: ["npx", "-y", "pi-acp"],
   };
 
+  /** Human-readable descriptions for built-in ACP agents. */
+  private static readonly BUILTIN_ACP_DESCRIPTIONS: Record<string, string> = {
+    claude: "Claude Code",
+    codex: "OpenAI Codex CLI",
+    gemini: "Gemini CLI",
+    opencode: "OpenCode",
+    pi: "Pi",
+  };
+
+  /** Binary names to check for each agent (may differ from agent id). */
+  private static readonly AGENT_BINARY_NAMES: Record<string, string> = {
+    claude: "claude",
+    codex: "codex",
+    gemini: "gemini",
+    opencode: "opencode",
+    pi: "pi",
+  };
+
+  /**
+   * Auto-detect which ACP agents are installed by checking if their binaries
+   * exist in PATH. Also checks config-defined custom commands.
+   */
+  static async detectAvailableAgents(
+    configCommands?: Record<string, string[]>,
+  ): Promise<import("./types.ts").AcpAgentInfo[]> {
+    const detected: import("./types.ts").AcpAgentInfo[] = [];
+    const whichCmd = process.platform === "win32" ? "where.exe" : "which";
+
+    // Check built-in agents
+    const checks = Object.keys(AcpProxy.BUILTIN_ACP_COMMANDS).map(async (agent) => {
+      const binary = AcpProxy.AGENT_BINARY_NAMES[agent] ?? agent;
+      try {
+        const proc = spawnProcess([whichCmd, binary], { stdout: "ignore", stderr: "ignore" });
+        const code = await proc.exited;
+        if (code === 0) {
+          detected.push({
+            id: agent,
+            description: AcpProxy.BUILTIN_ACP_DESCRIPTIONS[agent] ?? agent,
+          });
+        }
+      } catch { /* binary not found */ }
+    });
+
+    // Check custom config commands
+    if (configCommands) {
+      for (const [agent, cmd] of Object.entries(configCommands)) {
+        if (agent in AcpProxy.BUILTIN_ACP_COMMANDS) continue; // already checked above
+        checks.push((async () => {
+          try {
+            const proc = spawnProcess([whichCmd, cmd[0]!], { stdout: "ignore", stderr: "ignore" });
+            const code = await proc.exited;
+            if (code === 0) {
+              detected.push({ id: agent, description: agent });
+            }
+          } catch { /* binary not found */ }
+        })());
+      }
+    }
+
+    await Promise.all(checks);
+    return detected;
+  }
+
   private resolveCommand(agent: string): string[] {
     // Check config overrides first
     const commands = this.config.acp?.commands;

package/src/cluster-service.ts

@@ -165,6 +165,18 @@ export class ClusterRuntime {
       }
     }
 
+    // Auto-detect ACP agents if ACP is enabled but no agents are explicitly configured
+    if (this.acpProxy && this.config.acp?.enabled && (!this.config.acp.agents || this.config.acp.agents.length === 0)) {
+      AcpProxy.detectAvailableAgents(this.config.acp.commands).then((detected) => {
+        if (detected.length > 0) {
+          this.logger.info(`[clawmatrix] Auto-detected ACP agents: ${detected.map((a) => a.id).join(", ")}`);
+          this.peerManager.updateAcpAgents(detected);
+        }
+      }).catch((err) => {
+        this.logger.error(`[clawmatrix] ACP agent detection failed: ${err}`);
+      });
+    }
+
     // Start subsystems
     this.peerManager.start();
     this.modelProxy.start();

package/src/compat.ts

@@ -118,12 +118,38 @@ export function spawnPty(
   const pty = loadPty();
   if (!pty) throw new Error("node-pty is not available — install it with: npm install node-pty");
 
+  // Filter out undefined values from env — node-pty's C code (posix_spawnp)
+  // cannot handle undefined entries and will fail silently.
+  const baseEnv = process.env as Record<string, string | undefined>;
+  const mergedEnv: Record<string, string> = {};
+  for (const [k, v] of Object.entries(baseEnv)) {
+    if (v !== undefined) mergedEnv[k] = v;
+  }
+  if (opts.env) {
+    for (const [k, v] of Object.entries(opts.env)) {
+      if (v !== undefined) mergedEnv[k] = v;
+    }
+  }
+
+  // Validate cwd exists to give a clear error instead of cryptic posix_spawnp failure
+  if (opts.cwd) {
+    try {
+      const fs = require("node:fs");
+      if (!fs.existsSync(opts.cwd)) {
+        throw new Error(`cwd does not exist: ${opts.cwd}`);
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message.startsWith("cwd")) throw e;
+      // fs check failed, proceed anyway
+    }
+  }
+
   const proc = pty.spawn(shell, args, {
     name: "xterm-256color",
     cols: opts.cols ?? 80,
     rows: opts.rows ?? 24,
     cwd: opts.cwd,
-    env: opts.env ? { ...process.env, ...opts.env } as Record<string, string> : process.env as Record<string, string>,
+    env: mergedEnv,
   });
 
   return {

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";
 
@@ -80,6 +82,8 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private pendingNonce: string | null = null;
   private closed = false;
   private lastPingSentAt = 0;
+  /** Timestamp of the last frame received from the remote side. */
+  private lastReceivedAt = 0;
   /** Exponential moving average of heartbeat RTT in milliseconds. */
   latencyMs = 0;
 
@@ -188,6 +192,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private async onRawMessage(data: unknown) {
     const str = typeof data === "string" ? data : String(data);
     if (!str.length) return;
+    this.lastReceivedAt = Date.now();
 
     let frame: AnyClusterFrame | undefined;
 
@@ -287,7 +292,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 +337,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 +393,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;
@@ -453,24 +480,54 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   }
 
   // ── Heartbeat ──────────────────────────────────────────────────
+  /** Maximum silence duration before declaring the connection dead. */
+  private static readonly RECEIVE_TIMEOUT = HEARTBEAT_BASE * HEARTBEAT_TIMEOUT_COUNT + HEARTBEAT_JITTER * HEARTBEAT_TIMEOUT_COUNT;
+
   private startHeartbeat() {
+    this.lastReceivedAt = Date.now();
     const scheduleNext = () => {
       const interval = HEARTBEAT_BASE + Math.random() * HEARTBEAT_JITTER;
       this.heartbeatTimer = setTimeout(() => {
         if (this.closed) return;
+
+        // Watchdog: if no data received for a long time, the connection is dead
+        // regardless of what the heartbeat ping/pong state says.
+        const silenceMs = Date.now() - this.lastReceivedAt;
+        if (this.lastReceivedAt > 0 && silenceMs > Connection.RECEIVE_TIMEOUT) {
+          debug("heartbeat", `No data received for ${Math.round(silenceMs / 1000)}s from ${this.remoteNodeId ?? "unknown"}, closing`);
+          this.close(4002, "receive timeout");
+          return;
+        }
+
         // Increment before checking: this ping is about to be sent and
         // counts as outstanding until a pong arrives.
         this.missedPongs++;
         if (this.missedPongs >= HEARTBEAT_TIMEOUT_COUNT) {
+          debug("heartbeat", `${HEARTBEAT_TIMEOUT_COUNT} missed pongs from ${this.remoteNodeId ?? "unknown"}, closing`);
           this.close(4002, "heartbeat timeout");
           return;
         }
-        this.lastPingSentAt = Date.now();
-        this.send({
-          type: "ping",
-          from: this.nodeId,
-          timestamp: this.lastPingSentAt,
-        } as AnyClusterFrame);
+
+        // Send ping — wrapped in try-catch to prevent breaking the heartbeat chain.
+        // If send fails, the connection is dead; close it.
+        try {
+          if (this.transport.readyState !== WebSocket.OPEN) {
+            debug("heartbeat", `Transport not open (state=${this.transport.readyState}) for ${this.remoteNodeId ?? "unknown"}, closing`);
+            this.close(4002, "transport closed");
+            return;
+          }
+          this.lastPingSentAt = Date.now();
+          this.send({
+            type: "ping",
+            from: this.nodeId,
+            timestamp: this.lastPingSentAt,
+          } as AnyClusterFrame);
+        } catch (err) {
+          debug("heartbeat", `Ping send failed for ${this.remoteNodeId ?? "unknown"}: ${err}`);
+          this.close(4002, "ping send failed");
+          return;
+        }
+
         scheduleNext();
       }, interval);
     };

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/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

@@ -132,6 +132,16 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     this.approvalManager = new PeerApprovalManager(approvalConfig, stateDir);
   }
 
+  /** Update locally advertised ACP agents and re-broadcast to all peers. */
+  updateAcpAgents(agents: import("./types.ts").AcpAgentInfo[]) {
+    this.localCapabilities.acpAgents = agents;
+    this.router.updateLocalAcpAgents(agents);
+    // Re-sync all connected peers so they learn the updated capabilities
+    for (const conn of this.router.getDirectConnections()) {
+      this.sendPeerSync(conn);
+    }
+  }
+
   // ── Lifecycle ──────────────────────────────────────────────────
   async start() {
     await this.approvalManager.load();
@@ -387,6 +397,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
@@ -469,10 +487,22 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
   private completePeerJoin(conn: Connection, caps: NodeCapabilities) {
     const nodeId = conn.remoteNodeId!;
+
+    // If there's an existing connection for this nodeId (e.g. peer reconnected
+    // while old TCP hadn't closed yet), close it AFTER overwriting the route so
+    // the stale-close guard in onPeerDisconnected correctly skips cleanup.
+    const oldRoute = this.router.getRoute(nodeId);
+    const oldConn = oldRoute?.connection;
+
     // Same-nodeId 连接（如 Mac/iOS 桌面客户端）也正常注册路由，
     // 使得 sendTo(nodeId) 能将响应帧路由回客户端连接。
     this.router.addDirectPeer(nodeId, conn, caps);
 
+    if (oldConn && oldConn !== conn && oldConn.isOpen) {
+      debug("peer", `completePeerJoin(${nodeId}): closing replaced connection`);
+      oldConn.close(1000, "replaced by new connection");
+    }
+
     conn.on("message", (frame) => this.onFrame(frame, conn));
     conn.on("latency", (ms) => this.router.updateLatency(nodeId, ms));
     conn.on("close", () => this.onPeerDisconnected(conn));
@@ -512,6 +542,16 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     const nodeId = conn.remoteNodeId;
     if (!nodeId) return;
 
+    // Guard: only remove the peer if THIS connection is still the active one
+    // in the router. When a peer reconnects, the new connection replaces the
+    // old one in the route table. If the old connection's close event fires
+    // afterwards, it must NOT remove the new connection's route.
+    const currentRoute = this.router.getRoute(nodeId);
+    if (currentRoute?.connection && currentRoute.connection !== conn) {
+      debug("peer", `onPeerDisconnected(${nodeId}): stale connection close, current route has different connection — skipping cleanup`);
+      return;
+    }
+
     // Same-nodeId 本地客户端断开：仅清理路由，不广播 peer_leave
     if (nodeId === this.config.nodeId) {
       this.router.removePeer(nodeId);
@@ -540,6 +580,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})`);
@@ -691,6 +734,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

@@ -52,6 +52,11 @@ export class Router {
     this.rotateTimer = setInterval(() => this.rotateSeenFrames(), ROTATE_INTERVAL);
   }
 
+  /** Update locally advertised ACP agents (used after auto-detection). */
+  updateLocalAcpAgents(agents: AcpAgentInfo[]) {
+    this.localAcpAgents = agents;
+  }
+
   /** Stop periodic cleanup. Call on shutdown. */
   destroy() {
     if (this.rotateTimer) {
@@ -97,6 +102,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 +172,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 +188,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 +211,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 +227,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/terminal.ts

@@ -204,13 +204,15 @@ export class TerminalManager {
         payload: { success: true, sessionId },
       } as TerminalOpenResponse);
     } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      debug("terminal", `PTY spawn failed: shell=${shell} cwd=${frame.payload.cwd ?? "(default)"} error=${errMsg}`);
       this.peerManager.sendTo(frame.from, {
         type: "terminal_open_res",
         id: frame.id,
         from: nodeId,
         to: frame.from,
         timestamp: Date.now(),
-        payload: { success: false, error: `Failed to spawn PTY: ${err instanceof Error ? err.message : String(err)}` },
+        payload: { success: false, error: `Failed to spawn PTY (shell=${shell}): ${errMsg}` },
       } as TerminalOpenResponse);
     }
   }

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 ────────────────────────────────────