@desplega.ai/agent-swarm 1.83.2 → 1.84.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.83.2",
+    "version": "1.84.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -11394,6 +11394,25 @@
         }
       }
     },
+    "/api/integrations/kapso/webhook": {
+      "post": {
+        "summary": "Handle native Kapso/WhatsApp webhook events",
+        "tags": [
+          "Webhooks"
+        ],
+        "responses": {
+          "200": {
+            "description": "Event received"
+          },
+          "401": {
+            "description": "Invalid signature"
+          },
+          "503": {
+            "description": "Kapso integration not configured"
+          }
+        }
+      }
+    },
     "/api/workflow-runs/{runId}/events": {
       "post": {
         "summary": "Fire a run-scoped event signal",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.83.2",
+  "version": "1.84.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/http/webhooks.ts

@@ -41,7 +41,11 @@ import {
   isGitLabEnabled,
   verifyGitLabWebhook,
 } from "../gitlab";
+import { getKapsoConfig } from "../integrations/kapso/config";
+import { routeKapsoInbound } from "../integrations/kapso/inbound";
+import { getExecutorRegistry } from "../workflows";
 import { workflowEventBus } from "../workflows/event-bus";
+import { handleWebhookTrigger, verifyHmacSignature, WebhookError } from "../workflows/triggers";
 import { route } from "./route-def";
 
 // ─── Route Definitions (documentation only — webhooks handle their own body parsing) ─
@@ -88,6 +92,20 @@ const agentmailWebhook = route({
   },
 });
 
+const kapsoWebhook = route({
+  method: "post",
+  path: "/api/integrations/kapso/webhook",
+  pattern: ["api", "integrations", "kapso", "webhook"],
+  summary: "Handle native Kapso/WhatsApp webhook events",
+  tags: ["Webhooks"],
+  auth: { apiKey: false },
+  responses: {
+    200: { description: "Event received" },
+    401: { description: "Invalid signature" },
+    503: { description: "Kapso integration not configured" },
+  },
+});
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleWebhooks(
@@ -437,5 +455,88 @@ export async function handleWebhooks(
     return true;
   }
 
+  // Native Kapso/WhatsApp webhook — needs raw body for HMAC verification.
+  // Registered numbers route here (register-kapso-number points Kapso's webhook
+  // at this URL); the generic workflow-webhook path (/api/webhooks/{id}) is
+  // untouched and still serves any number not registered in KV.
+  if (kapsoWebhook.match(req.method, pathSegments)) {
+    const config = getKapsoConfig();
+    if (!config.webhookHmacSecret) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kapso integration not configured" }));
+      return true;
+    }
+
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) {
+      chunks.push(chunk as Buffer);
+    }
+    const rawBody = Buffer.concat(chunks).toString();
+
+    const signature = req.headers["x-webhook-signature"];
+    const signatureValue = Array.isArray(signature) ? signature[0] : signature;
+    if (
+      !signatureValue ||
+      !verifyHmacSignature(config.webhookHmacSecret, rawBody, signatureValue)
+    ) {
+      console.log("[Kapso] Invalid webhook signature");
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid signature" }));
+      return true;
+    }
+
+    let payload: Record<string, unknown>;
+    try {
+      payload = JSON.parse(rawBody);
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid JSON body" }));
+      return true;
+    }
+
+    try {
+      const routing = routeKapsoInbound(payload);
+      switch (routing.kind) {
+        case "workflow":
+          // Advanced override — dispatch through the workflow's webhook trigger.
+          await handleWebhookTrigger(
+            routing.workflowId,
+            rawBody,
+            req.headers,
+            getExecutorRegistry(),
+          );
+          break;
+        case "no_mapping":
+          console.warn(
+            `[Kapso] No native mapping for phone_number_id "${routing.phoneNumberId}" — ignoring (register it with register-kapso-number)`,
+          );
+          break;
+        case "task":
+          console.log(`[Kapso] Dispatched kapso-inbound task ${routing.taskId}`);
+          break;
+        case "duplicate":
+          console.log(`[Kapso] Duplicate delivery for message ${routing.messageId}, skipping`);
+          break;
+        case "skip":
+          console.log(`[Kapso] Skipping event: ${routing.reason}`);
+          break;
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ received: true, routing: routing.kind }));
+    } catch (err) {
+      // Never fail the delivery on a downstream dispatch error — we already
+      // verified + deduped. Log and ack so Kapso doesn't hammer retries.
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      if (err instanceof WebhookError) {
+        console.warn(`[Kapso] Workflow dispatch rejected: ${errorMessage}`);
+      } else {
+        console.error(`[Kapso] Error handling inbound event: ${errorMessage}`);
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ received: true, routing: "error" }));
+    }
+    return true;
+  }
+
   return false;
 }

