@desplega.ai/agent-swarm 1.49.0 → 1.52.0

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/request-human-input.ts

@@ -0,0 +1,106 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createApprovalRequest } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+const QuestionSchema = z.object({
+  id: z.string().describe("Unique ID for the question (used as key in responses)"),
+  type: z
+    .enum(["approval", "text", "single-select", "multi-select", "boolean"])
+    .describe("Question type"),
+  label: z.string().describe("The question text displayed to the user"),
+  required: z.boolean().optional().describe("Whether this question is required (default: true)"),
+  description: z.string().optional().describe("Optional help text"),
+  placeholder: z.string().optional().describe("Placeholder text (for text type)"),
+  multiline: z.boolean().optional().describe("Use textarea instead of input (for text type)"),
+  options: z
+    .array(
+      z.object({
+        value: z.string(),
+        label: z.string(),
+        description: z.string().optional(),
+      }),
+    )
+    .optional()
+    .describe("Options (for single-select/multi-select types)"),
+  minSelections: z.number().int().min(0).optional().describe("Min selections (for multi-select)"),
+  maxSelections: z.number().int().min(1).optional().describe("Max selections (for multi-select)"),
+  defaultValue: z.boolean().optional().describe("Default value (for boolean type)"),
+});
+
+export const registerRequestHumanInputTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "request-human-input",
+    {
+      title: "Request human input",
+      annotations: { destructiveHint: false },
+      description:
+        "Create an approval request that pauses until a human responds. " +
+        "Supports multiple question types: approval (yes/no), text, single-select, " +
+        "multi-select, and boolean. Returns the request ID and URL for the human to respond.",
+      inputSchema: z.object({
+        title: z.string().min(1).describe("Title of the approval request"),
+        questions: z.array(QuestionSchema).min(1).describe("Questions to ask the human"),
+        timeoutSeconds: z
+          .number()
+          .int()
+          .min(1)
+          .optional()
+          .describe("Timeout in seconds (auto-rejects on timeout)"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        requestId: z.string().uuid().optional(),
+        url: z.string().optional(),
+      }),
+    },
+    async ({ title, questions, timeoutSeconds }, requestInfo) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: 'Agent ID not found. The MCP client should define the "X-Agent-ID" header.',
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: 'Agent ID not found. The MCP client should define the "X-Agent-ID" header.',
+          },
+        };
+      }
+
+      const id = crypto.randomUUID();
+      const request = createApprovalRequest({
+        id,
+        title,
+        questions,
+        approvers: { policy: "any" },
+        sourceTaskId: requestInfo.sourceTaskId ?? undefined,
+        timeoutSeconds,
+      });
+
+      const appUrl = process.env.APP_URL || "http://localhost:5274";
+      const url = `${appUrl}/requests/${request.id}`;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Created approval request "${id}". Human can respond at: ${url}`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Approval request created. Respond at: ${url}`,
+          requestId: request.id,
+          url,
+        },
+      };
+    },
+  );
+};

package/src/tools/skills/index.ts

@@ -0,0 +1,11 @@
+export { registerSkillCreateTool } from "./skill-create";
+export { registerSkillDeleteTool } from "./skill-delete";
+export { registerSkillGetTool } from "./skill-get";
+export { registerSkillInstallTool } from "./skill-install";
+export { registerSkillInstallRemoteTool } from "./skill-install-remote";
+export { registerSkillListTool } from "./skill-list";
+export { registerSkillPublishTool } from "./skill-publish";
+export { registerSkillSearchTool } from "./skill-search";
+export { registerSkillSyncRemoteTool } from "./skill-sync-remote";
+export { registerSkillUninstallTool } from "./skill-uninstall";
+export { registerSkillUpdateTool } from "./skill-update";

package/src/tools/skills/skill-create.ts

