@desplega.ai/agent-swarm 1.123.0 → 1.124.0

package/src/tools/tracker/tracker-unlink.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { deleteTrackerSync } from "@/be/db-queries/tracker";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerTrackerUnlinkTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -14,27 +14,15 @@ export const registerTrackerUnlinkTool = (server: McpServer) => {
       inputSchema: z.object({
         syncId: z.string().describe("The tracker sync mapping ID to remove"),
       }),
-      outputSchema: z.object({
-        success: z.boolean(),
-        message: z.string(),
-      }),
+      outputSchema: swarmToolOutputSchema(),
     },
     async (args, _requestInfo, _meta) => {
       try {
         deleteTrackerSync(args.syncId);
-        return {
-          content: [{ type: "text", text: `Removed tracker sync mapping ${args.syncId}` }],
-          structuredContent: {
-            success: true,
-            message: `Removed tracker sync mapping ${args.syncId}.`,
-          },
-        };
+        return toolOk(`Removed tracker sync mapping ${args.syncId}.`);
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Failed to unlink: ${message}` }],
-          structuredContent: { success: false, message: `Failed: ${message}` },
-        };
+        return toolErr(`Failed to unlink: ${message}`);
       }
     },
   );

package/src/tools/unregister-service.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { deleteService, getServiceByAgentAndName, getServiceById } from "@/be/db";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerUnregisterServiceTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -19,32 +19,19 @@ export const registerUnregisterServiceTool = (server: McpServer) => {
           .optional()
           .describe("Service name to unregister (alternative to serviceId)."),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
       }),
     },
     async ({ serviceId, name }, requestInfo, _meta) => {
       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.',
-          },
-        };
+        return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
       }
 
       if (!serviceId && !name) {
-        return {
-          content: [{ type: "text", text: "Either serviceId or name is required." }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "Either serviceId or name is required.",
-          },
-        };
+        return toolErr("Either serviceId or name is required.", {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
 
       try {
@@ -55,58 +42,31 @@ export const registerUnregisterServiceTool = (server: McpServer) => {
         }
 
         if (!service) {
-          return {
-            content: [{ type: "text", text: "Service not found." }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "Service not found.",
-            },
-          };
+          return toolErr("Service not found.", { data: { yourAgentId: requestInfo.agentId } });
         }
 
         // Check ownership
         if (service.agentId !== requestInfo.agentId) {
-          return {
-            content: [{ type: "text", text: "You can only unregister your own services." }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "You can only unregister your own services.",
-            },
-          };
+          return toolErr("You can only unregister your own services.", {
+            data: { yourAgentId: requestInfo.agentId },
+          });
         }
 
         const deleted = deleteService(service.id);
         if (!deleted) {
-          return {
-            content: [{ type: "text", text: "Failed to unregister service." }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "Failed to unregister service.",
-            },
-          };
+          return toolErr("Failed to unregister service.", {
+            data: { yourAgentId: requestInfo.agentId },
+          });
         }
 
-        return {
-          content: [{ type: "text", text: `Unregistered service "${service.name}".` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: true,
-            message: `Unregistered service "${service.name}".`,
-          },
-        };
+        return toolOk(`Unregistered service "${service.name}".`, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Failed to unregister service: ${message}` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: `Failed to unregister service: ${message}`,
-          },
-        };
+        return toolErr(`Failed to unregister service: ${message}`, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
     },
   );

package/src/tools/update-profile.ts

@@ -5,8 +5,36 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getAgentById, updateAgentName, updateAgentProfile } from "@/be/db";
 import { can } from "@/rbac";
