clawmatrix 0.1.14 → 0.1.16

package/src/peer-manager.ts

@@ -5,9 +5,11 @@ import type { ClawMatrixConfig, PeerConfig } from "./config.ts";
 import { Connection } from "./connection.ts";
 import type { WsTransport } from "./connection.ts";
 import { Router } from "./router.ts";
+import { collectDeviceInfo } from "./device-info.ts";
 import type {
   AnyClusterFrame,
   ClusterFrame,
+  DeviceInfo,
   NodeCapabilities,
   PeerInfo,
   PeerSync,
@@ -24,6 +26,8 @@ export interface PeerManagerEvents {
 
 export class PeerManager extends EventEmitter<PeerManagerEvents> {
   readonly router: Router;
+  readonly localDeviceInfo: DeviceInfo;
+  satelliteContexts: import("./types.ts").SatelliteContext[] = [];
   private config: ClawMatrixConfig;
   private localCapabilities: NodeCapabilities;
   private httpServer: Server | null = null;
@@ -35,19 +39,28 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   private inboundConnections = new Map<WsWebSocket, Connection>();
   private gossipDebounceTimer: ReturnType<typeof setTimeout> | null = null;
 
-  constructor(config: ClawMatrixConfig) {
+  constructor(config: ClawMatrixConfig, openclawVersion?: string) {
     super();
     this.config = config;
+    this.localDeviceInfo = collectDeviceInfo(openclawVersion);
     this.localCapabilities = {
       nodeId: config.nodeId,
       agents: config.agents,
       models: config.models,
       tags: config.tags,
+      deviceInfo: this.localDeviceInfo,
+      toolProxy: config.toolProxy ? {
+        enabled: config.toolProxy.enabled,
+        allow: config.toolProxy.allow,
+        deny: config.toolProxy.deny,
+      } : undefined,
     };
     this.router = new Router(config.nodeId, {
       agents: config.agents,
       models: config.models,
       tags: config.tags,
+      deviceInfo: this.localDeviceInfo,
+      toolProxy: this.localCapabilities.toolProxy,
     });
   }
 
@@ -230,6 +243,7 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     this.router.addDirectPeer(nodeId, conn, caps);
 
     conn.on("message", (frame) => this.onFrame(frame, conn));
+    conn.on("latency", (ms) => this.router.updateLatency(nodeId, ms));
     conn.on("close", () => this.onPeerDisconnected(conn));
 
     this.sendPeerSync(conn);
@@ -244,6 +258,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         agents: caps.agents,
         models: caps.models,
         tags: caps.tags,
+        deviceInfo: caps.deviceInfo,
+        toolProxy: caps.toolProxy,
       },
     } as AnyClusterFrame);
 
@@ -263,6 +279,13 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
     this.router.removePeer(nodeId);
 
+    // Remove satellite contexts that were only reachable via this peer
+    this.satelliteContexts = this.satelliteContexts.filter(s => {
+      // Keep satellites that are not associated with the disconnected peer
+      // (satellite nodeIds typically differ from mesh peer nodeIds)
+      return s.nodeId !== nodeId;
+    });
+
     this.router.broadcast({
       type: "peer_leave",
       from: this.config.nodeId,
@@ -278,9 +301,22 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     // Validate from field: must be the direct peer or a known node (relayed)
     if (frame.from && frame.from !== from.remoteNodeId && !this.router.getRoute(frame.from)) return;
 
-    // Skip dedup for streaming frame types — they share one id across many chunks
-    const isStreamFrame = frame.type === "model_stream" || frame.type === "handoff_stream";
-    if (frame.id && !isStreamFrame && this.router.isDuplicate(frame.id)) return;
+    // Skip dedup for streaming and response frame types.
+    // Stream frames share one id across many chunks.
+    // Response frames (model_res, tool_res, handoff_res, etc.) share the same id
+    // as their request — without this exemption, a relay node that forwarded
+    // the request would mark the id as seen and then drop the returning response.
+    // Skip dedup for streaming chunks (same id across many chunks) and response
+    // frames (share id with their request — relay would otherwise drop the reply).
+    // handoff_input, handoff_cancel, and handoff_status reuse the original handoff_req id,
+    // so relay nodes that already forwarded the request would drop them as duplicates.
+    const skipDedup = frame.type === "model_stream" || frame.type === "handoff_stream"
+      || frame.type === "model_res" || frame.type === "tool_res"
+      || frame.type === "handoff_res" || frame.type === "handoff_status_res"
+      || frame.type === "handoff_input_required"
+      || frame.type === "handoff_input" || frame.type === "handoff_cancel"
+      || frame.type === "handoff_status";
+    if (frame.id && !skipDedup && this.router.isDuplicate(frame.id)) return;
 
     if (frame.type === "peer_sync") {
       this.handlePeerSync(frame as PeerSync, from);
@@ -314,23 +350,46 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
   private sendPeerSync(conn: Connection) {
     const peers = this.router.buildPeerSyncPayload();
+    const payload: Record<string, unknown> = { peers };
+    if (this.satelliteContexts.length > 0) {
+      payload.satellites = this.satelliteContexts;
+    }
     conn.send({
       type: "peer_sync",
       from: this.config.nodeId,
       timestamp: Date.now(),
-      payload: { peers },
+      payload,
     } as AnyClusterFrame);
   }
 
   private handlePeerSync(frame: PeerSync, from: Connection) {
+    // Merge satellite contexts from relay node (keep newest per nodeId)
+    if (frame.payload.satellites) {
+      const byNodeId = new Map<string, import("./types.ts").SatelliteContext>();
+      for (const s of this.satelliteContexts) byNodeId.set(s.nodeId, s);
+      for (const s of frame.payload.satellites) {
+        const existing = byNodeId.get(s.nodeId);
+        if (!existing || s.ts > existing.ts) {
+          byNodeId.set(s.nodeId, s);
+        }
+      }
+      this.satelliteContexts = [...byNodeId.values()];
+    }
+
     let changed = false;
     for (const peer of frame.payload.peers) {
       if (peer.nodeId === this.config.nodeId) continue;
       if (peer.nodeId === from.remoteNodeId) {
         const prev = this.router.getRoute(peer.nodeId);
         const hadAgents = prev?.agents.length ?? 0;
+        const hadDirectPeers = prev?.directPeers.length ?? 0;
+        const hadToolProxy = JSON.stringify(prev?.toolProxy);
+        const hadDeviceInfo = prev?.deviceInfo?.hostname;
         this.router.updatePeerCapabilities(peer.nodeId, peer);
-        if (peer.agents.length !== hadAgents || peer.models.length !== (prev?.models.length ?? 0)) {
+        if (peer.agents.length !== hadAgents || peer.models.length !== (prev?.models.length ?? 0)
+            || (peer.directPeers?.length ?? 0) !== hadDirectPeers
+            || JSON.stringify(peer.toolProxy) !== hadToolProxy
+            || peer.deviceInfo?.hostname !== hadDeviceInfo) {
           changed = true;
         }
       } else {

package/src/router.ts

@@ -1,10 +1,9 @@
-import type { ClusterFrame, AnyClusterFrame, PeerInfo, AgentInfo, ModelInfo } from "./types.ts";
+import type { ClusterFrame, AnyClusterFrame, PeerInfo, AgentInfo, ModelInfo, DeviceInfo, ToolProxyInfo } from "./types.ts";
 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
+const ROTATE_INTERVAL = 60_000; // rotate dedup maps every 60s
 
 export interface RouteEntry {
   nodeId: string;
@@ -15,6 +14,9 @@ export interface RouteEntry {
   reachableVia: string | null; // relay nodeId, null = direct
   lastSeen: number;
   latencyMs: number;
+  directPeers: string[]; // nodeIds this node has direct connections to
+  deviceInfo?: DeviceInfo;
+  toolProxy?: ToolProxyInfo;
 }
 
 export class Router {
@@ -22,37 +24,47 @@ export class Router {
   private localAgents: AgentInfo[];
   private localModels: ModelInfo[];
   private localTags: string[];
+  private localDeviceInfo?: DeviceInfo;
+  private localToolProxy?: ToolProxyInfo;
   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;
+  /** Double-map dedup: current window + previous window. Rotated periodically. */
+  private seenCurrent = new Map<string, true>();
+  private seenPrevious = new Map<string, true>();
+  private rotateTimer: ReturnType<typeof setInterval> | null = null;
+  /** Failed request IDs with expiry timestamps. Separate from dedup to support longer TTLs. */
+  private failedRequests = new Map<string, number>(); // requestId → expiresAt
 
   constructor(
     nodeId: string,
-    localCapabilities?: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[] },
+    localCapabilities?: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[]; deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo },
   ) {
     this.nodeId = nodeId;
     this.localAgents = localCapabilities?.agents ?? [];
     this.localModels = localCapabilities?.models ?? [];
     this.localTags = localCapabilities?.tags ?? [];
+    this.localDeviceInfo = localCapabilities?.deviceInfo;
+    this.localToolProxy = localCapabilities?.toolProxy;
 
-    this.pruneTimer = setInterval(() => this.pruneSeenFrames(true), PRUNE_INTERVAL);
+    this.rotateTimer = setInterval(() => this.rotateSeenFrames(), ROTATE_INTERVAL);
   }
 
   /** Stop periodic cleanup. Call on shutdown. */
   destroy() {
-    if (this.pruneTimer) {
-      clearInterval(this.pruneTimer);
-      this.pruneTimer = null;
+    if (this.rotateTimer) {
+      clearInterval(this.rotateTimer);
+      this.rotateTimer = null;
     }
-    this.seenFrames.clear();
+    this.seenCurrent.clear();
+    this.seenPrevious.clear();
+    this.failedRequests.clear();
   }
 
   // ── Route table management ─────────────────────────────────────
   addDirectPeer(
     nodeId: string,
     connection: Connection,
-    capabilities: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[] },
+    capabilities: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[]; deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo },
   ) {
     this.connections.set(nodeId, connection);
     this.routes.set(nodeId, {
@@ -64,6 +76,9 @@ export class Router {
       reachableVia: null,
       lastSeen: Date.now(),
       latencyMs: 0,
+      directPeers: [],
+      deviceInfo: capabilities.deviceInfo,
+      toolProxy: capabilities.toolProxy,
     });
   }
 
@@ -83,6 +98,9 @@ export class Router {
       reachableVia: viaNodeId,
       lastSeen: Date.now(),
       latencyMs: 0,
+      directPeers: peer.directPeers ?? [],
+      deviceInfo: peer.deviceInfo,
+      toolProxy: peer.toolProxy,
     });
   }
 
@@ -99,17 +117,31 @@ export class Router {
 
   updatePeerCapabilities(
     nodeId: string,
-    capabilities: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[] },
+    capabilities: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[]; directPeers?: string[]; deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo },
   ) {
     const entry = this.routes.get(nodeId);
     if (entry) {
       entry.agents = capabilities.agents;
       entry.models = capabilities.models;
       entry.tags = capabilities.tags;
+      if (capabilities.directPeers) {
+        entry.directPeers = capabilities.directPeers;
+      }
+      if (capabilities.deviceInfo) {
+        entry.deviceInfo = capabilities.deviceInfo;
+      }
+      entry.toolProxy = capabilities.toolProxy;
       entry.lastSeen = Date.now();
     }
   }
 
+  updateLatency(nodeId: string, latencyMs: number) {
+    const entry = this.routes.get(nodeId);
+    if (entry) {
+      entry.latencyMs = latencyMs;
+    }
+  }
+
   // ── Routing ────────────────────────────────────────────────────
   getRoute(nodeId: string): RouteEntry | undefined {
     return this.routes.get(nodeId);
@@ -152,24 +184,6 @@ export class Router {
     return candidates[0];
   }
 
-  /** Find node that has a specific model. */
-  resolveModel(modelId: string): RouteEntry | undefined {
-    let candidates: RouteEntry[] = [];
-    for (const entry of this.routes.values()) {
-      if (entry.models.some((m) => m.id === modelId)) {
-        candidates.push(entry);
-      }
-    }
-    if (candidates.length === 0) return undefined;
-
-    candidates.sort((a, b) => {
-      const aDirect = a.connection ? 0 : 1;
-      const bDirect = b.connection ? 0 : 1;
-      if (aDirect !== bDirect) return aDirect - bDirect;
-      return a.latencyMs - b.latencyMs;
-    });
-    return candidates[0];
-  }
 
   /** Resolve a node target (nodeId or "tags:<tag>"). */
   resolveNode(target: string): RouteEntry | undefined {
@@ -233,33 +247,54 @@ export class Router {
     return relayed;
   }
 
-  // ── Deduplication ──────────────────────────────────────────────
-  /** Returns true if the frame has been seen before (duplicate). */
+  // ── Deduplication (double-map rotation) ────────────────────────
+  /**
+   * Returns true if the frame has been seen before (duplicate).
+   * Uses a double-map strategy: entries live in `seenCurrent` and are
+   * promoted from `seenPrevious` on access. Every ROTATE_INTERVAL the
+   * previous map is discarded and current becomes previous — O(1) cleanup.
+   */
   isDuplicate(frameId: string): boolean {
     if (!frameId) return false;
-    if (this.seenFrames.has(frameId)) return true;
+    if (this.seenCurrent.has(frameId)) return true;
+    if (this.seenPrevious.has(frameId)) {
+      // Promote to current so it survives the next rotation
+      this.seenCurrent.set(frameId, true);
+      return true;
+    }
 
-    this.seenFrames.set(frameId, Date.now());
-    this.pruneSeenFrames();
+    this.seenCurrent.set(frameId, true);
+    // Safety valve: if current map grows too large, force a rotation
+    if (this.seenCurrent.size > MAX_SEEN_FRAMES) {
+      this.rotateSeenFrames();
+    }
     return false;
   }
 
-  /** Mark a request ID as failed so late responses are ignored. */
-  markFailed(requestId: string) {
-    this.seenFrames.set(`failed:${requestId}`, Date.now());
+  /** Mark a request ID as failed so late responses are ignored.
+   *  TTL defaults to 15 minutes — long enough for handoff timeouts. */
+  markFailed(requestId: string, ttlMs = 900_000) {
+    this.failedRequests.set(requestId, Date.now() + ttlMs);
   }
 
   isFailed(requestId: string): boolean {
-    return this.seenFrames.has(`failed:${requestId}`);
+    const expiresAt = this.failedRequests.get(requestId);
+    if (expiresAt === undefined) return false;
+    if (Date.now() > expiresAt) {
+      this.failedRequests.delete(requestId);
+      return false;
+    }
+    return true;
   }
 
-  private pruneSeenFrames(force = false) {
-    if (!force && this.seenFrames.size <= MAX_SEEN_FRAMES) return;
+  private rotateSeenFrames() {
+    this.seenPrevious = this.seenCurrent;
+    this.seenCurrent = new Map();
+
+    // Prune expired failed requests
     const now = Date.now();
-    for (const [id, ts] of this.seenFrames) {
-      if (now - ts > SEEN_FRAME_TTL) {
-        this.seenFrames.delete(id);
-      }
+    for (const [id, expiresAt] of this.failedRequests) {
+      if (now > expiresAt) this.failedRequests.delete(id);
     }
   }
 
@@ -275,12 +310,16 @@ export class Router {
   /** Build PeerInfo list for peer_sync. */
   buildPeerSyncPayload(): PeerInfo[] {
     const peers: PeerInfo[] = [];
-    // Include ourselves
+    // Include ourselves with our direct peer list
+    const myDirectPeers = [...this.connections.keys()];
     peers.push({
       nodeId: this.nodeId,
       agents: this.localAgents,
       models: this.localModels,
       tags: this.localTags,
+      directPeers: myDirectPeers,
+      deviceInfo: this.localDeviceInfo,
+      toolProxy: this.localToolProxy,
     });
     for (const entry of this.routes.values()) {
       peers.push({
@@ -289,6 +328,9 @@ export class Router {
         models: entry.models,
         tags: entry.tags,
         reachableVia: entry.reachableVia ?? undefined,
+        directPeers: entry.directPeers.length > 0 ? entry.directPeers : undefined,
+        deviceInfo: entry.deviceInfo,
+        toolProxy: entry.toolProxy,
       });
     }
     return peers;

package/src/tool-proxy.ts

@@ -16,11 +16,18 @@ export interface GatewayInfo {
   authHeader?: string;
 }
 
+/** Interface for satellite tool routing (implemented by WebHandler). */
+export interface SatelliteToolHandler {
+  isSatelliteNode(nodeId: string): boolean;
+  queueToolForSatellite(nodeId: string, id: string, tool: string, params: Record<string, unknown>, timeout?: number): Promise<Record<string, unknown>>;
+}
+
 export class ToolProxy {
   private config: ClawMatrixConfig;
   private peerManager: PeerManager;
   private pending = new Map<string, PendingToolReq>();
   private gatewayInfo: GatewayInfo;
+  private satelliteHandler: SatelliteToolHandler | null = null;
 
   constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo) {
     this.config = config;
@@ -28,6 +35,11 @@ export class ToolProxy {
     this.gatewayInfo = gatewayInfo;
   }
 
+  /** Set the satellite tool handler (called by ClusterRuntime after WebHandler is created). */
+  setSatelliteHandler(handler: SatelliteToolHandler) {
+    this.satelliteHandler = handler;
+  }
+
   // ── Outbound: request remote execution ─────────────────────────
   async invoke(
     node: string,
@@ -45,7 +57,15 @@ export class ToolProxy {
     timeout?: number,
   ): Promise<Record<string, unknown>> {
     const route = this.peerManager.router.resolveNode(node);
-    if (!route) throw new Error(`Node "${node}" not reachable`);
+
+    // If no WS route, try satellite fallback
+    if (!route) {
+      if (this.satelliteHandler?.isSatelliteNode(node)) {
+        const id = crypto.randomUUID();
+        return this.satelliteHandler.queueToolForSatellite(node, id, tool, params, timeout);
+      }
+      throw new Error(`Node "${node}" not reachable`);
+    }
 
     const id = crypto.randomUUID();
     const frame: ToolProxyRequest = {
@@ -114,17 +134,12 @@ export class ToolProxy {
     }
 
     try {
-      console.log(`Received tool request for: ${payload.tool}`);
-      console.log(`Is local tool? ${isLocalTool(payload.tool)}`);
-      
       const result = isLocalTool(payload.tool)
         ? await executeLocally(payload.tool, payload.params)
         : await this.executeViaGateway(payload.tool, payload.params);
-        
-      console.log(`Tool execution result: ${JSON.stringify(result)}`);
+
       this.sendResponse(id, from, { success: true, result });
     } catch (err) {
-      console.error(`Tool execution error: ${err}`);
       this.sendResponse(id, from, {
         success: false,
         error: err instanceof Error ? err.message : String(err),

package/src/tools/cluster-events.ts

@@ -0,0 +1,119 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterEventsTool(): AnyAgentTool {
+  return {
+    name: "cluster_events",
+    label: "Cluster Events",
+    description:
+      "Query and consume events from external sources (messages, calls, location changes).",
+    parameters: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["query", "consume"],
+          description: '"query" to list events, "consume" to mark events as processed',
+        },
+        type: {
+          type: "string",
+          description: 'Filter by event type (e.g. "message_received", "call_missed"). Only for action=query.',
+        },
+        source: {
+          type: "string",
+          description: 'Filter by source (e.g. "shortcuts", "iphone"). Only for action=query.',
+        },
+        unconsumed: {
+          type: "boolean",
+          description: "Only return unconsumed events. Default true. Only for action=query.",
+        },
+        since: {
+          type: "number",
+          description: "Only return events after this unix timestamp (ms). Only for action=query.",
+        },
+        limit: {
+          type: "number",
+          description: "Max events to return. Default 20. Only for action=query.",
+        },
+        ids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Event IDs to mark as consumed. Required for action=consume.",
+        },
+      },
+      required: ["action"],
+    },
+    async execute(_toolCallId, params) {
+      const { action, type, source, unconsumed, since, limit, ids } = params as {
+        action: "query" | "consume";
+        type?: string;
+        source?: string;
+        unconsumed?: boolean;
+        since?: number;
+        limit?: number;
+        ids?: string[];
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+        const webHandler = runtime.webHandler;
+        if (!webHandler) {
+          return {
+            content: [{ type: "text" as const, text: "Event ingestion requires web dashboard to be enabled (web.enabled = true)" }],
+            details: { error: true },
+          };
+        }
+
+        if (action === "consume") {
+          if (!ids || ids.length === 0) {
+            return {
+              content: [{ type: "text" as const, text: "Error: ids array required for consume action" }],
+              details: { error: true },
+            };
+          }
+          const consumed = webHandler.consumeEvents(ids);
+          return {
+            content: [{ type: "text" as const, text: `Consumed ${consumed} event(s)` }],
+            details: { consumed },
+          };
+        }
+
+        // action === "query"
+        const events = webHandler.queryEvents({
+          type,
+          source,
+          since,
+          unconsumed: unconsumed !== false, // default true
+          limit: limit ?? 20,
+        });
+
+        if (events.length === 0) {
+          return {
+            content: [{ type: "text" as const, text: "No matching events found." }],
+            details: { events: [] },
+          };
+        }
+
+        const summary = events.map(e => ({
+          id: e.id,
+          type: e.type,
+          source: e.source,
+          ts: e.ts,
+          time: new Date(e.ts).toISOString(),
+          consumed: e.consumed,
+          data: e.data,
+        }));
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(summary, null, 2) }],
+          details: { events: summary },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-exec.ts

@@ -40,10 +40,14 @@ export function createClusterExecTool(): AnyAgentTool {
 
       try {
         const runtime = getClusterRuntime();
+        // Network timeout must cover the exec timeout plus overhead
+        const execTimeoutSec = timeout ?? 1800;
+        const networkTimeout = (execTimeoutSec + 30) * 1000;
         const result = await runtime.toolProxy.invoke(
           node,
           "exec",
           { command, workdir, timeout },
+          networkTimeout,
         );
         return {
           content: [

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

@@ -0,0 +1,77 @@
+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: `Remote agent needs more information.\n\nHandoff ID: ${result.handoffId}\nQuestion: ${result.result}\n\nUse cluster_handoff_reply again to respond.`,
+              },
+            ],
+            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 },
+                null,
+                2,
+              ),
+            },
+          ],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Handoff reply error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}