@@ -0,0 +1,105 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createSkill, getAgentById, installSkill } from "@/be/db";
+import { parseSkillContent } from "@/be/skill-parser";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillCreateTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-create",
+    {
+      title: "Create Skill",
+      annotations: { destructiveHint: false },
+      description:
+        "Create a personal skill from SKILL.md content. Parses frontmatter for name, description, and metadata.",
+      inputSchema: z.object({
+        content: z
+          .string()
+          .min(1)
+          .describe("Full SKILL.md content (YAML frontmatter + markdown body)"),
+        scope: z
+          .enum(["agent", "swarm"])
+          .default("agent")
+          .optional()
+          .describe("Scope: agent (personal) or swarm (shared). Default: agent"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        skill: z.any().optional(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID not found." }],
+          structuredContent: { success: false, message: "Agent ID not found." },
+        };
+      }
+
+      try {
+        const parsed = parseSkillContent(args.content);
+
+        // If swarm scope requested, only leads can create directly
+        if (args.scope === "swarm") {
+          const agent = getAgentById(requestInfo.agentId);
+          if (!agent?.isLead) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: 'Only lead agents can create swarm-scope skills directly. Use "skill-publish" to request approval.',
+                },
+              ],
+              structuredContent: {
+                yourAgentId: requestInfo.agentId,
+                success: false,
+                message: "Only lead agents can create swarm-scope skills directly.",
+              },
+            };
+          }
+        }
+
+        const skill = createSkill({
+          name: parsed.name,
+          description: parsed.description,
+          content: args.content,
+          type: "personal",
+          scope: args.scope ?? "agent",
+          ownerAgentId: requestInfo.agentId,
+          allowedTools: parsed.allowedTools,
+          model: parsed.model,
+          effort: parsed.effort,
+          context: parsed.context,
+          agent: parsed.agent,
+          disableModelInvocation: parsed.disableModelInvocation,
+          userInvocable: parsed.userInvocable,
+        });
+
+        // Auto-install for the creating agent
+        installSkill(requestInfo.agentId, skill.id);
+
+        return {
+          content: [{ type: "text", text: `Created skill "${skill.name}" (${skill.id})` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Created and installed skill "${skill.name}".`,
+            skill,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed to create skill: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/skills/skill-delete.ts

@@ -0,0 +1,67 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { deleteSkill, getAgentById, getSkillById } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillDeleteTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-delete",
+    {
+      title: "Delete Skill",
+      annotations: { destructiveHint: true },
+      description: "Delete a skill. Only the owning agent or lead can delete.",
+      inputSchema: z.object({
+        skillId: z.string().describe("ID of the skill to delete"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID not found." }],
+          structuredContent: { success: false, message: "Agent ID not found." },
+        };
+      }
+
+      const existing = getSkillById(args.skillId);
+      if (!existing) {
+        return {
+          content: [{ type: "text", text: "Skill not found." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Skill not found.",
+          },
+        };
+      }
+
+      const agent = getAgentById(requestInfo.agentId);
+      if (existing.ownerAgentId !== requestInfo.agentId && !agent?.isLead) {
+        return {
+          content: [{ type: "text", text: "Only the owning agent or lead can delete this skill." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Permission denied.",
+          },
+        };
+      }
+
+      const deleted = deleteSkill(args.skillId);
+      return {
+        content: [
+          { type: "text", text: deleted ? `Deleted skill "${existing.name}".` : "Delete failed." },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: deleted,
+          message: deleted ? `Deleted skill "${existing.name}".` : "Delete failed.",
+        },
+      };
+    },
+  );
+};

package/src/tools/skills/skill-get.ts

@@ -0,0 +1,75 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getSkillById, getSkillByName } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillGetTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-get",
+    {
+      title: "Get Skill",
+      annotations: { destructiveHint: false },
+      description:
+        "Get full skill content by ID or name. Name resolution checks agent scope first, then swarm, then global.",
+      inputSchema: z.object({
+        skillId: z.string().optional().describe("Skill ID"),
+        name: z.string().optional().describe("Skill name (resolved with precedence)"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        skill: z.any().optional(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      if (!args.skillId && !args.name) {
+        return {
+          content: [{ type: "text", text: "Provide skillId or name." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Provide skillId or name.",
+          },
+        };
+      }
+
+      let skill = null;
+
+      if (args.skillId) {
+        skill = getSkillById(args.skillId);
+      } else if (args.name && requestInfo.agentId) {
+        // Precedence: agent (personal) → swarm → global
+        skill =
+          getSkillByName(args.name, "agent", requestInfo.agentId) ||
+          getSkillByName(args.name, "swarm") ||
+          getSkillByName(args.name, "global");
+      } else if (args.name) {
+        skill = getSkillByName(args.name, "swarm") || getSkillByName(args.name, "global");
+      }
+
+      if (!skill) {
+        return {
+          content: [{ type: "text", text: "Skill not found." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Skill not found.",
+          },
+        };
+      }
+
+      return {
+        content: [
+          { type: "text", text: `Skill "${skill.name}" (${skill.id}):\n\n${skill.content}` },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Found skill "${skill.name}".`,
+          skill,
+        },
+      };
+    },
+  );
+};

