@desplega.ai/agent-swarm 1.79.0 → 1.79.2

package/src/tests/telemetry-init.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import {
   _getInstallationIdForTests,
   _resetTelemetryStateForTests,
+  _resolveCloudMode,
   initTelemetry,
   track,
 } from "../telemetry";
@@ -13,6 +14,9 @@ process.env.ANONYMIZED_TELEMETRY = "true";
 describe("initTelemetry", () => {
   beforeEach(() => {
     _resetTelemetryStateForTests();
+    // Tests below set MCP_BASE_URL to assert classification — clear between
+    // tests so cases that expect "unset" don't inherit a prior test's value.
+    delete process.env.MCP_BASE_URL;
   });
 
   test("without generateIfMissing + missing config → installationId stays null (track no-ops)", async () => {
@@ -241,4 +245,149 @@ describe("initTelemetry", () => {
     expect(_getInstallationIdForTests()).toBe(existing);
     expect(writesB).toEqual([]);
   });
+
+  describe("_resolveCloudMode (URL → is_cloud)", () => {
+    test("cloud apex host → cloud=true", () => {
+      expect(_resolveCloudMode("https://agent-swarm-mcp.desplega.sh")).toEqual({ isCloud: true });
+      expect(_resolveCloudMode("https://api.agent-swarm.dev")).toEqual({ isCloud: true });
+      expect(_resolveCloudMode("https://agent-swarm.dev")).toEqual({ isCloud: true });
+      // Future cloud subdomains (suffix match)
+      expect(_resolveCloudMode("https://mcp.agent-swarm.dev/")).toEqual({ isCloud: true });
+      // Trailing path / port / auth must not change the host classification
+      expect(_resolveCloudMode("https://user:tok@api.agent-swarm.dev:443/api/foo?x=1")).toEqual({
+        isCloud: true,
+      });
+      // Case-insensitive
+      expect(_resolveCloudMode("https://API.Agent-Swarm.DEV")).toEqual({ isCloud: true });
+    });
+
+    test("agent-swarm.cloud apex host → cloud=true", () => {
+      // Exact apex
+      expect(_resolveCloudMode("https://agent-swarm.cloud")).toEqual({ isCloud: true });
+      // Suffix subdomain
+      expect(_resolveCloudMode("https://api.agent-swarm.cloud")).toEqual({ isCloud: true });
+      expect(_resolveCloudMode("https://mcp.agent-swarm.cloud/")).toEqual({ isCloud: true });
+      // Trailing path / port / auth must not change classification
+      expect(_resolveCloudMode("https://user:tok@api.agent-swarm.cloud:443/api/foo?x=1")).toEqual({
+        isCloud: true,
+      });
+      // Case-insensitive
+      expect(_resolveCloudMode("https://API.Agent-Swarm.CLOUD")).toEqual({ isCloud: true });
+    });
+
+    test("self-hosted hosts → cloud=false", () => {
+      expect(_resolveCloudMode("http://localhost:3013")).toEqual({ isCloud: false });
+      expect(_resolveCloudMode("https://my-internal-mcp.example.com")).toEqual({ isCloud: false });
+      // Substring trap — must NOT be treated as cloud
+      expect(_resolveCloudMode("https://agent-swarm.dev.attacker.com")).toEqual({ isCloud: false });
+      expect(_resolveCloudMode("https://agent-swarm.cloud.attacker.com")).toEqual({
+        isCloud: false,
+      });
+      // IPv4 self-host
+      expect(_resolveCloudMode("http://127.0.0.1:3013")).toEqual({ isCloud: false });
+    });
+
+    test("bare hostname / unset / weird scheme → safe fallback", () => {
+      // Bare hostname (no scheme) — URL constructor throws
+      expect(_resolveCloudMode("agent-swarm-mcp.desplega.sh")).toEqual({ isCloud: false });
+      // Empty / undefined / null
+      expect(_resolveCloudMode(undefined)).toEqual({ isCloud: false });
+      expect(_resolveCloudMode(null)).toEqual({ isCloud: false });
+      expect(_resolveCloudMode("")).toEqual({ isCloud: false });
+      // Obvious garbage
+      expect(_resolveCloudMode("not a url")).toEqual({ isCloud: false });
+      // Weird scheme with no host component
+      expect(_resolveCloudMode("file:///tmp/foo")).toEqual({ isCloud: false });
+    });
+  });
+
+  describe("track() ships is_cloud in properties", () => {
+    const originalFetch = globalThis.fetch;
+    let captured: Record<string, unknown> | null = null;
+
+    beforeEach(() => {
+      captured = null;
+      globalThis.fetch = (async (_url: string, init?: { body?: string }) => {
+        captured = init?.body ? JSON.parse(init.body) : null;
+        return new Response(null, { status: 204 });
+      }) as typeof fetch;
+    });
+
+    afterEach(() => {
+      globalThis.fetch = originalFetch;
+      delete process.env.MCP_BASE_URL;
+    });
+
+    test("cloud MCP_BASE_URL → properties.is_cloud=true", async () => {
+      process.env.MCP_BASE_URL = "https://agent-swarm-mcp.desplega.sh";
+      await initTelemetry(
+        "worker",
+        async () => "install_cloud_test",
+        async () => {},
+      );
+
+      track({ event: "server.started", properties: { port: 3013 } });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const properties = (captured as { properties: Record<string, unknown> }).properties;
+      expect(properties.is_cloud).toBe(true);
+      // Hostname must NOT be emitted — telemetry is anonymous.
+      expect(properties.mcp_host).toBeUndefined();
+      // Caller's properties preserved alongside the cohort signal.
+      expect(properties.port).toBe(3013);
+    });
+
+    test("self-hosted MCP_BASE_URL → properties.is_cloud=false", async () => {
+      process.env.MCP_BASE_URL = "http://localhost:3013";
+      await initTelemetry(
+        "worker",
+        async () => "install_self_test",
+        async () => {},
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const properties = (captured as { properties: Record<string, unknown> }).properties;
+      expect(properties.is_cloud).toBe(false);
+      expect(properties.mcp_host).toBeUndefined();
+    });
+
+    test("missing MCP_BASE_URL → safe fallback (false)", async () => {
+      delete process.env.MCP_BASE_URL;
+      await initTelemetry(
+        "api-server",
+        async () => "install_no_url",
+        async () => {},
+      );
+
+      track({ event: "test.event", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const properties = (captured as { properties: Record<string, unknown> }).properties;
+      expect(properties.is_cloud).toBe(false);
+      expect(properties.mcp_host).toBeUndefined();
+    });
+
+    test("caller properties cannot override is_cloud", async () => {
+      // Defense-in-depth: even if a caller passes through user-supplied
+      // values, the cohort signal shipped on every event must come from
+      // initTelemetry — not from arbitrary call sites.
+      process.env.MCP_BASE_URL = "https://agent-swarm-mcp.desplega.sh";
+      await initTelemetry(
+        "worker",
+        async () => "install_override_test",
+        async () => {},
+      );
+
+      track({
+        event: "test.event",
+        properties: { is_cloud: false },
+      });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const properties = (captured as { properties: Record<string, unknown> }).properties;
+      expect(properties.is_cloud).toBe(true);
+    });
+  });
 });

package/src/tools/kv/index.ts

@@ -0,0 +1,5 @@
+export { registerKvDeleteTool } from "./kv-delete";
+export { registerKvGetTool } from "./kv-get";
+export { registerKvIncrTool } from "./kv-incr";
+export { registerKvListTool } from "./kv-list";
+export { registerKvSetTool } from "./kv-set";

package/src/tools/kv/kv-delete.ts

@@ -0,0 +1,89 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { deleteKv, getAgentById } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { KvKeySchema, KvNamespaceSchema } from "@/types";
+import { resolveNamespace } from "./resolve-namespace";
+
+function authError(namespace: string, info: { agentId: string | undefined }): string | null {
+  if (namespace.startsWith("task:page:")) {
+    return "task:page:* writes require a page-proxy request, not an MCP call";
+  }
+  if (namespace.startsWith("task:agent:")) {
+    const target = namespace.slice("task:agent:".length);
+    if (info.agentId && target === info.agentId) return null;
+    if (info.agentId) {
+      const agent = getAgentById(info.agentId);
+      if (agent?.isLead) return null;
+    }
+    return "writes to another agent's namespace require lead";
+  }
+  return null;
+}
+
+export const registerKvDeleteTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "kv-delete",
+    {
+      title: "KV Delete",
+      description:
+        "Remove a key from the swarm KV store. Returns whether a row was actually deleted. Namespace defaults to your current context.",
+      annotations: { idempotentHint: true },
+
+      inputSchema: z.object({
+        key: KvKeySchema,
+        namespace: KvNamespaceSchema.optional(),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        namespace: z.string().optional(),
+        deleted: z.boolean().optional(),
+      }),
+    },
+    async ({ key, namespace }, requestInfo) => {
+      const resolved = resolveNamespace(namespace, requestInfo);
+      if ("error" in resolved) {
+        return {
+          content: [{ type: "text", text: resolved.error }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: resolved.error,
+          },
+        };
+      }
+      const authErr = authError(resolved.namespace, { agentId: requestInfo.agentId });
+      if (authErr) {
+        return {
+          content: [{ type: "text", text: authErr }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: authErr,
+            namespace: resolved.namespace,
+          },
+        };
+      }
+      const deleted = deleteKv(resolved.namespace, key);
+      return {
+        content: [
+          {
+            type: "text",
+            text: deleted
+              ? `Deleted "${key}" from "${resolved.namespace}".`
+              : `No entry to delete at "${key}" in "${resolved.namespace}".`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: deleted ? "deleted" : "not found",
+          namespace: resolved.namespace,
+          deleted,
+        },
+      };
+    },
+  );
+};

package/src/tools/kv/kv-get.ts

@@ -0,0 +1,64 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getKv } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { KvEntrySchema, KvKeySchema, KvNamespaceSchema } from "@/types";
+import { resolveNamespace } from "./resolve-namespace";
+
+export const registerKvGetTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "kv-get",
+    {
+      title: "KV Get",
+      description:
+        "Read a key from the swarm KV store. Returns the entry or null if missing/expired. Namespace defaults to your current context (Slack thread / PR / Linear issue when invoked from a task; otherwise your agent scratchpad).",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        key: KvKeySchema.describe("KV key (≤512 chars, [a-zA-Z0-9._:/-])."),
+        namespace: KvNamespaceSchema.optional().describe(
+          "Optional explicit namespace. Defaults to the caller's contextKey.",
+        ),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        namespace: z.string().optional(),
+        entry: KvEntrySchema.nullable().optional(),
+      }),
+    },
+    async ({ key, namespace }, requestInfo) => {
+      const resolved = resolveNamespace(namespace, requestInfo);
+      if ("error" in resolved) {
+        return {
+          content: [{ type: "text", text: resolved.error }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: resolved.error,
+          },
+        };
+      }
+
+      const entry = getKv(resolved.namespace, key);
+      return {
+        content: [
+          {
+            type: "text",
+            text: entry
+              ? `Found "${key}" in "${resolved.namespace}".`
+              : `No entry for "${key}" in "${resolved.namespace}".`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: entry ? "ok" : "not found",
+          namespace: resolved.namespace,
+          entry: entry ?? null,
+        },
+      };
+    },
+  );
+};

