@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/src/tools/tool-config.ts

@@ -0,0 +1,117 @@
+/**
+ * Tool classification for context optimization.
+ *
+ * CORE_TOOLS: Always in Claude Code's context (no Tool Search needed).
+ * These are tools that every worker/lead session needs immediately at startup
+ * for task lifecycle, basic communication, and memory recall.
+ *
+ * All other registered tools rely on Claude Code's Tool Search feature
+ * (auto-activates when total tool tokens exceed ~10K).
+ */
+
+/** Tools that must always be available in context (not deferred by Tool Search) */
+export const CORE_TOOLS = new Set([
+  // Session bootstrap
+  "join-swarm", // first tool called on startup
+  "my-agent-info", // identity check
+  "poll-task", // task discovery
+
+  // Task lifecycle (used every session)
+  "get-task-details", // inspect assigned task
+  "store-progress", // update/complete/fail tasks
+  "task-action", // claim/release/accept/reject
+  "send-task", // delegate subtasks
+  "get-tasks", // list/filter tasks
+
+  // Communication (used every session)
+  "read-messages", // internal swarm chat
+  "post-message", // internal swarm chat
+  "slack-reply", // respond to Slack threads
+  "slack-read", // read Slack thread history
+
+  // Memory (used at session start)
+  "memory-search", // recall relevant context
+  "memory-get", // retrieve full memory content
+
+  // Swarm awareness
+  "get-swarm", // check who's online
+]);
+
+/** Tools that can be discovered via Tool Search on demand */
+export const DEFERRED_TOOLS = new Set([
+  // Scheduling (5)
+  "list-schedules",
+  "create-schedule",
+  "update-schedule",
+  "delete-schedule",
+  "run-schedule-now",
+
+  // Workflows (9)
+  "create-workflow",
+  "list-workflows",
+  "get-workflow",
+  "update-workflow",
+  "delete-workflow",
+  "trigger-workflow",
+  "list-workflow-runs",
+  "get-workflow-run",
+  "retry-workflow-run",
+
+  // Epics (7)
+  "create-epic",
+  "list-epics",
+  "get-epic-details",
+  "update-epic",
+  "delete-epic",
+  "assign-task-to-epic",
+  "unassign-task-from-epic",
+
+  // Services (4)
+  "register-service",
+  "unregister-service",
+  "list-services",
+  "update-service-status",
+
+  // Config (4)
+  "set-config",
+  "get-config",
+  "list-config",
+  "delete-config",
+
+  // Profiles (3)
+  "update-profile",
+  "context-history",
+  "context-diff",
+
+  // Slack extras (4)
+  "slack-upload-file",
+  "slack-download-file",
+  "slack-list-channels",
+  "slack-post",
+
+  // Channel management (2)
+  "create-channel",
+  "delete-channel",
+  "list-channels",
+
+  // AgentMail (1)
+  "register-agentmail-inbox",
+
+  // Tracker (6)
+  "tracker-status",
+  "tracker-link-task",
+  "tracker-link-epic",
+  "tracker-unlink",
+  "tracker-sync-status",
+  "tracker-map-agent",
+
+  // Debug (1)
+  "db-query",
+
+  // Other (3)
+  "cancel-task",
+  "inject-learning",
+]);
+
+/** All known tool names = CORE_TOOLS ∪ DEFERRED_TOOLS */
+export const ALL_TOOLS = new Set([...CORE_TOOLS, ...DEFERRED_TOOLS]);

package/src/tools/tracker/index.ts

@@ -0,0 +1,6 @@
+export { registerTrackerLinkEpicTool } from "./tracker-link-epic";
+export { registerTrackerLinkTaskTool } from "./tracker-link-task";
+export { registerTrackerMapAgentTool } from "./tracker-map-agent";
+export { registerTrackerStatusTool } from "./tracker-status";
+export { registerTrackerSyncStatusTool } from "./tracker-sync-status";
+export { registerTrackerUnlinkTool } from "./tracker-unlink";

