@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/src/tools/memory-search.ts

@@ -0,0 +1,131 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, listMemoriesByAgent, searchMemoriesByVector } from "@/be/db";
+import { getEmbedding } from "@/be/embedding";
+import { createToolRegistrar } from "@/tools/utils";
+import { AgentMemoryScopeSchema, AgentMemorySourceSchema } from "@/types";
+
+export const registerMemorySearchTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "memory-search",
+    {
+      title: "Search memories",
+      description:
+        "Search your accumulated memories using natural language. Returns summaries with IDs — use memory-get to retrieve full content.",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        query: z.string().min(1).describe("Natural language search query."),
+        scope: z
+          .enum(["all", "agent", "swarm"])
+          .default("all")
+          .describe(
+            "Search scope: 'all' (own + swarm), 'agent' (own only), 'swarm' (shared only).",
+          ),
+        limit: z.number().int().min(1).max(50).default(10).describe("Max results to return."),
+        source: AgentMemorySourceSchema.optional().describe("Filter by memory source type."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        results: z
+          .array(
+            z.object({
+              id: z.string().uuid(),
+              name: z.string(),
+              summary: z.string().nullable(),
+              source: AgentMemorySourceSchema,
+              scope: AgentMemoryScopeSchema,
+              similarity: z.number().optional(),
+              createdAt: z.string(),
+            }),
+          )
+          .optional(),
+      }),
+    },
+    async ({ query, scope, limit, source }, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID required for memory search." }],
+          structuredContent: {
+            yourAgentId: undefined,
+            success: false,
+            message: "Agent ID required. Are you registered in the swarm?",
+          },
+        };
+      }
+
+      const agent = getAgentById(requestInfo.agentId);
+      const isLead = agent?.isLead ?? false;
+
+      // Try vector search first
+      const queryEmbedding = await getEmbedding(query);
+
+      if (queryEmbedding) {
+        const results = searchMemoriesByVector(queryEmbedding, requestInfo.agentId, {
+          scope: scope as "agent" | "swarm" | "all",
+          limit,
+          source,
+          isLead,
+        });
+
+        const mapped = results.map((r) => ({
+          id: r.id,
+          name: r.name,
+          summary: r.summary,
+          source: r.source,
+          scope: r.scope,
+          similarity: r.similarity,
+          createdAt: r.createdAt,
+        }));
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Found ${mapped.length} memories matching "${query}".`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Found ${mapped.length} memories matching "${query}".`,
+            results: mapped,
+          },
+        };
+      }
+
+      // Fallback: list recent memories (no OPENAI_API_KEY)
+      const recent = listMemoriesByAgent(requestInfo.agentId, {
+        scope: scope as "agent" | "swarm" | "all",
+        limit,
+        isLead,
+      });
+
+      const mapped = recent.map((r) => ({
+        id: r.id,
+        name: r.name,
+        summary: r.summary,
+        source: r.source,
+        scope: r.scope,
+        createdAt: r.createdAt,
+      }));
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Embedding unavailable. Showing ${mapped.length} most recent memories.`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Embedding unavailable (no OPENAI_API_KEY). Showing ${mapped.length} most recent memories.`,
+          results: mapped,
+        },
+      };
+    },
+  );
+};

package/src/tools/my-agent-info.ts

@@ -10,6 +10,8 @@ export const registerMyAgentInfoTool = (server: McpServer) => {
     {
       title: "Get your agent info",
       description: "Returns your agent ID based on the X-Agent-ID header.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({}),
       outputSchema: z.object({
         success: z.boolean(),

package/src/tools/poll-task.ts

@@ -26,6 +26,8 @@ export const registerPollTaskTool = (server: McpServer) => {
       title: "Poll for a task",
       description:
         "Poll for a new task assignment. Returns immediately if there are offered tasks awaiting accept/reject. Also returns count of unassigned tasks in the pool.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({}),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -86,26 +88,6 @@ export const registerPollTaskTool = (server: McpServer) => {
         };
       }
 
-      // Lead agents should not poll for tasks - they use inbox tools instead
-      if (agent.isLead) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Lead agents should not poll for tasks. Use inbox tools to respond to Slack messages, or get-tasks to monitor workers.",
-            },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "Lead agents use inbox and delegation tools instead of polling for tasks.",
-            offeredTasks: [],
-            availableCount: 0,
-            waitedForSeconds: 0,
-          },
-        };
-      }
-
       // Check for offered tasks first - these need immediate attention
       const offeredTasks = getOfferedTasksForAgent(agentId);
       const availableCount = getUnassignedTasksCount();

package/src/tools/post-message.ts

@@ -9,6 +9,7 @@ export const registerPostMessageTool = (server: McpServer) => {
     "post-message",
     {
       title: "Post Message",
+      annotations: { destructiveHint: false },
       description: "Posts a message to a channel for cross-agent communication.",
       inputSchema: z.object({
         channel: z.string().default("general").describe("Channel name (default: 'general')."),

package/src/tools/read-messages.ts

@@ -21,6 +21,8 @@ export const registerReadMessagesTool = (server: McpServer) => {
       title: "Read Messages",
       description:
         "Reads messages from a channel. If no channel is specified, returns unread messages from ALL channels. Supports filtering by unread, mentions, and time range. Automatically marks messages as read.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({
         channel: z
           .string()

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