@desplega.ai/agent-swarm 1.123.0 → 1.124.0

package/src/tools/swarm-config/set-config.ts

@@ -8,8 +8,22 @@ import {
 } from "@/be/swarm-config-guard";
 import { scheduleIntegrationsReload } from "@/http/core";
 import { can } from "@/rbac";
-import { createToolRegistrar } from "@/tools/utils";
-import { SwarmConfigSchema, SwarmConfigScopeSchema } from "@/types";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+import { SwarmConfigScopeSchema } from "@/types";
+
+const configEntryShape = z.looseObject({
+  id: z.string().optional(),
+  scope: SwarmConfigScopeSchema.optional(),
+  scopeId: z.string().nullable().optional(),
+  key: z.string().optional(),
+  value: z.string().optional(),
+  isSecret: z.boolean().optional(),
+  envPath: z.string().nullable().optional(),
+  description: z.string().nullable().optional(),
+  createdAt: z.string().optional(),
+  lastUpdatedAt: z.string().optional(),
+  encrypted: z.boolean().optional(),
+});
 
 export const registerSetConfigTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -47,51 +61,27 @@ export const registerSetConfigTool = (server: McpServer) => {
           .optional()
           .describe("Optional human-readable description of this config entry."),
       }),
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
-        config: SwarmConfigSchema.optional(),
+        config: configEntryShape.optional(),
       }),
     },
     async ({ scope, scopeId, key, value, isSecret, envPath, description }, 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.',
-          },
-        };
+        return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
       }
 
       try {
         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}'.`,
-            },
-          };
+          return toolErr(`scopeId is required for scope '${scope}'.`, {
+            details: `scopeId is required for scope '${scope}'. Provide an agent ID or repo ID.`,
+            data: { yourAgentId: requestInfo.agentId },
+          });
         }
 
         if (isReservedConfigKey(key)) {
           const message = reservedKeyError(key).message;
-          return {
-            content: [{ type: "text", text: message }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message,
-            },
-          };
+          return toolErr(message, { data: { yourAgentId: requestInfo.agentId } });
         }
 
         // Every swarm-config write is lead-gated (DES-445 follow-up): previously
@@ -110,27 +100,14 @@ export const registerSetConfigTool = (server: McpServer) => {
           source: "mcp",
         });
         if (!decision.allow) {
-          const message = "Writing swarm config requires the lead agent.";
-          return {
-            content: [{ type: "text", text: message }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message,
-            },
-          };
+          return toolErr("Writing swarm config requires the lead agent.", {
+            data: { yourAgentId: requestInfo.agentId },
+          });
         }
 
         const validationError = validateConfigValue(key, value);
         if (validationError) {
-          return {
-            content: [{ type: "text", text: validationError }],
-            structuredContent: {
-              yourAgentId: requestInfo.agentId,
-              success: false,
-              message: validationError,
-            },
-          };
+          return toolErr(validationError, { data: { yourAgentId: requestInfo.agentId } });
         }
 
         const config = upsertSwarmConfig({
@@ -149,30 +126,15 @@ export const registerSetConfigTool = (server: McpServer) => {
 
         const [masked] = maskSecrets([config]);
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Config "${key}" set successfully (scope: ${scope}${scopeId ? `, scopeId: ${scopeId}` : ""}).`,
-            },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: true,
-            message: `Config "${key}" set successfully.`,
-            config: masked,
-          },
-        };
+        return toolOk(`Config "${key}" set successfully.`, {
+          details: `Config "${key}" set successfully (scope: ${scope}${scopeId ? `, scopeId: ${scopeId}` : ""}).`,
+          data: { yourAgentId: requestInfo.agentId, config: masked },
+        });
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Failed to set config: ${message}` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: `Failed to set config: ${message}`,
-          },
-        };
+        return toolErr(`Failed to set config: ${message}`, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
     },
   );

package/src/tools/swarm-x.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { COMPOSIO_HTTP_METHODS, composioArgsFromParts, executeComposioRequest } from "@/x/composio";
-import { createToolRegistrar } from "./utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "./utils";
 
 const primitiveQueryValueSchema = z.union([z.string(), z.number(), z.boolean()]);
 
@@ -46,16 +46,15 @@ export const registerSwarmXTool = (server: McpServer) => {
           .default(false)
           .describe("Return raw text instead of JSON-pretty output text."),
       }),
