@desplega.ai/agent-swarm 1.83.2 → 1.84.1

package/src/tests/runner-context-preamble.test.ts

@@ -0,0 +1,202 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createServer, type Server } from "node:http";
+import {
+  buildContextPreamble,
+  CONTEXT_PREAMBLE_MAX_CHARS,
+  CONTEXT_PREAMBLE_MAX_TOKENS,
+  fetchTaskContextForPreamble,
+  type TaskContextForPreamble,
+} from "../commands/context-preamble";
+
+const TEST_PORT = 19091;
+const API_URL = `http://localhost:${TEST_PORT}`;
+const API_KEY = "test-key";
+
+// In-memory task store for the mock server
+const mockTasks: Record<string, TaskContextForPreamble> = {};
+
+let server: Server;
+
+beforeAll(async () => {
+  server = createServer((req, res) => {
+    const url = req.url ?? "";
+    const match = url.match(/^\/api\/tasks\/([^/?]+)/);
+    if (match) {
+      const id = match[1];
+      const task = mockTasks[id];
+      if (task) {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(task));
+      } else {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "not found" }));
+      }
+      return;
+    }
+    res.writeHead(404);
+    res.end();
+  });
+
+  await new Promise<void>((resolve) => server.listen(TEST_PORT, resolve));
+});
+
+afterAll(() => {
+  server.close();
+  // Clear mocks
+  for (const k of Object.keys(mockTasks)) delete mockTasks[k];
+});
+
+function seedTask(task: TaskContextForPreamble): void {
+  mockTasks[task.id] = task;
+}
+
+describe("fetchTaskContextForPreamble", () => {
+  test("returns null on 404", async () => {
+    const result = await fetchTaskContextForPreamble(API_URL, API_KEY, "missing-id");
+    expect(result).toBeNull();
+  });
+
+  test("fetches task context fields", async () => {
+    seedTask({
+      id: "task-a",
+      task: "Build the widget",
+      output: "Widget built successfully",
+      status: "completed",
+      attachments: [{ kind: "url", name: "Report", url: "https://example.com/report" }],
+    });
+
+    const result = await fetchTaskContextForPreamble(API_URL, API_KEY, "task-a");
+    expect(result).not.toBeNull();
+    expect(result?.id).toBe("task-a");
+    expect(result?.task).toBe("Build the widget");
+    expect(result?.output).toBe("Widget built successfully");
+    expect(result?.attachments).toHaveLength(1);
+    expect(result?.attachments?.[0].name).toBe("Report");
+  });
+});
+
+describe("buildContextPreamble", () => {
+  test("returns null when parent task not found", async () => {
+    const result = await buildContextPreamble(API_URL, API_KEY, "nonexistent-parent");
+    expect(result).toBeNull();
+  });
+
+  test("includes parent task subject and output in preamble", async () => {
+    seedTask({
+      id: "parent-1",
+      task: "Fix the auth bug in login flow",
+      output: "Fixed by patching jwt validation in auth.ts:42",
+      status: "completed",
+    });
+
+    const preamble = await buildContextPreamble(API_URL, API_KEY, "parent-1");
+    expect(preamble).not.toBeNull();
+    expect(preamble).toContain("parent-1");
+    expect(preamble).toContain("Fix the auth bug in login flow");
+    expect(preamble).toContain("Fixed by patching jwt validation");
+    expect(preamble).toContain("get-task-details");
+    expect(preamble).toContain("Prior Conversation Context");
+  });
+
+  test("includes attachment pointers in preamble", async () => {
+    seedTask({
+      id: "parent-2",
+      task: "Generate a report",
+      output: "Report generated",
+      status: "completed",
+      attachments: [
+        { kind: "url", name: "Final Report", url: "https://example.com/report.pdf" },
+        {
+          kind: "agent-fs",
+          name: "Raw Data",
+          path: "thoughts/agent/research/data.md",
+          orgId: "org-123",
+          driveId: "drv-456",
+        },
+      ],
+    });
+
+    const preamble = await buildContextPreamble(API_URL, API_KEY, "parent-2");
+    expect(preamble).toContain("Final Report");
+    expect(preamble).toContain("https://example.com/report.pdf");
+    expect(preamble).toContain("Raw Data");
+    expect(preamble).toContain("live.agent-fs.dev");
+    expect(preamble).toContain("org-123");
+    expect(preamble).toContain("drv-456");
+  });
+
+  test("shows 'no output recorded' when task has no output or progress", async () => {
+    seedTask({
+      id: "parent-no-output",
+      task: "A task with no output yet",
+      status: "in_progress",
+    });
+
+    const preamble = await buildContextPreamble(API_URL, API_KEY, "parent-no-output");
+    expect(preamble).toContain("no output recorded");
+  });
+
+  test("walks ancestor chain and includes older ancestors as pointers", async () => {
+    seedTask({
+      id: "grandparent-1",
+      task: "Initial research task",
+      output: "Research complete",
+      status: "completed",
+    });
+    seedTask({
+      id: "child-of-grandparent",
+      task: "Second task referencing research",
+      output: "Second task done",
+      status: "completed",
+      parentTaskId: "grandparent-1",
+    });
+
+    const preamble = await buildContextPreamble(API_URL, API_KEY, "child-of-grandparent");
+    expect(preamble).not.toBeNull();
+    // Immediate parent (child-of-grandparent) gets inline detail
+    expect(preamble).toContain("child-of-grandparent");
+    expect(preamble).toContain("Second task done");
+    // Grandparent gets pointer-only entry
+    expect(preamble).toContain("grandparent-1");
+    expect(preamble).toContain("Older Ancestor Tasks");
+    expect(preamble).toContain("Initial research task");
+  });
+
+  test("enforces token budget — truncates oversized output", async () => {
+    // Generate output that exceeds the budget
+    const hugeOutput = "x".repeat(CONTEXT_PREAMBLE_MAX_CHARS + 5000);
+    seedTask({
+      id: "parent-big",
+      task: "Task with very large output",
+      output: hugeOutput,
+      status: "completed",
+    });
+
+    const preamble = await buildContextPreamble(API_URL, API_KEY, "parent-big");
+    expect(preamble).not.toBeNull();
+    // Preamble must be within budget (some slack for the truncation suffix)
+    expect(preamble?.length ?? 0).toBeLessThanOrEqual(
+      CONTEXT_PREAMBLE_MAX_CHARS + 300, // 300 chars slack for the truncation message
+    );
+  });
+
+  test("preamble starts with context section and ends with separator", async () => {
+    seedTask({
+      id: "parent-structure",
+      task: "A well-structured task",
+      output: "Done",
+      status: "completed",
+    });
+
+    const preamble = await buildContextPreamble(API_URL, API_KEY, "parent-structure");
+    expect(preamble).toContain("---");
+    expect(preamble).toContain("Prior Conversation Context");
+    // Should end with trailing separator
+    expect(preamble?.trimEnd()).toMatch(/---\s*$/);
+  });
+
+  test("CONTEXT_PREAMBLE_MAX_TOKENS is 2000 by default", () => {
+    expect(CONTEXT_PREAMBLE_MAX_TOKENS).toBe(2000);
+    expect(CONTEXT_PREAMBLE_MAX_CHARS).toBe(8000);
+  });
+});

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/cancel-task.ts

