@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/tools/memory-search.ts

@@ -0,0 +1,131 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, listMemoriesByAgent, searchMemoriesByVector } from "@/be/db";
+import { getEmbedding } from "@/be/embedding";
+import { createToolRegistrar } from "@/tools/utils";
+import { AgentMemoryScopeSchema, AgentMemorySourceSchema } from "@/types";
+
+export const registerMemorySearchTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "memory-search",
+    {
+      title: "Search memories",
+      description:
+        "Search your accumulated memories using natural language. Returns summaries with IDs — use memory-get to retrieve full content.",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        query: z.string().min(1).describe("Natural language search query."),
+        scope: z
+          .enum(["all", "agent", "swarm"])
+          .default("all")
+          .describe(
+            "Search scope: 'all' (own + swarm), 'agent' (own only), 'swarm' (shared only).",
+          ),
+        limit: z.number().int().min(1).max(50).default(10).describe("Max results to return."),
+        source: AgentMemorySourceSchema.optional().describe("Filter by memory source type."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        results: z
+          .array(
+            z.object({
+              id: z.string().uuid(),
+              name: z.string(),
+              summary: z.string().nullable(),
+              source: AgentMemorySourceSchema,
+              scope: AgentMemoryScopeSchema,
+              similarity: z.number().optional(),
+              createdAt: z.string(),
+            }),
+          )
+          .optional(),
+      }),
+    },
+    async ({ query, scope, limit, source }, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID required for memory search." }],
+          structuredContent: {
+            yourAgentId: undefined,
+            success: false,
+            message: "Agent ID required. Are you registered in the swarm?",
+          },
+        };
+      }
+
+      const agent = getAgentById(requestInfo.agentId);
+      const isLead = agent?.isLead ?? false;
+
+      // Try vector search first
+      const queryEmbedding = await getEmbedding(query);
+
+      if (queryEmbedding) {
+        const results = searchMemoriesByVector(queryEmbedding, requestInfo.agentId, {
+          scope: scope as "agent" | "swarm" | "all",
+          limit,
+          source,
+          isLead,
+        });
+
+        const mapped = results.map((r) => ({
+          id: r.id,
+          name: r.name,
+          summary: r.summary,
+          source: r.source,
+          scope: r.scope,
+          similarity: r.similarity,
+          createdAt: r.createdAt,
+        }));
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Found ${mapped.length} memories matching "${query}".`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Found ${mapped.length} memories matching "${query}".`,
+            results: mapped,
+          },
+        };
+      }
+
+      // Fallback: list recent memories (no OPENAI_API_KEY)
+      const recent = listMemoriesByAgent(requestInfo.agentId, {
+        scope: scope as "agent" | "swarm" | "all",
+        limit,
+        isLead,
+      });
+
+      const mapped = recent.map((r) => ({
+        id: r.id,
+        name: r.name,
+        summary: r.summary,
+        source: r.source,
+        scope: r.scope,
+        createdAt: r.createdAt,
+      }));
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Embedding unavailable. Showing ${mapped.length} most recent memories.`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Embedding unavailable (no OPENAI_API_KEY). Showing ${mapped.length} most recent memories.`,
+          results: mapped,
+        },
+      };
+    },
+  );
+};

package/src/tools/my-agent-info.ts

@@ -10,6 +10,8 @@ export const registerMyAgentInfoTool = (server: McpServer) => {
     {
       title: "Get your agent info",
       description: "Returns your agent ID based on the X-Agent-ID header.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({}),
       outputSchema: z.object({
         success: z.boolean(),

package/src/tools/poll-task.ts

@@ -26,6 +26,8 @@ export const registerPollTaskTool = (server: McpServer) => {
       title: "Poll for a task",
       description:
         "Poll for a new task assignment. Returns immediately if there are offered tasks awaiting accept/reject. Also returns count of unassigned tasks in the pool.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({}),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -86,26 +88,6 @@ export const registerPollTaskTool = (server: McpServer) => {
         };
       }
 
-      // Lead agents should not poll for tasks - they use inbox tools instead
-      if (agent.isLead) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Lead agents should not poll for tasks. Use inbox tools to respond to Slack messages, or get-tasks to monitor workers.",
-            },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "Lead agents use inbox and delegation tools instead of polling for tasks.",
-            offeredTasks: [],
-            availableCount: 0,
-            waitedForSeconds: 0,
-          },
-        };
-      }
-
       // Check for offered tasks first - these need immediate attention
       const offeredTasks = getOfferedTasksForAgent(agentId);
       const availableCount = getUnassignedTasksCount();

package/src/tools/post-message.ts

