clawmatrix 0.1.16 → 0.1.18

package/openclaw.plugin.json

@@ -5,73 +5,7 @@
   "providers": ["clawmatrix"],
   "configSchema": {
     "type": "object",
-    "properties": {
-      "nodeId": { "type": "string" },
-      "secret": { "type": "string" },
-      "listen": { "type": "boolean", "default": false },
-      "listenHost": { "type": "string", "default": "0.0.0.0" },
-      "listenPort": { "type": "number", "default": 19000 },
-      "peers": {
-        "type": "array",
-        "items": {
-          "type": "object",
-          "properties": {
-            "nodeId": { "type": "string" },
-            "url": { "type": "string" }
-          },
-          "required": ["nodeId", "url"]
-        },
-        "default": []
-      },
-      "agents": {
-        "type": "array",
-        "items": {
-          "type": "object",
-          "properties": {
-            "id": { "type": "string" },
-            "description": { "type": "string" },
-            "tags": { "type": "array", "items": { "type": "string" }, "default": [] }
-          },
-          "required": ["id", "description"]
-        },
-        "default": []
-      },
-      "models": {
-        "type": "array",
-        "items": {
-          "type": "object",
-          "properties": {
-            "id": { "type": "string" },
-            "provider": { "type": "string" },
-            "description": { "type": "string" }
-          },
-          "required": ["id", "provider"]
-        },
-        "default": []
-      },
-      "tags": { "type": "array", "items": { "type": "string" }, "default": [] },
-      "proxyPort": { "type": "number", "default": 19001 },
-      "toolProxy": {
-        "type": "object",
-        "properties": {
-          "enabled": { "type": "boolean", "default": false },
-          "allow": {
-            "type": "array",
-            "items": { "type": "string" },
-            "default": [],
-            "description": "Allowed OpenClaw tool names. Use [\"*\"] for all. Empty or [\"*\"] = all allowed."
-          },
-          "deny": {
-            "type": "array",
-            "items": { "type": "string" },
-            "default": [],
-            "description": "Denied OpenClaw tool names (takes precedence over allow)."
-          },
-          "maxOutputBytes": { "type": "number", "default": 1048576 }
-        }
-      }
-    },
-    "required": ["nodeId", "secret"]
+    "additionalProperties": true
   },
   "uiHints": {
     "secret": { "sensitive": true, "label": "Cluster Secret", "help": "Shared secret for HMAC authentication between nodes" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",
@@ -32,9 +32,11 @@
     "release": "bunx bumpp"
   },
   "dependencies": {
+    "@automerge/automerge": "^3.2.4",
+    "@mariozechner/pi-coding-agent": ">=0.55.0",
+    "ignore": "^7.0.5",
     "ws": "^8.19.0",
-    "zod": "^4.3.6",
-    "@mariozechner/pi-coding-agent": ">=0.55.0"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/cluster-service.ts

@@ -4,6 +4,7 @@ import type {
   OpenClawConfig,
   PluginLogger,
 } from "openclaw/plugin-sdk";
+import path from "node:path";
 import type { ClawMatrixConfig } from "./config.ts";
 import { spawnProcess } from "./compat.ts";
 import { debug } from "./debug.ts";
@@ -12,6 +13,7 @@ import { HandoffManager } from "./handoff.ts";
 import { ModelProxy } from "./model-proxy.ts";
 import { ToolProxy, type GatewayInfo } from "./tool-proxy.ts";
 import { WebHandler } from "./web.ts";
+import { KnowledgeSync } from "./knowledge-sync.ts";
 import type {
   AnyClusterFrame,
   HandoffRequest,
@@ -22,6 +24,7 @@ import type {
   HandoffStatusResponse,
   HandoffInputRequired,
   HandoffInput,
+  KnowledgeSyncFrame,
   ModelRequest,
   ModelResponse,
   ModelStreamChunk,
@@ -49,12 +52,15 @@ export class ClusterRuntime {
   readonly handoffManager: HandoffManager;
   readonly modelProxy: ModelProxy;
   readonly toolProxy: ToolProxy;
+  knowledgeSync: KnowledgeSync | null = null;
   webHandler: WebHandler | null = null;
   private logger: PluginLogger;
+  private openclawConfig: OpenClawConfig;
 
   constructor(config: ClawMatrixConfig, logger: PluginLogger, openclawConfig: OpenClawConfig, openclawVersion?: string) {
     this.config = config;
     this.logger = logger;
+    this.openclawConfig = openclawConfig;
     const gatewayInfo = resolveGatewayInfo(openclawConfig);
     this.peerManager = new PeerManager(config, openclawVersion);
     this.handoffManager = new HandoffManager(config, this.peerManager);
@@ -85,6 +91,34 @@ export class ClusterRuntime {
       this.logger.info(`[clawmatrix] Web dashboard enabled on listen port`);
     }
 
+    // Knowledge sync
+    if (this.config.knowledge?.enabled) {
+      const workspacePath = this.resolveWorkspacePath();
+      if (workspacePath) {
+        const stateDir = path.join(path.dirname(workspacePath), ".clawmatrix");
+        this.knowledgeSync = new KnowledgeSync({
+          workspacePath,
+          storePath: path.join(stateDir, "knowledge.automerge"),
+          nodeId: this.config.nodeId,
+          debounce: this.config.knowledge.debounce ?? 5000,
+          peerManager: this.peerManager,
+        });
+        this.knowledgeSync.start().then(() => {
+          this.logger.info(`[clawmatrix] Knowledge sync started: ${workspacePath}`);
+        }).catch((err) => {
+          this.logger.error(`[clawmatrix] Knowledge sync failed to start: ${err}`);
+        });
+
+        // Sync with peers on connect/disconnect
+        this.peerManager.on("peerConnected", (nodeId) => {
+          this.knowledgeSync?.initPeerSync(nodeId);
+        });
+        this.peerManager.on("peerDisconnected", (nodeId) => {
+          this.knowledgeSync?.removePeerSync(nodeId);
+        });
+      }
+    }
+
     // Start subsystems
     this.peerManager.start();
     this.modelProxy.start();
@@ -97,6 +131,7 @@ export class ClusterRuntime {
   }
 
   async stop() {
+    await this.knowledgeSync?.stop();
     this.webHandler?.destroy();
     this.handoffManager.destroy();
     this.modelProxy.stop();
@@ -105,6 +140,24 @@ export class ClusterRuntime {
     this.logger.info(`[clawmatrix] Node "${this.config.nodeId}" stopped`);
   }
 
+  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
+      | { list?: Array<{ id?: string; default?: boolean; workspace?: string }>; defaults?: { workspace?: string } }
+      | undefined;
+    if (!agents) return null;
+    const list = agents.list ?? [];
+    const defaultAgent = list.find((a) => a.default) ?? list[0];
+    const workspace = defaultAgent?.workspace ?? agents.defaults?.workspace;
+    if (!workspace) return null;
+    // Resolve ~ to home directory
+    if (workspace.startsWith("~/") || workspace === "~") {
+      const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+      return path.resolve(home, workspace.slice(2));
+    }
+    return path.resolve(workspace);
+  }
+
   private dispatchFrame(frame: AnyClusterFrame) {
     if (frame.type.startsWith("model_")) {
       debug("dispatch", `${frame.type} id=${frame.id} from=${frame.from}`);
@@ -161,6 +214,11 @@ export class ClusterRuntime {
       case "send":
         this.handleSendMessage(frame as SendMessage);
         break;
+      case "knowledge_sync":
+        this.knowledgeSync?.handleSyncMessage(frame as KnowledgeSyncFrame).catch((err) => {
+          this.logger.error(`[clawmatrix] Knowledge sync error: ${err}`);
+        });
+        break;
     }
   }
 

package/src/config.ts

@@ -77,6 +77,11 @@ const ProxyModelGroupSchema = z.object({
   models: z.array(ProxyModelEntrySchema),
 });
 
+const KnowledgeConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  debounce: z.number().default(5000),
+}).optional();
+
 const WebConfigSchema = z.object({
   enabled: z.boolean().default(false),
   token: z.string().min(8, "web token must be at least 8 characters"),
@@ -97,6 +102,7 @@ const RawClawMatrixConfigSchema = z.object({
   toolProxy: ToolProxyConfigSchema.optional(),
   handoffTimeout: z.number().default(600_000),
   web: WebConfigSchema,
+  knowledge: KnowledgeConfigSchema,
 });
 
 /** Flat proxy model after group expansion (used internally). */
@@ -122,9 +128,15 @@ 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. */
+/** Parse and flatten grouped proxyModels into flat array.
+ *  Uses passthrough() to ignore unknown fields and safeParse to avoid crashing. */
 export function parseConfig(raw: unknown): ClawMatrixConfig {
-  const parsed = RawClawMatrixConfigSchema.parse(raw);
+  const result = RawClawMatrixConfigSchema.passthrough().safeParse(raw);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    throw new Error(`ClawMatrix config error: ${issues}`);
+  }
+  const parsed = result.data;
 
   // Flatten proxy model groups
   const proxyModels: ProxyModel[] = [];

package/src/index.ts

@@ -21,24 +21,20 @@ const plugin = {
 
   configSchema: {
     safeParse(value: unknown) {
-      const result = ClawMatrixConfigSchema.safeParse(value);
-      if (result.success) {
-        return { success: true, data: result.data };
-      }
-      return {
-        success: false,
-        error: {
-          issues: result.error.issues.map((i) => ({
-            path: i.path.map(String),
-            message: i.message,
-          })),
-        },
-      };
+      // Always pass — validation is handled internally with warnings
+      return { success: true, data: value };
     },
   },
 
   register(api: OpenClawPluginApi) {
-    const config = parseConfig(api.pluginConfig);
+    let config: ReturnType<typeof parseConfig>;
+    try {
+      config = parseConfig(api.pluginConfig);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`[clawmatrix] Config error (plugin disabled): ${message}`);
+      return;
+    }
 
     // Background service: manages mesh connections, WS listener, heartbeat
     api.registerService(createClusterService(config, api.config, api.runtime.version));
@@ -164,70 +160,63 @@ const plugin = {
     // CLI subcommand
     api.registerCli(registerClusterCli, { commands: ["clawmatrix"] });
 
-    // Inject cluster context into agent prompts
+    // Inject cluster context into agent prompts.
+    //
+    // Minimal-injection strategy:
+    //   prependSystemContext (cached) = static identity + guidance + peer count.
+    //     Content is stable across turns → prompt caching works.
+    //     Peer count is included so the agent knows the cluster exists;
+    //     detailed topology is on-demand via cluster_peers tool.
+    //   prependContext (per-turn) = only pending event notifications.
+    //     Events need proactive push so the agent can react without being asked.
+    //     Everything else (peer details, satellites) is pull-based via tools.
+
+    let cachedPeerCount = -1;
+    let cachedSystemContext = "";
+
     api.on("before_prompt_build", () => {
       try {
         const runtime = getClusterRuntime();
-        const peers = runtime.peerManager.router.getAllPeers();
-        if (peers.length === 0) return;
-
-        const lines = [
-          `[ClawMatrix Cluster]`,
-          `You are on node "${config.nodeId}"${config.tags.length ? ` (tags: ${config.tags.join(", ")})` : ""}.`,
-        ];
+        const peerCount = runtime.peerManager.router.getAllPeers().length;
 
-        if (config.agents.length > 0) {
-          const localAgent = config.agents[0]!;
-          lines.push(`Your role: ${localAgent.description}`);
-        }
-
-        // Satellite nodes (via WebHandler on relay, or gossiped via peer_sync)
-        const satellites = runtime.webHandler?.getSatelliteContexts() ?? runtime.peerManager.satelliteContexts;
-        const activeSatellites = satellites.filter(s => Date.now() - s.ts < 600_000);
-
-        lines.push("", "Remote nodes in the cluster:");
-        for (const peer of peers) {
-          const status = peer.connection?.isOpen ? "connected" : "via relay";
-          const tags = peer.tags.length ? ` [${peer.tags.join(", ")}]` : "";
-          lines.push(`  - ${peer.nodeId} (${status})${tags}`);
-          for (const agent of peer.agents) {
-            lines.push(`    agent "${agent.id}": ${agent.description}`);
-          }
-          if (peer.models.length > 0) {
-            lines.push(`    models: ${peer.models.map((m) => m.id).join(", ")}`);
-          }
-        }
-        for (const sat of activeSatellites) {
-          const age = Math.floor((Date.now() - sat.ts) / 1000);
-          const country = sat.country ? `, ${sat.country}` : "";
-          lines.push(`  - ${sat.nodeId} (satellite${country}, ${age}s ago)`);
-          if (sat.tools?.length) {
-            lines.push(`    tools: ${sat.tools.join(", ")}`);
+        // Rebuild system context only when peer count changes
+        if (peerCount !== cachedPeerCount) {
+          cachedPeerCount = peerCount;
+          const lines: string[] = [];
+          if (peerCount === 0) {
+            lines.push("[ClawMatrix] No peers online. Use cluster_peers to check cluster status.");
+          } else {
+            lines.push(
+              `[ClawMatrix Cluster] node="${config.nodeId}"${config.tags.length ? ` tags=${config.tags.join(",")}` : ""}`,
+              ...(config.agents.length > 0 ? [`Role: ${config.agents[0]!.description}`] : []),
+              `${peerCount} remote peer(s) online. Use cluster_peers to see topology, agents, and models.`,
+              "Prefer cluster_exec/read/write for simple ops; cluster_handoff for complex multi-step tasks.",
+              "IMPORTANT: Always tell user which remote node you're targeting before calling cluster tools.",
+            );
           }
+          cachedSystemContext = lines.join("\n");
         }
 
-        // Unconsumed events from external sources (Shortcuts automations, etc.)
+        // Per-turn: only push pending events (agent must react proactively)
         const pendingEvents = runtime.webHandler?.getUnconsumedEvents(5) ?? [];
+        let prependContext: string | undefined;
         if (pendingEvents.length > 0) {
-          lines.push("", "⚡ Pending events:");
+          const evtLines = ["Pending events (use cluster_events to query details or consume):"];
           for (const evt of pendingEvents) {
             const age = Math.floor((Date.now() - evt.ts) / 1000);
             const dataStr = Object.entries(evt.data)
-              .map(([k, v]) => `${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`)
-              .join(", ");
+              .map(([k, v]) => `${k}:${typeof v === "string" ? v : JSON.stringify(v)}`)
+              .join(",");
             const truncated = dataStr.length > 120 ? dataStr.slice(0, 120) + "…" : dataStr;
-            lines.push(`  - [${evt.type}] ${evt.source} (${age}s ago, id:${evt.id}): ${truncated}`);
+            evtLines.push(`  [${evt.type}] ${evt.source} (${age}s,id:${evt.id}): ${truncated}`);
           }
-          lines.push("Use cluster_events for details or to mark consumed.");
+          prependContext = evtLines.join("\n");
         }
 
-        lines.push(
-          "",
-          "Prefer cluster_exec/read/write for simple ops; cluster_handoff for complex multi-step tasks.",
-          "IMPORTANT: Always tell user which remote node you're targeting before calling cluster tools.",
-        );
-
-        return { prependSystemContext: lines.join("\n") };
+        return {
+          prependSystemContext: cachedSystemContext,
+          ...(prependContext ? { prependContext } : {}),
+        };
       } catch {
         return;
       }