@desplega.ai/agent-swarm 1.2.0 → 1.9.0

package/src/tools/list-services.ts

@@ -0,0 +1,110 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getAllServices } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { ServiceSchema, ServiceStatusSchema } from "@/types";
+
+export const registerListServicesTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "list-services",
+    {
+      title: "List Services",
+      description:
+        "Query services registered by agents in the swarm. Use this to discover services exposed by other agents.",
+      inputSchema: z.object({
+        agentId: z.uuid().optional().describe("Filter by specific agent ID."),
+        name: z.string().optional().describe("Filter by service name (partial match)."),
+        status: ServiceStatusSchema.optional().describe("Filter by health status."),
+        includeOwn: z
+          .boolean()
+          .default(true)
+          .optional()
+          .describe("Include services registered by calling agent (default: true)."),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        services: z.array(
+          ServiceSchema.extend({
+            agentName: z.string().optional(),
+          }),
+        ),
+        count: z.number(),
+      }),
+    },
+    async ({ agentId, name, status, includeOwn }, 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.',
+            services: [],
+            count: 0,
+          },
+        };
+      }
+
+      try {
+        let services = getAllServices({
+          agentId,
+          name,
+          status,
+        });
+
+        // Filter out own services if requested
+        if (includeOwn === false) {
+          services = services.filter((s) => s.agentId !== requestInfo.agentId);
+        }
+
+        // Denormalize agent names
+        const servicesWithAgentNames = services.map((service) => {
+          const agent = getAgentById(service.agentId);
+          return {
+            ...service,
+            agentName: agent?.name,
+          };
+        });
+
+        const count = servicesWithAgentNames.length;
+        const statusSummary =
+          count === 0 ? "No services found." : `Found ${count} service${count === 1 ? "" : "s"}.`;
+
+        // Format for text output
+        const serviceList = servicesWithAgentNames
+          .map(
+            (s) => `- ${s.name} (${s.status}) by ${s.agentName ?? "unknown"}: ${s.url ?? "no URL"}`,
+          )
+          .join("\n");
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: count === 0 ? statusSummary : `${statusSummary}\n\n${serviceList}`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: statusSummary,
+            services: servicesWithAgentNames,
+            count,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to list services: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to list services: ${message}`,
+            services: [],
+            count: 0,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/poll-task.ts

@@ -1,7 +1,15 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { addMinutes } from "date-fns";
 import * as z from "zod";
-import { getAgentById, getDb, getPendingTaskForAgent, startTask, updateAgentStatus } from "@/be/db";
+import {
+  getAgentById,
+  getDb,
+  getOfferedTasksForAgent,
+  getPendingTaskForAgent,
+  getUnassignedTasksCount,
+  startTask,
+  updateAgentStatus,
+} from "@/be/db";
 import { createToolRegistrar } from "@/tools/utils";
 import { AgentTaskSchema } from "@/types";
 
@@ -14,12 +22,16 @@ export const registerPollTaskTool = (server: McpServer) => {
     {
       title: "Poll for a task",
       description:
-        "Tool for an agent to poll for a new task assignment, to be used recursively until a task is assigned.",
+        "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.",
       inputSchema: z.object({}),
       outputSchema: z.object({
         success: z.boolean(),
         message: z.string(),
         task: AgentTaskSchema.optional(),
+        offeredTasks: z
+          .array(AgentTaskSchema)
+          .describe("Tasks offered to you awaiting accept/reject."),
+        availableCount: z.number().describe("Count of unassigned tasks in the pool."),
         waitedForSeconds: z.number().describe("Seconds waited before receiving the task."),
       }),
     },
@@ -37,6 +49,8 @@ export const registerPollTaskTool = (server: McpServer) => {
             yourAgentId: requestInfo.agentId,
             success: false,
             message: 'Agent ID not found. The MCP client should define the "X-Agent-ID" header.',
+            offeredTasks: [],
+            availableCount: 0,
             waitedForSeconds: 0,
           },
         };
@@ -59,6 +73,31 @@ export const registerPollTaskTool = (server: McpServer) => {
             yourAgentId: requestInfo.agentId,
             success: false,
             message: `Agent with ID "${agentId}" not found in the swarm.`,
+            offeredTasks: [],
+            availableCount: 0,
+            waitedForSeconds: 0,
+          },
+        };
+      }
+
+      // Check for offered tasks first - these need immediate attention
+      const offeredTasks = getOfferedTasksForAgent(agentId);
+      const availableCount = getUnassignedTasksCount();
+
+      if (offeredTasks.length > 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `You have ${offeredTasks.length} task(s) offered to you awaiting accept/reject. Use task-action with action='accept' or 'reject'.`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `You have ${offeredTasks.length} task(s) offered to you awaiting accept/reject.`,
+            offeredTasks,
+            availableCount,
             waitedForSeconds: 0,
           },
         };
@@ -68,6 +107,7 @@ export const registerPollTaskTool = (server: McpServer) => {
       while (new Date() < maxTime) {
         // Fetch and update in a single transaction to avoid race conditions
         const startedTask = getDb().transaction(() => {
+          // biome-ignore lint/style/noNonNullAssertion: agent existence verified above
           const agentNow = getAgentById(agentId)!;
 
           if (agentNow.status !== "busy") {
@@ -102,6 +142,8 @@ export const registerPollTaskTool = (server: McpServer) => {
               success: true,
               message: `Task "${startedTask.id}" assigned and started.`,
               task: startedTask,
+              offeredTasks: [],
+              availableCount: getUnassignedTasksCount(),
               waitedForSeconds: waitedFor,
             },
           };
@@ -126,13 +168,15 @@ export const registerPollTaskTool = (server: McpServer) => {
         content: [
           {
             type: "text",
-            text: `No task assigned within the polling duration.`,
+            text: `No task assigned within the polling duration. ${availableCount} unassigned task(s) available in pool.`,
           },
         ],
         structuredContent: {
           yourAgentId: requestInfo.agentId,
           success: false,
           message: `No task assigned within the polling duration, please keep polling until a task is assigned.`,
+          offeredTasks: [],
+          availableCount: getUnassignedTasksCount(),
           waitedForSeconds,
         },
       };

package/src/tools/post-message.ts

@@ -0,0 +1,87 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getChannelById, getChannelByName, postMessage, updateReadState } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { ChannelMessageSchema } from "@/types";
+
+export const registerPostMessageTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "post-message",
+    {
+      title: "Post Message",
+      description: "Posts a message to a channel for cross-agent communication.",
+      inputSchema: z.object({
+        channel: z.string().default("general").describe("Channel name (default: 'general')."),
+        content: z.string().min(1).max(4000).describe("Message content."),
+        replyTo: z.uuid().optional().describe("Message ID to reply to (for threading)."),
+        mentions: z
+          .array(z.uuid())
+          .optional()
+          .describe("Agent IDs to @mention (they'll see it in unread)."),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        posted: ChannelMessageSchema.optional(),
+      }),
+    },
+    async ({ channel, content, replyTo, mentions }, 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.',
+          },
+        };
+      }
+
+      // Find channel by name or ID
+      let targetChannel = getChannelByName(channel);
+      if (!targetChannel) {
+        targetChannel = getChannelById(channel);
+      }
+
+      if (!targetChannel) {
+        return {
+          content: [{ type: "text", text: `Channel "${channel}" not found.` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Channel "${channel}" not found.`,
+          },
+        };
+      }
+
+      try {
+        const posted = postMessage(targetChannel.id, requestInfo.agentId, content, {
+          replyToId: replyTo,
+          mentions,
+        });
+
+        // Auto-mark channel as read after posting (so you don't see your own message as unread)
+        updateReadState(requestInfo.agentId, targetChannel.id);
+
+        return {
+          content: [{ type: "text", text: `Posted message to #${targetChannel.name}.` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Posted message to #${targetChannel.name}.`,
+            posted,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to post message: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to post message: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/read-messages.ts

@@ -0,0 +1,192 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import {
+  getAllChannels,
+  getChannelById,
+  getChannelByName,
+  getChannelMessages,
+  getMentionsForAgent,
+  getUnreadMessages,
+  updateReadState,
+} from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import type { ChannelMessage } from "@/types";
+import { ChannelMessageSchema } from "@/types";
+
+export const registerReadMessagesTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "read-messages",
+    {
+      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.",
+      inputSchema: z.object({
+        channel: z
+          .string()
+          .optional()
+          .describe("Channel name or ID. If omitted, returns unread messages from all channels."),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .default(20)
+          .describe("Max messages to return per channel (default: 20)."),
+        since: z.iso.datetime().optional().describe("Only messages after this ISO timestamp."),
+        unreadOnly: z.boolean().default(false).describe("Only return unread messages."),
+        mentionsOnly: z
+          .boolean()
+          .default(false)
+          .describe("Only return messages that @mention you."),
+        markAsRead: z
+          .boolean()
+          .default(true)
+          .describe("Update your read position after fetching (default: true)."),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        channelName: z.string().optional(),
+        messages: z.array(ChannelMessageSchema),
+        unreadCount: z.number().optional(),
+        totalUnreadCount: z.number().optional(),
+      }),
+    },
+    async ({ channel, limit, since, unreadOnly, mentionsOnly, markAsRead }, 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.',
+            messages: [],
+          },
+        };
+      }
+
+      try {
+        // If no channel specified, get unread messages from all channels
+        if (!channel) {
+          const allChannels = getAllChannels();
+          let allMessages: ReturnType<typeof getUnreadMessages> = [];
+          let totalUnreadCount = 0;
+
+          for (const ch of allChannels) {
+            const unreadMessages = getUnreadMessages(requestInfo.agentId, ch.id);
+            totalUnreadCount += unreadMessages.length;
+
+            // Add channel name to messages for context
+            const messagesWithChannel = unreadMessages.slice(-limit).map((msg) => ({
+              ...msg,
+              agentName: msg.agentName ? `${msg.agentName} in #${ch.name}` : `#${ch.name}`,
+            }));
+            allMessages = allMessages.concat(messagesWithChannel);
+
+            // Update read state if requested
+            if (markAsRead && unreadMessages.length > 0) {
+              updateReadState(requestInfo.agentId, ch.id);
+            }
+          }
+
+          // Sort by createdAt and limit
+          allMessages.sort(
+            (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
+          );
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Found ${allMessages.length} unread message(s) across ${allChannels.length} channel(s).`,
+              },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: true,
+              message: `Found ${allMessages.length} unread message(s) across all channels.`,
+              messages: allMessages,
+              totalUnreadCount,
+            },
+          };
+        }
+
+        // Find channel by name or ID
+        let targetChannel = getChannelByName(channel);
+        if (!targetChannel) {
+          targetChannel = getChannelById(channel);
+        }
+
+        if (!targetChannel) {
+          return {
+            content: [{ type: "text", text: `Channel "${channel}" not found.` }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: `Channel "${channel}" not found.`,
+              messages: [],
+            },
+          };
+        }
+
+        let messages: ChannelMessage[] = [];
+
+        if (mentionsOnly) {
+          // Get messages that mention this agent
+          messages = getMentionsForAgent(requestInfo.agentId, {
+            unreadOnly,
+            channelId: targetChannel.id,
+          });
+        } else if (unreadOnly) {
+          // Get unread messages only
+          messages = getUnreadMessages(requestInfo.agentId, targetChannel.id);
+        } else {
+          // Get regular messages with filters
+          messages = getChannelMessages(targetChannel.id, {
+            limit,
+            since,
+          });
+        }
+
+        // Apply limit if not already applied (unreadOnly and mentionsOnly don't limit)
+        if ((unreadOnly || mentionsOnly) && messages.length > limit) {
+          messages = messages.slice(-limit); // Keep most recent
+        }
+
+        // Update read state if requested
+        if (markAsRead && messages.length > 0) {
+          updateReadState(requestInfo.agentId, targetChannel.id);
+        }
+
+        // Get unread count for context
+        const allUnread = getUnreadMessages(requestInfo.agentId, targetChannel.id);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Found ${messages.length} message(s) in #${targetChannel.name}${unreadOnly ? " (unread)" : ""}${mentionsOnly ? " (mentions)" : ""}.`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Found ${messages.length} message(s) in #${targetChannel.name}.`,
+            channelName: targetChannel.name,
+            messages,
+            unreadCount: allUnread.length,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to read messages: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to read messages: ${message}`,
+            messages: [],
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/register-service.ts

@@ -0,0 +1,118 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, upsertService } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { ServiceSchema } from "@/types";
+
+const SWARM_URL = process.env.SWARM_URL ?? "localhost";
+
+export const registerRegisterServiceTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "register-service",
+    {
+      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.",
+      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."),
+        healthCheckPath: z
+          .string()
+          .optional()
+          .describe("Health check endpoint path (default: /health)."),
+        cwd: z.string().optional().describe("Working directory for the script."),
+        interpreter: z
+          .string()
+          .optional()
+          .describe(
+            "Interpreter to use (e.g., 'node', 'bun'). Auto-detected from extension if not set.",
+          ),
+        args: z.array(z.string()).optional().describe("Command line arguments for the script."),
+        env: z
+          .record(z.string(), z.string())
+          .optional()
+          .describe("Environment variables for the process."),
+        metadata: z.record(z.string(), z.unknown()).optional().describe("Additional metadata."),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        service: ServiceSchema.optional(),
+      }),
+    },
+    async (
+      { script, description, healthCheckPath, cwd, interpreter, args, env, metadata },
+      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 {
+        // Look up the agent to get its name
+        const agent = getAgentById(requestInfo.agentId);
+        if (!agent) {
+          return {
+            content: [{ type: "text", text: "Agent not found. Join the swarm first." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Agent not found. Join the swarm first.",
+            },
+          };
+        }
+
+        // Service name uses agent ID (stable, URL-safe) for subdomain
+        const serviceName = agent.id;
+        const servicePort = 3000; // Fixed port - only one service per worker
+        const url = `https://${serviceName}.${SWARM_URL}`;
+
+        // Upsert: create or update if exists
+        const service = upsertService(requestInfo.agentId, serviceName, {
+          script,
+          port: servicePort,
+          description,
+          url,
+          healthCheckPath: healthCheckPath ?? "/health",
+          cwd,
+          interpreter,
+          args,
+          env,
+          metadata,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Registered service "${serviceName}" at ${url}. Status: ${service.status}. Use update-service-status to mark as healthy.`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Registered service "${serviceName}" at ${url}.`,
+            service,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to register service: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to register service: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};