@@ -9,6 +9,7 @@ export const registerPostMessageTool = (server: McpServer) => {
     "post-message",
     {
       title: "Post Message",
+      annotations: { destructiveHint: false },
       description: "Posts a message to a channel for cross-agent communication.",
       inputSchema: z.object({
         channel: z.string().default("general").describe("Channel name (default: 'general')."),

package/src/tools/prompt-templates/delete.ts

@@ -0,0 +1,86 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { deletePromptTemplate, getPromptTemplateById } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerDeletePromptTemplateTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "delete-prompt-template",
+    {
+      title: "Delete Prompt Template",
+      description:
+        "Delete a prompt template override by ID. Cannot delete default templates — use reset instead. Use list-prompt-templates to find template IDs first.",
+      annotations: { destructiveHint: true },
+
+      inputSchema: z.object({
+        id: z.string().describe("The prompt template ID to delete."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async ({ id }, requestInfo) => {
+      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.',
+          },
+        };
+      }
+
+      try {
+        const existing = getPromptTemplateById(id);
+        if (!existing) {
+          return {
+            content: [{ type: "text", text: `Prompt template "${id}" not found.` }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: `Prompt template "${id}" not found.`,
+            },
+          };
+        }
+
+        const deleted = deletePromptTemplate(id);
+        if (!deleted) {
+          return {
+            content: [{ type: "text", text: `Failed to delete prompt template "${id}".` }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: `Failed to delete prompt template "${id}".`,
+            },
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Prompt template "${existing.eventType}" (scope: ${existing.scope}${existing.scopeId ? `, scopeId: ${existing.scopeId}` : ""}) deleted successfully.`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Prompt template "${existing.eventType}" deleted successfully.`,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to delete prompt template: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to delete prompt template: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/prompt-templates/get.ts

@@ -0,0 +1,89 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getPromptTemplateById, getPromptTemplateHistory } from "@/be/db";
+import { getTemplateDefinition } from "@/prompts/registry";
+import { createToolRegistrar } from "@/tools/utils";
+import { PromptTemplateHistorySchema, PromptTemplateSchema } from "@/types";
+
+export const registerGetPromptTemplateTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "get-prompt-template",
+    {
+      title: "Get Prompt Template",
+      description:
+        "Get a prompt template by ID, including its version history and the code-defined variable definitions for its event type.",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        id: z.string().describe("The prompt template ID."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        template: PromptTemplateSchema.optional(),
+        history: z.array(PromptTemplateHistorySchema).optional(),
+        variables: z
+          .array(
+            z.object({ name: z.string(), description: z.string(), example: z.string().optional() }),
+          )
+          .optional(),
+      }),
+    },
+    async ({ id }, requestInfo) => {
+      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.',
+          },
+        };
+      }
+
+      try {
+        const template = getPromptTemplateById(id);
+        if (!template) {
+          return {
+            content: [{ type: "text", text: `Prompt template "${id}" not found.` }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: `Prompt template "${id}" not found.`,
+            },
+          };
+        }
+
+        const history = getPromptTemplateHistory(id);
+        const definition = getTemplateDefinition(template.eventType);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Template: ${template.eventType} (v${template.version}, ${template.state}, scope: ${template.scope})\n\nBody:\n${template.body}\n\nHistory: ${history.length} version(s)`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Found template "${template.eventType}" at version ${template.version}.`,
+            template,
+            history,
+            variables: definition?.variables,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to get prompt template: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to get prompt template: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/prompt-templates/index.ts

@@ -0,0 +1,5 @@
+export { registerDeletePromptTemplateTool } from "./delete";
+export { registerGetPromptTemplateTool } from "./get";
+export { registerListPromptTemplatesTool } from "./list";
+export { registerPreviewPromptTemplateTool } from "./preview";
+export { registerSetPromptTemplateTool } from "./set";

package/src/tools/prompt-templates/list.ts

@@ -0,0 +1,95 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getPromptTemplates } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { PromptTemplateSchema, PromptTemplateScopeSchema } from "@/types";
+
+export const registerListPromptTemplatesTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "list-prompt-templates",
+    {
+      title: "List Prompt Templates",
+      description:
+        "List prompt templates with optional filters. Returns all templates matching the specified criteria, including defaults and overrides at all scope levels.",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        eventType: z
+          .string()
+          .optional()
+          .describe("Filter by event type (e.g. 'github.pull_request.opened')."),
+        scope: PromptTemplateScopeSchema.optional().describe(
+          "Filter by scope: 'global', 'agent', or 'repo'.",
+        ),
+        scopeId: z.string().optional().describe("Filter by scope ID (agent ID or repo ID)."),
+        isDefault: z.boolean().optional().describe("Filter by default status."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        templates: z.array(PromptTemplateSchema),
+        count: z.number(),
+      }),
+    },
+    async ({ eventType, scope, scopeId, isDefault }, requestInfo) => {
+      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.',
+            templates: [],
+            count: 0,
+          },
+        };
+      }
+
+      try {
+        const templates = getPromptTemplates({ eventType, scope, scopeId, isDefault });
+        const count = templates.length;
+
+        const summary =
+          count === 0
+            ? "No prompt templates found."
+            : templates
+                .map(
+                  (t) =>
+                    `- [${t.scope}${t.scopeId ? `:${t.scopeId}` : ""}] ${t.eventType} (v${t.version}, ${t.state}${t.isDefault ? ", default" : ""})`,
+                )
+                .join("\n");
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                count === 0
+                  ? "No prompt templates found."
+                  : `Found ${count} prompt template(s):\n\n${summary}`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: count === 0 ? "No prompt templates found." : `Found ${count} template(s).`,
+            templates,
+            count,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to list prompt templates: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to list prompt templates: ${message}`,
+            templates: [],
+            count: 0,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/prompt-templates/preview.ts

@@ -0,0 +1,84 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getTemplateDefinition } from "@/prompts/registry";
+import { createToolRegistrar } from "@/tools/utils";
+import { interpolate } from "@/workflows/template";
+
+export const registerPreviewPromptTemplateTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "preview-prompt-template",
+    {
+      title: "Preview Prompt Template",
+      description:
+        "Dry-run render a prompt template with provided variables. Optionally supply a custom body to preview before saving. Returns the interpolated text and any unresolved {{variable}} tokens.",
+      annotations: { readOnlyHint: true },
+
+      inputSchema: z.object({
+        eventType: z
+          .string()
+          .describe("Event type to preview (used to look up header and default body)."),
+        body: z.string().optional().describe("Custom body to preview instead of the default."),
+        variables: z
+          .record(z.string(), z.unknown())
+          .optional()
+          .describe("Variables to interpolate into the template."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        rendered: z.string(),
+        unresolved: z.array(z.string()),
+      }),
+    },
+    async ({ eventType, body: customBody, variables }, requestInfo) => {
+      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.',
+            rendered: "",
+            unresolved: [],
+          },
+        };
+      }
+
+      try {
+        const definition = getTemplateDefinition(eventType);
+        const templateBody = customBody ?? definition?.defaultBody ?? "";
+        const header = definition?.header ?? "";
+        const composed = header ? `${header}\n\n${templateBody}` : templateBody;
+        const { result: rendered, unresolved } = interpolate(composed, variables ?? {});
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Preview for "${eventType}":\n\n${rendered}${unresolved.length > 0 ? `\n\nUnresolved variables: ${unresolved.join(", ")}` : ""}`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: "Template rendered successfully.",
+            rendered,
+            unresolved,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to preview template: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to preview template: ${message}`,
+            rendered: "",
+            unresolved: [],
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/prompt-templates/set.ts

@@ -0,0 +1,117 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { upsertPromptTemplate } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import {
+  PromptTemplateSchema,
+  PromptTemplateScopeSchema,
+  PromptTemplateStateSchema,
+} from "@/types";
+
+export const registerSetPromptTemplateTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "set-prompt-template",
+    {
+      title: "Set Prompt Template",
+      description:
+        "Create or update a prompt template override. Upserts by (eventType, scope, scopeId). Use scope='global' for server-wide, 'agent' for agent-specific, or 'repo' for repo-specific overrides.",
+      annotations: { idempotentHint: true },
+
+      inputSchema: z.object({
+        eventType: z
+          .string()
+          .min(1)
+          .describe("Event type identifier (e.g. 'github.pull_request.opened')."),
+        scope: PromptTemplateScopeSchema.optional().describe(
+          "Template scope: 'global' (default), 'agent', or 'repo'.",
+        ),
+        scopeId: z
+          .string()
+          .optional()
+          .describe(
+            "Agent ID or repo ID. Required for 'agent' and 'repo' scopes, omit for 'global'.",
+          ),
+        state: PromptTemplateStateSchema.optional().describe(
+          "Template state: 'enabled' (default), 'default_prompt_fallback', or 'skip_event'.",
+        ),
+        body: z.string().describe("The template body text with {{variable}} placeholders."),
+        changeReason: z
+          .string()
+          .optional()
+          .describe("Reason for the change (recorded in history)."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        template: PromptTemplateSchema.optional(),
+      }),
+    },
+    async ({ eventType, scope: rawScope, scopeId, state, body, changeReason }, requestInfo) => {
+      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 scope = rawScope ?? "global";
+
+      if (scope !== "global" && !scopeId) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `scopeId is required for scope '${scope}'. Provide an agent ID or repo ID.`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `scopeId is required for scope '${scope}'.`,
+          },
+        };
+      }
+
+      try {
+        const template = upsertPromptTemplate({
+          eventType,
+          scope,
+          scopeId: scope === "global" ? null : scopeId,
+          state,
+          body,
+          changedBy: requestInfo.agentId,
+          changeReason,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Prompt template for "${eventType}" set successfully (scope: ${scope}${scopeId ? `, scopeId: ${scopeId}` : ""}, v${template.version}).`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Template "${eventType}" set successfully at version ${template.version}.`,
+            template,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to set prompt template: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed to set prompt template: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/read-messages.ts

@@ -21,6 +21,8 @@ export const registerReadMessagesTool = (server: McpServer) => {
       title: "Read Messages",
       description:
         "Reads messages from a channel. If no channel is specified, returns unread messages from ALL channels. Supports filtering by unread, mentions, and time range. Automatically marks messages as read.",
+      annotations: { readOnlyHint: true },
+
       inputSchema: z.object({
         channel: z
           .string()