clawmatrix 0.1.23 → 0.2.0

package/src/index.ts

@@ -1,5 +1,6 @@
 import type { OpenClawPluginApi, OpenClawConfig, GatewayRequestHandlerOptions } from "openclaw/plugin-sdk";
 import { ClawMatrixConfigSchema, parseConfig, type ClawMatrixConfig } from "./config.ts";
+import { debug, initDebugLogger } from "./debug.ts";
 import { createClusterService, getClusterRuntime } from "./cluster-service.ts";
 import { createClusterHandoffTool } from "./tools/cluster-handoff.ts";
 import { createClusterHandoffReplyTool } from "./tools/cluster-handoff-reply.ts";
@@ -8,9 +9,15 @@ import { createClusterPeersTool } from "./tools/cluster-peers.ts";
 import { createClusterExecTool } from "./tools/cluster-exec.ts";
 import { createClusterReadTool } from "./tools/cluster-read.ts";
 import { createClusterWriteTool } from "./tools/cluster-write.ts";
-import { createClusterToolTool } from "./tools/cluster-tool.ts";
+import { createClusterEditTool } from "./tools/cluster-edit.ts";
+import { createClusterBatchTool } from "./tools/cluster-batch.ts";
 import { createClusterEventsTool } from "./tools/cluster-events.ts";
+import { createClusterDiagnosticTool } from "./tools/cluster-diagnostic.ts";
+import { createClusterAcpTool } from "./tools/cluster-acp.ts";
+import { createClusterTerminalTool } from "./tools/cluster-terminal.ts";
+import { createClusterToolInvokeTool } from "./tools/cluster-tool.ts";
 import { registerClusterCli } from "./cli.ts";
