@desplega.ai/agent-swarm 1.83.2 → 1.84.0

package/src/tests/kapso-client.test.ts

@@ -0,0 +1,94 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { sendKapsoText } from "../integrations/kapso/client";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+function mockFetch(status: number, body: unknown) {
+  globalThis.fetch = (async () =>
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { "Content-Type": "application/json" },
+    })) as typeof fetch;
+}
+
+describe("sendKapsoText", () => {
+  test("success → returns outbound wamid", async () => {
+    let captured: { url: string; body: unknown } | null = null;
+    globalThis.fetch = (async (url: string, init: RequestInit) => {
+      captured = { url, body: JSON.parse(init.body as string) };
+      return new Response(JSON.stringify({ messages: [{ id: "wamid.OUT123" }] }), { status: 200 });
+    }) as typeof fetch;
+
+    const result = await sendKapsoText({
+      apiBaseUrl: "https://api.kapso.ai",
+      apiKey: "k",
+      phoneNumberId: "1035039933036854",
+      to: "34679077777",
+      body: "hola",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.messageId).toBe("wamid.OUT123");
+    expect(captured!.url).toBe(
+      "https://api.kapso.ai/meta/whatsapp/v24.0/1035039933036854/messages",
+    );
+    expect(captured!.body).toMatchObject({
+      messaging_product: "whatsapp",
+      to: "34679077777",
+      type: "text",
+      text: { body: "hola", preview_url: false },
+    });
+  });
+
+  test("quote-reply sets context.message_id", async () => {
+    let body: Record<string, unknown> | null = null;
+    globalThis.fetch = (async (_url: string, init: RequestInit) => {
+      body = JSON.parse(init.body as string);
+      return new Response(JSON.stringify({ messages: [{ id: "wamid.R" }] }), { status: 200 });
+    }) as typeof fetch;
+
+    await sendKapsoText({
+      apiBaseUrl: "https://api.kapso.ai",
+      apiKey: "k",
+      phoneNumberId: "p",
+      to: "34679077777",
+      body: "re",
+      contextMessageId: "wamid.IN999",
+    });
+
+    expect(body!.context).toEqual({ message_id: "wamid.IN999" });
+  });
+
+  test("24h-window error (code 131047) → sessionWindowExpired", async () => {
+    mockFetch(400, {
+      error: { code: 131047, message: "Message failed: more than 24 hours since last reply" },
+    });
+    const result = await sendKapsoText({
+      apiBaseUrl: "https://api.kapso.ai",
+      apiKey: "k",
+      phoneNumberId: "p",
+      to: "34679077777",
+      body: "late",
+    });
+    expect(result.ok).toBe(false);
+    expect(result.sessionWindowExpired).toBe(true);
+  });
+
+  test("generic error → not flagged as session-window", async () => {
+    mockFetch(401, { error: { code: 0, message: "Invalid API key" } });
+    const result = await sendKapsoText({
+      apiBaseUrl: "https://api.kapso.ai",
+      apiKey: "bad",
+      phoneNumberId: "p",
+      to: "34679077777",
+      body: "x",
+    });
+    expect(result.ok).toBe(false);
+    expect(result.sessionWindowExpired).toBe(false);
+    expect(result.errorMessage).toContain("Invalid API key");
+  });
+});

package/src/tests/kapso-inbound.test.ts

@@ -0,0 +1,198 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import crypto from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { closeDb, createAgent, getTaskById, initDb } from "../be/db";
+import { handleWebhooks } from "../http/webhooks";
+import { putKapsoNumberMapping } from "../integrations/kapso/config";
+import { routeKapsoInbound } from "../integrations/kapso/inbound";
+
+const TEST_DB_PATH = "./test-kapso-inbound.sqlite";
+const HMAC_SECRET = "kapso-test-hmac-secret";
+
+let agentId: string;
+
+function makePayload(opts: {
+  phoneNumberId: string;
+  messageId?: string;
+  direction?: string;
+  type?: string;
+  text?: string;
+  from?: string;
+  conversationId?: string;
+}) {
+  return {
+    message: {
+      id: opts.messageId ?? `wamid.${Math.random().toString(36).slice(2)}`,
+      from: opts.from ?? "34679077777",
+      type: opts.type ?? "text",
+      text: { body: opts.text ?? "hola" },
+      kapso: { direction: opts.direction ?? "inbound", content: opts.text ?? "hola" },
+    },
+    conversation: {
+      id: opts.conversationId ?? "conv-1",
+      phone_number: opts.from ?? "34679077777",
+      contact_name: "Taras",
+    },
+    phone_number_id: opts.phoneNumberId,
+  };
+}
+
+function sign(secret: string, body: string): string {
+  return crypto.createHmac("sha256", secret).update(body).digest("hex");
+}
+
+/** Minimal fake req/res to drive handleWebhooks without a live server. */
+function fakeReqRes(rawBody: string, headers: Record<string, string>) {
+  const req = {
+    method: "POST",
+    headers,
+    async *[Symbol.asyncIterator]() {
+      yield Buffer.from(rawBody);
+    },
+  } as unknown as IncomingMessage;
+
+  const captured = { status: 0, body: "" };
+  const res = {
+    writeHead(status: number) {
+      captured.status = status;
+      return this;
+    },
+    end(chunk?: string) {
+      if (chunk) captured.body = chunk;
+      return this;
+    },
+  } as unknown as ServerResponse;
+
+  return { req, res, captured };
+}
+
+const KAPSO_PATH = ["api", "integrations", "kapso", "webhook"];
+
+beforeAll(() => {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      require("node:fs").unlinkSync(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+  initDb(TEST_DB_PATH);
+  process.env.KAPSO_WEBHOOK_HMAC_SECRET = HMAC_SECRET;
+  const agent = createAgent({ name: "KapsoWorker", isLead: false, status: "idle" });
+  agentId = agent.id;
+});
+
+afterAll(() => {
+  closeDb();
+  delete process.env.KAPSO_WEBHOOK_HMAC_SECRET;
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      require("node:fs").unlinkSync(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+});
+
+describe("routeKapsoInbound", () => {
+  test("mapping hit → dispatches a kapso-inbound task to the mapped agent", () => {
+    putKapsoNumberMapping({
+      phoneNumberId: "pn-task",
+      agentId,
+      createdAt: new Date().toISOString(),
+    });
+    const routing = routeKapsoInbound(makePayload({ phoneNumberId: "pn-task" }));
+    expect(routing.kind).toBe("task");
+    if (routing.kind !== "task") throw new Error("expected task");
+    const task = getTaskById(routing.taskId);
+    expect(task).not.toBeNull();
+    expect(task!.taskType).toBe("kapso-inbound");
+    expect(task!.agentId).toBe(agentId);
+    expect(task!.task).toContain("## Source: WhatsApp (Kapso)");
+  });
+
+  test("no mapping → no_mapping (does not break, no task)", () => {
+    const routing = routeKapsoInbound(makePayload({ phoneNumberId: "pn-unregistered" }));
+    expect(routing.kind).toBe("no_mapping");
+  });
+
+  test("workflow mapping → signals workflow dispatch", () => {
+    putKapsoNumberMapping({
+      phoneNumberId: "pn-wf",
+      workflowId: "11111111-1111-4111-8111-111111111111",
+      createdAt: new Date().toISOString(),
+    });
+    const routing = routeKapsoInbound(makePayload({ phoneNumberId: "pn-wf" }));
+    expect(routing.kind).toBe("workflow");
+    if (routing.kind !== "workflow") throw new Error("expected workflow");
+    expect(routing.workflowId).toBe("11111111-1111-4111-8111-111111111111");
+  });
+
+  test("non-inbound (outbound/status) → skip", () => {
+    const routing = routeKapsoInbound(
+      makePayload({ phoneNumberId: "pn-task", direction: "outbound" }),
+    );
+    expect(routing.kind).toBe("skip");
+  });
+
+  test("duplicate delivery of the same message id → second is deduped", () => {
+    putKapsoNumberMapping({
+      phoneNumberId: "pn-dup",
+      agentId,
+      createdAt: new Date().toISOString(),
+    });
+    const messageId = "wamid.DUPLICATE_TEST";
+    const first = routeKapsoInbound(makePayload({ phoneNumberId: "pn-dup", messageId }));
+    expect(first.kind).toBe("task");
+    const second = routeKapsoInbound(makePayload({ phoneNumberId: "pn-dup", messageId }));
+    expect(second.kind).toBe("duplicate");
+  });
+});
+
+describe("handleWebhooks — Kapso HMAC gate", () => {
+  test("valid HMAC + mapping hit → 200 and task routing", async () => {
+    putKapsoNumberMapping({
+      phoneNumberId: "pn-http",
+      agentId,
+      createdAt: new Date().toISOString(),
+    });
+    const rawBody = JSON.stringify(
+      makePayload({ phoneNumberId: "pn-http", messageId: "wamid.HTTP_OK" }),
+    );
+    const { req, res, captured } = fakeReqRes(rawBody, {
+      "x-webhook-signature": sign(HMAC_SECRET, rawBody),
+    });
+    const handled = await handleWebhooks(req, res, KAPSO_PATH);
+    expect(handled).toBe(true);
+    expect(captured.status).toBe(200);
+    expect(JSON.parse(captured.body)).toMatchObject({ received: true, routing: "task" });
+  });
+
+  test("valid HMAC + no mapping → 200 no_mapping (fallback, does not break)", async () => {
+    const rawBody = JSON.stringify(
+      makePayload({ phoneNumberId: "pn-http-unmapped", messageId: "wamid.HTTP_NOMAP" }),
+    );
+    const { req, res, captured } = fakeReqRes(rawBody, {
+      "x-webhook-signature": sign(HMAC_SECRET, rawBody),
+    });
+    await handleWebhooks(req, res, KAPSO_PATH);
+    expect(captured.status).toBe(200);
+    expect(JSON.parse(captured.body)).toMatchObject({ routing: "no_mapping" });
+  });
+
+  test("invalid HMAC → 401", async () => {
+    const rawBody = JSON.stringify(
+      makePayload({ phoneNumberId: "pn-http", messageId: "wamid.HTTP_BAD" }),
+    );
+    const { req, res, captured } = fakeReqRes(rawBody, {
+      "x-webhook-signature": sign("wrong-secret", rawBody),
+    });
+    await handleWebhooks(req, res, KAPSO_PATH);
+    expect(captured.status).toBe(401);
+  });
+
+  test("missing signature → 401", async () => {
+    const rawBody = JSON.stringify(
+      makePayload({ phoneNumberId: "pn-http", messageId: "wamid.HTTP_NOSIG" }),
+    );
+    const { req, res, captured } = fakeReqRes(rawBody, {});
+    await handleWebhooks(req, res, KAPSO_PATH);
+    expect(captured.status).toBe(401);
+  });
+});

package/src/tests/tool-annotations.test.ts

@@ -323,9 +323,10 @@ describe("Tool Annotations & Classification", () => {
   test("registered tool count matches expected total", () => {
     const count = Object.keys(tools).length;
     // We expect all tools to be registered when all capabilities are enabled (default)
-    // Includes 11 skill tools, 7 MCP server tools, and reusable script tools
+    // Includes 11 skill tools, 7 MCP server tools, reusable script tools, and the
+    // native Kapso/WhatsApp tools (register/unregister number + send/reply message).
     expect(count).toBeGreaterThanOrEqual(45);
-    expect(count).toBeLessThanOrEqual(100);
+    expect(count).toBeLessThanOrEqual(120);
   });
 
   test("core tools are fewer than deferred tools", () => {

package/src/tools/register-kapso-number.ts

@@ -0,0 +1,210 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getLeadAgent } from "@/be/db";
+import { registerKapsoWebhook } from "@/integrations/kapso/client";
+import {
+  deleteKapsoNumberMapping,
+  getKapsoConfig,
+  getKapsoNumberMapping,
+  type KapsoNumberMapping,
+  putKapsoNumberMapping,
+} from "@/integrations/kapso/config";
+import { createToolRegistrar } from "@/tools/utils";
+
+/** Build the native inbound webhook URL the swarm exposes for Kapso deliveries. */
+function nativeWebhookUrl(): string {
+  const base = (
+    process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`
+  ).replace(/\/+$/, "");
+  return `${base}/api/integrations/kapso/webhook`;
+}
+
+export const registerRegisterKapsoNumberTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "register-kapso-number",
+    {
+      title: "Register Kapso WhatsApp Number",
+      annotations: { idempotentHint: true, openWorldHint: true },
+      description:
+        "Provision a Kapso WhatsApp phone number for native inbound routing. Lead-only. Points the number's Kapso webhook at the swarm's native handler (signed with KAPSO_WEBHOOK_HMAC_SECRET) and stores a KV mapping so inbound messages route to an agent (defaults to the lead, or a workflow if workflowId is given). Returns the stored mapping + the registered webhook URL.",
+      inputSchema: z.object({
+        phoneNumberId: z
+          .string()
+          .min(1)
+          .describe("Kapso/Meta phone-number ID to provision (KAPSO_PHONE_NUMBER_ID)."),
+        agentId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe(
+            "Agent to route inbound messages to as a `kapso-inbound` task. Defaults to the lead agent when omitted.",
+          ),
+        workflowId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe(
+            "Advanced override: dispatch inbound via this workflow's webhook trigger instead of a task.",
+          ),
+        name: z.string().optional().describe("Human-friendly display name for the number."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        webhookUrl: z.string().optional(),
+        webhookRegistered: z.boolean().optional(),
+        mapping: z
+          .object({
+            phoneNumberId: z.string(),
+            agentId: z.string().optional(),
+            workflowId: z.string().optional(),
+            name: z.string().optional(),
+            createdAt: z.string(),
+          })
+          .optional(),
+      }),
+    },
+    async ({ phoneNumberId, agentId, workflowId, name }, requestInfo) => {
+      try {
+        // Lead-only: provisioning a number rewires inbound routing for the
+        // whole swarm, so restrict it to the lead agent.
+        const callerAgent = requestInfo.agentId ? getAgentById(requestInfo.agentId) : null;
+        if (!callerAgent?.isLead) {
+          const msg = "Permission denied. Only the lead can register a Kapso number.";
+          return {
+            content: [{ type: "text", text: msg }],
+            structuredContent: { yourAgentId: requestInfo.agentId, success: false, message: msg },
+          };
+        }
+
+        // Default the routing target to the lead when no agent/workflow is given.
+        const ownerAgentId = agentId ?? (workflowId ? undefined : getLeadAgent()?.id);
+
+        const config = getKapsoConfig();
+        const webhookUrl = nativeWebhookUrl();
+
+        // Best-effort: point the Kapso webhook at our native handler. The KV
+        // mapping (the durable routing record the inbound handler reads) is
+        // written regardless, so a manually-configured number still routes.
+        let webhookRegistered = false;
+        let webhookNote = "";
+        if (!config.apiKey) {
+          webhookNote =
+            " (KAPSO_API_KEY not configured — skipped provider webhook registration; configure the webhook in the Kapso dashboard)";
+        } else {
+          const result = await registerKapsoWebhook({
+            apiBaseUrl: config.apiBaseUrl,
+            apiKey: config.apiKey,
+            phoneNumberId,
+            webhookUrl,
+            secret: config.webhookHmacSecret,
+          });
+          webhookRegistered = result.ok;
+          if (!result.ok) {
+            webhookNote = ` (provider webhook registration failed: ${result.errorMessage})`;
+          } else if (result.alreadyRegistered) {
+            webhookNote = " (webhook already registered — skipped re-creation)";
+          }
+        }
+
+        const mapping: KapsoNumberMapping = {
+          phoneNumberId,
+          ...(ownerAgentId ? { agentId: ownerAgentId } : {}),
+          ...(workflowId ? { workflowId } : {}),
+          ...(name ? { name } : {}),
+          createdAt: new Date().toISOString(),
+        };
+        putKapsoNumberMapping(mapping);
+
+        const text = `Registered Kapso number ${phoneNumberId} → ${
+          workflowId
+            ? `workflow ${workflowId}`
+            : ownerAgentId
+              ? `agent ${ownerAgentId}`
+              : "task pool"
+        }${webhookNote}`;
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: text,
+            webhookUrl,
+            webhookRegistered,
+            mapping,
+          },
+        };
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${errorMessage}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: errorMessage,
+          },
+        };
+      }
+    },
+  );
+};
+
+export const registerUnregisterKapsoNumberTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "unregister-kapso-number",
+    {
+      title: "Unregister Kapso WhatsApp Number",
+      annotations: { idempotentHint: true },
+      description:
+        "Remove a Kapso phone number's native routing mapping from the KV store. Lead-only. Inbound messages for the number stop routing through the native handler. The Kapso-side webhook is not deleted automatically — remove it in the Kapso dashboard if you want deliveries to stop.",
+      inputSchema: z.object({
+        phoneNumberId: z
+          .string()
+          .min(1)
+          .describe("Kapso/Meta phone-number ID whose mapping should be removed."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async ({ phoneNumberId }, requestInfo) => {
+      try {
+        const callerAgent = requestInfo.agentId ? getAgentById(requestInfo.agentId) : null;
+        if (!callerAgent?.isLead) {
+          const msg = "Permission denied. Only the lead can unregister a Kapso number.";
+          return {
+            content: [{ type: "text", text: msg }],
+            structuredContent: { yourAgentId: requestInfo.agentId, success: false, message: msg },
+          };
+        }
+
+        const existing = getKapsoNumberMapping(phoneNumberId);
+        const deleted = deleteKapsoNumberMapping(phoneNumberId);
+        const text = existing
+          ? `Unregistered Kapso number ${phoneNumberId}`
+          : `No mapping found for Kapso number ${phoneNumberId}`;
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: deleted,
+            message: text,
+          },
+        };
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${errorMessage}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: errorMessage,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/templates.ts

@@ -7,6 +7,41 @@
 
 import { registerTemplate } from "../prompts/registry";
 
+// ============================================================================
+// Kapso/WhatsApp inbound (native handler creates a kapso-inbound task)
+// ============================================================================
+
+registerTemplate({
+  eventType: "kapso.message.received",
+  header: "",
+  defaultBody: `# WhatsApp inbound (Kapso)
+
+A Kapso webhook fired on the swarm's provisioned WhatsApp number. Load the \`kapso-whatsapp\` skill, then triage this like any other interaction and reply on WhatsApp by quote-replying the inbound WAMID (\`context.message_id\`).
+
+## Source: WhatsApp (Kapso)
+- conversation_id: {{conversation_id}}
+- inbound_wamid: {{inbound_wamid}}
+- sender_phone: {{sender_phone}}
+- contact_name: {{contact_name}}
+- phone_number_id: {{phone_number_id}}{{test_note}}
+
+## Message
+{{message_text}}`,
+  variables: [
+    { name: "conversation_id", description: "Kapso conversation id, or 'unknown'" },
+    { name: "inbound_wamid", description: "Inbound message WAMID, or 'unknown'" },
+    { name: "sender_phone", description: "Sender phone (E.164 no +), or 'unknown'" },
+    { name: "contact_name", description: "Contact display name, or 'unknown'" },
+    { name: "phone_number_id", description: "Provisioned phone-number id, or 'unknown'" },
+    {
+      name: "test_note",
+      description: "Appended note when the payload is a Kapso test delivery (else empty)",
+    },
+    { name: "message_text", description: "Inbound message text or a non-text placeholder" },
+  ],
+  category: "event",
+});
+
 // ============================================================================
 // Worker task follow-ups (created by store-progress for the lead)
 // ============================================================================

package/src/tools/tool-config.ts

@@ -98,6 +98,12 @@ export const DEFERRED_TOOLS = new Set([
   // AgentMail (1)
   "register-agentmail-inbox",
 
+  // Kapso/WhatsApp (4)
+  "register-kapso-number",
+  "unregister-kapso-number",
+  "send-whatsapp-message",
+  "reply-whatsapp-message",
+
   // Tracker (6)
   "tracker-status",
   "tracker-link-task",