-      outputSchema: z.object({
-        target: z.literal("composio"),
-        ok: z.boolean(),
-        status: z.number(),
-        statusText: z.string(),
-        method: z.string(),
-        url: z.string(),
-        response: z.unknown(),
-        responseText: z.string(),
-        message: z.string(),
+      outputSchema: swarmToolOutputSchema({
+        target: z.literal("composio").optional(),
+        ok: z.boolean().optional(),
+        status: z.number().optional(),
+        statusText: z.string().optional(),
+        method: z.string().optional(),
+        url: z.string().optional(),
+        response: z.unknown().optional(),
+        responseText: z.string().optional(),
       }),
     },
     async (input) => {
@@ -75,9 +74,8 @@ export const registerSwarmXTool = (server: McpServer) => {
         );
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{ type: "text", text: `swarm_x composio: ${message}` }],
-          structuredContent: {
+        return toolErr(`swarm_x composio: ${message}`, {
+          data: {
             target: "composio",
             ok: false,
             status: 0,
@@ -86,15 +84,14 @@ export const registerSwarmXTool = (server: McpServer) => {
             url: "",
             response: null,
             responseText: "",
-            message,
           },
-          isError: true,
-        };
+        });
       }
 
-      const message =
-        result.error || result.formattedBody || `HTTP ${result.status} ${result.statusText}`.trim();
-      const structuredContent = {
+      const summary =
+        `Composio ${result.method} ${result.url} → HTTP ${result.status} ${result.statusText}`.trim();
+      const details = result.error || result.formattedBody || undefined;
+      const data = {
         target: "composio" as const,
         ok: result.ok,
         status: result.status,
@@ -103,14 +100,11 @@ export const registerSwarmXTool = (server: McpServer) => {
         url: result.url,
         response: result.body,
         responseText: result.text,
-        message,
       };
 
-      return {
-        content: [{ type: "text", text: message }],
-        structuredContent,
-        isError: !result.ok,
-      };
+      return result.ok
+        ? toolOk(summary, { details, data })
+        : toolErr(result.error || summary, { details, data });
     },
   );
 };

package/src/tools/task-action.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";
@@ -29,15 +28,21 @@ import {
   updateTaskClaudeSessionId,
 } from "@/be/db";
 import { assertOwnsTask, ownerCtx, type ToolCtx } from "@/tools/task-tool-ctx";
-import { createToolRegistrar } from "@/tools/utils";
 import {
-  AgentTaskSchema,
+  createToolRegistrar,
+  type SwarmToolResult,
+  swarmToolOutputSchema,
+  toolErr,
+  toolOk,
+} from "@/tools/utils";
+import {
   AssetKeySchema,
   BudgetRefusalCauseSchema,
   ModelTierSchema,
   ReasoningEffortSchema,
   splitLegacyModelAlias,
 } from "@/types";
