@desplega.ai/agent-swarm 1.0.1

package/src/hooks/hook.ts

@@ -0,0 +1,198 @@
+#!/usr/bin/env bun
+
+import pkg from "../../package.json";
+import type { Agent } from "../types";
+
+// @ts-ignore
+const SERVER_NAME = pkg.config?.name ?? "agent-swarm";
+
+type McpServerConfig = {
+	url: string;
+	headers: {
+		Authorization: string;
+		"X-Agent-ID": string;
+	};
+};
+
+interface HookMessage {
+	hook_event_name: string;
+	session_id?: string;
+	transcript_path?: string;
+	permission_mode?: string;
+	cwd?: string;
+	source?: string;
+	trigger?: string;
+	custom_instructions?: string;
+	tool_name?: string;
+	tool_input?: Record<string, unknown>;
+	tool_response?: Record<string, unknown>;
+	tool_use_id?: string;
+	prompt?: string;
+	stop_hook_active?: boolean;
+}
+
+/**
+ * Main hook handler - processes Claude Code hook events
+ */
+export async function handleHook(): Promise<void> {
+	const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+	let mcpConfig: McpServerConfig | undefined;
+
+	try {
+		const mcpFile = Bun.file(`${projectDir}/.mcp.json`);
+		if (await mcpFile.exists()) {
+			const config = await mcpFile.json();
+			mcpConfig = config?.mcpServers?.[SERVER_NAME] as McpServerConfig;
+		}
+	} catch {
+		// No config found, proceed without MCP
+	}
+
+	let msg: HookMessage;
+	try {
+		msg = await Bun.stdin.json();
+	} catch {
+		// No stdin or invalid JSON - exit silently
+		return;
+	}
+
+	const getBaseUrl = (): string => {
+		if (!mcpConfig) return "";
+		try {
+			const url = new URL(mcpConfig.url);
+			return url.origin;
+		} catch {
+			return "";
+		}
+	};
+
+	const ping = async (): Promise<void> => {
+		if (!mcpConfig) return;
+
+		try {
+			await fetch(`${getBaseUrl()}/ping`, {
+				method: "POST",
+				headers: mcpConfig.headers,
+			});
+		} catch {
+			// Silently fail - server might not be running
+		}
+	};
+
+	const close = async (): Promise<void> => {
+		if (!mcpConfig) return;
+
+		try {
+			await fetch(`${getBaseUrl()}/close`, {
+				method: "POST",
+				headers: mcpConfig.headers,
+			});
+		} catch {
+			// Silently fail
+		}
+	};
+
+	const getAgentInfo = async (): Promise<Agent | undefined> => {
+		if (!mcpConfig) return;
+
+		try {
+			const resp = await fetch(`${getBaseUrl()}/me`, {
+				method: "GET",
+				headers: mcpConfig.headers,
+			});
+
+			if ([400, 404].includes(resp.status)) {
+				return;
+			}
+
+			return (await resp.json()) as Agent;
+		} catch {
+			// Silently fail
+		}
+
+		return;
+	};
+
+	// Ping the server to indicate activity
+	await ping();
+
+	// Get current agent info
+	const agentInfo = await getAgentInfo();
+
+	// Always output agent status
+	if (agentInfo) {
+		console.log(
+			`You are registered as ${agentInfo.isLead ? "lead" : "worker"} agent "${agentInfo.name}" with ID: ${agentInfo.id} (status: ${agentInfo.status}) as of ${new Date().toISOString()}.`,
+		);
+	} else {
+		console.log(
+			`You are not registered in the agent swarm yet. Use the join-swarm tool to register yourself, then check your status with my-agent-info.
+
+If the ${SERVER_NAME} server is not running or disabled, disregard this message.`,
+		);
+	}
+
+	// Handle specific hook events
+	switch (msg.hook_event_name) {
+		case "SessionStart":
+			if (!agentInfo) break;
+
+			if (agentInfo.isLead) {
+				console.log(
+					`As the lead agent, you are responsible for coordinating the swarm to fulfill the user's request efficiently. Use the ${SERVER_NAME} tools to assign tasks to worker agents and monitor their progress.`,
+				);
+			} else {
+				console.log(
+					`As a worker agent, you should call the poll-task tool to wait for tasks assigned by the lead agent, unless specified otherwise.`,
+				);
+			}
+			break;
+
+		case "PreCompact":
+			// Covered by SessionStart hook
+			break;
+
+		case "PreToolUse":
+			// Nothing to do here for now
+			break;
+
+		case "PostToolUse":
+			if (agentInfo) {
+				if (agentInfo.isLead) {
+					if (msg.tool_name?.endsWith("send-task")) {
+						const maybeTaskId = (msg.tool_response as { task?: { id?: string } })
+							?.task?.id;
+
+						console.log(
+							`Task sent successfully.${maybeTaskId ? ` Task ID: ${maybeTaskId}.` : ""} Monitor progress using the get-task-details tool periodically.`,
+						);
+					}
+				} else {
+					console.log(
+						`Remember to call store-progress periodically to update the lead agent on your progress.`,
+					);
+				}
+			}
+			break;
+
+		case "UserPromptSubmit":
+			// Nothing specific for now
+			break;
+
+		case "Stop":
+			// Mark the agent as offline
+			await close();
+			break;
+
+		default:
+			break;
+	}
+}
+
+// Run directly when executed as a script
+const isMainModule = import.meta.main;
+if (isMainModule) {
+	await handleHook();
+	process.exit(0);
+}

