@desplega.ai/agent-swarm 1.123.0 → 1.124.0

package/src/tools/send-task.ts

@@ -1,5 +1,4 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import * as z from "zod";
 import { AssetKeyAuthorizationError, authorizeAssetKeyWrite } from "@/be/asset-key-auth";
 import { resolveTaskAuditUserId } from "@/be/audit-user";
@@ -18,16 +17,22 @@ import { repointTrackerSyncBySwarmId } from "@/be/db-queries/tracker";
 import { checkSlackRoutingCoherence } from "@/tasks/slack-routing";
 import { findDuplicateTask } from "@/tools/task-dedup";
 import { ownerCtx, type ToolCtx } from "@/tools/task-tool-ctx";
-import { createToolRegistrar } from "@/tools/utils";
+import {
+  createToolRegistrar,
+  type SwarmToolResult,
+  swarmToolOutputSchema,
+  toolErr,
+  toolOk,
+} from "@/tools/utils";
 import {
   type AgentTask,
-  AgentTaskSchema,
   AssetKeySchema,
   FollowUpConfigSchema,
   ModelTierSchema,
   ReasoningEffortSchema,
   splitLegacyModelAlias,
 } from "@/types";
+import { looseAgentTaskOutputSchema } from "./get-task-details";
 
 export const sendTaskInputSchema = z
   .object({
@@ -142,11 +147,9 @@ export const sendTaskInputSchema = z
     }
   });
 
-export const sendTaskOutputSchema = z.object({
+export const sendTaskOutputSchema = swarmToolOutputSchema({
   yourAgentId: z.string().optional(),
-  success: z.boolean(),
-  message: z.string(),
-  task: AgentTaskSchema.optional(),
+  task: looseAgentTaskOutputSchema.optional(),
 });
 
 type SendTaskArgs = z.infer<typeof sendTaskInputSchema>;
@@ -211,21 +214,11 @@ export async function sendTaskHandler(
     requestedByUserId: inputRequestedByUserId,
     followUpConfig,
   }: SendTaskArgs,
-): Promise<CallToolResult> {
+): Promise<SwarmToolResult> {
   if (ctx.kind === "owner" && !ctx.agentId) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: 'Agent ID not found. The MCP client should define the "X-Agent-ID" header.',
-        },
-      ],
-      structuredContent: {
-        yourAgentId: ctx.agentId,
-        success: false,
-        message: 'Agent ID not found. The MCP client should define the "X-Agent-ID" header.',
-      },
-    };
+    return toolErr('Agent ID not found. The MCP client should define the "X-Agent-ID" header.', {
+      data: { yourAgentId: ctx.agentId },
+    });
   }
 
   const creatorAgentId = ctx.kind === "owner" ? ctx.agentId : undefined;
@@ -237,19 +230,9 @@ export async function sendTaskHandler(
       : (inputRequestedByUserId ?? callerTask?.requestedByUserId ?? undefined);
 
   if (ctx.kind === "owner" && agentId === ctx.agentId) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: "Cannot send a task to yourself, are you drunk?",
-        },
-      ],
-      structuredContent: {
-        yourAgentId: ctx.agentId,
-        success: false,
-        message: "Cannot send a task to yourself, are you drunk?",
-      },
-    };
+    return toolErr("Cannot send a task to yourself, are you drunk?", {
+      data: { yourAgentId: ctx.agentId },
+    });
   }
 
   const effectiveVcsRepo = vcsRepo;
