@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/tools/db-query.ts

@@ -0,0 +1,78 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById } from "@/be/db";
+import { executeReadOnlyQuery } from "@/http/db-query";
+import { createToolRegistrar } from "@/tools/utils";
+
+const MCP_MAX_ROWS = 100;
+
+export const registerDbQueryTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "db-query",
+    {
+      title: "Execute database query",
+      description:
+        "Execute a read-only SQL query against the swarm database. Lead-only. Results capped at 100 rows.",
+      annotations: { readOnlyHint: true },
+      inputSchema: z.object({
+        sql: z.string().describe("SQL query (read-only only — writes are rejected)"),
+        params: z.array(z.any()).optional().default([]).describe("Query parameters"),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        columns: z.array(z.string()),
+        rows: z.array(z.array(z.any())),
+        elapsed: z.number(),
+        total: z.number(),
+        truncated: z.boolean(),
+      }),
+    },
+    async ({ sql, params }, requestInfo, _meta) => {
+      const callerAgent = requestInfo.agentId ? getAgentById(requestInfo.agentId) : null;
+      if (!callerAgent?.isLead) {
+        return {
+          content: [{ type: "text" as const, text: "Only the lead agent can use this tool." }],
+          structuredContent: {
+            success: false,
+            columns: [],
+            rows: [],
+            elapsed: 0,
+            total: 0,
+            truncated: false,
+          },
+        };
+      }
+
+      try {
+        const result = executeReadOnlyQuery(sql, params, MCP_MAX_ROWS);
+        const truncated = result.total > MCP_MAX_ROWS;
+
+        // Build a simple text table for Claude
+        const header = result.columns.join(" | ");
+        const separator = result.columns.map(() => "---").join(" | ");
+        const dataRows = result.rows.map((row) => row.map((v) => String(v ?? "NULL")).join(" | "));
+        const table = [header, separator, ...dataRows].join("\n");
+        const suffix = truncated ? `\n(Showing ${MCP_MAX_ROWS} of ${result.total} rows)` : "";
+        const text = `${table}${suffix}\n\n${result.total} rows in ${result.elapsed}ms`;
+
+        return {
+          content: [{ type: "text" as const, text }],
+          structuredContent: { success: true, ...result, truncated },
+        };
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text" as const, text: `Query error: ${message}` }],
+          structuredContent: {
+            success: false,
+            columns: [],
+            rows: [],
+            elapsed: 0,
+            total: 0,
+            truncated: false,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/delete-channel.ts

@@ -0,0 +1,132 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { deleteChannel, getAgentById, getChannelById, getChannelByName } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+const GENERAL_CHANNEL_ID = "00000000-0000-4000-8000-000000000001";
+
+export const registerDeleteChannelTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "delete-channel",
+    {
+      title: "Delete Channel",
+      description:
+        "Deletes a channel and all its messages. Only the lead agent can delete channels. The default 'general' channel cannot be deleted.",
+      annotations: { destructiveHint: true },
+
+      inputSchema: z.object({
+        channelId: z.string().uuid().optional().describe("The ID of the channel to delete."),
+        name: z.string().optional().describe("Channel name (alternative to channelId)."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async (args, 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." },
+        };
+      }
+
+      if (!args.channelId && !args.name) {
+        return {
+          content: [{ type: "text", text: "Either channelId or name must be provided." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Either channelId or name must be provided.",
+          },
+        };
+      }
+
+      // Check authorization: must be lead agent
+      const callingAgent = getAgentById(requestInfo.agentId);
+      if (!callingAgent?.isLead) {
+        return {
+          content: [
+            { type: "text", text: "Not authorized. Only the lead agent can delete channels." },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Not authorized. Only the lead agent can delete channels.",
+          },
+        };
+      }
+
+      try {
+        // Find channel by ID or name
+        let channel = args.channelId ? getChannelById(args.channelId) : null;
+        if (!channel && args.name) {
+          channel = getChannelByName(args.name);
+        }
+
+        if (!channel) {
+          const identifier = args.channelId || args.name;
+          return {
+            content: [{ type: "text", text: `Channel not found: ${identifier}` }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: `Channel not found: ${identifier}`,
+            },
+          };
+        }
+
+        // Protect the default general channel
+        if (channel.id === GENERAL_CHANNEL_ID) {
+          return {
+            content: [{ type: "text", text: 'The default "general" channel cannot be deleted.' }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: 'The default "general" channel cannot be deleted.',
+            },
+          };
+        }
+
+        const channelName = channel.name;
+        const deleted = deleteChannel(channel.id);
+
+        if (!deleted) {
+          return {
+            content: [{ type: "text", text: "Failed to delete channel." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Failed to delete channel.",
+            },
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Deleted channel "${channelName}" and all its messages.`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Deleted channel "${channelName}".`,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to delete channel: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to delete channel: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/epics/assign-task-to-epic.ts

@@ -8,6 +8,7 @@ export const registerAssignTaskToEpicTool = (server: McpServer) => {
     "assign-task-to-epic",
     {
       title: "Assign Task to Epic",
+      annotations: { idempotentHint: true },
       description: "Assign an existing task to an epic.",
       inputSchema: z.object({
         taskId: z.string().uuid().describe("The ID of the task to assign"),

package/src/tools/epics/create-epic.ts

@@ -8,6 +8,7 @@ export const registerCreateEpicTool = (server: McpServer) => {
     "create-epic",
     {
       title: "Create Epic",
+      annotations: { destructiveHint: false },
       description: "Create a new epic (project) to organize related tasks.",
       inputSchema: z.object({
         name: z.string().min(1).max(200).describe("Unique name for the epic"),
@@ -22,8 +23,8 @@ export const registerCreateEpicTool = (server: McpServer) => {
         planDocPath: z.string().optional().describe("Path to plan document"),
         slackChannelId: z.string().optional(),
         slackThreadTs: z.string().optional(),
-        githubRepo: z.string().optional(),
-        githubMilestone: z.string().optional(),
+        vcsRepo: z.string().optional(),
+        vcsMilestone: z.string().optional(),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),

package/src/tools/epics/delete-epic.ts

@@ -10,6 +10,8 @@ export const registerDeleteEpicTool = (server: McpServer) => {
       title: "Delete Epic",
       description:
         "Delete an epic. Only the creator or swarm lead can delete. Tasks are unassigned, not deleted.",
+      annotations: { destructiveHint: true },
+
       inputSchema: z.object({
         epicId: z.string().uuid().optional().describe("The ID of the epic to delete"),
         name: z.string().optional().describe("Epic name (alternative to ID)"),

package/src/tools/epics/get-epic-details.ts

@@ -10,6 +10,8 @@ export const registerGetEpicDetailsTool = (server: McpServer) => {
       title: "Get Epic Details",
       description:
         "Get detailed information about a specific epic, including progress and associated tasks.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({
         epicId: z.string().uuid().optional().describe("The ID of the epic"),
         name: z.string().optional().describe("The name of the epic (alternative to ID)"),

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

@@ -10,6 +10,8 @@ export const registerListEpicsTool = (server: McpServer) => {
     {
       title: "List Epics",
       description: "List epics with optional filters. Returns epics with progress information.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({
         status: z
           .enum(["draft", "active", "paused", "completed", "cancelled"])

package/src/tools/epics/unassign-task-from-epic.ts

@@ -8,6 +8,7 @@ export const registerUnassignTaskFromEpicTool = (server: McpServer) => {
     "unassign-task-from-epic",
     {
       title: "Unassign Task from Epic",
+      annotations: { idempotentHint: true },
       description: "Remove a task from its epic. The task is kept but no longer associated.",
       inputSchema: z.object({
         taskId: z.string().uuid().describe("The ID of the task to unassign"),

package/src/tools/epics/update-epic.ts

@@ -9,6 +9,7 @@ export const registerUpdateEpicTool = (server: McpServer) => {
     "update-epic",
     {
       title: "Update Epic",
+      annotations: { idempotentHint: true },
       description:
         "Update an existing epic. Only the creator, lead agent, or swarm lead can update.",
       inputSchema: z.object({
@@ -30,8 +31,9 @@ export const registerUpdateEpicTool = (server: McpServer) => {
         planDocPath: z.string().optional(),
         slackChannelId: z.string().optional(),
         slackThreadTs: z.string().optional(),
-        githubRepo: z.string().optional(),
-        githubMilestone: z.string().optional(),
+        vcsRepo: z.string().optional(),
+        vcsMilestone: z.string().optional(),
+        nextSteps: z.string().optional().describe("Notes on what to do next for this epic"),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -130,8 +132,9 @@ export const registerUpdateEpicTool = (server: McpServer) => {
         if (args.planDocPath !== undefined) updateData.planDocPath = args.planDocPath;
         if (args.slackChannelId !== undefined) updateData.slackChannelId = args.slackChannelId;
         if (args.slackThreadTs !== undefined) updateData.slackThreadTs = args.slackThreadTs;
-        if (args.githubRepo !== undefined) updateData.githubRepo = args.githubRepo;
-        if (args.githubMilestone !== undefined) updateData.githubMilestone = args.githubMilestone;
+        if (args.vcsRepo !== undefined) updateData.vcsRepo = args.vcsRepo;
+        if (args.vcsMilestone !== undefined) updateData.vcsMilestone = args.vcsMilestone;
+        if (args.nextSteps !== undefined) updateData.nextSteps = args.nextSteps;
 
         const updatedEpic = updateEpic(epic.id, updateData);
 

package/src/tools/get-swarm.ts

@@ -10,6 +10,8 @@ export const registerGetSwarmTool = (server: McpServer) => {
     {
       title: "Get the agent swarm",
       description: "Returns a list of agents in the swarm without their tasks.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({
         a: z.string().optional(),
       }),

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

@@ -11,6 +11,8 @@ export const registerGetTaskDetailsTool = (server: McpServer) => {
       title: "Get task details",
       description:
         "Returns detailed information about a specific task, including output, failure reason, and log history.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({
         taskId: z.uuid().describe("The ID of the task to get details for."),
       }),

package/src/tools/get-tasks.ts

@@ -27,6 +27,8 @@ export const registerGetTasksTool = (server: McpServer) => {
       title: "Get tasks",
       description:
         "Returns a list of tasks in the swarm with various filters. Sorted by priority (desc) then lastUpdatedAt (desc).",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({
         status: AgentTaskStatusSchema.optional().describe(
           "Filter by task status (unassigned, offered, pending, in_progress, completed, failed).",
@@ -41,6 +43,15 @@ export const registerGetTasksTool = (server: McpServer) => {
         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()
@@ -55,7 +66,19 @@ export const registerGetTasksTool = (server: McpServer) => {
       }),
     },
     async (
-      { status, mineOnly, unassigned, offeredToMe, readyOnly, taskType, tags, search, limit },
+      {
+        status,
+        mineOnly,
+        unassigned,
+        offeredToMe,
+        readyOnly,
+        taskType,
+        tags,
+        search,
+        scheduleId,
+        includeHeartbeat,
+        limit,
+      },
       requestInfo,
       _meta,
     ) => {
@@ -71,6 +94,8 @@ export const registerGetTasksTool = (server: McpServer) => {
         taskType,
         tags,
         search,
+        scheduleId,
+        includeHeartbeat,
         limit,
       });
 
@@ -100,6 +125,7 @@ export const registerGetTasksTool = (server: McpServer) => {
       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(", ")})` : "";
 

package/src/tools/inject-learning.ts

@@ -0,0 +1,106 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createMemory, getAgentById, updateMemoryEmbedding } from "@/be/db";
+import { getEmbedding, serializeEmbedding } from "@/be/embedding";
+import { createToolRegistrar } from "@/tools/utils";
+
+const LearningCategoryEnum = z.enum([
+  "mistake-pattern",
+  "best-practice",
+  "codebase-knowledge",
+  "preference",
+]);
+
+export const registerInjectLearningTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "inject-learning",
+    {
+      title: "Inject learning into worker memory",
+      annotations: { destructiveHint: false },
+      description:
+        "Allows the lead agent to push learnings into a worker's memory. The learning will be stored as a searchable memory entry that the worker can recall in future sessions.",
+      inputSchema: z.object({
+        agentId: z.uuid().describe("Target worker agent ID"),
+        learning: z.string().min(1).describe("The learning content to inject"),
+        category: LearningCategoryEnum.describe(
+          "Category of the learning: mistake-pattern, best-practice, codebase-knowledge, or preference",
+        ),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        memoryId: z.string().optional(),
+      }),
+    },
+    async ({ agentId: targetAgentId, learning, category }, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID not found." }],
+          structuredContent: {
+            success: false,
+            message: 'Agent ID not found. The MCP client should define the "X-Agent-ID" header.',
+          },
+        };
+      }
+
+      // Validate caller is the lead agent
+      const callerAgent = getAgentById(requestInfo.agentId);
+      if (!callerAgent || !callerAgent.isLead) {
+        return {
+          content: [{ type: "text", text: "Only the lead agent can inject learnings." }],
+          structuredContent: {
+            success: false,
+            message: "Only the lead agent can inject learnings into worker memory.",
+          },
+        };
+      }
+
+      // Validate target agent exists
+      const targetAgent = getAgentById(targetAgentId);
+      if (!targetAgent) {
+        return {
+          content: [{ type: "text", text: `Agent "${targetAgentId}" not found.` }],
+          structuredContent: {
+            success: false,
+            message: `Agent with ID "${targetAgentId}" not found in the swarm.`,
+          },
+        };
+      }
+
+      // Create swarm-scoped memory — lead learnings are organizational knowledge visible to all workers
+      const content = `[Lead Feedback — ${category}]\n\n${learning}`;
+      const memory = createMemory({
+        agentId: targetAgentId,
+        scope: "swarm",
+        name: `Lead feedback: ${category} — ${learning.slice(0, 60)}`,
+        content,
+        source: "manual",
+      });
+
+      // Generate and store embedding (async, best-effort)
+      try {
+        const embedding = await getEmbedding(content);
+        if (embedding) {
+          updateMemoryEmbedding(memory.id, serializeEmbedding(embedding));
+        }
+      } catch {
+        // Non-blocking — memory was created, embedding is optional
+      }
+
+      const targetName = targetAgent.name || targetAgentId.slice(0, 8);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Learning injected into ${targetName}'s memory (category: ${category}).`,
+          },
+        ],
+        structuredContent: {
+          success: true,
+          message: `Learning injected into ${targetName}'s memory (category: ${category}).`,
+          memoryId: memory.id,
+        },
+      };
+    },
+  );
+};

package/src/tools/join-swarm.ts

@@ -1,12 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
+import { createAgent, getAllAgents, getDb, updateAgentProfile } from "@/be/db";
 import {
-  createAgent,
   generateDefaultClaudeMd,
-  getAllAgents,
-  getDb,
-  updateAgentProfile,
-} from "@/be/db";
+  generateDefaultIdentityMd,
+  generateDefaultSoulMd,
+} from "@/prompts/defaults";
 import { createToolRegistrar } from "@/tools/utils";
 import { AgentSchema } from "@/types";
 
@@ -17,6 +16,8 @@ export const registerJoinSwarmTool = (server: McpServer) => {
       title: "Join the agent swarm",
       description:
         "Tool for an agent to join the swarm of agents with optional profile information.",
+      annotations: { idempotentHint: true },
+
       inputSchema: z.object({
         requestedId: z
           .string()
@@ -96,20 +97,29 @@ export const registerJoinSwarmTool = (server: McpServer) => {
             capabilities: [],
           });
 
-          // Generate default CLAUDE.md with agent info
+          // Generate default CLAUDE.md, SOUL.md, and IDENTITY.md
           const defaultClaudeMd = generateDefaultClaudeMd({
             name,
             description,
             role,
             capabilities,
           });
+          const defaultSoulMd = generateDefaultSoulMd({ name, role });
+          const defaultIdentityMd = generateDefaultIdentityMd({
+            name,
+            description,
+            role,
+            capabilities,
+          });
 
-          // Update profile with any provided fields and the default CLAUDE.md
+          // Update profile with any provided fields and the default templates
           const updatedAgent = updateAgentProfile(agent.id, {
             description,
             role,
             capabilities,
             claudeMd: defaultClaudeMd,
+            soulMd: defaultSoulMd,
+            identityMd: defaultIdentityMd,
           });
 
           return updatedAgent ?? agent;

package/src/tools/list-channels.ts

@@ -10,6 +10,8 @@ export const registerListChannelsTool = (server: McpServer) => {
     {
       title: "List Channels",
       description: "Lists all available channels for cross-agent communication.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({}),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),

package/src/tools/list-services.ts

@@ -11,6 +11,8 @@ export const registerListServicesTool = (server: McpServer) => {
       title: "List Services",
       description:
         "Query services registered by agents in the swarm. Use this to discover services exposed by other agents.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({
         agentId: z.uuid().optional().describe("Filter by specific agent ID."),
         name: z.string().optional().describe("Filter by service name (partial match)."),

package/src/tools/memory-get.ts

@@ -0,0 +1,56 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getMemoryById } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { AgentMemorySchema } from "@/types";
+
+export const registerMemoryGetTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "memory-get",
+    {
+      title: "Get memory details",
+      description:
+        "Retrieve the full content of a specific memory by its ID. Use memory-search to find memory IDs first.",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        memoryId: z.uuid().describe("The ID of the memory to retrieve."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        memory: AgentMemorySchema.optional(),
+      }),
+    },
+    async ({ memoryId }, requestInfo, _meta) => {
+      const memory = getMemoryById(memoryId);
+
+      if (!memory) {
+        return {
+          content: [{ type: "text", text: `Memory "${memoryId}" not found.` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Memory "${memoryId}" not found.`,
+          },
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Memory "${memory.name}" retrieved.\n\n${memory.content}`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Memory "${memory.name}" retrieved.`,
+          memory,
+        },
+      };
+    },
+  );
+};