package/src/http.ts

@@ -0,0 +1,262 @@
+import { randomUUID } from "node:crypto";
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+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";
+
+const port = parseInt(process.env.PORT || process.argv[2] || "3013", 10);
+const apiKey = process.env.API_KEY || "";
+
+// Use globalThis to persist state across hot reloads
+const globalState = globalThis as typeof globalThis & {
+  __httpServer?: Server<typeof IncomingMessage, typeof ServerResponse>;
+  __transports?: Record<string, StreamableHTTPServerTransport>;
+  __sigintRegistered?: boolean;
+};
+
+// Clean up previous server on hot reload
+if (globalState.__httpServer) {
+  console.log("[HTTP] Hot reload detected, closing previous server...");
+  globalState.__httpServer.close();
+}
+
+const transports: Record<string, StreamableHTTPServerTransport> = globalState.__transports ?? {};
+
+function setCorsHeaders(res: ServerResponse) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "*");
+  res.setHeader("Access-Control-Expose-Headers", "*");
+}
+
+const httpServer = createHttpServer(async (req, res) => {
+  setCorsHeaders(res);
+
+  // Handle preflight
+  if (req.method === "OPTIONS") {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  const sessionId = req.headers["mcp-session-id"] as string | undefined;
+  const myAgentId = req.headers["x-agent-id"] as string | undefined;
+
+  console.log(
+    `[HTTP] ${req.method} ${req.url} (sessionId=${sessionId || ""}, agentId=${myAgentId || ""})`,
+  );
+
+  if (req.url === "/health") {
+    // Read version from package.json
+    const version = (await Bun.file("package.json").json()).version;
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        status: "ok",
+        version,
+      }),
+    );
+
+    return;
+  }
+
+  // API key authentication (if API_KEY is configured)
+  if (apiKey) {
+    const authHeader = req.headers.authorization;
+    const providedKey = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
+
+    if (providedKey !== apiKey) {
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Unauthorized" }));
+      return;
+    }
+  }
+
+  if (req.method === "GET" && req.url === "/me") {
+    if (!myAgentId) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing X-Agent-ID header" }));
+      return;
+    }
+
+    const agent = getAgentById(myAgentId);
+
+    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;
+  }
+
+  if (req.method === "POST" && req.url === "/ping") {
+    if (!myAgentId) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing X-Agent-ID header" }));
+      return;
+    }
+
+    const tx = getDb().transaction(() => {
+      const agent = getAgentById(myAgentId);
+
+      if (!agent) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Agent not found" }));
+        return;
+      }
+
+      let status: AgentStatus = "idle";
+
+      if (agent.status === "busy") {
+        status = "busy";
+      }
+
+      updateAgentStatus(agent.id, status);
+    });
+
+    tx();
+
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  if (req.method === "POST" && req.url === "/close") {
+    if (!myAgentId) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing X-Agent-ID header" }));
+      return;
+    }
+
+    const tx = getDb().transaction(() => {
+      const agent = getAgentById(myAgentId);
+
+      if (!agent) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Agent not found" }));
+        return;
+      }
+
+      updateAgentStatus(agent.id, "offline");
+    });
+
+    tx();
+
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  if (req.url !== "/mcp") {
+    res.writeHead(404);
+    res.end("Not Found");
+    return;
+  }
+
+  if (req.method === "POST") {
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) {
+      chunks.push(chunk);
+    }
+    const body = JSON.parse(Buffer.concat(chunks).toString());
+
+    let transport: StreamableHTTPServerTransport;
+
+    if (sessionId && transports[sessionId]) {
+      transport = transports[sessionId];
+    } else if (!sessionId && isInitializeRequest(body)) {
+      transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (id) => {
+          transports[id] = transport;
+        },
+        onsessionclosed: (id) => {
+          delete transports[id];
+        },
+      });
+
+      transport.onclose = () => {
+        if (transport.sessionId) {
+          delete transports[transport.sessionId];
+        }
+      };
+
+      const server = createServer();
+      await server.connect(transport);
+    } else {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "Invalid session" },
+          id: null,
+        }),
+      );
+      return;
+    }
+
+    await transport.handleRequest(req, res, body);
+    return;
+  }
+
+  if (req.method === "GET" || req.method === "DELETE") {
+    if (sessionId && transports[sessionId]) {
+      await transports[sessionId].handleRequest(req, res);
+      return;
+    }
+    res.writeHead(400);
+    res.end("Invalid session");
+    return;
+  }
+
+  res.writeHead(405);
+  res.end("Method not allowed");
+});
+
+// Store references in globalThis for hot reload persistence
+globalState.__httpServer = httpServer;
+globalState.__transports = transports;
+
+function shutdown() {
+  console.log("Shutting down HTTP server...");
+
+  // Close all active transports (SSE connections, etc.)
+  for (const [id, transport] of Object.entries(transports)) {
+    console.log(`[HTTP] Closing transport ${id}`);
+    transport.close();
+    delete transports[id];
+  }
+
+  // Close all active connections forcefully
+  httpServer.closeAllConnections();
+  httpServer.close(() => {
+    closeDb();
+    console.log("MCP HTTP server closed, and database connection closed");
+    process.exit(0);
+  });
+}
+
+// Only register SIGINT handler once (avoid duplicates on hot reload)
+if (!globalState.__sigintRegistered) {
+  globalState.__sigintRegistered = true;
+  process.on("SIGINT", shutdown);
+}
+
+httpServer
+  .listen(port, () => {
+    console.log(`MCP HTTP server running on http://localhost:${port}/mcp`);
+  })
+  .on("error", (err) => {
+    console.error("HTTP Server Error:", err);
+  });

