clawmatrix 0.1.23 → 0.2.0

package/src/tools/cluster-edit.ts

@@ -0,0 +1,70 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterEditTool(): AnyAgentTool {
+  return {
+    name: "cluster_edit",
+    label: "Cluster Edit",
+    description:
+      "Edit a file on a remote cluster node by replacing exact text. " +
+      "The oldText must match exactly (including whitespace).",
+    parameters: {
+      type: "object",
+      properties: {
+        node: {
+          type: "string",
+          description: 'Target nodeId or "tags:<tag>"',
+        },
+        path: {
+          type: "string",
+          description: "File path to edit (relative or absolute on the remote node)",
+        },
+        oldText: {
+          type: "string",
+          description: "Exact text to find and replace (must match exactly)",
+        },
+        newText: {
+          type: "string",
+          description: "New text to replace the old text with",
+        },
+      },
+      required: ["node", "path", "oldText", "newText"],
+    },
+    async execute(_toolCallId, params) {
+      const { node, path, oldText, newText } = params as {
+        node: string;
+        path: string;
+        oldText: string;
+        newText: string;
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+        const result = await runtime.toolProxy.invoke(
+          node,
+          "edit",
+          { path, oldText, newText },
+        );
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(result),
+            },
+          ],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Edit error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-peers.ts

@@ -14,19 +14,64 @@ export function createClusterPeersTool(): AnyAgentTool {
     async execute() {
       try {
         const runtime = getClusterRuntime();
-        const peers = runtime.peerManager.router.getAllPeers().map((entry) => ({
-          nodeId: entry.nodeId,
-          agents: entry.agents.map((a) => ({
-            id: a.id,
-            description: a.description,
-            tags: a.tags,
-          })),
-          models: entry.models.map((m) => m.id),
-          tags: entry.tags,
-          tools: entry.toolProxy?.enabled ? (entry.toolProxy.allow ?? []) : [],
-          status: runtime.peerManager.router.getPeerStatus(entry),
-          latencyMs: entry.latencyMs,
-        }));
+        const allEntries = runtime.peerManager.router.getAllPeers();
+
+        // Separate sentinel peers from normal peers
+        const sentinelSet = new Set<string>();
+        for (const entry of allEntries) {
+          if (entry.nodeId.endsWith(":sentinel")) {
+            sentinelSet.add(entry.nodeId.replace(/:sentinel$/, ""));
+          }
+        }
+
+        const peers = allEntries
+          .filter((entry) => !entry.nodeId.endsWith(":sentinel"))
+          .map((entry) => {
+            const sentinelNodeId = `${entry.nodeId}:sentinel`;
+            const sentinelEntry = allEntries.find((e) => e.nodeId === sentinelNodeId);
+            const status = runtime.peerManager.router.getPeerStatus(entry);
+            const hasSentinel = !!sentinelEntry;
+            const sentinelStatus = sentinelEntry
+              ? runtime.peerManager.router.getPeerStatus(sentinelEntry)
+              : undefined;
+
+            return {
+              nodeId: entry.nodeId,
+              agents: entry.agents.map((a) => ({
+                id: a.id,
+                description: a.description,
+                tags: a.tags,
+              })),
+              models: entry.models.map((m) => m.id),
+              tags: entry.tags,
+              tools: entry.toolProxy?.enabled ? (entry.toolProxy.allow ?? []) : [],
+              status,
+              latencyMs: entry.latencyMs,
+              // Sentinel info merged into the same row
+              ...(hasSentinel ? {
+                sentinel: sentinelStatus === "direct" || sentinelStatus === "relay" ? "online" : "offline",
+              } : {}),
+            };
+          });
+
+        // Sentinel-only entries (main node not in routing table, but sentinel is)
+        for (const entry of allEntries) {
+          if (!entry.nodeId.endsWith(":sentinel")) continue;
+          const mainNodeId = entry.nodeId.replace(/:sentinel$/, "");
+          if (peers.some((p) => p.nodeId === mainNodeId)) continue;
+          // Main node is gone, only sentinel remains
+          const sentinelStatus = runtime.peerManager.router.getPeerStatus(entry);
+          peers.push({
+            nodeId: mainNodeId,
+            agents: [],
+            models: [],
+            tags: entry.tags.filter((t) => t !== "sentinel"),
+            tools: [],
+            status: "unreachable",
+            latencyMs: entry.latencyMs,
+            sentinel: sentinelStatus === "direct" || sentinelStatus === "relay" ? "online" : "offline",
+          } as (typeof peers)[number]);
+        }
 
         // Include satellite nodes (minimal fields — no agents/models)
         const satellites = runtime.webHandler?.getSatelliteContexts() ?? runtime.peerManager.satelliteContexts;
@@ -36,7 +81,7 @@ export function createClusterPeersTool(): AnyAgentTool {
             nodeId: sat.nodeId,
             tools: sat.tools ?? [],
             status: "satellite",
-          } as (typeof peers)[number]);
+          } as unknown as (typeof peers)[number]);
         }
 
         return {

package/src/tools/cluster-terminal.ts

@@ -0,0 +1,232 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterTerminalTool(): AnyAgentTool {
+  return {
+    name: "cluster_terminal",
+    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.',
+    parameters: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["open", "input", "read", "resize", "list", "close"],
+          description: 'Action to perform. Default: "open"',
+        },
+        node: {
+          type: "string",
+          description: 'Target node ID or "tags:<tag>" (required for open)',
+        },
+        sessionId: {
+          type: "string",
+          description: "Session ID (required for input/read/resize/close)",
+        },
+        data: {
+          type: "string",
+          description: "Input data to send (for input action). Supports \\n for newline, \\x03 for Ctrl-C, etc.",
+        },
+        shell: {
+          type: "string",
+          description: "Shell to use (default: $SHELL or /bin/sh)",
+        },
+        cols: {
+          type: "number",
+          description: "Terminal columns (default: 80)",
+        },
+        rows: {
+          type: "number",
+          description: "Terminal rows (default: 24)",
+        },
+        cwd: {
+          type: "string",
+          description: "Working directory on remote node",
+        },
+      },
+      required: [],
+    },
+    async execute(_toolCallId, params) {
+      const {
+        action = "open",
+        node,
+        sessionId,
+        data,
+        shell,
+        cols,
+        rows,
+        cwd,
+      } = params as {
+        action?: "open" | "input" | "read" | "resize" | "list" | "close";
+        node?: string;
+        sessionId?: string;
+        data?: string;
+        shell?: string;
+        cols?: number;
+        rows?: number;
+        cwd?: string;
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+        const tm = runtime.terminalManager;
+
+        if (action === "list") {
+          const sessions = tm.listSessions();
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(sessions, null, 2) }],
+            details: sessions,
+          };
+        }
+
+        if (action === "open") {
+          if (!node) {
+            return {
+              content: [{ type: "text" as const, text: "node is required for open action" }],
+              details: { error: true },
+            };
+          }
+          const nodeId = resolveNodeId(runtime, node);
+          const sid = await tm.open(nodeId, { shell, cols, rows, cwd });
+
+          // Wait a moment for initial output (shell prompt)
+          await new Promise((r) => setTimeout(r, 500));
+          const initial = tm.readOutput(sid);
+
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify({
+                sessionId: sid,
+                nodeId,
+                status: "open",
+                initialOutput: initial.data,
+              }, null, 2),
+            }],
+            details: { sessionId: sid, nodeId },
+          };
+        }
+
+        if (action === "input") {
+          if (!sessionId) {
+            return {
+              content: [{ type: "text" as const, text: "sessionId is required for input action" }],
+              details: { error: true },
+            };
+          }
+          if (!data) {
+            return {
+              content: [{ type: "text" as const, text: "data is required for input action" }],
+              details: { error: true },
+            };
+          }
+          tm.sendInput(sessionId, data);
+
+          // Wait for output response
+          await new Promise((r) => setTimeout(r, 300));
+          const output = tm.readOutput(sessionId);
+
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify({
+                sessionId,
+                output: output.data,
+                closed: output.closed,
+                exitCode: output.exitCode,
+              }, null, 2),
+            }],
+            details: { output: output.data, closed: output.closed },
+          };
+        }
+
+        if (action === "read") {
+          if (!sessionId) {
+            return {
+              content: [{ type: "text" as const, text: "sessionId is required for read action" }],
+              details: { error: true },
+            };
+          }
+          const output = tm.readOutput(sessionId);
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify({
+                sessionId,
+                output: output.data,
+                closed: output.closed,
+                exitCode: output.exitCode,
+              }, null, 2),
+            }],
+            details: output,
+          };
+        }
+
+        if (action === "resize") {
+          if (!sessionId) {
+            return {
+              content: [{ type: "text" as const, text: "sessionId is required for resize action" }],
+              details: { error: true },
+            };
+          }
+          tm.resize(sessionId, cols ?? 80, rows ?? 24);
+          return {
+            content: [{ type: "text" as const, text: `Resized to ${cols ?? 80}x${rows ?? 24}` }],
+            details: { success: true },
+          };
+        }
+
+        if (action === "close") {
+          if (!sessionId) {
+            return {
+              content: [{ type: "text" as const, text: "sessionId is required for close action" }],
+              details: { error: true },
+            };
+          }
+          tm.close(sessionId);
+          return {
+            content: [{ type: "text" as const, text: `Session ${sessionId} closed` }],
+            details: { success: true },
+          };
+        }
+
+        return {
+          content: [{ type: "text" as const, text: `Unknown action: ${action}` }],
+          details: { error: true },
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: `Terminal error: ${err instanceof Error ? err.message : String(err)}`,
+          }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}
+
+function resolveNodeId(
+  runtime: ReturnType<typeof getClusterRuntime>,
+  node: string,
+): string {
+  const peers = runtime.peerManager.router.getAllPeers();
+  const direct = peers.find((p) => p.nodeId === node);
+  if (direct) return direct.nodeId;
+
+  if (node.startsWith("tags:")) {
+    const tag = node.slice(5);
+    const match = peers.find((p) => p.tags.includes(tag));
+    if (match) return match.nodeId;
+  }
+
+  return node;
+}

