@desplega.ai/agent-swarm 1.123.0 → 1.124.0

package/src/tools/schedules/update-schedule.ts

@@ -13,7 +13,7 @@ import {
 import { mergeScheduleTiming, validateRecurringTiming } from "@/be/schedules/validate";
 import { getScript } from "@/be/scripts/db";
 import { calculateNextRun } from "@/scheduler";
-import { createToolRegistrar } from "@/tools/utils";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import {
   AssetKeySchema,
   ModelTierSchema,
@@ -73,6 +73,34 @@ export const updateScheduleInputSchema = z.object({
     .describe("Portable model tier for tasks created by this schedule. Set to null to clear."),
 });
 
+const scheduleDataShape = {
+  id: z.string().optional(),
+  key: AssetKeySchema.optional(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  cronExpression: z.string().optional(),
+  intervalMs: z.number().optional(),
+  taskTemplate: z.string().optional(),
+  taskType: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  priority: z.number().optional(),
+  targetAgentId: z.string().optional(),
+  enabled: z.boolean().optional(),
+  lastRunAt: z.string().optional(),
+  nextRunAt: z.string().optional(),
+  createdByAgentId: z.string().optional(),
+  timezone: z.string().optional(),
+  model: z.string().optional(),
+  modelTier: ModelTierSchema.optional(),
+  scheduleType: z.string().optional(),
+  targetType: ScheduledTaskTargetTypeSchema.optional(),
+  workflowId: z.string().optional(),
+  scriptName: z.string().optional(),
+  scriptArgs: z.record(z.string(), z.unknown()).optional(),
+  createdAt: z.string().optional(),
+  lastUpdatedAt: z.string().optional(),
+};
+
 export const registerUpdateScheduleTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "update-schedule",
@@ -81,39 +109,9 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
       annotations: { idempotentHint: true },
       description: "Update an existing scheduled task. Any registered agent can update schedules.",
       inputSchema: updateScheduleInputSchema,
-      outputSchema: z.object({
+      outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
-        success: z.boolean(),
-        message: z.string(),
-        schedule: z
-          .object({
-            id: z.string(),
-            key: AssetKeySchema,
-            name: z.string(),
-            description: z.string().optional(),
-            cronExpression: z.string().optional(),
-            intervalMs: z.number().optional(),
-            taskTemplate: z.string().optional(),
-            taskType: z.string().optional(),
-            tags: z.array(z.string()),
-            priority: z.number(),
-            targetAgentId: z.string().optional(),
-            enabled: z.boolean(),
-            lastRunAt: z.string().optional(),
-            nextRunAt: z.string().optional(),
-            createdByAgentId: z.string().optional(),
-            timezone: z.string(),
-            model: z.string().optional(),
-            modelTier: ModelTierSchema.optional(),
-            scheduleType: z.string(),
-            targetType: ScheduledTaskTargetTypeSchema.optional(),
-            workflowId: z.string().optional(),
-            scriptName: z.string().optional(),
-            scriptArgs: z.record(z.string(), z.unknown()).optional(),
-            createdAt: z.string(),
-            lastUpdatedAt: z.string(),
-          })
-          .optional(),
+        schedule: z.looseObject(scheduleDataShape).optional(),
       }),
     },
     async (
@@ -143,13 +141,7 @@ export const registerUpdateScheduleTool = (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.');
       }
 
       // Find the schedule
@@ -160,40 +152,19 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
           : null;
 
       if (!schedule) {
-        return {
-          content: [{ type: "text", text: "Schedule not found." }],
-          structuredContent: {
-            success: false,
-            message: "Schedule not found.",
-          },
-        };
+        return toolErr("Schedule not found.");
       }
 
       const caller = getAgentById(requestInfo.agentId);
       if (!caller) {
-        return {
-          content: [{ type: "text", text: "Agent not found." }],
-          structuredContent: {
-            success: false,
-            message: "Agent not found.",
-          },
-        };
+        return toolErr("Agent not found.");
       }
 
       // Reject updates on completed one-time schedules
       if (schedule.scheduleType === "one_time" && !schedule.enabled && schedule.lastRunAt) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `One-time schedule "${schedule.name}" has already executed. Create a new one instead.`,
-            },
-          ],
-          structuredContent: {
-            success: false,
-            message: `One-time schedule "${schedule.name}" has already executed. Create a new one instead.`,
-          },
-        };
+        return toolErr(
+          `One-time schedule "${schedule.name}" has already executed. Create a new one instead.`,
+        );
       }
 
       // Validate new cron expression if provided