+import { looseAgentTaskOutputSchema } from "./get-task-details";
 
 export const TaskActionSchema = z.enum([
   "create",
@@ -100,11 +105,9 @@ export const taskActionInputSchema = z.object({
     ),
 });
 
-export const taskActionOutputSchema = z.object({
+export const taskActionOutputSchema = swarmToolOutputSchema({
   yourAgentId: z.string().optional(),
-  success: z.boolean(),
-  message: z.string(),
-  task: AgentTaskSchema.optional(),
+  task: looseAgentTaskOutputSchema.optional(),
   // Phase 3: budget-admission refusal fields. Populated only on
   // `accept` action when the per-agent or global daily budget is blown.
   refusalCause: BudgetRefusalCauseSchema.optional(),
@@ -133,43 +136,26 @@ type TaskActionResult = {
   refusalSideEffects?: unknown;
 };
 
-function agentOnlyActionResult(): CallToolResult {
-  const message = "This action is only available to worker agents.";
-  const structuredContent = {
-    success: false,
-    message,
-  };
-
-  return {
-    isError: true,
-    content: [
-      { type: "text", text: message },
-      { type: "text", text: JSON.stringify(structuredContent) },
-    ],
-    structuredContent,
-  };
+function agentOnlyActionResult(): SwarmToolResult {
+  return toolErr("This action is only available to worker agents.");
 }
 
-function taskActionCallResult(result: TaskActionResult, agentId?: string): CallToolResult {
-  const { refusalSideEffects: _omit, ...publicResult } = result;
-  const structuredContent = {
+function taskActionResult(result: TaskActionResult, agentId?: string): SwarmToolResult {
+  const { refusalSideEffects: _omit, success, message, ...rest } = result;
+  const data = {
     yourAgentId: agentId,
-    ...publicResult,
-  };
-
-  return {
-    content: [
-      { type: "text", text: result.message },
-      { type: "text", text: JSON.stringify(structuredContent) },
-    ],
-    structuredContent,
+    ...rest,
   };
+  // Most harnesses only show the model the text channel — render the payload
+  // (task object, refusalCause, ...) there too, not just in structuredContent.
+  const details = Object.keys(rest).length > 0 ? JSON.stringify(rest, null, 2) : undefined;
+  return success ? toolOk(message, { data, details }) : toolErr(message, { data, details });
 }
 
 export async function taskActionHandler(
   ctx: ToolCtx,
   input: TaskActionArgs,
-): Promise<CallToolResult> {
+): Promise<SwarmToolResult> {
   const {
     action,
     task,
@@ -191,7 +177,7 @@ export async function taskActionHandler(
       return agentOnlyActionResult();
     }
 
-    const result = getDb().transaction((): TaskActionResult | CallToolResult => {
+    const result = getDb().transaction((): TaskActionResult | SwarmToolResult => {
       if (!taskId) {
         return { success: false, message: `Task ID is required for '${action}' action.` };
       }
@@ -239,17 +225,11 @@ export async function taskActionHandler(
       };
     })();
 
-    return "content" in result ? result : taskActionCallResult(result);
+    return "ok" in result ? result : taskActionResult(result);
   }
 
   if (!ctx.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.');
   }
 
   const agentId = ctx.agentId;
@@ -266,7 +246,7 @@ export async function taskActionHandler(
           : error instanceof Error
             ? error.message
             : String(error);
-      return taskActionCallResult({ success: false, message }, agentId);
+      return taskActionResult({ success: false, message }, agentId);
     }
   }
 
@@ -597,7 +577,7 @@ export async function taskActionHandler(
     emitBudgetRefusalSideEffects(sideEffects.context, sideEffects.inserted);
   }
 
-  return taskActionCallResult(result, agentId);
+  return taskActionResult(result, agentId);
 }
 
 export const registerTaskActionTool = (server: McpServer) => {

package/src/tools/task-tool-ctx.ts

@@ -1,7 +1,6 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { can, type PermissionVerb } from "@/rbac";
 import type { AgentTask, User } from "@/types";
-import type { RequestInfo } from "./utils";
+import { type RequestInfo, type SwarmToolResult, toolErr } from "./utils";
 
 export type ToolCtx =
   | { kind: "owner"; agentId?: string; sourceTaskId?: string; sessionId?: string }
@@ -29,7 +28,7 @@ export function assertOwnsTask(
   ctx: ToolCtx,
   task: AgentTask,
   verb: PermissionVerb = "task.read.own",
-): CallToolResult | null {
+): SwarmToolResult | null {
   // RBAC chokepoint — a future admin/role tier widens visibility here, in this one function.
   const decision = can({
     principal:
@@ -46,14 +45,7 @@ export function assertOwnsTask(
     return null;
   }
 
-  const message = `Forbidden: this task is not yours (task ${task.id}).`;
-  return {
-    isError: true,
-    content: [{ type: "text", text: message }],
-    structuredContent: {
-      success: false,
-      code: "forbidden",
-      message,
-    },
-  };
+  return toolErr(`Forbidden: this task is not yours (task ${task.id}).`, {
+    data: { code: "forbidden" },
+  });
 }

package/src/tools/tracker/tracker-link-task.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { createTrackerSync } from "@/be/db-queries/tracker";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerTrackerLinkTaskTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -21,10 +21,8 @@ export const registerTrackerLinkTaskTool = (server: McpServer) => {
           .describe("Human-readable identifier (e.g. 'ENG-42')"),
         externalUrl: z.string().optional().describe("URL to the external issue"),
       }),
-      outputSchema: z.object({
-        success: z.boolean(),
-        message: z.string(),
-        sync: z.any().optional(),
+      outputSchema: swarmToolOutputSchema({
+        sync: z.unknown().optional(),
       }),
     },
     async (args, _requestInfo, _meta) => {
@@ -39,25 +37,13 @@ export const registerTrackerLinkTaskTool = (server: McpServer) => {
           syncDirection: "bidirectional",
         });
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Linked task ${args.swarmTaskId} to ${args.provider} issue ${args.externalIdentifier ?? args.externalId}`,
-            },
-          ],
-          structuredContent: {
-            success: true,
-            message: `Linked task ${args.swarmTaskId} to ${args.provider} issue ${args.externalIdentifier ?? args.externalId}.`,
-            sync,
-          },
-        };
+        return toolOk(
+          `Linked task ${args.swarmTaskId} to ${args.provider} issue ${args.externalIdentifier ?? args.externalId}.`,
+          { data: { sync } },
+        );
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Failed to link task: ${message}` }],
-          structuredContent: { success: false, message: `Failed: ${message}` },
-        };
+        return toolErr(`Failed to link task: ${message}`);
       }
     },
   );

package/src/tools/tracker/tracker-map-agent.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { createTrackerAgentMapping } from "@/be/db-queries/tracker";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerTrackerMapAgentTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -17,10 +17,8 @@ export const registerTrackerMapAgentTool = (server: McpServer) => {
         externalUserId: z.string().describe("The external user ID in the tracker"),
         agentName: z.string().describe("Display name for the agent mapping"),
       }),
-      outputSchema: z.object({
-        success: z.boolean(),
-        message: z.string(),
-        mapping: z.any().optional(),
+      outputSchema: swarmToolOutputSchema({
+        mapping: z.unknown().optional(),
       }),
     },
     async (args, _requestInfo, _meta) => {
@@ -32,25 +30,13 @@ export const registerTrackerMapAgentTool = (server: McpServer) => {
           agentName: args.agentName,
         });
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Mapped agent ${args.agentName} to ${args.provider} user ${args.externalUserId}`,
-            },
-          ],
-          structuredContent: {
-            success: true,
-            message: `Mapped agent ${args.agentName} to ${args.provider} user ${args.externalUserId}.`,
-            mapping,
-          },
-        };
+        return toolOk(
+          `Mapped agent ${args.agentName} to ${args.provider} user ${args.externalUserId}.`,
+          { data: { mapping } },
+        );
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Failed to map agent: ${message}` }],
-          structuredContent: { success: false, message: `Failed: ${message}` },
-        };
+        return toolErr(`Failed to map agent: ${message}`);
       }
     },
   );

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

