clawmatrix 0.1.0

package/src/tool-proxy.ts

@@ -0,0 +1,324 @@
+import { readdir, stat } from "node:fs/promises";
+import { join, resolve, normalize } from "node:path";
+import type { PeerManager } from "./peer-manager.ts";
+import type { ClawMatrixConfig, ToolProxyConfig } from "./config.ts";
+import type { ToolProxyRequest, ToolProxyResponse } from "./types.ts";
+
+const TOOL_TIMEOUT = 30_000;
+
+interface PendingToolReq {
+  resolve: (result: Record<string, unknown>) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class ToolProxy {
+  private config: ClawMatrixConfig;
+  private peerManager: PeerManager;
+  private pending = new Map<string, PendingToolReq>();
+
+  constructor(config: ClawMatrixConfig, peerManager: PeerManager) {
+    this.config = config;
+    this.peerManager = peerManager;
+  }
+
+  // ── Outbound: request remote execution ─────────────────────────
+  async exec(
+    node: string,
+    command: string,
+    cwd?: string,
+    timeout?: number,
+  ): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+    const result = await this.sendToolReq(node, "exec", {
+      command,
+      cwd,
+      timeout: timeout ?? TOOL_TIMEOUT,
+    });
+    return result as { exitCode: number; stdout: string; stderr: string };
+  }
+
+  async read(node: string, path: string): Promise<{ content: string }> {
+    const result = await this.sendToolReq(node, "read", { path });
+    return result as { content: string };
+  }
+
+  async write(
+    node: string,
+    path: string,
+    content: string,
+  ): Promise<{ success: boolean }> {
+    const result = await this.sendToolReq(node, "write", { path, content });
+    return result as { success: boolean };
+  }
+
+  async ls(
+    node: string,
+    path: string,
+  ): Promise<{ entries: { name: string; type: "file" | "dir"; size: number }[] }> {
+    const result = await this.sendToolReq(node, "ls", { path });
+    return result as { entries: { name: string; type: "file" | "dir"; size: number }[] };
+  }
+
+  private async sendToolReq(
+    node: string,
+    tool: ToolProxyRequest["payload"]["tool"],
+    params: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    const route = this.peerManager.router.resolveNode(node);
+    if (!route) throw new Error(`Node "${node}" not reachable`);
+
+    const id = crypto.randomUUID();
+    const frame: ToolProxyRequest = {
+      type: "tool_req",
+      id,
+      from: this.config.nodeId,
+      to: route.nodeId,
+      timestamp: Date.now(),
+      payload: { tool, params },
+    };
+
+    return new Promise((resolve, reject) => {
+      const timeoutMs = (params.timeout as number | undefined) ?? TOOL_TIMEOUT;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        this.peerManager.router.markFailed(id);
+        reject(new Error(`Tool "${tool}" timed out on node "${node}"`));
+      }, timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+
+      const sent = this.peerManager.sendTo(route.nodeId, frame);
+      if (!sent) {
+        this.pending.delete(id);
+        clearTimeout(timer);
+        reject(new Error(`Cannot reach node "${route.nodeId}"`));
+      }
+    });
+  }
+
+  // ── Incoming response ──────────────────────────────────────────
+  handleResponse(frame: ToolProxyResponse) {
+    if (this.peerManager.router.isFailed(frame.id)) return;
+    const pending = this.pending.get(frame.id);
+    if (!pending) return;
+
+    clearTimeout(pending.timer);
+    this.pending.delete(frame.id);
+
+    if (frame.payload.success && frame.payload.result) {
+      pending.resolve(frame.payload.result);
+    } else {
+      pending.reject(new Error(frame.payload.error ?? "Remote tool execution failed"));
+    }
+  }
+
+  // ── Incoming request: execute locally ──────────────────────────
+  async handleRequest(frame: ToolProxyRequest): Promise<void> {
+    const { id, from, payload } = frame;
+    const toolProxyConfig = this.config.toolProxy;
+
+    // Check if tool proxy is enabled
+    if (!toolProxyConfig?.enabled) {
+      this.sendResponse(id, from, {
+        success: false,
+        error: "Tool proxy not enabled on this node",
+      });
+      return;
+    }
+
+    // Check tool allowlist/denylist
+    if (!this.isToolAllowed(payload.tool, toolProxyConfig)) {
+      this.sendResponse(id, from, {
+        success: false,
+        error: `Tool "${payload.tool}" not allowed on this node`,
+      });
+      return;
+    }
+
+    try {
+      let result: Record<string, unknown>;
+
+      switch (payload.tool) {
+        case "exec":
+          result = await this.executeExec(payload.params, toolProxyConfig);
+          break;
+        case "read":
+          result = await this.executeRead(payload.params, toolProxyConfig);
+          break;
+        case "write":
+          result = await this.executeWrite(payload.params, toolProxyConfig);
+          break;
+        case "ls":
+          result = await this.executeLs(payload.params, toolProxyConfig);
+          break;
+        default:
+          throw new Error(`Unknown tool: ${payload.tool}`);
+      }
+
+      this.sendResponse(id, from, { success: true, result });
+    } catch (err) {
+      this.sendResponse(id, from, {
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  private sendResponse(
+    id: string,
+    to: string,
+    payload: ToolProxyResponse["payload"],
+  ) {
+    this.peerManager.sendTo(to, {
+      type: "tool_res",
+      id,
+      from: this.config.nodeId,
+      to,
+      timestamp: Date.now(),
+      payload,
+    } as ToolProxyResponse);
+  }
+
+  // ── Local execution ────────────────────────────────────────────
+  private async executeExec(
+    params: Record<string, unknown>,
+    tpConfig: ToolProxyConfig,
+  ): Promise<Record<string, unknown>> {
+    const command = params.command as string;
+    if (!command) throw new Error("Missing command");
+
+    // Check exec allowlist
+    if (tpConfig.execAllowlist.length > 0) {
+      const base = command.split(/\s+/)[0]!;
+      if (!tpConfig.execAllowlist.includes(base)) {
+        throw new Error(`Command "${base}" not in exec allowlist`);
+      }
+    }
+
+    const cwd = (params.cwd as string) ?? process.cwd();
+    const timeout = (params.timeout as number) ?? TOOL_TIMEOUT;
+
+    const proc = Bun.spawn(["sh", "-c", command], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const timeoutId = setTimeout(() => proc.kill(), timeout);
+
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const exitCode = await proc.exited;
+    clearTimeout(timeoutId);
+
+    const maxBytes = tpConfig.maxOutputBytes;
+    return {
+      exitCode,
+      stdout: stdout.slice(0, maxBytes),
+      stderr: stderr.slice(0, maxBytes),
+    };
+  }
+
+  private async executeRead(
+    params: Record<string, unknown>,
+    tpConfig: ToolProxyConfig,
+  ): Promise<Record<string, unknown>> {
+    const path = params.path as string;
+    if (!path) throw new Error("Missing path");
+    this.validatePath(path, tpConfig);
+
+    const file = Bun.file(path);
+    const content = await file.text();
+    return {
+      content: content.slice(0, tpConfig.maxOutputBytes),
+    };
+  }
+
+  private async executeWrite(
+    params: Record<string, unknown>,
+    tpConfig: ToolProxyConfig,
+  ): Promise<Record<string, unknown>> {
+    const path = params.path as string;
+    const content = params.content as string;
+    if (!path || content === undefined) throw new Error("Missing path or content");
+    this.validatePath(path, tpConfig);
+
+    await Bun.write(path, content);
+    return { success: true };
+  }
+
+  private async executeLs(
+    params: Record<string, unknown>,
+    tpConfig: ToolProxyConfig,
+  ): Promise<Record<string, unknown>> {
+    const path = params.path as string;
+    if (!path) throw new Error("Missing path");
+    this.validatePath(path, tpConfig);
+
+    const dirEntries = await readdir(path, { withFileTypes: true });
+    const entries: { name: string; type: "file" | "dir"; size: number }[] = [];
+
+    for (const entry of dirEntries) {
+      const fullPath = join(path, entry.name);
+      try {
+        const st = await stat(fullPath);
+        entries.push({
+          name: entry.name,
+          type: entry.isDirectory() ? "dir" : "file",
+          size: Number(st.size),
+        });
+      } catch {
+        entries.push({
+          name: entry.name,
+          type: entry.isDirectory() ? "dir" : "file",
+          size: 0,
+        });
+      }
+    }
+
+    return { entries };
+  }
+
+  // ── Security ───────────────────────────────────────────────────
+  private isToolAllowed(
+    tool: string,
+    tpConfig: ToolProxyConfig,
+  ): boolean {
+    if (tpConfig.deny.includes(tool as "exec" | "read" | "write" | "ls")) return false;
+    if (tpConfig.allow.length > 0) {
+      return tpConfig.allow.includes(tool as "exec" | "read" | "write" | "ls");
+    }
+    return true;
+  }
+
+  private validatePath(path: string, tpConfig: ToolProxyConfig) {
+    const normalized = normalize(resolve(path));
+
+    // Check deny paths first
+    for (const denied of tpConfig.denyPaths) {
+      if (normalized.startsWith(normalize(resolve(denied)))) {
+        throw new Error(`Path "${path}" is in denied path prefix`);
+      }
+    }
+
+    // Check allow paths
+    if (tpConfig.allowPaths.length > 0) {
+      const allowed = tpConfig.allowPaths.some((p) =>
+        normalized.startsWith(normalize(resolve(p))),
+      );
+      if (!allowed) {
+        throw new Error(`Path "${path}" is not in allowed path prefixes`);
+      }
+    }
+  }
+
+  destroy() {
+    for (const [, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Shutting down"));
+    }
+    this.pending.clear();
+  }
+}

package/src/tools/cluster-exec.ts

@@ -0,0 +1,66 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterExecTool(): AnyAgentTool {
+  return {
+    name: "cluster_exec",
+    label: "Cluster Exec",
+    description:
+      "Execute a shell command on a remote cluster node. " +
+      "Use nodeId or 'tags:<tag>' to specify the target.",
+    parameters: {
+      type: "object",
+      properties: {
+        node: {
+          type: "string",
+          description: 'Target nodeId or "tags:<tag>"',
+        },
+        command: {
+          type: "string",
+          description: "Shell command to execute",
+        },
+        cwd: {
+          type: "string",
+          description: "Working directory (optional)",
+        },
+        timeout: {
+          type: "number",
+          description: "Timeout in milliseconds (default 30000)",
+        },
+      },
+      required: ["node", "command"],
+    },
+    async execute(_toolCallId, params) {
+      const { node, command, cwd, timeout } = params as {
+        node: string;
+        command: string;
+        cwd?: string;
+        timeout?: number;
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+        const result = await runtime.toolProxy.exec(node, command, cwd, timeout);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Exec error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-handoff.ts

@@ -0,0 +1,82 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterHandoffTool(): AnyAgentTool {
+  return {
+    name: "cluster_handoff",
+    label: "Cluster Handoff",
+    description:
+      "Hand off a task to another agent in the cluster and wait for the result. " +
+      "Use agent ID (e.g. 'coder') or tag query (e.g. 'tags:coding') as target.",
+    parameters: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: 'Agent ID or "tags:<tag>" expression',
+        },
+        task: {
+          type: "string",
+          description: "Task description for the remote agent",
+        },
+        context: {
+          type: "string",
+          description: "Additional context for the task",
+        },
+      },
+      required: ["target", "task"],
+    },
+    async execute(_toolCallId, params) {
+      const { target, task, context } = params as {
+        target: string;
+        task: string;
+        context?: string;
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+        const result = await runtime.handoffManager.handoff(target, task, context);
+
+        if (!result.success) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Handoff failed: ${result.error}`,
+              },
+            ],
+            details: result,
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  nodeId: result.nodeId,
+                  agent: result.agent,
+                  result: result.result,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Handoff error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-ls.ts

@@ -0,0 +1,51 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterLsTool(): AnyAgentTool {
+  return {
+    name: "cluster_ls",
+    label: "Cluster Ls",
+    description: "List directory contents on a remote cluster node.",
+    parameters: {
+      type: "object",
+      properties: {
+        node: {
+          type: "string",
+          description: 'Target nodeId or "tags:<tag>"',
+        },
+        path: {
+          type: "string",
+          description: "Absolute directory path to list",
+        },
+      },
+      required: ["node", "path"],
+    },
+    async execute(_toolCallId, params) {
+      const { node, path } = params as { node: string; path: string };
+
+      try {
+        const runtime = getClusterRuntime();
+        const result = await runtime.toolProxy.ls(node, path);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(result.entries, null, 2),
+            },
+          ],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Ls error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-peers.ts

@@ -0,0 +1,55 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterPeersTool(): AnyAgentTool {
+  return {
+    name: "cluster_peers",
+    label: "Cluster Peers",
+    description:
+      "List all reachable peers in the cluster, their agents, available models, and connection status.",
+    parameters: {
+      type: "object",
+      properties: {},
+    },
+    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) => ({
+            id: m.id,
+            provider: m.provider,
+          })),
+          tags: entry.tags,
+          status: entry.connection?.isOpen ? "connected" : "unreachable",
+          latencyMs: entry.latencyMs,
+        }));
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(peers, null, 2),
+            },
+          ],
+          details: peers,
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-read.ts

@@ -0,0 +1,48 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterReadTool(): AnyAgentTool {
+  return {
+    name: "cluster_read",
+    label: "Cluster Read",
+    description: "Read a file from a remote cluster node.",
+    parameters: {
+      type: "object",
+      properties: {
+        node: {
+          type: "string",
+          description: 'Target nodeId or "tags:<tag>"',
+        },
+        path: {
+          type: "string",
+          description: "Absolute file path to read",
+        },
+      },
+      required: ["node", "path"],
+    },
+    async execute(_toolCallId, params) {
+      const { node, path } = params as { node: string; path: string };
+
+      try {
+        const runtime = getClusterRuntime();
+        const result = await runtime.toolProxy.read(node, path);
+        return {
+          content: [
+            { type: "text" as const, text: result.content },
+          ],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Read error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-send.ts

@@ -0,0 +1,79 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterSendTool(): AnyAgentTool {
+  return {
+    name: "cluster_send",
+    label: "Cluster Send",
+    description:
+      "Send a one-way message to another agent in the cluster. " +
+      "The message is injected into the target agent's session as an inbound message. " +
+      "Does not wait for a response.",
+    parameters: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: 'Agent ID or "tags:<tag>" expression',
+        },
+        message: {
+          type: "string",
+          description: "Message content to send",
+        },
+      },
+      required: ["target", "message"],
+    },
+    async execute(_toolCallId, params) {
+      const { target, message } = params as {
+        target: string;
+        message: string;
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+        const route = runtime.peerManager.router.resolveAgent(target);
+        if (!route) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `No reachable agent for target "${target}"`,
+              },
+            ],
+            details: { error: true },
+          };
+        }
+
+        const sent = runtime.peerManager.sendTo(route.nodeId, {
+          type: "send",
+          from: runtime.config.nodeId,
+          to: route.nodeId,
+          timestamp: Date.now(),
+          payload: { target, message },
+        });
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: sent
+                ? `Message sent to ${target} on node ${route.nodeId}`
+                : `Failed to deliver message to ${target}`,
+            },
+          ],
+          details: { sent, nodeId: route.nodeId },
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Send error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}