@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/tools/register-agentmail-inbox.ts

@@ -0,0 +1,166 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import {
+  createAgentMailInboxMapping,
+  deleteAgentMailInboxMapping,
+  getAgentById,
+  getAgentMailInboxMapping,
+  getAgentMailInboxMappingsByAgent,
+} from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerRegisterAgentMailInboxTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "register-agentmail-inbox",
+    {
+      title: "Register AgentMail Inbox",
+      annotations: { idempotentHint: true },
+      description:
+        "Register an AgentMail inbox ID to route incoming emails to this agent. When emails arrive at this inbox, they will be routed to you as tasks (for workers) or inbox messages (for leads). Use action 'register' to add a mapping, 'unregister' to remove one, or 'list' to see your current mappings.",
+      inputSchema: z.object({
+        action: z
+          .enum(["register", "unregister", "list"])
+          .describe("Action to perform: register, unregister, or list inbox mappings."),
+        inboxId: z
+          .string()
+          .optional()
+          .describe("The AgentMail inbox ID (e.g., 'inb_xxx'). Required for register/unregister."),
+        inboxEmail: z
+          .string()
+          .optional()
+          .describe("Optional email address for this inbox (for reference only)."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        mappings: z
+          .array(
+            z.object({
+              id: z.string(),
+              inboxId: z.string(),
+              agentId: z.string(),
+              inboxEmail: z.string().nullable(),
+              createdAt: z.string(),
+            }),
+          )
+          .optional(),
+      }),
+    },
+    async ({ action, inboxId, inboxEmail }, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: 'Agent ID not found. Set the "X-Agent-ID" header.' }],
+          structuredContent: {
+            success: false,
+            message: 'Agent ID not found. Set the "X-Agent-ID" header.',
+          },
+        };
+      }
+
+      try {
+        const agent = getAgentById(requestInfo.agentId);
+        if (!agent) {
+          return {
+            content: [{ type: "text", text: "Agent not found." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Agent not found.",
+            },
+          };
+        }
+
+        if (action === "list") {
+          const mappings = getAgentMailInboxMappingsByAgent(requestInfo.agentId);
+          const text =
+            mappings.length === 0
+              ? "No AgentMail inbox mappings registered."
+              : `Found ${mappings.length} mapping(s):\n${mappings.map((m) => `  - ${m.inboxId} (${m.inboxEmail ?? "no email"})`).join("\n")}`;
+          return {
+            content: [{ type: "text", text }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: true,
+              message: text,
+              mappings,
+            },
+          };
+        }
+
+        if (!inboxId) {
+          return {
+            content: [{ type: "text", text: "inboxId is required for register/unregister." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "inboxId is required for register/unregister.",
+            },
+          };
+        }
+
+        if (action === "register") {
+          const mapping = createAgentMailInboxMapping(inboxId, requestInfo.agentId, inboxEmail);
+          const text = `Registered inbox ${inboxId} → agent ${agent.name} (${requestInfo.agentId})`;
+          return {
+            content: [{ type: "text", text }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: true,
+              message: text,
+              mappings: [mapping],
+            },
+          };
+        }
+
+        if (action === "unregister") {
+          // Check ownership before allowing unregister
+          const existing = getAgentMailInboxMapping(inboxId);
+          if (existing && existing.agentId !== requestInfo.agentId) {
+            const text = `Cannot unregister inbox ${inboxId}: owned by another agent`;
+            return {
+              content: [{ type: "text", text }],
+              structuredContent: {
+                yourAgentId: requestInfo.agentId,
+                success: false,
+                message: text,
+              },
+            };
+          }
+
+          const deleted = deleteAgentMailInboxMapping(inboxId);
+          const text = deleted
+            ? `Unregistered inbox ${inboxId}`
+            : `No mapping found for inbox ${inboxId}`;
+          return {
+            content: [{ type: "text", text }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: deleted,
+              message: text,
+            },
+          };
+        }
+
+        return {
+          content: [{ type: "text", text: `Unknown action: ${action}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Unknown action: ${action}`,
+          },
+        };
+      } 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/register-service.ts

@@ -13,6 +13,8 @@ export const registerRegisterServiceTool = (server: McpServer) => {
       title: "Register Service",
       description:
         "Register a background service (e.g., PM2 process) for discovery by other agents. The service URL is automatically derived from your agent ID (https://{AGENT_ID}.{SWARM_URL}). Each agent can only run one service on port 3000.",
+      annotations: { idempotentHint: true },
+
       inputSchema: z.object({
         script: z.string().min(1).describe("Path to the script to run (required for PM2 restart)."),
         description: z.string().optional().describe("What this service does."),

package/src/tools/schedules/create-schedule.ts

@@ -10,8 +10,9 @@ export const registerCreateScheduleTool = (server: McpServer) => {
     "create-schedule",
     {
       title: "Create Scheduled Task",
+      annotations: { destructiveHint: false },
       description:
-        "Create a new scheduled task that will automatically create agent tasks at specified intervals. Either cronExpression or intervalMs must be provided.",
+        "Create a new scheduled task. For recurring: provide cronExpression or intervalMs. For one-time: provide delayMs or runAt with scheduleType 'one_time'.",
       inputSchema: z.object({
         name: z
           .string()
@@ -22,16 +23,32 @@ export const registerCreateScheduleTool = (server: McpServer) => {
           .string()
           .min(1)
           .describe("The task description that will be created each time"),
+        scheduleType: z
+          .enum(["recurring", "one_time"])
+          .default("recurring")
+          .optional()
+          .describe("Schedule type: 'recurring' (default) or 'one_time'"),
         cronExpression: z
           .string()
           .optional()
-          .describe("Cron expression (e.g., '0 9 * * *' for daily at 9 AM)"),
+          .describe("Cron expression for recurring schedules (e.g., '0 9 * * *')"),
         intervalMs: z
           .number()
           .int()
           .positive()
           .optional()
-          .describe("Interval in milliseconds (e.g., 3600000 for hourly)"),
+          .describe("Interval in milliseconds for recurring schedules (e.g., 3600000 for hourly)"),
+        delayMs: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe("Delay in milliseconds for one-time schedules (e.g., 1800000 for 30 min)"),
+        runAt: z
+          .string()
+          .datetime()
+          .optional()
+          .describe("ISO datetime for one-time schedules (e.g., '2026-03-06T15:00:00Z')"),
         description: z.string().optional().describe("Human-readable description of the schedule"),
         taskType: z
           .string()
@@ -58,6 +75,12 @@ export const registerCreateScheduleTool = (server: McpServer) => {
           .default(true)
           .optional()
           .describe("Whether the schedule is enabled (default: true)"),
+        model: z
+          .enum(["haiku", "sonnet", "opus"])
+          .optional()
+          .describe(
+            "Model to use for tasks created by this schedule ('haiku', 'sonnet', or 'opus'). If not set, uses agent/global config or defaults to 'opus'.",
+          ),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -80,6 +103,8 @@ export const registerCreateScheduleTool = (server: McpServer) => {
             nextRunAt: z.string().optional(),
             createdByAgentId: z.string().optional(),
             timezone: z.string(),
+            model: z.string().optional(),
+            scheduleType: z.string(),
             createdAt: z.string(),
             lastUpdatedAt: z.string(),
           })
@@ -90,8 +115,11 @@ export const registerCreateScheduleTool = (server: McpServer) => {
       {
         name,
         taskTemplate,
+        scheduleType,
         cronExpression,
         intervalMs,
+        delayMs,
+        runAt,
         description,
         taskType,
         tags,
@@ -99,6 +127,7 @@ export const registerCreateScheduleTool = (server: McpServer) => {
         targetAgentId,
         timezone,
         enabled,
+        model,
       },
       requestInfo,
       _meta,
@@ -113,17 +142,89 @@ export const registerCreateScheduleTool = (server: McpServer) => {
         };
       }
 
-      // Validate that either cronExpression or intervalMs is provided
-      if (!cronExpression && !intervalMs) {
-        return {
-          content: [
-            { type: "text", text: "Either cronExpression or intervalMs must be provided." },
-          ],
-          structuredContent: {
-            success: false,
-            message: "Either cronExpression or intervalMs must be provided.",
-          },
-        };
+      const isOneTime = scheduleType === "one_time";
+
+      // Validate params based on schedule type
+      if (isOneTime) {
+        if (cronExpression || intervalMs) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "One-time schedules cannot use cronExpression or intervalMs. Use delayMs or runAt instead.",
+              },
+            ],
+            structuredContent: {
+              success: false,
+              message:
+                "One-time schedules cannot use cronExpression or intervalMs. Use delayMs or runAt instead.",
+            },
+          };
+        }
+        if (!delayMs && !runAt) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "One-time schedules require either delayMs or runAt.",
+              },
+            ],
+            structuredContent: {
+              success: false,
+              message: "One-time schedules require either delayMs or runAt.",
+            },
+          };
+        }
+        if (delayMs && runAt) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Provide either delayMs or runAt, not both.",
+              },
+            ],
+            structuredContent: {
+              success: false,
+              message: "Provide either delayMs or runAt, not both.",
+            },
+          };
+        }
+        if (runAt && new Date(runAt).getTime() <= Date.now()) {
+          return {
+            content: [{ type: "text", text: "runAt must be in the future." }],
+            structuredContent: {
+              success: false,
+              message: "runAt must be in the future.",
+            },
+          };
+        }
+      } else {
+        if (delayMs || runAt) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "delayMs and runAt are only for one-time schedules. Set scheduleType to 'one_time'.",
+              },
+            ],
+            structuredContent: {
+              success: false,
+              message:
+                "delayMs and runAt are only for one-time schedules. Set scheduleType to 'one_time'.",
+            },
+          };
+        }
+        if (!cronExpression && !intervalMs) {
+          return {
+            content: [
+              { type: "text", text: "Either cronExpression or intervalMs must be provided." },
+            ],
+            structuredContent: {
+              success: false,
+              message: "Either cronExpression or intervalMs must be provided.",
+            },
+          };
+        }
       }
 
       // Validate cron expression syntax
