clawmatrix 0.3.1 → 0.4.1

package/src/peer-manager.ts

@@ -91,8 +91,19 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   private localCapabilities: NodeCapabilities;
   private httpServer: Server | null = null;
   private wss: WebSocketServer | null = null;
+  /** Reconnect timers keyed by `nodeId|url` for per-channel reconnection. */
   private reconnectTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private reconnectAttempts = new Map<string, number>();
+  /** Track which nodeIds have already completed the full peer join (for multi-channel). */
+  private joinedPeers = new Set<string>();
+  /** All configured URLs per peer (for multi-URL peers). */
+  private peerUrls = new Map<string, string[]>();
+  /** Currently active URL per peer. */
+  private activeUrls = new Map<string, string>();
+  /** Last probe latency per URL (ms). */
+  private urlProbeLatencies = new Map<string, number>();
+  /** Route probe interval timer. */
+  private probeTimer: ReturnType<typeof setInterval> | null = null;
   /** Deferred disconnect timers — grace period before broadcasting peer_leave. */
   private disconnectGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private stopped = false;
@@ -191,10 +202,16 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     for (const peer of this.config.peers) {
       this.connectToPeer(peer);
     }
+    // Start route probing for peers with multiple URLs
+    this.startRouteProbing();
   }
 
   async stop() {
     this.stopped = true;
+    if (this.probeTimer) {
+      clearInterval(this.probeTimer);
+      this.probeTimer = null;
+    }
     if (this.gossipDebounceTimer) {
       clearTimeout(this.gossipDebounceTimer);
       this.gossipDebounceTimer = null;
@@ -221,18 +238,187 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       conn.close(1000, "shutdown");
     }
 
+    this.closeServers();
+
+    this.rateLimiter.destroy();
+    this.approvalManager.destroy();
+    this.router.destroy();
+    this.joinedPeers.clear();
+  }
+
+  /** Force-stop without broadcasting or waiting — used when graceful stop times out. */
+  forceStop() {
+    this.stopped = true;
+    if (this.probeTimer) { clearInterval(this.probeTimer); this.probeTimer = null; }
+    for (const timer of this.reconnectTimers.values()) clearTimeout(timer);
+    this.reconnectTimers.clear();
+    for (const [, timer] of this.disconnectGraceTimers) clearTimeout(timer);
+    this.disconnectGraceTimers.clear();
+    if (this.gossipDebounceTimer) {
+      clearTimeout(this.gossipDebounceTimer);
+      this.gossipDebounceTimer = null;
+    }
+    for (const conn of this.router.getDirectConnections()) {
+      try { conn.close(1000, "shutdown"); } catch { /* best effort */ }
+    }
+    this.closeServers();
+    this.rateLimiter.destroy();
+    this.approvalManager.destroy();
+    this.router.destroy();
+    this.joinedPeers.clear();
+  }
+
+  private closeServers() {
     if (this.wss) {
       this.wss.close();
       this.wss = null;
     }
     if (this.httpServer) {
+      // Force-close all keep-alive connections so the port is released immediately
+      const server = this.httpServer as typeof this.httpServer & { closeAllConnections?: () => void };
+      if (typeof server.closeAllConnections === "function") {
+        server.closeAllConnections();
+      }
       this.httpServer.close();
       this.httpServer = null;
     }
+  }
 