@@ -204,13 +175,7 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
           });
         } catch (err) {
           const message = err instanceof Error ? err.message : "Invalid cron expression";
-          return {
-            content: [{ type: "text", text: `Invalid cron expression: ${message}` }],
-            structuredContent: {
-              success: false,
-              message: `Invalid cron expression: ${message}`,
-            },
-          };
+          return toolErr(`Invalid cron expression: ${message}`);
         }
       }
 
@@ -218,13 +183,7 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
       if (targetAgentId && targetAgentId !== null) {
         const agent = getAgentById(targetAgentId);
         if (!agent) {
-          return {
-            content: [{ type: "text", text: `Target agent not found: ${targetAgentId}` }],
-            structuredContent: {
-              success: false,
-              message: `Target agent not found: ${targetAgentId}`,
-            },
-          };
+          return toolErr(`Target agent not found: ${targetAgentId}`);
         }
       }
 
@@ -232,13 +191,7 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
       if (newName && newName !== schedule.name) {
         const existing = getScheduledTaskByName(newName);
         if (existing) {
-          return {
-            content: [{ type: "text", text: `Schedule with name "${newName}" already exists.` }],
-            structuredContent: {
-              success: false,
-              message: `Schedule with name "${newName}" already exists.`,
-            },
-          };
+          return toolErr(`Schedule with name "${newName}" already exists.`);
         }
       }
 
@@ -249,42 +202,22 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
       const mergedScriptName = scriptName !== undefined ? scriptName : schedule.scriptName;
 
       if (mergedTargetType === "agent-task" && !mergedTaskTemplate) {
-        const message = "taskTemplate is required when targetType is 'agent-task'.";
-        return {
-          content: [{ type: "text", text: message }],
-          structuredContent: { success: false, message },
-        };
+        return toolErr("taskTemplate is required when targetType is 'agent-task'.");
       }
       if (mergedTargetType === "workflow") {
         if (!mergedWorkflowId) {
-          const message = "workflowId is required when targetType is 'workflow'.";
-          return {
-            content: [{ type: "text", text: message }],
-            structuredContent: { success: false, message },
-          };
+          return toolErr("workflowId is required when targetType is 'workflow'.");
         }
         if (!getWorkflow(mergedWorkflowId)) {
-          const message = `Workflow not found: ${mergedWorkflowId}`;
-          return {
-            content: [{ type: "text", text: message }],
-            structuredContent: { success: false, message },
-          };
+          return toolErr(`Workflow not found: ${mergedWorkflowId}`);
         }
       }
       if (mergedTargetType === "script") {
         if (!mergedScriptName) {
-          const message = "scriptName is required when targetType is 'script'.";
-          return {
-            content: [{ type: "text", text: message }],
-            structuredContent: { success: false, message },
-          };
+          return toolErr("scriptName is required when targetType is 'script'.");
         }
         if (!getScript({ name: mergedScriptName, scope: "global" })) {
-          const message = `Script not found: ${mergedScriptName}`;
-          return {
-            content: [{ type: "text", text: message }],
-            structuredContent: { success: false, message },
-          };
+          return toolErr(`Script not found: ${mergedScriptName}`);
         }
       }
 
@@ -333,19 +266,9 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
           );
           const timingError = validateRecurringTiming(timing);
           if (timingError) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: "At least one of intervalMs or cronExpression must be set for recurring schedules.",
-                },
-              ],
-              structuredContent: {
-                success: false,
-                message:
-                  "At least one of intervalMs or cronExpression must be set for recurring schedules.",
-              },
-            };
+            return toolErr(
+              "At least one of intervalMs or cronExpression must be set for recurring schedules.",
+            );
           }
 
           const needsNextRunRecalc =