@@ -170,14 +271,19 @@ export const registerCreateScheduleTool = (server: McpServer) => {
 
       try {
         // Calculate initial nextRunAt
-        const tempSchedule = {
-          cronExpression,
-          intervalMs,
-          timezone: timezone || "UTC",
-        } as Parameters<typeof calculateNextRun>[0];
-
-        const nextRunAt =
-          enabled !== false ? calculateNextRun(tempSchedule, new Date()) : undefined;
+        let nextRunAt: string | undefined;
+        if (enabled === false) {
+          nextRunAt = undefined;
+        } else if (isOneTime) {
+          nextRunAt = delayMs ? new Date(Date.now() + delayMs).toISOString() : runAt!;
+        } else {
+          const tempSchedule = {
+            cronExpression,
+            intervalMs,
+            timezone: timezone || "UTC",
+          } as Parameters<typeof calculateNextRun>[0];
+          nextRunAt = calculateNextRun(tempSchedule, new Date());
+        }
 
         const schedule = createScheduledTask({
           name,
@@ -193,14 +299,18 @@ export const registerCreateScheduleTool = (server: McpServer) => {
           enabled,
           nextRunAt,
           createdByAgentId: requestInfo.agentId,
+          model,
+          scheduleType: scheduleType ?? "recurring",
         });
 
-        const scheduleType = cronExpression || `every ${intervalMs}ms`;
+        const scheduleDesc = isOneTime
+          ? `one-time at ${schedule.nextRunAt}`
+          : cronExpression || `every ${intervalMs}ms`;
         return {
           content: [
             {
               type: "text",
-              text: `Created schedule "${name}" (${scheduleType}). Next run: ${schedule.nextRunAt || "disabled"}`,
+              text: `Created schedule "${name}" (${scheduleDesc}). Next run: ${schedule.nextRunAt || "disabled"}`,
             },
           ],
           structuredContent: {

package/src/tools/schedules/delete-schedule.ts

@@ -15,6 +15,8 @@ export const registerDeleteScheduleTool = (server: McpServer) => {
       title: "Delete Scheduled Task",
       description:
         "Delete a scheduled task permanently. Only the creator or lead agent can delete schedules.",
+      annotations: { destructiveHint: true },
+
       inputSchema: z.object({
         scheduleId: z.string().uuid().optional().describe("Schedule ID to delete"),
         name: z.string().optional().describe("Schedule name to delete (alternative to ID)"),

package/src/tools/schedules/list-schedules.ts

@@ -10,9 +10,20 @@ export const registerListSchedulesTool = (server: McpServer) => {
       title: "List Scheduled Tasks",
       description:
         "View all scheduled tasks with optional filters. Use this to discover existing schedules.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({
         enabled: z.boolean().optional().describe("Filter by enabled status"),
         name: z.string().optional().describe("Filter by name (partial match)"),
+        scheduleType: z
+          .enum(["recurring", "one_time"])
+          .optional()
+          .describe("Filter by schedule type"),
+        hideCompleted: z
+          .boolean()
+          .default(true)
+          .optional()
+          .describe("Hide completed one-time schedules (default: true)"),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -35,6 +46,7 @@ export const registerListSchedulesTool = (server: McpServer) => {
             nextRunAt: z.string().optional(),
             createdByAgentId: z.string().optional(),
             timezone: z.string(),
+            scheduleType: z.string(),
             createdAt: z.string(),
             lastUpdatedAt: z.string(),
           }),
@@ -42,7 +54,7 @@ export const registerListSchedulesTool = (server: McpServer) => {
         count: z.number(),
       }),
     },
-    async ({ enabled, name }, requestInfo, _meta) => {
+    async ({ enabled, name, scheduleType, hideCompleted }, requestInfo, _meta) => {
       if (!requestInfo.agentId) {
         return {
           content: [{ type: "text", text: 'Agent ID not found. Set the "X-Agent-ID" header.' }],
@@ -56,7 +68,7 @@ export const registerListSchedulesTool = (server: McpServer) => {
       }
 
       try {
-        const schedules = getScheduledTasks({ enabled, name });
+        const schedules = getScheduledTasks({ enabled, name, scheduleType, hideCompleted });
         const count = schedules.length;
         const statusSummary =
           count === 0 ? "No schedules found." : `Found ${count} schedule${count === 1 ? "" : "s"}.`;
@@ -64,10 +76,14 @@ export const registerListSchedulesTool = (server: McpServer) => {
         // Format for text output
         const scheduleList = schedules
           .map((s) => {
-            const schedule = s.cronExpression || `every ${s.intervalMs}ms`;
+            const type = s.scheduleType === "one_time" ? "one-time" : "recurring";
+            const schedule =
+              s.scheduleType === "one_time"
+                ? `runs at ${s.nextRunAt || s.lastRunAt || "unknown"}`
+                : s.cronExpression || `every ${s.intervalMs}ms`;
             const status = s.enabled ? "enabled" : "disabled";
             const nextRun = s.nextRunAt ? `next: ${s.nextRunAt}` : "not scheduled";
-            return `- ${s.name} (${status}) [${schedule}] ${nextRun}`;
+            return `- ${s.name} (${status}, ${type}) [${schedule}] ${nextRun}`;
           })
           .join("\n");
 

package/src/tools/schedules/run-schedule-now.ts

@@ -9,6 +9,7 @@ export const registerRunScheduleNowTool = (server: McpServer) => {
     "run-schedule-now",
     {
       title: "Run Schedule Now",
+      annotations: { destructiveHint: false },
       description:
         "Immediately execute a scheduled task, creating a task right away. Does not affect the regular schedule timing.",
       inputSchema: z.object({

package/src/tools/schedules/update-schedule.ts

@@ -15,6 +15,7 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
     "update-schedule",
     {
       title: "Update Scheduled Task",
+      annotations: { idempotentHint: true },
       description:
         "Update an existing scheduled task. Only the creator or lead agent can update schedules.",
       inputSchema: z.object({
@@ -31,6 +32,11 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
         targetAgentId: z.string().uuid().nullable().optional().describe("New target agent ID"),
         timezone: z.string().optional().describe("New timezone"),
         enabled: z.boolean().optional().describe("Enable or disable the schedule"),
+        model: z
+          .enum(["haiku", "sonnet", "opus"])
+          .nullable()
+          .optional()
+          .describe("Model to use for tasks created by this schedule. Set to null to clear."),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -53,6 +59,8 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
             nextRunAt: z.string().optional(),
             createdByAgentId: z.string().optional(),
             timezone: z.string(),
+            model: z.string().optional(),
+            scheduleType: z.string(),
             createdAt: z.string(),
             lastUpdatedAt: z.string(),
           })
@@ -74,6 +82,7 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
         targetAgentId,
         timezone,
         enabled,
+        model,
       },
       requestInfo,
       _meta,
@@ -120,6 +129,22 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
         };
       }
 
+      // Reject updates on completed one-time schedules
+      if (schedule.scheduleType === "one_time" && !schedule.enabled && schedule.lastRunAt) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `One-time schedule "${schedule.name}" has already executed. Create a new one instead.`,
+            },
+          ],
+          structuredContent: {
+            success: false,
+            message: `One-time schedule "${schedule.name}" has already executed. Create a new one instead.`,
+          },
+        };
+      }
+
       // Validate new cron expression if provided
       if (cronExpression) {
         try {
@@ -181,24 +206,31 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
         if (targetAgentId !== undefined) updateData.targetAgentId = targetAgentId;
         if (timezone !== undefined) updateData.timezone = timezone;
         if (enabled !== undefined) updateData.enabled = enabled;
+        if (model !== undefined) updateData.model = model;
+
+        // Recalculate nextRunAt based on schedule type
+        if (schedule.scheduleType === "one_time") {
+          // One-time schedules: no recalculation of nextRunAt via cron/interval
+          if (enabled === false) {
+            updateData.nextRunAt = undefined;
+          }
+        } else {
+          const needsNextRunRecalc =
+            cronExpression !== undefined ||
+            intervalMs !== undefined ||
+            timezone !== undefined ||
+            (enabled === true && !schedule.enabled);
 
-        // Recalculate nextRunAt if cron/interval/timezone changes or schedule is re-enabled
-        const needsNextRunRecalc =
-          cronExpression !== undefined ||
-          intervalMs !== undefined ||
-          timezone !== undefined ||
-          (enabled === true && !schedule.enabled);
-
-        if (needsNextRunRecalc && enabled !== false) {
-          const tempSchedule = {
-            cronExpression: cronExpression ?? schedule.cronExpression,
-            intervalMs: intervalMs ?? schedule.intervalMs,
-            timezone: timezone ?? schedule.timezone,
-          } as Parameters<typeof calculateNextRun>[0];
-          updateData.nextRunAt = calculateNextRun(tempSchedule, new Date());
-        } else if (enabled === false) {
-          // When disabling, clear nextRunAt
-          updateData.nextRunAt = undefined;
+          if (needsNextRunRecalc && enabled !== false) {
+            const tempSchedule = {
+              cronExpression: cronExpression ?? schedule.cronExpression,
+              intervalMs: intervalMs ?? schedule.intervalMs,
+              timezone: timezone ?? schedule.timezone,
+            } as Parameters<typeof calculateNextRun>[0];
+            updateData.nextRunAt = calculateNextRun(tempSchedule, new Date());
+          } else if (enabled === false) {
+            updateData.nextRunAt = undefined;
+          }
         }
 
         const updated = updateScheduledTask(schedule.id, updateData);