package/src/server.ts

@@ -0,0 +1,41 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { initDb } from "./be/db";
+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";
+import { registerMyAgentInfoTool } from "./tools/my-agent-info";
+import { registerPollTaskTool } from "./tools/poll-task";
+import { registerSendTaskTool } from "./tools/send-task";
+import { registerStoreProgressTool } from "./tools/store-progress";
+import pkg from "../package.json";
+
+
+export function createServer() {
+  // Initialize database with WAL mode
+  initDb();
+
+  const server = new McpServer(
+    {
+      name: pkg.name,
+      version: pkg.version,
+      description: pkg.description,
+    },
+    {
+      capabilities: {
+        logging: {},
+      },
+    },
+  );
+
+  registerJoinSwarmTool(server);
+  registerPollTaskTool(server);
+  registerGetSwarmTool(server);
+  registerGetTasksTool(server);
+  registerSendTaskTool(server);
+  registerGetTaskDetailsTool(server);
+  registerStoreProgressTool(server);
+  registerMyAgentInfoTool(server);
+
+  return server;
+}

package/src/stdio.ts

@@ -0,0 +1,21 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "@/server";
+import { closeDb } from "./be/db";
+
+async function main() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+
+  await server.connect(transport);
+
+  await server.sendLoggingMessage({
+    level: "info",
+    data: "MCP server connected via stdio",
+  });
+}
+
+main()
+  .catch(console.error)
+  .finally(() => {
+    closeDb();
+  });