+import { spawnProcess } from "./compat.ts";
 
 /**
  * Auto-discover models from OpenClaw's models.providers config.
@@ -25,41 +32,89 @@ function discoverModels(
   config: ClawMatrixConfig,
 ): ClawMatrixConfig["models"] {
   const cfg = openclawConfig as Record<string, unknown>;
-  const providers = (cfg.models as { providers?: Record<string, ProviderEntry> } | undefined)?.providers;
-  if (!providers || typeof providers !== "object") return [];
 
   // Collect proxyModel node IDs to exclude clawmatrix-registered providers
   const proxyNodeIds = new Set(config.proxyModels.map((m) => m.nodeId));
 
   const result: ClawMatrixConfig["models"] = [];
-  for (const [providerId, providerConfig] of Object.entries(providers)) {
-    // Skip clawmatrix proxy providers (remote models from peer nodes)
-    if (proxyNodeIds.has(providerId)) continue;
+  const seenIds = new Set<string>(); // "provider/modelId"
 
-    const models = providerConfig?.models;
-    if (!Array.isArray(models)) continue;
+  // 1. Discover from models.providers (explicit provider configs)
+  const providers = (cfg.models as { providers?: Record<string, ProviderEntry> } | undefined)?.providers;
+  if (providers && typeof providers === "object") {
+    for (const [providerId, providerConfig] of Object.entries(providers)) {
+      // Skip clawmatrix proxy providers (remote models from peer nodes)
+      if (proxyNodeIds.has(providerId)) continue;
+
+      const models = providerConfig?.models;
+      if (!Array.isArray(models)) continue;
+
+      for (const m of models) {
+        if (!m.id || typeof m.id !== "string") continue;
+        const key = `${providerId}/${m.id}`;
+        if (seenIds.has(key)) continue;
+        seenIds.add(key);
+        result.push({
+          id: m.id,
+          provider: providerId,
+          description: m.name as string | undefined,
+          baseUrl: providerConfig?.baseUrl,
+          apiKey: typeof providerConfig?.apiKey === "string" ? providerConfig.apiKey : undefined,
+          api: (m.api ?? providerConfig?.api) as ClawMatrixConfig["models"][0]["api"],
+          contextWindow: m.contextWindow as number | undefined,
+          maxTokens: m.maxTokens as number | undefined,
+          reasoning: m.reasoning as boolean | undefined,
+          input: m.input as ("text" | "image")[] | undefined,
+          cost: m.cost as { input: number; output: number; cacheRead: number; cacheWrite: number } | undefined,
+          compat: m.compat as ClawMatrixConfig["models"][0]["compat"],
+        });
+      }
+    }
+  }
 
-    for (const m of models) {
-      if (!m.id || typeof m.id !== "string") continue;
+  // 2. Discover from agents.defaults.model (primary + fallbacks) — the user's
+  //    configured model list, which includes pi-ai built-in models like
+  //    anthropic/claude-opus-4-6 that aren't in models.providers.
+  const agentDefaults = (cfg.agents as { defaults?: { model?: { primary?: string; fallbacks?: string[] } } } | undefined)?.defaults;
+  const modelConfig = agentDefaults?.model;
+  if (modelConfig) {
+    const refs: string[] = [];
+    if (modelConfig.primary) refs.push(modelConfig.primary);
+    if (Array.isArray(modelConfig.fallbacks)) refs.push(...modelConfig.fallbacks);
+
+    for (const modelRef of refs) {
+      if (typeof modelRef !== "string") continue;
+      const slashIdx = modelRef.indexOf("/");
+      if (slashIdx <= 0) continue;
+      const provider = modelRef.slice(0, slashIdx);
+      const modelId = modelRef.slice(slashIdx + 1);
+      if (!modelId) continue;
+
+      const key = `${provider}/${modelId}`;
+      if (seenIds.has(key)) continue;
+      if (proxyNodeIds.has(provider)) continue;
+      seenIds.add(key);
+
+      // Look up provider config for richer model info if available
+      const providerConfig = providers?.[provider];
+      const providerModel = providerConfig?.models?.find((m: Record<string, unknown>) => m.id === modelId);
       result.push({
-        id: m.id,
-        provider: providerId,
-        description: m.name as string | undefined,
+        id: modelId,
+        provider,
+        description: providerModel?.name as string | undefined,
         baseUrl: providerConfig?.baseUrl,
         apiKey: typeof providerConfig?.apiKey === "string" ? providerConfig.apiKey : undefined,
-        api: (m.api ?? providerConfig?.api) as ClawMatrixConfig["models"][0]["api"],
-        contextWindow: m.contextWindow as number | undefined,
-        maxTokens: m.maxTokens as number | undefined,
-        reasoning: m.reasoning as boolean | undefined,
-        input: m.input as ("text" | "image")[] | undefined,
-        cost: m.cost as { input: number; output: number; cacheRead: number; cacheWrite: number } | undefined,
-        compat: m.compat as ClawMatrixConfig["models"][0]["compat"],
+        api: (providerModel?.api ?? providerConfig?.api) as ClawMatrixConfig["models"][0]["api"],
+        contextWindow: providerModel?.contextWindow as number | undefined,
+        maxTokens: providerModel?.maxTokens as number | undefined,
+        reasoning: providerModel?.reasoning as boolean | undefined,
+        input: providerModel?.input as ("text" | "image")[] | undefined,
       });
     }
   }
 
   if (result.length > 0) {
-    console.debug(`[clawmatrix] Auto-discovered ${result.length} model(s) from models.providers: ${result.map((m) => `${m.provider}/${m.id}`).join(", ")}`);
+    debug("models", `Auto-discovered ${result.length} model(s): ${result.map((m) => `${m.provider}/${m.id}`).join(", ")}`);
   }
 
   return result;
@@ -80,6 +135,8 @@ const plugin = {
   },
 
   register(api: OpenClawPluginApi) {
+    initDebugLogger(api.logger);
+
     let config: ReturnType<typeof parseConfig>;
     try {
       config = parseConfig(api.pluginConfig);
@@ -89,9 +146,33 @@ const plugin = {
       return;
     }
 
-    // Auto-discover models from agents.defaults.models if no explicit models configured
-    if (config.models.length === 0) {
-      config = { ...config, models: discoverModels(api.config, config) };
+    // Auto-discover models from OpenClaw providers and merge with explicit config
+    {
+      const discovered = discoverModels(api.config, config);
+      if (discovered.length > 0) {
+        // Merge: add discovered models not already explicitly configured
+        const existingIds = new Set(config.models.map((m) => `${m.provider}/${m.id}`));
+        const newModels = discovered.filter((m) => !existingIds.has(`${m.provider}/${m.id}`));
+        if (newModels.length > 0) {
+          config = { ...config, models: [...config.models, ...newModels] };
+        }
+      }
+
+      // Filter out models that have no direct API endpoint — these rely on OpenClaw's
+      // internal API key management and cannot be served to remote cluster nodes.
+      // Without this filter, remote nodes discover and try to use these models via
+      // model_req, only to get "No direct API endpoint configured" errors.
+      const openclawProviders = ((api.config as Record<string, unknown>).models as { providers?: Record<string, { baseUrl?: string }> } | undefined)?.providers;
+      const servable = config.models.filter((m) => {
+        if (m.baseUrl) return true;
+        if (openclawProviders?.[m.provider]?.baseUrl) return true;
+        return false;
+      });
+      if (servable.length < config.models.length) {
+        const dropped = config.models.length - servable.length;
+        debug("models", `Filtered out ${dropped} model(s) without direct API endpoint (not servable to cluster)`);
+        config = { ...config, models: servable };
+      }
     }
 
     // Background service: manages mesh connections, WS listener, heartbeat
@@ -135,14 +216,86 @@ const plugin = {
     // activateSecretsRuntimeSnapshot clones config on startup & hot-reload,
     // so our injected providers get lost. There is no plugin-facing "config_reload"
     // event, so we re-patch periodically and skip when the reference hasn't changed.
+    /** Track which model IDs we injected per provider so we can remove stale ones. */
+    const injectedDiscoveredIds = new Map<string, Set<string>>(); // nodeId → Set<modelId>
+
+    /** Patch discovered (auto-discovered from peers) models into OpenClaw config.
+     *  Full sync: adds new models, removes models whose peers went offline. */
+    const patchDiscoveredProviders = (cfg: Record<string, unknown>) => {
+      try {
+        const runtime = getClusterRuntime();
+        const discovered = runtime.modelProxy.allProxyModels;
+        const models = ((cfg).models ??= {}) as Record<string, unknown>;
+        const providers = (models.providers ??= {}) as Record<string, unknown>;
+
+        // Build desired state: group discovered models by nodeId (skip static ones)
+        const desiredByNode = new Map<string, ReturnType<typeof formatModel>[]>();
+        for (const m of discovered) {
+          if (modelsByNode[m.nodeId]?.some((sm) => sm.id === m.id)) continue;
+          const arr = desiredByNode.get(m.nodeId) ?? [];
+          arr.push(formatModel(m));
+          desiredByNode.set(m.nodeId, arr);
+        }
+
+        // Remove stale: models we previously injected but are no longer discovered
+        for (const [nodeId, prevIds] of injectedDiscoveredIds) {
+          const desiredModels = desiredByNode.get(nodeId);
+          const desiredIds = new Set(desiredModels?.map((m) => m.id) ?? []);
+          const staleIds = [...prevIds].filter((id) => !desiredIds.has(id));
+          if (staleIds.length === 0) continue;
+
+          const provider = providers[nodeId] as Record<string, unknown> | undefined;
+          if (!provider) continue;
+          const providerModels = provider.models as Array<{ id: string }> | undefined;
+          if (!providerModels) continue;
+          const staleSet = new Set(staleIds);
+          provider.models = providerModels.filter((m) => !staleSet.has(m.id));
+          // If provider has no models left and is purely discovered (not in static config), remove it
+          if ((provider.models as unknown[]).length === 0 && !modelsByNode[nodeId]) {
+            delete providers[nodeId];
+          }
+        }
+
+        // Add new discovered models
+        const nextInjected = new Map<string, Set<string>>();
+        for (const [nodeId, nodeModels] of desiredByNode) {
+          const ids = new Set(nodeModels.map((m) => m.id));
+          nextInjected.set(nodeId, ids);
+
+          const existing = providers[nodeId] as Record<string, unknown> | undefined;
+          if (existing) {
+            if (!existing.apiKey) existing.apiKey = "sk-clawmatrix-proxy";
+            if (!existing.baseUrl) existing.baseUrl = baseUrl;
+            const existingModels = (existing.models ?? []) as Array<{ id: string }>;
+            const existingIds = new Set(existingModels.map((m) => m.id));
+            for (const nm of nodeModels) {
+              if (!existingIds.has(nm.id)) existingModels.push(nm);
+            }
+            existing.models = existingModels;
+          } else {
+            const apiType = nodeApiType[nodeId] ?? "openai-completions";
+            providers[nodeId] = { baseUrl, apiKey: "sk-clawmatrix-proxy", api: apiType, models: nodeModels };
+          }
+        }
+
+        // Update tracking state
+        injectedDiscoveredIds.clear();
+        for (const [k, v] of nextInjected) injectedDiscoveredIds.set(k, v);
+      } catch {
+        // Runtime not ready yet — will be patched on next cycle
+      }
+    };
+
     let lastSnapshotRef: unknown = null;
     const patchAllConfigs = () => {
       patchProviders(api.config as Record<string, unknown>);
+      patchDiscoveredProviders(api.config as Record<string, unknown>);
       try {
         const snapshot = api.runtime.config.loadConfig();
         if (snapshot && snapshot !== lastSnapshotRef) {
           lastSnapshotRef = snapshot;
           patchProviders(snapshot as Record<string, unknown>);
+          patchDiscoveredProviders(snapshot as Record<string, unknown>);
         }
       } catch {
         // Best-effort
@@ -177,8 +330,107 @@ const plugin = {
     api.registerTool(createClusterExecTool(), { optional: true });
     api.registerTool(createClusterReadTool(), { optional: true });
     api.registerTool(createClusterWriteTool(), { optional: true });
-    api.registerTool(createClusterToolTool(), { optional: true });
+    api.registerTool(createClusterEditTool(), { optional: true });
+    api.registerTool(createClusterBatchTool(), { optional: true });
     api.registerTool(createClusterEventsTool(), { optional: true });
+    api.registerTool(createClusterDiagnosticTool(), { optional: true });
+    api.registerTool(createClusterAcpTool(), { optional: true });
+    api.registerTool(createClusterTerminalTool(), { optional: true });
+    api.registerTool(createClusterToolInvokeTool(), { optional: true });
+
+    // Wire up peer approval with OpenClaw channel API
+    if (config.peerApproval.enabled) {
+      const setupApproval = () => {
+        try {
+          const runtime = getClusterRuntime();
+          const mgr = runtime.peerManager.approvalManager;
+
+          // Set channel API from OpenClaw runtime
+          const channelApi = (api.runtime as Record<string, unknown>)?.channel;
+          if (channelApi && typeof channelApi === "object") {
+            mgr.setChannelApi(channelApi as import("./peer-approval.ts").ChannelApi);
+          }
+
+          // Set gateway send function for plugin channels (e.g. feishu)
+          // Uses OpenClaw's `send` gateway method via subprocess — works for all channels
+          mgr.setGatewaySend(async (params) => {
+            const sendParams: Record<string, unknown> = {
+              to: params.to,
+              message: params.message,
+              channel: params.channel,
+              idempotencyKey: crypto.randomUUID(),
+            };
+            if (params.accountId) sendParams.accountId = params.accountId;
+            if (params.threadId) sendParams.threadId = params.threadId;
+
+            const proc = spawnProcess(
+              ["openclaw", "gateway", "call", "send", "--json", "--params", JSON.stringify(sendParams)],
+              { stdout: "pipe", stderr: "pipe" },
+            );
+            const code = await proc.exited;
+            if (code !== 0) {
+              const stderrChunks: Uint8Array[] = [];
+              if (proc.stderr) {
+                const reader = proc.stderr.getReader();
+                while (true) {
+                  const { done, value } = await reader.read();
+                  if (done) break;
+                  stderrChunks.push(value);
+                }
+              }
+              const errMsg = Buffer.concat(stderrChunks).toString("utf-8").trim();
+              throw new Error(`gateway send failed (exit ${code}): ${errMsg}`);
+            }
+          });
+
+          // Resolve notification targets:
+          // 1. Explicit ClawMatrix notifyTargets config
+          // 2. Fallback: OpenClaw exec approval forwarding config
+          // 3. Auto-detect: scan OpenClaw channels config for configured groups
+          const targets: import("./peer-approval.ts").NotifyTarget[] = [];
+          if (config.peerApproval.notifyTargets.length > 0) {
+            for (const t of config.peerApproval.notifyTargets) {
+              targets.push({ channel: t.channel, to: t.to, accountId: t.accountId, threadId: t.threadId });
+            }
+          } else {
+            // Fallback: borrow from OpenClaw exec approval forwarding config
+            const approvalsConfig = (api.config as Record<string, unknown>).approvals as
+              | { exec?: { targets?: Array<{ channel: string; to: string; accountId?: string; threadId?: string | number }> } }
+              | undefined;
+            if (approvalsConfig?.exec?.targets) {
+              for (const t of approvalsConfig.exec.targets) {
+                targets.push({ channel: t.channel, to: t.to, accountId: t.accountId, threadId: t.threadId });
+              }
+            }
+          }
+          // Auto-detect: scan OpenClaw channels config for enabled channels with groups
+          if (targets.length === 0) {
+            const channelsConfig = (api.config as Record<string, unknown>).channels as
+              Record<string, { enabled?: boolean; groups?: Record<string, unknown> }> | undefined;
+            if (channelsConfig) {
+              for (const [channelId, chConf] of Object.entries(channelsConfig)) {
+                if (!chConf || chConf.enabled === false) continue;
+                if (chConf.groups && typeof chConf.groups === "object") {
+                  // Use the first configured group as notification target
+                  const firstGroupId = Object.keys(chConf.groups)[0];
+                  if (firstGroupId) {
+                    targets.push({ channel: channelId, to: firstGroupId });
+                  }
+                }
+              }
+            }
+          }
+          if (targets.length > 0) {
+            mgr.setNotifyTargets(targets);
+          }
+        } catch (err) {
+          debug("approval", `setupApproval failed: ${err}`);
+        }
+      };
+
+      // Delay setup until service has started
+      setTimeout(setupApproval, 1000);
+    }
 
     // Gateway methods (queried by CLI via `openclaw gateway call`)
     api.registerGatewayMethod(
@@ -194,19 +446,7 @@ const plugin = {
             agents: config.agents.map((a) => ({ id: a.id, description: a.description })),
             models: config.models.map((m) => ({ id: m.id })),
             tags: config.tags,
-            peers: peers.map((p) => {
-              const status = runtime.peerManager.router.getPeerStatus(p);
-              return {
-                nodeId: p.nodeId,
-                agents: p.agents,
-                models: p.models,
-                tags: p.tags,
-                connected: status !== "unreachable",
-                status,
-                reachableVia: p.reachableVia,
-                latencyMs: p.latencyMs,
-              };
-            }),
+            peers: mergeSentinelPeers(peers, runtime),
           });
         } catch {
           respond(false, { error: "ClawMatrix service not running" });
@@ -219,22 +459,84 @@ const plugin = {
       ({ respond }: GatewayRequestHandlerOptions) => {
         try {
           const runtime = getClusterRuntime();
-          const peers = runtime.peerManager.router.getAllPeers().map((p) => {
-            const status = runtime.peerManager.router.getPeerStatus(p);
-            return {
+          const allPeers = runtime.peerManager.router.getAllPeers();
+          respond(true, mergeSentinelPeers(allPeers, runtime));
+        } catch {
+          respond(true, []);
+        }
+      },
+    );
+
+    // Peer approval gateway methods
+    api.registerGatewayMethod(
+      "clawmatrix.approval.resolve",
+      ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          const { approvalId, decision, source } = (params ?? {}) as {
+            approvalId?: string; decision?: string; source?: string;
+          };
+          if (!approvalId || !decision || (decision !== "approve" && decision !== "deny")) {
+            respond(false, { error: "Invalid params: need approvalId and decision (approve|deny)" });
+            return;
+          }
+          const resolvedBy = { source: source || `gateway:${config.nodeId}`, at: Date.now() };
+          const ok = runtime.peerManager.approvalManager.handleResponse(approvalId, decision, resolvedBy);
+          if (!ok) {
+            // Not a local pending approval — broadcast response to mesh so the
+            // originating node can resolve it (e.g. user approved from a remote Telegram)
+            runtime.peerManager.router.broadcast({
+              type: "peer_approval_res",
+              id: approvalId,
+              from: config.nodeId,
+              timestamp: Date.now(),
+              payload: { approvalId, decision },
+            } as import("./types.ts").PeerApprovalResponse);
+          }
+          respond(true, { ok: true, approvalId, decision });
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
+    api.registerGatewayMethod(
+      "clawmatrix.approval.list",
+      ({ respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          const mgr = runtime.peerManager.approvalManager;
+          respond(true, {
+            approved: mgr.getApprovedPeers(),
+            pending: mgr.getPendingApprovals().map((p) => ({
+              approvalId: p.approvalId,
               nodeId: p.nodeId,
-              agents: p.agents,
-              models: p.models,
-              tags: p.tags,
-              connected: status !== "unreachable",
-              status,
-              reachableVia: p.reachableVia,
-              latencyMs: p.latencyMs,
-            };
+              deviceInfo: p.deviceInfo,
+              createdAt: p.createdAt,
+            })),
+            denied: mgr.getDeniedPeers(),
           });
-          respond(true, peers);
         } catch {
-          respond(true, []);
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
+    api.registerGatewayMethod(
+      "clawmatrix.approval.revoke",
+      ({ params, respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          const { nodeId, source } = (params ?? {}) as { nodeId?: string; source?: string };
+          if (!nodeId) {
+            respond(false, { error: "Missing nodeId" });
+            return;
+          }
+          const resolvedBy = { source: source || `gateway:${config.nodeId}`, at: Date.now() };
+          const ok = runtime.peerManager.approvalManager.revoke(nodeId, resolvedBy);
+          respond(true, { ok, nodeId });
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
         }
       },
     );
@@ -247,6 +549,66 @@ const plugin = {
     // CLI subcommand
     api.registerCli(registerClusterCli, { commands: ["clawmatrix"] });
 
+    // Plugin command: /clawmatrix approve|deny|revoke
+    // Handles Telegram callback buttons and other chat surfaces.
+    // Plugin commands are processed before the agent, so they bypass the LLM.
+    api.registerCommand({
+      name: "clawmatrix",
+      description: "ClawMatrix cluster management (approve/deny peer requests)",
+      acceptsArgs: true,
+      requireAuth: true,
+      handler: (ctx) => {
+        const args = ctx.args?.trim();
+        if (!args) {
+          return { text: "Usage: /clawmatrix approve|deny <id> or /clawmatrix revoke <nodeId>" };
+        }
+
+        const parts = args.split(/\s+/);
+        const subCmd = parts[0]?.toLowerCase();
+        const target = parts[1];
+
+        if (!target) {
+          return { text: "Usage: /clawmatrix approve|deny <approvalId> or /clawmatrix revoke <nodeId>" };
+        }
+
+        try {
+          const runtime = getClusterRuntime();
+          const mgr = runtime.peerManager.approvalManager;
+          const resolvedBy = { source: `command:${ctx.channel}:${ctx.senderId || "unknown"}`, at: Date.now() };
+
+          if (subCmd === "approve" || subCmd === "deny") {
+            const decision = subCmd as "approve" | "deny";
+            const ok = mgr.handleResponse(target, decision, resolvedBy);
+            if (!ok) {
+              // Not local — broadcast to mesh
+              runtime.peerManager.router.broadcast({
+                type: "peer_approval_res",
+                id: target,
+                from: config.nodeId,
+                timestamp: Date.now(),
+                payload: { approvalId: target, decision },
+              } as import("./types.ts").PeerApprovalResponse);
+            }
+            return { text: `${decision === "approve" ? "\u2705" : "\u274c"} ${decision === "approve" ? "Approved" : "Denied"}: ${target}` };
+          }
+
+          if (subCmd === "approval" && parts[1] === "revoke" && parts[2]) {
+            const ok = mgr.revoke(parts[2], resolvedBy);
+            return { text: ok ? `Revoked: ${parts[2]}` : `Node not found: ${parts[2]}` };
+          }
+
+          if (subCmd === "revoke") {
+            const ok = mgr.revoke(target, resolvedBy);
+            return { text: ok ? `Revoked: ${target}` : `Node not found: ${target}` };
+          }
+
+          return { text: "Unknown subcommand. Use: approve, deny, or revoke" };
+        } catch {
+          return { text: "ClawMatrix service not running" };
+        }
+      },
+    });
+
     // Inject cluster context into agent prompts.
     //
     // Minimal-injection strategy:
@@ -277,7 +639,7 @@ const plugin = {
               `[ClawMatrix Cluster] node="${config.nodeId}"${config.tags.length ? ` tags=${config.tags.join(",")}` : ""}`,
               ...(config.agents.length > 0 ? [`Role: ${config.agents[0]!.description}`] : []),
               `${peerCount} remote peer(s) online. Use cluster_peers to see topology, agents, and models.`,
-              "Prefer cluster_exec/read/write for simple ops; cluster_handoff for complex multi-step tasks.",
+              "Prefer cluster_tool for device-specific tools (screenshot, battery, etc.); cluster_exec/read/write for file/shell ops; cluster_handoff for complex multi-step tasks.",
               "IMPORTANT: Always tell user which remote node you're targeting before calling cluster tools.",
             );
           }
@@ -344,4 +706,57 @@ function groupModelsByNode(config: ReturnType<typeof parseConfig>): Record<strin
   return result;
 }
 
+/** Merge sentinel peers into their main node entry (hides `:sentinel` suffix). */
+function mergeSentinelPeers(
+  allPeers: import("./router.ts").RouteEntry[],
+  runtime: import("./cluster-service.ts").ClusterRuntime,
+) {
+  const result: Record<string, unknown>[] = [];
+  const sentinelMap = new Map<string, typeof allPeers[number]>();
+
+  for (const p of allPeers) {
+    if (p.nodeId.endsWith(":sentinel")) {
+      sentinelMap.set(p.nodeId.replace(/:sentinel$/, ""), p);
+    }
+  }
+
+  const seen = new Set<string>();
+  for (const p of allPeers) {
+    if (p.nodeId.endsWith(":sentinel")) continue;
+    seen.add(p.nodeId);
+    const status = runtime.peerManager.router.getPeerStatus(p);
+    const sentinel = sentinelMap.get(p.nodeId);
+    const sentinelStatus = sentinel ? runtime.peerManager.router.getPeerStatus(sentinel) : undefined;
+    result.push({
+      nodeId: p.nodeId,
+      agents: p.agents,
+      models: p.models,
+      tags: p.tags,
+      connected: status !== "unreachable",
+      status,
+      reachableVia: p.reachableVia,
+      latencyMs: p.latencyMs,
+      ...(sentinel ? { sentinel: sentinelStatus === "direct" || sentinelStatus === "relay" ? "online" : "offline" } : {}),
+    });
+  }
+
+  // Sentinel-only: main node gone but sentinel alive
+  for (const [mainId, sentinel] of sentinelMap) {
+    if (seen.has(mainId)) continue;
+    const sentinelStatus = runtime.peerManager.router.getPeerStatus(sentinel);
+    result.push({
+      nodeId: mainId,
+      agents: [],
+      models: [],
+      tags: [],
+      connected: false,
+      status: "unreachable",
+      latencyMs: sentinel.latencyMs,
+      sentinel: sentinelStatus === "direct" || sentinelStatus === "relay" ? "online" : "offline",
+    });
+  }
+
+  return result;
+}
+
 export default plugin;