package/src/tools/kv/kv-incr.ts

@@ -0,0 +1,116 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, incrKv, KvTypeCollisionError } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { KvEntrySchema, KvKeySchema, KvNamespaceSchema } from "@/types";
+import { resolveNamespace } from "./resolve-namespace";
+
+function authError(namespace: string, info: { agentId: string | undefined }): string | null {
+  if (namespace.startsWith("task:page:")) {
+    return "task:page:* writes require a page-proxy request, not an MCP call";
+  }
+  if (namespace.startsWith("task:agent:")) {
+    const target = namespace.slice("task:agent:".length);
+    if (info.agentId && target === info.agentId) return null;
+    if (info.agentId) {
+      const agent = getAgentById(info.agentId);
+      if (agent?.isLead) return null;
+    }
+    return "writes to another agent's namespace require lead";
+  }
+  return null;
+}
+
+export const registerKvIncrTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "kv-incr",
+    {
+      title: "KV Incr",
+      description:
+        "Atomically increment an integer KV entry. Creates the entry (set to `by`) if it doesn't exist or has expired. Fails if the existing value_type is not 'integer' (use kv-delete first if you want to switch).",
+      annotations: {},
+
+      inputSchema: z.object({
+        key: KvKeySchema,
+        by: z
+          .number()
+          .int()
+          .optional()
+          .describe("Increment (or decrement when negative). Default: 1."),
+        namespace: KvNamespaceSchema.optional(),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        namespace: z.string().optional(),
+        entry: KvEntrySchema.optional(),
+      }),
+    },
+    async ({ key, by, namespace }, requestInfo) => {
+      const resolved = resolveNamespace(namespace, requestInfo);
+      if ("error" in resolved) {
+        return {
+          content: [{ type: "text", text: resolved.error }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: resolved.error,
+          },
+        };
+      }
+      const authErr = authError(resolved.namespace, { agentId: requestInfo.agentId });
+      if (authErr) {
+        return {
+          content: [{ type: "text", text: authErr }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: authErr,
+            namespace: resolved.namespace,
+          },
+        };
+      }
+      try {
+        const entry = incrKv(resolved.namespace, key, by ?? 1);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `"${key}" now ${entry.value} in "${resolved.namespace}".`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: "ok",
+            namespace: resolved.namespace,
+            entry,
+          },
+        };
+      } catch (err) {
+        if (err instanceof KvTypeCollisionError) {
+          return {
+            content: [{ type: "text", text: err.message }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: err.message,
+              namespace: resolved.namespace,
+            },
+          };
+        }
+        const msg = err instanceof Error ? err.message : "INCR failed";
+        return {
+          content: [{ type: "text", text: msg }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: msg,
+            namespace: resolved.namespace,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/kv/kv-list.ts

@@ -0,0 +1,81 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { countKv, listKv } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { KvEntrySchema, KvNamespaceSchema } from "@/types";
+import { resolveNamespace } from "./resolve-namespace";
+
+const MAX_KV_LIST_LIMIT = 1000;
+
+export const registerKvListTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "kv-list",
+    {
+      title: "KV List",
+      description:
+        "List KV entries in the resolved namespace (optionally filtered by key prefix). Expired entries are filtered out. Pagination via limit/offset (limit capped at 1000).",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        prefix: z.string().optional().describe("Key prefix to filter on."),
+        limit: z
+          .number()
+          .int()
+          .positive()
+          .max(MAX_KV_LIST_LIMIT)
+          .optional()
+          .describe("Max entries to return (default 100, max 1000)."),
+        offset: z.number().int().nonnegative().optional(),
+        namespace: KvNamespaceSchema.optional(),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        namespace: z.string().optional(),
+        entries: z.array(KvEntrySchema).optional(),
+        total: z.number().optional(),
+      }),
+    },
+    async ({ prefix, limit, offset, namespace }, requestInfo) => {
+      const resolved = resolveNamespace(namespace, requestInfo);
+      if ("error" in resolved) {
+        return {
+          content: [{ type: "text", text: resolved.error }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: resolved.error,
+          },
+        };
+      }
+      const effectiveLimit = Math.min(limit ?? 100, MAX_KV_LIST_LIMIT);
+      const effectivePrefix = prefix && prefix.length > 0 ? prefix : undefined;
+      const entries = listKv(resolved.namespace, {
+        prefix: effectivePrefix,
+        limit: effectiveLimit,
+        offset: offset ?? 0,
+      });
+      const total = countKv(resolved.namespace, { prefix: effectivePrefix });
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              entries.length === 0
+                ? `No entries in "${resolved.namespace}".`
+                : `Found ${entries.length} of ${total} entries in "${resolved.namespace}".`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: "ok",
+          namespace: resolved.namespace,
+          entries,
+          total,
+        },
+      };
+    },
+  );
+};