clawmatrix 0.1.23 → 0.2.1

package/src/tool-proxy.ts

@@ -1,10 +1,17 @@
 import type { PeerManager } from "./peer-manager.ts";
 import type { ClawMatrixConfig, ToolProxyConfig } from "./config.ts";
-import type { ToolProxyRequest, ToolProxyResponse } from "./types.ts";
+import type {
+  ToolProxyRequest,
+  ToolProxyResponse,
+  ToolBatchRequest,
+  ToolBatchResponse,
+  ToolBatchItem,
+  ToolBatchResultItem,
+} from "./types.ts";
 import type { PluginLogger } from "openclaw/plugin-sdk";
 import { isLocalTool, executeLocally } from "./local-tools.ts";
 
-const TOOL_TIMEOUT = 30_000;
+const DEFAULT_TOOL_TIMEOUT = 30_000;
 
 interface PendingToolReq {
   resolve: (result: Record<string, unknown>) => void;
@@ -12,6 +19,12 @@ interface PendingToolReq {
   timer: ReturnType<typeof setTimeout>;
 }
 
+interface PendingBatchReq {
+  resolve: (results: ToolBatchResultItem[]) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
 export interface GatewayInfo {
   port: number;
   authHeader?: string;
@@ -27,15 +40,18 @@ export class ToolProxy {
   private config: ClawMatrixConfig;
   private peerManager: PeerManager;
   private pending = new Map<string, PendingToolReq>();
+  private pendingBatch = new Map<string, PendingBatchReq>();
   private gatewayInfo: GatewayInfo;
   private logger: PluginLogger;
   private satelliteHandler: SatelliteToolHandler | null = null;
+  private readonly toolTimeout: number;
 
   constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo, logger: PluginLogger) {
     this.config = config;
     this.peerManager = peerManager;
     this.gatewayInfo = gatewayInfo;
     this.logger = logger;
+    this.toolTimeout = config.toolTimeout ?? DEFAULT_TOOL_TIMEOUT;
   }
 
   /** Set the satellite tool handler (called by ClusterRuntime after WebHandler is created). */
@@ -83,7 +99,7 @@ export class ToolProxy {
     };
 
     return new Promise((resolve, reject) => {
-      const timeoutMs = timeout ?? TOOL_TIMEOUT;
+      const timeoutMs = timeout ?? this.toolTimeout;
       const timer = setTimeout(() => {
         this.pending.delete(id);
         this.peerManager.router.markFailed(id);
@@ -187,6 +203,7 @@ export class ToolProxy {
       method: "POST",
       headers,
       body: JSON.stringify({ tool, args: params }),
+      signal: AbortSignal.timeout(this.toolTimeout),
     });
 
     if (!res.ok) {
@@ -215,6 +232,108 @@ export class ToolProxy {
       : { result: body.result };
   }
 
+  // ── Batch: request remote batch execution ─────────────────────
+  async invokeBatch(
+    node: string,
+    items: ToolBatchItem[],
+    options?: { stopOnError?: boolean; timeout?: number },
+  ): Promise<ToolBatchResultItem[]> {
+    const route = this.peerManager.router.resolveNode(node);
+    if (!route) throw new Error(`Node "${node}" not reachable`);
+
+    const id = crypto.randomUUID();
+    this.logger.info(`[clawmatrix] Tool batch: ${items.length} items -> node "${node}" (id=${id})`);
+    const frame: ToolBatchRequest = {
+      type: "tool_batch_req",
+      id,
+      from: this.config.nodeId,
+      to: route.nodeId,
+      timestamp: Date.now(),
+      payload: { items, stopOnError: options?.stopOnError ?? true },
+    };
+
+    return new Promise((resolve, reject) => {
+      const timeoutMs = options?.timeout ?? this.toolTimeout * items.length;
+      const timer = setTimeout(() => {
+        this.pendingBatch.delete(id);
+        reject(new Error(`Tool batch timed out on node "${node}"`));
+      }, timeoutMs);
+
+      this.pendingBatch.set(id, { resolve, reject, timer });
+
+      const sent = this.peerManager.sendTo(route.nodeId, frame);
+      if (!sent) {
+        this.pendingBatch.delete(id);
+        clearTimeout(timer);
+        reject(new Error(`Cannot reach node "${route.nodeId}"`));
+      }
+    });
+  }
+
+  // ── Incoming batch response ──────────────────────────────────
+  handleBatchResponse(frame: ToolBatchResponse) {
+    const pending = this.pendingBatch.get(frame.id);
+    if (!pending) return;
+
+    clearTimeout(pending.timer);
+    this.pendingBatch.delete(frame.id);
+    pending.resolve(frame.payload.results);
+  }
+
+  // ── Incoming batch request: execute sequentially via local Gateway ──
+  async handleBatchRequest(frame: ToolBatchRequest): Promise<void> {
+    const { id, from, payload } = frame;
+    const { items, stopOnError = true } = payload;
+    const toolProxyConfig = this.config.toolProxy;
+
+    if (!toolProxyConfig?.enabled) {
+      this.sendBatchResponse(id, from, [{
+        tool: items[0]?.tool ?? "unknown",
+        success: false,
+        error: "Tool proxy not enabled on this node",
+      }]);
+      return;
+    }
+
+    this.logger.info(`[clawmatrix] Tool batch request: ${items.length} items from="${from}" (id=${id})`);
+
+    const results: ToolBatchResultItem[] = [];
+    for (const item of items) {
+      if (!this.isToolAllowed(item.tool, toolProxyConfig)) {
+        this.logger.warn(`[clawmatrix] Tool batch denied: "${item.tool}" from="${from}"`);
+        results.push({ tool: item.tool, success: false, error: `Tool "${item.tool}" not allowed on this node` });
+        if (stopOnError) break;
+        continue;
+      }
+
+      try {
+        const result = isLocalTool(item.tool)
+          ? await executeLocally(item.tool, item.params)
+          : await this.executeViaGateway(item.tool, item.params);
+        results.push({ tool: item.tool, success: true, result });
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        this.logger.error(`[clawmatrix] Tool batch item failed: "${item.tool}" id=${id}: ${error}`);
+        results.push({ tool: item.tool, success: false, error });
+        if (stopOnError) break;
+      }
+    }
+
+    this.logger.info(`[clawmatrix] Tool batch done: id=${id} ${results.length}/${items.length} executed`);
+    this.sendBatchResponse(id, from, results);
+  }
+
+  private sendBatchResponse(id: string, to: string, results: ToolBatchResultItem[]) {
+    this.peerManager.sendTo(to, {
+      type: "tool_batch_res",
+      id,
+      from: this.config.nodeId,
+      to,
+      timestamp: Date.now(),
+      payload: { results },
+    } as ToolBatchResponse);
+  }
+
   // ── Security ───────────────────────────────────────────────────
   private isToolAllowed(tool: string, tpConfig: ToolProxyConfig): boolean {
     if (tpConfig.deny.includes(tool)) return false;
@@ -228,5 +347,10 @@ export class ToolProxy {
       pending.reject(new Error("Shutting down"));
     }
     this.pending.clear();
+    for (const [, pending] of this.pendingBatch) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Shutting down"));
+    }
+    this.pendingBatch.clear();
   }
 }

package/src/tools/cluster-acp.ts

@@ -0,0 +1,237 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+import type { AcpSessionMode } from "../types.ts";
+
+export function createClusterAcpTool(): AnyAgentTool {
+  return {
+    name: "cluster_acp",
+    label: "Cluster ACP Agent",
+    description:
+      "Run a task on a remote coding agent (Claude Code, Codex, Gemini CLI, etc.) via ACP protocol. " +
+      "Actions: " +
+      '"prompt" — send a task (one-shot or persistent session). ' +
+      '"list" — list all sessions on a remote node. ' +
+      '"resume" — resume an existing ACP session for follow-up prompts. ' +
+      '"cancel" — cancel an in-flight prompt on a session. ' +
+      '"set_mode" — switch session mode (e.g. "code", "architect", "ask"). ' +
+      '"get_modes" — get available modes for a session. ' +
+      '"close" — terminate a persistent session.',
+    parameters: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["prompt", "list", "resume", "cancel", "set_mode", "get_modes", "close"],
+          description: 'Action to perform. Default: "prompt"',
+        },
+        node: {
+          type: "string",
+          description: 'Target node ID or "tags:<tag>" expression',
+        },
+        agent: {
+          type: "string",
+          description: 'ACP agent name: "claude", "codex", "gemini", etc.',
+        },
+        task: {
+          type: "string",
+          description: "Task or prompt to send to the remote coding agent",
+        },
+        sessionId: {
+          type: "string",
+          description: "Session ID for follow-up prompts, cancel, set_mode, get_modes, or close",
+        },
+        acpSessionId: {
+          type: "string",
+          description: "ACP protocol session ID to resume (from list results)",
+        },
+        modeId: {
+          type: "string",
+          description: 'Session mode ID to set (e.g. "code", "architect", "ask")',
+        },
+        mode: {
+          type: "string",
+          enum: ["oneshot", "persistent"],
+          description: 'Session mode. "oneshot" (default) runs once, "persistent" keeps the session alive for follow-ups',
+        },
+        cwd: {
+          type: "string",
+          description: "Working directory on the remote node (absolute path)",
+        },
+      },
+      required: ["node"],
+    },
+    async execute(_toolCallId, params) {
+      const {
+        action = "prompt",
+        node,
+        agent,
+        task,
+        sessionId,
+        acpSessionId,
+        modeId,
+        mode,
+        cwd,
+      } = params as {
+        action?: "prompt" | "list" | "resume" | "cancel" | "set_mode" | "get_modes" | "close";
+        node: string;
+        agent?: string;
+        task?: string;
+        sessionId?: string;
+        acpSessionId?: string;
+        modeId?: string;
+        mode?: AcpSessionMode;
+        cwd?: string;
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+
+        if (!runtime.acpProxy) {
+          return {
+            content: [{ type: "text" as const, text: "ACP proxy not available (acp.enabled is false in config)" }],
+            details: { error: true },
+          };
+        }
+
+        const nodeId = resolveNodeId(runtime, node);
+
+        if (action === "list") {
+          const result = await runtime.acpProxy.listSessions(nodeId, { agent, cwd });
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+            details: result,
+          };
+        }
+
+        if (action === "resume") {
+          if (!acpSessionId) {
+            return {
+              content: [{ type: "text" as const, text: "acpSessionId is required for resume action (use list to find session IDs)" }],
+              details: { error: true },
+            };
+          }
+          if (!agent) {
+            return {
+              content: [{ type: "text" as const, text: "agent is required for resume action" }],
+              details: { error: true },
+            };
+          }
+          const result = await runtime.acpProxy.resumeSession(
+            nodeId, agent, acpSessionId, cwd ?? process.cwd(),
+          );
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+            details: result,
+          };
+        }
+
+        if (action === "cancel") {
+          if (!sessionId) {
+            return {
+              content: [{ type: "text" as const, text: "sessionId is required for cancel action" }],
+              details: { error: true },
+            };
+          }
+          const result = await runtime.acpProxy.cancelSession(nodeId, sessionId);
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+            details: result,
+          };
+        }
+
+        if (action === "set_mode") {
+          if (!sessionId) {
+            return {
+              content: [{ type: "text" as const, text: "sessionId is required for set_mode action" }],
+              details: { error: true },
+            };
+          }
+          if (!modeId) {
+            return {
+              content: [{ type: "text" as const, text: "modeId is required for set_mode action" }],
+              details: { error: true },
+            };
+          }
+          const result = await runtime.acpProxy.setSessionMode(nodeId, sessionId, modeId);
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+            details: result,
+          };
+        }
+
+        if (action === "get_modes") {
+          if (!sessionId) {
+            return {
+              content: [{ type: "text" as const, text: "sessionId is required for get_modes action" }],
+              details: { error: true },
+            };
+          }
+          const result = await runtime.acpProxy.getSessionModes(nodeId, sessionId);
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+            details: result,
+          };
+        }
+
+        if (action === "close") {
+          if (!sessionId) {
+            return {
+              content: [{ type: "text" as const, text: "sessionId is required for close action" }],
+              details: { error: true },
+            };
+          }
+          const result = await runtime.acpProxy.closeSession(nodeId, sessionId);
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+            details: result,
+          };
+        }
+
+        // action === "prompt"
+        if (!task && sessionId) {
+          return {
+            content: [{ type: "text" as const, text: "task is required for follow-up prompts" }],
+            details: { error: true },
+          };
+        }
+        if (!agent && !sessionId) {
+          return {
+            content: [{ type: "text" as const, text: "agent is required when starting a new session (no sessionId provided)" }],
+            details: { error: true },
+          };
+        }
+
+        const result = await runtime.acpProxy.prompt(
+          node, agent ?? "", task ?? "", { sessionId, mode, cwd },
+        );
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result) }],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `ACP 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-batch.ts

@@ -0,0 +1,76 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterBatchTool(): AnyAgentTool {
+  return {
+    name: "cluster_batch",
+    label: "Cluster Batch",
+    description:
+      "Execute multiple tools on a remote node in a single round-trip. " +
+      "Tools run sequentially (supports dependencies like read→edit). " +
+      "By default stops on first error; set stopOnError=false to continue.",
+    parameters: {
+      type: "object",
+      properties: {
+        node: {
+          type: "string",
+          description: 'Target nodeId or "tags:<tag>"',
+        },
+        items: {
+          type: "array",
+          description: "Array of tool invocations to execute in order",
+          items: {
+            type: "object",
+            properties: {
+              tool: { type: "string", description: "Tool name" },
+              params: { type: "object", description: "Tool arguments" },
+            },
+            required: ["tool", "params"],
+          },
+        },
+        stopOnError: {
+          type: "boolean",
+          description: "Stop on first error (default true)",
+        },
+      },
+      required: ["node", "items"],
+    },
+    async execute(_toolCallId, params) {
+      const { node, items, stopOnError } = params as {
+        node: string;
+        items: Array<{ tool: string; params: Record<string, unknown> }>;
+        stopOnError?: boolean;
+      };
+
+      if (!items || items.length === 0) {
+        return {
+          content: [{ type: "text" as const, text: "Error: items array is empty" }],
+          details: { error: true },
+        };
+      }
+
+      try {
+        const runtime = getClusterRuntime();
+        const results = await runtime.toolProxy.invokeBatch(node, items, { stopOnError });
+
+        const succeeded = results.filter((r) => r.success).length;
+        const summary = results.map((r, i) => {
+          if (r.success) {
+            return `[${i + 1}] ${r.tool}: OK\n${JSON.stringify(r.result)}`;
+          }
+          return `[${i + 1}] ${r.tool}: FAILED\n${r.error}`;
+        }).join("\n\n");
+
+        return {
+          content: [{ type: "text" as const, text: `${succeeded}/${items.length} succeeded\n\n${summary}` }],
+          details: { results },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Batch error: ${err instanceof Error ? err.message : String(err)}` }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-diagnostic.ts