package/src/integrations/kapso/client.ts

@@ -0,0 +1,198 @@
+/**
+ * Thin Kapso REST client for the native integration. Pure `fetch` — no DB access.
+ *
+ * Two Kapso surfaces are used:
+ *  - Meta Cloud API proxy:  `{base}/meta/whatsapp/v24.0/{phoneNumberId}/messages`
+ *  - Kapso platform API:    `{base}/platform/v1/whatsapp/phone_numbers/{id}/webhooks`
+ *
+ * Both authenticate with the `X-API-Key` header.
+ */
+
+/** Result of an outbound text/reply send through the Meta proxy. */
+export interface KapsoSendResult {
+  ok: boolean;
+  status: number;
+  /** Outbound WAMID when the send succeeded. */
+  messageId?: string;
+  raw: unknown;
+  /** True when Kapso/Meta rejected the send for being outside the 24h session window. */
+  sessionWindowExpired: boolean;
+  errorMessage?: string;
+}
+
+/** Meta error codes that mean "outside the 24h customer-service window". */
+const SESSION_WINDOW_ERROR_CODES = new Set([131047, 131051, 470]);
+
+function extractMetaError(raw: unknown): { code?: number; message?: string } {
+  if (raw && typeof raw === "object" && "error" in raw) {
+    const err = (raw as { error?: { code?: number; message?: string } }).error;
+    if (err) return { code: err.code, message: err.message };
+  }
+  return {};
+}
+
+function isSessionWindowError(raw: unknown): boolean {
+  const { code, message } = extractMetaError(raw);
+  if (code !== undefined && SESSION_WINDOW_ERROR_CODES.has(code)) return true;
+  const text = (message ?? "").toLowerCase();
+  return text.includes("24 hours") || text.includes("re-engagement") || text.includes("outside");
+}
+
+async function parseJsonSafe(res: Response): Promise<unknown> {
+  const text = await res.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * Send a free-form WhatsApp text message via the Meta Cloud API proxy. When
+ * `contextMessageId` is set, the message renders as a quote-reply to that WAMID.
+ */
+export async function sendKapsoText(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+  phoneNumberId: string;
+  to: string;
+  body: string;
+  previewUrl?: boolean;
+  contextMessageId?: string;
+}): Promise<KapsoSendResult> {
+  const url = `${params.apiBaseUrl}/meta/whatsapp/v24.0/${params.phoneNumberId}/messages`;
+  const payload: Record<string, unknown> = {
+    messaging_product: "whatsapp",
+    recipient_type: "individual",
+    to: params.to,
+    type: "text",
+    text: { preview_url: params.previewUrl ?? false, body: params.body },
+  };
+  if (params.contextMessageId) {
+    payload.context = { message_id: params.contextMessageId };
+  }
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "X-API-Key": params.apiKey, "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  const raw = await parseJsonSafe(res);
+
+  if (!res.ok) {
+    const { message } = extractMetaError(raw);
+    return {
+      ok: false,
+      status: res.status,
+      raw,
+      sessionWindowExpired: isSessionWindowError(raw),
+      errorMessage: message ?? `Kapso send failed with status ${res.status}`,
+    };
+  }
+
+  const messageId =
+    raw && typeof raw === "object" && "messages" in raw
+      ? (raw as { messages?: Array<{ id?: string }> }).messages?.[0]?.id
+      : undefined;
+  return { ok: true, status: res.status, messageId, raw, sessionWindowExpired: false };
+}
+
+/** Result of configuring a webhook on a phone number. */
+export interface KapsoWebhookResult {
+  ok: boolean;
+  status: number;
+  raw: unknown;
+  errorMessage?: string;
+  /** True when an identical webhook already existed and we skipped re-creating it. */
+  alreadyRegistered?: boolean;
+}
+
+/** Pull a webhook array out of the various shapes Kapso's list endpoint may return. */
+function extractWebhookList(raw: unknown): Array<{ url?: string; kind?: string }> {
+  if (Array.isArray(raw)) return raw as Array<{ url?: string; kind?: string }>;
+  if (raw && typeof raw === "object") {
+    for (const key of ["whatsapp_webhooks", "webhooks", "data"]) {
+      const val = (raw as Record<string, unknown>)[key];
+      if (Array.isArray(val)) return val as Array<{ url?: string; kind?: string }>;
+    }
+  }
+  return [];
+}
+
+/**
+ * Return true when a Kapso webhook already points at `webhookUrl` for this
+ * phone number — used to avoid creating duplicate webhooks on re-registration.
+ * Best-effort: returns false if the list endpoint is unavailable.
+ */
+async function kapsoWebhookExists(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+  phoneNumberId: string;
+  webhookUrl: string;
+}): Promise<boolean> {
+  const url = `${params.apiBaseUrl}/platform/v1/whatsapp/phone_numbers/${params.phoneNumberId}/webhooks`;
+  try {
+    const res = await fetch(url, { headers: { "X-API-Key": params.apiKey } });
+    if (!res.ok) return false;
+    const raw = await parseJsonSafe(res);
+    return extractWebhookList(raw).some((w) => w?.url === params.webhookUrl);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Register (or re-point) the Kapso webhook for a phone number so inbound events
+ * are delivered to `webhookUrl`, signed with `secret` via `X-Webhook-Signature`.
+ *
+ * First checks whether an identical webhook already exists for the number and
+ * skips the create call if so, to avoid piling up duplicate webhooks when a
+ * number is registered more than once.
+ */
+export async function registerKapsoWebhook(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+  phoneNumberId: string;
+  webhookUrl: string;
+  secret?: string;
+  events?: string[];
+}): Promise<KapsoWebhookResult> {
+  const url = `${params.apiBaseUrl}/platform/v1/whatsapp/phone_numbers/${params.phoneNumberId}/webhooks`;
+
+  if (
+    await kapsoWebhookExists({
+      apiBaseUrl: params.apiBaseUrl,
+      apiKey: params.apiKey,
+      phoneNumberId: params.phoneNumberId,
+      webhookUrl: params.webhookUrl,
+    })
+  ) {
+    return { ok: true, status: 200, raw: null, alreadyRegistered: true };
+  }
+
+  const whatsapp_webhook: Record<string, unknown> = {
+    kind: "kapso",
+    url: params.webhookUrl,
+    events: params.events ?? ["whatsapp.message.received"],
+  };
+  if (params.secret) whatsapp_webhook.secret_key = params.secret;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "X-API-Key": params.apiKey, "Content-Type": "application/json" },
+    body: JSON.stringify({ whatsapp_webhook }),
+  });
+  const raw = await parseJsonSafe(res);
+
+  if (!res.ok) {
+    const { message } = extractMetaError(raw);
+    return {
+      ok: false,
+      status: res.status,
+      raw,
+      errorMessage: message ?? `Kapso webhook registration failed with status ${res.status}`,
+    };
+  }
+  return { ok: true, status: res.status, raw };
+}

