clawmatrix 0.2.9 → 0.3.1

package/src/cluster-service.ts

@@ -14,6 +14,7 @@ import { ModelProxy } from "./model-proxy.ts";
 import { ToolProxy, type GatewayInfo } from "./tool-proxy.ts";
 import { AcpProxy, readAllSessionStoresFromDisk } from "./acp-proxy.ts";
 import { TerminalManager } from "./terminal.ts";
+import { FileTransferManager } from "./file-transfer.ts";
 import { WebHandler } from "./web.ts";
 import { KnowledgeSync } from "./knowledge-sync.ts";
 import { HealthTracker } from "./health-tracker.ts";
@@ -30,6 +31,8 @@ import type {
   HandoffInput,
   KnowledgeSyncFrame,
   HealthSyncFrame,
+  AvailabilityRequest,
+  AvailabilityResponse,
   ModelRequest,
   ModelResponse,
   ModelStreamChunk,
@@ -63,6 +66,11 @@ import type {
   TerminalResize,
   TerminalCloseRequest,
   TerminalCloseResponse,
+  FileTransferInit,
+  FileTransferAck,
+  FileTransferChunk,
+  FileTransferChunkAck,
+  FileTransferComplete,
 } from "./types.ts";
 
 function resolveGatewayInfo(openclawConfig: OpenClawConfig): GatewayInfo {
@@ -86,6 +94,7 @@ export class ClusterRuntime {
   readonly toolProxy: ToolProxy;
   readonly acpProxy: AcpProxy | null;
   readonly terminalManager: TerminalManager;
+  readonly fileTransferManager: FileTransferManager | null;
   knowledgeSync: KnowledgeSync | null = null;
   healthTracker: HealthTracker;
   webHandler: WebHandler | null = null;
@@ -93,6 +102,9 @@ export class ClusterRuntime {
   private logger: PluginLogger;
   private openclawConfig: OpenClawConfig;
   private exitHandler: (() => void) | null = null;
+  // Pre-built indexes for O(1) local agent lookup
+  private agentById = new Map<string, ClawMatrixConfig["agents"][number]>();
+  private agentsByTag = new Map<string, ClawMatrixConfig["agents"][number]>();
 
   constructor(config: ClawMatrixConfig, logger: PluginLogger, openclawConfig: OpenClawConfig, openclawVersion?: string) {
     this.config = config;
@@ -107,13 +119,21 @@ export class ClusterRuntime {
     const acpEnabled = config.acp?.enabled || (openclawConfig as Record<string, any>).acp?.enabled;
     this.acpProxy = acpEnabled ? new AcpProxy(config, this.peerManager, openclawConfig as Record<string, unknown>, gatewayInfo) : null;
     this.terminalManager = new TerminalManager(config, this.peerManager);
+    this.fileTransferManager = config.fileTransfer?.enabled
+      ? new FileTransferManager(config, this.peerManager)
+      : null;
     this.healthTracker = new HealthTracker({
       nodeId: config.nodeId,
       peerManager: this.peerManager,
     });
+    // Build agent indexes
+    for (const a of config.agents) {
+      this.agentById.set(a.id, a);
+      for (const t of a.tags) this.agentsByTag.set(t, a);
+    }
   }
 
-  start() {
+  async start() {
     // Wire up frame dispatch
     this.peerManager.on("frame", (frame) => {
       this.dispatchFrame(frame);
@@ -195,14 +215,31 @@ export class ClusterRuntime {
       this.logger.error(`[clawmatrix] Health tracker failed to start: ${err}`);
     });
 
-    // Start subsystems
-    this.peerManager.start();
-    this.modelProxy.start();
-
     // Sentinel: detached subprocess for diagnostics when gateway dies.
     // Default on; starts when not explicitly disabled AND (has outbound peers OR gateway is a listener for port takeover)
-    if ((this.config.sentinel?.enabled ?? true) && (this.config.peers.length > 0 || this.config.listen)) {
+    const sentinelEnabled = (this.config.sentinel?.enabled ?? true) && (this.config.peers.length > 0 || this.config.listen);
+    if (sentinelEnabled) {
       this.sentinelManager = new SentinelManager(this.config);
+      // Kill old sentinel and wait for the listen port to be released
+      // before PeerManager tries to bind it.
+      await this.sentinelManager.ensurePortFree();
+    }
+
+    // Start subsystems (port is now guaranteed free)
+    this.peerManager.start();
+    this.modelProxy.start();
+
+    // Fetch tool catalog from the local gateway (non-blocking).
+    // The catalog (tool names, descriptions) is advertised to peers via peer_sync
+    // so remote LLM callers can discover available tools.
+    if (this.config.toolProxy?.enabled) {
+      this.fetchToolCatalog().catch((err) => {
+        this.logger.warn(`[clawmatrix] Tool catalog fetch failed (non-fatal): ${err}`);
+      });
+    }
+
+    // Spawn the new sentinel after PeerManager is listening
+    if (sentinelEnabled && this.sentinelManager) {
       this.sentinelManager.start();
       this.logger.info(`[clawmatrix] Sentinel started for node "${this.config.nodeId}"`);
     }
@@ -238,6 +275,7 @@ export class ClusterRuntime {
     this.acpProxy?.destroy();
     this.terminalManager.destroy();
     this.modelProxy.stop();
+    this.fileTransferManager?.destroy();
     this.toolProxy.destroy();
     await this.peerManager.stop();
     this.logger.info(`[clawmatrix] Node "${this.config.nodeId}" stopped`);
@@ -248,6 +286,61 @@ export class ClusterRuntime {
     this.modelProxy.updateDiscoveredModels(peers);
   }
 
+  /** Fetch tool catalog from the local OpenClaw gateway and advertise to peers. */
+  private async fetchToolCatalog() {
+    const { spawnProcess } = await import("./compat.ts");
+    const proc = spawnProcess(
+      ["openclaw", "gateway", "call", "tools.catalog", "--json", "--params", '{"includePlugins":true}'],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const chunks: Uint8Array[] = [];
+    if (proc.stdout) {
+      const reader = proc.stdout.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+      }
+    }
+    const code = await proc.exited;
+    if (code !== 0) return;
+
+    const stdout = Buffer.concat(chunks).toString("utf-8").trim();
+    if (!stdout) return;
+    // stdout may contain non-JSON log lines (e.g. "[plugins] ...") before the actual JSON.
+    // Extract the first JSON object from the output.
+    const jsonStart = stdout.indexOf("{");
+    if (jsonStart < 0) return;
+    const data = JSON.parse(stdout.slice(jsonStart)) as {
+      groups?: Array<{
+        tools: Array<{ id: string; label: string; description: string }>;
+      }>;
+    };
+    if (!data.groups) return;
+
+    const allowSet = new Set(this.config.toolProxy?.allow ?? []);
+    const isWildcard = allowSet.has("*") || allowSet.size === 0;
+    const denySet = new Set(this.config.toolProxy?.deny ?? []);
+    const catalog: import("./types.ts").ToolCatalogEntry[] = [];
+    for (const group of data.groups) {
+      for (const tool of group.tools) {
+        if (denySet.has(tool.id)) continue;
+        if (!isWildcard && !allowSet.has(tool.id)) continue;
+        // Skip clawmatrix's own cluster_ tools (they're the invoker, not the invokee)
+        if (tool.id.startsWith("cluster_")) continue;
+        catalog.push({
+          name: tool.id,
+          description: tool.description,
+        });
+      }
+    }
+
+    if (catalog.length > 0) {
+      this.peerManager.updateToolCatalog(catalog);
+      this.logger.info(`[clawmatrix] Tool catalog: ${catalog.length} tool(s) advertised to peers`);
+    }
+  }
+
   private resolveWorkspacePath(): string | null {
     // Read workspace from OpenClaw agent config (first agent or default agent)
     const agents = (this.openclawConfig as Record<string, unknown>).agents as
@@ -338,6 +431,20 @@ export class ClusterRuntime {
       case "health_sync":
         this.healthTracker.handleSyncMessage(frame as HealthSyncFrame);
         break;
+      case "availability_req": {
+        const af = frame as AvailabilityRequest;
+        const range = af.payload.range ?? "24h";
+        const data = this.healthTracker.getAvailability(range);
+        this.peerManager.sendTo(af.from, {
+          type: "availability_res",
+          id: af.id,
+          from: this.config.nodeId,
+          to: af.from,
+          timestamp: Date.now(),
+          payload: { success: true, data },
+        } as AvailabilityResponse);
+        break;
+      }
       case "acp_req":
         if (this.acpProxy) {
           this.acpProxy.handleRequest(frame as AcpTaskRequest).catch((err) => {
@@ -464,6 +571,29 @@ export class ClusterRuntime {
       case "acp_get_modes_res":
         this.acpProxy?.handleGetModesResponse(frame as AcpGetModesResponse);
         break;
+      case "acp_set_config":
+        if (this.acpProxy) {
+          this.acpProxy.handleSetConfigRequest(frame as import("./types.ts").AcpSetConfigRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP set config error: ${err}`);
+          });
+        }
+        break;
+      case "acp_set_config_res":
+        this.acpProxy?.handleSetConfigResponse(frame as import("./types.ts").AcpSetConfigResponse);
+        break;
+      case "acp_subscribe":
+        if (this.acpProxy) {
+          this.acpProxy.handleSubscribeRequest(frame as import("./types.ts").AcpSubscribeRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP subscribe error: ${err}`);
+          });
+        }
+        break;
+      case "acp_unsubscribe":
+        this.acpProxy?.handleUnsubscribeRequest(frame as import("./types.ts").AcpUnsubscribeRequest);
+        break;
+      case "acp_session_notify":
+        // Outbound notification — no server-side handling needed.
+        break;
       case "chat_history_req":
         if (this.acpProxy) {
           this.acpProxy.handleChatHistoryRequest(frame as ChatHistoryRequest).catch((err) => {
@@ -494,18 +624,32 @@ export class ClusterRuntime {
           frame as TerminalOpenRequest | TerminalOpenResponse | TerminalData | TerminalResize | TerminalCloseRequest | TerminalCloseResponse,
         );
         break;
+      case "file_transfer_init":
+        this.fileTransferManager?.handleInit(frame as FileTransferInit).catch((err) => {
+          this.logger.error(`[clawmatrix] File transfer init error: ${err}`);
+        });
+        break;
+      case "file_transfer_ack":
+        this.fileTransferManager?.handleAck(frame as FileTransferAck);
+        break;
+      case "file_transfer_chunk":
+        this.fileTransferManager?.handleChunk(frame as FileTransferChunk);
+        break;
+      case "file_transfer_chunk_ack":
+        this.fileTransferManager?.handleChunkAck(frame as FileTransferChunkAck);
+        break;
+      case "file_transfer_complete":
+        this.fileTransferManager?.handleComplete(frame as FileTransferComplete);
+        break;
     }
   }
 
   private handleSendMessage(frame: SendMessage) {
     // Inject message into local agent session via openclaw CLI
     const { target, message } = frame.payload;
-    const agent = this.config.agents.find((a) => {
-      if (target.startsWith("tags:")) {
-        return a.tags.includes(target.slice(5));
-      }
-      return a.id === target;
-    });
+    const agent = target.startsWith("tags:")
+      ? this.agentsByTag.get(target.slice(5))
+      : this.agentById.get(target);
 
     if (!agent) {
       this.logger.warn(
@@ -543,9 +687,9 @@ export function createClusterService(
 ): OpenClawPluginService {
   return {
     id: "clawmatrix",
-    start(ctx: OpenClawPluginServiceContext) {
+    async start(ctx: OpenClawPluginServiceContext) {
       clusterRuntime = new ClusterRuntime(config, ctx.logger, openclawConfig, openclawVersion);
-      clusterRuntime.start();
+      await clusterRuntime.start();
       onStarted?.();
     },
     async stop() {

package/src/compat.ts

@@ -8,12 +8,6 @@ import { spawn as cpSpawn } from "node:child_process";
 import { open, readFile, stat, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 
-export interface SpawnResult {
-  exitCode: number;
-  stdout: string;
-  stderr: string;
-}
-
 /** Spawn a subprocess and collect stdout/stderr. */
 export function spawnProcess(
   cmd: string[],

package/src/config.ts

@@ -134,6 +134,14 @@ const TerminalConfigSchema = z.object({
   allowFrom: z.array(z.string()).default([]),
 }).optional();
 
+const FileTransferConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  chunkSize: z.number().default(262_144),       // 256KB
+  maxFileSize: z.number().default(104_857_600),  // 100MB
+  timeout: z.number().default(300_000),          // 5min per-chunk
+  allowedPaths: z.array(z.string()).default([]), // empty = no restriction
+}).optional();
+
 const AcpConfigSchema = z.object({
   enabled: z.boolean().default(false),
   /** ACP agents available on this node. Advertised to peers via capabilities. */
@@ -153,22 +161,26 @@ const RawClawMatrixConfigSchema = z.object({
   secret: z.string().min(16, "secret must be at least 16 characters"),
   listen: z.boolean().default(false),
   listenHost: z.string().default("0.0.0.0"),
-  listenPort: z.number().default(0),
+  listenPort: z.number().int().min(0).max(65535).default(0),
   peers: z.array(PeerConfigSchema).default([]),
   agents: z.array(AgentInfoSchema).default([]),
   models: z.array(ModelInfoSchema).default([]),
   proxyModels: z.array(ProxyModelGroupSchema).default([]),
   tags: z.array(z.string()).default([]),
-  proxyPort: z.number().default(0),
+  proxyPort: z.number().int().min(0).max(65535).default(0),
   toolProxy: ToolProxyConfigSchema.optional(),
-  handoffTimeout: z.number().default(600_000),
-  modelTimeout: z.number().default(120_000),
-  toolTimeout: z.number().default(30_000),
+  handoffTimeout: z.number().positive().default(600_000),
+  modelTimeout: z.number().positive().default(120_000),
+  toolTimeout: z.number().positive().default(30_000),
+  /** Grace period (ms) before broadcasting peer_leave after disconnect.
+   *  Allows brief reconnections (WiFi/cellular handoff) to be invisible to the mesh. */
+  disconnectGrace: z.number().nonnegative().default(30_000),
   sentinel: SentinelConfigSchema,
   web: WebConfigSchema,
   knowledge: KnowledgeConfigSchema,
   terminal: TerminalConfigSchema,
   acp: AcpConfigSchema,
+  fileTransfer: FileTransferConfigSchema,
   peerApproval: z.union([
     z.boolean(),           // true = required mode, false = disabled
     PeerApprovalConfigSchema,

package/src/connection.ts

@@ -485,70 +485,76 @@ export class Connection extends EventEmitter<ConnectionEvents> {
 
   private startHeartbeat() {
     this.lastReceivedAt = Date.now();
-    const scheduleNext = () => {
-      const interval = HEARTBEAT_BASE + Math.random() * HEARTBEAT_JITTER;
-      this.heartbeatTimer = setTimeout(() => {
-        if (this.closed) return;
-
-        // Watchdog: if no data received for a long time, the connection is dead
-        // regardless of what the heartbeat ping/pong state says.
-        const silenceMs = Date.now() - this.lastReceivedAt;
-        if (this.lastReceivedAt > 0 && silenceMs > Connection.RECEIVE_TIMEOUT) {
-          debug("heartbeat", `No data received for ${Math.round(silenceMs / 1000)}s from ${this.remoteNodeId ?? "unknown"}, closing`);
-          this.close(4002, "receive timeout");
-          return;
-        }
+    this.scheduleHeartbeatTick();
+  }
 
-        // Increment before checking: this ping is about to be sent and
-        // counts as outstanding until a pong arrives.
-        this.missedPongs++;
-        if (this.missedPongs >= HEARTBEAT_TIMEOUT_COUNT) {
-          debug("heartbeat", `${HEARTBEAT_TIMEOUT_COUNT} missed pongs from ${this.remoteNodeId ?? "unknown"}, closing`);
-          this.close(4002, "heartbeat timeout");
-          return;
-        }
+  private scheduleHeartbeatTick() {
+    const interval = HEARTBEAT_BASE + Math.random() * HEARTBEAT_JITTER;
+    this.heartbeatTimer = setTimeout(this.heartbeatTick, interval);
+  }
 
-        // Send ping — wrapped in try-catch to prevent breaking the heartbeat chain.
-        // If send fails, the connection is dead; close it.
-        try {
-          if (this.transport.readyState !== WebSocket.OPEN) {
-            debug("heartbeat", `Transport not open (state=${this.transport.readyState}) for ${this.remoteNodeId ?? "unknown"}, closing`);
-            this.close(4002, "transport closed");
-            return;
-          }
-          this.lastPingSentAt = Date.now();
-          this.send({
-            type: "ping",
-            from: this.nodeId,
-            timestamp: this.lastPingSentAt,
-          } as AnyClusterFrame);
-        } catch (err) {
-          debug("heartbeat", `Ping send failed for ${this.remoteNodeId ?? "unknown"}: ${err}`);
-          this.close(4002, "ping send failed");
-          return;
-        }
+  private heartbeatTick = () => {
+    if (this.closed) return;
 
-        scheduleNext();
-      }, interval);
-    };
-    scheduleNext();
-  }
+    // Watchdog: if no data received for a long time, the connection is dead
+    // regardless of what the heartbeat ping/pong state says.
+    const silenceMs = Date.now() - this.lastReceivedAt;
+    if (this.lastReceivedAt > 0 && silenceMs > Connection.RECEIVE_TIMEOUT) {
+      debug("heartbeat", `No data received for ${Math.round(silenceMs / 1000)}s from ${this.remoteNodeId ?? "unknown"}, closing`);
+      this.close(4002, "receive timeout");
+      return;
+    }
+
+    // Increment before checking: this ping is about to be sent and
+    // counts as outstanding until a pong arrives.
+    this.missedPongs++;
+    if (this.missedPongs >= HEARTBEAT_TIMEOUT_COUNT) {
+      debug("heartbeat", `${HEARTBEAT_TIMEOUT_COUNT} missed pongs from ${this.remoteNodeId ?? "unknown"}, closing`);
+      this.close(4002, "heartbeat timeout");
+      return;
+    }
+
+    // Send ping — wrapped in try-catch to prevent breaking the heartbeat chain.
+    // If send fails, the connection is dead; close it.
+    try {
+      if (this.transport.readyState !== WebSocket.OPEN) {
+        debug("heartbeat", `Transport not open (state=${this.transport.readyState}) for ${this.remoteNodeId ?? "unknown"}, closing`);
+        this.close(4002, "transport closed");
+        return;
+      }
+      this.lastPingSentAt = Date.now();
+      this.send({
+        type: "ping",
+        from: this.nodeId,
+        timestamp: this.lastPingSentAt,
+      } as AnyClusterFrame);
+    } catch (err) {
+      debug("heartbeat", `Ping send failed for ${this.remoteNodeId ?? "unknown"}: ${err}`);
+      this.close(4002, "ping send failed");
+      return;
+    }
+
+    this.scheduleHeartbeatTick();
+  };
 
   // ── Dummy traffic (breaks heartbeat timing pattern) ────────────
   private startDummyTraffic() {
     if (!this.sessionKey) return;
-    const scheduleNext = () => {
-      // Random interval 2-8 seconds — interleaves with heartbeat to obscure pattern
-      const interval = 2_000 + Math.random() * 6_000;
-      this.dummyTimer = setTimeout(() => {
-        if (this.closed || !this.sessionKey) return;
-        this.send({ type: "_d", from: "", timestamp: 0 } as unknown as AnyClusterFrame);
-        scheduleNext();
-      }, interval);
-    };
-    scheduleNext();
+    this.scheduleDummyTick();
   }
 
+  private scheduleDummyTick() {
+    // Random interval 2-8 seconds — interleaves with heartbeat to obscure pattern
+    const interval = 2_000 + Math.random() * 6_000;
+    this.dummyTimer = setTimeout(this.dummyTick, interval);
+  }
+
+  private dummyTick = () => {
+    if (this.closed || !this.sessionKey) return;
+    this.send({ type: "_d", from: "", timestamp: 0 } as unknown as AnyClusterFrame);
+    this.scheduleDummyTick();
+  };
+
   // ── Cleanup ────────────────────────────────────────────────────
   close(code = 1000, reason = "normal") {
     if (this.closed) return;

package/src/e2e/helpers.ts

@@ -23,11 +23,6 @@ export function allocPort(): number {
   return nextPort++;
 }
 
-/** Reset port counter (call in afterAll if tests run in a loop). */
-export function resetPorts(start = 19500): void {
-  nextPort = start;
-}
-
 // ── Logger ──────────────────────────────────────────────────────────
 
 /** Minimal no-op logger satisfying PluginLogger. */
@@ -110,6 +105,7 @@ function buildConfig(options: TestNodeOptions): ClawMatrixConfig {
     handoffTimeout: options.handoffTimeout ?? 600_000,
     modelTimeout: options.modelTimeout ?? 120_000,
     toolTimeout: options.toolTimeout ?? 30_000,
+    disconnectGrace: 0,
     peerApproval: {
       enabled: false,
       mode: "notify",