package/src/tools/skills/skill-install-remote.ts

@@ -0,0 +1,152 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createSkill, getAgentById } from "@/be/db";
+import { parseSkillContent } from "@/be/skill-parser";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillInstallRemoteTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-install-remote",
+    {
+      title: "Install Remote Skill",
+      annotations: { destructiveHint: false },
+      description:
+        "Fetch and install a remote skill from a GitHub repository. Fetches SKILL.md via GitHub raw content API.",
+      inputSchema: z.object({
+        sourceRepo: z.string().describe('GitHub repo (e.g. "vercel-labs/skills")'),
+        sourcePath: z.string().optional().describe('Path within repo (e.g. "skills/nextjs")'),
+        scope: z
+          .enum(["global", "swarm"])
+          .default("global")
+          .optional()
+          .describe("Scope for the installed skill"),
+        isComplex: z
+          .boolean()
+          .default(false)
+          .optional()
+          .describe("If true, registers for npx install (metadata only)"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        skill: z.any().optional(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID not found." }],
+          structuredContent: { success: false, message: "Agent ID not found." },
+        };
+      }
+
+      // Only leads can install global/swarm remote skills
+      const agent = getAgentById(requestInfo.agentId);
+      if (!agent?.isLead) {
+        return {
+          content: [{ type: "text", text: "Only lead agents can install remote skills." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Only lead agents can install remote skills.",
+          },
+        };
+      }
+
+      try {
+        const branch = "main";
+        const filePath = args.sourcePath ? `${args.sourcePath}/SKILL.md` : "SKILL.md";
+        const rawUrl = `https://raw.githubusercontent.com/${args.sourceRepo}/${branch}/${filePath}`;
+
+        let content = "";
+        let sourceHash: string | null = null;
+
+        if (!args.isComplex) {
+          // Fetch SKILL.md content
+          const response = await fetch(rawUrl);
+          if (!response.ok) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Failed to fetch SKILL.md from ${rawUrl}: ${response.status}`,
+                },
+              ],
+              structuredContent: {
+                yourAgentId: requestInfo.agentId,
+                success: false,
+                message: `Failed to fetch: HTTP ${response.status}`,
+              },
+            };
+          }
+          content = await response.text();
+          sourceHash = new Bun.CryptoHasher("sha256").update(content).digest("hex");
+        }
+
+        let name: string;
+        let description: string;
+        let parsedMeta: Partial<ReturnType<typeof parseSkillContent>> = {};
+
+        if (content) {
+          const parsed = parseSkillContent(content);
+          name = parsed.name;
+          description = parsed.description;
+          parsedMeta = parsed;
+        } else {
+          // Complex skill — use repo/path as name
+          name = args.sourcePath
+            ? args.sourcePath.split("/").pop() || args.sourceRepo
+            : args.sourceRepo.split("/").pop() || args.sourceRepo;
+          description = `Complex skill from ${args.sourceRepo}`;
+        }
+
+        const skill = createSkill({
+          name,
+          description,
+          content,
+          type: "remote",
+          scope: args.scope ?? "global",
+          sourceUrl: rawUrl,
+          sourceRepo: args.sourceRepo,
+          sourcePath: args.sourcePath,
+          sourceBranch: branch,
+          sourceHash: sourceHash ?? undefined,
+          isComplex: args.isComplex ?? false,
+          allowedTools: parsedMeta.allowedTools,
+          model: parsedMeta.model,
+          effort: parsedMeta.effort,
+          context: parsedMeta.context,
+          agent: parsedMeta.agent,
+          disableModelInvocation: parsedMeta.disableModelInvocation,
+          userInvocable: parsedMeta.userInvocable,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Installed remote skill "${skill.name}" from ${args.sourceRepo}`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Installed remote skill "${skill.name}".`,
+            skill,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};