@desplega.ai/agent-swarm 1.83.2 → 1.84.1

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,147 @@
+import { resolveTemplate } from "@/prompts/resolver";
+import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
+import { workflowEventBus } from "@/workflows/event-bus";
+import "@/tools/templates";
+import { recordUnmappedIdentity } from "@/be/unmapped-identities";
+import { findUserByExternalId } from "@/be/users";
+import { getKapsoNumberMapping, markKapsoMessageSeen } from "./config";
+
+const KAPSO_IDENTITY_KIND = "kapso";
+const WHATSAPP_IDENTITY_KIND = "whatsapp";
+
+/** 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;
+}
+
+function normalizeKapsoSender(payload: KapsoWebhookPayload): string | null {
+  const raw = payload.message?.from ?? payload.conversation?.phone_number ?? "";
+  const digits = raw.replace(/\D/g, "");
+  return digits || null;
+}
+
+function resolveKapsoRequestedByUserId(payload: KapsoWebhookPayload): string | undefined {
+  const externalId = normalizeKapsoSender(payload);
+  if (!externalId) return undefined;
+
+  const mapped =
+    findUserByExternalId(KAPSO_IDENTITY_KIND, externalId) ??
+    findUserByExternalId(WHATSAPP_IDENTITY_KIND, externalId);
+  if (mapped) return mapped.id;
+
+  recordUnmappedIdentity(KAPSO_IDENTITY_KIND, externalId, {
+    sampleEventType: "kapso.message.received",
+    sampleContext: [
+      payload.conversation?.contact_name ? `contact=${payload.conversation.contact_name}` : null,
+      payload.conversation?.id ? `conversation=${payload.conversation.id}` : null,
+      payload.message?.id ? `message=${payload.message.id}` : null,
+      payload.phone_number_id ? `phone_number_id=${payload.phone_number_id}` : null,
+    ]
+      .filter(Boolean)
+      .join(" "),
+  });
+
+  return undefined;
+}
+
+/**
+ * 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,
+    requestedByUserId: resolveKapsoRequestedByUserId(payload),
+    contextKey: `kapso:conversation:${payload.conversation?.id ?? messageId}`,
+  });
+
+  return { kind: "task", taskId: task.id };
+}

package/src/prompts/base-prompt.ts

@@ -23,6 +23,13 @@ const BOOTSTRAP_TOTAL_MAX_CHARS = 150_000;
 const truncationNotice = (file: string) =>
   `\n\n[...truncated, see /workspace/${file} for full content]\n`;
 
+export function areSlackPromptToolsEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const slackDisable = env.SLACK_DISABLE;
+  if (slackDisable === "true" || slackDisable === "1") return false;
+
+  return Boolean(env.SLACK_BOT_TOKEN && env.SLACK_APP_TOKEN);
+}
+
 export type BasePromptArgs = {
   role: string;
   agentId: string;
@@ -71,9 +78,15 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
   const compositeResult = await resolveTemplateAsync(compositeEventType, vars);
   let prompt = compositeResult.text;
 
+  const slackPromptToolsEnabled = areSlackPromptToolsEnabled();
+
+  if (hasMcp && slackPromptToolsEnabled) {
+    const slackResult = await resolveTemplateAsync("system.agent.slack", {});
+    prompt += slackResult.text;
+  }
+
   // Conditionally inject Slack instructions for workers with Slack-originated tasks
-  // Skip for providers without MCP — they can't call Slack tools (slack-reply, etc.)
-  if (role !== "lead" && args.slackContext && hasMcp) {
+  if (role !== "lead" && args.slackContext && hasMcp && slackPromptToolsEnabled) {
     const slackResult = await resolveTemplateAsync("system.agent.worker.slack", {
       slackChannelId: args.slackContext.channelId,
       slackThreadTs: args.slackContext.threadTs ?? "",

package/src/prompts/session-templates.ts

@@ -59,16 +59,11 @@ As the lead agent, you coordinate all worker agents in the swarm.
 - \`send-task\`: Assign a task to a specific worker or to the general pool. Slack/AgentMail metadata auto-inherits from parent task.
 - \`store-progress\`: Track coordination notes or update task status
 
-**User Registration:** When a task arrives from an unknown user (no \`requestedByUserId\`), use the \`manage-user\` tool to register them before proceeding. Resolve their identity from the Slack metadata (user ID, display name) attached to the task.
-
-**Slack:**
-- \`slack-reply\`: Reply to user in the Slack thread (use taskId for context)
-- \`slack-read\`: Read thread/channel history (use taskId or channelId)
-- \`slack-list-channels\`: Discover available Slack channels
+**User Registration:** When a task arrives from an unknown user (no \`requestedByUserId\`), use the \`manage-user\` tool to register them before proceeding. Resolve their identity from the task metadata attached to the task.
 
 **Identity:**
 - \`update-profile\`: Update your own or other agents' profile fields (name, role, capabilities, soulMd, identityMd, heartbeatMd, claudeMd, toolsMd, setupScript)
-- \`manage-user\`: Register or update human users (resolve from Slack/GitHub/GitLab identity)
+- \`manage-user\`: Register or update human users (resolve from GitHub/GitLab identity or other source metadata)
 
 #### Task Routing
 
@@ -85,16 +80,14 @@ When composing task descriptions: include the repo URL (if applicable), specific
 For follow-up tasks that should continue from previous work, pass \`parentTaskId\` with the previous task's ID:
 - Worker resumes the parent's Claude session (full conversation context preserved)
 - Child task is auto-routed to the same worker (session data is local)
-- Slack metadata (channelId, threadTs, userId) auto-inherits
 
 If you explicitly assign to a different worker, session resume gracefully falls back to a fresh session.
 
-#### Follow-Up Tasks & Slack
+#### Follow-Up Tasks
 
 When a worker completes or fails a task, you receive an automatic follow-up task. Handle it by:
 1. Review the output/failure reason
-2. If the task has Slack metadata, use \`slack-reply\` with the task's ID to post the result back to the originating thread
-3. Complete this task. Do NOT re-delegate or create new worker tasks from a follow-up \u2014 the worker's result IS the answer. Only escalate to the stakeholder if the worker explicitly failed and the failure needs human attention.
+2. Complete this task. Do NOT re-delegate or create new worker tasks from a follow-up \u2014 the worker's result IS the answer. Only escalate to the stakeholder if the worker explicitly failed and the failure needs human attention.
 
 #### Heartbeat Checklist
 
@@ -106,7 +99,6 @@ The system reads your \`/workspace/HEARTBEAT.md\` every 30 minutes. If it has co
 
 **Example standing orders:**
 \`\`\`markdown
-- Check Slack for unaddressed requests older than 1 hour
 - Review active tasks for any that seem stuck or need follow-up
 - If idle workers exist and unassigned tasks are available, investigate why
 \`\`\`
@@ -122,6 +114,28 @@ The system reads your \`/workspace/HEARTBEAT.md\` every 30 minutes. If it has co
   category: "system",
 });
 
+registerTemplate({
+  eventType: "system.agent.slack",
+  header: "",
+  defaultBody: `
+#### Slack Tools
+
+- \`slack-reply\`: Reply to user in the Slack thread (use taskId for context)
+- \`slack-read\`: Read thread/channel history (use taskId or channelId)
+- \`slack-list-channels\`: Discover available Slack channels
+
+**Slack User Registration:** When a task arrives from an unknown user (no \`requestedByUserId\`) with Slack metadata, use the \`manage-user\` tool to register them before proceeding. Resolve their identity from the Slack metadata (user ID, display name) attached to the task.
+
+**Slack context inheritance:** For follow-up tasks using \`parentTaskId\`, Slack metadata (channelId, threadTs, userId) auto-inherits.
+
+**Slack follow-up tasks:** When a worker completes or fails a task that has Slack metadata, use \`slack-reply\` with the task's ID to post the result back to the originating thread before completing the follow-up task.
+
+**Slack standing orders:** If you maintain heartbeat standing orders, check Slack for unaddressed requests older than 1 hour when appropriate.
+`,
+  variables: [],
+  category: "system",
+});
+
 registerTemplate({
   eventType: "system.agent.worker",
   header: "",

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);

package/src/tests/agentmail-sending-skill.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+
+const skillPath = `${import.meta.dir}/../../templates/skills/agentmail-sending/SKILL.md`;
+const skill = await Bun.file(skillPath).text();
+const curlInboxVariable = "$" + "{INBOX}";
+const scriptApiKeyVariable = "$" + "{apiKey}";
+
+function requireMatch(pattern: RegExp, label: string): RegExpMatchArray {
+  const match = skill.match(pattern);
+  if (!match) {
+    throw new Error(`Missing ${label}`);
+  }
+  return match;
+}
+
+describe("agentmail-sending skill template", () => {
+  test("pins the canonical base URL and rejects the hallucinated host", () => {
+    expect(skill).toContain("```text\nhttps://api.agentmail.to/v0/\n```");
+    expect(skill).toContain("DO NOT use `api.agentmail.ai`");
+    expect(skill).not.toContain("https://api.agentmail.ai");
+  });
+
+  test("pins send-message field names and text-only guidance", () => {
+    expect(skill).toContain("```text\nto\nbcc\nsubject\ntext\n```");
+    expect(skill).toContain("Use `text`, NOT `text_body`, `body`, or `content`.");
+    expect(skill).toContain("Do NOT pass `html`.");
+  });
+
+  test("curl example uses the canonical endpoint, bearer auth, and exact JSON fields", () => {
+    expect(skill).toContain("https://api.agentmail.to/v0/inboxes/{inbox}/messages/send");
+    expect(skill).toContain(
+      [
+        'curl -sS -X POST "https://api.agentmail.to/v0/inboxes/',
+        curlInboxVariable,
+        '/messages/send"',
+      ].join(""),
+    );
+    expect(skill).toContain('-H "Authorization: Bearer $AGENTMAIL_API_KEY"');
+
+    const jsonBlock = requireMatch(
+      /--data-binary @- <<'JSON'\n([\s\S]*?)\nJSON/,
+      "curl JSON body",
+    )[1];
+    const payload = JSON.parse(jsonBlock);
+
+    expect(Object.keys(payload)).toEqual(["to", "bcc", "subject", "text"]);
+    expect(payload).not.toHaveProperty("text_body");
+    expect(payload).not.toHaveProperty("body");
+    expect(payload).not.toHaveProperty("content");
+    expect(payload).not.toHaveProperty("html");
+  });
+
+  test("script_upsert example uses fetch and resolves AGENTMAIL_API_KEY from swarm config", () => {
+    const scriptBlock = requireMatch(/```ts\n([\s\S]*?)\n```/, "script_upsert example")[1];
+
+    expect(scriptBlock).toContain("await script_upsert({");
+    expect(scriptBlock).toContain("ctx.swarm.config.get('AGENTMAIL_API_KEY')");
+    expect(scriptBlock).toContain("ctx.stdlib.fetch(");
+    expect(scriptBlock).toContain("https://api.agentmail.to/v0/inboxes/");
+    expect(scriptBlock).toContain("messages/send");
+    expect(scriptBlock).toContain(
+      ["Authorization: \\`Bearer \\", scriptApiKeyVariable, "\\`"].join(""),
+    );
+    expect(scriptBlock).toContain("text: args.text");
+    expect(scriptBlock).not.toContain("text_body");
+    expect(scriptBlock).not.toContain("html:");
+  });
+
+  test("common error table covers known AgentMail mistakes", () => {
+    expect(skill).toContain("404 on `/v0/inboxes/.../send`");
+    expect(skill).toContain('422 `{"detail":"text Field required"}`');
+    expect(skill).toContain("401");
+    expect(skill).toContain("HTML rendering bug");
+  });
+});