clawmatrix 0.3.1 → 0.4.0

package/cli/bin/clawmatrix.mjs

@@ -0,0 +1,1006 @@
+#!/usr/bin/env node
+// ClawMatrix CLI — zero-dependency, connects directly to gateway WebSocket.
+// Requires Node.js >= 22 (built-in WebSocket).
+
+import crypto, { randomUUID } from "node:crypto";
+import { readFileSync, mkdirSync, existsSync, readlinkSync, realpathSync, symlinkSync, unlinkSync, rmSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+
+// ── Config resolution ────────────────────────────────────────────────
+
+const DEFAULT_PORT = 18789;
+
+function readOpenClawConfig() {
+  const configPath = process.env.OPENCLAW_CONFIG_PATH?.trim();
+  if (configPath) {
+    try { return JSON.parse(readFileSync(configPath, "utf-8")); } catch {}
+  }
+  const stateDir = process.env.OPENCLAW_STATE_DIR?.trim() || join(homedir(), ".openclaw");
+  for (const name of ["openclaw.json", "clawdbot.json"]) {
+    try { return JSON.parse(readFileSync(join(stateDir, name), "utf-8")); } catch {}
+  }
+  return undefined;
+}
+
+function resolvePort() {
+  const envRaw = process.env.OPENCLAW_GATEWAY_PORT?.trim() || process.env.CLAWDBOT_GATEWAY_PORT?.trim();
+  if (envRaw) {
+    const parsed = parseInt(envRaw, 10);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  try {
+    const port = readOpenClawConfig()?.gateway?.port;
+    if (typeof port === "number" && port > 0) return port;
+  } catch {}
+  return DEFAULT_PORT;
+}
+
+function resolveCredentials() {
+  const token = process.env.OPENCLAW_GATEWAY_TOKEN?.trim() || process.env.CLAWDBOT_GATEWAY_TOKEN?.trim() || undefined;
+  const password = process.env.OPENCLAW_GATEWAY_PASSWORD?.trim() || process.env.CLAWDBOT_GATEWAY_PASSWORD?.trim() || undefined;
+  if (token || password) return { token, password };
+  try {
+    const cfg = readOpenClawConfig();
+    return {
+      token: cfg?.gateway?.auth?.token?.trim() || undefined,
+      password: cfg?.gateway?.auth?.password?.trim() || undefined,
+    };
+  } catch {}
+  return {};
+}
+
+// ── Device identity (Ed25519 key pair for gateway auth) ──────────────
+
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+function base64UrlEncode(buf) {
+  return buf.toString("base64").replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/g, "");
+}
+
+function loadDeviceIdentity() {
+  const stateDir = process.env.OPENCLAW_STATE_DIR?.trim() || join(homedir(), ".openclaw");
+  const idPath = join(stateDir, "identity", "device.json");
+  try {
+    const parsed = JSON.parse(readFileSync(idPath, "utf-8"));
+    if (parsed?.version === 1 && parsed.deviceId && parsed.publicKeyPem && parsed.privateKeyPem) {
+      return parsed;
+    }
+  } catch {}
+  return null;
+}
+
+function buildDeviceAuth(identity, { nonce, token, scopes }) {
+  const signedAtMs = Date.now();
+  const payload = [
+    "v3", identity.deviceId, "cli", "cli", "operator",
+    scopes.join(","), String(signedAtMs), token ?? "", nonce, process.platform, "",
+  ].join("|");
+  const key = crypto.createPrivateKey(identity.privateKeyPem);
+  const sig = crypto.sign(null, Buffer.from(payload, "utf8"), key);
+  const pubKey = crypto.createPublicKey(identity.publicKeyPem);
+  const spki = pubKey.export({ type: "spki", format: "der" });
+  const rawKey = spki.length === ED25519_SPKI_PREFIX.length + 32
+    ? spki.subarray(ED25519_SPKI_PREFIX.length)
+    : spki;
+  return {
+    id: identity.deviceId,
+    publicKey: base64UrlEncode(rawKey),
+    signature: base64UrlEncode(sig),
+    signedAt: signedAtMs,
+  };
+}
+
+// ── Gateway WebSocket RPC (built-in WebSocket, W3C API) ──────────────
+
+const TIMEOUT_MS = 10_000;
+
+function callGateway(method, params, timeoutMs = TIMEOUT_MS) {
+  const port = resolvePort();
+  const creds = resolveCredentials();
+  const url = `ws://127.0.0.1:${port}`;
+
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url);
+    const callId = randomUUID();
+    let connectId;
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        ws.close();
+        reject(new Error(`Gateway call timed out (${timeoutMs}ms). Is the gateway running?`));
+      }
+    }, timeoutMs);
+
+    const finish = (err, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      ws.close();
+      err ? reject(err) : resolve(result);
+    };
+
+    ws.addEventListener("error", () => {
+      finish(new Error(`Could not connect to gateway at ${url}`));
+    });
+
+    ws.addEventListener("close", () => {
+      finish(new Error("Gateway connection closed unexpectedly"));
+    });
+
+    ws.addEventListener("message", (event) => {
+      try {
+        const frame = JSON.parse(event.data);
+
+        if (frame.type === "event" && frame.event === "connect.challenge") {
+          connectId = randomUUID();
+          const nonce = frame.payload?.nonce;
+          const scopes = ["operator.admin", "operator.read", "operator.write"];
+          const identity = loadDeviceIdentity();
+          const connectParams = {
+            minProtocol: 3,
+            maxProtocol: 3,
+            client: {
+              id: "cli",
+              version: "1.0.0",
+              platform: process.platform,
+              mode: "cli",
+              instanceId: randomUUID(),
+            },
+            auth: { token: creds.token, password: creds.password },
+            role: "operator",
+            scopes,
+            caps: [],
+          };
+          if (identity && nonce) {
+            const device = buildDeviceAuth(identity, {
+              nonce, token: creds.token, scopes,
+            });
+            device.nonce = nonce;
+            connectParams.device = device;
+          }
+          ws.send(JSON.stringify({
+            type: "req", id: connectId, method: "connect", params: connectParams,
+          }));
+          return;
+        }
+
+        if (frame.type === "res" && frame.id === connectId) {
+          if (!frame.ok) {
+            finish(new Error(`Gateway auth failed: ${frame.error?.message ?? "unknown error"}`));
+            return;
+          }
+          ws.send(JSON.stringify({ type: "req", id: callId, method, params: params ?? {} }));
+          return;
+        }
+
+        if (frame.type === "res" && frame.id === callId) {
+          frame.ok ? finish(null, frame.payload) : finish(new Error(frame.error?.message ?? frame.payload?.error ?? `Gateway call failed: ${method}`));
+        }
+      } catch (err) {
+        finish(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  });
+}
+
+// ── Style helpers ────────────────────────────────────────────────────
+
+const isTTY = process.stdout.isTTY === true;
+const ansi = (code, reset) =>
+  isTTY ? (s) => `\x1b[${code}m${s}\x1b[${reset}m` : (s) => s;
+
+const bold   = ansi("1", "22");
+const dim    = ansi("2", "22");
+const green  = ansi("32", "39");
+const red    = ansi("31", "39");
+const cyan   = ansi("36", "39");
+const yellow = ansi("33", "39");
+
+const jsonOut = (data) => JSON.stringify(data, null, isTTY ? 2 : 0);
+const bar = dim("│");
+const lbl = (text) => dim(text.padEnd(13));
+
+// ── Commands ─────────────────────────────────────────────────────────
+
+async function cmdStatus(args) {
+  const isJson = args.includes("--json");
+  let data;
+  try {
+    data = await callGateway("clawmatrix.status");
+  } catch {
+    console.log("Could not reach gateway. Is it running?");
+    process.exit(1);
+  }
+
+  if (data.error) { console.log(String(data.error)); return; }
+  if (isJson) { console.log(jsonOut(data)); return; }
+
+  const agents = data.agents || [];
+  const models = data.models || [];
+  const tags = data.tags || [];
+  const peers = data.peers || [];
+
+  if (!isTTY) {
+    // Compact output for AI/scripting consumption
+    const parts = [`Node: ${data.nodeId}`];
+    if (tags.length > 0) parts.push(`Tags: ${tags.join(", ")}`);
+    parts.push(`Listen: ${data.listen !== false ? `:${data.listen}` : "disabled"}`);
+    parts.push(`Model Proxy: :${data.proxyPort}`);
+    if (agents.length > 0) parts.push(`Agents: ${agents.map((a) => a.id).join(", ")}`);
+    if (models.length > 0) parts.push(`Models: ${models.map((m) => m.id).join(", ")}`);
+    console.log(parts.join(" | "));
+
+    if (peers.length === 0) { console.log("Peers: none"); return; }
+
+    const reachable = peers.filter((p) => p.connected).length;
+    console.log(`Peers: ${reachable}/${peers.length} reachable`);
+    for (const peer of peers) {
+      const info = [`[${peer.status}]`, peer.nodeId];
+      if (peer.latencyMs > 0) info.push(`${peer.latencyMs}ms`);
+      if (peer.status === "relay") info.push(`via ${peer.reachableVia}`);
+      if (peer.tags?.length > 0) info.push(`Tags: ${peer.tags.join(", ")}`);
+      const pa = (peer.agents || []).map((a) => a.id).join(", ");
+      if (pa) info.push(`Agents: ${pa}`);
+      const pm = (peer.models || []).map((m) => m.id).join(", ");
+      if (pm) info.push(`Models: ${pm}`);
+      console.log(info.join(" | "));
+    }
+    return;
+  }
+
+  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("–")}`);
+
+  if (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();
+}
+
+async function cmdPeers() {
+  try {
+    const peers = await callGateway("clawmatrix.peers");
+    console.log(jsonOut(peers));
+  } catch {
+    console.log("[]");
+  }
+}
+
+async function cmdCheck(nodeId) {
+  if (!nodeId) { console.error("Usage: clawmatrix check <nodeId>"); process.exit(1); }
+  try {
+    const peers = await callGateway("clawmatrix.peers");
+    const peer = peers.find((p) => p.nodeId === nodeId);
+    if (!peer) {
+      console.log(jsonOut({ nodeId, reachable: false, status: "unknown", error: "Node not found in peer list" }));
+      process.exit(1);
+    }
+    console.log(jsonOut({
+      nodeId: peer.nodeId, reachable: peer.connected, status: peer.status,
+      latencyMs: peer.latencyMs, agents: peer.agents?.length ?? 0,
+      models: peer.models?.length ?? 0, toolProxy: peer.toolProxy?.enabled ?? false,
+    }));
+    if (!peer.connected) process.exitCode = 1;
+  } catch {
+    console.log(jsonOut({ nodeId, reachable: false, status: "error", error: "Could not reach gateway" }));
+    process.exit(1);
+  }
+}
+
+async function cmdTools(args) {
+  const isJson = args.includes("--json");
+  const verbose = args.includes("-v") || args.includes("--verbose");
+  const filterIdx = args.indexOf("-f") !== -1 ? args.indexOf("-f") : args.indexOf("--filter");
+  const filterKw = filterIdx !== -1 ? args[filterIdx + 1] : undefined;
+  const descIdx = args.indexOf("-d") !== -1 ? args.indexOf("-d") : args.indexOf("--describe");
+  const describeTool = descIdx !== -1 ? args[descIdx + 1] : undefined;
+  const node = args.find((a) => !a.startsWith("-") && a !== filterKw && a !== describeTool);
+
+  try {
+    const data = await callGateway("clawmatrix.tools.list", node ? { node } : undefined);
+    if (isJson) { console.log(jsonOut(data)); return; }
+    if (data.length === 0) { console.log("No nodes with tool proxy enabled."); return; }
+
+    if (describeTool) {
+      const toolName = describeTool.toLowerCase();
+      for (const entry of data) {
+        const found = (entry.toolProxy.catalog || []).find((t) => t.name.toLowerCase() === toolName);
+        if (found) {
+          const parts = [`node: ${entry.nodeId}`, `tool: ${found.name}`, `description: ${found.description}`];
+          if (found.inputSchema) parts.push(`params: ${JSON.stringify(found.inputSchema)}`);
+          if (found.usage) parts.push(`usage:\n${found.usage}`);
+          parts.push(`invoke: clawmatrix call ${entry.nodeId} ${found.name} '{}'`);
+          console.log(parts.join(isTTY ? "\n" : " | "));
+          return;
+        }
+      }
+      console.error(`Tool "${describeTool}" not found. Run 'clawmatrix tools' to see available tools.`);
+      process.exit(1);
+    }
+
+    const filterLower = filterKw?.toLowerCase();
+    const matchesFilter = (t) =>
+      !filterLower || t.name.toLowerCase().includes(filterLower) ||
+      t.description.toLowerCase().includes(filterLower) ||
+      (t.usage ?? "").toLowerCase().includes(filterLower);
+
+    if (!isTTY) {
+      // Compact output for AI/scripting consumption
+      for (const entry of data) {
+        const tools = entry.toolProxy.allow;
+        const catalog = entry.toolProxy.catalog || [];
+        const catalogMap = new Map(catalog.map((t) => [t.name, t]));
+        const isWildcard = tools.includes("*");
+        const toolsToShow = isWildcard
+          ? catalog.filter(matchesFilter)
+          : tools.map((name) => catalogMap.get(name) ?? { name, description: "" }).filter(matchesFilter);
+        const totalCount = isWildcard ? catalog.length : tools.length;
+        const shownCount = toolsToShow.length;
+        const countLabel = filterLower ? `${shownCount}/${totalCount} matched` : `${totalCount} tools`;
+        const denied = entry.toolProxy.deny;
+
+        console.log(`${entry.nodeId} | ${entry.status} | ${countLabel}`);
+        for (const tool of toolsToShow) {
+          const desc = tool.description ? ` - ${tool.description}` : "";
+          console.log(`  ${tool.name}${desc}`);
+        }
+        if (denied.length > 0) console.log(`  Denied: ${denied.join(", ")}`);
+      }
+      return;
+    }
+
+    console.log();
+    for (const entry of data) {
+      const tools = entry.toolProxy.allow;
+      const catalog = entry.toolProxy.catalog || [];
+      const catalogMap = new Map(catalog.map((t) => [t.name, t]));
+      const denied = entry.toolProxy.deny;
+      const isWildcard = tools.includes("*");
+      const toolsToShow = isWildcard
+        ? catalog.filter(matchesFilter)
+        : tools.map((name) => catalogMap.get(name) ?? { name, description: "" }).filter(matchesFilter);
+      const totalCount = isWildcard ? catalog.length : tools.length;
+      const shownCount = toolsToShow.length;
+      const countLabel = filterLower ? `${shownCount}/${totalCount} matched` : `${totalCount} tools`;
+
+      console.log(`  ${cyan("◆")}  ${bold(entry.nodeId)}  ${green(entry.status)}  ${dim(countLabel)}`);
+      console.log(`  ${bar}`);
+
+      if (toolsToShow.length === 0 && !filterLower) {
+        console.log(`  ${bar}  ${isWildcard ? green("*") + " " + dim("(all tools allowed)") : dim("No tools advertised")}`);
+      } else if (toolsToShow.length === 0) {
+        console.log(`  ${bar}  ${dim(`No tools matching "${filterKw}"`)}`);
+      } else if (verbose) {
+        for (const tool of toolsToShow) {
+          console.log(`  ${bar}  ${green("●")} ${bold(tool.name)}`);
+          if (tool.description) console.log(`  ${bar}    ${dim(tool.description)}`);
+          if (tool.usage) tool.usage.split("\n").forEach((l) => console.log(`  ${bar}    ${l}`));
+        }
+      } else {
+        const maxNameLen = Math.max(...toolsToShow.map((t) => t.name.length));
+        for (const tool of toolsToShow) {
+          const desc = tool.description ? `  ${dim(tool.description)}` : "";
+          console.log(`  ${bar}  ${green("●")} ${tool.name.padEnd(maxNameLen)}${desc}`);
+        }
+      }
+      if (denied.length > 0) console.log(`  ${bar}  ${dim("Denied:")} ${denied.join(", ")}`);
+      console.log();
+    }
+  } catch {
+    console.log("Could not reach gateway. Is it running?");
+  }
+}
+
+async function cmdCall(node, tool, paramsStr, args) {
+  if (!node || !tool) { console.error("Usage: clawmatrix call <node> <tool> [json-params]"); process.exit(1); }
+  try {
+    let toolParams = {};
+    if (paramsStr) {
+      try { toolParams = JSON.parse(paramsStr); } catch {
+        console.error(`Error: Invalid JSON params: ${paramsStr}`);
+        process.exit(1);
+      }
+    }
+    const tIdx = args.indexOf("-t") !== -1 ? args.indexOf("-t") : args.indexOf("--timeout");
+    const timeout = tIdx !== -1 ? parseInt(args[tIdx + 1], 10) : undefined;
+    const result = await callGateway("clawmatrix.tools.call", {
+      node, tool, params: toolParams,
+      ...(timeout !== undefined && { timeout }),
+    });
+    console.log(jsonOut(result));
+  } catch (err) {
+    const msg = err.message || String(err);
+    if (msg.includes("not reachable")) console.error(`Error: Node "${node}" is not reachable. Run 'clawmatrix status' to check connectivity.`);
+    else if (msg.includes("not allowed")) console.error(`Error: Tool "${tool}" is not allowed on node "${node}". Run 'clawmatrix tools ${node}' to see available tools.`);
+    else if (msg.includes("timed out")) console.error(`Error: Tool "${tool}" timed out on node "${node}". Try increasing timeout with -t <ms>.`);
+    else console.error(`Error: ${msg}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdBatch(node, itemsStr, args) {
+  if (!node) { console.error("Usage: clawmatrix batch <node> [json-items]"); process.exit(1); }
+  try {
+    let jsonStr = itemsStr;
+    if (!jsonStr && !process.stdin.isTTY) {
+      const chunks = [];
+      for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+      jsonStr = Buffer.concat(chunks).toString("utf-8").trim();
+    }
+    if (!jsonStr) {
+      console.error('Error: No items provided. Pass JSON array or pipe via stdin.');
+      process.exit(1);
+    }
+    const items = JSON.parse(jsonStr);
+    const tIdx = args.indexOf("-t") !== -1 ? args.indexOf("-t") : args.indexOf("--timeout");
+    const timeout = tIdx !== -1 ? parseInt(args[tIdx + 1], 10) : undefined;
+    const stopOnError = !args.includes("--no-stop-on-error");
+    const results = await callGateway("clawmatrix.tools.batch", {
+      node, items, stopOnError,
+      ...(timeout !== undefined && { timeout }),
+    });
+    console.log(jsonOut(results));
+  } catch (err) {
+    console.error(`Error: ${err.message || String(err)}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdModels(args) {
+  const isJson = args.includes("--json");
+  const nIdx = args.indexOf("-n") !== -1 ? args.indexOf("-n") : args.indexOf("--node");
+  const nodeFilter = nIdx !== -1 ? args[nIdx + 1] : undefined;
+
+  try {
+    const data = await callGateway("clawmatrix.models.list", nodeFilter ? { node: nodeFilter } : undefined);
+    if (isJson) { console.log(jsonOut(data)); return; }
+    if (data.length === 0) { console.log("No models available in the cluster."); return; }
+
+    const byNode = new Map();
+    for (const m of data) {
+      const arr = byNode.get(m.nodeId) || [];
+      arr.push(m);
+      byNode.set(m.nodeId, arr);
+    }
+
+    if (!isTTY) {
+      // Compact output for AI/scripting consumption
+      for (const [nodeId, models] of byNode) {
+        const reachable = models[0]?.reachable !== false;
+        console.log(`${nodeId} | ${reachable ? "reachable" : "unreachable"} | ${models.length} models`);
+        for (const m of models) {
+          const details = [];
+          if (m.contextWindow) details.push(`${Math.round(m.contextWindow / 1000)}k ctx`);
+          if (m.reasoning) details.push("reasoning");
+          if (m.input?.includes("image")) details.push("vision");
+          const detailStr = details.length > 0 ? ` (${details.join(", ")})` : "";
+          console.log(`  ${m.id}${detailStr}`);
+        }
+      }
+      return;
+    }
+
+    console.log();
+    for (const [nodeId, models] of byNode) {
+      const reachable = models[0]?.reachable !== false;
+      const statusLabel = reachable ? green("reachable") : red("unreachable");
+      console.log(`  ${cyan("◆")}  ${bold(nodeId)}  ${statusLabel}  ${dim(`${models.length} models`)}`);
+      console.log(`  ${bar}`);
+      const maxIdLen = Math.max(...models.map((m) => m.id.length));
+      for (const m of models) {
+        const details = [];
+        if (m.contextWindow) details.push(`${Math.round(m.contextWindow / 1000)}k ctx`);
+        if (m.reasoning) details.push("reasoning");
+        if (m.input?.includes("image")) details.push("vision");
+        const detailStr = details.length > 0 ? `  ${dim(details.join(", "))}` : "";
+        console.log(`  ${bar}  ${green("●")} ${m.id.padEnd(maxIdLen)}${detailStr}`);
+      }
+      console.log();
+    }
+  } catch {
+    console.log("Could not reach gateway. Is it running?");
+  }
+}
+
+async function cmdEvents(args) {
+  const isJson = args.includes("--json");
+  const consumeIdx = args.indexOf("--consume");
+  if (consumeIdx !== -1) {
+    const raw = args[consumeIdx + 1];
+    if (!raw) { console.error("Usage: clawmatrix events --consume <id1,id2,...>"); process.exit(1); }
+    const ids = raw.split(",").map((s) => s.trim()).filter(Boolean);
+    try {
+      const result = await callGateway("clawmatrix.events.consume", { ids });
+      console.log(jsonOut(result));
+    } catch (e) {
+      console.error(e.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  try {
+    const params = {};
+    const tIdx = args.indexOf("-t") !== -1 ? args.indexOf("-t") : args.indexOf("--type");
+    if (tIdx !== -1) params.type = args[tIdx + 1];
+    const sIdx = args.indexOf("-s") !== -1 ? args.indexOf("-s") : args.indexOf("--source");
+    if (sIdx !== -1) params.source = args[sIdx + 1];
+    const lIdx = args.indexOf("-l") !== -1 ? args.indexOf("-l") : args.indexOf("--limit");
+    if (lIdx !== -1) params.limit = parseInt(args[lIdx + 1], 10);
+    if (args.includes("-a") || args.includes("--all")) params.unconsumed = false;
+
+    const events = await callGateway("clawmatrix.events.query", params);
+    if (isJson) { console.log(jsonOut(events)); return; }
+    if (events.length === 0) { console.log("No events found."); return; }
+
+    if (!isTTY) {
+      // Compact output for AI/scripting consumption
+      console.log(`Events: ${events.length} result(s)`);
+      for (const evt of events) {
+        const age = Math.floor((Date.now() - evt.ts) / 1000);
+        const ageStr = age < 60 ? `${age}s ago` : age < 3600 ? `${Math.floor(age / 60)}m ago` : `${Math.floor(age / 3600)}h ago`;
+        const consumed = evt.consumed ? " [consumed]" : "";
+        const dataStr = JSON.stringify(evt.data);
+        const truncated = dataStr.length > 200 ? dataStr.slice(0, 200) + "..." : dataStr;
+        console.log(`${evt.type} | ${evt.source} | ${ageStr}${consumed} | id:${evt.id} | ${truncated}`);
+      }
+      return;
+    }
+
+    console.log();
+    console.log(`  ${cyan("◆")}  ${bold("Events")}  ${dim(`${events.length} result(s)`)}`);
+    console.log(`  ${bar}`);
+
+    for (const evt of events) {
+      const age = Math.floor((Date.now() - evt.ts) / 1000);
+      const ageStr = age < 60 ? `${age}s ago` : age < 3600 ? `${Math.floor(age / 60)}m ago` : `${Math.floor(age / 3600)}h ago`;
+      const consumed = evt.consumed ? dim(" [consumed]") : "";
+      console.log(`  ${bar}  ${green("●")} ${bold(evt.type)} ${dim(`from ${evt.source}`)} ${dim(ageStr)}${consumed}`);
+      console.log(`  ${bar}    ${dim("id:")} ${evt.id}`);
+      const dataStr = JSON.stringify(evt.data);
+      const truncated = dataStr.length > 120 ? dataStr.slice(0, 120) + "..." : dataStr;
+      console.log(`  ${bar}    ${dim("data:")} ${truncated}`);
+    }
+    console.log();
+  } catch (err) {
+    const msg = err.message || String(err);
+    if (msg.includes("not enabled")) console.log("Events not available (web.enabled = false in config).");
+    else console.log("Could not reach gateway. Is it running?");
+  }
+}
+
+async function cmdApprove(approvalId) {
+  if (!approvalId) { console.error("Usage: clawmatrix approve <approvalId>"); process.exit(1); }
+  try {
+    const result = await callGateway("clawmatrix.approval.resolve", { approvalId, decision: "approve" });
+    console.log(result.ok ? `Approved: ${approvalId}` : `Not found or already resolved: ${approvalId}`);
+  } catch { console.log("Could not reach gateway. Is it running?"); }
+}
+
+async function cmdDeny(approvalId) {
+  if (!approvalId) { console.error("Usage: clawmatrix deny <approvalId>"); process.exit(1); }
+  try {
+    const result = await callGateway("clawmatrix.approval.resolve", { approvalId, decision: "deny" });
+    console.log(result.ok ? `Denied: ${approvalId}` : `Not found or already resolved: ${approvalId}`);
+  } catch { console.log("Could not reach gateway. Is it running?"); }
+}
+
+async function cmdApprovalList() {
+  try {
+    const result = await callGateway("clawmatrix.approval.list");
+    console.log(jsonOut(result));
+  } catch { console.log("Could not reach gateway. Is it running?"); }
+}
+
+async function cmdApprovalRevoke(nodeId) {
+  if (!nodeId) { console.error("Usage: clawmatrix approval revoke <nodeId>"); process.exit(1); }
+  try {
+    const result = await callGateway("clawmatrix.approval.revoke", { nodeId });
+    console.log(result.ok ? `Revoked: ${nodeId}` : `Node not found in approved list: ${nodeId}`);
+  } catch { console.log("Could not reach gateway. Is it running?"); }
+}
+
+function cmdHelpJson() {
+  const commands = [
+    { name: "status", args: "", options: ["--json"], description: "Show cluster topology and peer status" },
+    { name: "peers", args: "", options: [], description: "List known peers (JSON)" },
+    { name: "check", args: "<nodeId>", options: [], description: "Check if a specific node is reachable" },
+    { name: "tools", args: "[node]", options: ["--json", "-v", "-f <keyword>", "-d <tool>"], description: "List available tools on remote nodes" },
+    { name: "call", args: "<node> <tool> [json]", options: ["-t <ms>"], description: "Invoke a tool on a remote node" },
+    { name: "batch", args: "<node> [json]", options: ["--no-stop-on-error", "-t <ms>"], description: "Invoke multiple tools in sequence" },
+    { name: "models", args: "", options: ["--json", "-n <nodeId>"], description: "List all cluster models" },
+    { name: "events", args: "", options: ["--json", "-t <type>", "-s <source>", "-l <n>", "-a", "--consume <ids>"], description: "Query and consume events" },
+    { name: "send", args: "<node> <message>", options: [], description: "Send a message to a remote node" },
+    { name: "handoff", args: "<task>", options: ["--agent <agent>", "--node <node>", "-t <ms>"], description: "Delegate a task to a remote agent" },
+    { name: "acp", args: "<action>", options: ["-n <node>", "-a <agent>", "--session <id>", "--mode <mode>", "--cwd <dir>"], description: "Manage ACP agent sessions" },
+    { name: "diagnostic", args: "<node>", options: ["--action status|exec", "-c <command>", "-t <seconds>"], description: "Diagnose a remote node via sentinel" },
+    { name: "notify", args: "<title>", options: ["--detail <text>", "--progress <0-100>", "--action start|update|end", "--task-id <id>", "--tool <name>"], description: "Push notification to mobile devices" },
+    { name: "terminal", args: "<node>", options: ["--shell <shell>", "--cwd <dir>", "--action list|close|read|input", "--session <id>"], description: "Open/manage remote terminal sessions" },
+    { name: "transfer", args: "<node> <path> [remote]", options: ["--pull", "-t <ms>"], description: "Transfer files to/from a remote node" },
+    { name: "approve", args: "<approvalId>", options: [], description: "Approve a pending peer" },
+    { name: "deny", args: "<approvalId>", options: [], description: "Deny a pending peer" },
+    { name: "approval list", args: "", options: [], description: "List approved/pending peers" },
+    { name: "approval revoke", args: "<nodeId>", options: [], description: "Revoke an approved peer" },
+    { name: "install-skill", args: "", options: [], description: "Symlink skill into ~/.claude/skills/" },
+  ];
+  console.log(jsonOut({ prefix: "clawmatrix", commands }));
+}
+
+function cmdInstallSkill() {
+  const pluginSkillsDir = resolve(dirname(new URL(import.meta.url).pathname), "..", "skills", "clawmatrix");
+  if (!existsSync(pluginSkillsDir)) {
+    console.error("Skill source not found: " + pluginSkillsDir);
+    process.exit(1);
+  }
+
+  const claudeSkillsDir = join(homedir(), ".claude", "skills", "clawmatrix");
+  const claudeSkillsParent = dirname(claudeSkillsDir);
+  mkdirSync(claudeSkillsParent, { recursive: true });
+
+  // Remove existing (symlink, dir, or broken symlink)
+  try {
+    const existing = readlinkSync(claudeSkillsDir);
+    // It's a symlink — check if it already points to the right place
+    try {
+      if (realpathSync(claudeSkillsDir) === realpathSync(pluginSkillsDir)) {
+        console.log("Already installed: " + claudeSkillsDir + " -> " + pluginSkillsDir);
+        return;
+      }
+    } catch { /* broken symlink, remove it */ }
+    unlinkSync(claudeSkillsDir);
+  } catch {
+    // Not a symlink — remove if it's a regular dir
+    try { rmSync(claudeSkillsDir, { recursive: true }); } catch {}
+  }
+
+  symlinkSync(pluginSkillsDir, claudeSkillsDir, "dir");
+  console.log("Installed: " + claudeSkillsDir + " -> " + pluginSkillsDir);
+}
+
+async function cmdSend(node, message) {
+  if (!node || !message) { console.error("Usage: clawmatrix send <node> <message>"); process.exit(1); }
+  try {
+    const result = await callGateway("clawmatrix.send", { node, message });
+    console.log(result.sent ? `Sent to ${result.nodeId}` : "Failed to send");
+  } catch (err) {
+    console.error(`Error: ${err.message || String(err)}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdHandoff(args) {
+  const agentIdx = args.indexOf("--agent");
+  const agent = agentIdx !== -1 ? args[agentIdx + 1] : undefined;
+  const nodeIdx = args.indexOf("--node");
+  const node = nodeIdx !== -1 ? args[nodeIdx + 1] : undefined;
+  const tIdx = args.indexOf("-t") !== -1 ? args.indexOf("-t") : args.indexOf("--timeout");
+  const timeout = tIdx !== -1 ? parseInt(args[tIdx + 1], 10) : 600000;
+  const task = args.find((a) => !a.startsWith("-") && a !== agent && a !== node && a !== args[tIdx + 1]);
+  if (!task) { console.error("Usage: clawmatrix handoff <task> [--agent <agent>] [--node <node>]"); process.exit(1); }
+  const target = agent || (node ? `tags:${node}` : undefined);
+  if (!target) { console.error("Error: Provide --agent or --node"); process.exit(1); }
+  try {
+    const result = await callGateway("clawmatrix.handoff", { target, task }, timeout);
+    console.log(jsonOut(result));
+  } catch (err) {
+    console.error(`Error: ${err.message || String(err)}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdAcp(subCmd, args) {
+  const nodeFlag = (idx) => { const i = args.indexOf(idx); return i !== -1 ? args[i + 1] : undefined; };
+  const node = nodeFlag("--node") || nodeFlag("-n");
+  const agent = nodeFlag("--agent") || nodeFlag("-a");
+
+  switch (subCmd) {
+    case "list": {
+      if (!node) { console.error("Usage: clawmatrix acp list --node <node>"); process.exit(1); }
+      try {
+        const result = await callGateway("clawmatrix.acp.list", { node, agent });
+        console.log(jsonOut(result));
+      } catch (err) {
+        console.error(`Error: ${err.message || String(err)}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "prompt": case "create": {
+      if (!node) { console.error("Usage: clawmatrix acp prompt --node <node> --agent <agent> <task>"); process.exit(1); }
+      const sessionId = nodeFlag("--session");
+      const mode = nodeFlag("--mode");
+      const cwd = nodeFlag("--cwd");
+      const task = args.find((a) => !a.startsWith("-") && a !== node && a !== agent && a !== sessionId && a !== mode && a !== cwd);
+      try {
+        const result = await callGateway("clawmatrix.acp.prompt", { node, agent, task, sessionId, mode, cwd }, 600000);
+        console.log(jsonOut(result));
+      } catch (err) {
+        console.error(`Error: ${err.message || String(err)}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "resume": {
+      if (!node) { console.error("Usage: clawmatrix acp resume --node <node> --agent <agent> --session <acpSessionId>"); process.exit(1); }
+      const acpSessionId = nodeFlag("--session");
+      const cwd = nodeFlag("--cwd");
+      if (!acpSessionId || !agent) { console.error("Missing --agent and --session"); process.exit(1); }
+      try {
+        const result = await callGateway("clawmatrix.acp.resume", { node, agent, acpSessionId, cwd }, 600000);
+        console.log(jsonOut(result));
+      } catch (err) {
+        console.error(`Error: ${err.message || String(err)}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "cancel": {
+      if (!node) { console.error("Usage: clawmatrix acp cancel --node <node> --session <sessionId>"); process.exit(1); }
+      const sessionId = nodeFlag("--session");
+      if (!sessionId) { console.error("Missing --session"); process.exit(1); }
+      try {
+        const result = await callGateway("clawmatrix.acp.cancel", { node, sessionId });
+        console.log(jsonOut(result));
+      } catch (err) {
+        console.error(`Error: ${err.message || String(err)}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "close": {
+      if (!node) { console.error("Usage: clawmatrix acp close --node <node> --session <sessionId>"); process.exit(1); }
+      const sessionId = nodeFlag("--session");
+      if (!sessionId) { console.error("Missing --session"); process.exit(1); }
+      try {
+        const result = await callGateway("clawmatrix.acp.close", { node, sessionId });
+        console.log(jsonOut(result));
+      } catch (err) {
+        console.error(`Error: ${err.message || String(err)}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    default:
+      console.error("Usage: clawmatrix acp list|prompt|resume|cancel|close [options]");
+      process.exit(1);
+  }
+}
+
+async function cmdDiagnostic(node, args) {
+  if (!node) { console.error("Usage: clawmatrix diagnostic <node> [--action status|exec] [--command <cmd>]"); process.exit(1); }
+  const actionIdx = args.indexOf("--action");
+  const action = actionIdx !== -1 ? args[actionIdx + 1] : "status";
+  const cmdIdx = args.indexOf("--command") !== -1 ? args.indexOf("--command") : args.indexOf("-c");
+  const command = cmdIdx !== -1 ? args[cmdIdx + 1] : undefined;
+  const tIdx = args.indexOf("-t") !== -1 ? args.indexOf("-t") : args.indexOf("--timeout");
+  const timeout = tIdx !== -1 ? parseInt(args[tIdx + 1], 10) : 30;
+  if (action === "exec" && !command) { console.error("--command required for exec action"); process.exit(1); }
+  try {
+    const result = await callGateway("clawmatrix.diagnostic", { node, action, command, timeout }, (timeout + 10) * 1000);
+    console.log(jsonOut(result));
+  } catch (err) {
+    console.error(`Error: ${err.message || String(err)}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdNotify(title, args) {
+  if (!title) { console.error("Usage: clawmatrix notify <title> [--detail <text>] [--progress <0-100>]"); process.exit(1); }
+  const detailIdx = args.indexOf("--detail") !== -1 ? args.indexOf("--detail") : args.indexOf("-d");
+  const detail = detailIdx !== -1 ? args[detailIdx + 1] : undefined;
+  const progressIdx = args.indexOf("--progress") !== -1 ? args.indexOf("--progress") : args.indexOf("-p");
+  const progressRaw = progressIdx !== -1 ? parseInt(args[progressIdx + 1], 10) : undefined;
+  const progress = progressRaw !== undefined ? progressRaw / 100 : undefined;
+  const actionIdx = args.indexOf("--action");
+  const action = actionIdx !== -1 ? args[actionIdx + 1] : "start";
+  const taskIdIdx = args.indexOf("--task-id");
+  const taskId = taskIdIdx !== -1 ? args[taskIdIdx + 1] : undefined;
+  const toolIdx = args.indexOf("--tool");
+  const tool = toolIdx !== -1 ? args[toolIdx + 1] : undefined;
+  try {
+    const result = await callGateway("clawmatrix.notify", { action, taskId, title, detail, progress, tool });
+    if (isTTY) {
+      console.log(`${green("●")} Notification ${action}ed → ${result.targets} mobile peer(s) (taskId: ${result.taskId})`);
+    } else {
+      console.log(jsonOut(result));
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message || String(err)}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdTerminal(node, args) {
+  if (!node) { console.error("Usage: clawmatrix terminal <node> [--shell <shell>] [--cwd <dir>]"); process.exit(1); }
+  const shellIdx = args.indexOf("--shell");
+  const shell = shellIdx !== -1 ? args[shellIdx + 1] : undefined;
+  const cwdIdx = args.indexOf("--cwd");
+  const cwd = cwdIdx !== -1 ? args[cwdIdx + 1] : undefined;
+  const actionIdx = args.indexOf("--action");
+  const action = actionIdx !== -1 ? args[actionIdx + 1] : undefined;
+  const sessionIdx = args.indexOf("--session");
+  const sessionId = sessionIdx !== -1 ? args[sessionIdx + 1] : undefined;
+
+  if (action === "list") {
+    try {
+      const result = await callGateway("clawmatrix.terminal.list");
+      console.log(jsonOut(result));
+    } catch (err) { console.error(`Error: ${err.message || String(err)}`); process.exitCode = 1; }
+    return;
+  }
+  if (action === "close" && sessionId) {
+    try {
+      await callGateway("clawmatrix.terminal.close", { sessionId });
+      console.log(`Session ${sessionId} closed`);
+    } catch (err) { console.error(`Error: ${err.message || String(err)}`); process.exitCode = 1; }
+    return;
+  }
+  if (action === "read" && sessionId) {
+    try {
+      const result = await callGateway("clawmatrix.terminal.read", { sessionId });
+      if (result.data) process.stdout.write(result.data);
+    } catch (err) { console.error(`Error: ${err.message || String(err)}`); process.exitCode = 1; }
+    return;
+  }
+  if (action === "input" && sessionId) {
+    const data = args.find((a) => !a.startsWith("-") && a !== node && a !== sessionId && a !== action);
+    if (!data) { console.error("Missing input data"); process.exit(1); }
+    try {
+      await callGateway("clawmatrix.terminal.input", { sessionId, data });
+    } catch (err) { console.error(`Error: ${err.message || String(err)}`); process.exitCode = 1; }
+    return;
+  }
+
+  // Default: open a new session
+  try {
+    const result = await callGateway("clawmatrix.terminal.open", { node, shell, cwd }, 30000);
+    console.log(jsonOut(result));
+  } catch (err) {
+    console.error(`Error: ${err.message || String(err)}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdTransfer(node, localPath, args) {
+  if (!node || !localPath) { console.error("Usage: clawmatrix transfer <node> <local-path> [remote-path] [--pull]"); process.exit(1); }
+  const isPull = args.includes("--pull");
+  const remotePathIdx = args.findIndex((a) => !a.startsWith("-") && a !== node && a !== localPath);
+  const remotePath = remotePathIdx !== -1 ? args[remotePathIdx] : localPath;
+  const tIdx = args.indexOf("-t") !== -1 ? args.indexOf("-t") : args.indexOf("--timeout");
+  const timeout = tIdx !== -1 ? parseInt(args[tIdx + 1], 10) : 120000;
+  try {
+    let params;
+    if (isPull) {
+      params = { source_node: node, source_path: remotePath, target_path: localPath };
+    } else {
+      params = { target_node: node, source_path: localPath, target_path: remotePath };
+    }
+    const result = await callGateway("clawmatrix.transfer", params, timeout);
+    if (result.success) {
+      console.log(`Transfer complete: ${result.bytesTransferred} bytes`);
+    } else {
+      console.error(`Transfer failed: ${result.error}`);
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message || String(err)}`);
+    process.exitCode = 1;
+  }
+}
+
+const HELP = `ClawMatrix - Decentralized mesh cluster CLI
+
+Usage: clawmatrix <command> [options]
+
+Commands:
+  status                  Show cluster topology and peer status
+  check <nodeId>          Check if a specific node is reachable
+  tools [node]            List available tools on remote nodes
+  call <node> <tool> [p]  Invoke a tool on a remote node
+  batch <node> [json]     Invoke multiple tools in sequence
+  models                  List all models available across the cluster
+  events                  Query and consume ingested events
+  send <node> <message>   Send a message to a remote node
+  handoff <task> [opts]   Delegate a task to a remote agent
+  acp <action> [opts]     Manage ACP agent sessions (list|prompt|resume|cancel|close)
+  diagnostic <node>       Diagnose a remote node via sentinel
+  notify <title> [opts]   Push notification to mobile devices (Dynamic Island)
+  terminal <node>         Open/manage remote terminal sessions
+  transfer <node> <path>  Transfer files to/from a remote node
+  approve <approvalId>    Approve a pending peer join request
+  deny <approvalId>       Deny a pending peer join request
+  approval list|revoke    Manage approved peers
+  install-skill           Symlink skill into ~/.claude/skills/
+  help-json               Structured command reference (JSON)
+
+Options:
+  --help, -h              Show this help message
+
+Run 'clawmatrix <command> --help' for command-specific options.`;
+
+// ── Main dispatch ────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const rest = args.slice(1);
+
+try {
+  switch (cmd) {
+    case "status":        await cmdStatus(rest); break;
+    case "peers":         await cmdPeers(); break;
+    case "check":         await cmdCheck(rest[0]); break;
+    case "tools":         await cmdTools(rest); break;
+    case "call":          await cmdCall(rest[0], rest[1], rest[2], rest); break;
+    case "batch":         await cmdBatch(rest[0], rest.find((a) => a.startsWith("[") || a.startsWith("{")), rest); break;
+    case "models":        await cmdModels(rest); break;
+    case "events":        await cmdEvents(rest); break;
+    case "send":          await cmdSend(rest[0], rest.slice(1).join(" ")); break;
+    case "handoff":       await cmdHandoff(rest); break;
+    case "acp":           await cmdAcp(rest[0], rest.slice(1)); break;
+    case "diagnostic":    await cmdDiagnostic(rest[0], rest.slice(1)); break;
+    case "notify":        await cmdNotify(rest[0], rest.slice(1)); break;
+    case "terminal":      await cmdTerminal(rest[0], rest.slice(1)); break;
+    case "transfer":      await cmdTransfer(rest[0], rest[1], rest.slice(2)); break;
+    case "approve":       await cmdApprove(rest[0]); break;
+    case "deny":          await cmdDeny(rest[0]); break;
+    case "approval":
+      if (rest[0] === "list") await cmdApprovalList();
+      else if (rest[0] === "revoke") await cmdApprovalRevoke(rest[1]);
+      else { console.error("Usage: clawmatrix approval list|revoke <nodeId>"); process.exit(1); }
+      break;
+    case "install-skill": cmdInstallSkill(); break;
+    case "help-json":     cmdHelpJson(); break;
+    case "--help": case "-h": case undefined:
+      console.log(HELP); break;
+    default:
+      console.error(`Unknown command: ${cmd}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+} catch (e) {
+  console.error(e.message);
+  process.exit(1);
+}