@@ -142,12 +142,20 @@ export async function cancelTaskHandler(
 
   if ("content" in result) return result;
 
+  const structuredContent = {
+    yourAgentId: agentId,
+    ...result,
+  };
+
   return {
-    content: [{ type: "text", text: result.message }],
-    structuredContent: {
-      yourAgentId: agentId,
-      ...result,
-    },
+    content: [
+      { type: "text", text: result.message },
+      {
+        type: "text",
+        text: JSON.stringify(structuredContent),
+      },
+    ],
+    structuredContent,
   };
 }
 

package/src/tools/get-task-details.ts

@@ -65,17 +65,25 @@ export async function getTaskDetailsHandler(
     ? { name: requestedByUser.name, email: requestedByUser.email }
     : undefined;
 
+  const structuredContent = {
+    yourAgentId: agentId,
+    success: true,
+    message: `Task "${taskId}" details retrieved.`,
+    task,
+    requestedBy,
+    logs,
+    attachments,
+  };
+
   return {
-    content: [{ type: "text", text: `Task "${taskId}" details retrieved.` }],
-    structuredContent: {
-      yourAgentId: agentId,
-      success: true,
-      message: `Task "${taskId}" details retrieved.`,
-      task,
-      requestedBy,
-      logs,
-      attachments,
-    },
+    content: [
+      { type: "text", text: `Task "${taskId}" details retrieved.` },
+      {
+        type: "text",
+        text: JSON.stringify(structuredContent),
+      },
+    ],
+    structuredContent,
   };
 }
 

package/src/tools/get-tasks.ts

@@ -140,6 +140,10 @@ export async function getTasksHandler(
   if (scheduleId) filters.push(`scheduleId='${scheduleId}'`);
 
   const filterMsg = filters.length > 0 ? ` (${filters.join(", ")})` : "";
+  const structuredContent = {
+    yourAgentId: agentId,
+    tasks: taskSummaries,
+  };
 
   return {
     content: [
@@ -147,11 +151,12 @@ export async function getTasksHandler(
         type: "text",
         text: `Found ${taskSummaries.length} task(s)${filterMsg}.`,
       },
+      {
+        type: "text",
+        text: JSON.stringify(structuredContent),
+      },
     ],
-    structuredContent: {
-      yourAgentId: agentId,
-      tasks: taskSummaries,
-    },
+    structuredContent,
   };
 }
 

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/send-task.ts

@@ -326,13 +326,17 @@ export async function sendTaskHandler(
   });
 
   const result = txn();
+  const structuredContent = {
+    yourAgentId: creatorAgentId,
+    ...result,
+  };
 
   return {
-    content: [{ type: "text", text: result.message }],
-    structuredContent: {
-      yourAgentId: creatorAgentId,
-      ...result,
-    },
+    content: [
+      { type: "text", text: result.message },
+      { type: "text", text: JSON.stringify(result) },
+    ],
+    structuredContent,
   };
 }
 

package/src/tools/task-action.ts

@@ -108,24 +108,34 @@ type TaskActionResult = {
 
 function agentOnlyActionResult(): CallToolResult {
   const message = "This action is only available to worker agents.";
+  const structuredContent = {
+    success: false,
+    message,
+  };
+
   return {
     isError: true,
-    content: [{ type: "text", text: message }],
-    structuredContent: {
-      success: false,
-      message,
-    },
+    content: [
+      { type: "text", text: message },
+      { type: "text", text: JSON.stringify(structuredContent) },
+    ],
+    structuredContent,
   };
 }
 
 function taskActionCallResult(result: TaskActionResult, agentId?: string): CallToolResult {
   const { refusalSideEffects: _omit, ...publicResult } = result;
+  const structuredContent = {
+    yourAgentId: agentId,
+    ...publicResult,
+  };
+
   return {
-    content: [{ type: "text", text: result.message }],
-    structuredContent: {
-      yourAgentId: agentId,
-      ...publicResult,
-    },
+    content: [
+      { type: "text", text: result.message },
+      { type: "text", text: JSON.stringify(structuredContent) },
+    ],
+    structuredContent,
   };
 }
 

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",