@@ -375,39 +298,20 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
         const updated = updateScheduledTask(schedule.id, { ...updateData, updatedBy });
 
         if (!updated) {
-          return {
-            content: [{ type: "text", text: "Failed to update schedule." }],
-            structuredContent: {
-              success: false,
-              message: "Failed to update schedule.",
-            },
-          };
+          return toolErr("Failed to update schedule.");
         }
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Updated schedule "${updated.name}". Next run: ${updated.nextRunAt || "disabled"}`,
-            },
-          ],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: true,
-            message: `Updated schedule "${updated.name}".`,
-            schedule: updated,
+        return toolOk(
+          `Updated schedule "${updated.name}". Next run: ${updated.nextRunAt || "disabled"}`,
+          {
+            data: { yourAgentId: requestInfo.agentId, schedule: updated },
           },
-        };
+        );
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Failed to update schedule: ${message}` }],
-          structuredContent: {
-            yourAgentId: requestInfo.agentId,
-            success: false,
-            message: `Failed to update schedule: ${message}`,
-          },
-        };
+        return toolErr(`Failed to update schedule: ${message}`, {
+          data: { yourAgentId: requestInfo.agentId },
+        });
       }
     },
   );

package/src/tools/script-apis.ts

@@ -1,10 +1,9 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import * as z from "zod";
 import { getAgentById } from "@/be/db";
 import { can, type PermissionVerb } from "@/rbac";
-import type { RequestInfo } from "@/tools/utils";
-import { createToolRegistrar } from "@/tools/utils";
+import type { RequestInfo, SwarmToolResult } from "@/tools/utils";
+import { createToolRegistrar, toolErr, toolOk } from "@/tools/utils";
 import type { ScriptApiRecord, ScriptApiWithSecret } from "@/types";
 import { registerVolatileSecret } from "@/utils/secret-scrubber";
 import { proxyScriptsApi, SCRIPT_TRANSPORT_ERROR, scriptToolOutputSchema } from "./script-common";
@@ -44,20 +43,23 @@ function maskToken(endpoint: RawEndpoint): RawEndpoint {
   return { ...rest, token: endpoint.authMode === "bearer" ? "********" : null };
 }
 
-function errorResult(message: string, status = 400): CallToolResult {
-  return {
-    isError: true,
-    content: [{ type: "text", text: message }],
-    structuredContent: { success: false, status, error: message },
-  };
+function renderEndpointsList(endpoints: RawEndpoint[]): string | undefined {
+  if (endpoints.length === 0) return undefined;
+  return endpoints
+    .map((endpoint) => {
+      const label = endpoint.label ? ` "${endpoint.label}"` : "";
+      const token = endpoint.token ? `, token=${endpoint.token}` : "";
+      return `- ${endpoint.id}${label}: authMode=${endpoint.authMode}, enabled=${endpoint.enabled}${token}`;
+    })
+    .join("\n");
 }
 
 function requireScriptApiPermission(
   requestInfo: RequestInfo,
   verb: PermissionVerb,
   message: string,
-): CallToolResult | null {
-  if (!requestInfo.agentId) return errorResult(SCRIPT_TRANSPORT_ERROR);
+): SwarmToolResult | null {
+  if (!requestInfo.agentId) return toolErr(SCRIPT_TRANSPORT_ERROR);
 
   const agent = getAgentById(requestInfo.agentId);
   const decision = can({
@@ -70,7 +72,7 @@ function requireScriptApiPermission(
     resource: { kind: "none" },
     source: "mcp",
   });
-  return decision.allow ? null : errorResult(message, 403);
+  return decision.allow ? null : toolErr(message, { data: { status: 403 } });
 }
 
 export const registerScriptApisTool = (server: McpServer) => {
@@ -92,8 +94,8 @@ export const registerScriptApisTool = (server: McpServer) => {
           requestInfo,
           successMessage: () => "",
         });
-        if (result.isError) return result;
-        const raw = (result.structuredContent as { data?: { apis?: RawEndpoint[] } })?.data;
+        if (!result.ok) return result;
+        const raw = (result.data as { data?: { apis?: RawEndpoint[] } } | undefined)?.data;
         let endpoints = (raw?.apis ?? []).map(maskToken);
 
         if (args.includeSecrets) {
@@ -113,8 +115,8 @@ export const registerScriptApisTool = (server: McpServer) => {
                 requestInfo,
                 successMessage: () => "",
               });
-              if (secretResult.isError) return endpoint;
-              const token = (secretResult.structuredContent as { data?: { token?: string | null } })
+              if (!secretResult.ok) return endpoint;
+              const token = (secretResult.data as { data?: { token?: string | null } } | undefined)
                 ?.data?.token;
               if (token) registerVolatileSecret(token, `script-api:${endpoint.id}`);
               return { ...endpoint, token: token ?? null };
@@ -122,10 +124,12 @@ export const registerScriptApisTool = (server: McpServer) => {
           );
         }
 
-        return {
-          content: [{ type: "text", text: `Found ${endpoints.length} endpoint(s).` }],
-          structuredContent: { success: true, status: 200, data: { apis: endpoints } },
-        };
+        return toolOk(`Found ${endpoints.length} endpoint(s).`, {
+          details: renderEndpointsList(endpoints),
+          data: { status: 200, data: { apis: endpoints } },
+          // Deliberate reveal path — includeSecrets returns real bearer tokens.
+          allowSecretEgress: args.includeSecrets === true,
+        });
       }
 
       if (args.action === "create") {
@@ -146,16 +150,23 @@ export const registerScriptApisTool = (server: McpServer) => {
           },
           requestInfo,
           successMessage: (data) => `Endpoint ${(data as ScriptApiWithSecret).id} created.`,
+          successDetails: (data) => {
+            const token = (data as ScriptApiWithSecret).token;
+            return token ? `Bearer token (shown once — save it now): ${token}` : undefined;
+          },
         });
