@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/src/tools/swarm-config/delete-config.ts

@@ -0,0 +1,87 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { deleteSwarmConfig, getSwarmConfigById } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerDeleteConfigTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "delete-config",
+    {
+      title: "Delete Config",
+      description:
+        "Delete a swarm configuration entry by its ID. Use list-config to find config IDs first.",
+      annotations: { destructiveHint: true },
+
+      inputSchema: z.object({
+        id: z.string().uuid().describe("The config entry ID to delete."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async ({ id }, requestInfo) => {
+      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 {
+        // Check if config exists first for a better error message
+        const existing = getSwarmConfigById(id);
+        if (!existing) {
+          return {
+            content: [{ type: "text", text: `Config entry "${id}" not found.` }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: `Config entry "${id}" not found.`,
+            },
+          };
+        }
+
+        const deleted = deleteSwarmConfig(id);
+        if (!deleted) {
+          return {
+            content: [{ type: "text", text: `Failed to delete config entry "${id}".` }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: `Failed to delete config entry "${id}".`,
+            },
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Config "${existing.key}" (scope: ${existing.scope}${existing.scopeId ? `, scopeId: ${existing.scopeId}` : ""}) deleted successfully.`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Config "${existing.key}" deleted successfully.`,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to delete config: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to delete config: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/swarm-config/get-config.ts

@@ -0,0 +1,108 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getResolvedConfig, maskSecrets } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { SwarmConfigSchema } from "@/types";
+
+export const registerGetConfigTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "get-config",
+    {
+      title: "Get Config",
+      description:
+        "Get resolved configuration values with scope resolution (repo > agent > global). Returns one entry per unique key with the most-specific scope winning. Use includeSecrets=true to see secret values.",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        agentId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe("Agent ID for scope resolution. Omit for global-only configs."),
+        repoId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe("Repo ID for scope resolution. Omit for agent/global-only configs."),
+        key: z
+          .string()
+          .optional()
+          .describe("Filter by specific key. If omitted, returns all resolved configs."),
+        includeSecrets: z
+          .boolean()
+          .optional()
+          .describe("If true, include actual secret values (default: false, secrets are masked)."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        configs: z.array(SwarmConfigSchema),
+        count: z.number(),
+      }),
+    },
+    async ({ agentId, repoId, key, includeSecrets }, requestInfo) => {
+      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.',
+            configs: [],
+            count: 0,
+          },
+        };
+      }
+
+      try {
+        let configs = getResolvedConfig(agentId, repoId);
+
+        if (key) {
+          configs = configs.filter((c) => c.key === key);
+        }
+
+        const result = includeSecrets ? configs : maskSecrets(configs);
+        const count = result.length;
+
+        const configList =
+          count === 0
+            ? "No configs found."
+            : result
+                .map(
+                  (c) =>
+                    `- ${c.key}=${c.isSecret && !includeSecrets ? "********" : c.value} (scope: ${c.scope}${c.scopeId ? `, scopeId: ${c.scopeId}` : ""})`,
+                )
+                .join("\n");
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                count === 0 ? "No configs found." : `Found ${count} config(s):\n\n${configList}`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: count === 0 ? "No configs found." : `Found ${count} config(s).`,
+            configs: result,
+            count,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to get config: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to get config: ${message}`,
+            configs: [],
+            count: 0,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/swarm-config/index.ts

@@ -0,0 +1,4 @@
+export { registerDeleteConfigTool } from "./delete-config";
+export { registerGetConfigTool } from "./get-config";
+export { registerListConfigTool } from "./list-config";
+export { registerSetConfigTool } from "./set-config";

package/src/tools/swarm-config/list-config.ts

@@ -0,0 +1,99 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getSwarmConfigs, maskSecrets } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { SwarmConfigSchema, SwarmConfigScopeSchema } from "@/types";
+
+export const registerListConfigTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "list-config",
+    {
+      title: "List Config",
+      description:
+        "List raw config entries with optional filters. Unlike get-config, this returns raw entries without scope resolution — useful for seeing exactly what's configured at each scope level.",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        scope: SwarmConfigScopeSchema.optional().describe(
+          "Filter by scope: 'global', 'agent', or 'repo'.",
+        ),
+        scopeId: z.string().uuid().optional().describe("Filter by agent ID or repo ID."),
+        key: z.string().optional().describe("Filter by specific key."),
+        includeSecrets: z
+          .boolean()
+          .optional()
+          .describe("If true, include actual secret values (default: false)."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        configs: z.array(SwarmConfigSchema),
+        count: z.number(),
+      }),
+    },
+    async ({ scope, scopeId, key, includeSecrets }, requestInfo) => {
+      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.',
+            configs: [],
+            count: 0,
+          },
+        };
+      }
+
+      try {
+        const configs = getSwarmConfigs({
+          scope,
+          scopeId,
+          key,
+        });
+
+        const result = includeSecrets ? configs : maskSecrets(configs);
+        const count = result.length;
+
+        const configList =
+          count === 0
+            ? "No configs found."
+            : result
+                .map(
+                  (c) =>
+                    `- [${c.scope}${c.scopeId ? `:${c.scopeId}` : ""}] ${c.key}=${c.isSecret && !includeSecrets ? "********" : c.value}${c.description ? ` — ${c.description}` : ""}`,
+                )
+                .join("\n");
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                count === 0 ? "No configs found." : `Found ${count} config(s):\n\n${configList}`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: count === 0 ? "No configs found." : `Found ${count} config(s).`,
+            configs: result,
+            count,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to list configs: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to list configs: ${message}`,
+            configs: [],
+            count: 0,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/swarm-config/set-config.ts

@@ -0,0 +1,118 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { maskSecrets, upsertSwarmConfig } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { SwarmConfigSchema, SwarmConfigScopeSchema } from "@/types";
+
+export const registerSetConfigTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "set-config",
+    {
+      title: "Set Config",
+      description:
+        "Set or update a swarm configuration value. Upserts by (scope, scopeId, key). Use scope='global' for server-wide settings, 'agent' for agent-specific, or 'repo' for repo-specific. Set isSecret=true to mask the value in API responses.",
+      annotations: { idempotentHint: true },
+
+      inputSchema: z.object({
+        scope: SwarmConfigScopeSchema.describe("Config scope: 'global', 'agent', or 'repo'."),
+        scopeId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe(
+            "Agent ID or repo ID. Required for 'agent' and 'repo' scopes, omit for 'global'.",
+          ),
+        key: z
+          .string()
+          .min(1)
+          .max(255)
+          .describe("Configuration key (e.g., 'AGENTMAIL_WEBHOOK_SECRET')."),
+        value: z.string().describe("Configuration value."),
+        isSecret: z
+          .boolean()
+          .optional()
+          .describe("If true, value is masked in API responses (default: false)."),
+        envPath: z
+          .string()
+          .optional()
+          .describe("Optional: file path to write the value as KEY=VALUE in a .env file."),
+        description: z
+          .string()
+          .optional()
+          .describe("Optional human-readable description of this config entry."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        config: SwarmConfigSchema.optional(),
+      }),
+    },
+    async ({ scope, scopeId, key, value, isSecret, envPath, description }, requestInfo) => {
+      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 {
+        if (scope !== "global" && !scopeId) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `scopeId is required for scope '${scope}'. Provide an agent ID or repo ID.`,
+              },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: `scopeId is required for scope '${scope}'.`,
+            },
+          };
+        }
+
+        const config = upsertSwarmConfig({
+          scope,
+          scopeId: scope === "global" ? null : scopeId,
+          key,
+          value,
+          isSecret,
+          envPath,
+          description,
+        });
+
+        const [masked] = maskSecrets([config]);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Config "${key}" set successfully (scope: ${scope}${scopeId ? `, scopeId: ${scopeId}` : ""}).`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Config "${key}" set successfully.`,
+            config: masked,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to set config: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to set config: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/task-action.ts

@@ -33,6 +33,7 @@ export const registerTaskActionTool = (server: McpServer) => {
     "task-action",
     {
       title: "Task Pool Actions",
+      annotations: { destructiveHint: false },
       description:
         "Perform task pool operations: create unassigned tasks, claim/release tasks from pool, accept/reject offered tasks.",
       inputSchema: z.object({
@@ -58,6 +59,21 @@ export const registerTaskActionTool = (server: McpServer) => {
         taskId: z.uuid().optional().describe("Task ID (required for claim/release/accept/reject)."),
         // For 'reject' action:
         reason: z.string().optional().describe("Reason for rejection (optional for 'reject')."),
+        // For 'create' action:
+        dir: z
+          .string()
+          .min(1)
+          .startsWith("/")
+          .optional()
+          .describe(
+            "Working directory (absolute path) for the agent to start in. Only used with 'create' action.",
+          ),
+        model: z
+          .enum(["haiku", "sonnet", "opus"])
+          .optional()
+          .describe(
+            "Model to use for the created task ('haiku', 'sonnet', or 'opus'). Only used with 'create' action.",
+          ),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -67,7 +83,8 @@ export const registerTaskActionTool = (server: McpServer) => {
       }),
     },
     async (input, requestInfo, _meta) => {
-      const { action, task, taskType, tags, priority, dependsOn, taskId, reason } = input;
+      const { action, task, taskType, tags, priority, dependsOn, taskId, reason, dir, model } =
+        input;
 
       if (!requestInfo.agentId) {
         return {
@@ -96,6 +113,8 @@ export const registerTaskActionTool = (server: McpServer) => {
               tags,
               priority,
               dependsOn,
+              dir,
+              model,
             });
             return {
               success: true,
@@ -117,6 +136,8 @@ export const registerTaskActionTool = (server: McpServer) => {
                 message: `You have no capacity (${activeCount}/${agent?.maxTasks ?? 1} tasks). Complete a task first.`,
               };
             }
+            // Pre-checks for informative error messages (the atomic UPDATE in
+            // claimTask is the real guard against race conditions)
             const existingTask = getTaskById(taskId);
             if (!existingTask) {
               return { success: false, message: `Task "${taskId}" not found.` };
@@ -124,7 +145,7 @@ export const registerTaskActionTool = (server: McpServer) => {
             if (existingTask.status !== "unassigned") {
               return {
                 success: false,
-                message: `Task "${taskId}" is not unassigned (status: ${existingTask.status}).`,
+                message: `Task "${taskId}" is not unassigned (status: ${existingTask.status}). It may have been claimed by another agent.`,
               };
             }
             // Check if task dependencies are met
@@ -135,9 +156,13 @@ export const registerTaskActionTool = (server: McpServer) => {
                 message: `Task "${taskId}" has unmet dependencies: ${blockedBy.join(", ")}. Cannot claim until dependencies are completed.`,
               };
             }
+            // Atomic claim — only one agent can win this race
             const claimedTask = claimTask(taskId, agentId);
             if (!claimedTask) {
-              return { success: false, message: `Failed to claim task "${taskId}".` };
+              return {
+                success: false,
+                message: `Task "${taskId}" was already claimed by another agent. Try a different task.`,
+              };
             }
             return {
               success: true,
@@ -157,10 +182,10 @@ export const registerTaskActionTool = (server: McpServer) => {
             if (existingTask.agentId !== agentId) {
               return { success: false, message: `Task "${taskId}" is not assigned to you.` };
             }
-            if (existingTask.status !== "pending") {
+            if (existingTask.status !== "pending" && existingTask.status !== "in_progress") {
               return {
                 success: false,
-                message: `Cannot release task in status "${existingTask.status}". Only 'pending' tasks can be released.`,
+                message: `Cannot release task in status "${existingTask.status}". Only 'pending' or 'in_progress' tasks can be released.`,
               };
             }
             const releasedTask = releaseTask(taskId);

package/src/tools/task-dedup.ts

@@ -0,0 +1,97 @@
+import { findRecentSimilarTasks } from "@/be/db";
+import type { AgentTask } from "@/types";
+
+/**
+ * Jaccard similarity on word sets.
+ * Tokenizes both strings into lowercase word sets and computes |intersection| / |union|.
+ */
+export function jaccardSimilarity(a: string, b: string): number {
+  const tokenize = (s: string) =>
+    new Set(
+      s
+        .toLowerCase()
+        .replace(/[^\w\s]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 0),
+    );
+
+  const wordsA = tokenize(a);
+  const wordsB = tokenize(b);
+
+  if (wordsA.size === 0 && wordsB.size === 0) return 1;
+  if (wordsA.size === 0 || wordsB.size === 0) return 0;
+
+  let intersection = 0;
+  for (const w of wordsA) {
+    if (wordsB.has(w)) intersection++;
+  }
+  const union = new Set([...wordsA, ...wordsB]).size;
+  return intersection / union;
+}
+
+/** Similarity above which any two task descriptions are considered duplicates */
+const HIGH_SIMILARITY_THRESHOLD = 0.8;
+/** Lower threshold used when the tasks also target the same agent */
+const SAME_AGENT_SIMILARITY_THRESHOLD = 0.6;
+
+export interface DedupMatch {
+  task: AgentTask;
+  reason: string;
+}
+
+/**
+ * Check for duplicate tasks created recently.
+ * Returns the first matching duplicate, or null if none found.
+ */
+export function findDuplicateTask(opts: {
+  taskDescription: string;
+  creatorAgentId: string;
+  targetAgentId?: string;
+  slackChannelId?: string;
+  slackThreadTs?: string;
+  windowMinutes?: number;
+}): DedupMatch | null {
+  const recentTasks = findRecentSimilarTasks({
+    creatorAgentId: opts.creatorAgentId,
+    windowMinutes: opts.windowMinutes ?? 10,
+  });
+
+  for (const existing of recentTasks) {
+    // 1. Exact Slack thread match — definitely a duplicate
+    if (
+      opts.slackChannelId &&
+      opts.slackThreadTs &&
+      existing.slackChannelId === opts.slackChannelId &&
+      existing.slackThreadTs === opts.slackThreadTs
+    ) {
+      return {
+        task: existing,
+        reason: `same Slack thread (${opts.slackChannelId}/${opts.slackThreadTs})`,
+      };
+    }
+
+    const similarity = jaccardSimilarity(existing.task, opts.taskDescription);
+
+    // 2. Very similar task description — likely duplicate regardless of target
+    if (similarity > HIGH_SIMILARITY_THRESHOLD) {
+      return {
+        task: existing,
+        reason: `similar task description (${(similarity * 100).toFixed(0)}% match)`,
+      };
+    }
+
+    // 3. Same target agent + moderately similar task — lower threshold
+    if (
+      opts.targetAgentId &&
+      existing.agentId === opts.targetAgentId &&
+      similarity > SAME_AGENT_SIMILARITY_THRESHOLD
+    ) {
+      return {
+        task: existing,
+        reason: `similar task to same agent (${(similarity * 100).toFixed(0)}% match)`,
+      };
+    }
+  }
+
+  return null;
+}