-    this.rateLimiter.destroy();
-    this.approvalManager.destroy();
-    this.router.destroy();
+  // ── Route probing (for multi-URL peers) ──────────────────────────
+  private static readonly PROBE_INTERVAL = 3_600_000; // 1 hour
+  /** Minimum improvement ratio to trigger a route switch. */
+  private static readonly SWITCH_THRESHOLD = 0.7; // new must be ≤70% of current
+
+  private startRouteProbing() {
+    // Only probe if any peer has multiple URLs
+    const hasMultiUrl = [...this.peerUrls.values()].some((urls) => urls.length > 1);
+    if (!hasMultiUrl) return;
+
+    this.probeTimer = setInterval(() => this.probeAllRoutes(), PeerManager.PROBE_INTERVAL);
+  }
+
+  private async probeAllRoutes() {
+    for (const [nodeId, urls] of this.peerUrls) {
+      if (urls.length <= 1) continue;
+      const activeUrl = this.activeUrls.get(nodeId);
+      for (const url of urls) {
+        if (url === activeUrl) continue;
+        // Probe non-active URLs
+        const latency = await this.probeUrl(url);
+        if (latency !== null) {
+          this.urlProbeLatencies.set(url, latency);
+        }
+      }
+      // Also record active connection's real latency
+      if (activeUrl) {
+        const route = this.router.getRoute(nodeId);
+        if (route && route.latencyMs > 0) {
+          this.urlProbeLatencies.set(activeUrl, route.latencyMs);
+        }
+      }
+      // Evaluate if we should switch
+      this.evaluateRouteSwitch(nodeId);
+    }
+  }
+
+  /**
+   * Probe a URL by measuring HTTP response time (WS server also serves HTTP).
+   * Returns latency in ms, or null if unreachable.
+   */
+  private async probeUrl(wsUrl: string): Promise<number | null> {
+    try {
+      const httpUrl = wsUrl.replace(/^ws(s?):\/\//, "http$1://");
+      const start = Date.now();
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 5_000);
+      try {
+        const res = await fetch(httpUrl, {
+          method: "HEAD",
+          signal: controller.signal,
+          // @ts-ignore — Node.js 18+ supports this
+          keepalive: false,
+        });
+        clearTimeout(timeout);
+        if (res.ok || res.status === 200) {
+          return Date.now() - start;
+        }
+        return null;
+      } catch {
+        clearTimeout(timeout);
+        return null;
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  /** Check if we should switch to a better URL for a peer. */
+  private evaluateRouteSwitch(nodeId: string) {
+    const urls = this.peerUrls.get(nodeId);
+    const activeUrl = this.activeUrls.get(nodeId);
+    if (!urls || !activeUrl || urls.length <= 1) return;
+
+    const currentLatency = this.urlProbeLatencies.get(activeUrl);
+    if (!currentLatency || currentLatency <= 0) return;
+
+    // Find best alternative
+    let bestUrl: string | undefined;
+    let bestLatency = Infinity;
+    for (const url of urls) {
+      if (url === activeUrl) continue;
+      const lat = this.urlProbeLatencies.get(url);
+      if (lat !== undefined && lat < bestLatency) {
+        bestLatency = lat;
+        bestUrl = url;
+      }
+    }
+
+    if (!bestUrl || bestLatency >= currentLatency * PeerManager.SWITCH_THRESHOLD) return;
+
+    // Check if there are active tasks — don't switch mid-task
+    if (this.hasActiveTasks(nodeId)) {
+      debug("probe", `${nodeId}: better route found (${activeUrl} ${currentLatency}ms → ${bestUrl} ${bestLatency}ms) but has active tasks, deferring`);
+      return;
+    }
+
+    debug("probe", `${nodeId}: switching route ${activeUrl} ${currentLatency}ms → ${bestUrl} ${bestLatency}ms`);
+    this.switchRoute(nodeId, bestUrl);
+  }
+
+  /** Callback to check if there are active tasks involving a peer. Set by ClusterRuntime. */
+  private activeTaskChecker: ((nodeId: string) => boolean) | null = null;
+
+  /** Register a callback to check for active tasks (used to prevent route switches mid-task). */
+  setActiveTaskChecker(checker: (nodeId: string) => boolean) {
+    this.activeTaskChecker = checker;
+  }
+
+  /** Check if there are active tasks involving a peer (handoffs, model requests, etc.). */
+  private hasActiveTasks(nodeId: string): boolean {
+    return this.activeTaskChecker?.(nodeId) ?? false;
+  }
+
+  /** Switch the active route for a peer to a new URL. */
+  private switchRoute(nodeId: string, newUrl: string) {
+    this.activeUrls.set(nodeId, newUrl);
+    // Connect to the new URL — the new connection will authenticate and join
+    // as an additional channel briefly, then we close the old one.
+    const oldRoute = this.router.getRoute(nodeId);
+    const oldConn = oldRoute?.connection;
+
+    this.connectToChannel(nodeId, newUrl);
+
+    // Close the old connection after a short delay (give new connection time to establish)
+    if (oldConn?.isOpen) {
+      setTimeout(() => {
+        // Only close if a new connection has taken over
+        const currentRoute = this.router.getRoute(nodeId);
+        if (currentRoute?.connection && currentRoute.connection !== oldConn) {
+          debug("probe", `${nodeId}: closing old channel after route switch`);
+          oldConn.close(1000, "route switch");
+        }
+      }, 5_000);
+    }
   }
 
   /** Set an HTTP request handler for non-WebSocket requests (e.g. web dashboard). */
@@ -351,26 +537,52 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
   // ── Outbound connections (standard WebSocket) ──────────────────
   private connectToPeer(peer: PeerConfig) {
+    const urls = Array.isArray(peer.url) ? peer.url : [peer.url];
+    this.peerUrls.set(peer.nodeId, urls);
+    // Connect to the first URL (or best known from probes)
+    const bestUrl = this.pickBestUrl(peer.nodeId, urls);
+    this.activeUrls.set(peer.nodeId, bestUrl);
+    this.connectToChannel(peer.nodeId, bestUrl);
+  }
+
+  /** Pick the best URL for a peer based on probe latencies. Falls back to first URL. */
+  private pickBestUrl(nodeId: string, urls: string[]): string {
+    if (urls.length <= 1) return urls[0];
+    let bestUrl = urls[0];
+    let bestLatency = Infinity;
+    for (const url of urls) {
+      const lat = this.urlProbeLatencies.get(url);
+      if (lat !== undefined && lat < bestLatency) {
+        bestLatency = lat;
+        bestUrl = url;
+      }
+    }
+    return bestUrl;
+  }
+
+  /** Connect a single channel (URL) for a peer. */
+  private connectToChannel(nodeId: string, url: string) {
     if (this.stopped) {
-      debug("peer", `connectToPeer(${peer.nodeId}): skipped (stopped)`);
+      debug("peer", `connectToChannel(${nodeId}): skipped (stopped)`);
       return;
     }
 
-    const attempt = this.reconnectAttempts.get(peer.nodeId) ?? 0;
-    debug("peer", `connectToPeer(${peer.nodeId}): attempt=${attempt} url=${peer.url}`);
+    const channelKey = `${nodeId}|${url}`;
+    const attempt = this.reconnectAttempts.get(channelKey) ?? 0;
+    debug("peer", `connectToChannel(${nodeId}): attempt=${attempt} url=${url}`);
 
     // Use a common WS subprotocol for traffic disguise
     let ws: WebSocket;
     try {
-      ws = new WebSocket(peer.url, ["graphql-transport-ws"]);
+      ws = new WebSocket(url, ["graphql-transport-ws"]);
     } catch (err) {
-      debug("peer", `connectToPeer(${peer.nodeId}): WebSocket constructor threw: ${err}`);
-      this.scheduleReconnect(peer);
+      debug("peer", `connectToChannel(${nodeId}): WebSocket constructor threw: ${err}`);
+      this.scheduleChannelReconnect(nodeId, url);
       return;
     }
 
     ws.addEventListener("open", () => {
-      debug("peer", `connectToPeer(${peer.nodeId}): ws open`);
+      debug("peer", `connectToChannel(${nodeId}): ws open url=${url}`);
       const conn = new Connection(
         ws,
         "outbound",
@@ -382,8 +594,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       conn.bindWebSocket(ws);
 
       conn.on("authenticated", (caps) => {
-        debug("peer", `connectToPeer(${peer.nodeId}): authenticated`);
-        this.reconnectAttempts.delete(peer.nodeId);
+        debug("peer", `connectToChannel(${nodeId}): authenticated url=${url}`);
+        this.reconnectAttempts.delete(channelKey);
         this.onPeerAuthenticated(conn, caps);
       });
 
@@ -397,7 +609,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     const tryReconnect = () => {
       if (!reconnectScheduled) {
         reconnectScheduled = true;
-        this.scheduleReconnect(peer, lastError);
+        this.scheduleChannelReconnect(nodeId, url, lastError);
       }
     };
 
@@ -409,7 +621,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       // Don't reconnect if this was a self-connection (peer URL points to ourselves).
       // Without this guard, outbound detects self → closes → scheduleReconnect → loop.
       if (ev.code === 4002 && ev.reason === "self-connection") {
-        debug("peer", `connectToPeer(${peer.nodeId}): self-connection, will not reconnect`);
+        debug("peer", `connectToChannel(${nodeId}): self-connection, will not reconnect`);
         return;
       }
       if (!lastError) {
@@ -419,24 +631,65 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     });
   }
 
-  private scheduleReconnect(peer: PeerConfig, reason?: string) {
+  private scheduleChannelReconnect(nodeId: string, url: string, reason?: string) {
     if (this.stopped) {
-      debug("peer", `scheduleReconnect(${peer.nodeId}): skipped (stopped)`);
+      debug("peer", `scheduleChannelReconnect(${nodeId}): skipped (stopped)`);
       return;
     }
-    if (this.reconnectTimers.has(peer.nodeId)) return;
+    const channelKey = `${nodeId}|${url}`;
+    if (this.reconnectTimers.has(channelKey)) return;
+
+    const attempt = this.reconnectAttempts.get(channelKey) ?? 0;
+
+    // On first failure, try an alternative URL immediately (failover)
+    if (attempt === 0) {
+      const urls = this.peerUrls.get(nodeId);
+      if (urls && urls.length > 1) {
+        const altUrl = this.pickNextUrl(nodeId, url, urls);
+        if (altUrl && altUrl !== url) {
+          debug("peer", `scheduleChannelReconnect(${nodeId}): failover ${url} → ${altUrl}`);
+          this.activeUrls.set(nodeId, altUrl);
+          this.reconnectAttempts.set(channelKey, attempt + 1);
+          // Connect to alternative immediately, schedule original for later
+          this.connectToChannel(nodeId, altUrl);
+          const timer = setTimeout(() => {
+            this.reconnectTimers.delete(channelKey);
+            // Only reconnect original URL if not already connected
+            if (!this.joinedPeers.has(nodeId)) {
+              this.connectToChannel(nodeId, url);
+            }
+          }, RECONNECT_MAX);
+          this.reconnectTimers.set(channelKey, timer);
+          return;
+        }
+      }
+    }
 
-    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);
+    this.reconnectAttempts.set(channelKey, attempt + 1);
     const tag = reason ? ` reason="${reason}"` : "";
-    debug("peer", `scheduleReconnect(${peer.nodeId}): attempt=${attempt} delay=${delay}ms${tag}`);
+    debug("peer", `scheduleChannelReconnect(${nodeId}): attempt=${attempt} delay=${delay}ms url=${url}${tag}`);
 
     const timer = setTimeout(() => {
-      this.reconnectTimers.delete(peer.nodeId);
-      this.connectToPeer(peer);
+      this.reconnectTimers.delete(channelKey);
+      this.connectToChannel(nodeId, url);
     }, delay);
-    this.reconnectTimers.set(peer.nodeId, timer);
+    this.reconnectTimers.set(channelKey, timer);
+  }
+
+  /** Pick the next best URL to try, excluding the current one. */
+  private pickNextUrl(nodeId: string, currentUrl: string, urls: string[]): string | undefined {
+    let bestUrl: string | undefined;
+    let bestLatency = Infinity;
+    for (const url of urls) {
+      if (url === currentUrl) continue;
+      const lat = this.urlProbeLatencies.get(url) ?? 10_000;
+      if (lat < bestLatency) {
+        bestLatency = lat;
+        bestUrl = url;
+      }
+    }
+    return bestUrl ?? urls.find((u) => u !== currentUrl);
   }
 
   // ── Peer lifecycle ─────────────────────────────────────────────
@@ -536,6 +789,23 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     // Cancel disconnect grace timer if the peer is reconnecting
     const wasInGrace = this.cancelDisconnectGrace(nodeId);
 
+    // Check if this peer already has an active connection (additional channel)
+    const isAdditionalChannel = this.joinedPeers.has(nodeId);
+
+    if (isAdditionalChannel) {
+      // Additional channel — just add to the channel pool, no peer_join broadcast
+      this.router.addChannel(nodeId, conn);
+      conn.on("message", (frame) => this.onFrame(frame, conn));
+      conn.on("latency", () => this.router.updateActiveChannel(nodeId));
+      conn.on("close", () => this.onChannelDisconnected(conn));
+      const channelCount = this.router.getChannelCount(nodeId);
+      debug("peer", `completePeerJoin(${nodeId}): additional channel added (total=${channelCount})`);
+      audit("channel_add", { nodeId, detail: `channels=${channelCount}` });
+      return;
+    }
+
+    // First channel — full join flow
+
     // 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.
@@ -551,9 +821,11 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       oldConn.close(1000, "replaced by new connection");
     }
 
+    this.joinedPeers.add(nodeId);
+
     conn.on("message", (frame) => this.onFrame(frame, conn));
-    conn.on("latency", (ms) => this.router.updateLatency(nodeId, ms));
-    conn.on("close", () => this.onPeerDisconnected(conn));
+    conn.on("latency", () => this.router.updateActiveChannel(nodeId));
+    conn.on("close", () => this.onChannelDisconnected(conn));
 
     this.sendPeerSync(conn);
 
@@ -586,6 +858,25 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     this.emit("peerConnected", nodeId);
   }
 
+  /** Handle a single channel disconnecting (multi-channel aware). */
+  private onChannelDisconnected(conn: Connection) {
+    const nodeId = conn.remoteNodeId;
+    if (!nodeId) return;
+
+    // Remove this channel from the pool
+    const hasRemaining = this.router.removeChannel(nodeId, conn);
+    if (hasRemaining) {
+      // Other channels still alive — just log, no peer_leave
+      const channelCount = this.router.getChannelCount(nodeId);
+      debug("peer", `onChannelDisconnected(${nodeId}): channel lost, ${channelCount} remaining`);
+      audit("channel_remove", { nodeId, detail: `channels=${channelCount}` });
+      return;
+    }
+
+    // Last channel gone — proceed with peer disconnect logic
+    this.onPeerDisconnected(conn);
+  }
+
   private onPeerDisconnected(conn: Connection) {
     const nodeId = conn.remoteNodeId;
     if (!nodeId) return;
@@ -603,6 +894,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     // Same-nodeId 本地客户端断开：仅清理路由，不广播 peer_leave
     if (nodeId === this.config.nodeId) {
       this.router.removePeer(nodeId);
+      this.joinedPeers.delete(nodeId);
       return;
     }
 
@@ -651,6 +943,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
     audit("peer_leave", { nodeId });
     this.router.removePeer(nodeId);
+    this.joinedPeers.delete(nodeId);
 
     // Remove satellite contexts that were only reachable via this peer
     for (let i = this.satelliteContexts.length - 1; i >= 0; i--) {

package/src/router.ts

@@ -30,7 +30,9 @@ export class Router {
   private localToolProxy?: ToolProxyInfo;
   private localAcpAgents?: AcpAgentInfo[];
   private routes = new Map<string, RouteEntry>();
-  private connections = new Map<string, Connection>(); // nodeId → direct connection
+  private connections = new Map<string, Connection>(); // nodeId → active (best) direct connection
+  /** All live channels per nodeId (multi-channel support). */
+  private channels = new Map<string, Set<Connection>>();
   /** Double-map dedup: current window + previous window. Rotated periodically. */
   private seenCurrent = new Map<string, true>();
   private seenPrevious = new Map<string, true>();
@@ -128,6 +130,7 @@ export class Router {
     this.seenCurrent.clear();
     this.seenPrevious.clear();
     this.failedRequests.clear();
+    this.channels.clear();
   }
 
   // ── Route table management ─────────────────────────────────────
@@ -139,6 +142,10 @@ export class Router {
     const old = this.routes.get(nodeId);
     if (old) this.unindexEntry(old);
     this.connections.set(nodeId, connection);
+    // Add to channel set
+    let channelSet = this.channels.get(nodeId);
+    if (!channelSet) { channelSet = new Set(); this.channels.set(nodeId, channelSet); }
+    channelSet.add(connection);
     const entry: RouteEntry = {
       nodeId,
       agents: capabilities.agents,
@@ -157,6 +164,74 @@ export class Router {
     this.indexEntry(entry);
   }
 
+  /** Add an additional channel to an existing peer (multi-channel). */
+  addChannel(nodeId: string, connection: Connection) {
+    let channelSet = this.channels.get(nodeId);
+    if (!channelSet) { channelSet = new Set(); this.channels.set(nodeId, channelSet); }
+    channelSet.add(connection);
+    this.updateActiveChannel(nodeId);
+  }
+
+  /** Remove a single channel. Returns true if the peer still has live channels. */
+  removeChannel(nodeId: string, connection: Connection): boolean {
+    const channelSet = this.channels.get(nodeId);
+    if (channelSet) {
+      channelSet.delete(connection);
+      if (channelSet.size === 0) {
+        this.channels.delete(nodeId);
+        return false;
+      }
+      // Pick new active channel
+      this.updateActiveChannel(nodeId);
+      return true;
+    }
+    return false;
+  }
+
+  /** Re-evaluate the active (best) channel for a peer based on latency. */
+  updateActiveChannel(nodeId: string) {
+    const channelSet = this.channels.get(nodeId);
+    if (!channelSet || channelSet.size === 0) return;
+
+    let best: Connection | null = null;
+    let bestLatency = Infinity;
+    for (const conn of channelSet) {
+      if (!conn.isOpen) continue;
+      // Prefer lower latency; treat 0 (unmeasured) as high
+      const lat = conn.latencyMs > 0 ? conn.latencyMs : 10_000;
+      if (lat < bestLatency) {
+        bestLatency = lat;
+        best = conn;
+      }
+    }
+
+    if (best) {
+      this.connections.set(nodeId, best);
+      const route = this.routes.get(nodeId);
+      if (route) {
+        route.connection = best;
+        route.latencyMs = best.latencyMs;
+      }
+    }
+  }
+
+  /** Get the number of live channels for a peer. */
+  getChannelCount(nodeId: string): number {
+    const channelSet = this.channels.get(nodeId);
+    if (!channelSet) return 0;
+    let count = 0;
+    for (const conn of channelSet) {
+      if (conn.isOpen) count++;
+    }
+    return count;
+  }
+
+  /** Get all channels for a peer (for diagnostics/status). */
+  getChannels(nodeId: string): Connection[] {
+    const channelSet = this.channels.get(nodeId);
+    return channelSet ? [...channelSet] : [];
+  }
+
   addRelayPeer(peer: PeerInfo, viaNodeId: string) {
     // Don't add ourselves
     if (peer.nodeId === this.nodeId) return;
@@ -192,6 +267,7 @@ export class Router {
 
   removePeer(nodeId: string) {
     this.connections.delete(nodeId);
+    this.channels.delete(nodeId);
     const removed = this.routes.get(nodeId);
     if (removed) {
       this.unindexEntry(removed);
@@ -346,11 +422,27 @@ export class Router {
     const route = this.routes.get(targetNodeId);
     if (!route) return false;
 
+    // Try active connection first
     if (route.connection?.isOpen) {
       route.connection.send(frame);
       return true;
     }
 
+    // Fallback: try other channels (multi-channel failover)
+    const channelSet = this.channels.get(targetNodeId);
+    if (channelSet) {
+      for (const conn of channelSet) {
+        if (conn.isOpen) {
+          conn.send(frame);
+          // Promote to active
+          this.connections.set(targetNodeId, conn);
+          route.connection = conn;
+          route.latencyMs = conn.latencyMs;
+          return true;
+        }
+      }
+    }
+
     // Relay through intermediate node
     if (route.reachableVia) {
       const relay = this.connections.get(route.reachableVia);

package/src/tool-proxy.ts

@@ -10,6 +10,9 @@ import type {
 } from "./types.ts";
 import type { PluginLogger } from "openclaw/plugin-sdk";
 import { isLocalTool, executeLocally } from "./local-tools.ts";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
 
 const DEFAULT_TOOL_TIMEOUT = 30_000;
 
@@ -136,13 +139,41 @@ export class ToolProxy {
 
     if (frame.payload.success && frame.payload.result) {
       this.logger.info(`[clawmatrix] Tool response: id=${frame.id} from="${frame.from}" success`);
-      pending.resolve(frame.payload.result);
+      const result = this.extractInlineImage(frame.payload.result);
+      pending.resolve(result);
     } else {
       this.logger.warn(`[clawmatrix] Tool response: id=${frame.id} from="${frame.from}" failed: ${frame.payload.error}`);
       pending.reject(new Error(frame.payload.error ?? "Remote tool execution failed"));
     }
   }
 
+  /**
+   * If the tool result contains inline base64 image data (mime: "image/*" + data),
+   * save it to a local temp file and replace `data` with `localPath`.
+   * This avoids flooding the LLM context with base64 text (saves ~tens of thousands of tokens).
+   */
+  private extractInlineImage(result: Record<string, unknown>): Record<string, unknown> {
+    const mime = result.mime;
+    const data = result.data;
+    if (typeof mime !== "string" || !mime.startsWith("image/") || typeof data !== "string") {
+      return result;
+    }
+
+    try {
+      const ext = mime === "image/png" ? ".png" : mime === "image/webp" ? ".webp" : ".jpg";
+      const dir = join(tmpdir(), "clawmatrix-images");
+      mkdirSync(dir, { recursive: true });
+      const localPath = join(dir, `${Date.now()}-${Math.random().toString(36).slice(2, 8)}${ext}`);
+      writeFileSync(localPath, Buffer.from(data, "base64"));
+      this.logger.info(`[clawmatrix] Saved inline image (${(data.length * 0.75 / 1024).toFixed(0)}KB) to ${localPath}`);
+      const { data: _stripped, ...rest } = result;
+      return { ...rest, localPath };
+    } catch (err) {
+      this.logger.warn(`[clawmatrix] Failed to extract inline image: ${err}`);
+      return result;
+    }
+  }
+
   // ── Incoming request: execute via local Gateway ────────────────
   async handleRequest(frame: ToolProxyRequest): Promise<void> {
     const { id, from, payload } = frame;
@@ -288,7 +319,14 @@ export class ToolProxy {
 
     clearTimeout(pending.timer);
     this.pendingBatch.delete(frame.id);
-    pending.resolve(frame.payload.results);
+    // Extract inline images from batch results
+    const results = frame.payload.results.map((item) => {
+      if (item.success && item.result) {
+        return { ...item, result: this.extractInlineImage(item.result) };
+      }
+      return item;
+    });
+    pending.resolve(results);
   }
 
   // ── Incoming batch request: execute sequentially via local Gateway ──