shadow-claw 1.27.0 → 1.28.0

package/src/core/utils/initializeApp.test.ts

@@ -108,9 +108,35 @@ describe("initializeApp", () => {
     } as unknown as Document;
 
     const { initializeApp } = await import("./initializeApp.js");
-
     const result = await initializeApp(doc, true);
     expect(result).toBeUndefined();
     expect(doc.querySelector).not.toHaveBeenCalled();
   });
+
+  it("calls ensureAllConnections({ force: false }) on uiElement.orchestrator after whenReady", async () => {
+    const mockEnsureAllConnections = jest
+      .fn()
+      .mockResolvedValue(undefined as never);
+    const doc = {
+      querySelector: jest.fn(() => ({
+        orchestrator: {
+          ensureAllConnections: mockEnsureAllConnections,
+        },
+      })),
+      body: { appendChild: jest.fn((el) => el) },
+      createElement: jest.fn(() => ({
+        orchestrator: {
+          ensureAllConnections: mockEnsureAllConnections,
+        },
+      })),
+    } as unknown as Document;
+
+    const { initializeApp } = await import("./initializeApp.js");
+
+    const promise = initializeApp(doc, false);
+    resolveReady();
+    await promise;
+
+    expect(mockEnsureAllConnections).toHaveBeenCalledWith({ force: false });
+  });
 });

package/src/core/utils/initializeApp.ts