package/src/integrations/kapso/config.ts

@@ -0,0 +1,104 @@
+import { deleteKv, getKv, getSwarmConfigs, upsertKv } from "@/be/db";
+
+/**
+ * Native Kapso/WhatsApp integration — shared server-side config + mapping store.
+ *
+ * The mapping (phone-number-id → routing target) is backed by the swarm KV store
+ * under a pinned namespace, NOT a dedicated table. The inbound webhook handler and
+ * the `register-kapso-number` MCP tool are the only readers/writers.
+ */
+
+/** Pinned KV namespace for phone-number → routing mappings. No TTL. */
+export const KAPSO_NUMBERS_NAMESPACE = "integrations:kapso:numbers";
+
+/** Pinned KV namespace for inbound message-id dedupe markers (24h TTL). */
+export const KAPSO_DEDUPE_NAMESPACE = "integrations:kapso:dedupe";
+
+/** How long a dedupe marker lives — long enough to cover Kapso's webhook retries. */
+export const KAPSO_DEDUPE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Default Kapso API host when `KAPSO_API_BASE_URL` is unset (host only, no path). */
+export const DEFAULT_KAPSO_API_BASE_URL = "https://api.kapso.ai";
+
+/** A registered phone number and where its inbound messages should route. */
+export interface KapsoNumberMapping {
+  phoneNumberId: string;
+  /** Route inbound to this agent as a task. */
+  agentId?: string;
+  /** Advanced override: dispatch via this workflow's webhook trigger instead of a task. */
+  workflowId?: string;
+  /** Human-friendly display name for the number. */
+  name?: string;
+  createdAt: string;
+}
+
+export interface KapsoConfig {
+  apiKey: string | undefined;
+  apiBaseUrl: string;
+  webhookHmacSecret: string | undefined;
+  phoneNumberId: string | undefined;
+}
+
+/**
+ * Read a swarm-config value (global scope) by key, falling back to the process
+ * env. Decryption happens inside `getSwarmConfigs`.
+ */
+function readConfigValue(key: string): string | undefined {
+  const found = getSwarmConfigs({ scope: "global", key }).find(
+    (c) => typeof c.value === "string" && c.value.length > 0,
+  );
+  if (found) return found.value;
+  const env = process.env[key];
+  return env && env.length > 0 ? env : undefined;
+}
+
+/** Resolve the Kapso integration config from swarm config (env fallback). */
+export function getKapsoConfig(): KapsoConfig {
+  const base = readConfigValue("KAPSO_API_BASE_URL") ?? DEFAULT_KAPSO_API_BASE_URL;
+  return {
+    apiKey: readConfigValue("KAPSO_API_KEY"),
+    apiBaseUrl: base.replace(/\/+$/, ""),
+    webhookHmacSecret: readConfigValue("KAPSO_WEBHOOK_HMAC_SECRET"),
+    phoneNumberId: readConfigValue("KAPSO_PHONE_NUMBER_ID"),
+  };
+}
+
+/** Look up the routing mapping for a phone-number-id, or null if unregistered. */
+export function getKapsoNumberMapping(phoneNumberId: string): KapsoNumberMapping | null {
+  const row = getKv(KAPSO_NUMBERS_NAMESPACE, phoneNumberId);
+  return row ? (row.value as KapsoNumberMapping) : null;
+}
+
+/** Upsert a routing mapping (no TTL). */
+export function putKapsoNumberMapping(mapping: KapsoNumberMapping): KapsoNumberMapping {
+  upsertKv({
+    namespace: KAPSO_NUMBERS_NAMESPACE,
+    key: mapping.phoneNumberId,
+    value: mapping,
+    valueType: "json",
+    expiresAt: null,
+  });
+  return mapping;
+}
+
+/** Delete a routing mapping. Returns true if a row was removed. */
+export function deleteKapsoNumberMapping(phoneNumberId: string): boolean {
+  return deleteKv(KAPSO_NUMBERS_NAMESPACE, phoneNumberId);
+}
+
+/**
+ * Record a message-id as processed. Returns true the FIRST time a given id is
+ * seen and false on every subsequent delivery within the TTL window — so the
+ * caller drops duplicates (Kapso retries deliveries).
+ */
+export function markKapsoMessageSeen(messageId: string): boolean {
+  if (getKv(KAPSO_DEDUPE_NAMESPACE, messageId)) return false;
+  upsertKv({
+    namespace: KAPSO_DEDUPE_NAMESPACE,
+    key: messageId,
+    value: 1,
+    valueType: "integer",
+    expiresAt: Date.now() + KAPSO_DEDUPE_TTL_MS,
+  });
+  return true;
+}

