@desplega.ai/agent-swarm 1.2.0 → 1.9.0

package/src/http.ts

@@ -8,8 +8,29 @@ import {
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { createServer } from "@/server";
-import { closeDb, getAgentById, getDb, updateAgentStatus } from "./be/db";
-import type { AgentStatus } from "./types";
+import {
+  closeDb,
+  getAgentById,
+  getAgentWithTasks,
+  getAllAgents,
+  getAllAgentsWithTasks,
+  getAllChannels,
+  getAllLogs,
+  getAllServices,
+  getAllTasks,
+  getChannelById,
+  getChannelMessages,
+  getDb,
+  getInboxSummary,
+  getLogsByAgentId,
+  getLogsByTaskId,
+  getServicesByAgentId,
+  getTaskById,
+  postMessage,
+  updateAgentStatus,
+} from "./be/db";
+import { startSlackApp, stopSlackApp } from "./slack";
+import type { AgentLog, AgentStatus } from "./types";
 
 const port = parseInt(process.env.PORT || process.argv[2] || "3013", 10);
 const apiKey = process.env.API_KEY || "";
@@ -36,6 +57,18 @@ function setCorsHeaders(res: ServerResponse) {
   res.setHeader("Access-Control-Expose-Headers", "*");
 }
 
+function parseQueryParams(url: string): URLSearchParams {
+  const queryIndex = url.indexOf("?");
+  if (queryIndex === -1) return new URLSearchParams();
+  return new URLSearchParams(url.slice(queryIndex + 1));
+}
+
+function getPathSegments(url: string): string[] {
+  const pathEnd = url.indexOf("?");
+  const path = pathEnd === -1 ? url : url.slice(0, pathEnd);
+  return path.split("/").filter(Boolean);
+}
+
 const httpServer = createHttpServer(async (req, res) => {
   setCorsHeaders(res);
 
@@ -80,7 +113,7 @@ const httpServer = createHttpServer(async (req, res) => {
     }
   }
 
-  if (req.method === "GET" && req.url === "/me") {
+  if (req.method === "GET" && (req.url === "/me" || req.url?.startsWith("/me?"))) {
     if (!myAgentId) {
       res.writeHead(400, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ error: "Missing X-Agent-ID header" }));
@@ -95,6 +128,16 @@ const httpServer = createHttpServer(async (req, res) => {
       return;
     }
 
+    // Check for ?include=inbox query param
+    const includeInbox = parseQueryParams(req.url || "").get("include") === "inbox";
+
+    if (includeInbox) {
+      const inbox = getInboxSummary(myAgentId);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ...agent, inbox }));
+      return;
+    }
+
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify(agent));
     return;
@@ -166,6 +209,313 @@ const httpServer = createHttpServer(async (req, res) => {
     return;
   }
 
+  // GET /ecosystem - Generate PM2 ecosystem config for agent's services
+  if (req.method === "GET" && req.url === "/ecosystem") {
+    if (!myAgentId) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing X-Agent-ID header" }));
+      return;
+    }
+
+    const services = getServicesByAgentId(myAgentId);
+
+    // Generate PM2 ecosystem format
+    const ecosystem = {
+      apps: services
+        .filter((s) => s.script) // Only include services with script path
+        .map((s) => {
+          const app: Record<string, unknown> = {
+            name: s.name,
+            script: s.script,
+          };
+
+          if (s.cwd) app.cwd = s.cwd;
+          if (s.interpreter) app.interpreter = s.interpreter;
+          if (s.args && s.args.length > 0) app.args = s.args;
+          if (s.env && Object.keys(s.env).length > 0) app.env = s.env;
+          if (s.port)
+            app.env = { ...((app.env as Record<string, string>) || {}), PORT: String(s.port) };
+
+          return app;
+        }),
+    };
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(ecosystem));
+    return;
+  }
+
+  // ============================================================================
+  // REST API Endpoints (for frontend dashboard)
+  // ============================================================================
+
+  const pathSegments = getPathSegments(req.url || "");
+  const queryParams = parseQueryParams(req.url || "");
+
+  // GET /api/agents - List all agents (optionally with tasks)
+  if (
+    req.method === "GET" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "agents" &&
+    !pathSegments[2]
+  ) {
+    const includeTasks = queryParams.get("include") === "tasks";
+    const agents = includeTasks ? getAllAgentsWithTasks() : getAllAgents();
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ agents }));
+    return;
+  }
+
+  // GET /api/agents/:id - Get single agent (optionally with tasks)
+  if (
+    req.method === "GET" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "agents" &&
+    pathSegments[2]
+  ) {
+    const agentId = pathSegments[2];
+    const includeTasks = queryParams.get("include") === "tasks";
+    const agent = includeTasks ? getAgentWithTasks(agentId) : getAgentById(agentId);
+
+    if (!agent) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Agent not found" }));
+      return;
+    }
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(agent));
+    return;
+  }
+
+  // GET /api/tasks - List all tasks (with optional filters: status, agentId, search)
+  if (
+    req.method === "GET" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "tasks" &&
+    !pathSegments[2]
+  ) {
+    const status = queryParams.get("status") as import("./types").AgentTaskStatus | null;
+    const agentId = queryParams.get("agentId");
+    const search = queryParams.get("search");
+    const tasks = getAllTasks({
+      status: status || undefined,
+      agentId: agentId || undefined,
+      search: search || undefined,
+    });
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ tasks }));
+    return;
+  }
+
+  // GET /api/tasks/:id - Get single task with logs
+  if (
+    req.method === "GET" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "tasks" &&
+    pathSegments[2]
+  ) {
+    const taskId = pathSegments[2];
+    const task = getTaskById(taskId);
+
+    if (!task) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Task not found" }));
+      return;
+    }
+
+    const logs = getLogsByTaskId(taskId);
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ ...task, logs }));
+    return;
+  }
+
+  // GET /api/logs - List recent logs (optionally filtered by agentId)
+  if (req.method === "GET" && pathSegments[0] === "api" && pathSegments[1] === "logs") {
+    const limitParam = queryParams.get("limit");
+    const limit = limitParam ? parseInt(limitParam, 10) : 100;
+    const agentId = queryParams.get("agentId");
+    let logs: AgentLog[] = [];
+    if (agentId) {
+      logs = getLogsByAgentId(agentId).slice(0, limit);
+    } else {
+      logs = getAllLogs(limit);
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ logs }));
+    return;
+  }
+
+  // GET /api/stats - Dashboard summary stats
+  if (req.method === "GET" && pathSegments[0] === "api" && pathSegments[1] === "stats") {
+    const agents = getAllAgents();
+    const tasks = getAllTasks();
+
+    const stats = {
+      agents: {
+        total: agents.length,
+        idle: agents.filter((a) => a.status === "idle").length,
+        busy: agents.filter((a) => a.status === "busy").length,
+        offline: agents.filter((a) => a.status === "offline").length,
+      },
+      tasks: {
+        total: tasks.length,
+        pending: tasks.filter((t) => t.status === "pending").length,
+        in_progress: tasks.filter((t) => t.status === "in_progress").length,
+        completed: tasks.filter((t) => t.status === "completed").length,
+        failed: tasks.filter((t) => t.status === "failed").length,
+      },
+    };
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(stats));
+    return;
+  }
+
+  // GET /api/services - List all services (with optional filters: status, agentId, name)
+  if (
+    req.method === "GET" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "services" &&
+    !pathSegments[2]
+  ) {
+    const status = queryParams.get("status") as import("./types").ServiceStatus | null;
+    const agentId = queryParams.get("agentId");
+    const name = queryParams.get("name");
+    const services = getAllServices({
+      status: status || undefined,
+      agentId: agentId || undefined,
+      name: name || undefined,
+    });
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ services }));
+    return;
+  }
+
+  // GET /api/channels - List all channels
+  if (
+    req.method === "GET" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "channels" &&
+    !pathSegments[2]
+  ) {
+    const channels = getAllChannels();
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ channels }));
+    return;
+  }
+
+  // GET /api/channels/:id/messages - Get messages in a channel
+  if (
+    req.method === "GET" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "channels" &&
+    pathSegments[2] &&
+    pathSegments[3] === "messages" &&
+    !pathSegments[4]
+  ) {
+    const channelId = pathSegments[2];
+    const channel = getChannelById(channelId);
+
+    if (!channel) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Channel not found" }));
+      return;
+    }
+
+    const limitParam = queryParams.get("limit");
+    const limit = limitParam ? parseInt(limitParam, 10) : 50;
+    const since = queryParams.get("since") || undefined;
+    const before = queryParams.get("before") || undefined;
+
+    const messages = getChannelMessages(channelId, { limit, since, before });
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ messages }));
+    return;
+  }
+
+  // GET /api/channels/:id/messages/:messageId/thread - Get thread messages
+  if (
+    req.method === "GET" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "channels" &&
+    pathSegments[2] &&
+    pathSegments[3] === "messages" &&
+    pathSegments[4] &&
+    pathSegments[5] === "thread"
+  ) {
+    const channelId = pathSegments[2];
+    const parentMessageId = pathSegments[4];
+
+    const channel = getChannelById(channelId);
+    if (!channel) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Channel not found" }));
+      return;
+    }
+
+    // Get all messages that reply to this message
+    const allMessages = getChannelMessages(channelId, { limit: 1000 });
+    const threadMessages = allMessages.filter((m) => m.replyToId === parentMessageId);
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ messages: threadMessages }));
+    return;
+  }
+
+  // POST /api/channels/:id/messages - Post a message
+  if (
+    req.method === "POST" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "channels" &&
+    pathSegments[2] &&
+    pathSegments[3] === "messages"
+  ) {
+    const channelId = pathSegments[2];
+    const channel = getChannelById(channelId);
+
+    if (!channel) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Channel not found" }));
+      return;
+    }
+
+    // Parse request body
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) {
+      chunks.push(chunk);
+    }
+    const body = JSON.parse(Buffer.concat(chunks).toString());
+
+    if (!body.content || typeof body.content !== "string") {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing or invalid content" }));
+      return;
+    }
+
+    // agentId is optional (null for human users)
+    const agentId = body.agentId || null;
+
+    // If agentId provided, verify agent exists
+    if (agentId) {
+      const agent = getAgentById(agentId);
+      if (!agent) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid agentId" }));
+        return;
+      }
+    }
+
+    const message = postMessage(channelId, agentId, body.content, {
+      replyToId: body.replyToId,
+      mentions: body.mentions,
+    });
+
+    res.writeHead(201, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(message));
+    return;
+  }
+
   if (req.url !== "/mcp") {
     res.writeHead(404);
     res.end("Not Found");
@@ -236,9 +586,12 @@ const httpServer = createHttpServer(async (req, res) => {
 globalState.__httpServer = httpServer;
 globalState.__transports = transports;
 
-function shutdown() {
+async function shutdown() {
   console.log("Shutting down HTTP server...");
 
+  // Stop Slack bot
+  await stopSlackApp();
+
   // Close all active transports (SSE connections, etc.)
   for (const [id, transport] of Object.entries(transports)) {
     console.log(`[HTTP] Closing transport ${id}`);
@@ -262,8 +615,11 @@ if (!globalState.__sigintRegistered) {
 }
 
 httpServer
-  .listen(port, () => {
+  .listen(port, async () => {
     console.log(`MCP HTTP server running on http://localhost:${port}/mcp`);
+
+    // Start Slack bot (if configured)
+    await startSlackApp();
   })
   .on("error", (err) => {
     console.error("HTTP Server Error:", err);

package/src/prompts/base-prompt.ts

@@ -0,0 +1,131 @@
+const BASE_PROMPT_ROLE = `
+You are part of an agent swarm, your role is: {role} and your unique identified is {agentId}.
+
+The agent swarm operates in a collaborative manner to achieve complex tasks by dividing responsibilities among specialized agents.
+`;
+
+const BASE_PROMPT_REGISTER = `
+If you are not yet registered in the swarm, use the \`join-swarm\` tool to register yourself.
+`;
+
+const BASE_PROMPT_LEAD = `
+As the lead agent, you are responsible for coordinating the activities of all worker agents in the swarm.
+
+The lead assigns tasks, monitors progress, and ensures that the swarm operates efficiently towards achieving its overall objectives. The lead communicates with workers, provides guidance, and resolves any conflicts that may arise within the swarm.
+
+It should not perform worker tasks itself, but rather focus on leadership and coordination.
+
+#### General monitor and control tools
+
+- get-swarm: To get the list of all workers in the swarm along with their status.
+- get-tasks: To get the list of all tasks assigned to workers.
+- get-task-details: To get detailed information about a specific task.
+
+#### Task assignment tools
+
+- send-task: Quickly assign a new task to a specific worker, or to the general pool of unassigned tasks.
+- task-action: Manage tasks with different actions like claim, release, accept, reject, and complete.
+- store-progress: Critical tool to save your work and progress on tasks! Also useful to fix issues with tasks assigned to workers.
+- poll-task: Can be used to claim tasks from the unassigned pool if needed, or sometimes you might also get tasks assigned to you directly.
+`;
+
+const BASE_PROMPT_WORKER = `
+As a worker agent of the swarm, you are responsible for executing tasks assigned by the lead agent.
+
+- Each worker focuses on specific tasks or objectives, contributing to the overall goals of the swarm.
+- Workers MUST report their progress back to the lead and collaborate with other workers as needed to complete their assignments effectively.
+
+#### Useful tools for workers
+
+- poll-task: Automatically waits for new tasks assigned by the lead or claimed from the unassigned pool.
+- read-messages: To read messages sent to you by the lead or other workers, by default when a task is found, it will auto-assign it to you.
+- store-progress: Critical tool to save your work and progress on tasks!
+- task-action: Manage tasks with different actions like claim, release, accept, reject, and complete.
+`;
+
+const BASE_PROMPT_FILESYSTEM = `
+### You are given a full Ubuntu filesystem at /workspace, where you can find the following CRUCIAL files and directories:
+
+- /workspace/personal - Your personal directory for storing files, code, and data related to your tasks.
+- /workspace/personal/todos.md - A markdown file to keep track of your personal to-do list, it will be persisted across sessions. Use the /todos command to interact with it.
+- /workspace/shared - A shared directory accessible by all agents in the swarm for collaboration, critical if you want to share files or data with other agents, specially the lead agent.
+- /workspace/shared/thoughts/{name}/{plans,research} directories - A shared thoughts directory, where you and all other agents will be storing your plans and research notes. Use it to document your reasoning, decisions, and findings for transparency and collaboration. The commands to interact with it are /research, /create-plan and /implement-plan.
+  - There will be a /workspace/shared/thoughts/shared/... directory for general swarm-wide notes.
+  - There will be a /workspace/shared/thoughts/{yourId}/... directory for each agent to store their individual notes, you can access other agents' notes here as well.
+`;
+
+const BASE_PROMPT_GUIDELINES = `
+### Agent Swarm Operational Guidelines
+
+- Communication: Use the /swarm-chat command to communicate with other agents and the human operator. Keep everyone informed of your progress and any issues you encounter. It will allow you to see the internal Slack-like communication platform to: create and view channels (or DMs), read messages, and post messages.
+-
+`;
+
+const BASE_PROMPT_SYSTEM = `
+### System packages available
+
+You have a full Ubuntu environment with some packages pre-installed: node, bun, python3, curl, wget, git, gh, jq, etc.
+
+If you need to install additional packages, use "sudo apt-get install {package_name}".
+
+### External Swarm Access & Service Registry
+
+Port 3000 is exposed for web apps or APIs. Use PM2 for robust process management:
+
+**PM2 Commands:**
+- \`pm2 start <script> --name <name>\` - Start a service
+- \`pm2 stop|restart|delete <name>\` - Manage services
+- \`pm2 logs [name]\` - View logs
+- \`pm2 list\` - Show running processes
+
+**Service Registry Tools:**
+- \`register-service\` - Register your service for discovery and auto-restart
+- \`unregister-service\` - Remove your service from the registry
+- \`list-services\` - Find services exposed by other agents
+- \`update-service-status\` - Update your service's health status
+
+**Starting a New Service:**
+1. Start with PM2: \`pm2 start /workspace/myapp/server.js --name my-api\`
+2. Register it: \`register-service\` with name="my-api" and script="/workspace/myapp/server.js"
+3. Mark healthy: \`update-service-status\` with status="healthy"
+
+**Updating a Service:**
+1. Update locally: \`pm2 restart my-api\`
+2. If config changed, re-register: \`register-service\` with updated params (it upserts)
+
+**Stopping a Service:**
+1. Stop locally: \`pm2 delete my-api\`
+2. Remove from registry: \`unregister-service\` with name="my-api"
+
+**Auto-Restart:** Registered services are automatically restarted on container restart via ecosystem.config.js.
+
+Your service URL will be: \`https://{agentId}.{swarmUrl}\` (based on your agent ID, not name)
+
+**Health Checks:** Implement a \`/health\` endpoint returning 200 OK for monitoring.
+`;
+
+export type BasePromptArgs = {
+  role: string;
+  agentId: string;
+  swarmUrl: string;
+};
+
+export const getBasePrompt = (args: BasePromptArgs): string => {
+  const { role, agentId, swarmUrl } = args;
+
+  let prompt = BASE_PROMPT_ROLE.replace("{role}", role).replace("{agentId}", agentId);
+
+  prompt += BASE_PROMPT_REGISTER;
+
+  if (role === "lead") {
+    prompt += BASE_PROMPT_LEAD;
+  } else {
+    prompt += BASE_PROMPT_WORKER;
+  }
+
+  prompt += BASE_PROMPT_FILESYSTEM;
+  prompt += BASE_PROMPT_GUIDELINES;
+  prompt += BASE_PROMPT_SYSTEM.replace("{swarmUrl}", swarmUrl);
+
+  return prompt;
+};

package/src/server.ts

@@ -1,14 +1,43 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import pkg from "../package.json";
 import { initDb } from "./be/db";
+import { registerCreateChannelTool } from "./tools/create-channel";
 import { registerGetSwarmTool } from "./tools/get-swarm";
 import { registerGetTaskDetailsTool } from "./tools/get-task-details";
 import { registerGetTasksTool } from "./tools/get-tasks";
 import { registerJoinSwarmTool } from "./tools/join-swarm";
+// Messaging capability
+import { registerListChannelsTool } from "./tools/list-channels";
+import { registerListServicesTool } from "./tools/list-services";
 import { registerMyAgentInfoTool } from "./tools/my-agent-info";
 import { registerPollTaskTool } from "./tools/poll-task";
+import { registerPostMessageTool } from "./tools/post-message";
+import { registerReadMessagesTool } from "./tools/read-messages";
+// Services capability
+import { registerRegisterServiceTool } from "./tools/register-service";
 import { registerSendTaskTool } from "./tools/send-task";
 import { registerStoreProgressTool } from "./tools/store-progress";
+// Task pool capability
+import { registerTaskActionTool } from "./tools/task-action";
+import { registerUnregisterServiceTool } from "./tools/unregister-service";
+// Profiles capability
+import { registerUpdateProfileTool } from "./tools/update-profile";
+import { registerUpdateServiceStatusTool } from "./tools/update-service-status";
+
+// Capability-based feature flags
+// Default: all capabilities enabled
+const DEFAULT_CAPABILITIES = "core,task-pool,messaging,profiles,services";
+const CAPABILITIES = new Set(
+  (process.env.CAPABILITIES || DEFAULT_CAPABILITIES).split(",").map((s) => s.trim()),
+);
+
+export function hasCapability(cap: string): boolean {
+  return CAPABILITIES.has(cap);
+}
+
+export function getEnabledCapabilities(): string[] {
+  return Array.from(CAPABILITIES);
+}
 
 export function createServer() {
   // Initialize database with WAL mode
@@ -27,6 +56,7 @@ export function createServer() {
     },
   );
 
+  // Core tools - always registered
   registerJoinSwarmTool(server);
   registerPollTaskTool(server);
   registerGetSwarmTool(server);
@@ -36,5 +66,31 @@ export function createServer() {
   registerStoreProgressTool(server);
   registerMyAgentInfoTool(server);
 
+  // Task pool capability - task pool operations (create unassigned, claim, release, accept, reject)
+  if (hasCapability("task-pool")) {
+    registerTaskActionTool(server);
+  }
+
+  // Messaging capability - channel-based communication
+  if (hasCapability("messaging")) {
+    registerListChannelsTool(server);
+    registerCreateChannelTool(server);
+    registerPostMessageTool(server);
+    registerReadMessagesTool(server);
+  }
+
+  // Profiles capability - agent profile management
+  if (hasCapability("profiles")) {
+    registerUpdateProfileTool(server);
+  }
+
+  // Services capability - PM2/background service registry
+  if (hasCapability("services")) {
+    registerRegisterServiceTool(server);
+    registerUnregisterServiceTool(server);
+    registerListServicesTool(server);
+    registerUpdateServiceStatusTool(server);
+  }
+
   return server;
 }