package/src/tools/cluster-tool.ts

@@ -1,12 +1,15 @@
 import type { AnyAgentTool } from "openclaw/plugin-sdk";
 import { getClusterRuntime } from "../cluster-service.ts";
 
-export function createClusterToolTool(): AnyAgentTool {
+export function createClusterToolInvokeTool(): AnyAgentTool {
   return {
     name: "cluster_tool",
-    label: "Cluster Tool",
+    label: "Cluster Tool Invoke",
     description:
-      "Invoke any OpenClaw tool on a remote cluster node. Use nodeId or 'tags:<tag>' to specify the target.",
+      "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. " +
+      "Use nodeId or 'tags:<tag>' to specify the target.",
     parameters: {
       type: "object",
       properties: {
@@ -16,25 +19,37 @@ export function createClusterToolTool(): AnyAgentTool {
         },
         tool: {
           type: "string",
-          description: "Tool name to invoke on the remote node",
+          description: "Remote tool name to invoke (e.g. screenshot, battery, location)",
         },
-        args: {
+        params: {
           type: "object",
-          description: "Tool arguments (tool-specific)",
+          description: "Parameters to pass to the remote tool (tool-specific)",
+          additionalProperties: true,
+        },
+        timeout: {
+          type: "number",
+          description: "Timeout in seconds (default 30)",
         },
       },
-      required: ["node", "tool", "args"],
+      required: ["node", "tool"],
     },
     async execute(_toolCallId, params) {
-      const { node, tool, args } = params as {
+      const { node, tool, params: toolParams, timeout } = params as {
         node: string;
         tool: string;
-        args: Record<string, unknown>;
+        params?: Record<string, unknown>;
+        timeout?: number;
       };
 
       try {
         const runtime = getClusterRuntime();
-        const result = await runtime.toolProxy.invoke(node, tool, args);
+        const timeoutMs = (timeout ?? 30) * 1000;
+        const result = await runtime.toolProxy.invoke(
+          node,
+          tool,
+          toolParams ?? {},
+          timeoutMs,
+        );
         return {
           content: [
             {
@@ -49,7 +64,7 @@ export function createClusterToolTool(): AnyAgentTool {
           content: [
             {
               type: "text" as const,
-              text: `Tool error: ${err instanceof Error ? err.message : String(err)}`,
+              text: `Tool invoke error: ${err instanceof Error ? err.message : String(err)}`,
             },
           ],
           details: { error: true },