package/src/integrations/kapso/inbound.ts

@@ -0,0 +1,111 @@
+import { resolveTemplate } from "@/prompts/resolver";
+import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
+import { workflowEventBus } from "@/workflows/event-bus";
+import "@/tools/templates";
+import { getKapsoNumberMapping, markKapsoMessageSeen } from "./config";
+
+/** Minimal shape of the Kapso v2 inbound webhook payload (see the kapso-whatsapp skill). */
+export interface KapsoWebhookPayload {
+  message?: {
+    id?: string;
+    from?: string;
+    type?: string;
+    text?: { body?: string };
+    kapso?: { direction?: string; content?: string; has_media?: boolean };
+  };
+  conversation?: {
+    id?: string;
+    phone_number?: string;
+    contact_name?: string;
+  };
+  phone_number_id?: string;
+  test?: boolean;
+}
+
+/** Outcome of routing one inbound webhook delivery. */
+export type KapsoRouting =
+  | { kind: "skip"; reason: string }
+  | { kind: "duplicate"; messageId: string }
+  | { kind: "workflow"; workflowId: string }
+  | { kind: "task"; taskId: string }
+  | { kind: "no_mapping"; phoneNumberId: string };
+
+function extractText(message: NonNullable<KapsoWebhookPayload["message"]>): string {
+  if (message.text?.body) return message.text.body;
+  if (message.kapso?.content) return message.kapso.content;
+  return `(non-text message — type: ${message.type ?? "unknown"})`;
+}
+
+function buildTaskDescription(payload: KapsoWebhookPayload): string {
+  const message = payload.message ?? {};
+  const conversation = payload.conversation ?? {};
+  return resolveTemplate("kapso.message.received", {
+    conversation_id: conversation.id ?? "unknown",
+    inbound_wamid: message.id ?? "unknown",
+    sender_phone: message.from ?? conversation.phone_number ?? "unknown",
+    contact_name: conversation.contact_name ?? "unknown",
+    phone_number_id: payload.phone_number_id ?? "unknown",
+    test_note: payload.test ? "\n- test: true (do NOT send a real WhatsApp reply)" : "",
+    message_text: extractText(message),
+  }).text;
+}
+
+/**
+ * Route one inbound Kapso webhook delivery. Pure of HTTP concerns — the caller
+ * handles HMAC verification and the workflow-trigger dispatch (which needs the
+ * raw body + executor registry). This:
+ *   1. drops non-inbound events and deliveries missing a message id,
+ *   2. dedupes by message id (KV, 24h TTL),
+ *   3. emits the `kapso.message.received` workflow event (additive),
+ *   4. looks up the phone-number mapping and either signals a workflow dispatch
+ *      or creates a native `kapso-inbound` task,
+ *   5. returns `no_mapping` when the number isn't registered (caller logs a warning).
+ */
+export function routeKapsoInbound(payload: KapsoWebhookPayload): KapsoRouting {
+  const message = payload.message;
+  const direction = message?.kapso?.direction;
+  if (direction !== "inbound") {
+    return { kind: "skip", reason: `non_inbound (direction=${direction ?? "none"})` };
+  }
+
+  const messageId = message?.id;
+  if (!messageId) {
+    return { kind: "skip", reason: "missing_message_id" };
+  }
+
+  if (!markKapsoMessageSeen(messageId)) {
+    return { kind: "duplicate", messageId };
+  }
+
+  const phoneNumberId = payload.phone_number_id ?? "";
+
+  // Additive: let event-subscribed workflows observe inbound regardless of mapping.
+  workflowEventBus.emit("kapso.message.received", {
+    phoneNumberId,
+    conversationId: payload.conversation?.id,
+    messageId,
+    from: message?.from,
+    type: message?.type,
+    text: extractText(message ?? {}),
+  });
+
+  const mapping = phoneNumberId ? getKapsoNumberMapping(phoneNumberId) : null;
+  if (!mapping) {
+    return { kind: "no_mapping", phoneNumberId };
+  }
+
+  if (mapping.workflowId) {
+    return { kind: "workflow", workflowId: mapping.workflowId };
+  }
+
+  const task = createTaskWithSiblingAwareness(buildTaskDescription(payload), {
+    agentId: mapping.agentId ?? null,
+    source: "system",
+    taskType: "kapso-inbound",
+    tags: ["kapso-whatsapp", "inbound"],
+    priority: 70,
+    contextKey: `kapso:conversation:${payload.conversation?.id ?? messageId}`,
+  });
+
+  return { kind: "task", taskId: task.id };
+}

