clawmatrix 0.1.6 → 0.1.11

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";
@@ -14,6 +15,7 @@ import type {
   AnyClusterFrame,
   HandoffRequest,
   HandoffResponse,
+  HandoffStreamChunk,
   ModelRequest,
   ModelResponse,
   ModelStreamChunk,
@@ -87,12 +89,18 @@ 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) => {
           this.logger.error(`[clawmatrix] Handoff request error: ${err}`);
         });
         break;
+      case "handoff_stream":
+        this.handoffManager.handleStream(frame as HandoffStreamChunk);
+        break;
       case "handoff_res":
         this.handoffManager.handleResponse(frame as HandoffResponse);
         break;
@@ -139,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({
@@ -63,6 +79,7 @@ export const ClawMatrixConfigSchema = z.object({
   tags: z.array(z.string()).default([]),
   proxyPort: z.number().default(19001),
   toolProxy: ToolProxyConfigSchema.optional(),
+  handoffTimeout: z.number().default(600_000),
 });
 
 export type ClawMatrixConfig = z.infer<typeof ClawMatrixConfigSchema>;

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/handoff.ts

@@ -4,10 +4,10 @@ import { spawnProcess } from "./compat.ts";
 import type {
   HandoffRequest,
   HandoffResponse,
-  AnyClusterFrame,
+  HandoffStreamChunk,
 } from "./types.ts";
 
-const HANDOFF_TIMEOUT = 120_000; // 2 minutes
+const DEFAULT_HANDOFF_TIMEOUT = 600_000; // 10 minutes (resets on each stream chunk)
 const MAX_RETRIES = 2;
 
 interface PendingHandoff {
@@ -18,6 +18,7 @@ interface PendingHandoff {
   retriesLeft: number;
   task: string;
   context?: string;
+  accumulated: string;
 }
 
 export class HandoffManager {
@@ -54,24 +55,9 @@ export class HandoffManager {
     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);
+      const timer = this.createTimeout(id, targetNodeId, target, task, context, retriesLeft, resolve, reject);
 
-      this.pending.set(id, { resolve, reject, timer, target, retriesLeft, task, context });
+      this.pending.set(id, { resolve, reject, timer, target, retriesLeft, task, context, accumulated: "" });
 
       const frame: HandoffRequest = {
         type: "handoff_req",
@@ -102,6 +88,57 @@ export class HandoffManager {
     });
   }
 
+  private createTimeout(
+    id: string,
+    targetNodeId: string,
+    target: string,
+    task: string,
+    context: string | undefined,
+    retriesLeft: number,
+    resolve: (result: HandoffResponse["payload"]) => void,
+    reject: (error: Error) => void,
+  ): ReturnType<typeof setTimeout> {
+    return 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`));
+    }, this.config.handoffTimeout ?? DEFAULT_HANDOFF_TIMEOUT);
+  }
+
+  /** Handle incoming stream chunk — reset timeout & accumulate. */
+  handleStream(frame: HandoffStreamChunk) {
+    if (this.peerManager.router.isFailed(frame.id)) return;
+
+    const pending = this.pending.get(frame.id);
+    if (!pending) return;
+
+    pending.accumulated += frame.payload.delta;
+
+    // Reset timeout — the remote agent is still working
+    clearTimeout(pending.timer);
+    pending.timer = this.createTimeout(
+      frame.id,
+      frame.from,
+      pending.target,
+      pending.task,
+      pending.context,
+      pending.retriesLeft,
+      pending.resolve,
+      pending.reject,
+    );
+  }
+
   /** Handle incoming handoff response. */
   handleResponse(frame: HandoffResponse) {
     if (this.peerManager.router.isFailed(frame.id)) return;
@@ -111,6 +148,12 @@ export class HandoffManager {
 
     clearTimeout(pending.timer);
     this.pending.delete(frame.id);
+
+    // If the response has no result but we accumulated stream data, use that
+    if (frame.payload.success && !frame.payload.result && pending.accumulated) {
+      frame.payload.result = pending.accumulated;
+    }
+
     pending.resolve(frame.payload);
   }
 
@@ -153,7 +196,8 @@ export class HandoffManager {
         { stdout: "pipe", stderr: "pipe" },
       );
 
-      const stdout = proc.stdout ? await new Response(proc.stdout).text() : "";
+      // Stream stdout chunks back to the caller
+      const fullOutput = await this.streamStdout(proc.stdout, id, from);
       const exitCode = await proc.exited;
 
       if (exitCode !== 0) {
@@ -171,7 +215,7 @@ export class HandoffManager {
           success: true,
           nodeId: this.config.nodeId,
           agent: agent.id,
-          result: stdout.trim(),
+          result: fullOutput.trim(),
         },
       } satisfies HandoffResponse);
     } catch (err) {
@@ -191,9 +235,55 @@ export class HandoffManager {
     }
   }
 
+  /** Read stdout incrementally, sending handoff_stream chunks to the caller. */
+  private async streamStdout(
+    stdout: ReadableStream | null,
+    handoffId: string,
+    to: string,
+  ): Promise<string> {
+    if (!stdout) return "";
+
+    const reader = stdout.getReader();
+    const decoder = new TextDecoder();
+    let full = "";
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        full += chunk;
+
+        this.peerManager.sendTo(to, {
+          type: "handoff_stream",
+          id: handoffId,
+          from: this.config.nodeId,
+          to,
+          timestamp: Date.now(),
+          payload: { delta: chunk, done: false },
+        } satisfies HandoffStreamChunk);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+
+    // Send final done marker
+    this.peerManager.sendTo(to, {
+      type: "handoff_stream",
+      id: handoffId,
+      from: this.config.nodeId,
+      to,
+      timestamp: Date.now(),
+      payload: { delta: "", done: true },
+    } satisfies HandoffStreamChunk);
+
+    return full;
+  }
+
   /** Clean up on shutdown. */
   destroy() {
-    for (const [id, pending] of this.pending) {
+    for (const [, pending] of this.pending) {
       clearTimeout(pending.timer);
       pending.reject(new Error("Shutting down"));
     }

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi, GatewayRequestHandlerOptions } from "openclaw/plugin-sdk";
 import { ClawMatrixConfigSchema, parseConfig } from "./config.ts";
 import { createClusterService, getClusterRuntime } from "./cluster-service.ts";
 import { createClusterHandoffTool } from "./tools/cluster-handoff.ts";
@@ -41,18 +41,51 @@ const plugin = {
     // Background service: manages mesh connections, WS listener, heartbeat
     api.registerService(createClusterService(config, api.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),
-      },
-    });
+    // Model providers: register per-node providers so models are accessed as nodeId/modelId
+    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 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 };
+        }
+      }
+    };
+
+    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}`,
+        docsPath: "/plugins/clawmatrix",
+        auth: [],
+        models: {
+          baseUrl,
+          apiKey: "sk-clawmatrix-proxy",
+          models,
+        },
+      });
+    }
 
     // Agent tools
     api.registerTool(createClusterHandoffTool(), { optional: true });
@@ -63,6 +96,57 @@ const plugin = {
     api.registerTool(createClusterWriteTool(), { optional: true });
     api.registerTool(createClusterToolTool(), { optional: true });
 
+    // Gateway methods (queried by CLI via `openclaw gateway call`)
+    api.registerGatewayMethod(
+      "clawmatrix.status",
+      ({ respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          const peers = runtime.peerManager.router.getAllPeers();
+          respond(true, {
+            nodeId: config.nodeId,
+            listen: config.listen ? config.listenPort : false,
+            proxyPort: config.proxyPort,
+            agents: config.agents.map((a) => ({ id: a.id, description: a.description })),
+            models: config.models.map((m) => ({ id: m.id })),
+            tags: config.tags,
+            peers: peers.map((p) => ({
+              nodeId: p.nodeId,
+              agents: p.agents,
+              models: p.models,
+              tags: p.tags,
+              connected: !!p.connection?.isOpen,
+              reachableVia: p.reachableVia,
+              latencyMs: p.latencyMs,
+            })),
+          });
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
+    api.registerGatewayMethod(
+      "clawmatrix.peers",
+      ({ respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          const peers = runtime.peerManager.router.getAllPeers().map((p) => ({
+            nodeId: p.nodeId,
+            agents: p.agents,
+            models: p.models,
+            tags: p.tags,
+            connected: !!p.connection?.isOpen,
+            reachableVia: p.reachableVia,
+            latencyMs: p.latencyMs,
+          }));
+          respond(true, peers);
+        } catch {
+          respond(true, []);
+        }
+      },
+    );
+
     // CLI subcommand
     api.registerCli(registerClusterCli, { commands: ["clawmatrix"] });
 
@@ -117,17 +201,8 @@ const plugin = {
   },
 };
 
-function getAllClusterModels(config: ReturnType<typeof parseConfig>) {
-  // models = models this node serves to the cluster
-  // proxyModels = remote models this node wants to consume from the cluster
-  // Both need to be registered with the OpenClaw provider so it routes requests to our local proxy.
-  const seen = new Set<string>();
-  const all = [...config.models, ...config.proxyModels].filter((m) => {
-    if (seen.has(m.id)) return false;
-    seen.add(m.id);
-    return true;
-  });
-  return all.map((m) => ({
+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),
@@ -136,7 +211,27 @@ function getAllClusterModels(config: ReturnType<typeof parseConfig>) {
     cost: m.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     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>[]> {
+  const result: Record<string, ReturnType<typeof formatModel>[]> = {};
+
+  // Local models served by this node
+  for (const m of config.models) {
+    const nodeId = config.nodeId;
+    (result[nodeId] ??= []).push(formatModel(m));
+  }
+
+  // Remote models consumed from peers (proxyModels have nodeId)
+  for (const m of config.proxyModels) {
+    const nodeId = m.nodeId;
+    (result[nodeId] ??= []).push(formatModel(m));
+  }
+
+  return result;
 }
 
 export default plugin;

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,
+  };
+}