package/src/tools/tracker/tracker-link-epic.ts

@@ -0,0 +1,64 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createTrackerSync } from "@/be/db-queries/tracker";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerTrackerLinkEpicTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "tracker-link-epic",
+    {
+      title: "Link Epic to Tracker",
+      description: "Link a swarm epic to an external tracker issue or project.",
+      annotations: { destructiveHint: false },
+
+      inputSchema: z.object({
+        provider: z.string().describe("Tracker provider (e.g. 'linear')"),
+        swarmEpicId: z.string().describe("The swarm epic ID to link"),
+        externalId: z.string().describe("The external issue/project ID in the tracker"),
+        externalIdentifier: z
+          .string()
+          .optional()
+          .describe("Human-readable identifier (e.g. 'ENG-42')"),
+        externalUrl: z.string().optional().describe("URL to the external issue/project"),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        sync: z.any().optional(),
+      }),
+    },
+    async (args, _requestInfo, _meta) => {
+      try {
+        const sync = createTrackerSync({
+          provider: args.provider,
+          entityType: "epic",
+          swarmId: args.swarmEpicId,
+          externalId: args.externalId,
+          externalIdentifier: args.externalIdentifier ?? null,
+          externalUrl: args.externalUrl ?? null,
+          syncDirection: "bidirectional",
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Linked epic ${args.swarmEpicId} to ${args.provider} issue ${args.externalIdentifier ?? args.externalId}`,
+            },
+          ],
+          structuredContent: {
+            success: true,
+            message: `Linked epic ${args.swarmEpicId} to ${args.provider} issue ${args.externalIdentifier ?? args.externalId}.`,
+            sync,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to link epic: ${message}` }],
+          structuredContent: { success: false, message: `Failed: ${message}` },
+        };
+      }
+    },
+  );
+};

package/src/tools/tracker/tracker-link-task.ts

@@ -0,0 +1,64 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createTrackerSync } from "@/be/db-queries/tracker";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerTrackerLinkTaskTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "tracker-link-task",
+    {
+      title: "Link Task to Tracker",
+      description: "Link a swarm task to an external tracker issue.",
+      annotations: { destructiveHint: false },
+
+      inputSchema: z.object({
+        provider: z.string().describe("Tracker provider (e.g. 'linear')"),
+        swarmTaskId: z.string().describe("The swarm task ID to link"),
+        externalId: z.string().describe("The external issue ID in the tracker"),
+        externalIdentifier: z
+          .string()
+          .optional()
+          .describe("Human-readable identifier (e.g. 'ENG-42')"),
+        externalUrl: z.string().optional().describe("URL to the external issue"),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        sync: z.any().optional(),
+      }),
+    },
+    async (args, _requestInfo, _meta) => {
+      try {
+        const sync = createTrackerSync({
+          provider: args.provider,
+          entityType: "task",
+          swarmId: args.swarmTaskId,
+          externalId: args.externalId,
+          externalIdentifier: args.externalIdentifier ?? null,
+          externalUrl: args.externalUrl ?? null,
+          syncDirection: "bidirectional",
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Linked task ${args.swarmTaskId} to ${args.provider} issue ${args.externalIdentifier ?? args.externalId}`,
+            },
+          ],
+          structuredContent: {
+            success: true,
+            message: `Linked task ${args.swarmTaskId} to ${args.provider} issue ${args.externalIdentifier ?? args.externalId}.`,
+            sync,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to link task: ${message}` }],
+          structuredContent: { success: false, message: `Failed: ${message}` },
+        };
+      }
+    },
+  );
+};

package/src/tools/tracker/tracker-map-agent.ts

