@desplega.ai/agent-swarm 1.2.1 → 1.9.0

package/src/tools/send-task.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
-import { createTask, getAgentById, getDb } from "@/be/db";
+import { createTaskExtended, getAgentById, getDb } from "@/be/db";
 import { createToolRegistrar } from "@/tools/utils";
 import { AgentTaskSchema } from "@/types";
 
@@ -9,10 +9,35 @@ export const registerSendTaskTool = (server: McpServer) => {
     "send-task",
     {
       title: "Send a task",
-      description: "Sends a task to a specific agent in the swarm.",
+      description:
+        "Sends a task to a specific agent, creates an unassigned task for the pool, or offers a task for acceptance.",
       inputSchema: z.object({
-        agentId: z.uuid().describe("The ID of the agent to send the task to."),
+        agentId: z
+          .uuid()
+          .optional()
+          .describe("The agent to assign/offer task to. Omit to create unassigned task for pool."),
         task: z.string().min(1).describe("The task description to send."),
+        offerMode: z
+          .boolean()
+          .default(false)
+          .describe("If true, offer the task instead of direct assign (agent must accept/reject)."),
+        taskType: z
+          .string()
+          .max(50)
+          .optional()
+          .describe("Task type (e.g., 'bug', 'feature', 'review')."),
+        tags: z
+          .array(z.string())
+          .optional()
+          .describe("Tags for filtering (e.g., ['urgent', 'frontend'])."),
+        priority: z
+          .number()
+          .int()
+          .min(0)
+          .max(100)
+          .optional()
+          .describe("Priority 0-100 (default: 50)."),
+        dependsOn: z.array(z.uuid()).optional().describe("Task IDs this task depends on."),
       }),
       outputSchema: z.object({
         success: z.boolean(),
@@ -20,7 +45,11 @@ export const registerSendTaskTool = (server: McpServer) => {
         task: AgentTaskSchema.optional(),
       }),
     },
-    async ({ agentId, task }, requestInfo, _meta) => {
+    async (
+      { agentId, task, offerMode, taskType, tags, priority, dependsOn },
+      requestInfo,
+      _meta,
+    ) => {
       if (!requestInfo.agentId) {
         return {
           content: [
@@ -54,6 +83,23 @@ export const registerSendTaskTool = (server: McpServer) => {
       }
 
       const txn = getDb().transaction(() => {
+        // If no agentId, create an unassigned task for the pool
+        if (!agentId) {
+          const newTask = createTaskExtended(task, {
+            creatorAgentId: requestInfo.agentId,
+            taskType,
+            tags,
+            priority,
+            dependsOn,
+          });
+
+          return {
+            success: true,
+            message: `Created unassigned task "${newTask.id}" in the pool.`,
+            task: newTask,
+          };
+        }
+
         const agent = getAgentById(agentId);
 
         if (!agent) {
@@ -70,14 +116,41 @@ export const registerSendTaskTool = (server: McpServer) => {
           };
         }
 
-        if (agent.status !== "idle") {
+        // For direct assignment (not offer), check if agent is idle
+        if (!offerMode && agent.status !== "idle") {
           return {
             success: false,
-            message: `Agent "${agent.name}" is not idle (status: ${agent.status}). Cannot assign task.`,
+            message: `Agent "${agent.name}" is not idle (status: ${agent.status}). Cannot assign task directly. Use offerMode: true to offer the task instead.`,
+          };
+        }
+
+        if (offerMode) {
+          // Offer the task to the agent (they must accept/reject)
+          const newTask = createTaskExtended(task, {
+            offeredTo: agentId,
+            creatorAgentId: requestInfo.agentId,
+            taskType,
+            tags,
+            priority,
+            dependsOn,
+          });
+
+          return {
+            success: true,
+            message: `Task "${newTask.id}" offered to agent "${agent.name}". They must accept or reject it.`,
+            task: newTask,
           };
         }
 
-        const newTask = createTask(agentId, task);
+        // Direct assignment
+        const newTask = createTaskExtended(task, {
+          agentId,
+          creatorAgentId: requestInfo.agentId,
+          taskType,
+          tags,
+          priority,
+          dependsOn,
+        });
 
         return {
           success: true,

package/src/tools/store-progress.ts

@@ -87,17 +87,23 @@ export const registerStoreProgressTool = (server: McpServer) => {
           const result = completeTask(taskId, output);
           if (result) {
             updatedTask = result;
-            updateAgentStatus(existingTask.agentId, "idle");
+            if (existingTask.agentId) {
+              updateAgentStatus(existingTask.agentId, "idle");
+            }
           }
         } else if (status === "failed") {
           const result = failTask(taskId, failureReason ?? "Unknown failure");
           if (result) {
             updatedTask = result;
-            updateAgentStatus(existingTask.agentId, "idle");
+            if (existingTask.agentId) {
+              updateAgentStatus(existingTask.agentId, "idle");
+            }
           }
         } else {
           // Keep it busy if just updating progress
-          updateAgentStatus(existingTask.agentId, "busy");
+          if (existingTask.agentId) {
+            updateAgentStatus(existingTask.agentId, "busy");
+          }
         }
 
         return {

package/src/tools/task-action.ts

@@ -0,0 +1,211 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import {
+  acceptTask,
+  claimTask,
+  createTaskExtended,
+  getDb,
+  getTaskById,
+  rejectTask,
+  releaseTask,
+} from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { AgentTaskSchema } from "@/types";
+
+const TaskActionSchema = z.enum(["create", "claim", "release", "accept", "reject"]);
+
+export const registerTaskActionTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "task-action",
+    {
+      title: "Task Pool Actions",
+      description:
+        "Perform task pool operations: create unassigned tasks, claim/release tasks from pool, accept/reject offered tasks.",
+      inputSchema: z.object({
+        action: TaskActionSchema.describe(
+          "The action to perform: 'create' creates an unassigned task, 'claim' takes a task from pool, 'release' returns task to pool, 'accept' accepts offered task, 'reject' declines offered task.",
+        ),
+        // For 'create' action:
+        task: z.string().min(1).optional().describe("Task description (required for 'create')."),
+        taskType: z.string().max(50).optional().describe("Task type (e.g., 'bug', 'feature')."),
+        tags: z
+          .array(z.string())
+          .optional()
+          .describe("Tags for filtering (e.g., ['urgent', 'frontend'])."),
+        priority: z
+          .number()
+          .int()
+          .min(0)
+          .max(100)
+          .optional()
+          .describe("Priority 0-100, default 50."),
+        dependsOn: z.array(z.uuid()).optional().describe("Task IDs this task depends on."),
+        // For claim/release/accept/reject actions:
+        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')."),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        task: AgentTaskSchema.optional(),
+      }),
+    },
+    async (input, requestInfo, _meta) => {
+      const { action, task, taskType, tags, priority, dependsOn, taskId, reason } = input;
+
+      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.',
+          },
+        };
+      }
+
+      const agentId = requestInfo.agentId;
+
+      const txn = getDb().transaction(() => {
+        switch (action) {
+          case "create": {
+            if (!task) {
+              return {
+                success: false,
+                message: "Task description is required for 'create' action.",
+              };
+            }
+            const newTask = createTaskExtended(task, {
+              creatorAgentId: agentId,
+              taskType,
+              tags,
+              priority,
+              dependsOn,
+            });
+            return {
+              success: true,
+              message: `Created unassigned task "${newTask.id}".`,
+              task: newTask,
+            };
+          }
+
+          case "claim": {
+            if (!taskId) {
+              return { success: false, message: "Task ID is required for 'claim' action." };
+            }
+            const existingTask = getTaskById(taskId);
+            if (!existingTask) {
+              return { success: false, message: `Task "${taskId}" not found.` };
+            }
+            if (existingTask.status !== "unassigned") {
+              return {
+                success: false,
+                message: `Task "${taskId}" is not unassigned (status: ${existingTask.status}).`,
+              };
+            }
+            const claimedTask = claimTask(taskId, agentId);
+            if (!claimedTask) {
+              return { success: false, message: `Failed to claim task "${taskId}".` };
+            }
+            return {
+              success: true,
+              message: `Claimed task "${taskId}".`,
+              task: claimedTask,
+            };
+          }
+
+          case "release": {
+            if (!taskId) {
+              return { success: false, message: "Task ID is required for 'release' action." };
+            }
+            const existingTask = getTaskById(taskId);
+            if (!existingTask) {
+              return { success: false, message: `Task "${taskId}" not found.` };
+            }
+            if (existingTask.agentId !== agentId) {
+              return { success: false, message: `Task "${taskId}" is not assigned to you.` };
+            }
+            if (existingTask.status !== "pending") {
+              return {
+                success: false,
+                message: `Cannot release task in status "${existingTask.status}". Only 'pending' tasks can be released.`,
+              };
+            }
+            const releasedTask = releaseTask(taskId);
+            if (!releasedTask) {
+              return { success: false, message: `Failed to release task "${taskId}".` };
+            }
+            return {
+              success: true,
+              message: `Released task "${taskId}" back to pool.`,
+              task: releasedTask,
+            };
+          }
+
+          case "accept": {
+            if (!taskId) {
+              return { success: false, message: "Task ID is required for 'accept' action." };
+            }
+            const existingTask = getTaskById(taskId);
+            if (!existingTask) {
+              return { success: false, message: `Task "${taskId}" not found.` };
+            }
+            if (existingTask.status !== "offered") {
+              return { success: false, message: `Task "${taskId}" is not offered.` };
+            }
+            if (existingTask.offeredTo !== agentId) {
+              return { success: false, message: `Task "${taskId}" was not offered to you.` };
+            }
+            const acceptedTask = acceptTask(taskId, agentId);
+            if (!acceptedTask) {
+              return { success: false, message: `Failed to accept task "${taskId}".` };
+            }
+            return {
+              success: true,
+              message: `Accepted task "${taskId}".`,
+              task: acceptedTask,
+            };
+          }
+
+          case "reject": {
+            if (!taskId) {
+              return { success: false, message: "Task ID is required for 'reject' action." };
+            }
+            const existingTask = getTaskById(taskId);
+            if (!existingTask) {
+              return { success: false, message: `Task "${taskId}" not found.` };
+            }
+            if (existingTask.status !== "offered") {
+              return { success: false, message: `Task "${taskId}" is not offered.` };
+            }
+            if (existingTask.offeredTo !== agentId) {
+              return { success: false, message: `Task "${taskId}" was not offered to you.` };
+            }
+            const rejectedTask = rejectTask(taskId, agentId, reason);
+            if (!rejectedTask) {
+              return { success: false, message: `Failed to reject task "${taskId}".` };
+            }
+            return {
+              success: true,
+              message: `Rejected task "${taskId}". Task returned to pool.`,
+              task: rejectedTask,
+            };
+          }
+
+          default:
+            return { success: false, message: `Unknown action: ${action}` };
+        }
+      });
+
+      const result = txn();
+
+      return {
+        content: [{ type: "text", text: result.message }],
+        structuredContent: {
+          yourAgentId: agentId,
+          ...result,
+        },
+      };
+    },
+  );
+};

package/src/tools/unregister-service.ts

@@ -0,0 +1,110 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { deleteService, getServiceByAgentAndName, getServiceById } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerUnregisterServiceTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "unregister-service",
+    {
+      title: "Unregister Service",
+      description:
+        "Remove a service from the registry. Use this after stopping a PM2 process. You can only unregister your own services.",
+      inputSchema: z.object({
+        serviceId: z.uuid().optional().describe("Service ID to unregister."),
+        name: z
+          .string()
+          .optional()
+          .describe("Service name to unregister (alternative to serviceId)."),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async ({ serviceId, name }, 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.',
+          },
+        };
+      }
+
+      if (!serviceId && !name) {
+        return {
+          content: [{ type: "text", text: "Either serviceId or name is required." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Either serviceId or name is required.",
+          },
+        };
+      }
+
+      try {
+        // Find the service
+        let service = serviceId ? getServiceById(serviceId) : null;
+        if (!service && name) {
+          service = getServiceByAgentAndName(requestInfo.agentId, name);
+        }
+
+        if (!service) {
+          return {
+            content: [{ type: "text", text: "Service not found." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Service not found.",
+            },
+          };
+        }
+
+        // Check ownership
+        if (service.agentId !== requestInfo.agentId) {
+          return {
+            content: [{ type: "text", text: "You can only unregister your own services." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "You can only unregister your own services.",
+            },
+          };
+        }
+
+        const deleted = deleteService(service.id);
+        if (!deleted) {
+          return {
+            content: [{ type: "text", text: "Failed to unregister service." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Failed to unregister service.",
+            },
+          };
+        }
+
+        return {
+          content: [{ type: "text", text: `Unregistered service "${service.name}".` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Unregistered service "${service.name}".`,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to unregister service: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to unregister service: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/update-profile.ts

@@ -0,0 +1,105 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { updateAgentProfile } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { AgentSchema } from "@/types";
+
+export const registerUpdateProfileTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "update-profile",
+    {
+      title: "Update Profile",
+      description:
+        "Updates the calling agent's profile information (description, role, capabilities).",
+      inputSchema: z.object({
+        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(),
+        message: z.string(),
+        agent: AgentSchema.optional(),
+      }),
+    },
+    async ({ description, role, capabilities }, 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.',
+          },
+        };
+      }
+
+      // At least one field must be provided
+      if (description === undefined && role === undefined && capabilities === undefined) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "At least one field (description, role, or capabilities) must be provided.",
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "At least one field (description, role, or capabilities) must be provided.",
+          },
+        };
+      }
+
+      try {
+        const agent = updateAgentProfile(requestInfo.agentId, {
+          description,
+          role,
+          capabilities,
+        });
+
+        if (!agent) {
+          return {
+            content: [{ type: "text", text: "Agent not found." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Agent not found.",
+            },
+          };
+        }
+
+        const updatedFields: string[] = [];
+        if (description !== undefined) updatedFields.push("description");
+        if (role !== undefined) updatedFields.push("role");
+        if (capabilities !== undefined) updatedFields.push("capabilities");
+
+        return {
+          content: [{ type: "text", text: `Updated profile: ${updatedFields.join(", ")}.` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Updated profile: ${updatedFields.join(", ")}.`,
+            agent,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to update profile: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to update profile: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/update-service-status.ts

@@ -0,0 +1,118 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getServiceByAgentAndName, getServiceById, updateServiceStatus } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { ServiceSchema, ServiceStatusSchema } from "@/types";
+
+export const registerUpdateServiceStatusTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "update-service-status",
+    {
+      title: "Update Service Status",
+      description:
+        "Update the health status of a registered service. Use this after a service becomes healthy or needs to be marked as stopped/unhealthy.",
+      inputSchema: z.object({
+        serviceId: z.uuid().optional().describe("Service ID to update."),
+        name: z.string().optional().describe("Service name to update (alternative to serviceId)."),
+        status: ServiceStatusSchema.describe(
+          "New status: 'starting', 'healthy', 'unhealthy', or 'stopped'.",
+        ),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        service: ServiceSchema.optional(),
+      }),
+    },
+    async ({ serviceId, name, status }, 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.',
+          },
+        };
+      }
+
+      if (!serviceId && !name) {
+        return {
+          content: [{ type: "text", text: "Either serviceId or name is required." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Either serviceId or name is required.",
+          },
+        };
+      }
+
+      try {
+        // Find the service
+        let service = serviceId ? getServiceById(serviceId) : null;
+        if (!service && name) {
+          service = getServiceByAgentAndName(requestInfo.agentId, name);
+        }
+
+        if (!service) {
+          return {
+            content: [{ type: "text", text: "Service not found." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Service not found.",
+            },
+          };
+        }
+
+        // Check ownership
+        if (service.agentId !== requestInfo.agentId) {
+          return {
+            content: [{ type: "text", text: "You can only update status of your own services." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "You can only update status of your own services.",
+            },
+          };
+        }
+
+        const updated = updateServiceStatus(service.id, status);
+        if (!updated) {
+          return {
+            content: [{ type: "text", text: "Failed to update service status." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Failed to update service status.",
+            },
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Updated service "${service.name}" status to "${status}".`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Updated service "${service.name}" status to "${status}".`,
+            service: updated,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to update service status: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to update service status: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};