shadow-claw 1.28.0 → 1.29.0

package/src/server/mcp/tools/client-tool-relay.ts

@@ -7,8 +7,27 @@
  */
 
 import type { McpServer } from "../mcp-server.js";
-import type { McpTool, McpToolCallResult } from "../types.js";
-import { resolveTargetClientId } from "./built-in-tools.js";
+import {
+  MCP_CLIENT_TOOL_PREFIX,
+  type McpTool,
+  type McpToolCallResult,
+} from "../types.js";
+import {
+  resolveTargetClientId,
+  getDynamicSendNotificationTool,
+} from "./built-in-tools.js";
+
+function getClientRawToolName(name: string): string {
+  return name.startsWith(MCP_CLIENT_TOOL_PREFIX)
+    ? name.slice(MCP_CLIENT_TOOL_PREFIX.length)
+    : name;
+}
+
+function toClientExposedToolName(name: string): string {
+  return !name.startsWith(MCP_CLIENT_TOOL_PREFIX)
+    ? `${MCP_CLIENT_TOOL_PREFIX}${name}`
+    : name;
+}
 
 export interface ClientToolRelayOptions {
   targetClientId?: string;
@@ -51,46 +70,44 @@ export function createClientToolRelay(
             : [];
     } catch (_) {}
 
-    if (!Array.isArray(clients) || clients.length === 0) {
-      toolSupportingClientsMap.clear();
-      toolDefMap.clear();
-      return [];
-    }
-
     toolSupportingClientsMap.clear();
     toolDefMap.clear();
 
-    for (const c of clients) {
-      const cid = (c as any).clientId || (c as any).id;
-      if (!cid) continue;
-
-      try {
-        const res = await controlPlane.sendCommand(cid, "list-tools", {});
-        if (
-          res &&
-          res.success &&
-          res.data?.tools &&
-          Array.isArray(res.data.tools)
-        ) {
-          for (const t of res.data.tools) {
-            if (
-              t.name === "send_notification" ||
-              t.name.startsWith("shadowclaw_")
-            ) {
-              continue;
-            }
-            if (!toolDefMap.has(t.name)) {
-              toolDefMap.set(t.name, t);
-              toolSupportingClientsMap.set(t.name, []);
+    if (Array.isArray(clients) && clients.length > 0) {
+      for (const c of clients) {
+        const cid = (c as any).clientId || (c as any).id;
+        if (!cid) continue;
+
+        try {
+          const res = await controlPlane.sendCommand(cid, "list-tools", {});
+          if (
+            res &&
+            res.success &&
+            res.data?.tools &&
+            Array.isArray(res.data.tools)
+          ) {
+            for (const t of res.data.tools) {
+              const rawName = getClientRawToolName(t.name);
+              if (
+                rawName === "send_notification" ||
+                (rawName.startsWith("shadowclaw_") &&
+                  !rawName.startsWith("shadowclaw_client_"))
+              ) {
+                continue;
+              }
+              if (!toolDefMap.has(rawName)) {
+                toolDefMap.set(rawName, t);
+                toolSupportingClientsMap.set(rawName, []);
+              }
+              toolSupportingClientsMap.get(rawName)!.push(c);
             }
-            toolSupportingClientsMap.get(t.name)!.push(c);
           }
+        } catch (err) {
+          console.warn(
+            `[ClientToolRelay] Failed to query tools from client ${cid}:`,
+            err,
+          );
         }
-      } catch (err) {
-        console.warn(
-          `[ClientToolRelay] Failed to query tools from client ${cid}:`,
-          err,
-        );
       }
     }
 
@@ -100,8 +117,8 @@ export function createClientToolRelay(
     );
     const toolMap = new Map<string, McpTool>();
 
-    for (const [toolName, t] of toolDefMap.entries()) {
-      const supportingClients = toolSupportingClientsMap.get(toolName) || [];
+    for (const [rawToolName, t] of toolDefMap.entries()) {
+      const supportingClients = toolSupportingClientsMap.get(rawToolName) || [];
       const supportingClientIds = supportingClients
         .map((cl: any) => cl.clientId || cl.id)
         .filter(Boolean);
@@ -135,10 +152,13 @@ export function createClientToolRelay(
             : ` [Client: ${toolDefaultLabel} (${toolDefaultId.slice(0, 14)}...)]`
           : "";
 
-      toolMap.set(toolName, {
-        name: t.name,
+      const exposedName = toClientExposedToolName(rawToolName);
+
+      toolMap.set(exposedName, {
+        name: exposedName,
         description:
-          (t.description || `Relayed tool '${t.name}' from connected client.`) +
+          (t.description ||
+            `Relayed tool '${rawToolName}' from connected client.`) +
           clientNote,
         inputSchema: {
           ...existingSchema,
@@ -149,6 +169,9 @@ export function createClientToolRelay(
       });
     }
 
+    const dynamicNotifTool = getDynamicSendNotificationTool(controlPlane);
+    toolMap.set(dynamicNotifTool.name, dynamicNotifTool);
+
     cachedTools = Array.from(toolMap.values());
     cacheTime = now;
     return cachedTools;
@@ -168,6 +191,16 @@ export function createClientToolRelay(
             },
           );
         }
+        const rawName = getClientRawToolName(tool.name);
+        if (!registeredHandlers.has(rawName)) {
+          registeredHandlers.add(rawName);
+          server.registerToolHandler(
+            rawName,
+            async (args, meta, inputResponses) => {
+              return executeRelayedTool(rawName, args, meta, inputResponses);
+            },
+          );
+        }
       }
       return tools;
     });
@@ -202,7 +235,11 @@ export function createClientToolRelay(
       await discoverTools();
     }
 
-    const supportingClients = toolSupportingClientsMap.get(toolName) || [];
+    const rawToolName = getClientRawToolName(toolName);
+    const supportingClients =
+      toolSupportingClientsMap.get(rawToolName) ||
+      toolSupportingClientsMap.get(toolName) ||
+      [];
     const supportingClientIds = supportingClients
       .map((cl: any) => cl.clientId || cl.id)
       .filter(Boolean);
@@ -253,7 +290,7 @@ export function createClientToolRelay(
     }
 
     // Interactive tool handling: ask_user via MRTR
-    if (toolName === "ask_user") {
+    if (rawToolName === "ask_user" || toolName === "ask_user") {
       if (!inputResponses || !inputResponses["response"]) {
         const question =
           (args.question as string) ||
@@ -302,7 +339,7 @@ export function createClientToolRelay(
       const toolArgs = { ...args };
       delete toolArgs.clientId;
       const res = await controlPlane.sendCommand(clientId, "invoke-tool", {
-        toolName,
+        toolName: rawToolName,
         input: toolArgs,
       });
 

package/src/server/mcp/tools/mcp-tools.test.ts

@@ -36,15 +36,17 @@ describe("ShadowClaw Built-in MCP Tools", () => {
     registerBuiltInTools(server, mockControlPlane);
 
     const toolNames = SHADOWCLAW_BUILTIN_TOOLS.map((t) => t.name);
-    expect(toolNames).toContain("shadowclaw_list_clients");
-    expect(toolNames).toContain("shadowclaw_send_message");
-    expect(toolNames).toContain("shadowclaw_read_state");
-    expect(toolNames).toContain("shadowclaw_list_tasks");
-    expect(toolNames).toContain("shadowclaw_manage_backup");
-    expect(toolNames).toContain("shadowclaw_send_notification");
+    expect(toolNames).toContain("shadowclaw_server_list_clients");
+    expect(toolNames).toContain("shadowclaw_server_send_message");
+    expect(toolNames).toContain("shadowclaw_server_read_state");
+    expect(toolNames).toContain("shadowclaw_server_list_tasks");
+    expect(toolNames).toContain("shadowclaw_server_manage_backup");
+    expect(toolNames).toContain("shadowclaw_server_set_active_client");
+    expect(toolNames).toContain("shadowclaw_server_status");
+    expect(toolNames).toContain("shadowclaw_server_send_notification");
   });
 
-  it("executes shadowclaw_list_clients", async () => {
+  it("executes shadowclaw_server_list_clients", async () => {
     const server = new McpServer();
     const mockControlPlane: any = {
       getConnectedClients: jest.fn().mockReturnValue([
@@ -65,7 +67,7 @@ describe("ShadowClaw Built-in MCP Tools", () => {
       id: 1,
       method: "tools/call",
       params: {
-        name: "shadowclaw_list_clients",
+        name: "shadowclaw_server_list_clients",
         arguments: {},
       },
     });
@@ -77,6 +79,21 @@ describe("ShadowClaw Built-in MCP Tools", () => {
       expect(text).toContain("client-abc");
       expect(text).toContain("MacBook Chrome");
     }
+
+    // Legacy alias also works
+    const resAlias = await server.handleRequest({
+      jsonrpc: "2.0",
+      id: 11,
+      method: "tools/call",
+      params: {
+        name: "shadowclaw_list_clients",
+        arguments: {},
+      },
+    });
+    expect(resAlias).not.toBeNull();
+    if (resAlias && "result" in resAlias) {
+      expect(resAlias.result.content[0].text).toContain("client-abc");
+    }
   });
 
   it("executes shadowclaw_send_message to active client", async () => {
@@ -481,6 +498,60 @@ describe("ShadowClaw Built-in MCP Tools", () => {
       closePushStore();
     }
   });
+
+  it("dynamically populates clientId enum and description for shadowclaw_server_send_notification when push clients are registered", async () => {
+    openPushStore(":memory:");
+    try {
+      saveSubscription({
+        endpoint: "https://fcm.googleapis.com/fcm/send/device1",
+        keys: { p256dh: "k1", auth: "a1" },
+        clientId: "client-push-001",
+        deviceLabel: "Pixel 9 Pro",
+      });
+      saveSubscription({
+        endpoint: "https://fcm.googleapis.com/fcm/send/device2",
+        keys: { p256dh: "k2", auth: "a2" },
+        clientId: "client-push-002",
+        deviceLabel: "MacBook Air",
+      });
+
+      const server = new McpServer();
+      const mockControlPlane: any = {
+        getConnectedClients: jest.fn().mockReturnValue([]),
+      };
+      registerBuiltInTools(server, mockControlPlane);
+      const relay = createClientToolRelay(mockControlPlane);
+      relay.attachToServer(server);
+
+      const res = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 99,
+        method: "tools/list",
+      });
+
+      expect(res).not.toBeNull();
+      if (res && "result" in res) {
+        const notifTool = res.result.tools.find(
+          (t: any) => t.name === "shadowclaw_server_send_notification",
+        );
+        expect(notifTool).toBeDefined();
+        const clientIdProp = notifTool.inputSchema.properties.clientId;
+        expect(clientIdProp).toBeDefined();
+        expect(clientIdProp.enum).toEqual([
+          "client-push-001",
+          "client-push-002",
+        ]);
+        expect(clientIdProp.description).toContain(
+          "client-push-001 (Pixel 9 Pro)",
+        );
+        expect(clientIdProp.description).toContain(
+          "client-push-002 (MacBook Air)",
+        );
+      }
+    } finally {
+      closePushStore();
+    }
+  });
 });
 
 describe("Client Tool Relay", () => {
@@ -528,7 +599,9 @@ describe("Client Tool Relay", () => {
 
     // Tools list should discover relayed tool
     const tools = await server.getTools();
-    const readFileTool = tools.find((t) => t.name === "read_file");
+    const readFileTool = tools.find(
+      (t) => t.name === "shadowclaw_client_read_file",
+    );
     expect(readFileTool).toBeDefined();
     expect(readFileTool?.description).toBe("Read workspace file");
 
@@ -538,7 +611,7 @@ describe("Client Tool Relay", () => {
       id: 3,
       method: "tools/call",
       params: {
-        name: "read_file",
+        name: "shadowclaw_client_read_file",
         arguments: { path: "notes.txt" },
       },
     });
@@ -548,6 +621,21 @@ describe("Client Tool Relay", () => {
       expect(res.result.resultType).toBe("complete");
       expect(res.result.content[0].text).toContain("File content here");
     }
+
+    // Calling via unprefixed name also works as backward-compatible alias
+    const resAlias = await server.handleRequest({
+      jsonrpc: "2.0",
+      id: 31,
+      method: "tools/call",
+      params: {
+        name: "read_file",
+        arguments: { path: "notes.txt" },
+      },
+    });
+    expect(resAlias).not.toBeNull();
+    if (resAlias && "result" in resAlias) {
+      expect(resAlias.result.content[0].text).toContain("File content here");
+    }
   });
 
   it("handles ask_user interactive MRTR loop via client relay", async () => {
@@ -802,7 +890,9 @@ describe("Client Tool Relay", () => {
 
       // 1. Discover tools across multi-client: schema should have clientId enum
       const tools = await server.getTools();
-      const listFilesTool = tools.find((t) => t.name === "list_files");
+      const listFilesTool = tools.find(
+        (t) => t.name === "shadowclaw_client_list_files",
+      );
       expect(listFilesTool).toBeDefined();
       const props = listFilesTool?.inputSchema.properties as any;
       expect(props?.clientId).toBeDefined();
@@ -828,7 +918,7 @@ describe("Client Tool Relay", () => {
         id: 21,
         method: "tools/call",
         params: {
-          name: "list_files",
+          name: "shadowclaw_client_list_files",
           arguments: { clientId: "c1" },
         },
       });
@@ -843,7 +933,7 @@ describe("Client Tool Relay", () => {
         id: 22,
         method: "tools/call",
         params: {
-          name: "list_files",
+          name: "shadowclaw_client_list_files",
           arguments: {},
         },
       });

package/src/server/mcp/types.ts

@@ -19,6 +19,9 @@ export const SUPPORTED_PROTOCOL_VERSIONS = [
 export type SupportedProtocolVersion =
   (typeof SUPPORTED_PROTOCOL_VERSIONS)[number];
 
+export const MCP_CLIENT_TOOL_PREFIX = "shadowclaw_client_";
+export const MCP_SERVER_TOOL_PREFIX = "shadowclaw_server_";
+
 // Standard JSON-RPC and MCP error codes
 export const MCP_ERROR_CODES = {
   ParseError: -32700,

package/src/server/openapi/paths/push.ts

@@ -101,6 +101,54 @@ export const pushPaths: Record<string, OpenApiPathItem> = {
       },
     },
   },
+  "/push/clients": {
+    get: {
+      tags: ["Push Notifications"],
+      summary: "List Registered Push Clients",
+      description:
+        "Retrieves unique registered clients that have active Web Push subscriptions, including device labels and subscription counts.",
+      responses: {
+        "200": {
+          description: "List of registered push clients",
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  clients: {
+                    type: "array",
+                    items: {
+                      type: "object",
+                      required: ["clientId"],
+                      properties: {
+                        clientId: {
+                          type: "string",
+                          description: "Unique client ID",
+                        },
+                        deviceLabel: {
+                          type: "string",
+                          description: "Client device label",
+                        },
+                        subscriptionCount: {
+                          type: "integer",
+                          description: "Number of active push subscriptions",
+                        },
+                        lastSeen: {
+                          type: "string",
+                          description:
+                            "Timestamp of latest subscription creation",
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
   "/push/send": {
     post: {
       tags: ["Push Notifications"],

package/src/server/server.ts

@@ -2,6 +2,8 @@ import { exit } from "node:process";
 import http from "node:http";
 import https from "node:https";
 import path from "node:path";
+import fs from "node:fs";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import tcpPortUsed from "tcp-port-used";
 
@@ -116,6 +118,34 @@ export async function startServer(
         `Control plane active at ${protocol}://${config.bindHost}:${config.port}/api/control/events (SSE) and ${wsProtocol}://${config.bindHost}:${config.port}/ws/control (WebSocket)`,
       );
       console.log(`Control token: ${controlPlane.getToken()}`);
+      try {
+        const tmpDir = path.join(tmpdir(), "shadow-claw");
+        if (!fs.existsSync(tmpDir)) {
+          fs.mkdirSync(tmpDir, { recursive: true });
+        }
+        const tokenFilePayload =
+          JSON.stringify(
+            {
+              token: controlPlane.getToken(),
+              port: config.port,
+              bindHost: config.bindHost,
+              createdAt: Date.now(),
+              createdAtIso: new Date().toISOString(),
+            },
+            null,
+            2,
+          ) + "\n";
+        fs.writeFileSync(
+          path.join(tmpDir, `control-token-${config.port}.json`),
+          tokenFilePayload,
+          "utf8",
+        );
+        fs.writeFileSync(
+          path.join(tmpDir, "control-token.json"),
+          tokenFilePayload,
+          "utf8",
+        );
+      } catch (_) {}
       console.log(
         `MCP endpoint active at ${protocol}://${config.bindHost}:${config.port}/mcp`,
       );

package/src/subsystems/notifications/push-client.test.ts

@@ -187,6 +187,23 @@ describe("push-client", () => {
       expect(body.clientId).toBe("client-explicit-123");
       expect(body.deviceLabel).toBe("Pixel 9 Pro");
     });
+
+    it("automatically resolves clientId and deviceLabel if omitted", async () => {
+      (fetch as any)
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({ publicKey: "test-vapid-key" }),
+        })
+        .mockResolvedValueOnce({ ok: true });
+
+      await subscribeToPush();
+      const postCall = (fetch as any).mock.calls[1];
+      const body = JSON.parse(postCall[1].body);
+      expect(body.clientId).toBeDefined();
+      expect(typeof body.clientId).toBe("string");
+      expect(body.deviceLabel).toBeDefined();
+      expect(typeof body.deviceLabel).toBe("string");
+    });
   });
 
   describe("unsubscribeFromPush", () => {

package/src/subsystems/notifications/push-client.ts

@@ -106,12 +106,32 @@ export async function subscribeToPush(
     applicationServerKey: urlBase64ToUint8Array(publicKey) as any,
   });
 
-  const resolvedClientId =
+  let resolvedClientId =
     clientId ||
     (typeof localStorage !== "undefined"
       ? localStorage.getItem(CONFIG_KEYS.CONTROL_PLANE_CLIENT_ID) || undefined
       : undefined);
 
+  let resolvedDeviceLabel = deviceLabel;
+
+  if (!resolvedClientId || !resolvedDeviceLabel) {
+    try {
+      const initCp = await import("../../core/utils/initControlPlane.js");
+      if (
+        !resolvedClientId &&
+        typeof initCp.getOrCreateControlPlaneClientId === "function"
+      ) {
+        resolvedClientId = initCp.getOrCreateControlPlaneClientId();
+      }
+      if (
+        !resolvedDeviceLabel &&
+        typeof initCp.detectDeviceLabel === "function"
+      ) {
+        resolvedDeviceLabel = initCp.detectDeviceLabel();
+      }
+    } catch (_) {}
+  }
+
   const subJson =
     typeof subscription.toJSON === "function"
       ? subscription.toJSON()
@@ -126,7 +146,7 @@ export async function subscribeToPush(
       body: JSON.stringify({
         ...subJson,
         ...(resolvedClientId ? { clientId: resolvedClientId } : {}),
-        ...(deviceLabel ? { deviceLabel } : {}),
+        ...(resolvedDeviceLabel ? { deviceLabel: resolvedDeviceLabel } : {}),
       }),
     }),
   );

package/src/subsystems/notifications/push-routes.test.ts

@@ -25,6 +25,7 @@ jest.unstable_mockModule("./push-store.js", () => ({
   getAllSubscriptions: jest.fn(() => []),
   getSubscriptionsByClientId: jest.fn(() => []),
   findSubscriptionsForClient: jest.fn(() => []),
+  getRegisteredPushClients: jest.fn(() => []),
 }));
 
 const { registerPushRoutes, broadcastPush } = await import("./push-routes.js");
@@ -179,6 +180,36 @@ describe("push-routes", () => {
     });
   });
 
+  describe("GET /push/clients", () => {
+    it("registers the route", () => {
+      expect(app.routes.get["/push/clients"]).toBeDefined();
+    });
+
+    it("returns registered push clients", async () => {
+      (store.getRegisteredPushClients as any).mockReturnValue([
+        {
+          clientId: "client-abc",
+          deviceLabel: "Mac Chrome",
+          subscriptionCount: 1,
+          lastSeen: "2026-09-01",
+        },
+      ]);
+      const req = createMockReq();
+      const res = createMockRes();
+      await app.routes.get["/push/clients"](req, res);
+      expect(res._json).toEqual({
+        clients: [
+          {
+            clientId: "client-abc",
+            deviceLabel: "Mac Chrome",
+            subscriptionCount: 1,
+            lastSeen: "2026-09-01",
+          },
+        ],
+      });
+    });
+  });
+
   describe("POST /push/send", () => {
     it("registers the route", () => {
       expect(app.routes.post["/push/send"]).toBeDefined();

package/src/subsystems/notifications/push-routes.ts

@@ -16,10 +16,14 @@ import {
   getSubscription,
   getAllSubscriptions,
   findSubscriptionsForClient,
+  getRegisteredPushClients,
   type PushSubscriptionRow,
+  type PushClientRecord,
 } from "./push-store.js";
 import type { Express } from "express";
 
+export { getRegisteredPushClients, type PushClientRecord };
+
 export interface BroadcastPushOptions {
   clientId?: string;
 }
@@ -159,6 +163,12 @@ export function registerPushRoutes(app: Express): void {
     res.json(subs);
   });
 
+  // List unique registered clients with push subscriptions
+  app.get("/push/clients", (_req, res) => {
+    const clients = getRegisteredPushClients();
+    res.json({ clients });
+  });
+
   // Send a notification to a specific subscription
   app.post("/push/send", async (req, res) => {
     const { endpoint, payload } = req.body || {};

package/src/subsystems/notifications/push-store.test.ts

@@ -9,6 +9,7 @@ import {
   removeSubscriptionById,
   getSubscriptionsByClientId,
   findSubscriptionsForClient,
+  getRegisteredPushClients,
 } from "./push-store.js";
 
 // Use in-memory DB for tests
@@ -207,4 +208,52 @@ describe("push-store", () => {
       expect(notFound).toHaveLength(0);
     });
   });
+
+  describe("getRegisteredPushClients", () => {
+    it("returns empty array when no subscriptions exist", () => {
+      expect(getRegisteredPushClients()).toEqual([]);
+    });
+
+    it("returns deduplicated registered push clients with device labels and counts", () => {
+      saveSubscription({
+        ...MOCK_SUBSCRIPTION,
+        clientId: "client-01jtest123",
+        deviceLabel: "Pixel 9 Pro",
+      });
+      // Second subscription from same client (e.g. renewed endpoint)
+      saveSubscription({
+        endpoint: "https://fcm.googleapis.com/fcm/send/abc123-renewed",
+        keys: MOCK_SUBSCRIPTION.keys,
+        clientId: "client-01jtest123",
+        deviceLabel: "Pixel 9 Pro",
+      });
+      // Different client
+      saveSubscription({
+        ...MOCK_SUBSCRIPTION_2,
+        clientId: "client-02ktest456",
+        deviceLabel: "MacBook Air",
+      });
+
+      const clients = getRegisteredPushClients();
+      expect(clients).toHaveLength(2);
+
+      const client1 = clients.find((c) => c.clientId === "client-01jtest123");
+      expect(client1).toBeDefined();
+      expect(client1?.deviceLabel).toBe("Pixel 9 Pro");
+      expect(client1?.subscriptionCount).toBe(2);
+
+      const client2 = clients.find((c) => c.clientId === "client-02ktest456");
+      expect(client2).toBeDefined();
+      expect(client2?.deviceLabel).toBe("MacBook Air");
+      expect(client2?.subscriptionCount).toBe(1);
+    });
+
+    it("falls back to subscription id when clientId is omitted", () => {
+      saveSubscription(MOCK_SUBSCRIPTION);
+      const clients = getRegisteredPushClients();
+      expect(clients).toHaveLength(1);
+      const all = getAllSubscriptions();
+      expect(clients[0].clientId).toBe(String(all[0].id));
+    });
+  });
 });