@@ -0,0 +1,57 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createTrackerAgentMapping } from "@/be/db-queries/tracker";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerTrackerMapAgentTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "tracker-map-agent",
+    {
+      title: "Map Agent to Tracker User",
+      description: "Map a swarm agent to an external tracker user (for assignment sync).",
+      annotations: { destructiveHint: false },
+
+      inputSchema: z.object({
+        provider: z.string().describe("Tracker provider (e.g. 'linear')"),
+        agentId: z.string().describe("The swarm agent ID"),
+        externalUserId: z.string().describe("The external user ID in the tracker"),
+        agentName: z.string().describe("Display name for the agent mapping"),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        mapping: z.any().optional(),
+      }),
+    },
+    async (args, _requestInfo, _meta) => {
+      try {
+        const mapping = createTrackerAgentMapping({
+          provider: args.provider,
+          agentId: args.agentId,
+          externalUserId: args.externalUserId,
+          agentName: args.agentName,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Mapped agent ${args.agentName} to ${args.provider} user ${args.externalUserId}`,
+            },
+          ],
+          structuredContent: {
+            success: true,
+            message: `Mapped agent ${args.agentName} to ${args.provider} user ${args.externalUserId}.`,
+            mapping,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to map agent: ${message}` }],
+          structuredContent: { success: false, message: `Failed: ${message}` },
+        };
+      }
+    },
+  );
+};

package/src/tools/tracker/tracker-status.ts

@@ -0,0 +1,56 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getOAuthApp, getOAuthTokens } from "@/be/db-queries/oauth";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerTrackerStatusTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "tracker-status",
+    {
+      title: "Tracker Status",
+      description:
+        "Show all connected trackers and their OAuth status (token expiry, workspace info).",
+      annotations: { readOnlyHint: true },
+
+      outputSchema: z.object({
+        success: z.boolean(),
+        trackers: z.array(
+          z.object({
+            provider: z.string(),
+            connected: z.boolean(),
+            tokenExpiresAt: z.string().nullable(),
+            scopes: z.string().nullable(),
+            redirectUri: z.string().nullable(),
+          }),
+        ),
+      }),
+    },
+    async (_requestInfo, _meta) => {
+      const providers = ["linear"] as const;
+      const trackers = providers.map((provider) => {
+        const app = getOAuthApp(provider);
+        const tokens = getOAuthTokens(provider);
+
+        return {
+          provider,
+          connected: !!tokens,
+          tokenExpiresAt: tokens?.expiresAt ?? null,
+          scopes: tokens?.scope ?? app?.scopes ?? null,
+          redirectUri: app?.redirectUri ?? null,
+        };
+      });
+
+      const summary = trackers
+        .map((t) => `${t.provider}: ${t.connected ? "connected" : "not connected"}`)
+        .join(", ");
+
+      return {
+        content: [{ type: "text", text: `Tracker status: ${summary}` }],
+        structuredContent: {
+          success: true,
+          trackers,
+        },
+      };
+    },
+  );
+};

package/src/tools/tracker/tracker-sync-status.ts

@@ -0,0 +1,42 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAllTrackerSyncs } from "@/be/db-queries/tracker";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerTrackerSyncStatusTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "tracker-sync-status",
+    {
+      title: "Tracker Sync Status",
+      description: "Show all tracker sync mappings with their state.",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        provider: z.string().optional().describe("Filter by provider (e.g. 'linear')"),
+        entityType: z.enum(["task", "epic"]).optional().describe("Filter by entity type"),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        count: z.number(),
+        syncs: z.array(z.any()),
+      }),
+    },
+    async (args, _requestInfo, _meta) => {
+      const syncs = getAllTrackerSyncs(args.provider, args.entityType);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${syncs.length} tracker sync mapping(s)${args.provider ? ` for ${args.provider}` : ""}${args.entityType ? ` (${args.entityType})` : ""}.`,
+          },
+        ],
+        structuredContent: {
+          success: true,
+          count: syncs.length,
+          syncs,
+        },
+      };
+    },
+  );
+};

package/src/tools/tracker/tracker-unlink.ts

@@ -0,0 +1,41 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { deleteTrackerSync } from "@/be/db-queries/tracker";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerTrackerUnlinkTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "tracker-unlink",
+    {
+      title: "Unlink Tracker Sync",
+      description: "Remove a tracker sync mapping by ID.",
+      annotations: { destructiveHint: true },
+
+      inputSchema: z.object({
+        syncId: z.string().describe("The tracker sync mapping ID to remove"),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async (args, _requestInfo, _meta) => {
+      try {
+        deleteTrackerSync(args.syncId);
+        return {
+          content: [{ type: "text", text: `Removed tracker sync mapping ${args.syncId}` }],
+          structuredContent: {
+            success: true,
+            message: `Removed tracker sync mapping ${args.syncId}.`,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to unlink: ${message}` }],
+          structuredContent: { success: false, message: `Failed: ${message}` },
+        };
+      }
+    },
+  );
+};

