clawmatrix 0.2.9 → 0.3.1

package/src/tools/cluster-diagnostic.ts

@@ -10,9 +10,10 @@ export function createClusterDiagnosticTool(): AnyAgentTool {
     label: "Cluster Diagnostic",
     description:
       "Diagnose or execute commands on a remote node's sentinel process. " +
-      "Works even when the remote OpenClaw gateway is down. " +
+      "Works even when the remote OpenClaw gateway is down (sentinel is a lightweight always-on process). " +
       "Use action 'status' to check if the remote gateway is alive, " +
-      "or 'exec' to run a shell command on the remote machine.",
+      "or 'exec' to run a shell command on the remote machine. " +
+      "Note: exec runs commands without restrictions — only use in trusted networks.",
     parameters: {
       type: "object",
       properties: {
@@ -88,6 +89,8 @@ export function createClusterDiagnosticTool(): AnyAgentTool {
           };
         }
 
+        // TODO(security): exec 允许任何已认证 peer 在远程 sentinel 执行任意命令，无 allowlist 或 capability check。
+        // 当前仅用于受信任网络。开放前需添加命令白名单或 per-peer 授权。
         if (action === "exec") {
           if (!command) {
             return {

package/src/tools/cluster-edit.ts

@@ -7,7 +7,8 @@ export function createClusterEditTool(): AnyAgentTool {
     label: "Cluster Edit",
     description:
       "Edit a file on a remote cluster node by replacing exact text. " +
-      "The oldText must match exactly (including whitespace).",
+      "IMPORTANT: Use cluster_read first to get exact file content — oldText must match precisely (including whitespace and indentation). " +
+      "For creating new files use cluster_write instead.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-events.ts

@@ -6,7 +6,9 @@ export function createClusterEventsTool(): AnyAgentTool {
     name: "cluster_events",
     label: "Cluster Events",
     description:
-      "Query and consume events from external sources (messages, calls, location changes).",
+      "Query and consume events from external sources (iOS Shortcuts, webhooks, etc.). " +
+      "Common types: message_received, location_change, battery_status. " +
+      "Events are persistent until consumed. Requires web.enabled in config.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-exec.ts

@@ -7,6 +7,8 @@ export function createClusterExecTool(): AnyAgentTool {
     label: "Cluster Exec",
     description:
       "Execute a shell command on a remote cluster node. " +
+      "Use for file/shell operations on remote machines. " +
+      "Returns {stdout, stderr, exitCode}. " +
       "Use nodeId or 'tags:<tag>' to specify the target.",
     parameters: {
       type: "object",

package/src/tools/cluster-handoff.ts

@@ -6,7 +6,9 @@ export function createClusterHandoffTool(): AnyAgentTool {
     name: "cluster_handoff",
     label: "Cluster Handoff",
     description:
-      "Hand off a task to another agent in the cluster and wait for the result. " +
+      "Hand off a complex task to another agent in the cluster and wait for the result. " +
+      "Use for multi-step tasks that require the remote agent's full capabilities. " +
+      "If the remote agent needs more info, response includes inputRequired=true — use cluster_handoff_reply to continue. " +
       "Use agent ID (e.g. 'coder') or tag query (e.g. 'tags:coding') as target.",
     parameters: {
       type: "object",

package/src/tools/cluster-peers.ts

@@ -6,7 +6,9 @@ export function createClusterPeersTool(): AnyAgentTool {
     name: "cluster_peers",
     label: "Cluster Peers",
     description:
-      "List all reachable peers in the cluster, their agents, models, tools, and connection status.",
+      "List all peers in the cluster with their agents, models, tools, tags, and connection status. " +
+      "Call this first to discover what's available before using other cluster tools. " +
+      "Status: direct (connected), relay (via another node), sentinel-only (gateway down, sentinel up), satellite (HTTP polling device), unreachable.",
     parameters: {
       type: "object",
       properties: {},

package/src/tools/cluster-read.ts

@@ -5,7 +5,10 @@ export function createClusterReadTool(): AnyAgentTool {
   return {
     name: "cluster_read",
     label: "Cluster Read",
-    description: "Read a file from a remote cluster node.",
+    description:
+      "Read a file from a remote cluster node. " +
+      "Returns {content} with the file text. " +
+      "Use nodeId or 'tags:<tag>' to specify the target.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-send.ts

@@ -6,7 +6,8 @@ export function createClusterSendTool(): AnyAgentTool {
     name: "cluster_send",
     label: "Cluster Send",
     description:
-      "Send a one-way message to a remote agent. Does not wait for a response.",
+      "Send a one-way notification to a remote agent. Fire-and-forget: does not wait for a response. " +
+      "Use cluster_handoff instead when you need the remote agent to process a task and return a result.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-terminal.ts

@@ -7,13 +7,10 @@ export function createClusterTerminalTool(): AnyAgentTool {
     label: "Cluster Terminal",
     description:
       "Interactive terminal (PTY) on a remote cluster node. " +
-      "Actions: " +
-      '"open" — open a terminal session on a remote node. ' +
-      '"input" — send input (keystrokes/commands) to a session. ' +
-      '"read" — read buffered output from a session. ' +
-      '"resize" — resize the terminal. ' +
-      '"list" — list active terminal sessions. ' +
-      '"close" — close a terminal session.',
+      "Workflow: open → input/read (repeat) → close. " +
+      'Actions: "open" (requires node), "input" (requires sessionId + data), "read" (requires sessionId), ' +
+      '"resize" (requires sessionId), "list" (no params), "close" (requires sessionId). ' +
+      "Prefer cluster_exec for one-shot commands; use this for interactive/stateful sessions.",
     parameters: {
       type: "object",
       properties: {

package/src/tools/cluster-tool.ts

@@ -7,8 +7,8 @@ export function createClusterToolInvokeTool(): AnyAgentTool {
     label: "Cluster Tool Invoke",
     description:
       "Invoke any tool on a remote cluster node by name. " +
-      "Use this for device-specific tools (e.g. screenshot, battery, location on mobile nodes). " +
-      "Use cluster_peers to discover available tools on each peer. " +
+      "Preferred for device-specific tools (screenshot, battery, location, clipboard, etc.). " +
+      "Run cluster_peers first to discover available tools, or use CLI: clawmatrix tools --describe <tool> for params. " +
       "Use nodeId or 'tags:<tag>' to specify the target.",
     parameters: {
       type: "object",

package/src/tools/cluster-transfer.ts

@@ -0,0 +1,91 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterTransferTool(): AnyAgentTool {
+  return {
+    name: "cluster_transfer",
+    label: "Cluster File Transfer",
+    description:
+      "Transfer a file between the local node and a remote cluster node. " +
+      "Supports large files (up to 100MB) with chunked transfer and SHA-256 integrity check. " +
+      "Specify source_node to pull from remote, or target_node to push to remote.",
+    parameters: {
+      type: "object",
+      properties: {
+        source_node: {
+          type: "string",
+          description: "Source nodeId (omit for local). Exactly one of source_node or target_node must be provided.",
+        },
+        source_path: {
+          type: "string",
+          description: "File path on the source node",
+        },
+        target_node: {
+          type: "string",
+          description: "Target nodeId (omit for local). Exactly one of source_node or target_node must be provided.",
+        },
+        target_path: {
+          type: "string",
+          description: "File path on the target node",
+        },
+      },
+      required: ["source_path", "target_path"],
+    },
+    async execute(_toolCallId, params) {
+      const { source_node, source_path, target_node, target_path } = params as {
+        source_node?: string;
+        source_path: string;
+        target_node?: string;
+        target_path: string;
+      };
+
+      // Validate: exactly one of source_node or target_node must be provided
+      if (source_node && target_node) {
+        return {
+          content: [{ type: "text" as const, text: "Error: Provide either source_node or target_node, not both." }],
+          details: { error: true },
+        };
+      }
+      if (!source_node && !target_node) {
+        return {
+          content: [{ type: "text" as const, text: "Error: Provide either source_node (to pull) or target_node (to push)." }],
+          details: { error: true },
+        };
+      }
+
+      try {
+        const runtime = getClusterRuntime();
+        const ftm = runtime.fileTransferManager;
+        if (!ftm) {
+          return {
+            content: [{ type: "text" as const, text: "Error: File transfer is not enabled on this node." }],
+            details: { error: true },
+          };
+        }
+
+        let result;
+        if (source_node) {
+          // Pull: remote → local
+          result = await ftm.pullFile(source_node, source_path, target_path);
+        } else {
+          // Push: local → remote
+          result = await ftm.pushFile(target_node!, source_path, target_path);
+        }
+
+        const text = result.success
+          ? `Transfer complete: ${result.bytesTransferred} bytes transferred.`
+          : `Transfer failed: ${result.error}`;
+
+        return {
+          content: [{ type: "text" as const, text }],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Transfer error: ${err instanceof Error ? err.message : String(err)}` }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-write.ts

@@ -5,7 +5,9 @@ export function createClusterWriteTool(): AnyAgentTool {
   return {
     name: "cluster_write",
     label: "Cluster Write",
-    description: "Write content to a file on a remote cluster node.",
+    description:
+      "Write content to a file on a remote cluster node (creates or overwrites). " +
+      "Use nodeId or 'tags:<tag>' to specify the target.",
     parameters: {
       type: "object",
       properties: {

package/src/types.ts

@@ -317,6 +317,68 @@ export interface ToolBatchResponse extends ClusterFrame {
   };
 }
 
+// ── File transfer ─────────────────────────────────────────────────
+export interface FileTransferInit extends ClusterFrame {
+  type: "file_transfer_init";
+  id: string;
+  payload: {
+    sessionId: string;
+    direction: "push" | "pull";
+    filePath: string;
+    targetPath: string;
+    fileSize: number;
+    totalChunks: number;
+    chunkSize: number;
+    checksum: string; // SHA-256 hex
+  };
+}
+
+export interface FileTransferAck extends ClusterFrame {
+  type: "file_transfer_ack";
+  id: string;
+  payload: {
+    sessionId: string;
+    accepted: boolean;
+    error?: string;
+    // Pull mode: responder includes file metadata
+    fileSize?: number;
+    totalChunks?: number;
+    checksum?: string;
+  };
+}
+
+export interface FileTransferChunk extends ClusterFrame {
+  type: "file_transfer_chunk";
+  id: string;
+  payload: {
+    sessionId: string;
+    chunkIndex: number;
+    data: string; // base64-encoded
+  };
+}
+
+export interface FileTransferChunkAck extends ClusterFrame {
+  type: "file_transfer_chunk_ack";
+  id: string;
+  payload: {
+    sessionId: string;
+    chunkIndex: number;
+    success: boolean;
+    error?: string;
+  };
+}
+
+export interface FileTransferComplete extends ClusterFrame {
+  type: "file_transfer_complete";
+  id: string;
+  payload: {
+    sessionId: string;
+    success: boolean;
+    error?: string;
+    bytesTransferred?: number;
+  };
+}
+
 // ── Device info ───────────────────────────────────────────────────
 export interface DeviceInfo {
   os: string; // e.g. "Darwin 24.6.0", "Linux 6.1.0"
@@ -358,10 +420,20 @@ export interface ModelInfo {
   compat?: ModelCompatInfo;
 }
 
+export interface ToolCatalogEntry {
+  name: string;
+  description: string;
+  usage?: string;
+  /** JSON Schema for the tool's input parameters (for LLM callers to construct invocations). */
+  inputSchema?: Record<string, unknown>;
+}
+
 export interface ToolProxyInfo {
   enabled: boolean;
   allow: string[];
   deny: string[];
+  /** Optional tool catalog with descriptions and usage hints for remote callers. */
+  catalog?: ToolCatalogEntry[];
 }
 
 export interface AcpAgentInfo {
@@ -419,6 +491,24 @@ export interface HealthSyncFrame extends ClusterFrame {
   };
 }
 
+export interface AvailabilityRequest extends ClusterFrame {
+  type: "availability_req";
+  id: string;
+  payload: {
+    range: "24h" | "7d" | "90d";
+  };
+}
+
+export interface AvailabilityResponse extends ClusterFrame {
+  type: "availability_res";
+  id: string;
+  payload: {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+  };
+}
+
 // ── Diagnostic (sentinel) ────────────────────────────────────────
 export interface DiagnosticExec extends ClusterFrame {
   type: "diagnostic_exec";
@@ -479,9 +569,10 @@ export interface AcpStreamChunk extends ClusterFrame {
   id: string;
   payload: {
     delta: string;
-    event?: string;         // "agent_message_chunk" | "tool_call" | etc.
+    event?: string;         // "agent_message_chunk" | "tool_call" | "plan" | "available_commands" | "config_options" | "usage" | "session_info" | etc.
     done: boolean;
     sessionId?: string;     // included for session watchers (multi-device sync)
+    data?: unknown;         // structured data for rich events (plan entries, slash commands, config options, usage stats)
   };
 }
 
@@ -497,6 +588,10 @@ export interface AcpTaskResponse extends ClusterFrame {
     acpSessionId?: string;  // ACP-level session ID for future resume
     stopReason?: string;    // ACP stop reason
     error?: string;
+    configOptions?: AcpConfigOption[];    // initial config options (model, thinking level, etc.)
+    slashCommands?: AcpSlashCommand[];    // available slash commands
+    availableModes?: AcpModeInfo[];       // available session modes
+    currentModeId?: string;               // current mode
   };
 }
 
@@ -525,6 +620,7 @@ export interface AcpSessionInfo {
   description?: string;     // first user message (for display in session list)
   updatedAt?: string;
   agent?: string;           // which ACP agent (claude, codex, etc.)
+  status?: "active" | "idle"; // active = in-memory session with daemon, idle = persisted on disk
 }
 
 export interface AcpListRequest extends ClusterFrame {
@@ -626,6 +722,86 @@ export interface AcpGetModesResponse extends ClusterFrame {
   };
 }
 
+// ── ACP config options ───────────────────────────────────────────
+
+export interface AcpConfigOption {
+  id: string;
+  name: string;
+  type: "select" | "boolean";
+  currentValue: string | boolean;
+  options?: Array<{ id: string; name: string; description?: string }>;
+  description?: string;
+  category?: string;        // "mode" | "model" | "thought_level" | custom
+}
+
+export interface AcpSetConfigRequest extends ClusterFrame {
+  type: "acp_set_config";
+  id: string;
+  payload: {
+    sessionId: string;
+    configId: string;
+    value: string | boolean;
+  };
+}
+
+export interface AcpSetConfigResponse extends ClusterFrame {
+  type: "acp_set_config_res";
+  id: string;
+  payload: {
+    success: boolean;
+    configOptions?: AcpConfigOption[];
+    error?: string;
+  };
+}
+
+// ── ACP subscribe / observe ──────────────────────────────────────
+
+export interface AcpSubscribeRequest extends ClusterFrame {
+  type: "acp_subscribe";
+  id: string;
+  payload: {
+    sessionId: string;      // ClawMatrix session ID to observe
+  };
+}
+
+export interface AcpSubscribeResponse extends ClusterFrame {
+  type: "acp_subscribe_res";
+  id: string;
+  payload: {
+    success: boolean;
+    history?: ChatHistoryMessage[];   // snapshot at subscribe time
+    error?: string;
+  };
+}
+
+export interface AcpUnsubscribeRequest extends ClusterFrame {
+  type: "acp_unsubscribe";
+  payload: {
+    sessionId: string;
+  };
+}
+
+/** Pushed to all peers when a session is created, its title changes, or it completes. */
+export interface AcpSessionNotify extends ClusterFrame {
+  type: "acp_session_notify";
+  payload: {
+    sessionId: string;
+    nodeId: string;
+    event: "created" | "updated" | "completed";
+    title?: string;
+    updatedAt?: string;
+    agent?: string;
+  };
+}
+
+// ── ACP slash commands ──────────────────────────────────────────
+
+export interface AcpSlashCommand {
+  name: string;
+  description: string;
+  input?: { hint?: string };
+}
+
 // ── Chat history ──────────────────────────────────────────────────
 
 export interface ChatHistoryMessage {
@@ -828,6 +1004,12 @@ export type AnyClusterFrame =
   | AcpSetModeResponse
   | AcpGetModesRequest
   | AcpGetModesResponse
+  | AcpSetConfigRequest
+  | AcpSetConfigResponse
+  | AcpSubscribeRequest
+  | AcpSubscribeResponse
+  | AcpUnsubscribeRequest
+  | AcpSessionNotify
   | ChatHistoryRequest
   | ChatHistoryResponse
   | PeerApprovalNotify
@@ -840,4 +1022,11 @@ export type AnyClusterFrame =
   | TerminalResize
   | TerminalCloseRequest
   | TerminalCloseResponse
-  | HealthSyncFrame;
+  | HealthSyncFrame
+  | AvailabilityRequest
+  | AvailabilityResponse
+  | FileTransferInit
+  | FileTransferAck
+  | FileTransferChunk
+  | FileTransferChunkAck
+  | FileTransferComplete;

package/src/web.ts

@@ -5,7 +5,6 @@ import type { ClawMatrixConfig } from "./config.ts";
 import type { SatelliteContext, IngestedEvent } from "./types.ts";
 import type { HealthTracker } from "./health-tracker.ts";
 import { timingSafeEqual } from "./auth.ts";
-import { renderDashboard } from "./web-ui.ts";
 import { readBody } from "./http-utils.ts";
 
 const COOKIE_NAME = "clawmatrix_token";
@@ -135,13 +134,6 @@ export class WebHandler {
       return true;
     }
 
-    // Serve dashboard HTML (auth checked client-side via API)
-    if (path === "/" && req.method === "GET") {
-      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-      res.end(renderDashboard(this.config.nodeId));
-      return true;
-    }
-
     // All /api/* routes require auth (async)
     if (path.startsWith("/api/")) {
       this.handleAuthenticatedRoute(req, res, path);
@@ -224,7 +216,7 @@ export class WebHandler {
   private async checkAuth(req: IncomingMessage): Promise<boolean> {
     // Check Authorization header
     const authHeader = req.headers.authorization;
-    if (authHeader?.startsWith("Bearer ") && await timingSafeEqual(authHeader.slice(7), this.token)) {
+    if (authHeader?.startsWith("Bearer ") && timingSafeEqual(authHeader.slice(7), this.token)) {
       return true;
     }
 
@@ -658,7 +650,7 @@ export class WebHandler {
         ssid: ctx.ssid || undefined,
         ip: ctx.ip || undefined,
         router: ctx.router || undefined,
-        cellular: !ctx.ssid,
+        cellular: typeof ctx.cellular === "boolean" ? ctx.cellular : !ctx.ssid,
         country: ctx.country || undefined,
         tools: Array.isArray(ctx.tools) ? ctx.tools : undefined,
         ts: Date.now(),