clawmatrix 0.2.6 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.2.6",
+  "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

@@ -82,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;
 
@@ -190,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;
 
@@ -477,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/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();
@@ -477,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));
@@ -520,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);

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) {

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);
     }
   }