@desplega.ai/agent-swarm 1.49.0 → 1.52.0

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

@@ -0,0 +1,101 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getSkillById, installSkill } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillInstallTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-install",
+    {
+      title: "Install Skill",
+      annotations: { destructiveHint: false },
+      description: "Install/assign a skill to an agent. Leads can install for other agents.",
+      inputSchema: z.object({
+        skillId: z.string().describe("ID of the skill to install"),
+        agentId: z
+          .string()
+          .optional()
+          .describe("Target agent (default: calling agent). Lead can install for others."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        agentSkill: 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." },
+        };
+      }
+
+      const targetAgentId = args.agentId ?? requestInfo.agentId;
+
+      // If installing for another agent, must be lead
+      if (targetAgentId !== requestInfo.agentId) {
+        const agent = getAgentById(requestInfo.agentId);
+        if (!agent?.isLead) {
+          return {
+            content: [{ type: "text", text: "Only leads can install skills for other agents." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Permission denied.",
+            },
+          };
+        }
+      }
+
+      const skill = getSkillById(args.skillId);
+      if (!skill) {
+        return {
+          content: [{ type: "text", text: "Skill not found." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Skill not found.",
+          },
+        };
+      }
+
+      if (!skill.isEnabled) {
+        return {
+          content: [{ type: "text", text: "Skill is disabled." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Skill is disabled.",
+          },
+        };
+      }
+
+      try {
+        const agentSkill = installSkill(targetAgentId, args.skillId);
+        return {
+          content: [
+            { type: "text", text: `Installed skill "${skill.name}" for agent ${targetAgentId}.` },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Installed skill "${skill.name}".`,
+            agentSkill,
+          },
+        };
+      } 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}`,
+          },
+        };
+      }
+    },
+  );
+};

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

@@ -0,0 +1,77 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentSkills, listSkills } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillListTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-list",
+    {
+      title: "List Skills",
+      annotations: { destructiveHint: false },
+      description: "List available skills with optional filters.",
+      inputSchema: z.object({
+        type: z.enum(["remote", "personal"]).optional().describe("Filter by type"),
+        scope: z.enum(["global", "swarm", "agent"]).optional().describe("Filter by scope"),
+        agentId: z.string().optional().describe("Filter by owning agent"),
+        installedOnly: z
+          .boolean()
+          .optional()
+          .describe("Only show skills installed for calling agent"),
+        includeContent: z
+          .boolean()
+          .default(false)
+          .optional()
+          .describe("Include full content (default false)"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        skills: z.array(z.any()),
+        total: z.number(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      try {
+        const skills =
+          args.installedOnly && requestInfo.agentId
+            ? getAgentSkills(requestInfo.agentId)
+            : listSkills({
+                type: args.type,
+                scope: args.scope,
+                ownerAgentId: args.agentId,
+                includeContent: args.includeContent,
+              });
+
+        // Strip content if not requested
+        const result = args.includeContent
+          ? skills
+          : skills.map(({ content: _content, ...rest }) => rest);
+
+        return {
+          content: [{ type: "text", text: `Found ${result.length} skill(s).` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Found ${result.length} skill(s).`,
+            skills: result,
+            total: result.length,
+          },
+        };
+      } 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}`,
+            skills: [],
+            total: 0,
+          },
+        };
+      }
+    },
+  );
+};

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

@@ -0,0 +1,123 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createTaskExtended, getAgentById, getLeadAgent, getSkillById } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillPublishTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-publish",
+    {
+      title: "Publish Skill",
+      annotations: { destructiveHint: false },
+      description:
+        "Publish a personal skill to swarm scope. Creates an approval task for the lead agent.",
+      inputSchema: z.object({
+        skillId: z.string().describe("ID of the personal skill to publish"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        taskId: z.string().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." },
+        };
+      }
+
+      const skill = getSkillById(args.skillId);
+      if (!skill) {
+        return {
+          content: [{ type: "text", text: "Skill not found." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Skill not found.",
+          },
+        };
+      }
+
+      if (skill.type !== "personal") {
+        return {
+          content: [{ type: "text", text: "Only personal skills can be published." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Only personal skills can be published.",
+          },
+        };
+      }
+
+      if (skill.ownerAgentId !== requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "You can only publish your own skills." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "You can only publish your own skills.",
+          },
+        };
+      }
+
+      // Find the lead agent
+      const leadAgent = getLeadAgent();
+
+      if (!leadAgent) {
+        return {
+          content: [{ type: "text", text: "No lead agent found to approve the skill." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "No lead agent available.",
+          },
+        };
+      }
+
+      // Create an approval task for the lead
+      const agent = getAgentById(requestInfo.agentId);
+      const taskDescription = `Skill Approval Request: "${skill.name}"
+
+Agent ${agent?.name ?? requestInfo.agentId} wants to publish a personal skill to swarm scope.
+
+**Skill Name:** ${skill.name}
+**Description:** ${skill.description}
+**Version:** ${skill.version}
+
+**Content:**
+\`\`\`
+${skill.content}
+\`\`\`
+
+To approve: update the skill's scope to "swarm" using skill-update.
+To reject: close this task with a rejection reason.`;
+
+      const task = createTaskExtended(taskDescription, {
+        agentId: leadAgent.id,
+        creatorAgentId: requestInfo.agentId,
+        source: "mcp",
+        taskType: "skill-approval",
+        tags: ["skill-approval", skill.name],
+        priority: 60,
+      });
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Skill publish request created. Task ${task.id} sent to lead for approval.`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Publish request sent to lead. Track via task ${task.id}.`,
+          taskId: task.id,
+        },
+      };
+    },
+  );
+};

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

@@ -0,0 +1,43 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { searchSkills } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillSearchTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-search",
+    {
+      title: "Search Skills",
+      annotations: { destructiveHint: false },
+      description: "Search skills by keyword (name and description).",
+      inputSchema: z.object({
+        query: z.string().min(1).describe("Search query"),
+        limit: z.number().int().min(1).max(100).default(20).optional(),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        skills: z.array(z.any()),
+        total: z.number(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      const skills = searchSkills(args.query, args.limit ?? 20);
+      const result = skills.map(({ content: _content, ...rest }) => rest);
+
+      return {
+        content: [
+          { type: "text", text: `Found ${result.length} skill(s) matching "${args.query}".` },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Found ${result.length} skill(s).`,
+          skills: result,
+          total: result.length,
+        },
+      };
+    },
+  );
+};

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

@@ -0,0 +1,128 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getSkillById, listSkills, updateSkill } from "@/be/db";
+import { parseSkillContent } from "@/be/skill-parser";
+import { createToolRegistrar } from "@/tools/utils";
+
+function contentHash(content: string): string {
+  const hash = new Bun.CryptoHasher("sha256").update(content).digest("hex");
+  return hash;
+}
+
+export const registerSkillSyncRemoteTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-sync-remote",
+    {
+      title: "Sync Remote Skills",
+      annotations: { destructiveHint: false },
+      description:
+        "Check and update remote skills from their GitHub sources. Compares content and updates if changed.",
+      inputSchema: z.object({
+        skillId: z
+          .string()
+          .optional()
+          .describe("Sync a specific skill, or all remote skills if omitted"),
+        force: z
+          .boolean()
+          .default(false)
+          .optional()
+          .describe("Force re-fetch even if hash matches"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        updated: z.number(),
+        checked: z.number(),
+        errors: z.array(z.string()),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      try {
+        const skills = args.skillId
+          ? (() => {
+              const skill = getSkillById(args.skillId!);
+              return skill && skill.type === "remote" ? [skill] : [];
+            })()
+          : listSkills({ type: "remote" });
+
+        let updated = 0;
+        const errors: string[] = [];
+
+        for (const skill of skills) {
+          if (skill.isComplex) continue; // Skip complex skills (handled by npx)
+          if (!skill.sourceRepo) continue;
+
+          try {
+            const filePath = skill.sourcePath ? `${skill.sourcePath}/SKILL.md` : "SKILL.md";
+            const rawUrl = `https://raw.githubusercontent.com/${skill.sourceRepo}/${skill.sourceBranch}/${filePath}`;
+
+            const response = await fetch(rawUrl);
+            if (!response.ok) {
+              errors.push(`${skill.name}: HTTP ${response.status}`);
+              continue;
+            }
+
+            const newContent = await response.text();
+            const newHash = contentHash(newContent);
+            const now = new Date().toISOString();
+
+            if (args.force || newHash !== skill.sourceHash) {
+              const parsed = parseSkillContent(newContent);
+              updateSkill(skill.id, {
+                content: newContent,
+                name: parsed.name,
+                description: parsed.description,
+                allowedTools: parsed.allowedTools,
+                model: parsed.model,
+                effort: parsed.effort,
+                context: parsed.context,
+                agent: parsed.agent,
+                disableModelInvocation: parsed.disableModelInvocation,
+                userInvocable: parsed.userInvocable,
+                sourceHash: newHash,
+                lastFetchedAt: now,
+              });
+              updated++;
+            } else {
+              // Content unchanged — still update lastFetchedAt
+              updateSkill(skill.id, { lastFetchedAt: now });
+            }
+          } catch (err) {
+            errors.push(`${skill.name}: ${err instanceof Error ? err.message : "Unknown error"}`);
+          }
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Synced remote skills: ${updated} updated, ${skills.length} checked, ${errors.length} errors.`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `${updated} updated, ${skills.length} checked.`,
+            updated,
+            checked: skills.length,
+            errors,
+          },
+        };
+      } 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}`,
+            updated: 0,
+            checked: 0,
+            errors: [message],
+          },
+        };
+      }
+    },
+  );
+};

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