package/src/server.ts

@@ -55,6 +55,10 @@ import {
 } from "./tools/prompt-templates";
 import { registerReadMessagesTool } from "./tools/read-messages";
 import { registerRegisterAgentmailInboxTool } from "./tools/register-agentmail-inbox";
+import {
+  registerRegisterKapsoNumberTool,
+  registerUnregisterKapsoNumberTool,
+} from "./tools/register-kapso-number";
 // Services capability
 import { registerRegisterServiceTool } from "./tools/register-service";
 // Repo management tools
@@ -118,6 +122,10 @@ import { registerUnregisterServiceTool } from "./tools/unregister-service";
 // Profiles capability
 import { registerUpdateProfileTool } from "./tools/update-profile";
 import { registerUpdateServiceStatusTool } from "./tools/update-service-status";
+import {
+  registerReplyWhatsappMessageTool,
+  registerSendWhatsappMessageTool,
+} from "./tools/whatsapp-message";
 // Workflows capability
 import {
   registerCancelWorkflowRunTool,
@@ -228,6 +236,12 @@ export function createServer() {
   // AgentMail integration tool (always registered, self-service inbox mapping)
   registerRegisterAgentmailInboxTool(server);
 
+  // Kapso/WhatsApp integration tools (native inbound provisioning + outbound)
+  registerRegisterKapsoNumberTool(server);
+  registerUnregisterKapsoNumberTool(server);
+  registerSendWhatsappMessageTool(server);
+  registerReplyWhatsappMessageTool(server);
+
   // Task pool capability - task pool operations (create unassigned, claim, release, accept, reject)
   if (hasCapability("task-pool")) {
     registerTaskActionTool(server);