@desplega.ai/agent-swarm 1.2.0 → 1.9.0

package/src/slack/router.ts

@@ -0,0 +1,170 @@
+import { getAgentById, getAgentWorkingOnThread, getAllAgents } from "../be/db";
+import type { AgentMatch } from "./types";
+
+interface ThreadContext {
+  channelId: string;
+  threadTs: string;
+}
+
+// Common 3-letter words to exclude from matching
+const COMMON_WORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "are",
+  "but",
+  "not",
+  "you",
+  "all",
+  "can",
+  "had",
+  "her",
+  "was",
+  "one",
+  "our",
+  "out",
+  "has",
+  "his",
+  "how",
+  "its",
+  "let",
+  "may",
+  "new",
+  "now",
+  "old",
+  "see",
+  "way",
+  "who",
+  "boy",
+  "did",
+  "get",
+  "say",
+  "she",
+  "too",
+  "use",
+  "hey",
+  "hi",
+  "hello",
+  "please",
+  "help",
+]);
+
+/**
+ * Check if a word is suitable for agent name matching.
+ * Allows 3+ char words if they're not common words.
+ * Always allows uppercase words (CEO, CTO, etc).
+ */
+function isMatchableWord(word: string): boolean {
+  if (word.length < 3) return false;
+  // Always allow fully uppercase words (acronyms like CEO, CTO)
+  if (word === word.toUpperCase() && word.length >= 3) return true;
+  // Allow 3+ char words that aren't common
+  if (word.length >= 3 && !COMMON_WORDS.has(word.toLowerCase())) return true;
+  return false;
+}
+
+/**
+ * Routes a Slack message to the appropriate agent(s) based on mentions.
+ *
+ * Routing rules:
+ * - `swarm#<uuid>` → exact agent by ID
+ * - `swarm#all` → all non-lead agents
+ * - Partial name match (3+ chars, not common words) → agent by name
+ * - Multiple partial matches → route to lead (let lead decide)
+ * - Thread follow-up (no match but agent working on thread) → route to that agent
+ * - Bot @mention only → lead agent
+ */
+export function routeMessage(
+  text: string,
+  _botUserId: string,
+  botMentioned: boolean,
+  threadContext?: ThreadContext,
+): AgentMatch[] {
+  const matches: AgentMatch[] = [];
+  const agents = getAllAgents().filter((a) => a.status !== "offline");
+
+  // Check for explicit swarm#<id> syntax
+  const idMatches = text.matchAll(/swarm#([a-f0-9-]{36})/gi);
+  for (const match of idMatches) {
+    const agentId = match[1];
+    if (!agentId) continue;
+    const agent = getAgentById(agentId);
+    if (agent && agent.status !== "offline") {
+      matches.push({ agent, matchedText: match[0] });
+    }
+  }
+
+  // Check for swarm#all broadcast
+  if (/swarm#all/i.test(text)) {
+    const nonLeadAgents = agents.filter((a) => !a.isLead);
+    for (const agent of nonLeadAgents) {
+      if (!matches.some((m) => m.agent.id === agent.id)) {
+        matches.push({ agent, matchedText: "swarm#all" });
+      }
+    }
+  }
+
+  // Check for partial name matches (3+ chars, not common words)
+  if (matches.length === 0) {
+    for (const agent of agents) {
+      const nameWords = agent.name.split(/\s+/).filter(isMatchableWord);
+      for (const word of nameWords) {
+        const regex = new RegExp(`\\b${escapeRegex(word)}\\b`, "i");
+        if (regex.test(text)) {
+          if (!matches.some((m) => m.agent.id === agent.id)) {
+            matches.push({ agent, matchedText: word });
+          }
+          break;
+        }
+      }
+    }
+
+    // If multiple agents matched a partial name, route to lead instead (let lead decide)
+    if (matches.length > 1) {
+      const lead = agents.find((a) => a.isLead);
+      if (lead) {
+        const matchedWords = matches.map((m) => m.matchedText).join(", ");
+        const matchedAgents = matches.map((m) => m.agent.name).join(", ");
+        return [
+          {
+            agent: lead,
+            matchedText: `ambiguous match "${matchedWords}" (could be: ${matchedAgents})`,
+          },
+        ];
+      }
+    }
+  }
+
+  // Thread follow-up: If no matches and we're in a thread, check if an agent is working on it
+  if (matches.length === 0 && threadContext) {
+    const workingAgent = getAgentWorkingOnThread(threadContext.channelId, threadContext.threadTs);
+    if (workingAgent && workingAgent.status !== "offline") {
+      matches.push({ agent: workingAgent, matchedText: "thread follow-up" });
+    }
+  }
+
+  // If only bot was mentioned and no agents matched, route to lead
+  if (matches.length === 0 && botMentioned) {
+    const lead = agents.find((a) => a.isLead);
+    if (lead) {
+      matches.push({ agent: lead, matchedText: "@bot" });
+    }
+  }
+
+  return matches;
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Extracts the task description from a message, removing bot mentions and agent references.
+ */
+export function extractTaskFromMessage(text: string, botUserId: string): string {
+  return text
+    .replace(new RegExp(`<@${botUserId}>`, "g"), "") // Remove bot mentions
+    .replace(/swarm#[a-f0-9-]{36}/gi, "") // Remove swarm#<id>
+    .replace(/swarm#all/gi, "") // Remove swarm#all
+    .trim();
+}

package/src/slack/types.ts

@@ -0,0 +1,20 @@
+import type { Agent } from "../types";
+
+export interface SlackMessageContext {
+  channelId: string;
+  threadTs?: string;
+  userId: string;
+  text: string;
+  botUserId: string;
+}
+
+export interface AgentMatch {
+  agent: Agent;
+  matchedText: string;
+}
+
+export interface SlackConfig {
+  botToken: string;
+  appToken: string;
+  signingSecret?: string;
+}

package/src/slack/watcher.ts

@@ -0,0 +1,119 @@
+import { getCompletedSlackTasks, getInProgressSlackTasks } from "../be/db";
+import { getSlackApp } from "./app";
+import { sendProgressUpdate, sendTaskResponse } from "./responses";
+
+let watcherInterval: ReturnType<typeof setInterval> | null = null;
+let isProcessing = false;
+
+// Track notified completion tasks (taskId -> timestamp)
+const notifiedCompletions = new Map<string, number>();
+
+// Track sent progress messages (taskId -> last progress text)
+const sentProgress = new Map<string, string>();
+
+// Track in-flight sends to prevent race conditions
+const pendingSends = new Set<string>();
+
+// Track last send time per task to throttle (taskId -> timestamp)
+const lastSendTime = new Map<string, number>();
+const MIN_SEND_INTERVAL = 1000; // Don't send for same task within 1 second
+
+/**
+ * Start watching for Slack task updates and sending responses.
+ */
+export function startTaskWatcher(intervalMs = 3000): void {
+  if (watcherInterval) {
+    console.log("[Slack] Task watcher already running");
+    return;
+  }
+
+  // Initialize with existing completed tasks to avoid re-notifying on restart
+  const existingCompleted = getCompletedSlackTasks();
+  const now = Date.now();
+  for (const task of existingCompleted) {
+    notifiedCompletions.set(task.id, now);
+  }
+  console.log(`[Slack] Initialized with ${existingCompleted.length} existing completed tasks`);
+
+  watcherInterval = setInterval(async () => {
+    // Prevent overlapping processing cycles
+    if (isProcessing || !getSlackApp()) return;
+    isProcessing = true;
+
+    try {
+      // Check for progress updates on in-progress tasks
+      const inProgressTasks = getInProgressSlackTasks();
+      const now = Date.now();
+      for (const task of inProgressTasks) {
+        const progressKey = `progress:${task.id}`;
+
+        // Skip if already sending or sent recently (throttle)
+        if (pendingSends.has(progressKey)) continue;
+        const lastSent = lastSendTime.get(progressKey);
+        if (lastSent && now - lastSent < MIN_SEND_INTERVAL) continue;
+
+        const lastSentProgress = sentProgress.get(task.id);
+        // Only send if progress exists and is different from last sent
+        if (task.progress && task.progress !== lastSentProgress) {
+          // Mark as pending and sent BEFORE sending
+          pendingSends.add(progressKey);
+          sentProgress.set(task.id, task.progress);
+          lastSendTime.set(progressKey, now);
+          try {
+            await sendProgressUpdate(task, task.progress);
+            console.log(`[Slack] Sent progress update for task ${task.id.slice(0, 8)}`);
+          } catch (error) {
+            // If send fails, clear markers so we can retry
+            sentProgress.delete(task.id);
+            lastSendTime.delete(progressKey);
+            console.error(`[Slack] Failed to send progress:`, error);
+          } finally {
+            pendingSends.delete(progressKey);
+          }
+        }
+      }
+
+      // Check for completed tasks
+      const completedTasks = getCompletedSlackTasks();
+      for (const task of completedTasks) {
+        const completionKey = `completion:${task.id}`;
+
+        // Skip if already notified or currently sending or sent recently
+        if (notifiedCompletions.has(task.id) || pendingSends.has(completionKey)) continue;
+        const lastSent = lastSendTime.get(completionKey);
+        if (lastSent && now - lastSent < MIN_SEND_INTERVAL) continue;
+
+        // Mark as pending and notified BEFORE sending
+        pendingSends.add(completionKey);
+        notifiedCompletions.set(task.id, now);
+        lastSendTime.set(completionKey, now);
+        try {
+          await sendTaskResponse(task);
+          // Clean up progress tracking
+          sentProgress.delete(task.id);
+          console.log(`[Slack] Sent ${task.status} response for task ${task.id.slice(0, 8)}`);
+        } catch (error) {
+          // If send fails, remove from notified so we can retry
+          notifiedCompletions.delete(task.id);
+          lastSendTime.delete(completionKey);
+          console.error(`[Slack] Failed to send completion:`, error);
+        } finally {
+          pendingSends.delete(completionKey);
+        }
+      }
+    } finally {
+      isProcessing = false;
+    }
+  }, intervalMs);
+
+  console.log(`[Slack] Task watcher started (interval: ${intervalMs}ms)`);
+}
+
+export function stopTaskWatcher(): void {
+  if (watcherInterval) {
+    clearInterval(watcherInterval);
+    watcherInterval = null;
+    isProcessing = false;
+    console.log("[Slack] Task watcher stopped");
+  }
+}

package/src/tools/create-channel.ts

@@ -0,0 +1,80 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createChannel, getChannelByName } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { ChannelSchema, ChannelTypeSchema } from "@/types";
+
+export const registerCreateChannelTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "create-channel",
+    {
+      title: "Create Channel",
+      description: "Creates a new channel for cross-agent communication.",
+      inputSchema: z.object({
+        name: z.string().min(1).max(100).describe("Channel name (must be unique)."),
+        description: z.string().max(500).optional().describe("Channel description."),
+        type: ChannelTypeSchema.optional().describe("Channel type: 'public' (default) or 'dm'."),
+        participants: z.array(z.uuid()).optional().describe("Agent IDs for DM channels."),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        channel: ChannelSchema.optional(),
+      }),
+    },
+    async ({ name, description, type, participants }, 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.',
+          },
+        };
+      }
+
+      // Check if channel already exists
+      const existing = getChannelByName(name);
+      if (existing) {
+        return {
+          content: [{ type: "text", text: `Channel "${name}" already exists.` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Channel "${name}" already exists.`,
+            channel: existing,
+          },
+        };
+      }
+
+      try {
+        const channel = createChannel(name, {
+          description,
+          type: type ?? "public",
+          createdBy: requestInfo.agentId,
+          participants,
+        });
+
+        return {
+          content: [{ type: "text", text: `Created channel "${name}".` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Created channel "${name}".`,
+            channel,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to create channel: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to create channel: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/get-tasks.ts

@@ -6,8 +6,14 @@ import { AgentTaskStatusSchema } from "@/types";
 
 const TaskSummarySchema = z.object({
   id: z.string(),
+  agentId: z.string().nullable(),
   task: z.string(),
   status: AgentTaskStatusSchema,
+  taskType: z.string().optional(),
+  tags: z.array(z.string()),
+  priority: z.number(),
+  dependsOn: z.array(z.string()),
+  offeredTo: z.string().optional(),
   createdAt: z.string(),
   lastUpdatedAt: z.string(),
   finishedAt: z.string().optional(),
@@ -20,56 +26,83 @@ export const registerGetTasksTool = (server: McpServer) => {
     {
       title: "Get tasks",
       description:
-        "Returns a list of tasks in the swarm, filtered by status and sorted by lastUpdatedAt desc. Defaults to in_progress tasks only. Does not return output or failure reason.",
+        "Returns a list of tasks in the swarm with various filters. Sorted by priority (desc) then lastUpdatedAt (desc).",
       inputSchema: z.object({
         status: AgentTaskStatusSchema.optional().describe(
-          "Filter by task status. Defaults to 'in_progress'.",
+          "Filter by task status (unassigned, offered, pending, in_progress, completed, failed).",
         ),
-        mineOnly: z
+        mineOnly: z.boolean().optional().describe("Only return tasks assigned to you."),
+        unassigned: z.boolean().optional().describe("Only return unassigned tasks in the pool."),
+        offeredToMe: z
           .boolean()
           .optional()
-          .describe(
-            "If true, only return tasks assigned to your agent. Requires X-Agent-ID header.",
-          ),
+          .describe("Only return tasks offered to you (awaiting accept/reject)."),
+        readyOnly: z.boolean().optional().describe("Only return tasks whose dependencies are met."),
+        taskType: z.string().optional().describe("Filter by task type (e.g., 'bug', 'feature')."),
+        tags: z.array(z.string()).optional().describe("Filter by any matching tag."),
+        search: z.string().optional().describe("Search in task description."),
       }),
       outputSchema: z.object({
         tasks: z.array(TaskSummarySchema),
       }),
     },
-    async ({ status, mineOnly }, requestInfo, _meta) => {
-      const filterStatus = status ?? "in_progress";
-      let tasks = getAllTasks(filterStatus);
+    async (
+      { status, mineOnly, unassigned, offeredToMe, readyOnly, taskType, tags, search },
+      requestInfo,
+      _meta,
+    ) => {
+      const agentId = requestInfo.agentId;
 
-      // Filter to only tasks assigned to this agent if mineOnly is true
-      if (mineOnly) {
-        if (!requestInfo.agentId) {
-          // No agent ID set, return empty list
-          tasks = [];
-        } else {
-          tasks = tasks.filter((t) => t.agentId === requestInfo.agentId);
-        }
-      }
+      // Build filters
+      const tasks = getAllTasks({
+        status,
+        agentId: mineOnly ? (agentId ?? undefined) : undefined,
+        unassigned,
+        offeredTo: offeredToMe ? (agentId ?? undefined) : undefined,
+        readyOnly,
+        taskType,
+        tags,
+        search,
+      });
 
       const taskSummaries = tasks.map((t) => ({
         id: t.id,
+        agentId: t.agentId,
         task: t.task,
         status: t.status,
+        taskType: t.taskType,
+        tags: t.tags,
+        priority: t.priority,
+        dependsOn: t.dependsOn,
+        offeredTo: t.offeredTo,
         createdAt: t.createdAt,
         lastUpdatedAt: t.lastUpdatedAt,
         finishedAt: t.finishedAt,
         progress: t.progress,
       }));
 
-      const mineOnlyMsg = mineOnly ? " (mine only)" : "";
+      // Build filter description for message
+      const filters: string[] = [];
+      if (status) filters.push(`status='${status}'`);
+      if (mineOnly) filters.push("mine only");
+      if (unassigned) filters.push("unassigned");
+      if (offeredToMe) filters.push("offered to me");
+      if (readyOnly) filters.push("ready only");
+      if (taskType) filters.push(`type='${taskType}'`);
+      if (tags?.length) filters.push(`tags=[${tags.join(", ")}]`);
+      if (search) filters.push(`search='${search}'`);
+
+      const filterMsg = filters.length > 0 ? ` (${filters.join(", ")})` : "";
+
       return {
         content: [
           {
             type: "text",
-            text: `Found ${taskSummaries.length} task(s) with status '${filterStatus}'${mineOnlyMsg}.`,
+            text: `Found ${taskSummaries.length} task(s)${filterMsg}.`,
           },
         ],
         structuredContent: {
-          yourAgentId: requestInfo.agentId,
+          yourAgentId: agentId,
           tasks: taskSummaries,
         },
       };

package/src/tools/join-swarm.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
-import { createAgent, getAllAgents, getDb } from "@/be/db";
+import { createAgent, getAllAgents, getDb, updateAgentProfile } from "@/be/db";
 import { createToolRegistrar } from "@/tools/utils";
 import { AgentSchema } from "@/types";
 
@@ -9,7 +9,8 @@ export const registerJoinSwarmTool = (server: McpServer) => {
     "join-swarm",
     {
       title: "Join the agent swarm",
-      description: "Tool for an agent to join the swarm of agents.",
+      description:
+        "Tool for an agent to join the swarm of agents with optional profile information.",
       inputSchema: z.object({
         requestedId: z
           .string()
@@ -17,6 +18,16 @@ export const registerJoinSwarmTool = (server: McpServer) => {
           .describe("Requested ID for the agent (overridden by X-Agent-ID header)."),
         lead: z.boolean().default(false).describe("Whether this agent should be the lead."),
         name: z.string().min(1).describe("The name of the agent joining the swarm."),
+        description: z.string().optional().describe("Agent description."),
+        role: z
+          .string()
+          .max(100)
+          .optional()
+          .describe("Agent role (free-form, e.g., 'frontend dev', 'code reviewer')."),
+        capabilities: z
+          .array(z.string())
+          .optional()
+          .describe("List of capabilities (e.g., ['typescript', 'react', 'testing'])."),
       }),
       outputSchema: z.object({
         success: z.boolean(),
@@ -24,7 +35,7 @@ export const registerJoinSwarmTool = (server: McpServer) => {
         agent: AgentSchema.optional(),
       }),
     },
-    async ({ lead, name, requestedId }, requestInfo, _meta) => {
+    async ({ lead, name, requestedId, description, role, capabilities }, requestInfo, _meta) => {
       // Check if agent ID is set
       if (!requestInfo.agentId && !requestedId) {
         return {
@@ -70,12 +81,25 @@ export const registerJoinSwarmTool = (server: McpServer) => {
             );
           }
 
-          return createAgent({
+          const agent = createAgent({
             id: agentId,
             name,
             isLead: lead,
             status: "idle",
+            capabilities: [],
           });
+
+          // Update profile if any profile fields were provided
+          if (description !== undefined || role !== undefined || capabilities !== undefined) {
+            const updatedAgent = updateAgentProfile(agent.id, {
+              description,
+              role,
+              capabilities,
+            });
+            return updatedAgent ?? agent;
+          }
+
+          return agent;
         });
 
         const agent = agentTx();

package/src/tools/list-channels.ts

@@ -0,0 +1,37 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAllChannels } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { ChannelSchema } from "@/types";
+
+export const registerListChannelsTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "list-channels",
+    {
+      title: "List Channels",
+      description: "Lists all available channels for cross-agent communication.",
+      inputSchema: z.object({}),
+      outputSchema: z.object({
+        success: z.boolean(),
+        channels: z.array(ChannelSchema),
+      }),
+    },
+    async (_input, requestInfo, _meta) => {
+      const channels = getAllChannels();
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${channels.length} channel(s): ${channels.map((c) => c.name).join(", ") || "(none)"}`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          channels,
+        },
+      };
+    },
+  );
+};