-        if (!result.isError) {
-          const endpoint = (result.structuredContent as { data?: ScriptApiWithSecret })?.data;
+        if (result.ok) {
+          const endpoint = (result.data as { data?: ScriptApiWithSecret } | undefined)?.data;
           if (endpoint?.token) registerVolatileSecret(endpoint.token, `script-api:${endpoint.id}`);
+          // Deliberate one-time reveal — the volatile secret registered above
+          // would otherwise be redacted by the finalize scrubber.
+          return { ...result, allowSecretEgress: true };
         }
         return result;
       }
 
       if (args.action === "rotate") {
-        if (!args.endpointId) return errorResult("endpointId is required for rotate.");
+        if (!args.endpointId) return toolErr("endpointId is required for rotate.");
         const denied = requireScriptApiPermission(
           requestInfo,
           "script.api.rotate",
@@ -168,16 +179,23 @@ export const registerScriptApisTool = (server: McpServer) => {
           path: `/api/scripts/${args.scriptId}/apis/${args.endpointId}/rotate`,
           requestInfo,
           successMessage: () => "Token rotated.",
+          successDetails: (data) => {
+            const token = (data as ScriptApiWithSecret).token;
+            return token ? `New bearer token (shown once — save it now): ${token}` : undefined;
+          },
         });
-        if (!result.isError) {
-          const endpoint = (result.structuredContent as { data?: ScriptApiWithSecret })?.data;
+        if (result.ok) {
+          const endpoint = (result.data as { data?: ScriptApiWithSecret } | undefined)?.data;
           if (endpoint?.token) registerVolatileSecret(endpoint.token, `script-api:${endpoint.id}`);
+          // Deliberate one-time reveal — the volatile secret registered above
+          // would otherwise be redacted by the finalize scrubber.
+          return { ...result, allowSecretEgress: true };
         }
         return result;
       }
 
       if (args.action === "update") {
-        if (!args.endpointId) return errorResult("endpointId is required for update.");
+        if (!args.endpointId) return toolErr("endpointId is required for update.");
         const denied = requireScriptApiPermission(
           requestInfo,
           "script.api.update",
@@ -195,7 +213,7 @@ export const registerScriptApisTool = (server: McpServer) => {
       }
 
       if (args.action === "delete") {
-        if (!args.endpointId) return errorResult("endpointId is required for delete.");
+        if (!args.endpointId) return toolErr("endpointId is required for delete.");
         const denied = requireScriptApiPermission(
           requestInfo,
           "script.api.delete",
@@ -211,7 +229,7 @@ export const registerScriptApisTool = (server: McpServer) => {
         });
       }
 
-      return errorResult(`Unknown action: ${args.action}`);
+      return toolErr(`Unknown action: ${args.action}`);
     },
   );
 };

