clawmatrix 0.2.11 → 0.4.0

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-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

@@ -420,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 {
@@ -559,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)
   };
 }
 
@@ -577,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
   };
 }
 
@@ -605,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?: "busy" | "active" | "idle"; // busy = currently executing a prompt, active = daemon alive, idle = on disk only
 }
 
 export interface AcpListRequest extends ClusterFrame {
@@ -706,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 {
@@ -908,6 +1004,12 @@ export type AnyClusterFrame =
   | AcpSetModeResponse
   | AcpGetModesRequest
   | AcpGetModesResponse
+  | AcpSetConfigRequest
+  | AcpSetConfigResponse
+  | AcpSubscribeRequest
+  | AcpSubscribeResponse
+  | AcpUnsubscribeRequest
+  | AcpSessionNotify
   | ChatHistoryRequest
   | ChatHistoryResponse
   | PeerApprovalNotify

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(),

package/src/cli.ts

@@ -1,243 +0,0 @@
-import type { Command } from "commander";
-import { spawnProcess } from "./compat.ts";
-
-async function callGateway(method: string, params?: Record<string, unknown>): Promise<unknown> {
-  const args = ["openclaw", "gateway", "call", method, "--json"];
-  if (params) {
-    args.push("--params", JSON.stringify(params));
-  }
-  const proc = spawnProcess(args, {
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-
-  const stdoutChunks: Uint8Array[] = [];
-  const stderrChunks: Uint8Array[] = [];
-
-  const readStream = async (stream: ReadableStream | null, target: Uint8Array[]) => {
-    if (!stream) return;
-    const reader = stream.getReader();
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      target.push(value);
-    }
-  };
-
-  await Promise.all([
-    readStream(proc.stdout, stdoutChunks),
-    readStream(proc.stderr, stderrChunks),
-  ]);
-
-  const code = await proc.exited;
-  const stdout = Buffer.concat(stdoutChunks).toString("utf-8").trim();
-  const stderr = Buffer.concat(stderrChunks).toString("utf-8").trim();
-
-  if (code !== 0) {
-    // Extract meaningful error from stderr
-    const errLine = stderr.split("\n").find((l) => l.includes("Error:") || l.includes("error"));
-    throw new Error(errLine || stderr || "Gateway call failed (exit code " + code + ")");
-  }
-
-  if (!stdout) {
-    throw new Error("Empty response from gateway");
-  }
-
-  return JSON.parse(stdout);
-}
-
-export const registerClusterCli = ({ program }: { program: Command }) => {
-  const cmd = program.command("clawmatrix").description("ClawMatrix cluster management");
-
-  cmd
-    .command("status")
-    .description("Show cluster topology and peer status")
-    .action(async () => {
-      let data: Record<string, unknown>;
-      try {
-        data = (await callGateway("clawmatrix.status")) as Record<string, unknown>;
-      } catch {
-        console.log("Could not reach gateway. Is it running?");
-        return;
-      }
-
-      if (data.error) {
-        console.log(String(data.error));
-        return;
-      }
-
-      // Style helpers
-      const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;
-      const dim = (s: string) => `\x1b[2m${s}\x1b[22m`;
-      const green = (s: string) => `\x1b[32m${s}\x1b[39m`;
-      const red = (s: string) => `\x1b[31m${s}\x1b[39m`;
-      const cyan = (s: string) => `\x1b[36m${s}\x1b[39m`;
-      const yellow = (s: string) => `\x1b[33m${s}\x1b[39m`;
-      const bar = dim("│");
-      const lbl = (text: string) => dim(text.padEnd(13));
-
-      const agents = data.agents as Array<{ id: string }>;
-      const models = data.models as Array<{ id: string }>;
-      const tags = data.tags as string[];
-
-      // Local node
-      console.log();
-      console.log(`  ${cyan("◆")}  ${bold("ClawMatrix Cluster")}`);
-      console.log(`  ${bar}`);
-      console.log(`  ${bar}  ${lbl("Node")}${bold(String(data.nodeId))}`);
-      if (tags.length > 0) {
-        console.log(`  ${bar}  ${lbl("Tags")}${tags.join(dim(", "))}`);
-      }
-      console.log(`  ${bar}  ${lbl("Listen")}${data.listen !== false ? `:${data.listen}` : dim("disabled")}`);
-      console.log(`  ${bar}  ${lbl("Model Proxy")}:${data.proxyPort}`);
-      console.log(`  ${bar}  ${lbl("Agents")}${agents.map((a) => a.id).join(dim(", ")) || dim("–")}`);
-      console.log(`  ${bar}  ${lbl("Models")}${models.map((m) => m.id).join(dim(", ")) || dim("–")}`);
-
-      const peers = data.peers as Array<{
-        nodeId: string;
-        agents: Array<{ id: string }>;
-        models: Array<{ id: string }>;
-        tags: string[];
-        connected: boolean;
-        status: "direct" | "relay" | "unreachable" | "sentinel-only";
-        latencyMs: number;
-        reachableVia: string | null;
-      }>;
-
-      if (!peers || peers.length === 0) {
-        console.log(`  ${bar}`);
-        console.log(`  ${dim("◇")}  ${dim("No peers discovered")}`);
-        console.log();
-        return;
-      }
-
-      const reachable = peers.filter((p) => p.connected).length;
-      const countStr = `${reachable}/${peers.length} reachable`;
-      const countColor = reachable === peers.length ? green : reachable > 0 ? yellow : red;
-
-      console.log(`  ${bar}`);
-      console.log(`  ${cyan("◆")}  ${bold("Peers")}  ${countColor(countStr)}`);
-      console.log(`  ${bar}`);
-
-      for (let i = 0; i < peers.length; i++) {
-        const peer = peers[i];
-        const dot = peer.status === "direct" ? green("●")
-          : peer.status === "relay" ? yellow("●")
-          : peer.status === "sentinel-only" ? yellow("◐")
-          : red("○");
-        const latency = peer.connected && peer.latencyMs > 0 ? dim(` ${peer.latencyMs}ms`) : "";
-        const statusLabel = peer.status === "relay"
-          ? yellow(` relay via ${peer.reachableVia}`)
-          : peer.status === "sentinel-only"
-            ? yellow(" sentinel only")
-          : peer.status === "unreachable"
-            ? red(" unreachable")
-            : "";
-        console.log(`  ${bar}  ${dot} ${bold(peer.nodeId)}${statusLabel}${latency}`);
-
-        if (peer.tags.length > 0) {
-          console.log(`  ${bar}    ${lbl("Tags")}${peer.tags.join(dim(", "))}`);
-        }
-        const peerAgents = peer.agents.map((a) => a.id).join(dim(", "));
-        if (peerAgents) {
-          console.log(`  ${bar}    ${lbl("Agents")}${peerAgents}`);
-        }
-        const peerModels = peer.models.map((m) => m.id).join(dim(", "));
-        if (peerModels) {
-          console.log(`  ${bar}    ${lbl("Models")}${peerModels}`);
-        }
-
-        if (i < peers.length - 1) {
-          console.log(`  ${bar}`);
-        }
-      }
-
-      console.log(`  ${bar}`);
-      console.log(`  ${dim("◇")}`);
-      console.log();
-    });
-
-  cmd
-    .command("peers")
-    .description("List known peers (JSON)")
-    .action(async () => {
-      let peers: unknown;
-      try {
-        peers = await callGateway("clawmatrix.peers");
-      } catch {
-        console.log("[]");
-        return;
-      }
-      console.log(JSON.stringify(peers, null, 2));
-    });
-
-  // ── Peer approval commands ──────────────────────────────────────
-
-  cmd
-    .command("approve <approvalId>")
-    .description("Approve a pending peer join request")
-    .action(async (approvalId: string) => {
-      try {
-        const result = await callGateway("clawmatrix.approval.resolve", {
-          approvalId,
-          decision: "approve",
-        }) as Record<string, unknown>;
-        if (result.ok) {
-          console.log(`Approved: ${approvalId}`);
-        } else {
-          console.log(`Approval not found or already resolved: ${approvalId}`);
-        }
-      } catch {
-        console.log("Could not reach gateway. Is it running?");
-      }
-    });
-
-  cmd
-    .command("deny <approvalId>")
-    .description("Deny a pending peer join request")
-    .action(async (approvalId: string) => {
-      try {
-        const result = await callGateway("clawmatrix.approval.resolve", {
-          approvalId,
-          decision: "deny",
-        }) as Record<string, unknown>;
-        if (result.ok) {
-          console.log(`Denied: ${approvalId}`);
-        } else {
-          console.log(`Approval not found or already resolved: ${approvalId}`);
-        }
-      } catch {
-        console.log("Could not reach gateway. Is it running?");
-      }
-    });
-
-  const approval = cmd.command("approval").description("Manage peer approvals");
-
-  approval
-    .command("list")
-    .description("List approved and pending peers")
-    .action(async () => {
-      try {
-        const data = await callGateway("clawmatrix.approval.list") as Record<string, unknown>;
-        console.log(JSON.stringify(data, null, 2));
-      } catch {
-        console.log("Could not reach gateway. Is it running?");
-      }
-    });
-
-  approval
-    .command("revoke <nodeId>")
-    .description("Revoke an approved peer")
-    .action(async (nodeId: string) => {
-      try {
-        const result = await callGateway("clawmatrix.approval.revoke", { nodeId }) as Record<string, unknown>;
-        if (result.ok) {
-          console.log(`Revoked: ${nodeId}`);
-        } else {
-          console.log(`Node not found in approved list: ${nodeId}`);
-        }
-      } catch {
-        console.log("Could not reach gateway. Is it running?");
-      }
-    });
-};