@@ -0,0 +1,60 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, uninstallSkill } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillUninstallTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-uninstall",
+    {
+      title: "Uninstall Skill",
+      annotations: { destructiveHint: true },
+      description: "Remove a skill from an agent.",
+      inputSchema: z.object({
+        skillId: z.string().describe("ID of the skill to uninstall"),
+        agentId: z.string().optional().describe("Target agent (default: calling agent)"),
+      }),
+      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 targetAgentId = args.agentId ?? requestInfo.agentId;
+
+      if (targetAgentId !== requestInfo.agentId) {
+        const agent = getAgentById(requestInfo.agentId);
+        if (!agent?.isLead) {
+          return {
+            content: [{ type: "text", text: "Only leads can uninstall skills for other agents." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Permission denied.",
+            },
+          };
+        }
+      }
+
+      const removed = uninstallSkill(targetAgentId, args.skillId);
+      return {
+        content: [
+          { type: "text", text: removed ? "Skill uninstalled." : "Skill was not installed." },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: removed,
+          message: removed ? "Skill uninstalled." : "Skill was not installed for this agent.",
+        },
+      };
+    },
+  );
+};

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

@@ -0,0 +1,128 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getSkillById, updateSkill } from "@/be/db";
+import { parseSkillContent } from "@/be/skill-parser";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSkillUpdateTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "skill-update",
+    {
+      title: "Update Skill",
+      annotations: { destructiveHint: false },
+      description:
+        "Update a skill's content or settings. Re-parses frontmatter if content changes.",
+      inputSchema: z.object({
+        skillId: z.string().optional().describe("Skill ID to update"),
+        content: z.string().optional().describe("New SKILL.md content (re-parses frontmatter)"),
+        isEnabled: z.boolean().optional().describe("Toggle enabled/disabled"),
+      }),
+      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." },
+        };
+      }
+
+      if (!args.skillId) {
+        return {
+          content: [{ type: "text", text: "skillId is required." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "skillId is required.",
+          },
+        };
+      }
+
+      try {
+        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.",
+            },
+          };
+        }
+
+        // Only owner or lead can update
+        const agent = getAgentById(requestInfo.agentId);
+        if (existing.ownerAgentId !== requestInfo.agentId && !agent?.isLead) {
+          return {
+            content: [
+              { type: "text", text: "Only the owning agent or lead can update this skill." },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Permission denied.",
+            },
+          };
+        }
+
+        const updates: Parameters<typeof updateSkill>[1] = {};
+
+        if (args.content !== undefined) {
+          const parsed = parseSkillContent(args.content);
+          updates.content = args.content;
+          updates.name = parsed.name;
+          updates.description = parsed.description;
+          updates.allowedTools = parsed.allowedTools;
+          updates.model = parsed.model;
+          updates.effort = parsed.effort;
+          updates.context = parsed.context;
+          updates.agent = parsed.agent;
+          updates.disableModelInvocation = parsed.disableModelInvocation;
+          updates.userInvocable = parsed.userInvocable;
+        }
+
+        if (args.isEnabled !== undefined) {
+          updates.isEnabled = args.isEnabled;
+        }
+
+        const skill = updateSkill(args.skillId, updates);
+        if (!skill) {
+          return {
+            content: [{ type: "text", text: "Failed to update skill." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Update failed.",
+            },
+          };
+        }
+
+        return {
+          content: [{ type: "text", text: `Updated skill "${skill.name}" (v${skill.version})` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Updated skill "${skill.name}" to version ${skill.version}.`,
+            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}`,
+          },
+        };
+      }
+    },
+  );
+};