@@ -280,14 +263,7 @@ export async function sendTaskHandler(
         routingCheck.verdict === "partial-unit"
           ? `Slack routing rejected: ${routingCheck.detail}`
           : `Slack routing mismatch: you passed ${routingCheck.field}="${routingCheck.got}" but the ${routingCheck.expectedSource} task says "${routingCheck.expected}". Omit the three Slack fields to inherit them from the parent as a unit (preferred), or pass overrideSlackContext: true if the cross-channel routing is deliberate.`;
-      return {
-        content: [{ type: "text", text: msg }],
-        structuredContent: {
-          yourAgentId: creatorAgentId,
-          success: false,
-          message: msg,
-        },
-      };
+      return toolErr(msg, { data: { yourAgentId: creatorAgentId } });
     }
   } else if (slackChannelId || slackThreadTs) {
     console.log(
@@ -308,11 +284,7 @@ export async function sendTaskHandler(
         : error instanceof Error
           ? error.message
           : String(error);
-    return {
-      isError: true,
-      content: [{ type: "text", text: message }],
-      structuredContent: { yourAgentId: creatorAgentId, success: false, message },
-    };
+    return toolErr(message, { data: { yourAgentId: creatorAgentId } });
   }
 
   // Auto-route to parent's worker if parentTaskId is set and no explicit agentId
@@ -327,15 +299,9 @@ export async function sendTaskHandler(
   if (existingTrackerWork) {
     const msg = `Skipped: Linear tracker contextKey ${effectiveParentTask?.contextKey} already has ${existingTrackerWork.reason === "active_task" ? "active task" : "linked open PR"} ${existingTrackerWork.task.id.slice(0, 8)}.`;
     console.log(`[send-task] ${msg}`);
-    return {
-      content: [{ type: "text", text: msg }],
-      structuredContent: {
-        yourAgentId: creatorAgentId,
-        success: true,
-        message: msg,
-        task: existingTrackerWork.task,
-      },
-    };
+    return toolOk(msg, {
+      data: { yourAgentId: creatorAgentId, task: existingTrackerWork.task },
+    });
   }
 
   // Dedup guard: check for similar recent tasks
@@ -347,14 +313,7 @@ export async function sendTaskHandler(
     });
     if (duplicate) {
       const msg = `Duplicate task detected (matches task ${duplicate.task.id.slice(0, 8)}, ${duplicate.reason}). Skipping. Use allowDuplicate: true to override.`;
-      return {
-        content: [{ type: "text", text: msg }],
-        structuredContent: {
-          yourAgentId: creatorAgentId,
-          success: false,
-          message: msg,
-        },
-      };
+      return toolErr(msg, { data: { yourAgentId: creatorAgentId } });
     }
   }
 
@@ -397,14 +356,7 @@ export async function sendTaskHandler(
             new Date(recentCompleted.lastUpdatedAt).getTime();
         if (!cancelledMoreRecent) {
           const msg = `Blocked: re-delegation from follow-up task in a thread that already has completed work (task ${recentCompleted.id.slice(0, 8)}). The original request was already handled.`;
-          return {
-            content: [{ type: "text", text: msg }],
-            structuredContent: {
-              yourAgentId: creatorAgentId,
-              success: false,
-              message: msg,
-            },
-          };
+          return toolErr(msg, { data: { yourAgentId: creatorAgentId } });
         }
         // else: fall through — the cancellation is more recent than the
         // completion, so re-delegation is legitimate.
@@ -557,18 +509,17 @@ export async function sendTaskHandler(
   });
 
   const result = txn();
-  const structuredContent = {
+  const data = {
     yourAgentId: creatorAgentId,
-    ...result,
+    task: result.task,
   };
 
-  return {
-    content: [
-      { type: "text", text: result.message },
-      { type: "text", text: JSON.stringify(result) },
-    ],
-    structuredContent,
-  };
+  // Text channel must carry the created task too — most harnesses never show
+  // the model structuredContent.
+  const details = result.task ? JSON.stringify(result.task, null, 2) : undefined;
+  return result.success
+    ? toolOk(result.message, { data, details })
+    : toolErr(result.message, { data, details });
 }
 
 export const registerSendTaskTool = (server: McpServer) => {

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

@@ -3,7 +3,7 @@ import * as z from "zod";
 import { createSkill, getAgentById, installSkill } from "@/be/db";
 import { parseSkillContent } from "@/be/skill-parser";
 import { can } from "@/rbac";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerSkillCreateTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -24,19 +24,14 @@ export const registerSkillCreateTool = (server: McpServer) => {
           .optional()
           .describe("Scope: agent (personal) or swarm (shared). Default: agent"),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
-        skill: z.any().optional(),
+        skill: z.looseObject({}).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." },
-        };
+        return toolErr("Agent ID not found.");
       }
 
       try {
@@ -56,19 +51,10 @@ export const registerSkillCreateTool = (server: McpServer) => {
             source: "mcp",
           });
           if (!decision.allow) {
-            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.",
-              },
-            };
+            return toolErr("Only lead agents can create swarm-scope skills directly.", {
+              details: 'Use "skill-publish" to request approval.',
+              data: { yourAgentId: requestInfo.agentId },
+            });
           }
         }
 