-import { createToolRegistrar } from "@/tools/utils";
-import { type Agent, AgentAvatarSchema, AgentSchema } from "@/types";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+import { type Agent, AgentAvatarSchema, AgentStatusSchema, ProviderNameSchema } from "@/types";
+
+// Loose mirror of AgentSchema for tool output: every field optional, no
+// datetime/uuid format pins, nested blobs collapsed to permissive objects.
+const agentOutputShape = z.looseObject({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  isLead: z.boolean().optional(),
+  status: AgentStatusSchema.optional(),
+  description: z.string().optional(),
+  role: z.string().optional(),
+  capabilities: z.array(z.string()).optional(),
+  claudeMd: z.string().optional(),
+  soulMd: z.string().optional(),
+  identityMd: z.string().optional(),
+  setupScript: z.string().optional(),
+  toolsMd: z.string().optional(),
+  heartbeatMd: z.string().optional(),
+  maxTasks: z.number().optional(),
+  emptyPollCount: z.number().optional(),
+  lastActivityAt: z.string().optional(),
+  provider: ProviderNameSchema.optional(),
+  harnessProvider: ProviderNameSchema.nullable().optional(),
+  credentialMissing: z.array(z.string()).nullable().optional(),
+  credStatus: z.looseObject({}).nullable().optional(),
+  avatar: z.looseObject({}).nullable().optional(),
+  createdAt: z.string().optional(),
+  lastUpdatedAt: z.string().optional(),
+});
 
 async function validateSetupScriptSyntax(setupScript: string): Promise<string | null> {
   const proc = Bun.spawn(["bash", "-n", "-c", setupScript], {
@@ -126,11 +154,9 @@ export const registerUpdateProfileTool = (server: McpServer) => {
             "Custom avatar: { type: 'lucide', icon: '<kebab-case-lucide-name>', color?: '#RRGGBB' }. Pass null to reset to the default deterministic icon/color.",
           ),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
-        agent: AgentSchema.optional(),
+        agent: agentOutputShape.optional(),
       }),
     },
     async (
@@ -152,13 +178,7 @@ export const registerUpdateProfileTool = (server: McpServer) => {
       _meta,
     ) => {
       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.',
-          },
-        };
+        return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
       }
 
       // Determine target agent: if agentId is provided, check lead permissions
@@ -169,14 +189,9 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         // Only lead agents can update other agents' profiles
         const callingAgent = getAgentById(requestInfo.agentId);
         if (!callingAgent) {
-          return {
-            content: [{ type: "text", text: "Calling agent not found." }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "Calling agent not found.",
-            },
-          };
+          return toolErr("Calling agent not found.", {
+            data: { yourAgentId: requestInfo.agentId },
+          });
         }
         const decision = can({
           principal: { kind: "agent", agentId: callingAgent.id, isLead: callingAgent.isLead },
@@ -185,33 +200,18 @@ export const registerUpdateProfileTool = (server: McpServer) => {
           source: "mcp",
         });
         if (!decision.allow) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Only lead agents can update other agents' profiles. Provide no agentId to update your own profile.",
-              },
-            ],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message:
-                "Only lead agents can update other agents' profiles. Provide no agentId to update your own profile.",
-            },
-          };
+          return toolErr(
+            "Only lead agents can update other agents' profiles. Provide no agentId to update your own profile.",
+            { data: { yourAgentId: requestInfo.agentId } },
+          );
         }
 
         // Validate target agent exists before proceeding
         const targetAgent = getAgentById(targetAgentId);
         if (!targetAgent) {
-          return {
-            content: [{ type: "text", text: `Target agent ${targetAgentId} not found.` }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: `Target agent ${targetAgentId} not found.`,
-            },
-          };
+          return toolErr(`Target agent ${targetAgentId} not found.`, {
+            data: { yourAgentId: requestInfo.agentId },
+          });
         }
       }
 
@@ -229,20 +229,10 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         heartbeatMd === undefined &&
         avatar === undefined
       ) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, toolsMd, heartbeatMd, or avatar) must be provided.",
-            },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message:
-              "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, toolsMd, heartbeatMd, or avatar) must be provided.",
-          },
-        };
+        return toolErr(
+          "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, toolsMd, heartbeatMd, or avatar) must be provided.",
+          { data: { yourAgentId: requestInfo.agentId } },
+        );
       }
 
       try {
@@ -253,14 +243,9 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         if (setupScript !== undefined) {
           const syntaxError = await validateSetupScriptSyntax(setupScript);
           if (syntaxError) {
-            return {
-              content: [{ type: "text", text: `Invalid setupScript: ${syntaxError}` }],
-              structuredContent: {
-                yourAgentId: requestInfo.agentId,
-                success: false,
-                message: `Invalid setupScript: ${syntaxError}`,
-              },
-            };
+            return toolErr(`Invalid setupScript: ${syntaxError}`, {
+              data: { yourAgentId: requestInfo.agentId },
+            });
           }
         }
 
@@ -268,14 +253,9 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         if (name !== undefined) {
           agent = updateAgentName(targetAgentId, name);
           if (!agent) {
-            return {
-              content: [{ type: "text", text: "Target agent not found." }],
-              structuredContent: {
-                yourAgentId: requestInfo.agentId,
-                success: false,
-                message: "Target agent not found.",
-              },
-            };
+            return toolErr("Target agent not found.", {
+              data: { yourAgentId: requestInfo.agentId },
+            });
           }
         }
 
@@ -368,14 +348,7 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         }
 
         if (!agent) {
-          return {
-            content: [{ type: "text", text: "Agent not found." }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "Agent not found.",
-            },
-          };
+          return toolErr("Agent not found.", { data: { yourAgentId: requestInfo.agentId } });
         }
 
         const updatedFields: string[] = [];