package/src/tools/script-common.ts

@@ -1,8 +1,13 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import * as z from "zod";
 import { getApiKey } from "@/utils/api-key";
 import { getMcpBaseUrl } from "@/utils/constants";
-import type { RequestInfo } from "./utils";
+import {
+  type RequestInfo,
+  type SwarmToolResult,
+  swarmToolOutputSchema,
+  toolErr,
+  toolOk,
+} from "./utils";
 
 export const SCRIPT_TRANSPORT_ERROR =
   "script_* tools require HTTP MCP transport — agent identity is not available over stdio in this build. Switch to MCP_BASE_URL=http://... or invoke the HTTP API directly.";
@@ -11,29 +16,108 @@ export const scriptNameSchema = z.string().min(1).max(200);
 export const scriptScopeSchema = z.enum(["agent", "global"]);
 export const scriptFsModeSchema = z.enum(["none", "workspace-rw"]);
 
-export const scriptToolOutputSchema = z.object({
-  success: z.boolean(),
-  status: z.number(),
+export const scriptToolOutputSchema = swarmToolOutputSchema({
+  status: z.number().optional(),
   data: z.unknown().optional(),
-  error: z.string().optional(),
 });
 
-export type ScriptToolStructuredContent = z.infer<typeof scriptToolOutputSchema>;
+const DETAILS_CAP = 16_000;
+
+function stripAnsi(text: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping terminal color codes
+  return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+export function capDetails(text: string | undefined): string | undefined {
+  if (!text) return undefined;
+  if (text.length <= DETAILS_CAP) return text;
+  return `${text.slice(0, DETAILS_CAP)}\n… [truncated ${text.length - DETAILS_CAP} chars]`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
 function apiBaseUrl(): string {
   return getMcpBaseUrl();
 }
 
-function toolError(message: string, status = 400): CallToolResult {
-  return {
-    isError: true,
-    content: [{ type: "text", text: message }],
-    structuredContent: {
-      success: false,
-      status,
-      error: message,
-    } satisfies ScriptToolStructuredContent,
-  };
+type ScriptFailure = { message: string; details?: string };
+
+/**
+ * Honest failure detection for the scripts API. The API returns HTTP 200 for
+ * script runs that failed at runtime (error / runtimeError / exitCode live in
+ * the body) and durable runs carry `run.status` / `run.error` — trusting
+ * `res.ok` alone reports failures as successes.
+ */
+function describeScriptFailure(
+  resOk: boolean,
+  status: number,
+  data: unknown,
+): ScriptFailure | undefined {
+  const body = isRecord(data) ? data : undefined;
+
+  if (!resOk) {
+    const error = body && "error" in body ? String(body.error) : undefined;
+
+    // Typecheck rejection: fold real diagnostics instead of the literal "typecheck_failed".
+    const diagnostics =
+      body && Array.isArray(body.diagnostics)
+        ? (body.diagnostics as unknown[]).map((d) => stripAnsi(String(d)))
+        : undefined;
+    if (error === "typecheck_failed" && diagnostics && diagnostics.length > 0) {
+      const more = diagnostics.length > 1 ? ` (+${diagnostics.length - 1} more)` : "";
+      const firstLine = diagnostics[0]?.split("\n")[0] ?? "unknown diagnostic";
+      return {
+        message: `Typecheck failed: ${firstLine}${more}`,
+        details: capDetails(diagnostics.join("\n\n")),
+      };
+    }
+
+    // Label-lint / policy rejections: fold violation detail.
+    const violations =
+      body && Array.isArray(body.violations) ? (body.violations as unknown[]) : undefined;
+    if (violations && violations.length > 0) {
+      return {
+        message: `${error ?? `Scripts API request failed with ${status}`} — ${violations.length} violation(s)`,
+        details: capDetails(
+          violations.map((v) => (typeof v === "string" ? v : JSON.stringify(v))).join("\n"),
+        ),
+      };
+    }
+
+    return { message: error ?? `Scripts API request failed with ${status}` };
+  }
+
+  // HTTP 200 inline-run body: failure signalled inside the payload.
+  if (body && ("exitCode" in body || "runtimeError" in body || "stderr" in body)) {
+    const runtimeError = isRecord(body.runtimeError)
+      ? `${String(body.runtimeError.name ?? "Error")}: ${String(body.runtimeError.message ?? "")}`
+      : undefined;
+    const error = typeof body.error === "string" && body.error ? body.error : undefined;
+    const exitCode = typeof body.exitCode === "number" ? body.exitCode : 0;
+    if (error || runtimeError || exitCode !== 0) {
+      const reason =
+        [error, runtimeError].filter(Boolean).join(" — ") || `script exited with code ${exitCode}`;
+      const stderr =
+        typeof body.stderr === "string" && body.stderr.trim() ? body.stderr.trim() : undefined;
+      return {
+        message: `Script run failed: ${reason}`,
+        details: capDetails(stderr ? `stderr:\n${stderr}` : undefined),
+      };
+    }
+  }
+
+  // Durable run body: { run: { status, error, ... } }.
+  if (body && isRecord(body.run) && body.run.status === "failed") {
+    const runError =
+      typeof body.run.error === "string" && body.run.error ? body.run.error : "unknown error";
+    return {
+      message: `Script run ${String(body.run.id ?? "")} failed: ${runError}`.replace("  ", " "),
+    };
+  }
+
+  return undefined;
 }
 
 export async function proxyScriptsApi(args: {
@@ -42,8 +126,22 @@ export async function proxyScriptsApi(args: {
   body?: unknown;
   requestInfo: RequestInfo;
   successMessage: (data: unknown) => string;
-}): Promise<CallToolResult> {
-  if (!args.requestInfo.agentId) return toolError(SCRIPT_TRANSPORT_ERROR);
+  /** Optional model-facing rendering of the success payload (appended to the text channel). */
+  successDetails?: (data: unknown) => string | undefined;
+  /**
+   * Optional model-facing rendering of the payload when the call fails, used
+   * when the failure itself carries no details (e.g. a failed durable run whose
+   * journal holds the step errors).
+   */
+  failureDetails?: (data: unknown) => string | undefined;
+  /**
+   * Skip the generic details cap. Only for payloads that are authoritative in
+   * full (e.g. script-query-types' type blobs, which exceed the cap and have
+   * no pagination) — everything else stays capped.
+   */
+  uncappedDetails?: boolean;
+}): Promise<SwarmToolResult> {
+  if (!args.requestInfo.agentId) return toolErr(SCRIPT_TRANSPORT_ERROR);
 
   const apiKey = getApiKey();
   const headers: Record<string, string> = {
@@ -70,21 +168,18 @@ export async function proxyScriptsApi(args: {
     }
   }
 
-  const error =
-    typeof data === "object" && data !== null && "error" in data
-      ? String((data as { error: unknown }).error)
-      : undefined;
-
-  if (!res.ok) {
-    return toolError(error ?? `Scripts API request failed with ${res.status}`, res.status);
+  const toolData = { status: res.status, data };
+  const failure = describeScriptFailure(res.ok, res.status, data);
+  if (failure) {
+    return toolErr(failure.message, {
+      details: failure.details ?? capDetails(args.failureDetails?.(data)),
+      data: toolData,
+    });
   }
 
-  return {
-    content: [{ type: "text", text: args.successMessage(data) }],
-    structuredContent: {
-      success: true,
-      status: res.status,
-      data,
-    } satisfies ScriptToolStructuredContent,
-  };
+  const successDetails = args.successDetails?.(data);
+  return toolOk(args.successMessage(data), {
+    details: args.uncappedDetails ? successDetails : capDetails(successDetails),
+    data: toolData,
+  });
 }