package/src/tools/unregister-service.ts

@@ -10,6 +10,8 @@ export const registerUnregisterServiceTool = (server: McpServer) => {
       title: "Unregister Service",
       description:
         "Remove a service from the registry. Use this after stopping a PM2 process. You can only unregister your own services.",
+      annotations: { destructiveHint: true },
+
       inputSchema: z.object({
         serviceId: z.uuid().optional().describe("Service ID to unregister."),
         name: z

package/src/tools/update-profile.ts

@@ -11,6 +11,8 @@ export const registerUpdateProfileTool = (server: McpServer) => {
       title: "Update Profile",
       description:
         "Updates the calling agent's profile information (name, description, role, capabilities).",
+      annotations: { idempotentHint: true },
+
       inputSchema: z.object({
         name: z.string().min(1).optional().describe("Agent name."),
         description: z.string().optional().describe("Agent description."),
@@ -30,6 +32,34 @@ export const registerUpdateProfileTool = (server: McpServer) => {
           .describe(
             "Personal CLAUDE.md content. Loaded on session start and synced back on session end. Use for persistent notes and instructions.",
           ),
+        soulMd: z
+          .string()
+          .max(65536)
+          .optional()
+          .describe(
+            "Soul content: persona and behavioral directives. Updates both DB and /workspace/SOUL.md.",
+          ),
+        identityMd: z
+          .string()
+          .max(65536)
+          .optional()
+          .describe(
+            "Identity content: expertise and working style. Updates both DB and /workspace/IDENTITY.md.",
+          ),
+        setupScript: z
+          .string()
+          .max(65536)
+          .optional()
+          .describe(
+            "Setup script content (bash). Runs at container start to install tools, configure environment. Persists across sessions. Also written to /workspace/start-up.sh.",
+          ),
+        toolsMd: z
+          .string()
+          .max(65536)
+          .optional()
+          .describe(
+            "Environment-specific operational knowledge. Repos, services, SSH hosts, APIs, device names — anything specific to your setup. Synced to /workspace/TOOLS.md.",
+          ),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -38,7 +68,11 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         agent: AgentSchema.optional(),
       }),
     },
-    async ({ name, description, role, capabilities, claudeMd }, requestInfo, _meta) => {
+    async (
+      { name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, toolsMd },
+      requestInfo,
+      _meta,
+    ) => {
       if (!requestInfo.agentId) {
         return {
           content: [{ type: "text", text: 'Agent ID not found. Set the "X-Agent-ID" header.' }],
@@ -55,20 +89,24 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         description === undefined &&
         role === undefined &&
         capabilities === undefined &&
-        claudeMd === undefined
+        claudeMd === undefined &&
+        soulMd === undefined &&
+        identityMd === undefined &&
+        setupScript === undefined &&
+        toolsMd === undefined
       ) {
         return {
           content: [
             {
               type: "text",
-              text: "At least one field (name, description, role, capabilities, or claudeMd) must be provided.",
+              text: "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, or toolsMd) must be provided.",
             },
           ],
           structuredContent: {
             yourAgentId: requestInfo.agentId,
             success: false,
             message:
-              "At least one field (name, description, role, capabilities, or claudeMd) must be provided.",
+              "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, or toolsMd) must be provided.",
           },
         };
       }
@@ -92,12 +130,53 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         }
 
         // Update profile fields if provided
-        agent = updateAgentProfile(requestInfo.agentId, {
-          description,
-          role,
-          capabilities,
-          claudeMd,
-        });
+        agent = updateAgentProfile(
+          requestInfo.agentId,
+          {
+            description,
+            role,
+            capabilities,
+            claudeMd,
+            soulMd,
+            identityMd,
+            setupScript,
+            toolsMd,
+          },
+          {
+            changeSource: "self_edit",
+            changedByAgentId: requestInfo.agentId,
+          },
+        );
+
+        // Write updated files to workspace so changes are visible immediately
+        if (soulMd !== undefined) {
+          try {
+            await Bun.write("/workspace/SOUL.md", soulMd);
+          } catch {
+            /* ignore */
+          }
+        }
+        if (identityMd !== undefined) {
+          try {
+            await Bun.write("/workspace/IDENTITY.md", identityMd);
+          } catch {
+            /* ignore */
+          }
+        }
+        if (setupScript !== undefined) {
+          try {
+            await Bun.write("/workspace/start-up.sh", `#!/bin/bash\n${setupScript}\n`);
+          } catch {
+            /* ignore */
+          }
+        }
+        if (toolsMd !== undefined) {
+          try {
+            await Bun.write("/workspace/TOOLS.md", toolsMd);
+          } catch {
+            /* ignore */
+          }
+        }
 
         if (!agent) {
           return {
@@ -116,6 +195,10 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         if (role !== undefined) updatedFields.push("role");
         if (capabilities !== undefined) updatedFields.push("capabilities");
         if (claudeMd !== undefined) updatedFields.push("claudeMd");
+        if (soulMd !== undefined) updatedFields.push("soulMd");
+        if (identityMd !== undefined) updatedFields.push("identityMd");
+        if (setupScript !== undefined) updatedFields.push("setupScript");
+        if (toolsMd !== undefined) updatedFields.push("toolsMd");
 
         return {
           content: [{ type: "text", text: `Updated profile: ${updatedFields.join(", ")}.` }],

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

@@ -11,6 +11,8 @@ export const registerUpdateServiceStatusTool = (server: McpServer) => {
       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.",
+      annotations: { idempotentHint: true },
+
       inputSchema: z.object({
         serviceId: z.uuid().optional().describe("Service ID to update."),
         name: z.string().optional().describe("Service name to update (alternative to serviceId)."),

package/src/tools/utils.ts

@@ -18,22 +18,31 @@ type Meta = RequestHandlerExtra<ServerRequest, ServerNotification>;
 export type RequestInfo = {
   sessionId: string | undefined;
   agentId: string | undefined;
+  sourceTaskId: string | undefined;
 };
 
 export const getRequestInfo = (req: Meta): RequestInfo => {
   const agentIdHeader = req.requestInfo?.headers?.["x-agent-id"];
+  const sourceTaskIdHeader = req.requestInfo?.headers?.["x-source-task-id"];
 
   let agentId: string | undefined;
-
   if (Array.isArray(agentIdHeader)) {
     agentId = agentIdHeader?.[0];
   } else if (typeof agentIdHeader === "string") {
     agentId = agentIdHeader;
   }
 
+  let sourceTaskId: string | undefined;
+  if (Array.isArray(sourceTaskIdHeader)) {
+    sourceTaskId = sourceTaskIdHeader?.[0];
+  } else if (typeof sourceTaskIdHeader === "string") {
+    sourceTaskId = sourceTaskIdHeader;
+  }
+
   return {
     sessionId: req.sessionId || undefined,
     agentId,
+    sourceTaskId,
   };
 };