@@ -392,27 +365,14 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         if (avatar !== undefined) updatedFields.push("avatar");
 
         const targetLabel = isUpdatingSelf ? "own" : `agent ${targetAgentId}`;
-        return {
-          content: [
-            { type: "text", text: `Updated ${targetLabel} profile: ${updatedFields.join(", ")}.` },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: true,
-            message: `Updated ${targetLabel} profile: ${updatedFields.join(", ")}.`,
-            agent,
-          },
-        };
+        return toolOk(`Updated ${targetLabel} profile: ${updatedFields.join(", ")}.`, {
+          data: { yourAgentId: requestInfo.agentId, agent },
+        });
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Failed to update profile: ${message}` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: `Failed to update profile: ${message}`,
-          },
-        };
+        return toolErr(`Failed to update profile: ${message}`, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
     },
   );

package/src/tools/update-service-status.ts

@@ -1,8 +1,29 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getServiceByAgentAndName, getServiceById, updateServiceStatus } from "@/be/db";
-import { createToolRegistrar } from "@/tools/utils";
-import { ServiceSchema, ServiceStatusSchema } from "@/types";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+import { ServiceStatusSchema } from "@/types";
+
+// Loose mirror of ServiceSchema for tool output: every field optional, no
+// url/uuid/datetime format pins.
+const serviceOutputShape = z.looseObject({
+  id: z.string().optional(),
+  agentId: z.string().optional(),
+  name: z.string().optional(),
+  port: z.number().optional(),
+  description: z.string().optional(),
+  url: z.string().optional(),
+  healthCheckPath: z.string().optional(),
+  status: ServiceStatusSchema.optional(),
+  script: z.string().optional(),
+  cwd: z.string().optional(),
+  interpreter: z.string().optional(),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  createdAt: z.string().optional(),
+  lastUpdatedAt: z.string().optional(),
+});
 
 export const registerUpdateServiceStatusTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -20,33 +41,20 @@ export const registerUpdateServiceStatusTool = (server: McpServer) => {
           "New status: 'starting', 'healthy', 'unhealthy', or 'stopped'.",
         ),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
-        service: ServiceSchema.optional(),
+        service: serviceOutputShape.optional(),
       }),
     },
     async ({ serviceId, name, status }, requestInfo, _meta) => {
       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.',
-          },
-        };
+        return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
       }
 
       if (!serviceId && !name) {
-        return {
-          content: [{ type: "text", text: "Either serviceId or name is required." }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: "Either serviceId or name is required.",
-          },
-        };
+        return toolErr("Either serviceId or name is required.", {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
 
       try {
@@ -57,64 +65,31 @@ export const registerUpdateServiceStatusTool = (server: McpServer) => {
         }
 
         if (!service) {
-          return {
-            content: [{ type: "text", text: "Service not found." }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "Service not found.",
-            },
-          };
+          return toolErr("Service not found.", { data: { yourAgentId: requestInfo.agentId } });
         }
 
         // Check ownership
         if (service.agentId !== requestInfo.agentId) {
-          return {
-            content: [{ type: "text", text: "You can only update status of your own services." }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "You can only update status of your own services.",
-            },
-          };
+          return toolErr("You can only update status of your own services.", {
+            data: { yourAgentId: requestInfo.agentId },
+          });
         }
 
         const updated = updateServiceStatus(service.id, status);
         if (!updated) {
-          return {
-            content: [{ type: "text", text: "Failed to update service status." }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: "Failed to update service status.",
-            },
-          };
+          return toolErr("Failed to update service status.", {
+            data: { yourAgentId: requestInfo.agentId },
+          });
         }
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Updated service "${service.name}" status to "${status}".`,
-            },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: true,
-            message: `Updated service "${service.name}" status to "${status}".`,
-            service: updated,
-          },
-        };
+        return toolOk(`Updated service "${service.name}" status to "${status}".`, {
+          data: { yourAgentId: requestInfo.agentId, service: updated },
+        });
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Failed to update service status: ${message}` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: `Failed to update service status: ${message}`,
-          },
-        };
+        return toolErr(`Failed to update service status: ${message}`, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
     },
   );