clawmatrix 0.1.0

package/src/connection.ts

@@ -0,0 +1,261 @@
+import { EventEmitter } from "node:events";
+import type {
+  AnyClusterFrame,
+  AuthChallenge,
+  AuthOk,
+  AuthFail,
+  ClusterFrame,
+  NodeCapabilities,
+} from "./types.ts";
+import { generateNonce, computeHmac, verifyHmac } from "./auth.ts";
+
+const HEARTBEAT_BASE = 12_000;
+const HEARTBEAT_JITTER = 6_000;
+const HEARTBEAT_TIMEOUT_COUNT = 3;
+
+export type ConnectionRole = "inbound" | "outbound";
+
+/** Minimal transport interface that works with both standard WebSocket and Bun's ServerWebSocket. */
+export interface WsTransport {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  readonly readyState: number;
+}
+
+export interface ConnectionEvents {
+  message: [frame: AnyClusterFrame];
+  authenticated: [capabilities: NodeCapabilities];
+  close: [code: number, reason: string];
+  error: [error: Error];
+}
+
+export class Connection extends EventEmitter<ConnectionEvents> {
+  readonly role: ConnectionRole;
+  private transport: WsTransport;
+  private nodeId: string;
+  private secret: string;
+  private localCapabilities: NodeCapabilities;
+
+  remoteNodeId: string | null = null;
+  remoteCapabilities: NodeCapabilities | null = null;
+  authenticated = false;
+
+  private heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
+  private missedPongs = 0;
+  private pendingNonce: string | null = null;
+  private closed = false;
+
+  constructor(
+    transport: WsTransport,
+    role: ConnectionRole,
+    nodeId: string,
+    secret: string,
+    localCapabilities: NodeCapabilities,
+  ) {
+    super();
+    this.transport = transport;
+    this.role = role;
+    this.nodeId = nodeId;
+    this.secret = secret;
+    this.localCapabilities = localCapabilities;
+
+    if (role === "inbound") {
+      this.sendAuthChallenge();
+    }
+  }
+
+  /** Bind standard WebSocket event listeners. Call this for outbound connections. */
+  bindWebSocket(ws: WebSocket) {
+    ws.addEventListener("message", (ev) => this.onRawMessage(ev.data));
+    ws.addEventListener("close", (ev) => {
+      this.close(ev.code, ev.reason);
+    });
+    ws.addEventListener("error", () => {
+      this.emit("error", new Error("WebSocket error"));
+    });
+  }
+
+  /** Feed a raw message into this connection (for Bun ServerWebSocket). */
+  feedMessage(data: string | Buffer) {
+    this.onRawMessage(data);
+  }
+
+  /** Notify this connection that the transport closed. */
+  feedClose(code: number, reason: string) {
+    this.close(code, reason);
+  }
+
+  // ── Handshake (server side) ────────────────────────────────────
+  private async sendAuthChallenge() {
+    const nonce = generateNonce();
+    this.pendingNonce = nonce;
+    this.sendRaw({
+      type: "auth_challenge",
+      from: this.nodeId,
+      timestamp: Date.now(),
+      payload: { nonce },
+    });
+  }
+
+  // ── Send helpers ───────────────────────────────────────────────
+  send(frame: ClusterFrame | AnyClusterFrame) {
+    if (this.closed) return;
+    this.sendRaw(frame);
+  }
+
+  private sendRaw(data: unknown) {
+    if (this.transport.readyState === WebSocket.OPEN) {
+      this.transport.send(JSON.stringify(data));
+    }
+  }
+
+  // ── Message dispatch ───────────────────────────────────────────
+  private async onRawMessage(data: unknown) {
+    let frame: AnyClusterFrame;
+    try {
+      frame = JSON.parse(typeof data === "string" ? data : String(data));
+    } catch {
+      return;
+    }
+
+    if (!this.authenticated) {
+      await this.handleAuthMessage(frame);
+      return;
+    }
+
+    if (frame.type === "ping") {
+      this.sendRaw({
+        type: "pong",
+        from: this.nodeId,
+        timestamp: Date.now(),
+      });
+      return;
+    }
+    if (frame.type === "pong") {
+      this.missedPongs = 0;
+      return;
+    }
+
+    this.emit("message", frame);
+  }
+
+  private async handleAuthMessage(frame: AnyClusterFrame) {
+    if (this.role === "inbound") {
+      if (frame.type !== "auth") return;
+      const { nodeId, sig } = frame.payload as { nodeId: string; sig: string };
+      if (!this.pendingNonce) return;
+
+      const valid = await verifyHmac(this.pendingNonce, this.secret, sig);
+      this.pendingNonce = null;
+
+      if (!valid) {
+        this.sendRaw({
+          type: "auth_fail",
+          from: this.nodeId,
+          timestamp: Date.now(),
+          payload: { reason: "Invalid signature" },
+        } satisfies AuthFail);
+        this.close(4001, "auth failed");
+        return;
+      }
+
+      this.remoteNodeId = nodeId;
+      this.authenticated = true;
+
+      this.sendRaw({
+        type: "auth_ok",
+        from: this.nodeId,
+        timestamp: Date.now(),
+        payload: {
+          nodeId: this.nodeId,
+          agents: this.localCapabilities.agents,
+          models: this.localCapabilities.models,
+          tags: this.localCapabilities.tags,
+        },
+      } satisfies AuthOk);
+
+      this.startHeartbeat();
+      this.emit("authenticated", {
+        nodeId,
+        agents: [],
+        models: [],
+        tags: [],
+      });
+    } else {
+      if (frame.type === "auth_challenge") {
+        const { nonce } = (frame as AuthChallenge).payload;
+        const sig = await computeHmac(nonce, this.secret);
+        this.sendRaw({
+          type: "auth",
+          from: this.nodeId,
+          timestamp: Date.now(),
+          payload: { nodeId: this.nodeId, sig },
+        });
+        return;
+      }
+
+      if (frame.type === "auth_ok") {
+        const ok = frame as AuthOk;
+        this.remoteNodeId = ok.payload.nodeId;
+        this.remoteCapabilities = {
+          nodeId: ok.payload.nodeId,
+          agents: ok.payload.agents,
+          models: ok.payload.models,
+          tags: ok.payload.tags,
+        };
+        this.authenticated = true;
+        this.startHeartbeat();
+        this.emit("authenticated", this.remoteCapabilities);
+        return;
+      }
+
+      if (frame.type === "auth_fail") {
+        const fail = frame as AuthFail;
+        this.emit("error", new Error(`Auth failed: ${fail.payload.reason}`));
+        this.close(4001, "auth failed");
+      }
+    }
+  }
+
+  // ── Heartbeat ──────────────────────────────────────────────────
+  private startHeartbeat() {
+    const scheduleNext = () => {
+      const interval = HEARTBEAT_BASE + Math.random() * HEARTBEAT_JITTER;
+      this.heartbeatTimer = setTimeout(() => {
+        if (this.closed) return;
+        this.missedPongs++;
+        if (this.missedPongs >= HEARTBEAT_TIMEOUT_COUNT) {
+          this.close(4002, "heartbeat timeout");
+          return;
+        }
+        this.sendRaw({
+          type: "ping",
+          from: this.nodeId,
+          timestamp: Date.now(),
+        });
+        scheduleNext();
+      }, interval);
+    };
+    scheduleNext();
+  }
+
+  // ── Cleanup ────────────────────────────────────────────────────
+  close(code = 1000, reason = "normal") {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.heartbeatTimer) {
+      clearTimeout(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    try {
+      this.transport.close(code, reason);
+    } catch {
+      // already closed
+    }
+    this.emit("close", code, reason);
+  }
+
+  get isOpen(): boolean {
+    return !this.closed && this.transport.readyState === WebSocket.OPEN;
+  }
+}

package/src/handoff.ts

@@ -0,0 +1,201 @@
+import type { PeerManager } from "./peer-manager.ts";
+import type { ClawMatrixConfig } from "./config.ts";
+import type {
+  HandoffRequest,
+  HandoffResponse,
+  AnyClusterFrame,
+} from "./types.ts";
+
+const HANDOFF_TIMEOUT = 120_000; // 2 minutes
+const MAX_RETRIES = 2;
+
+interface PendingHandoff {
+  resolve: (result: HandoffResponse["payload"]) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+  target: string;
+  retriesLeft: number;
+  task: string;
+  context?: string;
+}
+
+export class HandoffManager {
+  private config: ClawMatrixConfig;
+  private peerManager: PeerManager;
+  private pending = new Map<string, PendingHandoff>();
+
+  constructor(config: ClawMatrixConfig, peerManager: PeerManager) {
+    this.config = config;
+    this.peerManager = peerManager;
+  }
+
+  /** Send a handoff request and wait for the response. */
+  async handoff(
+    target: string,
+    task: string,
+    context?: string,
+  ): Promise<HandoffResponse["payload"]> {
+    const route = this.peerManager.router.resolveAgent(target);
+    if (!route) {
+      throw new Error(`No reachable agent for target "${target}"`);
+    }
+
+    return this.sendHandoff(route.nodeId, target, task, context, MAX_RETRIES);
+  }
+
+  private sendHandoff(
+    targetNodeId: string,
+    target: string,
+    task: string,
+    context: string | undefined,
+    retriesLeft: number,
+  ): Promise<HandoffResponse["payload"]> {
+    const id = crypto.randomUUID();
+
+    return new Promise<HandoffResponse["payload"]>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        this.peerManager.router.markFailed(id);
+
+        // Retry with failover
+        if (retriesLeft > 0) {
+          const nextRoute = this.peerManager.router.resolveAgent(target);
+          if (nextRoute && nextRoute.nodeId !== targetNodeId) {
+            this.sendHandoff(nextRoute.nodeId, target, task, context, retriesLeft - 1)
+              .then(resolve)
+              .catch(reject);
+            return;
+          }
+        }
+        reject(new Error(`Handoff to "${target}" timed out`));
+      }, HANDOFF_TIMEOUT);
+
+      this.pending.set(id, { resolve, reject, timer, target, retriesLeft, task, context });
+
+      const frame: HandoffRequest = {
+        type: "handoff_req",
+        id,
+        from: this.config.nodeId,
+        to: targetNodeId,
+        timestamp: Date.now(),
+        payload: { target, task, context },
+      };
+
+      const sent = this.peerManager.sendTo(targetNodeId, frame);
+      if (!sent) {
+        this.pending.delete(id);
+        clearTimeout(timer);
+
+        // Retry immediately with another node
+        if (retriesLeft > 0) {
+          const nextRoute = this.peerManager.router.resolveAgent(target);
+          if (nextRoute && nextRoute.nodeId !== targetNodeId) {
+            this.sendHandoff(nextRoute.nodeId, target, task, context, retriesLeft - 1)
+              .then(resolve)
+              .catch(reject);
+            return;
+          }
+        }
+        reject(new Error(`Cannot reach node "${targetNodeId}" for handoff`));
+      }
+    });
+  }
+
+  /** Handle incoming handoff response. */
+  handleResponse(frame: HandoffResponse) {
+    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);
+    pending.resolve(frame.payload);
+  }
+
+  /** Handle incoming handoff request (execute locally). */
+  async handleRequest(frame: HandoffRequest): Promise<void> {
+    const { id, from, payload } = frame;
+
+    // Find matching local agent
+    const agent = this.config.agents.find((a) => {
+      if (payload.target.startsWith("tags:")) {
+        const tag = payload.target.slice(5);
+        return a.tags.includes(tag);
+      }
+      return a.id === payload.target;
+    });
+
+    if (!agent) {
+      this.peerManager.sendTo(from, {
+        type: "handoff_res",
+        id,
+        from: this.config.nodeId,
+        to: from,
+        timestamp: Date.now(),
+        payload: {
+          success: false,
+          error: `No matching agent for "${payload.target}"`,
+        },
+      } satisfies HandoffResponse);
+      return;
+    }
+
+    try {
+      // Execute via openclaw agent subprocess
+      const message = payload.context
+        ? `${payload.task}\n\nContext:\n${payload.context}`
+        : payload.task;
+
+      const proc = Bun.spawn(["openclaw", "agent", "--message", message], {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const stdout = await new Response(proc.stdout).text();
+      const exitCode = await proc.exited;
+
+      if (exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text();
+        throw new Error(`Agent exited with code ${exitCode}: ${stderr}`);
+      }
+
+      this.peerManager.sendTo(from, {
+        type: "handoff_res",
+        id,
+        from: this.config.nodeId,
+        to: from,
+        timestamp: Date.now(),
+        payload: {
+          success: true,
+          nodeId: this.config.nodeId,
+          agent: agent.id,
+          result: stdout.trim(),
+        },
+      } satisfies HandoffResponse);
+    } catch (err) {
+      this.peerManager.sendTo(from, {
+        type: "handoff_res",
+        id,
+        from: this.config.nodeId,
+        to: from,
+        timestamp: Date.now(),
+        payload: {
+          success: false,
+          nodeId: this.config.nodeId,
+          agent: agent.id,
+          error: err instanceof Error ? err.message : String(err),
+        },
+      } satisfies HandoffResponse);
+    }
+  }
+
+  /** Clean up on shutdown. */
+  destroy() {
+    for (const [id, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Shutting down"));
+    }
+    this.pending.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,119 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { ClawMatrixConfigSchema, parseConfig } from "./config.ts";
+import { createClusterService, getClusterRuntime } from "./cluster-service.ts";
+import { createClusterHandoffTool } from "./tools/cluster-handoff.ts";
+import { createClusterSendTool } from "./tools/cluster-send.ts";
+import { createClusterPeersTool } from "./tools/cluster-peers.ts";
+import { createClusterExecTool } from "./tools/cluster-exec.ts";
+import { createClusterReadTool } from "./tools/cluster-read.ts";
+import { createClusterWriteTool } from "./tools/cluster-write.ts";
+import { createClusterLsTool } from "./tools/cluster-ls.ts";
+import { registerClusterCli } from "./cli.ts";
+
+const plugin = {
+  id: "clawmatrix",
+  name: "ClawMatrix",
+  description:
+    "Decentralized mesh cluster for inter-gateway communication, " +
+    "model proxy, task handoff, and tool proxy.",
+
+  configSchema: {
+    safeParse(value: unknown) {
+      const result = ClawMatrixConfigSchema.safeParse(value);
+      if (result.success) {
+        return { success: true, data: result.data };
+      }
+      return {
+        success: false,
+        error: {
+          issues: result.error.issues.map((i) => ({
+            path: i.path.map(String),
+            message: i.message,
+          })),
+        },
+      };
+    },
+  },
+
+  register(api: OpenClawPluginApi) {
+    const config = parseConfig(api.pluginConfig);
+
+    // Background service: manages mesh connections, WS listener, heartbeat
+    api.registerService(createClusterService(config));
+
+    // Model provider: register clawmatrix as a provider pointing to local HTTP proxy
+    api.registerProvider({
+      id: "clawmatrix",
+      label: "ClawMatrix Cluster",
+      docsPath: "/plugins/clawmatrix",
+      auth: [],
+      models: {
+        baseUrl: `http://127.0.0.1:${config.proxyPort}`,
+        api: "openai-completions",
+        models: getAllClusterModels(config),
+      },
+    });
+
+    // Agent tools
+    api.registerTool(createClusterHandoffTool(), { optional: true });
+    api.registerTool(createClusterSendTool(), { optional: true });
+    api.registerTool(createClusterPeersTool(), { optional: true });
+    api.registerTool(createClusterExecTool(), { optional: true });
+    api.registerTool(createClusterReadTool(), { optional: true });
+    api.registerTool(createClusterWriteTool(), { optional: true });
+    api.registerTool(createClusterLsTool(), { optional: true });
+
+    // CLI subcommand
+    api.registerCli(registerClusterCli, { commands: ["clawmatrix"] });
+
+    // Inject cluster context into agent prompts
+    api.on("before_prompt_build", () => {
+      try {
+        const runtime = getClusterRuntime();
+        const peers = runtime.peerManager.router.getAllPeers();
+        if (peers.length === 0) return;
+
+        const lines = [
+          `[ClawMatrix Cluster] This node: ${config.nodeId}`,
+          `Connected peers:`,
+        ];
+        for (const peer of peers) {
+          const agents = peer.agents.map((a) => a.id).join(", ") || "none";
+          const models = peer.models.map((m) => m.id).join(", ") || "none";
+          const status = peer.connection?.isOpen ? "connected" : "via relay";
+          lines.push(
+            `  - ${peer.nodeId} (${status}): agents=[${agents}], models=[${models}]`,
+          );
+        }
+        lines.push(
+          "",
+          "Available cluster tools: cluster_handoff, cluster_send, cluster_peers, " +
+            "cluster_exec, cluster_read, cluster_write, cluster_ls",
+        );
+
+        return { prependContext: lines.join("\n") };
+      } catch {
+        return;
+      }
+    });
+  },
+};
+
+function getAllClusterModels(config: ReturnType<typeof parseConfig>) {
+  // We register placeholder models from config.
+  // The actual model list is dynamic (from cluster peers),
+  // but we need to declare known models at registration time.
+  // The local HTTP proxy handles routing to the right cluster node.
+  return config.models.map((m) => ({
+    id: m.id,
+    name: m.id,
+    api: "openai-completions" as const,
+    reasoning: false,
+    input: ["text" as const],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128_000,
+    maxTokens: 4096,
+  }));
+}
+
+export default plugin;