@@ -35,21 +35,14 @@ export async function initializeApp(
 
     await orchestratorStore.whenReady;
 
-    if (typeof window !== "undefined") {
+    if (
+      typeof window !== "undefined" &&
+      typeof uiElement.orchestrator?.ensureAllConnections === "function"
+    ) {
       try {
-        const {
-          createDefaultControlPlaneClient,
-          shouldConnectControlPlane,
-          isControlPlaneEnabledSync,
-        } = await import("./initControlPlane.js");
-
-        if (isControlPlaneEnabledSync() && shouldConnectControlPlane()) {
-          createDefaultControlPlaneClient({
-            orchestrator: uiElement.orchestrator,
-          });
-        }
+        await uiElement.orchestrator.ensureAllConnections({ force: false });
       } catch (err) {
-        console.warn("[ControlPlane] Failed to initialize:", err);
+        console.warn("[App] Failed to ensure connections on initialize:", err);
       }
     }
 

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

@@ -5,6 +5,7 @@ import {
   MCP_PROTOCOL_VERSION_2026_07_28,
   type McpTool,
 } from "./types.js";
+import { getPackageVersion } from "../utils/packageVersion.js";
 
 describe("McpServer", () => {
   function createServer(tools: McpTool[] = []) {
@@ -17,6 +18,11 @@ describe("McpServer", () => {
   }
 
   describe("server/discover", () => {
+    it("defaults version to package.json version when no version is provided", () => {
+      const server = new McpServer();
+      expect(server.serverInfo.version).toBe(getPackageVersion());
+    });
+
     it("returns discovery response with 2026-07-28 and capabilities", async () => {
       const server = createServer();
       const res = await server.handleRequest({

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

@@ -24,6 +24,7 @@ import {
   type McpToolsListResult,
   type ServerDiscoverResult,
 } from "./types.js";
+import { getPackageVersion } from "../utils/packageVersion.js";
 
 export type McpToolHandler = (
   args: Record<string, unknown>,
@@ -47,7 +48,7 @@ export class McpServer {
 
   constructor(options: McpServerOptions = {}) {
     this._name = options.name || "shadow-claw";
-    this._version = options.version || "1.25.0";
+    this._version = options.version || getPackageVersion();
     this._toolProvider = options.toolProvider;
 
     if (options.tools) {

package/src/server/mcp/tools/built-in-tools.ts

@@ -7,6 +7,8 @@
 
 import type { McpServer } from "../mcp-server.js";
 import type { McpTool } from "../types.js";
+import { broadcastPush } from "../../../subsystems/notifications/push-routes.js";
+import { getPackageVersion } from "../../utils/packageVersion.js";
 
 export const SHADOWCLAW_BUILTIN_TOOLS: McpTool[] = [
   {
@@ -130,6 +132,30 @@ export const SHADOWCLAW_BUILTIN_TOOLS: McpTool[] = [
       properties: {},
     },
   },
+  {
+    name: "shadowclaw_send_notification",
+    description:
+      "Broadcast an OS-level push notification to subscribed devices via Web Push (VAPID), or send to a specific registered client. Works even when the client browser tab is closed, asleep, or running in the background.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "Notification title (default: 'ShadowClaw').",
+        },
+        body: {
+          type: "string",
+          description: "Notification body message text.",
+        },
+        clientId: {
+          type: "string",
+          description:
+            "Target client ID, prefix, or device label of a specific client that has registered in the past. If omitted, broadcasts to all subscribed devices.",
+        },
+      },
+      required: ["body"],
+    },
+  },
 ];
 
 export function resolveTargetClientId(
@@ -444,7 +470,7 @@ export function registerBuiltInTools(
                 text: JSON.stringify(
                   {
                     server: "ShadowClaw",
-                    version: "1.25.0",
+                    version: getPackageVersion(),
                     connectedClients: clients.length,
                     status: "healthy",
                   },
@@ -456,6 +482,67 @@ export function registerBuiltInTools(
           };
         }
 
+        case "shadowclaw_send_notification":
+        case "send_notification": {
+          const body = String(args.body || "").trim();
+          if (!body) {
+            return {
+              isError: true,
+              content: [
+                {
+                  type: "text",
+                  text: "Error: Notification 'body' parameter cannot be empty.",
+                },
+              ],
+            };
+          }
+
+          const title = String(args.title || "ShadowClaw").trim();
+          const targetClientId =
+            typeof args.clientId === "string" && args.clientId.trim()
+              ? args.clientId.trim()
+              : undefined;
+
+          try {
+            const res = await broadcastPush(
+              { title, body },
+              targetClientId ? { clientId: targetClientId } : undefined,
+            );
+            const sentCount = res?.sent ?? 0;
+            const failedCount = res?.failed ?? 0;
+            let msg: string;
+
+            if (res?.notFound) {
+              msg = `Warning: No push subscriptions found for client '${targetClientId}'. Ensure push notifications were registered by this client in ShadowClaw Settings.`;
+            } else if (res?.noSubscribers) {
+              msg =
+                "Warning: Push notification broadcast completed, but no devices are currently subscribed to push notifications. Enable push notifications in ShadowClaw Settings on the client first.";
+            } else if (targetClientId) {
+              msg = `Push notification sent to client '${targetClientId}': ${sentCount} recipient(s) delivered, ${failedCount} failed.`;
+            } else {
+              msg = `Push notification broadcast sent: ${sentCount} recipient(s) delivered, ${failedCount} failed.`;
+            }
+
+            return {
+              content: [{ type: "text", text: msg }],
+              _meta: {
+                ...res,
+                ...(targetClientId ? { targetClientId } : {}),
+              },
+            };
+          } catch (err: any) {
+            return {
+              isError: true,
+              content: [
+                {
+                  type: "text",
+                  text: `Failed to send push notification: ${err.message}`,
+                },
+              ],
+            };
+          }
+        }
+
         default:
           return {
             isError: true,

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

@@ -73,6 +73,12 @@ export function createClientToolRelay(
           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, []);

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

@@ -6,6 +6,12 @@ import {
 } from "./built-in-tools.js";
 import { createClientToolRelay } from "./client-tool-relay.js";
 import { McpServer } from "../mcp-server.js";
+import {
+  openPushStore,
+  closePushStore,
+  saveSubscription,
+} from "../../../subsystems/notifications/push-store.js";
+import { getPackageVersion } from "../../utils/packageVersion.js";
 
 describe("ShadowClaw Built-in MCP Tools", () => {
   it("registers all built-in ShadowClaw control tools", () => {
@@ -35,6 +41,7 @@ describe("ShadowClaw Built-in MCP Tools", () => {
     expect(toolNames).toContain("shadowclaw_read_state");
     expect(toolNames).toContain("shadowclaw_list_tasks");
     expect(toolNames).toContain("shadowclaw_manage_backup");
+    expect(toolNames).toContain("shadowclaw_send_notification");
   });
 
   it("executes shadowclaw_list_clients", async () => {
@@ -351,6 +358,127 @@ describe("ShadowClaw Built-in MCP Tools", () => {
     if (res && "result" in res) {
       expect(res.result.content[0].text).toContain("ShadowClaw");
       expect(res.result.content[0].text).toContain("healthy");
+      const statusData = JSON.parse(res.result.content[0].text);
+      expect(statusData.version).toBe(getPackageVersion());
+    }
+  });
+
+  it("executes shadowclaw_send_notification and handles empty subscribers / validation", async () => {
+    openPushStore(":memory:");
+    try {
+      const server = new McpServer();
+      const mockControlPlane: any = {
+        getConnectedClients: jest.fn().mockReturnValue([]),
+      };
+      registerBuiltInTools(server, mockControlPlane);
+
+      // 1. Validation error on empty body
+      const resEmpty = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 16,
+        method: "tools/call",
+        params: {
+          name: "shadowclaw_send_notification",
+          arguments: { body: "" },
+        },
+      });
+      expect(resEmpty).not.toBeNull();
+      if (resEmpty && "result" in resEmpty) {
+        expect(resEmpty.result.isError).toBe(true);
+        expect(resEmpty.result.content[0].text).toContain("cannot be empty");
+      }
+
+      // 2. Broadcast with 0 subscribers returns informative warning
+      const resBroadcast = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 17,
+        method: "tools/call",
+        params: {
+          name: "shadowclaw_send_notification",
+          arguments: {
+            title: "Test Alert",
+            body: "Testing push",
+          },
+        },
+      });
+      expect(resBroadcast).not.toBeNull();
+      if (resBroadcast && "result" in resBroadcast) {
+        expect(resBroadcast.result.isError).toBeFalsy();
+        expect(resBroadcast.result.content[0].text).toContain(
+          "no devices are currently subscribed",
+        );
+      }
+
+      // 3. Alias send_notification works as well
+      const resAlias = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 18,
+        method: "tools/call",
+        params: {
+          name: "send_notification",
+          arguments: {
+            body: "Testing alias push",
+          },
+        },
+      });
+      expect(resAlias).not.toBeNull();
+      if (resAlias && "result" in resAlias) {
+        expect(resAlias.result.isError).toBeFalsy();
+        expect(resAlias.result.content[0].text).toContain(
+          "no devices are currently subscribed",
+        );
+      }
+
+      // 4. Targeted push with unknown client returns informative warning
+      const resNotFound = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 19,
+        method: "tools/call",
+        params: {
+          name: "shadowclaw_send_notification",
+          arguments: {
+            body: "Direct message",
+            clientId: "nonexistent-client-id",
+          },
+        },
+      });
+      expect(resNotFound).not.toBeNull();
+      if (resNotFound && "result" in resNotFound) {
+        expect(resNotFound.result.isError).toBeFalsy();
+        expect(resNotFound.result.content[0].text).toContain(
+          "No push subscriptions found for client 'nonexistent-client-id'",
+        );
+      }
+
+      // 5. Targeted push delivering to a registered client
+      saveSubscription({
+        endpoint: "https://fcm.googleapis.com/fcm/send/target-device",
+        keys: { p256dh: "key-target", auth: "auth-target" },
+        clientId: "client-target-55",
+        deviceLabel: "Workstation",
+      });
+
+      const resTargeted = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 20,
+        method: "tools/call",
+        params: {
+          name: "shadowclaw_send_notification",
+          arguments: {
+            body: "Direct workstation alert",
+            clientId: "client-target-55",
+          },
+        },
+      });
+      expect(resTargeted).not.toBeNull();
+      if (resTargeted && "result" in resTargeted) {
+        expect(resTargeted.result.isError).toBeFalsy();
+        expect(resTargeted.result.content[0].text).toContain(
+          "Push notification sent to client 'client-target-55'",
+        );
+      }
+    } finally {
+      closePushStore();
     }
   });
 });

package/src/server/openapi/openapi-coverage.test.ts

@@ -6,6 +6,7 @@ import { createApp } from "../app.js";
 import { createControlPlane } from "../control-plane.js";
 import { registerMcpRoutes } from "../routes/mcp.js";
 import { openApiSpec } from "./openapi-spec.js";
+import { getPackageVersion } from "../utils/packageVersion.js";
 import type { ServerConfig } from "../config.js";
 
 const REST_METHODS = new Set(["get", "post", "put", "delete", "patch"]);
@@ -105,7 +106,7 @@ describe("OpenAPI Route Coverage & Drift Guardrail", () => {
   it("should have valid OpenAPI 3.1 root metadata", () => {
     expect(openApiSpec.openapi).toBe("3.1.0");
     expect(openApiSpec.info.title).toBe("ShadowClaw API");
-    expect(openApiSpec.info.version).toBeDefined();
+    expect(openApiSpec.info.version).toBe(getPackageVersion());
     expect(openApiSpec.paths).toBeDefined();
   });
 

package/src/server/openapi/openapi-spec.ts

@@ -8,12 +8,13 @@ import { integrationPaths } from "./paths/integrations.js";
 import { proxyPaths } from "./paths/proxies.js";
 import { diagnosticPaths } from "./paths/diagnostics.js";
 import { mcpPaths } from "./paths/mcp.js";
+import { getPackageVersion } from "../utils/packageVersion.js";
 
 export const openApiSpec: OpenApiSpec = {
   openapi: "3.1.0",
   info: {
     title: "ShadowClaw API",
-    version: "1.25.0",
+    version: getPackageVersion(),
     description:
       "Official REST and streaming API specification for ShadowClaw personal AI assistant and control plane server.",
     license: {

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

@@ -38,4 +38,108 @@ export const mcpPaths: Record<string, OpenApiPathItem> = {
       },
     },
   },
+  "/.well-known/mcp": {
+    post: {
+      tags: ["Model Context Protocol"],
+      summary: "Stateless MCP Endpoint (Well-Known)",
+      description:
+        "Alternative well-known path for Stateless MCP (2026-07-28) Streamable HTTP requests.",
+      security: [{ ControlTokenAuth: [] }, { BearerAuth: [] }],
+      responses: {
+        "200": { description: "JSON-RPC response" },
+        "401": { description: "Unauthorized" },
+      },
+    },
+    get: {
+      tags: ["Model Context Protocol"],
+      summary: "MCP Server Card Discovery",
+      description: "Returns SEP-2127 MCP Server Card discovery metadata.",
+      responses: {
+        "200": {
+          description: "MCP Server Card",
+          content: { "application/json": { schema: { type: "object" } } },
+        },
+      },
+    },
+  },
+  "/.well-known/mcp.json": {
+    get: {
+      tags: ["Model Context Protocol"],
+      summary: "MCP Server Card (SEP-2127)",
+      description: "Returns SEP-2127 MCP Server Card discovery metadata.",
+      responses: {
+        "200": {
+          description: "MCP Server Card",
+          content: { "application/json": { schema: { type: "object" } } },
+        },
+      },
+    },
+  },
+  "/mcp/server-card": {
+    get: {
+      tags: ["Model Context Protocol"],
+      summary: "MCP Server Card (Canonical Endpoint)",
+      description: "Returns SEP-2127 MCP Server Card for this server.",
+      responses: {
+        "200": {
+          description: "MCP Server Card",
+          content: { "application/json": { schema: { type: "object" } } },
+        },
+      },
+    },
+  },
+  "/.well-known/ai-catalog.json": {
+    get: {
+      tags: ["Model Context Protocol"],
+      summary: "AI Catalog Discovery (SEP-2127)",
+      description: "Returns AI Catalog referencing this MCP Server Card.",
+      responses: {
+        "200": {
+          description: "AI Catalog manifest",
+          content: { "application/json": { schema: { type: "object" } } },
+        },
+      },
+    },
+  },
+  "/.well-known/mcp/servers.json": {
+    get: {
+      tags: ["Model Context Protocol"],
+      summary: "MCP Servers Manifest (Discussion #1147)",
+      description: "Returns servers manifest per Discussion #1147.",
+      responses: {
+        "200": {
+          description: "MCP servers manifest",
+          content: { "application/json": { schema: { type: "object" } } },
+        },
+      },
+    },
+  },
+  "/.well-known/oauth-protected-resource": {
+    get: {
+      tags: ["Model Context Protocol"],
+      summary: "Protected Resource Metadata (RFC 9728)",
+      description:
+        "OAuth 2.0 Protected Resource Metadata pointing clients to authorization servers.",
+      responses: {
+        "200": {
+          description: "Protected Resource Metadata",
+          content: { "application/json": { schema: { type: "object" } } },
+        },
+      },
+    },
+  },
+  "/.well-known/oauth-protected-resource.json": {
+    get: {
+      tags: ["Model Context Protocol"],
+      summary: "Protected Resource Metadata JSON (RFC 9728)",
+      description:
+        "OAuth 2.0 Protected Resource Metadata pointing clients to authorization servers.",
+      responses: {
+        "200": {
+          description: "Protected Resource Metadata",
+          content: { "application/json": { schema: { type: "object" } } },
+        },
+      },
+    },
+  },
 };

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

@@ -45,6 +45,8 @@ export const pushPaths: Record<string, OpenApiPathItem> = {
                     auth: { type: "string" },
                   },
                 },
+                clientId: { type: "string" },
+                deviceLabel: { type: "string" },
               },
             },
           },
@@ -165,6 +167,7 @@ export const pushPaths: Record<string, OpenApiPathItem> = {
               properties: {
                 title: { type: "string", default: "ShadowClaw" },
                 body: { type: "string" },
+                clientId: { type: "string" },
               },
             },
           },

package/src/server/routes/mcp.test.ts

@@ -4,6 +4,7 @@ import http from "node:http";
 import type { AddressInfo } from "node:net";
 import { registerMcpRoutes } from "./mcp.js";
 import { McpServer } from "../mcp/mcp-server.js";
+import { getPackageVersion } from "../utils/packageVersion.js";
 
 function makeHttpRequest(options: {
   method?: string;
@@ -219,6 +220,12 @@ describe("MCP Streamable HTTP Route (POST /mcp)", () => {
     });
 
     expect(res.status).toBe(401);
+    expect(res.headers["www-authenticate"]).toContain(
+      'Bearer resource_metadata="',
+    );
+    expect(res.headers["www-authenticate"]).toContain(
+      "/.well-known/oauth-protected-resource",
+    );
   });
 
   it("authenticates via Bearer Authorization header and query parameter", async () => {
@@ -301,4 +308,89 @@ describe("MCP Streamable HTTP Route (POST /mcp)", () => {
     });
     expect(resLocal.status).toBe(200);
   });
+
+  it("handles Streamable HTTP requests at POST /.well-known/mcp", async () => {
+    const res = await makeHttpRequest({
+      port,
+      path: "/.well-known/mcp",
+      method: "POST",
+      headers: {
+        "x-control-token": testToken,
+        "mcp-protocol-version": "2026-07-28",
+      },
+      body: {
+        jsonrpc: "2.0",
+        id: 101,
+        method: "server/discover",
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.data.result.serverInfo.name).toBe("shadow-claw-http-test");
+  });
+
+  it("serves MCP Server Card discovery at GET /.well-known/mcp, /.well-known/mcp.json, and /mcp/server-card", async () => {
+    for (const p of [
+      "/.well-known/mcp",
+      "/.well-known/mcp.json",
+      "/mcp/server-card",
+    ]) {
+      const res = await makeHttpRequest({
+        port,
+        path: p,
+        method: "GET",
+      });
+
+      expect(res.status).toBe(200);
+      expect(res.headers["content-type"]).toContain("application/json");
+      expect(res.data.name).toBe("shadow-claw");
+      expect(res.data.version).toBe(getPackageVersion());
+      expect(res.data.title).toBe("ShadowClaw MCP Server");
+      expect(Array.isArray(res.data.remotes)).toBe(true);
+      expect(res.data.remotes[0].type).toBe("streamable-http");
+      expect(res.data.remotes[0].supportedProtocolVersions).toContain(
+        "2026-07-28",
+      );
+    }
+  });
+
+  it("serves AI Catalog discovery at GET /.well-known/ai-catalog.json", async () => {
+    const res = await makeHttpRequest({
+      port,
+      path: "/.well-known/ai-catalog.json",
+      method: "GET",
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.headers["content-type"]).toContain("application/json");
+    expect(res.data.name).toBe("ShadowClaw AI Catalog");
+    expect(Array.isArray(res.data.servers)).toBe(true);
+  });
+
+  it("serves MCP Servers manifest at GET /.well-known/mcp/servers.json", async () => {
+    const res = await makeHttpRequest({
+      port,
+      path: "/.well-known/mcp/servers.json",
+      method: "GET",
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.headers["content-type"]).toContain("application/json");
+    expect(res.data.version).toBe("1.0");
+    expect(res.data.servers[0].name).toBe("shadow-claw");
+  });
+
+  it("serves Protected Resource Metadata at GET /.well-known/oauth-protected-resource", async () => {
+    const res = await makeHttpRequest({
+      port,
+      path: "/.well-known/oauth-protected-resource",
+      method: "GET",
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.headers["content-type"]).toContain("application/json");
+    expect(res.data.resource).toContain("/mcp");
+    expect(Array.isArray(res.data.authorization_servers)).toBe(true);
+    expect(res.data.scopes_supported).toBeUndefined();
+  });
 });