clawmatrix 0.1.14 → 0.1.16

package/BOOTSTRAP.md

@@ -122,7 +122,8 @@ openclaw clawmatrix status
   ],
   "models": [],
   "proxyModels": [
-    { "id": "claude-sonnet", "nodeId": "office-01" }
+    { "id": "gpt-5", "nodeId": "office-01", "description": "GPT-5", "input": ["text", "image"], "contextWindow": 400000, "maxTokens": 128000 },
+    { "id": "gemini-2.5-pro", "nodeId": "office-01", "description": "Gemini 2.5 Pro", "input": ["text", "image"], "contextWindow": 1048576, "maxTokens": 65535 }
   ],
   "tags": ["home"]
 }
@@ -165,9 +166,55 @@ openclaw clawmatrix status
 | `toolProxy.deny` | array | `[]` | 禁止的工具名（优先于 allow） |
 | `toolProxy.maxOutputBytes` | number | `1048576` | 单次响应最大字节数 |
 
-## 安装后 Agent 获得的工具
+## 启用集群工具
 
-安装后，本节点的 Agent 自动获得 7 个集群工具：
+ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenClaw 配置中显式启用。
+
+在 `openclaw.json` 中添加：
+
+```json
+{
+  "tools": {
+    "profile": "full",
+    "sessions": {
+      "visibility": "all"
+    },
+    "allow": [
+      "clawmatrix"
+    ]
+  }
+}
+```
+
+配置说明：
+- `profile: "full"` — 启用完整工具集（包括可选工具）
+- `sessions.visibility: "all"` — 允许跨会话访问工具（集群工具需要此设置才能在所有会话中可用）
+- `allow: ["clawmatrix"]` — 显式允许 ClawMatrix 插件注册的所有集群工具
+
+也可以按 Agent 粒度启用：
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "profile": "full",
+          "sessions": {
+            "visibility": "all"
+          },
+          "allow": ["clawmatrix"]
+        }
+      }
+    ]
+  }
+}
+```
+
+> 如果不配置，Agent 的系统提示中会提到集群工具，但实际无法调用。
+
+启用后，本节点的 Agent 获得 7 个集群工具：
 
 | 工具 | 用途 | 关键参数 |
 |------|------|----------|
@@ -199,13 +246,13 @@ openclaw clawmatrix status
         "api": "openai-completions",
         "models": [
           {
-            "id": "<模型ID>",
-            "name": "<显示名>",
+            "id": "gpt-5",
+            "name": "GPT-5",
             "reasoning": false,
-            "input": ["text"],
+            "input": ["text", "image"],
             "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 32000
+            "contextWindow": 400000,
+            "maxTokens": 128000
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,8 @@
     "@types/ws": "^8.18.1"
   },
   "peerDependencies": {
+    "openclaw": ">=2026.3.7",
     "typescript": "^5"
-  }
+  },
+  "overrides": {}
 }

package/src/auth.ts

@@ -3,17 +3,40 @@ export function generateNonce(): string {
   return Buffer.from(bytes).toString("hex");
 }
 
-export async function computeHmac(
-  nonce: string,
-  secret: string,
-): Promise<string> {
-  const key = await crypto.subtle.importKey(
+/** Cache imported CryptoKey keyed by a hash of the secret (avoid storing plaintext). Max 8 entries. */
+const KEY_CACHE_MAX = 8;
+const keyCache = new Map<string, CryptoKey>();
+
+function cacheKeyFor(secret: string): string {
+  const { createHash } = require("node:crypto");
+  return createHash("sha256").update(secret).digest("hex");
+}
+
+async function getHmacKey(secret: string): Promise<CryptoKey> {
+  const cacheKey = cacheKeyFor(secret);
+  let key = keyCache.get(cacheKey);
+  if (key) return key;
+  key = await crypto.subtle.importKey(
     "raw",
     new TextEncoder().encode(secret),
     { name: "HMAC", hash: "SHA-256" },
     false,
     ["sign"],
   );
+  if (keyCache.size >= KEY_CACHE_MAX) {
+    // Evict oldest entry
+    const oldest = keyCache.keys().next().value!;
+    keyCache.delete(oldest);
+  }
+  keyCache.set(cacheKey, key);
+  return key;
+}
+
+export async function computeHmac(
+  nonce: string,
+  secret: string,
+): Promise<string> {
+  const key = await getHmacKey(secret);
   const sig = await crypto.subtle.sign(
     "HMAC",
     key,
@@ -22,14 +45,21 @@ export async function computeHmac(
   return Buffer.from(sig).toString("hex");
 }
 
-/** Constant-time string comparison. */
+/** Constant-time string comparison. Uses native crypto.timingSafeEqual with
+ *  SHA-256 pre-hash to normalize lengths (avoids length-leak from early return). */
 export function timingSafeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) {
-    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  const nodeTimingSafeEqual = require("node:crypto").timingSafeEqual;
+  const encoder = new TextEncoder();
+  const bufA = encoder.encode(a);
+  const bufB = encoder.encode(b);
+  if (bufA.byteLength !== bufB.byteLength) {
+    // Hash both to fixed length so we still compare in constant time
+    const { createHash } = require("node:crypto");
+    const hashA = createHash("sha256").update(bufA).digest();
+    const hashB = createHash("sha256").update(bufB).digest();
+    return nodeTimingSafeEqual(hashA, hashB);
   }
-  return diff === 0;
+  return nodeTimingSafeEqual(Buffer.from(bufA), Buffer.from(bufB));
 }
 
 export async function verifyHmac(
@@ -38,5 +68,5 @@ export async function verifyHmac(
   sig: string,
 ): Promise<boolean> {
   const expected = await computeHmac(nonce, secret);
-  return timingSafeEqual(expected, sig);
+  return timingSafeEqual(expected, sig); // timingSafeEqual is now sync
 }

package/src/cluster-service.ts

@@ -17,6 +17,11 @@ import type {
   HandoffRequest,
   HandoffResponse,
   HandoffStreamChunk,
+  HandoffCancel,
+  HandoffStatusQuery,
+  HandoffStatusResponse,
+  HandoffInputRequired,
+  HandoffInput,
   ModelRequest,
   ModelResponse,
   ModelStreamChunk,
@@ -44,13 +49,14 @@ export class ClusterRuntime {
   readonly handoffManager: HandoffManager;
   readonly modelProxy: ModelProxy;
   readonly toolProxy: ToolProxy;
+  webHandler: WebHandler | null = null;
   private logger: PluginLogger;
 
-  constructor(config: ClawMatrixConfig, logger: PluginLogger, openclawConfig: OpenClawConfig) {
+  constructor(config: ClawMatrixConfig, logger: PluginLogger, openclawConfig: OpenClawConfig, openclawVersion?: string) {
     this.config = config;
     this.logger = logger;
     const gatewayInfo = resolveGatewayInfo(openclawConfig);
-    this.peerManager = new PeerManager(config);
+    this.peerManager = new PeerManager(config, openclawVersion);
     this.handoffManager = new HandoffManager(config, this.peerManager);
     this.modelProxy = new ModelProxy(config, this.peerManager, gatewayInfo, openclawConfig);
     this.toolProxy = new ToolProxy(config, this.peerManager, gatewayInfo);
@@ -58,7 +64,7 @@ export class ClusterRuntime {
 
   start() {
     // Wire up frame dispatch
-    this.peerManager.on("frame", (frame, conn) => {
+    this.peerManager.on("frame", (frame) => {
       this.dispatchFrame(frame);
     });
 
@@ -72,8 +78,10 @@ export class ClusterRuntime {
 
     // Web dashboard (must be set before peerManager.start() creates the HTTP server)
     if (this.config.web?.enabled) {
-      const webHandler = new WebHandler(this.config, this.peerManager);
-      this.peerManager.setHttpHandler((req, res) => webHandler.handle(req, res));
+      this.webHandler = new WebHandler(this.config, this.peerManager, this.handoffManager);
+      this.peerManager.setHttpHandler((req, res) => this.webHandler!.handle(req, res));
+      // Enable satellite tool routing through WebHandler
+      this.toolProxy.setSatelliteHandler(this.webHandler);
       this.logger.info(`[clawmatrix] Web dashboard enabled on listen port`);
     }
 
@@ -89,6 +97,7 @@ export class ClusterRuntime {
   }
 
   async stop() {
+    this.webHandler?.destroy();
     this.handoffManager.destroy();
     this.modelProxy.stop();
     this.toolProxy.destroy();
@@ -98,7 +107,7 @@ export class ClusterRuntime {
 
   private dispatchFrame(frame: AnyClusterFrame) {
     if (frame.type.startsWith("model_")) {
-      debug("dispatch", `${frame.type} id=${frame.id} from=${(frame as ClusterFrame).from}`);
+      debug("dispatch", `${frame.type} id=${frame.id} from=${frame.from}`);
     }
     switch (frame.type) {
       case "handoff_req":
@@ -112,6 +121,24 @@ export class ClusterRuntime {
       case "handoff_res":
         this.handoffManager.handleResponse(frame as HandoffResponse);
         break;
+      case "handoff_cancel":
+        this.handoffManager.handleCancel(frame as HandoffCancel);
+        break;
+      case "handoff_status":
+        this.handoffManager.handleStatusQuery(frame as HandoffStatusQuery);
+        break;
+      case "handoff_input_required":
+        this.handoffManager.handleInputRequired(frame as HandoffInputRequired);
+        break;
+      case "handoff_input":
+        this.handoffManager.handleInput(frame as HandoffInput).catch((err) => {
+          this.logger.error(`[clawmatrix] Handoff input error: ${err}`);
+        });
+        break;
+      case "handoff_status_res":
+        // Status responses are handled by the requester via pending callbacks
+        // (currently informational — logged but not routed to pending map)
+        break;
       case "model_req":
         this.modelProxy.handleModelRequest(frame as ModelRequest).catch((err) => {
           this.logger.error(`[clawmatrix] Model request error: ${err}`);
@@ -178,11 +205,12 @@ export function getClusterRuntime(): ClusterRuntime {
 export function createClusterService(
   config: ClawMatrixConfig,
   openclawConfig: OpenClawConfig,
+  openclawVersion?: string,
 ): OpenClawPluginService {
   return {
     id: "clawmatrix",
     start(ctx: OpenClawPluginServiceContext) {
-      clusterRuntime = new ClusterRuntime(config, ctx.logger, openclawConfig);
+      clusterRuntime = new ClusterRuntime(config, ctx.logger, openclawConfig, openclawVersion);
       clusterRuntime.start();
     },
     async stop() {

package/src/compat.ts

@@ -40,6 +40,9 @@ export function spawnProcess(
         stream.on("end", () => controller.close());
         stream.on("error", (err) => controller.error(err));
       },
+      cancel() {
+        stream.destroy();
+      },
     });
   }
 

package/src/config.ts

@@ -61,19 +61,28 @@ const ToolProxyConfigSchema = z.object({
   maxOutputBytes: z.number().default(1_048_576),
 });
 
-const ProxyModelSchema = z.object({
+// Per-model entry inside a proxy group (minimal — inherits group-level fields)
+const ProxyModelEntrySchema = z.object({
   id: z.string(),
-  nodeId: z.string().optional(),
   description: z.string().optional(),
   ...ModelParamsSchema,
 });
 
+// Grouped proxy models: shared nodeId/api/provider, list of models
+const ProxyModelGroupSchema = z.object({
+  nodeId: z.string(),
+  provider: z.string().optional(),
+  description: z.string().optional(),
+  ...ModelParamsSchema,
+  models: z.array(ProxyModelEntrySchema),
+});
+
 const WebConfigSchema = z.object({
   enabled: z.boolean().default(false),
   token: z.string().min(8, "web token must be at least 8 characters"),
 }).optional();
 
-export const ClawMatrixConfigSchema = z.object({
+const RawClawMatrixConfigSchema = z.object({
   nodeId: z.string(),
   secret: z.string().min(16, "secret must be at least 16 characters"),
   listen: z.boolean().default(false),
@@ -82,7 +91,7 @@ export const ClawMatrixConfigSchema = z.object({
   peers: z.array(PeerConfigSchema).default([]),
   agents: z.array(AgentInfoSchema).default([]),
   models: z.array(ModelInfoSchema).default([]),
-  proxyModels: z.array(ProxyModelSchema).default([]),
+  proxyModels: z.array(ProxyModelGroupSchema).default([]),
   tags: z.array(z.string()).default([]),
   proxyPort: z.number().default(19001),
   toolProxy: ToolProxyConfigSchema.optional(),
@@ -90,10 +99,52 @@ export const ClawMatrixConfigSchema = z.object({
   web: WebConfigSchema,
 });
 
-export type ClawMatrixConfig = z.infer<typeof ClawMatrixConfigSchema>;
+/** Flat proxy model after group expansion (used internally). */
+export interface ProxyModel {
+  id: string;
+  nodeId: string;
+  provider?: string;
+  description?: string;
+  api?: string;
+  contextWindow?: number;
+  maxTokens?: number;
+  reasoning?: boolean;
+  input?: ("text" | "image")[];
+  cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  compat?: z.infer<typeof ModelCompatSchema>;
+}
+
+export type ClawMatrixConfig = Omit<z.infer<typeof RawClawMatrixConfigSchema>, "proxyModels"> & {
+  proxyModels: ProxyModel[];
+};
+
+export { RawClawMatrixConfigSchema as ClawMatrixConfigSchema };
 export type PeerConfig = z.infer<typeof PeerConfigSchema>;
 export type ToolProxyConfig = z.infer<typeof ToolProxyConfigSchema>;
 
+/** Parse and flatten grouped proxyModels into flat array. */
 export function parseConfig(raw: unknown): ClawMatrixConfig {
-  return ClawMatrixConfigSchema.parse(raw);
+  const parsed = RawClawMatrixConfigSchema.parse(raw);
+
+  // Flatten proxy model groups
+  const proxyModels: ProxyModel[] = [];
+  for (const group of parsed.proxyModels) {
+    for (const m of group.models) {
+      proxyModels.push({
+        id: m.id,
+        nodeId: group.nodeId,
+        provider: group.provider,
+        description: m.description ?? group.description,
+        api: m.api ?? group.api,
+        contextWindow: m.contextWindow ?? group.contextWindow,
+        maxTokens: m.maxTokens ?? group.maxTokens,
+        reasoning: m.reasoning ?? group.reasoning,
+        input: m.input ?? group.input,
+        cost: m.cost ?? group.cost,
+        compat: m.compat ?? group.compat,
+      });
+    }
+  }
+
+  return { ...parsed, proxyModels };
 }

package/src/connection.ts

@@ -6,8 +6,10 @@ import type {
   AuthOk,
   AuthFail,
   ClusterFrame,
+  DeviceInfo,
   ModelInfo,
   NodeCapabilities,
+  ToolProxyInfo,
 } from "./types.ts";
 import { generateNonce, computeHmac, verifyHmac } from "./auth.ts";
 
@@ -28,6 +30,7 @@ export interface WsTransport {
 export interface ConnectionEvents {
   message: [frame: AnyClusterFrame];
   authenticated: [capabilities: NodeCapabilities];
+  latency: [ms: number];
   close: [code: number, reason: string];
   error: [error: Error];
 }
@@ -48,6 +51,9 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private missedPongs = 0;
   private pendingNonce: string | null = null;
   private closed = false;
+  private lastPingSentAt = 0;
+  /** Exponential moving average of heartbeat RTT in milliseconds. */
+  latencyMs = 0;
 
   constructor(
     transport: WsTransport,
@@ -63,13 +69,15 @@ export class Connection extends EventEmitter<ConnectionEvents> {
     this.secret = secret;
     this.localCapabilities = localCapabilities;
 
+    // Both inbound and outbound get an auth timeout to prevent hanging connections
+    this.authTimer = setTimeout(() => {
+      if (!this.authenticated) {
+        this.close(4003, "auth timeout");
+      }
+    }, AUTH_TIMEOUT);
+
     if (role === "inbound") {
       this.sendAuthChallenge();
-      this.authTimer = setTimeout(() => {
-        if (!this.authenticated) {
-          this.close(4003, "auth timeout");
-        }
-      }, AUTH_TIMEOUT);
     }
   }
 
@@ -142,6 +150,12 @@ export class Connection extends EventEmitter<ConnectionEvents> {
     }
     if (frame.type === "pong") {
       this.missedPongs = 0;
+      if (this.lastPingSentAt > 0) {
+        const rtt = Date.now() - this.lastPingSentAt;
+        // Exponential moving average (α = 0.3)
+        this.latencyMs = this.latencyMs === 0 ? rtt : Math.round(this.latencyMs * 0.7 + rtt * 0.3);
+        this.emit("latency", this.latencyMs);
+      }
       return;
     }
 
@@ -151,12 +165,14 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private async handleAuthMessage(frame: AnyClusterFrame) {
     if (this.role === "inbound") {
       if (frame.type !== "auth") return;
-      const { nodeId, sig, agents, models, tags } = frame.payload as {
+      const { nodeId, sig, agents, models, tags, deviceInfo, toolProxy } = frame.payload as {
         nodeId: string;
         sig: string;
         agents?: AgentInfo[];
         models?: ModelInfo[];
         tags?: string[];
+        deviceInfo?: DeviceInfo;
+        toolProxy?: ToolProxyInfo;
       };
       if (!this.pendingNonce) return;
 
@@ -180,6 +196,8 @@ export class Connection extends EventEmitter<ConnectionEvents> {
         agents: agents ?? [],
         models: models ?? [],
         tags: tags ?? [],
+        deviceInfo,
+        toolProxy,
       };
       this.authenticated = true;
       this.clearAuthTimer();
@@ -193,8 +211,10 @@ export class Connection extends EventEmitter<ConnectionEvents> {
           agents: this.localCapabilities.agents,
           models: this.localCapabilities.models,
           tags: this.localCapabilities.tags,
+          deviceInfo: this.localCapabilities.deviceInfo,
+          toolProxy: this.localCapabilities.toolProxy,
         },
-      } satisfies AuthOk);
+      } as AuthOk);
 
       this.startHeartbeat();
       this.emit("authenticated", this.remoteCapabilities);
@@ -212,6 +232,8 @@ export class Connection extends EventEmitter<ConnectionEvents> {
             agents: this.localCapabilities.agents,
             models: this.localCapabilities.models,
             tags: this.localCapabilities.tags,
+            deviceInfo: this.localCapabilities.deviceInfo,
+            toolProxy: this.localCapabilities.toolProxy,
           },
         });
         return;
@@ -225,8 +247,11 @@ export class Connection extends EventEmitter<ConnectionEvents> {
           agents: ok.payload.agents,
           models: ok.payload.models,
           tags: ok.payload.tags,
+          deviceInfo: ok.payload.deviceInfo,
+          toolProxy: ok.payload.toolProxy,
         };
         this.authenticated = true;
+        this.clearAuthTimer();
         this.startHeartbeat();
         this.emit("authenticated", this.remoteCapabilities);
         return;
@@ -258,10 +283,11 @@ export class Connection extends EventEmitter<ConnectionEvents> {
           this.close(4002, "heartbeat timeout");
           return;
         }
+        this.lastPingSentAt = Date.now();
         this.sendRaw({
           type: "ping",
           from: this.nodeId,
-          timestamp: Date.now(),
+          timestamp: this.lastPingSentAt,
         });
         scheduleNext();
       }, interval);

package/src/device-info.ts

@@ -0,0 +1,48 @@
+/**
+ * Collect local device/system information using Node.js os module.
+ */
+import { arch, cpus, hostname, totalmem, type, release } from "node:os";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import type { DeviceInfo } from "./types.ts";
+
+function readVersionFromPkgJson(dir: string): string | undefined {
+  try {
+    const raw = readFileSync(join(dir, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw) as { name?: string; version?: string };
+    if (pkg.name === "openclaw" && pkg.version) return pkg.version;
+  } catch { /* not found */ }
+  return undefined;
+}
+
+function resolveOpenclawVersion(hint?: string): string | undefined {
+  if (hint && hint !== "unknown") return hint;
+  // Walk up from the OpenClaw entry script (process.argv[1]) to find package.json
+  try {
+    const entry = process.argv[1];
+    if (!entry) return undefined;
+    let dir = dirname(entry);
+    for (let i = 0; i < 10; i++) {
+      const v = readVersionFromPkgJson(dir);
+      if (v) return v;
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch { /* best effort */ }
+  return undefined;
+}
+
+/** Collect device info once at startup. */
+export function collectDeviceInfo(openclawVersion?: string): DeviceInfo {
+  const cpuList = cpus();
+  return {
+    os: `${type()} ${release()}`,
+    arch: arch(),
+    cpuModel: cpuList[0]?.model?.trim() ?? "unknown",
+    cpuCores: cpuList.length,
+    totalMemoryMB: Math.round(totalmem() / (1024 * 1024)),
+    hostname: hostname(),
+    openclawVersion: resolveOpenclawVersion(openclawVersion),
+  };
+}