@@ -0,0 +1,174 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+import type { ClusterRuntime } from "../cluster-service.ts";
+import { randomUUID } from "node:crypto";
+import type { AnyClusterFrame, DiagnosticExecResponse, DiagnosticStatusResponse } from "../types.ts";
+
+export function createClusterDiagnosticTool(): AnyAgentTool {
+  return {
+    name: "cluster_diagnostic",
+    label: "Cluster Diagnostic",
+    description:
+      "Diagnose or execute commands on a remote node's sentinel process. " +
+      "Works even when the remote OpenClaw gateway is down. " +
+      "Use action 'status' to check if the remote gateway is alive, " +
+      "or 'exec' to run a shell command on the remote machine.",
+    parameters: {
+      type: "object",
+      properties: {
+        node: {
+          type: "string",
+          description:
+            'Target nodeId. The sentinel is reached as "<nodeId>:sentinel".',
+        },
+        action: {
+          type: "string",
+          enum: ["status", "exec"],
+          description: '"status" to check gateway health, "exec" to run a command',
+        },
+        command: {
+          type: "string",
+          description: "Shell command to execute (required when action is exec)",
+        },
+        timeout: {
+          type: "number",
+          description: "Timeout in seconds (default 30)",
+        },
+      },
+      required: ["node", "action"],
+    },
+    async execute(_toolCallId: string, params: Record<string, unknown>) {
+      const { node, action, command, timeout = 30 } = params as {
+        node: string;
+        action: "status" | "exec";
+        command?: string;
+        timeout?: number;
+      };
+
+      const sentinelNodeId = node.endsWith(":sentinel") ? node : `${node}:sentinel`;
+
+      try {
+        const runtime = getClusterRuntime();
+        const router = runtime.peerManager.router;
+
+        // Check if sentinel is reachable
+        const route = router.getRoute(sentinelNodeId);
+        if (!route) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: `Sentinel "${sentinelNodeId}" is not reachable. The remote machine may be completely offline.`,
+            }],
+            details: { error: true },
+          };
+        }
+
+        const id = randomUUID();
+        const timeoutMs = timeout * 1000;
+
+        if (action === "status") {
+          const result = await sendAndWait<DiagnosticStatusResponse>(
+            runtime, sentinelNodeId, id,
+            {
+              type: "diagnostic_status",
+              id,
+              from: runtime.config.nodeId,
+              to: sentinelNodeId,
+              timestamp: Date.now(),
+            } as AnyClusterFrame,
+            "diagnostic_status_res",
+            timeoutMs,
+          );
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify(result.payload, null, 2),
+            }],
+            details: result.payload,
+          };
+        }
+
+        if (action === "exec") {
+          if (!command) {
+            return {
+              content: [{ type: "text" as const, text: "Missing 'command' parameter for exec action." }],
+              details: { error: true },
+            };
+          }
+          const result = await sendAndWait<DiagnosticExecResponse>(
+            runtime, sentinelNodeId, id,
+            {
+              type: "diagnostic_exec",
+              id,
+              from: runtime.config.nodeId,
+              to: sentinelNodeId,
+              timestamp: Date.now(),
+              payload: { command, timeout },
+            } as AnyClusterFrame,
+            "diagnostic_exec_res",
+            timeoutMs + 5_000, // extra overhead
+          );
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify(result.payload, null, 2),
+            }],
+            details: result.payload,
+          };
+        }
+
+        return {
+          content: [{ type: "text" as const, text: `Unknown action: ${action}` }],
+          details: { error: true },
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: `Diagnostic error: ${err instanceof Error ? err.message : String(err)}`,
+          }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}
+
+/** Send a frame to the sentinel and wait for the correlated response. */
+function sendAndWait<T>(
+  runtime: ClusterRuntime,
+  to: string,
+  id: string,
+  frame: AnyClusterFrame,
+  responseType: string,
+  timeoutMs: number,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error(`Diagnostic request timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const handler = (incoming: AnyClusterFrame) => {
+      if (incoming.type === responseType && incoming.id === id) {
+        cleanup();
+        resolve(incoming as unknown as T);
+      }
+    };
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      runtime.peerManager.off("frame", handler);
+    };
+
+    // Listen for response frames
+    runtime.peerManager.on("frame", handler);
+
+    // Route the frame to sentinel via router
+    const sent = runtime.peerManager.router.sendTo(to, frame);
+    if (!sent) {
+      cleanup();
+      reject(new Error(`No route to ${to}`));
+    }
+  });
+}