clawmatrix 0.1.16 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -164,70 +164,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(", ")})` : ""}.`,
-        ];
-
-        if (config.agents.length > 0) {
-          const localAgent = config.agents[0]!;
-          lines.push(`Your role: ${localAgent.description}`);
-        }
+        const peerCount = runtime.peerManager.router.getAllPeers().length;
 
-        // 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;
       }

package/src/tools/cluster-events.ts

@@ -13,32 +13,32 @@ export function createClusterEventsTool(): AnyAgentTool {
         action: {
           type: "string",
           enum: ["query", "consume"],
-          description: '"query" to list events, "consume" to mark events as processed',
+          description: '"query" to list events (type/source/unconsumed/since/limit filters apply), "consume" to mark as processed (requires ids)',
         },
         type: {
           type: "string",
-          description: 'Filter by event type (e.g. "message_received", "call_missed"). Only for action=query.',
+          description: 'Filter by event type (e.g. "message_received")',
         },
         source: {
           type: "string",
-          description: 'Filter by source (e.g. "shortcuts", "iphone"). Only for action=query.',
+          description: 'Filter by source (e.g. "shortcuts")',
         },
         unconsumed: {
           type: "boolean",
-          description: "Only return unconsumed events. Default true. Only for action=query.",
+          description: "Only unconsumed events (default true)",
         },
         since: {
           type: "number",
-          description: "Only return events after this unix timestamp (ms). Only for action=query.",
+          description: "Events after this unix timestamp (ms)",
         },
         limit: {
           type: "number",
-          description: "Max events to return. Default 20. Only for action=query.",
+          description: "Max events to return (default 20)",
         },
         ids: {
           type: "array",
           items: { type: "string" },
-          description: "Event IDs to mark as consumed. Required for action=consume.",
+          description: "Event IDs to consume",
         },
       },
       required: ["action"],
@@ -105,7 +105,7 @@ export function createClusterEventsTool(): AnyAgentTool {
         }));
 
         return {
-          content: [{ type: "text" as const, text: JSON.stringify(summary, null, 2) }],
+          content: [{ type: "text" as const, text: JSON.stringify(summary) }],
           details: { events: summary },
         };
       } catch (err) {

package/src/tools/cluster-exec.ts

@@ -53,7 +53,7 @@ export function createClusterExecTool(): AnyAgentTool {
           content: [
             {
               type: "text" as const,
-              text: JSON.stringify(result, null, 2),
+              text: JSON.stringify(result),
             },
           ],
           details: result,

package/src/tools/cluster-handoff-reply.ts

@@ -34,7 +34,7 @@ export function createClusterHandoffReplyTool(): AnyAgentTool {
             content: [
               {
                 type: "text" as const,
-                text: `Remote agent needs more information.\n\nHandoff ID: ${result.handoffId}\nQuestion: ${result.result}\n\nUse cluster_handoff_reply again to respond.`,
+                text: `Input required (handoff_id:${result.handoffId}): ${result.result}`,
               },
             ],
             details: result,
@@ -52,11 +52,7 @@ export function createClusterHandoffReplyTool(): AnyAgentTool {
           content: [
             {
               type: "text" as const,
-              text: JSON.stringify(
-                { nodeId: result.nodeId, agent: result.agent, result: result.result },
-                null,
-                2,
-              ),
+              text: JSON.stringify({ nodeId: result.nodeId, agent: result.agent, result: result.result }),
             },
           ],
           details: result,

package/src/tools/cluster-handoff.ts

@@ -42,7 +42,7 @@ export function createClusterHandoffTool(): AnyAgentTool {
             content: [
               {
                 type: "text" as const,
-                text: `Remote agent needs more information before continuing.\n\nHandoff ID: ${result.handoffId}\nQuestion: ${result.result}\n\nUse cluster_handoff_reply tool to respond.`,
+                text: `Input required (handoff_id:${result.handoffId}): ${result.result}`,
               },
             ],
             details: result,
@@ -65,15 +65,7 @@ export function createClusterHandoffTool(): AnyAgentTool {
           content: [
             {
               type: "text" as const,
-              text: JSON.stringify(
-                {
-                  nodeId: result.nodeId,
-                  agent: result.agent,
-                  result: result.result,
-                },
-                null,
-                2,
-              ),
+              text: JSON.stringify({ nodeId: result.nodeId, agent: result.agent, result: result.result }),
             },
           ],
           details: result,

package/src/tools/cluster-peers.ts

@@ -21,36 +21,29 @@ export function createClusterPeersTool(): AnyAgentTool {
             description: a.description,
             tags: a.tags,
           })),
-          models: entry.models.map((m) => ({
-            id: m.id,
-            provider: m.provider,
-          })),
+          models: entry.models.map((m) => m.id),
           tags: entry.tags,
           tools: entry.toolProxy?.enabled ? (entry.toolProxy.allow ?? []) : [],
           status: entry.connection?.isOpen ? "connected" : "unreachable",
           latencyMs: entry.latencyMs,
         }));
 
-        // Include satellite nodes
+        // Include satellite nodes (minimal fields — no agents/models)
         const satellites = runtime.webHandler?.getSatelliteContexts() ?? runtime.peerManager.satelliteContexts;
         for (const sat of satellites) {
           if (Date.now() - sat.ts >= 600_000) continue;
           peers.push({
             nodeId: sat.nodeId,
-            agents: [],
-            models: [],
-            tags: [],
             tools: sat.tools ?? [],
             status: "satellite",
-            latencyMs: undefined,
-          });
+          } as (typeof peers)[number]);
         }
 
         return {
           content: [
             {
               type: "text" as const,
-              text: JSON.stringify(peers, null, 2),
+              text: JSON.stringify(peers),
             },
           ],
           details: peers,

package/src/tools/cluster-read.ts

@@ -30,7 +30,7 @@ export function createClusterReadTool(): AnyAgentTool {
           content: [
             {
               type: "text" as const,
-              text: JSON.stringify(result, null, 2),
+              text: JSON.stringify(result),
             },
           ],
           details: result,

package/src/tools/cluster-tool.ts

@@ -39,7 +39,7 @@ export function createClusterToolTool(): AnyAgentTool {
           content: [
             {
               type: "text" as const,
-              text: JSON.stringify(result, null, 2),
+              text: JSON.stringify(result),
             },
           ],
           details: result,

package/src/tools/cluster-write.ts

@@ -42,7 +42,7 @@ export function createClusterWriteTool(): AnyAgentTool {
           content: [
             {
               type: "text" as const,
-              text: JSON.stringify(result, null, 2),
+              text: JSON.stringify(result),
             },
           ],
           details: result,