clawmatrix 0.1.15 → 0.1.17

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

@@ -0,0 +1,73 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterHandoffReplyTool(): AnyAgentTool {
+  return {
+    name: "cluster_handoff_reply",
+    label: "Cluster Handoff Reply",
+    description:
+      "Reply to a remote agent that requested more input during a handoff. " +
+      "Use the handoff_id returned by cluster_handoff.",
+    parameters: {
+      type: "object",
+      properties: {
+        handoff_id: {
+          type: "string",
+          description: "The handoff ID from cluster_handoff's response",
+        },
+        message: {
+          type: "string",
+          description: "Your reply to the remote agent's question",
+        },
+      },
+      required: ["handoff_id", "message"],
+    },
+    async execute(_toolCallId, params) {
+      const { handoff_id, message } = params as { handoff_id: string; message: string };
+
+      try {
+        const runtime = getClusterRuntime();
+        const result = await runtime.handoffManager.sendHandoffInput(handoff_id, message);
+
+        if (result.inputRequired) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Input required (handoff_id:${result.handoffId}): ${result.result}`,
+              },
+            ],
+            details: result,
+          };
+        }
+
+        if (!result.success) {
+          return {
+            content: [{ type: "text" as const, text: `Handoff failed: ${result.error}` }],
+            details: result,
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ nodeId: result.nodeId, agent: result.agent, result: result.result }),
+            },
+          ],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Handoff reply error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-handoff.ts

@@ -37,6 +37,18 @@ export function createClusterHandoffTool(): AnyAgentTool {
         const runtime = getClusterRuntime();
         const result = await runtime.handoffManager.handoff(target, task, context);
 
+        if (result.inputRequired) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Input required (handoff_id:${result.handoffId}): ${result.result}`,
+              },
+            ],
+            details: result,
+          };
+        }
+
         if (!result.success) {
           return {
             content: [
@@ -53,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

@@ -6,7 +6,7 @@ export function createClusterPeersTool(): AnyAgentTool {
     name: "cluster_peers",
     label: "Cluster Peers",
     description:
-      "List all reachable peers in the cluster, their agents, available models, and connection status.",
+      "List all reachable peers in the cluster, their agents, models, tools, and connection status.",
     parameters: {
       type: "object",
       properties: {},
@@ -21,20 +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 (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,
+            tools: sat.tools ?? [],
+            status: "satellite",
+          } 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-send.ts

@@ -6,9 +6,7 @@ export function createClusterSendTool(): AnyAgentTool {
     name: "cluster_send",
     label: "Cluster Send",
     description:
-      "Send a one-way message to another agent in the cluster. " +
-      "The message is injected into the target agent's session as an inbound message. " +
-      "Does not wait for a response.",
+      "Send a one-way message to a remote agent. Does not wait for a response.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-tool.ts

@@ -6,10 +6,7 @@ export function createClusterToolTool(): AnyAgentTool {
     name: "cluster_tool",
     label: "Cluster Tool",
     description:
-      "Invoke any OpenClaw tool on a remote cluster node. " +
-      "Supports all tools available on the remote node (exec, read, write, edit, " +
-      "web_search, web_fetch, browser, process, etc.). " +
-      "Use nodeId or 'tags:<tag>' to specify the target.",
+      "Invoke any OpenClaw tool on a remote cluster node. Use nodeId or 'tags:<tag>' to specify the target.",
     parameters: {
       type: "object",
       properties: {
@@ -19,7 +16,7 @@ export function createClusterToolTool(): AnyAgentTool {
         },
         tool: {
           type: "string",
-          description: "Tool name to invoke (e.g. exec, read, write, edit, web_search, web_fetch, browser, process)",
+          description: "Tool name to invoke on the remote node",
         },
         args: {
           type: "object",
@@ -42,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,

package/src/types.ts

@@ -24,6 +24,7 @@ export interface AuthRequest extends ClusterFrame {
     models?: ModelInfo[];
     tags?: string[];
     deviceInfo?: DeviceInfo;
+    toolProxy?: ToolProxyInfo;
   };
 }
 
@@ -35,6 +36,7 @@ export interface AuthOk extends ClusterFrame {
     models: ModelInfo[];
     tags: string[];
     deviceInfo?: DeviceInfo;
+    toolProxy?: ToolProxyInfo;
   };
 }
 
@@ -44,10 +46,27 @@ export interface AuthFail extends ClusterFrame {
 }
 
 // ── Peer discovery ─────────────────────────────────────────────────
+export interface SatelliteContext {
+  nodeId: string;
+  ssid?: string;
+  ip?: string;
+  router?: string;
+  cellular: boolean;
+  country?: string;
+  tools?: string[];
+  ts: number;
+  // Extended context
+  battery?: number; // 0-100
+  charging?: boolean;
+  platform?: string; // "ios" | "macos"
+  location?: string; // user-defined location name from WiFi mapping
+}
+
 export interface PeerSync extends ClusterFrame {
   type: "peer_sync";
   payload: {
     peers: PeerInfo[];
+    satellites?: SatelliteContext[];
   };
 }
 
@@ -113,6 +132,14 @@ export interface ModelStreamChunk extends ClusterFrame {
 }
 
 // ── Handoff ────────────────────────────────────────────────────────
+export type HandoffStatus = "working" | "input_required" | "completed" | "failed" | "canceled";
+
+export interface Artifact {
+  name: string;
+  mimeType: string;
+  data: string; // text content or base64-encoded binary
+}
+
 export interface HandoffRequest extends ClusterFrame {
   type: "handoff_req";
   id: string;
@@ -129,6 +156,7 @@ export interface HandoffStreamChunk extends ClusterFrame {
   payload: {
     delta: string;
     done: boolean;
+    artifacts?: Artifact[];
   };
 }
 
@@ -141,6 +169,48 @@ export interface HandoffResponse extends ClusterFrame {
     agent?: string;
     result?: string;
     error?: string;
+    artifacts?: Artifact[];
+    inputRequired?: boolean;
+    handoffId?: string;
+  };
+}
+
+export interface HandoffCancel extends ClusterFrame {
+  type: "handoff_cancel";
+  id: string;
+  payload?: unknown;
+}
+
+export interface HandoffStatusQuery extends ClusterFrame {
+  type: "handoff_status";
+  id: string;
+  payload?: unknown;
+}
+
+export interface HandoffStatusResponse extends ClusterFrame {
+  type: "handoff_status_res";
+  id: string;
+  payload: {
+    status: HandoffStatus;
+    nodeId: string;
+    agent: string;
+    elapsedMs: number;
+  };
+}
+
+export interface HandoffInputRequired extends ClusterFrame {
+  type: "handoff_input_required";
+  id: string;
+  payload: {
+    message: string;
+  };
+}
+
+export interface HandoffInput extends ClusterFrame {
+  type: "handoff_input";
+  id: string;
+  payload: {
+    message: string;
   };
 }
 
@@ -213,6 +283,12 @@ export interface ModelInfo {
   compat?: ModelCompatInfo;
 }
 
+export interface ToolProxyInfo {
+  enabled: boolean;
+  allow: string[];
+  deny: string[];
+}
+
 export interface PeerInfo {
   nodeId: string;
   agents: AgentInfo[];
@@ -221,6 +297,7 @@ export interface PeerInfo {
   reachableVia?: string; // nodeId of the relay node
   directPeers?: string[]; // nodeIds this node has direct connections to
   deviceInfo?: DeviceInfo; // system/hardware info
+  toolProxy?: ToolProxyInfo;
 }
 
 export interface NodeCapabilities {
@@ -229,6 +306,17 @@ export interface NodeCapabilities {
   models: ModelInfo[];
   tags: string[];
   deviceInfo?: DeviceInfo;
+  toolProxy?: ToolProxyInfo;
+}
+
+// ── Ingested events (from Shortcuts automations, etc.) ────────────
+export interface IngestedEvent {
+  id: string;
+  source: string;      // e.g. "shortcuts", "iphone-14", "surge"
+  type: string;        // e.g. "message_received", "call_missed", "location_changed"
+  data: Record<string, unknown>;
+  ts: number;          // ingestion timestamp
+  consumed: boolean;   // whether an agent has consumed this event
 }
 
 // ── Union of all frame types ───────────────────────────────────────
@@ -248,6 +336,11 @@ export type AnyClusterFrame =
   | HandoffRequest
   | HandoffStreamChunk
   | HandoffResponse
+  | HandoffCancel
+  | HandoffStatusQuery
+  | HandoffStatusResponse
   | SendMessage
+  | HandoffInputRequired
+  | HandoffInput
   | ToolProxyRequest
   | ToolProxyResponse;