clawmatrix 0.1.8 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.1.8",
+  "version": "0.1.11",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,11 @@
   },
   "scripts": {
     "test": "bun test",
-    "prepublishOnly": "bun test"
+    "prepublishOnly": "bun test",
+    "release": "bun scripts/release.ts",
+    "release:minor": "bun scripts/release.ts minor",
+    "release:major": "bun scripts/release.ts major",
+    "release:dry": "bun scripts/release.ts --dry-run"
   },
   "dependencies": {
     "ws": "^8.19.0",

package/src/cli.ts

@@ -62,21 +62,32 @@ export const registerClusterCli = ({ program }: { program: Command }) => {
         return;
       }
 
+      // Style helpers
+      const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;
+      const dim = (s: string) => `\x1b[2m${s}\x1b[22m`;
+      const green = (s: string) => `\x1b[32m${s}\x1b[39m`;
+      const red = (s: string) => `\x1b[31m${s}\x1b[39m`;
+      const cyan = (s: string) => `\x1b[36m${s}\x1b[39m`;
+      const yellow = (s: string) => `\x1b[33m${s}\x1b[39m`;
+      const bar = dim("│");
+      const lbl = (text: string) => dim(text.padEnd(13));
+
       const agents = data.agents as Array<{ id: string }>;
       const models = data.models as Array<{ id: string }>;
       const tags = data.tags as string[];
 
-      console.log("");
-      console.log("ClawMatrix Cluster");
-      console.log("");
-      console.log(`  Node:        ${data.nodeId}`);
+      // Local node
+      console.log();
+      console.log(`  ${cyan("◆")}  ${bold("ClawMatrix Cluster")}`);
+      console.log(`  ${bar}`);
+      console.log(`  ${bar}  ${lbl("Node")}${bold(String(data.nodeId))}`);
       if (tags.length > 0) {
-        console.log(`  Tags:        ${tags.join(", ")}`);
+        console.log(`  ${bar}  ${lbl("Tags")}${tags.join(dim(", "))}`);
       }
-      console.log(`  Listen:      ${data.listen !== false ? `port ${data.listen}` : "disabled"}`);
-      console.log(`  Model proxy: port ${data.proxyPort}`);
-      console.log(`  Agents:      ${agents.map((a) => a.id).join(", ") || "-"}`);
-      console.log(`  Models:      ${models.map((m) => m.id).join(", ") || "-"}`);
+      console.log(`  ${bar}  ${lbl("Listen")}${data.listen !== false ? `:${data.listen}` : dim("disabled")}`);
+      console.log(`  ${bar}  ${lbl("Model Proxy")}:${data.proxyPort}`);
+      console.log(`  ${bar}  ${lbl("Agents")}${agents.map((a) => a.id).join(dim(", ")) || dim("–")}`);
+      console.log(`  ${bar}  ${lbl("Models")}${models.map((m) => m.id).join(dim(", ")) || dim("–")}`);
 
       const peers = data.peers as Array<{
         nodeId: string;
@@ -87,34 +98,48 @@ export const registerClusterCli = ({ program }: { program: Command }) => {
         latencyMs: number;
       }>;
 
-      const connected = peers.filter((p) => p.connected).length;
-      console.log("");
       if (!peers || peers.length === 0) {
-        console.log("  No peers discovered.");
-        console.log("");
+        console.log(`  ${bar}`);
+        console.log(`  ${dim("◇")}  ${dim("No peers discovered")}`);
+        console.log();
         return;
       }
 
-      console.log(`Peers (${connected}/${peers.length} connected)`);
-      console.log("");
+      const connected = peers.filter((p) => p.connected).length;
+      const countStr = `${connected}/${peers.length} connected`;
+      const countColor = connected === peers.length ? green : connected > 0 ? yellow : red;
+
+      console.log(`  ${bar}`);
+      console.log(`  ${cyan("◆")}  ${bold("Peers")}  ${countColor(countStr)}`);
+      console.log(`  ${bar}`);
+
+      for (let i = 0; i < peers.length; i++) {
+        const peer = peers[i];
+        const dot = peer.connected ? green("●") : red("○");
+        const latency = peer.connected && peer.latencyMs > 0 ? dim(` ${peer.latencyMs}ms`) : "";
+        const status = peer.connected ? "" : red(" disconnected");
+        console.log(`  ${bar}  ${dot} ${bold(peer.nodeId)}${status}${latency}`);
 
-      for (const peer of peers) {
-        const status = peer.connected ? "connected" : "unreachable";
-        const latency = peer.latencyMs > 0 ? `, ${peer.latencyMs}ms` : "";
-        console.log(`  ${peer.nodeId} (${status}${latency})`);
         if (peer.tags.length > 0) {
-          console.log(`    Tags:   ${peer.tags.join(", ")}`);
+          console.log(`  ${bar}    ${lbl("Tags")}${peer.tags.join(dim(", "))}`);
         }
-        const peerAgents = peer.agents.map((a) => a.id).join(", ");
+        const peerAgents = peer.agents.map((a) => a.id).join(dim(", "));
         if (peerAgents) {
-          console.log(`    Agents: ${peerAgents}`);
+          console.log(`  ${bar}    ${lbl("Agents")}${peerAgents}`);
         }
-        const peerModels = peer.models.map((m) => m.id).join(", ");
+        const peerModels = peer.models.map((m) => m.id).join(dim(", "));
         if (peerModels) {
-          console.log(`    Models: ${peerModels}`);
+          console.log(`  ${bar}    ${lbl("Models")}${peerModels}`);
+        }
+
+        if (i < peers.length - 1) {
+          console.log(`  ${bar}`);
         }
       }
-      console.log("");
+
+      console.log(`  ${bar}`);
+      console.log(`  ${dim("◇")}`);
+      console.log();
     });
 
   cmd

package/src/cluster-service.ts

@@ -6,6 +6,7 @@ import type {
 } from "openclaw/plugin-sdk";
 import type { ClawMatrixConfig } from "./config.ts";
 import { spawnProcess } from "./compat.ts";
+import { debug } from "./debug.ts";
 import { PeerManager } from "./peer-manager.ts";
 import { HandoffManager } from "./handoff.ts";
 import { ModelProxy } from "./model-proxy.ts";
@@ -88,6 +89,9 @@ export class ClusterRuntime {
   }
 
   private dispatchFrame(frame: AnyClusterFrame) {
+    if (frame.type.startsWith("model_")) {
+      debug("dispatch", `${frame.type} id=${frame.id} from=${(frame as ClusterFrame).from}`);
+    }
     switch (frame.type) {
       case "handoff_req":
         this.handoffManager.handleRequest(frame as HandoffRequest).catch((err) => {
@@ -143,10 +147,13 @@ export class ClusterRuntime {
     }
 
     // Fire-and-forget: inject message via openclaw agent CLI
-    spawnProcess(["openclaw", "agent", "--agent", agent.id, "--message", message], {
+    const proc = spawnProcess(["openclaw", "agent", "--agent", agent.id, "--message", message], {
       stdout: "ignore",
       stderr: "ignore",
     });
+    proc.exited.catch((err) => {
+      this.logger.error(`[clawmatrix] Failed to inject message to agent "${agent.id}": ${err}`);
+    });
   }
 }
 

package/src/config.ts

@@ -6,6 +6,21 @@ const AgentInfoSchema = z.object({
   tags: z.array(z.string()).default([]),
 });
 
+const ModelCompatSchema = z.object({
+  supportsTools: z.boolean().optional(),
+  supportsStore: z.boolean().optional(),
+  supportsDeveloperRole: z.boolean().optional(),
+  supportsReasoningEffort: z.boolean().optional(),
+  supportsUsageInStreaming: z.boolean().optional(),
+  supportsStrictMode: z.boolean().optional(),
+  maxTokensField: z.enum(["max_completion_tokens", "max_tokens"]).optional(),
+  thinkingFormat: z.enum(["openai", "zai", "qwen"]).optional(),
+  requiresToolResultName: z.boolean().optional(),
+  requiresAssistantAfterToolResult: z.boolean().optional(),
+  requiresThinkingAsText: z.boolean().optional(),
+  requiresMistralToolIds: z.boolean().optional(),
+}).optional();
+
 const ModelParamsSchema = {
   api: z.enum([
     "openai-completions", "openai-responses", "openai-codex-responses",
@@ -22,6 +37,7 @@ const ModelParamsSchema = {
     cacheRead: z.number(),
     cacheWrite: z.number(),
   }).optional(),
+  compat: ModelCompatSchema,
 };
 
 const ModelInfoSchema = z.object({

package/src/connection.ts

@@ -284,6 +284,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
       // already closed
     }
     this.emit("close", code, reason);
+    this.removeAllListeners();
   }
 
   get isOpen(): boolean {

package/src/debug.ts

@@ -0,0 +1,5 @@
+const enabled = process.env.CLAWMATRIX_DEBUG !== "0";
+
+export function debug(tag: string, msg: string) {
+  if (enabled) console.error(`[clawmatrix:${tag}] ${msg}`);
+}

package/src/index.ts

@@ -45,20 +45,35 @@ const plugin = {
     const baseUrl = `http://127.0.0.1:${config.proxyPort}/v1`;
     const modelsByNode = groupModelsByNode(config);
 
-    // Patch openclaw config so auth resolution can find a dummy API key
-    // (resolveApiKeyForProvider checks cfg.models.providers, not plugin registry)
-    const ocModels = ((api.config as Record<string, unknown>).models ??= {}) as Record<string, unknown>;
-    const ocProviders = (ocModels.providers ??= {}) as Record<string, unknown>;
+    // Patch openclaw config so auth resolution can find a dummy API key.
+    // resolveApiKeyForProvider checks cfg.models.providers, not the plugin registry.
+    // We must patch BOTH api.config (cfgAtStart) AND the runtimeConfigSnapshot
+    // (returned by loadConfig()) because activateSecretsRuntimeSnapshot clones the
+    // config before plugins load, so api.config and the snapshot are separate objects.
+    const patchProviders = (cfg: Record<string, unknown>) => {
+      const models = ((cfg).models ??= {}) as Record<string, unknown>;
+      const providers = (models.providers ??= {}) as Record<string, unknown>;
+      for (const [nodeId, nodeModels] of Object.entries(modelsByNode)) {
+        if (!providers[nodeId]) {
+          providers[nodeId] = { baseUrl, apiKey: "sk-clawmatrix-proxy", api: "openai-completions", models: nodeModels };
+        }
+      }
+    };
 
-    for (const [nodeId, models] of Object.entries(modelsByNode)) {
-      if (!ocProviders[nodeId]) {
-        ocProviders[nodeId] = {
-          baseUrl,
-          apiKey: "sk-clawmatrix-proxy",
-          models,
-        };
+    patchProviders(api.config as Record<string, unknown>);
+
+    // Also patch the runtime config snapshot (loadConfig returns it by reference).
+    // api.runtime.config.loadConfig() returns runtimeConfigSnapshot directly.
+    try {
+      const snapshot = api.runtime.config.loadConfig();
+      if (snapshot && snapshot !== api.config) {
+        patchProviders(snapshot as Record<string, unknown>);
       }
+    } catch {
+      // Best-effort; api.config patch is the fallback
+    }
 
+    for (const [nodeId, models] of Object.entries(modelsByNode)) {
       api.registerProvider({
         id: nodeId,
         label: `ClawMatrix: ${nodeId}`,
@@ -186,8 +201,8 @@ const plugin = {
   },
 };
 
-function formatModel(m: { id: string; description?: string; api?: string; reasoning?: boolean; input?: string[]; cost?: { input: number; output: number; cacheRead: number; cacheWrite: number }; contextWindow?: number; maxTokens?: number }) {
-  return {
+function formatModel(m: { id: string; description?: string; api?: string; reasoning?: boolean; input?: string[]; cost?: { input: number; output: number; cacheRead: number; cacheWrite: number }; contextWindow?: number; maxTokens?: number; compat?: Record<string, unknown> }) {
+  const result: Record<string, unknown> = {
     id: m.id,
     name: m.description ?? m.id,
     api: m.api ?? ("openai-completions" as const),
@@ -197,6 +212,8 @@ function formatModel(m: { id: string; description?: string; api?: string; reason
     contextWindow: m.contextWindow ?? 128_000,
     maxTokens: m.maxTokens ?? 4096,
   };
+  if (m.compat) result.compat = m.compat;
+  return result;
 }
 
 function groupModelsByNode(config: ReturnType<typeof parseConfig>): Record<string, ReturnType<typeof formatModel>[]> {

package/src/local-tools.ts

@@ -0,0 +1,176 @@
+/**
+ * Local tool execution for exec/read/write/edit.
+ *
+ * These tools cannot go through the Gateway HTTP `/tools/invoke` endpoint
+ * because it only exposes `createOpenClawTools()` (safe tools), not
+ * `createOpenClawCodingTools()` (which includes exec/read/write/edit).
+ *
+ * Instead, we execute them directly in the same Node.js process.
+ * - exec: simplified child_process.spawn (no sandbox/PTY/background)
+ * - read/write/edit: reuse @mariozechner/pi-coding-agent factories
+ */
+
+import { spawn } from "node:child_process";
+import {
+  createReadTool,
+  createWriteTool,
+  createEditTool,
+} from "@mariozechner/pi-coding-agent";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+interface ExecParams {
+  command: string;
+  workdir?: string;
+  env?: Record<string, string>;
+  timeout?: number;
+}
+
+type ToolResult = Record<string, unknown>;
+
+// ── Constants ──────────────────────────────────────────────────────
+
+const LOCAL_TOOLS = new Set(["exec", "read", "write", "edit"]);
+const DEFAULT_EXEC_TIMEOUT = 300; // seconds
+const MAX_OUTPUT_BYTES = 512 * 1024; // 512KB
+
+// ── Public API ─────────────────────────────────────────────────────
+
+export function isLocalTool(tool: string): boolean {
+  return LOCAL_TOOLS.has(tool);
+}
+
+export async function executeLocally(
+  tool: string,
+  params: Record<string, unknown>,
+): Promise<ToolResult> {
+  switch (tool) {
+    case "exec":
+      return executeExec(params as unknown as ExecParams);
+    case "read":
+      return executePiTool("read", params);
+    case "write":
+      return executePiTool("write", params);
+    case "edit":
+      return executePiTool("edit", params);
+    default:
+      throw new Error(`Unknown local tool: ${tool}`);
+  }
+}
+
+// ── exec: simplified child_process.spawn ───────────────────────────
+
+async function executeExec(params: ExecParams): Promise<ToolResult> {
+  const { command, workdir, env, timeout } = params;
+  if (!command) throw new Error("exec: command is required");
+
+  const shell = process.env.SHELL || "/bin/bash";
+  const timeoutMs = (timeout ?? DEFAULT_EXEC_TIMEOUT) * 1000;
+
+  return new Promise<ToolResult>((resolve, reject) => {
+    const child = spawn(shell, ["-c", command], {
+      cwd: workdir || process.cwd(),
+      env: env ? { ...process.env, ...env } : process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: true,
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+      if (stdout.length > MAX_OUTPUT_BYTES) {
+        stdout = stdout.slice(0, MAX_OUTPUT_BYTES);
+      }
+    });
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+      if (stderr.length > MAX_OUTPUT_BYTES) {
+        stderr = stderr.slice(0, MAX_OUTPUT_BYTES);
+      }
+    });
+
+    const timer = setTimeout(() => {
+      killed = true;
+      // Kill the process group
+      try {
+        process.kill(-child.pid!, "SIGKILL");
+      } catch {
+        child.kill("SIGKILL");
+      }
+    }, timeoutMs);
+
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      const truncated =
+        stdout.length >= MAX_OUTPUT_BYTES || stderr.length >= MAX_OUTPUT_BYTES;
+      resolve({
+        exitCode: code ?? 1,
+        stdout,
+        stderr,
+        ...(signal && { signal }),
+        ...(killed && { timedOut: true }),
+        ...(truncated && { truncated: true }),
+      });
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(new Error(`exec: failed to spawn: ${err.message}`));
+    });
+  });
+}
+
+// ── read/write/edit: reuse pi-coding-agent factories ───────────────
+
+const piToolCache = new Map<string, { execute: Function }>();
+
+function getPiTool(name: string): { execute: Function } {
+  let tool = piToolCache.get(name);
+  if (tool) return tool;
+
+  const cwd = process.cwd();
+  switch (name) {
+    case "read":
+      tool = createReadTool(cwd);
+      break;
+    case "write":
+      tool = createWriteTool(cwd);
+      break;
+    case "edit":
+      tool = createEditTool(cwd);
+      break;
+    default:
+      throw new Error(`Unknown pi tool: ${name}`);
+  }
+
+  piToolCache.set(name, tool);
+  return tool;
+}
+
+async function executePiTool(
+  name: string,
+  params: Record<string, unknown>,
+): Promise<ToolResult> {
+  const tool = getPiTool(name);
+  const toolCallId = crypto.randomUUID();
+
+  const result = (await tool.execute(toolCallId, params)) as {
+    content: Array<{ type: string; text?: string }>;
+    details: unknown;
+  };
+
+  // Flatten content array to a single text result
+  const text = result.content
+    .filter((c) => c.type === "text" && c.text)
+    .map((c) => c.text)
+    .join("\n");
+
+  return {
+    content: text,
+    details: result.details,
+  };
+}

package/src/model-proxy.ts

@@ -7,6 +7,7 @@ import type {
   ModelResponse,
   ModelStreamChunk,
 } from "./types.ts";
+import { debug } from "./debug.ts";
 
 const MODEL_TIMEOUT = 120_000; // 2 minutes
 
@@ -35,21 +36,37 @@ export class ModelProxy {
   /** Start the local HTTP proxy server for OpenAI-compatible requests. */
   start() {
     this.httpServer = createServer(async (req, res) => {
-      const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
-
-      if (url.pathname === "/v1/chat/completions" && req.method === "POST") {
-        const body = await this.readBody(req);
-        const response = await this.handleChatCompletion(body);
-        this.sendResponse(res, response);
-      } else if (url.pathname === "/v1/models" && req.method === "GET") {
-        const response = this.handleListModels();
-        this.sendResponse(res, response);
-      } else {
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end("Not Found");
+      try {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+
+        const p = url.pathname.replace(/^\/v1/, "");
+        debug("proxy", `${req.method} ${url.pathname} → ${p}`);
+
+        if (p === "/chat/completions" && req.method === "POST") {
+          const body = await this.readBody(req);
+          const response = await this.handleChatCompletion(body);
+          debug("proxy", `response status=${response.status}`);
+          this.sendResponse(res, response);
+        } else if (p === "/models" && req.method === "GET") {
+          const response = this.handleListModels();
+          this.sendResponse(res, response);
+        } else {
+          res.writeHead(404, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: { message: `No handler for ${req.method} ${url.pathname}` } }));
+        }
+      } catch {
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+        }
+        res.end(JSON.stringify({ error: { message: "Internal proxy error" } }));
       }
     });
 
+    this.httpServer.on("error", (err) => {
+      // Log but don't crash — port conflict or other server error
+      console.error(`[clawmatrix] Model proxy server error: ${err.message}`);
+    });
+
     this.httpServer.listen(this.config.proxyPort, "127.0.0.1");
   }
 
@@ -84,12 +101,16 @@ export class ModelProxy {
       const pump = (): void => {
         reader.read().then(({ done, value }) => {
           if (done) {
+            reader.releaseLock();
             res.end();
             return;
           }
           res.write(value);
           pump();
-        }).catch(() => res.end());
+        }).catch(() => {
+          reader.releaseLock();
+          res.end();
+        });
       };
       pump();
     }
@@ -115,17 +136,32 @@ export class ModelProxy {
       };
     }
 
-    const modelId = body.model;
-    // Check proxyModels for a nodeId routing hint
-    const proxyModel = this.config.proxyModels.find((m) => m.id === modelId);
-    const route = proxyModel?.nodeId
-      ? this.peerManager.router.getRoute(proxyModel.nodeId)
+    const rawModelId = body.model;
+    // Parse "nodeId/model" format: first segment is nodeId, rest is model ID.
+    // OpenClaw sends "providerId/modelId" where providerId = nodeId, so this
+    // naturally handles both OpenClaw calls and direct curl calls.
+    // If no "/" present, treat entire string as model ID and auto-resolve.
+    let nodeId: string | undefined;
+    let modelId: string;
+    const slashIdx = rawModelId.indexOf("/");
+    if (slashIdx > 0) {
+      nodeId = rawModelId.slice(0, slashIdx);
+      modelId = rawModelId.slice(slashIdx + 1);
+    } else {
+      modelId = rawModelId;
+    }
+    debug("proxy", `model raw="${rawModelId}" nodeId=${nodeId ?? "auto"} modelId="${modelId}" stream=${body.stream ?? false}`);
+    const proxyModel = this.config.proxyModels.find((m) => m.id === modelId && (!nodeId || m.nodeId === nodeId))
+      ?? this.config.proxyModels.find((m) => m.id === modelId);
+    const route = nodeId
+      ? this.peerManager.router.getRoute(nodeId)
       : this.peerManager.router.resolveModel(modelId);
+    debug("proxy", `proxyModel=${proxyModel?.id ?? "none"} route=${route?.nodeId ?? "none"} reachable=${route ? this.peerManager.canReach(route.nodeId) : false}`);
     if (!route) {
       return {
         status: 404,
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ error: { message: `Model "${modelId}" not found in cluster` } }),
+        body: JSON.stringify({ error: { message: `Model "${modelId}" not found in cluster (proxyModels: [${this.config.proxyModels.map(m => m.id).join(", ")}])` } }),
       };
     }
 
@@ -158,6 +194,15 @@ export class ModelProxy {
       },
     };
 
+    // Pre-check reachability before starting a stream (avoids silent empty response)
+    if (!this.peerManager.canReach(route.nodeId)) {
+      return {
+        status: 502,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ error: { message: `Cannot reach model node "${route.nodeId}"` } }),
+      };
+    }
+
     if (stream) {
       return this.handleStreamRequest(requestId, route.nodeId, frame);
     } else {
@@ -178,8 +223,13 @@ export class ModelProxy {
           this.pending.delete(requestId);
           this.peerManager.router.markFailed(requestId);
           try {
+            const errorChunk = {
+              id: `chatcmpl-${requestId}`,
+              object: "chat.completion.chunk",
+              choices: [{ index: 0, delta: { content: "\n\n[ClawMatrix] Error: model request timed out" }, finish_reason: "stop" }],
+            };
             controller.enqueue(
-              encoder.encode(`data: ${JSON.stringify({ error: "timeout" })}\n\n`),
+              encoder.encode(`data: ${JSON.stringify(errorChunk)}\n\n`),
             );
             controller.enqueue(encoder.encode("data: [DONE]\n\n"));
             controller.close();
@@ -201,10 +251,13 @@ export class ModelProxy {
         if (!sent) {
           this.pending.delete(requestId);
           clearTimeout(timer);
+          const errChunk = {
+            id: `chatcmpl-${requestId}`,
+            object: "chat.completion.chunk",
+            choices: [{ index: 0, delta: { content: `[ClawMatrix] Cannot reach model node "${targetNodeId}"` }, finish_reason: "stop" }],
+          };
           controller.enqueue(
-            encoder.encode(
-              `data: ${JSON.stringify({ error: "Cannot reach model node" })}\n\n`,
-            ),
+            encoder.encode(`data: ${JSON.stringify(errChunk)}\n\n`),
           );
           controller.enqueue(encoder.encode("data: [DONE]\n\n"));
           controller.close();
@@ -317,7 +370,31 @@ export class ModelProxy {
   handleModelResponse(frame: ModelResponse) {
     if (this.peerManager.router.isFailed(frame.id)) return;
     const pending = this.pending.get(frame.id);
-    if (!pending || pending.stream) return;
+    if (!pending) return;
+
+    // For stream requests, handle error responses (the remote node couldn't
+    // process the request and sent model_res instead of model_stream).
+    if (pending.stream) {
+      if (!frame.payload.success && pending.controller && pending.encoder) {
+        clearTimeout(pending.timer);
+        this.pending.delete(frame.id);
+        try {
+          const errChunk = {
+            id: `chatcmpl-${frame.id}`,
+            object: "chat.completion.chunk",
+            choices: [{ index: 0, delta: { content: `[ClawMatrix] Remote error: ${frame.payload.error}` }, finish_reason: "stop" }],
+          };
+          pending.controller.enqueue(
+            pending.encoder.encode(`data: ${JSON.stringify(errChunk)}\n\n`),
+          );
+          pending.controller.enqueue(pending.encoder.encode("data: [DONE]\n\n"));
+          pending.controller.close();
+        } catch {
+          // controller may already be closed
+        }
+      }
+      return;
+    }
 
     clearTimeout(pending.timer);
     this.pending.delete(frame.id);
@@ -325,27 +402,28 @@ export class ModelProxy {
   }
 
   handleModelStream(frame: ModelStreamChunk) {
+    debug("stream", `id=${frame.id} done=${frame.payload.done} delta=${JSON.stringify(frame.payload.delta?.slice?.(0, 50) ?? frame.payload.delta)} failed=${this.peerManager.router.isFailed(frame.id)} hasPending=${this.pending.has(frame.id)}`);
     if (this.peerManager.router.isFailed(frame.id)) return;
     const pending = this.pending.get(frame.id);
     if (!pending?.stream || !pending.controller || !pending.encoder) return;
 
     try {
       if (frame.payload.done) {
+        const finalChunk: Record<string, unknown> = {
+          id: `chatcmpl-${frame.id}`,
+          object: "chat.completion.chunk",
+          choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+        };
         if (frame.payload.usage) {
-          const usageChunk = {
-            id: `chatcmpl-${frame.id}`,
-            object: "chat.completion.chunk",
-            choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
-            usage: {
-              prompt_tokens: frame.payload.usage.inputTokens,
-              completion_tokens: frame.payload.usage.outputTokens,
-              total_tokens: frame.payload.usage.inputTokens + frame.payload.usage.outputTokens,
-            },
+          finalChunk.usage = {
+            prompt_tokens: frame.payload.usage.inputTokens,
+            completion_tokens: frame.payload.usage.outputTokens,
+            total_tokens: frame.payload.usage.inputTokens + frame.payload.usage.outputTokens,
           };
-          pending.controller.enqueue(
-            pending.encoder.encode(`data: ${JSON.stringify(usageChunk)}\n\n`),
-          );
         }
+        pending.controller.enqueue(
+          pending.encoder.encode(`data: ${JSON.stringify(finalChunk)}\n\n`),
+        );
         pending.controller.enqueue(pending.encoder.encode("data: [DONE]\n\n"));
         pending.controller.close();
         clearTimeout(pending.timer);
@@ -375,6 +453,7 @@ export class ModelProxy {
   /** Handle model_req locally: forward to OpenClaw's configured model provider. */
   async handleModelRequest(frame: ModelRequest): Promise<void> {
     const { id, from, payload } = frame;
+    debug("model_req", `handling model="${payload.model}" from=${from} stream=${payload.stream}`);
 
     const model = this.config.models.find((m) => m.id === payload.model);
     if (!model) {
@@ -403,57 +482,88 @@ export class ModelProxy {
           temperature: payload.temperature,
           max_tokens: payload.maxTokens,
           stream: payload.stream,
+          ...(payload.stream ? { stream_options: { include_usage: true } } : {}),
         }),
       });
 
+      if (!response.ok) {
+        const errBody = await response.text();
+        throw new Error(`Upstream ${response.status}: ${errBody.slice(0, 200)}`);
+      }
+
       if (payload.stream) {
         const reader = response.body?.getReader();
         if (!reader) throw new Error("No response body");
 
-        const decoder = new TextDecoder();
-        let buffer = "";
-
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-
-          buffer += decoder.decode(value, { stream: true });
-          const lines = buffer.split("\n");
-          buffer = lines.pop()!;
-
-          for (const line of lines) {
-            if (!line.startsWith("data: ")) continue;
-            const data = line.slice(6).trim();
-            if (data === "[DONE]") {
-              this.peerManager.sendTo(from, {
-                type: "model_stream",
-                id,
-                from: this.config.nodeId,
-                to: from,
-                timestamp: Date.now(),
-                payload: { delta: "", done: true },
-              } satisfies ModelStreamChunk);
-              break;
-            }
+        try {
+          const decoder = new TextDecoder();
+          let buffer = "";
+          let lastUsage: { inputTokens: number; outputTokens: number } | undefined;
+          let streamDone = false;
 
-            try {
-              const parsed = JSON.parse(data);
-              const d = parsed.choices?.[0]?.delta;
-              const delta = d?.content || d?.reasoning_content || "";
-              if (delta) {
+          while (!streamDone) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop()!;
+
+            for (const line of lines) {
+              if (!line.startsWith("data: ")) continue;
+              const data = line.slice(6).trim();
+              if (data === "[DONE]") {
                 this.peerManager.sendTo(from, {
                   type: "model_stream",
                   id,
                   from: this.config.nodeId,
                   to: from,
                   timestamp: Date.now(),
-                  payload: { delta, done: false },
+                  payload: { delta: "", done: true, usage: lastUsage },
                 } satisfies ModelStreamChunk);
+                streamDone = true;
+                break;
+              }
+
+              try {
+                const parsed = JSON.parse(data);
+                if (parsed.usage) {
+                  lastUsage = {
+                    inputTokens: parsed.usage.prompt_tokens,
+                    outputTokens: parsed.usage.completion_tokens,
+                  };
+                }
+                const d = parsed.choices?.[0]?.delta;
+                const delta = d?.content || d?.reasoning_content || "";
+                if (delta) {
+                  this.peerManager.sendTo(from, {
+                    type: "model_stream",
+                    id,
+                    from: this.config.nodeId,
+                    to: from,
+                    timestamp: Date.now(),
+                    payload: { delta, done: false },
+                  } satisfies ModelStreamChunk);
+                }
+              } catch {
+                // skip malformed chunks
               }
-            } catch {
-              // skip malformed chunks
             }
           }
+          // If the upstream closed without sending [DONE], send a completion
+          // frame so the requesting side doesn't hang until MODEL_TIMEOUT.
+          if (!streamDone) {
+            this.peerManager.sendTo(from, {
+              type: "model_stream",
+              id,
+              from: this.config.nodeId,
+              to: from,
+              timestamp: Date.now(),
+              payload: { delta: "", done: true, usage: lastUsage },
+            } satisfies ModelStreamChunk);
+          }
+        } finally {
+          reader.releaseLock();
         }
       } else {
         const result = (await response.json()) as {

package/src/peer-manager.ts

@@ -33,6 +33,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   private stopped = false;
   /** Map from ws WebSocket to Connection for inbound connections. */
   private inboundConnections = new Map<WsWebSocket, Connection>();
+  private gossipDebounceTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(config: ClawMatrixConfig) {
     super();
@@ -62,6 +63,10 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
   async stop() {
     this.stopped = true;
+    if (this.gossipDebounceTimer) {
+      clearTimeout(this.gossipDebounceTimer);
+      this.gossipDebounceTimer = null;
+    }
     for (const timer of this.reconnectTimers.values()) {
       clearTimeout(timer);
     }
@@ -86,6 +91,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       this.httpServer.close();
       this.httpServer = null;
     }
+
+    this.router.destroy();
   }
 
   // ── Inbound WS server (node:http + ws) ──────────────────────────
@@ -119,6 +126,10 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       });
     });
 
+    this.httpServer.on("error", (err) => {
+      console.error(`[clawmatrix] WS server error on port ${port}: ${err.message}`);
+    });
+
     this.httpServer.listen(port, hostname);
   }
 
@@ -319,13 +330,17 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       }
     }
 
-    // If we learned new info, re-sync with other peers
+    // If we learned new info, re-sync with other peers (debounced to avoid storms)
     if (changed) {
-      for (const conn of this.router.getDirectConnections()) {
-        if (conn !== from && conn.isOpen) {
-          this.sendPeerSync(conn);
+      if (this.gossipDebounceTimer) clearTimeout(this.gossipDebounceTimer);
+      this.gossipDebounceTimer = setTimeout(() => {
+        this.gossipDebounceTimer = null;
+        for (const conn of this.router.getDirectConnections()) {
+          if (conn !== from && conn.isOpen) {
+            this.sendPeerSync(conn);
+          }
         }
-      }
+      }, 100);
     }
   }
 
@@ -334,6 +349,18 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     return this.router.sendTo(nodeId, frame);
   }
 
+  /** Check if a node is reachable (direct or via relay) without sending. */
+  canReach(nodeId: string): boolean {
+    const route = this.router.getRoute(nodeId);
+    if (!route) return false;
+    if (route.connection?.isOpen) return true;
+    if (route.reachableVia) {
+      const relay = this.router.getRoute(route.reachableVia);
+      return !!relay?.connection?.isOpen;
+    }
+    return false;
+  }
+
   broadcast(frame: ClusterFrame | AnyClusterFrame) {
     this.router.broadcast(frame);
   }

package/src/router.ts

@@ -4,6 +4,7 @@ import type { Connection } from "./connection.ts";
 const DEFAULT_TTL = 3;
 const SEEN_FRAME_TTL = 60_000; // 60s dedup window
 const MAX_SEEN_FRAMES = 10_000;
+const PRUNE_INTERVAL = 30_000; // periodic cleanup every 30s
 
 export interface RouteEntry {
   nodeId: string;
@@ -24,6 +25,7 @@ export class Router {
   private routes = new Map<string, RouteEntry>();
   private connections = new Map<string, Connection>(); // nodeId → direct connection
   private seenFrames = new Map<string, number>(); // frameId → timestamp
+  private pruneTimer: ReturnType<typeof setInterval> | null = null;
 
   constructor(
     nodeId: string,
@@ -33,6 +35,17 @@ export class Router {
     this.localAgents = localCapabilities?.agents ?? [];
     this.localModels = localCapabilities?.models ?? [];
     this.localTags = localCapabilities?.tags ?? [];
+
+    this.pruneTimer = setInterval(() => this.pruneSeenFrames(true), PRUNE_INTERVAL);
+  }
+
+  /** Stop periodic cleanup. Call on shutdown. */
+  destroy() {
+    if (this.pruneTimer) {
+      clearInterval(this.pruneTimer);
+      this.pruneTimer = null;
+    }
+    this.seenFrames.clear();
   }
 
   // ── Route table management ─────────────────────────────────────
@@ -211,7 +224,9 @@ export class Router {
   tryRelay(frame: ClusterFrame): boolean {
     if (!frame.to || frame.to === this.nodeId) return false;
 
-    const ttl = (frame.ttl ?? DEFAULT_TTL) - 1;
+    const rawTtl = frame.ttl ?? DEFAULT_TTL;
+    if (typeof rawTtl !== "number" || !Number.isFinite(rawTtl) || rawTtl < 1) return false;
+    const ttl = rawTtl - 1;
     if (ttl <= 0) return false;
 
     const relayed = this.sendTo(frame.to, { ...frame, ttl });
@@ -238,8 +253,8 @@ export class Router {
     return this.seenFrames.has(`failed:${requestId}`);
   }
 
-  private pruneSeenFrames() {
-    if (this.seenFrames.size <= MAX_SEEN_FRAMES) return;
+  private pruneSeenFrames(force = false) {
+    if (!force && this.seenFrames.size <= MAX_SEEN_FRAMES) return;
     const now = Date.now();
     for (const [id, ts] of this.seenFrames) {
       if (now - ts > SEEN_FRAME_TTL) {

package/src/tool-proxy.ts

@@ -1,6 +1,7 @@
 import type { PeerManager } from "./peer-manager.ts";
 import type { ClawMatrixConfig, ToolProxyConfig } from "./config.ts";
 import type { ToolProxyRequest, ToolProxyResponse } from "./types.ts";
+import { isLocalTool, executeLocally } from "./local-tools.ts";
 
 const TOOL_TIMEOUT = 30_000;
 
@@ -113,7 +114,9 @@ export class ToolProxy {
     }
 
     try {
-      const result = await this.executeViaGateway(payload.tool, payload.params);
+      const result = isLocalTool(payload.tool)
+        ? await executeLocally(payload.tool, payload.params)
+        : await this.executeViaGateway(payload.tool, payload.params);
       this.sendResponse(id, from, { success: true, result });
     } catch (err) {
       this.sendResponse(id, from, {

package/src/types.ts

@@ -170,10 +170,26 @@ export interface AgentInfo {
   tags: string[];
 }
 
+export interface ModelCompatInfo {
+  supportsTools?: boolean;
+  supportsStore?: boolean;
+  supportsDeveloperRole?: boolean;
+  supportsReasoningEffort?: boolean;
+  supportsUsageInStreaming?: boolean;
+  supportsStrictMode?: boolean;
+  maxTokensField?: "max_completion_tokens" | "max_tokens";
+  thinkingFormat?: "openai" | "zai" | "qwen";
+  requiresToolResultName?: boolean;
+  requiresAssistantAfterToolResult?: boolean;
+  requiresThinkingAsText?: boolean;
+  requiresMistralToolIds?: boolean;
+}
+
 export interface ModelInfo {
   id: string;
   provider: string;
   description?: string;
+  compat?: ModelCompatInfo;
 }
 
 export interface PeerInfo {