@@ -91,25 +77,14 @@ export const registerSkillCreateTool = (server: McpServer) => {
         // 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,
-          },
-        };
+        return toolOk(`Created and installed skill "${skill.name}".`, {
+          data: { yourAgentId: requestInfo.agentId, 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}`,
-          },
-        };
+        return toolErr(`Failed to create skill: ${message}`, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
     },
   );

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

@@ -2,7 +2,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { deleteSkill, getAgentById, getSkillById } from "@/be/db";
 import { can } from "@/rbac";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 const SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE =
   "This skill is system-managed and cannot be edited from the UI; it is re-seeded on each start. Fork it under a new name to customize.";
@@ -17,30 +17,18 @@ export const registerSkillDeleteTool = (server: McpServer) => {
       inputSchema: z.object({
         skillId: z.string().describe("ID of the skill to delete"),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().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." },
-        };
+        return toolErr("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.",
-          },
-        };
+        return toolErr("Skill not found.", { data: { yourAgentId: requestInfo.agentId } });
       }
 
       const agent = getAgentById(requestInfo.agentId);
@@ -55,38 +43,22 @@ export const registerSkillDeleteTool = (server: McpServer) => {
         source: "mcp",
       });
       if (!decision.allow) {
-        return {
-          content: [{ type: "text", text: "Only the owning agent or lead can delete this skill." }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "Permission denied.",
-          },
-        };
+        return toolErr("Only the owning agent or lead can delete this skill.", {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
 
       if (existing.systemDefault) {
-        return {
-          content: [{ type: "text", text: SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE,
-          },
-        };
+        return toolErr(SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
 
       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.",
-        },
-      };
+      const message = deleted ? `Deleted skill "${existing.name}".` : "Delete failed.";
+      return deleted
+        ? toolOk(message, { data: { yourAgentId: requestInfo.agentId } })
+        : toolErr(message, { data: { yourAgentId: requestInfo.agentId } });
     },
   );
 };

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

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getSkillById, getSkillFile } from "@/be/db";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerSkillGetFileTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -15,24 +15,15 @@ export const registerSkillGetFileTool = (server: McpServer) => {
         skillId: z.string().describe("Skill ID"),
         path: z.string().describe("Relative path, e.g. references/animations.md"),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
-        file: z.any().optional(),
+        file: z.looseObject({}).optional(),
       }),
     },
     async (args, requestInfo, _meta) => {
       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.",
-          },
-        };
+        return toolErr("Skill not found.", { data: { yourAgentId: requestInfo.agentId } });
       }
 
       let file = null;
@@ -40,41 +31,17 @@ export const registerSkillGetFileTool = (server: McpServer) => {
         file = getSkillFile(args.skillId, args.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : "Invalid file path.";
-        return {
-          content: [{ type: "text", text: message }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message,
-          },
-        };
+        return toolErr(message, { data: { yourAgentId: requestInfo.agentId } });
       }
 
       if (!file) {
-        return {
-          content: [{ type: "text", text: "Skill file not found." }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "Skill file not found.",
-          },
-        };
+        return toolErr("Skill file not found.", { data: { yourAgentId: requestInfo.agentId } });
       }
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Skill file "${skill.name}/${file.path}" (${file.mimeType}):\n\n${file.content}`,
-          },
-        ],
-        structuredContent: {
-          yourAgentId: requestInfo.agentId,
-          success: true,
-          message: `Found skill file "${file.path}".`,
-          file,
-        },
-      };
+      return toolOk(`Found skill file "${file.path}".`, {
+        details: `Skill file "${skill.name}/${file.path}" (${file.mimeType}):\n\n${file.content}`,
+        data: { yourAgentId: requestInfo.agentId, file },
+      });
     },
   );
 };

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

