@desplega.ai/agent-swarm 1.83.1 → 1.84.0

package/src/tools/get-tasks.ts

@@ -1,6 +1,8 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import * as z from "zod";
 import { getAllTasks } from "@/be/db";
+import { ownerCtx, type ToolCtx } from "@/tools/task-tool-ctx";
 import { createToolRegistrar } from "@/tools/utils";
 import type { AgentTask, AgentTaskSummary } from "@/types";
 import { AgentTaskStatusSchema } from "@/types";
@@ -24,6 +26,135 @@ const TaskSummarySchema = z.object({
   progress: z.string().optional(),
 });
 
+export const getTasksInputSchema = z.object({
+  status: AgentTaskStatusSchema.optional().describe(
+    "Filter by task status (unassigned, offered, pending, in_progress, completed, failed).",
+  ),
+  mineOnly: z.boolean().optional().describe("Only return tasks assigned to you."),
+  unassigned: z.boolean().optional().describe("Only return unassigned tasks in the pool."),
+  offeredToMe: z
+    .boolean()
+    .optional()
+    .describe("Only return tasks offered to you (awaiting accept/reject)."),
+  readyOnly: z.boolean().optional().describe("Only return tasks whose dependencies are met."),
+  taskType: z.string().optional().describe("Filter by task type (e.g., 'bug', 'feature')."),
+  tags: z.array(z.string()).optional().describe("Filter by any matching tag."),
+  search: z.string().optional().describe("Search in task description."),
+  scheduleId: z
+    .string()
+    .uuid()
+    .optional()
+    .describe("Filter by schedule ID to find tasks created by a specific schedule."),
+  includeHeartbeat: z
+    .boolean()
+    .optional()
+    .describe("Include heartbeat/system tasks in results (excluded by default)."),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Max tasks to return (default: 25, max: 100)."),
+  includeFull: z
+    .boolean()
+    .optional()
+    .describe("Return the full `task` text instead of a ~300-char `taskPreview`. Default false."),
+});
+
+export const getTasksOutputSchema = z.object({
+  yourAgentId: z.string().uuid().optional(),
+  tasks: z.array(TaskSummarySchema),
+});
+
+type GetTasksArgs = z.infer<typeof getTasksInputSchema>;
+
+export async function getTasksHandler(
+  ctx: ToolCtx,
+  {
+    status,
+    mineOnly,
+    unassigned,
+    offeredToMe,
+    readyOnly,
+    taskType,
+    tags,
+    search,
+    scheduleId,
+    includeHeartbeat,
+    limit,
+    includeFull,
+  }: GetTasksArgs,
+): Promise<CallToolResult> {
+  const agentId = ctx.kind === "owner" ? ctx.agentId : undefined;
+
+  // Build filters. User context is hard-scoped by requestedByUserId and ignores
+  // agent-specific shortcuts like mineOnly/offeredToMe.
+  const taskFilters = {
+    status,
+    agentId: ctx.kind === "owner" && mineOnly ? (agentId ?? undefined) : undefined,
+    unassigned: ctx.kind === "owner" ? unassigned : undefined,
+    offeredTo: ctx.kind === "owner" && offeredToMe ? (agentId ?? undefined) : undefined,
+    readyOnly,
+    taskType,
+    tags,
+    search,
+    scheduleId,
+    includeHeartbeat,
+    limit,
+    requestedByUserId: ctx.kind === "user" ? ctx.userId : undefined,
+  };
+  // Default to slim rows (full `task` text → ~300-char `taskPreview`).
+  const tasks: Array<AgentTask | AgentTaskSummary> = includeFull
+    ? getAllTasks(taskFilters)
+    : getAllTasks(taskFilters, { slim: true });
+
+  // Slim rows carry a truncated `task`; surface it as `taskPreview` so the
+  // agent knows it is truncated. `includeFull` returns the full `task`.
+  const taskSummaries = tasks.map((t) => ({
+    id: t.id,
+    agentId: t.agentId,
+    ...(includeFull ? { task: t.task } : { taskPreview: t.task }),
+    status: t.status,
+    taskType: t.taskType,
+    tags: t.tags,
+    priority: t.priority,
+    dependsOn: t.dependsOn,
+    offeredTo: t.offeredTo,
+    createdAt: t.createdAt,
+    lastUpdatedAt: t.lastUpdatedAt,
+    finishedAt: t.finishedAt,
+    progress: t.progress,
+  }));
+
+  // Build filter description for message
+  const filters: string[] = [];
+  if (status) filters.push(`status='${status}'`);
+  if (ctx.kind === "owner" && mineOnly) filters.push("mine only");
+  if (ctx.kind === "owner" && unassigned) filters.push("unassigned");
+  if (ctx.kind === "owner" && offeredToMe) filters.push("offered to me");
+  if (readyOnly) filters.push("ready only");
+  if (taskType) filters.push(`type='${taskType}'`);
+  if (tags?.length) filters.push(`tags=[${tags.join(", ")}]`);
+  if (search) filters.push(`search='${search}'`);
+  if (scheduleId) filters.push(`scheduleId='${scheduleId}'`);
+
+  const filterMsg = filters.length > 0 ? ` (${filters.join(", ")})` : "";
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Found ${taskSummaries.length} task(s)${filterMsg}.`,
+      },
+    ],
+    structuredContent: {
+      yourAgentId: agentId,
+      tasks: taskSummaries,
+    },
+  };
+}
+
 export const registerGetTasksTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "get-tasks",
@@ -32,132 +163,9 @@ export const registerGetTasksTool = (server: McpServer) => {
       description:
         "Returns a list of tasks in the swarm with various filters. Sorted by priority (desc) then lastUpdatedAt (desc). Each row carries a `taskPreview` (~300 chars) — enough to pool-triage; pass includeFull:true (or call `get-task-details` by id) for the full `task` text.",
       annotations: { readOnlyHint: true },
-
-      inputSchema: z.object({
-        status: AgentTaskStatusSchema.optional().describe(
-          "Filter by task status (unassigned, offered, pending, in_progress, completed, failed).",
-        ),
-        mineOnly: z.boolean().optional().describe("Only return tasks assigned to you."),
-        unassigned: z.boolean().optional().describe("Only return unassigned tasks in the pool."),
-        offeredToMe: z
-          .boolean()
-          .optional()
-          .describe("Only return tasks offered to you (awaiting accept/reject)."),
-        readyOnly: z.boolean().optional().describe("Only return tasks whose dependencies are met."),
-        taskType: z.string().optional().describe("Filter by task type (e.g., 'bug', 'feature')."),
-        tags: z.array(z.string()).optional().describe("Filter by any matching tag."),
-        search: z.string().optional().describe("Search in task description."),
-        scheduleId: z
-          .string()
-          .uuid()
-          .optional()
-          .describe("Filter by schedule ID to find tasks created by a specific schedule."),
-        includeHeartbeat: z
-          .boolean()
-          .optional()
-          .describe("Include heartbeat/system tasks in results (excluded by default)."),
-        limit: z
-          .number()
-          .int()
-          .min(1)
-          .max(100)
-          .optional()
-          .describe("Max tasks to return (default: 25, max: 100)."),
-        includeFull: z
-          .boolean()
-          .optional()
-          .describe(
-            "Return the full `task` text instead of a ~300-char `taskPreview`. Default false.",
-          ),
-      }),
-      outputSchema: z.object({
-        yourAgentId: z.string().uuid().optional(),
-        tasks: z.array(TaskSummarySchema),
-      }),
-    },
-    async (
-      {
-        status,
-        mineOnly,
-        unassigned,
-        offeredToMe,
-        readyOnly,
-        taskType,
-        tags,
-        search,
-        scheduleId,
-        includeHeartbeat,
-        limit,
-        includeFull,
-      },
-      requestInfo,
-      _meta,
-    ) => {
-      const agentId = requestInfo.agentId;
-
-      // Build filters
-      const taskFilters = {
-        status,
-        agentId: mineOnly ? (agentId ?? undefined) : undefined,
-        unassigned,
-        offeredTo: offeredToMe ? (agentId ?? undefined) : undefined,
-        readyOnly,
-        taskType,
-        tags,
-        search,
-        scheduleId,
-        includeHeartbeat,
-        limit,
-      };
-      // Default to slim rows (full `task` text → ~300-char `taskPreview`).
-      const tasks: Array<AgentTask | AgentTaskSummary> = includeFull
-        ? getAllTasks(taskFilters)
-        : getAllTasks(taskFilters, { slim: true });
-
-      // Slim rows carry a truncated `task`; surface it as `taskPreview` so the
-      // agent knows it is truncated. `includeFull` returns the full `task`.
-      const taskSummaries = tasks.map((t) => ({
-        id: t.id,
-        agentId: t.agentId,
-        ...(includeFull ? { task: t.task } : { taskPreview: t.task }),
-        status: t.status,
-        taskType: t.taskType,
-        tags: t.tags,
-        priority: t.priority,
-        dependsOn: t.dependsOn,
-        offeredTo: t.offeredTo,
-        createdAt: t.createdAt,
-        lastUpdatedAt: t.lastUpdatedAt,
-        finishedAt: t.finishedAt,
-        progress: t.progress,
-      }));
-
-      // Build filter description for message
-      const filters: string[] = [];
-      if (status) filters.push(`status='${status}'`);
-      if (mineOnly) filters.push("mine only");
-      if (unassigned) filters.push("unassigned");
-      if (offeredToMe) filters.push("offered to me");
-      if (readyOnly) filters.push("ready only");
-      if (taskType) filters.push(`type='${taskType}'`);
-      if (tags?.length) filters.push(`tags=[${tags.join(", ")}]`);
-      if (search) filters.push(`search='${search}'`);
-      if (scheduleId) filters.push(`scheduleId='${scheduleId}'`);
-
-      const filterMsg = filters.length > 0 ? ` (${filters.join(", ")})` : "";
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Found ${taskSummaries.length} task(s)${filterMsg}.`,
-          },
-        ],
-        structuredContent: {
-          yourAgentId: agentId,
-          tasks: taskSummaries,
-        },
-      };
+      inputSchema: getTasksInputSchema,
+      outputSchema: getTasksOutputSchema,
     },
+    async (args, info, _meta) => getTasksHandler(ownerCtx(info), args),
   );
 };

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,
+          },
+        };
+      }
+    },
+  );
+};