clawmatrix 0.1.15 → 0.1.17

package/src/model-proxy.ts

@@ -9,12 +9,19 @@ import type {
   ModelStreamChunk,
 } from "./types.ts";
 import { debug } from "./debug.ts";
+import { readBody } from "./http-utils.ts";
 
 const MODEL_TIMEOUT = 120_000; // 2 minutes
 const MAX_STREAM_BUFFER = 1_048_576; // 1MB — guard against upstream not sending newlines
 
 type ResponseFormat = "chat" | "responses";
 
+interface ProxyResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string | ReadableStream;
+}
+
 interface PendingModelReq {
   resolve: (value: unknown) => void;
   reject: (error: Error) => void;
@@ -173,12 +180,12 @@ export class ModelProxy {
         debug("proxy", `${req.method} ${url.pathname} → ${p}`);
 
         if (p === "/chat/completions" && req.method === "POST") {
-          const body = await this.readBody(req);
+          const body = await readBody(req);
           const response = await this.handleChatCompletion(body, "openai-completions");
           debug("proxy", `response status=${response.status}`);
           this.sendResponse(res, response);
         } else if (p === "/responses" && req.method === "POST") {
-          const body = await this.readBody(req);
+          const body = await readBody(req);
           const response = await this.handleResponses(body);
           debug("proxy", `response status=${response.status}`);
           this.sendResponse(res, response);
@@ -215,18 +222,11 @@ export class ModelProxy {
       pending.reject(new Error("Shutting down"));
     }
     this.pending.clear();
+    this.streamText.clear();
   }
 
-  private readBody(req: import("node:http").IncomingMessage): Promise<string> {
-    return new Promise((resolve, reject) => {
-      const chunks: Buffer[] = [];
-      req.on("data", (chunk: Buffer) => chunks.push(chunk));
-      req.on("end", () => resolve(Buffer.concat(chunks).toString()));
-      req.on("error", reject);
-    });
-  }
 
-  private sendResponse(res: import("node:http").ServerResponse, response: { status: number; headers: Record<string, string>; body: string | ReadableStream }) {
+  private sendResponse(res: import("node:http").ServerResponse, response: ProxyResponse) {
     res.writeHead(response.status, response.headers);
     if (typeof response.body === "string") {
       res.end(response.body);
@@ -288,7 +288,7 @@ export class ModelProxy {
     return { nodeId, modelId, proxyModel, routeNodeId: route.nodeId };
   }
 
-  private async handleChatCompletion(rawBody: string, _api: string): Promise<{ status: number; headers: Record<string, string>; body: string | ReadableStream }> {
+  private async handleChatCompletion(rawBody: string, _api: string): Promise<ProxyResponse> {
     let body: { model: string; messages: unknown[]; stream?: boolean; temperature?: number; max_tokens?: number };
     try {
       body = JSON.parse(rawBody);
@@ -303,6 +303,8 @@ export class ModelProxy {
 
     const { modelId, proxyModel, routeNodeId } = resolved;
     const messages = body.messages;
+    debug("proxy", `messages count=${messages?.length ?? 0} roles=${(messages ?? []).map((m: unknown) => (m as Record<string, unknown>)?.role).join(",")}`);
+
     if (proxyModel?.description) {
       const first = messages[0] as { role?: string; content?: string } | undefined;
       if (first?.role === "system" && typeof first.content === "string") {
@@ -326,7 +328,7 @@ export class ModelProxy {
     }
   }
 
-  private async handleResponses(rawBody: string): Promise<{ status: number; headers: Record<string, string>; body: string | ReadableStream }> {
+  private async handleResponses(rawBody: string): Promise<ProxyResponse> {
     let body: { model: string; input: unknown; stream?: boolean; temperature?: number; max_output_tokens?: number; instructions?: string };
     try {
       body = JSON.parse(rawBody);
@@ -382,7 +384,7 @@ export class ModelProxy {
     targetNodeId: string,
     frame: ModelRequest,
     responseFormat: ResponseFormat,
-  ): { status: number; headers: Record<string, string>; body: ReadableStream } {
+  ): ProxyResponse & { body: ReadableStream } {
     const encoder = new TextEncoder();
     const model = frame.payload.model;
 
@@ -390,6 +392,7 @@ export class ModelProxy {
       start: (controller) => {
         const timer = setTimeout(() => {
           this.pending.delete(requestId);
+          this.streamText.delete(requestId);
           this.peerManager.router.markFailed(requestId);
           try {
             if (responseFormat === "responses") {
@@ -475,7 +478,7 @@ export class ModelProxy {
     targetNodeId: string,
     frame: ModelRequest,
     responseFormat: ResponseFormat,
-  ): Promise<{ status: number; headers: Record<string, string>; body: string }> {
+  ): Promise<ProxyResponse & { body: string }> {
     try {
       const result = await new Promise<ModelResponse["payload"]>(
         (resolve, reject) => {
@@ -569,7 +572,7 @@ export class ModelProxy {
     }
   }
 
-  private handleListModels(): { status: number; headers: Record<string, string>; body: string } {
+  private handleListModels(): ProxyResponse & { body: string } {
     // Build from proxyModels config (has full detail) and enrich with
     // connectivity info from the router so consumers know what's reachable.
     const reachable = new Set(

package/src/peer-manager.ts

@@ -27,6 +27,7 @@ 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;
@@ -48,12 +49,18 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       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,
     });
   }
 
@@ -251,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);
 
@@ -270,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,
@@ -285,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);
@@ -321,15 +350,32 @@ 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;
@@ -337,9 +383,13 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         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)
-            || (peer.directPeers?.length ?? 0) !== hadDirectPeers) {
+            || (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, DeviceInfo } 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;
@@ -17,6 +16,7 @@ export interface RouteEntry {
   latencyMs: number;
   directPeers: string[]; // nodeIds this node has direct connections to
   deviceInfo?: DeviceInfo;
+  toolProxy?: ToolProxyInfo;
 }
 
 export class Router {
@@ -25,38 +25,46 @@ export class Router {
   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[]; deviceInfo?: DeviceInfo },
+    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[]; deviceInfo?: DeviceInfo },
+    capabilities: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[]; deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo },
   ) {
     this.connections.set(nodeId, connection);
     this.routes.set(nodeId, {
@@ -70,6 +78,7 @@ export class Router {
       latencyMs: 0,
       directPeers: [],
       deviceInfo: capabilities.deviceInfo,
+      toolProxy: capabilities.toolProxy,
     });
   }
 
@@ -91,6 +100,7 @@ export class Router {
       latencyMs: 0,
       directPeers: peer.directPeers ?? [],
       deviceInfo: peer.deviceInfo,
+      toolProxy: peer.toolProxy,
     });
   }
 
@@ -107,7 +117,7 @@ export class Router {
 
   updatePeerCapabilities(
     nodeId: string,
-    capabilities: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[]; directPeers?: string[]; deviceInfo?: DeviceInfo },
+    capabilities: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[]; directPeers?: string[]; deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo },
   ) {
     const entry = this.routes.get(nodeId);
     if (entry) {
@@ -120,6 +130,7 @@ export class Router {
       if (capabilities.deviceInfo) {
         entry.deviceInfo = capabilities.deviceInfo;
       }
+      entry.toolProxy = capabilities.toolProxy;
       entry.lastSeen = Date.now();
     }
   }
@@ -236,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);
     }
   }
 
@@ -287,6 +319,7 @@ export class Router {
       tags: this.localTags,
       directPeers: myDirectPeers,
       deviceInfo: this.localDeviceInfo,
+      toolProxy: this.localToolProxy,
     });
     for (const entry of this.routes.values()) {
       peers.push({
@@ -297,6 +330,7 @@ export class Router {
         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 (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")',
+        },
+        source: {
+          type: "string",
+          description: 'Filter by source (e.g. "shortcuts")',
+        },
+        unconsumed: {
+          type: "boolean",
+          description: "Only unconsumed events (default true)",
+        },
+        since: {
+          type: "number",
+          description: "Events after this unix timestamp (ms)",
+        },
+        limit: {
+          type: "number",
+          description: "Max events to return (default 20)",
+        },
+        ids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Event IDs to 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) }],
+          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,16 +40,20 @@ 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: [
             {
               type: "text" as const,
-              text: JSON.stringify(result, null, 2),
+              text: JSON.stringify(result),
             },
           ],
           details: result,