@@ -1,7 +1,7 @@
 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";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerSkillGetTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -15,23 +15,14 @@ export const registerSkillGetTool = (server: McpServer) => {
         skillId: z.string().optional().describe("Skill ID"),
         name: z.string().optional().describe("Skill name (resolved with precedence)"),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
-        skill: z.any().optional(),
+        skill: z.looseObject({}).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.",
-          },
-        };
+        return toolErr("Provide skillId or name.", { data: { yourAgentId: requestInfo.agentId } });
       }
 
       let skill = null;
@@ -49,27 +40,13 @@ export const registerSkillGetTool = (server: McpServer) => {
       }
 
       if (!skill) {
-        return {
-          content: [{ type: "text", text: "Skill not found." }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "Skill not found.",
-          },
-        };
+        return toolErr("Skill not found.", { data: { yourAgentId: requestInfo.agentId } });
       }
 
-      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,
-        },
-      };
+      return toolOk(`Found skill "${skill.name}".`, {
+        details: `Skill "${skill.name}" (${skill.id}):\n\n${skill.content}`,
+        data: { yourAgentId: requestInfo.agentId, skill },
+      });
     },
   );
 };

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

@@ -3,7 +3,7 @@ import * as z from "zod";
 import { createSkill, getAgentById } from "@/be/db";
 import { parseSkillContent } from "@/be/skill-parser";
 import { can } from "@/rbac";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerSkillInstallRemoteTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -27,19 +27,14 @@ export const registerSkillInstallRemoteTool = (server: McpServer) => {
           .optional()
           .describe("If true, registers for npx install (metadata only)"),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
-        skill: z.any().optional(),
+        skill: z.looseObject({}).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." },
-        };
+        return toolErr("Agent ID not found.");
       }
 
       // Only leads can install global/swarm remote skills
@@ -55,14 +50,9 @@ export const registerSkillInstallRemoteTool = (server: McpServer) => {
         source: "mcp",
       });
       if (!decision.allow) {
-        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.",
-          },
-        };
+        return toolErr("Only lead agents can install remote skills.", {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
 
       try {
@@ -77,19 +67,10 @@ export const registerSkillInstallRemoteTool = (server: McpServer) => {
           // 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}`,
-              },
-            };
+            return toolErr(`Failed to fetch: HTTP ${response.status}`, {
+              details: `Failed to fetch SKILL.md from ${rawUrl}: ${response.status}`,
+              data: { yourAgentId: requestInfo.agentId },
+            });
           }
           content = await response.text();
           sourceHash = new Bun.CryptoHasher("sha256").update(content).digest("hex");
@@ -133,30 +114,13 @@ export const registerSkillInstallRemoteTool = (server: McpServer) => {
           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,
-          },
-        };
+        return toolOk(`Installed remote skill "${skill.name}".`, {
+          details: `Installed remote skill "${skill.name}" from ${args.sourceRepo}`,
+          data: { yourAgentId: requestInfo.agentId, 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}`,
-          },
-        };
+        return toolErr(`Failed: ${message}`, { data: { yourAgentId: requestInfo.agentId } });
       }
     },
   );