@@ -2,7 +2,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getOAuthApp, getOAuthTokens } from "@/be/db-queries/oauth";
 import { ensureToken } from "@/oauth/ensure-token";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolOk } from "@/tools/utils";
 
 export const registerTrackerStatusTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -13,17 +13,18 @@ export const registerTrackerStatusTool = (server: McpServer) => {
         "Show all connected trackers and their OAuth status (token expiry, workspace info). Proactively refreshes near-expiry tokens before reporting, so the returned `tokenExpiresAt` reflects the row that subsequent API calls (and direct DB reads) will see.",
       annotations: { readOnlyHint: true },
 
-      outputSchema: z.object({
-        success: z.boolean(),
-        trackers: z.array(
-          z.object({
-            provider: z.string(),
-            connected: z.boolean(),
-            tokenExpiresAt: z.string().nullable(),
-            scopes: z.string().nullable(),
-            redirectUri: z.string().nullable(),
-          }),
-        ),
+      outputSchema: swarmToolOutputSchema({
+        trackers: z
+          .array(
+            z.looseObject({
+              provider: z.string().optional(),
+              connected: z.boolean().optional(),
+              tokenExpiresAt: z.string().nullable().optional(),
+              scopes: z.string().nullable().optional(),
+              redirectUri: z.string().nullable().optional(),
+            }),
+          )
+          .optional(),
       }),
     },
     async (_requestInfo, _meta) => {
@@ -50,13 +51,20 @@ export const registerTrackerStatusTool = (server: McpServer) => {
         .map((t) => `${t.provider}: ${t.connected ? "connected" : "not connected"}`)
         .join(", ");
 
-      return {
-        content: [{ type: "text", text: `Tracker status: ${summary}` }],
-        structuredContent: {
-          success: true,
-          trackers,
-        },
-      };
+      const details = trackers
+        .map((t) => {
+          const bits = [
+            `provider: ${t.provider}`,
+            `connected: ${t.connected}`,
+            `tokenExpiresAt: ${t.tokenExpiresAt ?? "n/a"}`,
+            `scopes: ${t.scopes ?? "n/a"}`,
+            `redirectUri: ${t.redirectUri ?? "n/a"}`,
+          ];
+          return `- ${bits.join(", ")}`;
+        })
+        .join("\n");
+
+      return toolOk(`Tracker status: ${summary}`, { details, data: { trackers } });
     },
   );
 };

package/src/tools/tracker/tracker-sync-status.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getAllTrackerSyncs } from "@/be/db-queries/tracker";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolOk } from "@/tools/utils";
 
 export const registerTrackerSyncStatusTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -15,28 +15,18 @@ export const registerTrackerSyncStatusTool = (server: McpServer) => {
         provider: z.string().optional().describe("Filter by provider (e.g. 'linear', 'jira')"),
         entityType: z.enum(["task"]).optional().describe("Filter by entity type"),
       }),
-      outputSchema: z.object({
-        success: z.boolean(),
-        count: z.number(),
-        syncs: z.array(z.any()),
+      outputSchema: swarmToolOutputSchema({
+        count: z.number().optional(),
+        syncs: z.array(z.unknown()).optional(),
       }),
     },
     async (args, _requestInfo, _meta) => {
       const syncs = getAllTrackerSyncs(args.provider, args.entityType);
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Found ${syncs.length} tracker sync mapping(s)${args.provider ? ` for ${args.provider}` : ""}${args.entityType ? ` (${args.entityType})` : ""}.`,
-          },
-        ],
-        structuredContent: {
-          success: true,
-          count: syncs.length,
-          syncs,
-        },
-      };
+      return toolOk(
+        `Found ${syncs.length} tracker sync mapping(s)${args.provider ? ` for ${args.provider}` : ""}${args.entityType ? ` (${args.entityType})` : ""}.`,
+        { data: { count: syncs.length, syncs } },
+      );
     },
   );
 };