package/src/tools/get-swarm.ts

@@ -0,0 +1,37 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAllAgents } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { AgentSchema } from "@/types";
+
+export const registerGetSwarmTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "get-swarm",
+    {
+      title: "Get the agent swarm",
+      description: "Returns a list of agents in the swarm without their tasks.",
+      inputSchema: z.object({
+        a: z.string().optional(),
+      }),
+      outputSchema: z.object({
+        agents: z.array(AgentSchema),
+      }),
+    },
+    async (_input, requestInfo, _meta) => {
+      const agents = getAllAgents();
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${agents.length} agent(s) in the swarm. Requested by session: ${requestInfo.sessionId}`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          agents,
+        },
+      };
+    },
+  );
+};

package/src/tools/get-task-details.ts

@@ -0,0 +1,48 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getTaskById } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { AgentTaskSchema } from "@/types";
+
+export const registerGetTaskDetailsTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "get-task-details",
+    {
+      title: "Get task details",
+      description:
+        "Returns detailed information about a specific task, including output and failure reason.",
+      inputSchema: z.object({
+        taskId: z.uuid().describe("The ID of the task to get details for."),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        task: AgentTaskSchema.optional(),
+      }),
+    },
+    async ({ taskId }, requestInfo, _meta) => {
+      const task = getTaskById(taskId);
+
+      if (!task) {
+        return {
+          content: [{ type: "text", text: `Task with ID "${taskId}" not found.` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Task with ID "${taskId}" not found.`,
+          },
+        };
+      }
+
+      return {
+        content: [{ type: "text", text: `Task "${taskId}" details retrieved.` }],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Task "${taskId}" details retrieved.`,
+          task,
+        },
+      };
+    },
+  );
+};

package/src/tools/get-tasks.ts

@@ -0,0 +1,78 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAllTasks } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { AgentTaskStatusSchema } from "@/types";
+
+const TaskSummarySchema = z.object({
+  id: z.string(),
+  task: z.string(),
+  status: AgentTaskStatusSchema,
+  createdAt: z.string(),
+  lastUpdatedAt: z.string(),
+  finishedAt: z.string().optional(),
+  progress: z.string().optional(),
+});
+
+export const registerGetTasksTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "get-tasks",
+    {
+      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.",
+      inputSchema: z.object({
+        status: AgentTaskStatusSchema.optional().describe(
+          "Filter by task status. Defaults to 'in_progress'.",
+        ),
+        mineOnly: z
+          .boolean()
+          .optional()
+          .describe(
+            "If true, only return tasks assigned to your agent. Requires X-Agent-ID header.",
+          ),
+      }),
+      outputSchema: z.object({
+        tasks: z.array(TaskSummarySchema),
+      }),
+    },
+    async ({ status, mineOnly }, requestInfo, _meta) => {
+      const filterStatus = status ?? "in_progress";
+      let tasks = getAllTasks(filterStatus);
+
+      // 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);
+        }
+      }
+
+      const taskSummaries = tasks.map((t) => ({
+        id: t.id,
+        task: t.task,
+        status: t.status,
+        createdAt: t.createdAt,
+        lastUpdatedAt: t.lastUpdatedAt,
+        finishedAt: t.finishedAt,
+        progress: t.progress,
+      }));
+
+      const mineOnlyMsg = mineOnly ? " (mine only)" : "";
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${taskSummaries.length} task(s) with status '${filterStatus}'${mineOnlyMsg}.`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          tasks: taskSummaries,
+        },
+      };
+    },
+  );
+};