clawmatrix 0.2.11 → 0.3.1

package/src/router.ts

@@ -38,6 +38,14 @@ export class Router {
   /** Failed request IDs with expiry timestamps. Separate from dedup to support longer TTLs. */
   private failedRequests = new Map<string, number>(); // requestId → expiresAt
 
+  // ── Indexes for O(1) lookups in hot paths ──────────────────────
+  /** agentId → Set of nodeIds that host this agent. */
+  private agentIndex = new Map<string, Set<string>>();
+  /** tag → Set of nodeIds (both node-level and agent-level tags). */
+  private tagIndex = new Map<string, Set<string>>();
+  /** modelId → Set of nodeIds that provide this model. */
+  private modelIndex = new Map<string, Set<string>>();
+
   constructor(
     nodeId: string,
     localCapabilities?: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[]; deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo; acpAgents?: AcpAgentInfo[] },
@@ -53,11 +61,64 @@ export class Router {
     this.rotateTimer = setInterval(() => this.rotateSeenFrames(), ROTATE_INTERVAL);
   }
 
+  /** Rebuild all indexes from scratch. Called after any route table mutation. */
+  private rebuildIndexes() {
+    this.agentIndex.clear();
+    this.tagIndex.clear();
+    this.modelIndex.clear();
+    for (const entry of this.routes.values()) {
+      this.indexEntry(entry);
+    }
+  }
+
+  /** Add a single entry to all indexes. */
+  private indexEntry(entry: RouteEntry) {
+    const nid = entry.nodeId;
+    for (const a of entry.agents) {
+      let set = this.agentIndex.get(a.id);
+      if (!set) { set = new Set(); this.agentIndex.set(a.id, set); }
+      set.add(nid);
+      for (const t of a.tags ?? []) {
+        let ts = this.tagIndex.get(t);
+        if (!ts) { ts = new Set(); this.tagIndex.set(t, ts); }
+        ts.add(nid);
+      }
+    }
+    for (const t of entry.tags ?? []) {
+      let set = this.tagIndex.get(t);
+      if (!set) { set = new Set(); this.tagIndex.set(t, set); }
+      set.add(nid);
+    }
+    for (const m of entry.models ?? []) {
+      let set = this.modelIndex.get(m.id);
+      if (!set) { set = new Set(); this.modelIndex.set(m.id, set); }
+      set.add(nid);
+    }
+  }
+
+  /** Remove a single entry from all indexes. */
+  private unindexEntry(entry: RouteEntry) {
+    const nid = entry.nodeId;
+    for (const a of entry.agents ?? []) {
+      this.agentIndex.get(a.id)?.delete(nid);
+      for (const t of a.tags ?? []) this.tagIndex.get(t)?.delete(nid);
+    }
+    for (const t of entry.tags ?? []) this.tagIndex.get(t)?.delete(nid);
+    for (const m of entry.models ?? []) this.modelIndex.get(m.id)?.delete(nid);
+  }
+
   /** Update locally advertised ACP agents (used after auto-detection). */
   updateLocalAcpAgents(agents: AcpAgentInfo[]) {
     this.localAcpAgents = agents;
   }
 
+  /** Update the local tool proxy catalog (descriptions + schemas for remote callers). */
+  updateLocalToolCatalog(catalog: ToolProxyInfo["catalog"]) {
+    if (this.localToolProxy) {
+      this.localToolProxy = { ...this.localToolProxy, catalog };
+    }
+  }
+
   /** Stop periodic cleanup. Call on shutdown. */
   destroy() {
     if (this.rotateTimer) {
@@ -75,8 +136,10 @@ export class Router {
     connection: Connection,
     capabilities: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[]; deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo; acpAgents?: AcpAgentInfo[] },
   ) {
+    const old = this.routes.get(nodeId);
+    if (old) this.unindexEntry(old);
     this.connections.set(nodeId, connection);
-    this.routes.set(nodeId, {
+    const entry: RouteEntry = {
       nodeId,
       agents: capabilities.agents,
       models: capabilities.models,
@@ -89,7 +152,9 @@ export class Router {
       deviceInfo: capabilities.deviceInfo,
       toolProxy: capabilities.toolProxy,
       acpAgents: capabilities.acpAgents,
-    });
+    };
+    this.routes.set(nodeId, entry);
+    this.indexEntry(entry);
   }
 
   addRelayPeer(peer: PeerInfo, viaNodeId: string) {
@@ -106,7 +171,8 @@ export class Router {
     // 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, {
+    if (existing) this.unindexEntry(existing);
+    const entry: RouteEntry = {
       nodeId: peer.nodeId,
       agents: peer.agents,
       models: peer.models,
@@ -119,15 +185,22 @@ export class Router {
       deviceInfo: peer.deviceInfo,
       toolProxy: peer.toolProxy,
       acpAgents: peer.acpAgents,
-    });
+    };
+    this.routes.set(peer.nodeId, entry);
+    this.indexEntry(entry);
   }
 
   removePeer(nodeId: string) {
     this.connections.delete(nodeId);
-    this.routes.delete(nodeId);
+    const removed = this.routes.get(nodeId);
+    if (removed) {
+      this.unindexEntry(removed);
+      this.routes.delete(nodeId);
+    }
     // Also remove routes that relied on this node as relay
     for (const [id, entry] of this.routes) {
       if (entry.reachableVia === nodeId) {
+        this.unindexEntry(entry);
         this.routes.delete(id);
       }
     }
@@ -139,6 +212,7 @@ export class Router {
   ) {
     const entry = this.routes.get(nodeId);
     if (entry) {
+      this.unindexEntry(entry);
       entry.agents = capabilities.agents;
       entry.models = capabilities.models;
       entry.tags = capabilities.tags;
@@ -151,6 +225,7 @@ export class Router {
       entry.toolProxy = capabilities.toolProxy;
       entry.acpAgents = capabilities.acpAgents;
       entry.lastSeen = Date.now();
+      this.indexEntry(entry);
     }
   }
 
@@ -169,20 +244,20 @@ export class Router {
   /** Resolve target agent to a specific nodeId. Supports agent ID or "tags:<tag>". */
   resolveAgent(target: string): RouteEntry | undefined {
     const isTagQuery = target.startsWith("tags:");
-    const tag = isTagQuery ? target.slice(5) : null;
+
+    let nodeIds: Set<string> | undefined;
+    if (isTagQuery) {
+      nodeIds = this.tagIndex.get(target.slice(5));
+    } else {
+      nodeIds = this.agentIndex.get(target);
+    }
 
     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);
-        }
-      } else {
-        if (entry.agents.some((a) => a.id === target)) {
-          candidates.push(entry);
-        }
+    if (nodeIds) {
+      for (const nid of nodeIds) {
+        if (nid === this.nodeId) continue;
+        const entry = this.routes.get(nid);
+        if (entry) candidates.push(entry);
       }
     }
 
@@ -193,6 +268,7 @@ export class Router {
     }
 
     if (candidates.length === 0) return undefined;
+    if (candidates.length === 1) return candidates[0];
 
     // Sort: direct connections first, then by latency
     candidates.sort((a, b) => {
@@ -210,15 +286,16 @@ export class Router {
   resolveNode(target: string): RouteEntry | undefined {
     if (target.startsWith("tags:")) {
       const tag = target.slice(5);
+      const nodeIds = this.tagIndex.get(tag);
+      if (!nodeIds) return undefined;
       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);
-        }
+      for (const nid of nodeIds) {
+        if (nid === this.nodeId) continue;
+        const entry = this.routes.get(nid);
+        if (entry) candidates.push(entry);
       }
       if (candidates.length === 0) return undefined;
+      if (candidates.length === 1) return candidates[0];
       // Sort: direct connections first, then by latency
       candidates.sort((a, b) => {
         const aDirect = a.connection ? 0 : 1;
@@ -236,10 +313,13 @@ export class Router {
   /** Find reachable nodes that provide a specific model, sorted by latency.
    *  Excludes nodes in the `exclude` set. */
   findNodesForModel(modelId: string, exclude?: Set<string>): RouteEntry[] {
+    const nodeIds = this.modelIndex.get(modelId);
+    if (!nodeIds) return [];
     const candidates: RouteEntry[] = [];
-    for (const entry of this.routes.values()) {
-      if (exclude?.has(entry.nodeId)) continue;
-      if (!entry.models.some((m) => m.id === modelId)) continue;
+    for (const nid of nodeIds) {
+      if (exclude?.has(nid)) continue;
+      const entry = this.routes.get(nid);
+      if (!entry) continue;
       // Check reachability
       if (entry.connection?.isOpen) {
         candidates.push(entry);
@@ -248,13 +328,15 @@ export class Router {
         if (relay?.isOpen) candidates.push(entry);
       }
     }
-    // Sort: direct first, then by latency
-    candidates.sort((a, b) => {
-      const aDirect = a.connection ? 0 : 1;
-      const bDirect = b.connection ? 0 : 1;
-      if (aDirect !== bDirect) return aDirect - bDirect;
-      return a.latencyMs - b.latencyMs;
-    });
+    if (candidates.length > 1) {
+      // Sort: direct first, then by latency
+      candidates.sort((a, b) => {
+        const aDirect = a.connection ? 0 : 1;
+        const bDirect = b.connection ? 0 : 1;
+        if (aDirect !== bDirect) return aDirect - bDirect;
+        return a.latencyMs - b.latencyMs;
+      });
+    }
     return candidates;
   }
 

package/src/sentinel-manager.ts

@@ -9,6 +9,7 @@
 import { fork, type ChildProcess } from "node:child_process";
 import { join, dirname } from "node:path";
 import { existsSync, readFileSync, mkdirSync, openSync, closeSync } from "node:fs";
+import { createConnection } from "node:net";
 import { homedir, tmpdir } from "node:os";
 import type { ClawMatrixConfig } from "./config.ts";
 
@@ -86,6 +87,56 @@ export class SentinelManager {
     }, 1000);
   }
 
+  /**
+   * Kill the old sentinel and wait for the listen port to become free.
+   * Must be called BEFORE PeerManager.startListening() to avoid EADDRINUSE.
+   */
+  async ensurePortFree() {
+    // Kill old sentinel process if alive
+    if (existsSync(this.pidFile)) {
+      try {
+        const pid = parseInt(readFileSync(this.pidFile, "utf-8").trim(), 10);
+        if (pid) {
+          try {
+            process.kill(pid, "SIGTERM");
+            // Wait for the process to exit (up to 5s)
+            for (let i = 0; i < 100; i++) {
+              try {
+                process.kill(pid, 0);
+                await new Promise((r) => setTimeout(r, 50));
+              } catch {
+                break; // exited
+              }
+            }
+          } catch {
+            // Already gone
+          }
+        }
+      } catch {
+        // Malformed PID file
+      }
+    }
+
+    // Probe the port until it's free (up to 5s)
+    const port = this.config.sentinel?.listenPort
+      ?? (this.config.listen ? this.config.listenPort : 0);
+    if (!port) return;
+
+    const host = this.config.sentinel?.listenHost ?? this.config.listenHost ?? "0.0.0.0";
+    for (let i = 0; i < 50; i++) {
+      const inUse = await new Promise<boolean>((resolve) => {
+        const sock = createConnection({ port, host }, () => {
+          sock.destroy();
+          resolve(true);
+        });
+        sock.on("error", () => resolve(false));
+        sock.setTimeout(200, () => { sock.destroy(); resolve(false); });
+      });
+      if (!inUse) return;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+
   async stop() {
     // IPC is disconnected shortly after start, so use PID file for shutdown
     if (existsSync(this.pidFile)) {

package/src/sentinel.ts

@@ -78,6 +78,11 @@ let httpServer: Server | null = null;
 let wss: WebSocketServer | null = null;
 const inboundConnections = new Map<WsWebSocket, Connection>();
 let listening = false;
+/** Timestamp when sentinel voluntarily released the port. During the cooldown
+ *  period (30s), sentinel will not re-listen even if gateway appears to be gone,
+ *  giving the new gateway time to bind the port. */
+let voluntaryReleaseAt = 0;
+const PORT_RELEASE_COOLDOWN = 30_000;
 
 // ── Rate limiting for diagnostic_exec ────────────────────────────
 const EXEC_RATE_WINDOW = 60_000; // 1 minute
@@ -464,6 +469,9 @@ function stopListening() {
   httpServer?.close();
   httpServer = null;
   listening = false;
+  // Mark voluntary release — sentinel will not re-listen during cooldown
+  // to give the gateway time to bind the port.
+  voluntaryReleaseAt = Date.now();
   log("Port released — gateway is back");
 }
 
@@ -612,12 +620,14 @@ function startGatewayHealthCheck() {
         log(`Gateway process (pid ${gatewayPid}) gone — entering standalone mode`);
         // Connect to peers now that gateway is down
         connectAllPeers();
-        // Take over the gateway's listen port
+        // Take over the gateway's listen port — but respect cooldown after
+        // voluntary release so we don't compete with a restarting gateway.
         if (config.listenPort) {
-          // Small delay to let the OS release the port from the dead process
+          const cooldownRemaining = PORT_RELEASE_COOLDOWN - (Date.now() - voluntaryReleaseAt);
+          const delay = Math.max(2_000, cooldownRemaining);
           setTimeout(() => {
             if (!gatewayAlive && !isReplaced()) startListening();
-          }, 2_000);
+          }, delay);
         }
       }
     }

package/src/tool-proxy.ts

@@ -45,6 +45,10 @@ export class ToolProxy {
   private logger: PluginLogger;
   private satelliteHandler: SatelliteToolHandler | null = null;
   private readonly toolTimeout: number;
+  // Pre-built Sets for O(1) allow/deny checks
+  private readonly allowSet: Set<string>;
+  private readonly denySet: Set<string>;
+  private readonly allowAll: boolean;
 
   constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo, logger: PluginLogger) {
     this.config = config;
@@ -52,6 +56,10 @@ export class ToolProxy {
     this.gatewayInfo = gatewayInfo;
     this.logger = logger;
     this.toolTimeout = config.toolTimeout ?? DEFAULT_TOOL_TIMEOUT;
+    const tp = config.toolProxy;
+    this.denySet = new Set(tp?.deny ?? []);
+    this.allowSet = new Set(tp?.allow ?? []);
+    this.allowAll = this.allowSet.size === 0 || this.allowSet.has("*");
   }
 
   /** Set the satellite tool handler (called by ClusterRuntime after WebHandler is created). */
@@ -338,10 +346,10 @@ export class ToolProxy {
   }
 
   // ── Security ───────────────────────────────────────────────────
-  private isToolAllowed(tool: string, tpConfig: ToolProxyConfig): boolean {
-    if (tpConfig.deny.includes(tool)) return false;
-    if (tpConfig.allow.length === 0 || tpConfig.allow.includes("*")) return true;
-    return tpConfig.allow.includes(tool);
+  private isToolAllowed(tool: string, _tpConfig: ToolProxyConfig): boolean {
+    if (this.denySet.has(tool)) return false;
+    if (this.allowAll) return true;
+    return this.allowSet.has(tool);
   }
 
   destroy() {

package/src/tools/cluster-diagnostic.ts

@@ -10,9 +10,10 @@ export function createClusterDiagnosticTool(): AnyAgentTool {
     label: "Cluster Diagnostic",
     description:
       "Diagnose or execute commands on a remote node's sentinel process. " +
-      "Works even when the remote OpenClaw gateway is down. " +
+      "Works even when the remote OpenClaw gateway is down (sentinel is a lightweight always-on process). " +
       "Use action 'status' to check if the remote gateway is alive, " +
-      "or 'exec' to run a shell command on the remote machine.",
+      "or 'exec' to run a shell command on the remote machine. " +
+      "Note: exec runs commands without restrictions — only use in trusted networks.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-edit.ts

@@ -7,7 +7,8 @@ export function createClusterEditTool(): AnyAgentTool {
     label: "Cluster Edit",
     description:
       "Edit a file on a remote cluster node by replacing exact text. " +
-      "The oldText must match exactly (including whitespace).",
+      "IMPORTANT: Use cluster_read first to get exact file content — oldText must match precisely (including whitespace and indentation). " +
+      "For creating new files use cluster_write instead.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-events.ts

@@ -6,7 +6,9 @@ export function createClusterEventsTool(): AnyAgentTool {
     name: "cluster_events",
     label: "Cluster Events",
     description:
-      "Query and consume events from external sources (messages, calls, location changes).",
+      "Query and consume events from external sources (iOS Shortcuts, webhooks, etc.). " +
+      "Common types: message_received, location_change, battery_status. " +
+      "Events are persistent until consumed. Requires web.enabled in config.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-exec.ts

@@ -7,6 +7,8 @@ export function createClusterExecTool(): AnyAgentTool {
     label: "Cluster Exec",
     description:
       "Execute a shell command on a remote cluster node. " +
+      "Use for file/shell operations on remote machines. " +
+      "Returns {stdout, stderr, exitCode}. " +
       "Use nodeId or 'tags:<tag>' to specify the target.",
     parameters: {
       type: "object",

package/src/tools/cluster-handoff.ts

@@ -6,7 +6,9 @@ export function createClusterHandoffTool(): AnyAgentTool {
     name: "cluster_handoff",
     label: "Cluster Handoff",
     description:
-      "Hand off a task to another agent in the cluster and wait for the result. " +
+      "Hand off a complex task to another agent in the cluster and wait for the result. " +
+      "Use for multi-step tasks that require the remote agent's full capabilities. " +
+      "If the remote agent needs more info, response includes inputRequired=true — use cluster_handoff_reply to continue. " +
       "Use agent ID (e.g. 'coder') or tag query (e.g. 'tags:coding') as target.",
     parameters: {
       type: "object",

package/src/tools/cluster-peers.ts

@@ -6,7 +6,9 @@ export function createClusterPeersTool(): AnyAgentTool {
     name: "cluster_peers",
     label: "Cluster Peers",
     description:
-      "List all reachable peers in the cluster, their agents, models, tools, and connection status.",
+      "List all peers in the cluster with their agents, models, tools, tags, and connection status. " +
+      "Call this first to discover what's available before using other cluster tools. " +
+      "Status: direct (connected), relay (via another node), sentinel-only (gateway down, sentinel up), satellite (HTTP polling device), unreachable.",
     parameters: {
       type: "object",
       properties: {},

package/src/tools/cluster-read.ts

@@ -5,7 +5,10 @@ export function createClusterReadTool(): AnyAgentTool {
   return {
     name: "cluster_read",
     label: "Cluster Read",
-    description: "Read a file from a remote cluster node.",
+    description:
+      "Read a file from a remote cluster node. " +
+      "Returns {content} with the file text. " +
+      "Use nodeId or 'tags:<tag>' to specify the target.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-send.ts

@@ -6,7 +6,8 @@ export function createClusterSendTool(): AnyAgentTool {
     name: "cluster_send",
     label: "Cluster Send",
     description:
-      "Send a one-way message to a remote agent. Does not wait for a response.",
+      "Send a one-way notification to a remote agent. Fire-and-forget: does not wait for a response. " +
+      "Use cluster_handoff instead when you need the remote agent to process a task and return a result.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-terminal.ts

@@ -7,13 +7,10 @@ export function createClusterTerminalTool(): AnyAgentTool {
     label: "Cluster Terminal",
     description:
       "Interactive terminal (PTY) on a remote cluster node. " +
-      "Actions: " +
-      '"open" — open a terminal session on a remote node. ' +
-      '"input" — send input (keystrokes/commands) to a session. ' +
-      '"read" — read buffered output from a session. ' +
-      '"resize" — resize the terminal. ' +
-      '"list" — list active terminal sessions. ' +
-      '"close" — close a terminal session.',
+      "Workflow: open → input/read (repeat) → close. " +
+      'Actions: "open" (requires node), "input" (requires sessionId + data), "read" (requires sessionId), ' +
+      '"resize" (requires sessionId), "list" (no params), "close" (requires sessionId). ' +
+      "Prefer cluster_exec for one-shot commands; use this for interactive/stateful sessions.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-tool.ts

@@ -7,8 +7,8 @@ export function createClusterToolInvokeTool(): AnyAgentTool {
     label: "Cluster Tool Invoke",
     description:
       "Invoke any tool on a remote cluster node by name. " +
-      "Use this for device-specific tools (e.g. screenshot, battery, location on mobile nodes). " +
-      "Use cluster_peers to discover available tools on each peer. " +
+      "Preferred for device-specific tools (screenshot, battery, location, clipboard, etc.). " +
+      "Run cluster_peers first to discover available tools, or use CLI: clawmatrix tools --describe <tool> for params. " +
       "Use nodeId or 'tags:<tag>' to specify the target.",
     parameters: {
       type: "object",

package/src/tools/cluster-write.ts

@@ -5,7 +5,9 @@ export function createClusterWriteTool(): AnyAgentTool {
   return {
     name: "cluster_write",
     label: "Cluster Write",
-    description: "Write content to a file on a remote cluster node.",
+    description:
+      "Write content to a file on a remote cluster node (creates or overwrites). " +
+      "Use nodeId or 'tags:<tag>' to specify the target.",
     parameters: {
       type: "object",
       properties: {