@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/tools/tool-config.ts

@@ -0,0 +1,124 @@
+/**
+ * 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",
+
+  // Prompt Templates (5)
+  "list-prompt-templates",
+  "get-prompt-template",
+  "set-prompt-template",
+  "delete-prompt-template",
+  "preview-prompt-template",
+
+  // 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