clawmatrix 0.2.11 → 0.4.0

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

@@ -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;
 
@@ -45,6 +48,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 +59,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). */
@@ -128,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;
@@ -280,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 ──
@@ -338,10 +384,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-notify.ts

@@ -0,0 +1,132 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+import { randomUUID } from "node:crypto";
+
+export function createClusterNotifyTool(): AnyAgentTool {
+  return {
+    name: "cluster_notify",
+    label: "Cluster Notify",
+    description:
+      "Push a notification to mobile devices in the cluster (triggers Dynamic Island / Live Activity on iOS). " +
+      "Use this when you are about to start a long-running task so the user can track progress on their phone. " +
+      'Actions: "start" begins a new activity, "update" changes detail/progress, "end" dismisses it.',
+    parameters: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["start", "update", "end"],
+          description: 'Action to perform. Default: "start"',
+        },
+        taskId: {
+          type: "string",
+          description: "Task ID for update/end actions. Returned by start action. Omit for start to auto-generate.",
+        },
+        title: {
+          type: "string",
+          description: "Activity title (shown in Dynamic Island and lock screen)",
+        },
+        detail: {
+          type: "string",
+          description: "Activity detail text (e.g. current step description)",
+        },
+        progress: {
+          type: "number",
+          description: "Progress value 0.0 to 1.0 (optional, shows progress bar when provided)",
+        },
+        tool: {
+          type: "string",
+          description: "Current tool being executed (shown as a tag in the activity)",
+        },
+        success: {
+          type: "boolean",
+          description: 'For "end" action: true for completed, false for failed. Default: true',
+        },
+      },
+      required: [],
+    },
+    async execute(_toolCallId, params) {
+      const {
+        action = "start",
+        taskId: providedTaskId,
+        title,
+        detail,
+        progress,
+        tool,
+        success = true,
+      } = params as {
+        action?: "start" | "update" | "end";
+        taskId?: string;
+        title?: string;
+        detail?: string;
+        progress?: number;
+        tool?: string;
+        success?: boolean;
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+        const peers = runtime.peerManager.router.getAllPeers();
+        const mobileTargets = peers.filter((p) =>
+          p.tags.some((t) => t === "mobile" || t === "ios" || t === "phone"),
+        );
+
+        if (mobileTargets.length === 0) {
+          return {
+            content: [{ type: "text" as const, text: "No mobile peers connected" }],
+            details: { error: true },
+          };
+        }
+
+        const taskId = providedTaskId || randomUUID();
+        const now = Date.now();
+
+        let status: string;
+        if (action === "start") status = "started";
+        else if (action === "end") status = success ? "completed" : "failed";
+        else status = "progress";
+
+        const frame = {
+          type: "task_activity" as const,
+          id: randomUUID(),
+          from: runtime.config.nodeId,
+          timestamp: now,
+          payload: {
+            taskId,
+            taskType: "notify" as const,
+            status,
+            agent: title || runtime.config.nodeId,
+            nodeId: runtime.config.nodeId,
+            title: title || runtime.config.nodeId,
+            detail: detail || (action === "end" ? (success ? "已完成" : "失败") : undefined),
+            startedAt: now,
+            elapsedMs: 0,
+            progress,
+            tool,
+          },
+        };
+
+        for (const target of mobileTargets) {
+          runtime.peerManager.sendTo(target.nodeId, { ...frame, to: target.nodeId });
+        }
+
+        const targetNames = mobileTargets.map((t) => t.nodeId).join(", ");
+        return {
+          content: [{
+            type: "text" as const,
+            text: `Notification ${action}ed → ${targetNames} (taskId: ${taskId})`,
+          }],
+          details: { taskId, action, targets: mobileTargets.length },
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: `Notify error: ${err instanceof Error ? err.message : String(err)}`,
+          }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

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: {},