@desplega.ai/agent-swarm 1.149.1 → 1.151.0

package/src/tools/defer-task.ts

@@ -9,6 +9,7 @@ import {
   getAgentById,
   getDbClient,
   getTaskById,
+  getUserById,
   updateAgentStatusFromCapacity,
 } from "@/be/db";
 import { reconcileDeferredTaskWaits } from "@/scheduler/deferred-task-waits";
@@ -17,6 +18,7 @@ import { getTaskOutputValidationError } from "@/tasks/terminal-result-guard";
 import { assertOwnsTask, ownerCtx } from "@/tools/task-tool-ctx";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import { isTerminalTaskStatus } from "@/types";
+import { getAppUrl } from "@/utils/constants";
 
 /** Thrown inside the transaction to abort and roll back the schedule INSERT. */
 class DeferAbortedError extends Error {}
@@ -27,6 +29,109 @@ function renderChecks(checks?: string[]): string {
   return `\n\nChecks:\n${checks.map((c) => `- ${c}`).join("\n")}`;
 }
 
+/** Date/time parts of `date` as rendered in IANA zone `tz`. */
+function partsInTz(date: Date, tz: string) {
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+  });
+  const parts = Object.fromEntries(fmt.formatToParts(date).map((p) => [p.type, p.value]));
+  // Some locales render midnight as "24" under hour12: false.
+  const hour = parts.hour === "24" ? "00" : parts.hour;
+  return {
+    year: parts.year!,
+    month: parts.month!,
+    day: parts.day!,
+    hour: hour!,
+    minute: parts.minute!,
+    second: parts.second!,
+  };
+}
+
+/**
+ * "today"/"tomorrow" or "MM-dd" plus "HH:MM:ss", both computed in `tz`.
+ * Falls back to UTC (parts still computed correctly) if `tz` is not a valid
+ * IANA zone — the caller decides whether to label the fallback.
+ */
+function formatDeferralDateTime(
+  target: Date,
+  now: Date,
+  tz: string,
+): { date: string; time: string } {
+  let zone = tz;
+  try {
+    Intl.DateTimeFormat("en-US", { timeZone: zone });
+  } catch {
+    zone = "UTC";
+  }
+  const t = partsInTz(target, zone);
+  const time = `${t.hour}:${t.minute}:${t.second}`;
+  const n = partsInTz(now, zone);
+  if (t.year === n.year && t.month === n.month && t.day === n.day) return { date: "today", time };
+  const tm = partsInTz(new Date(now.getTime() + 86_400_000), zone);
+  if (t.year === tm.year && t.month === tm.month && t.day === tm.day) {
+    return { date: "tomorrow", time };
+  }
+  return { date: `${t.month}-${t.day}`, time };
+}
+
+/**
+ * Resolve the requesting human's IANA timezone from `users.timezone` via
+ * `task.requestedByUserId`. We do not currently capture a Slack profile `tz`
+ * anywhere in the ingest path (checked `src/slack/enrich.ts`, the only place
+ * that reads `users.info`) — a user only has a timezone here if someone set
+ * it explicitly via `manage-user`. Falls back to UTC, flagged as such.
+ */
+async function resolveRequesterTimezone(
+  requestedByUserId: string | undefined,
+): Promise<{ tz: string; isFallback: boolean }> {
+  if (requestedByUserId) {
+    const user = await getUserById(requestedByUserId);
+    if (user?.timezone) return { tz: user.timezone, isFallback: false };
+  }
+  return { tz: "UTC", isFallback: true };
+}
+
+/** First line of `note`, `Pending:` prefix stripped, capped to ~100 chars. */
+function renderShortDesc(note: string, max = 100): string {
+  const firstLine = (note.split("\n")[0] ?? "").trim().replace(/^pending:\s*/i, "");
+  if (firstLine.length <= max) return firstLine;
+  return `${firstLine.slice(0, max - 1).trimEnd()}…`;
+}
+
+/**
+ * Human-facing deferral text for tasks without an outputSchema — this is what
+ * lands verbatim in a human's Slack thread as the task's terminal output.
+ * One line: `Deferred until {date} {time} ([shortId](url)) -> {short desc}`.
+ * No ISO timestamp, no bare UUID, no checks list, no `Pending:` prefix —
+ * those stay in the task log. The `[text](url)` link is plain GFM markdown:
+ * `markdownToSlack` (src/slack/blocks.ts) already down-converts it to a
+ * readable `text (url)` fallback for Slack, and it reads fine verbatim in
+ * the non-Slack task-output row / UI too.
+ */
+function renderHumanFacingDeferral(
+  note: string,
+  nextRunAt: string,
+  scheduleId: string,
+  tz: string,
+  isFallbackTz: boolean,
+): string {
+  const now = new Date();
+  const target = new Date(nextRunAt);
+  const { date, time } = formatDeferralDateTime(target, now, tz);
+  const timeLabel = isFallbackTz ? `${time} UTC` : time;
+  const shortId = scheduleId.slice(0, 8);
+  const link = `[${shortId}](${getAppUrl()}/schedules/${scheduleId})`;
+  const shortDesc = renderShortDesc(note);
+  return `Deferred until ${date} ${timeLabel} (${link}) -> ${shortDesc}`;
+}
+
 export const registerDeferTaskTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "defer-task",
@@ -34,7 +139,7 @@ export const registerDeferTaskTool = (server: McpServer) => {
       title: "Defer Task",
       annotations: { destructiveHint: false, idempotentHint: false },
       description:
-        "Completes this task now with status `completed` and books a wake-up for you. Use when the result needs time: a build, a deploy, a reply. The task reaches its final state on this call; the lead sees your summary as its output unless the task has an outputSchema. For a task with an outputSchema, provide output as a JSON string matching that schema; it is stored verbatim as terminal output, while deferral details remain visible in the task log. A one-off schedule wakes you up later with a child task that carries this task as its parent. Optionally provide wakeOn to wake early when another task completes or fails; delayMs or runAt remains required as the ceiling. Provide delayMs or runAt, a summary of what you did, and a note that says what is pending and what to check.",
+        "Completes this task now with status `completed` and books a wake-up for you. Use when the result needs time: a build, a deploy, a reply. The task reaches its final state on this call; the lead sees your summary as its output unless the task has an outputSchema. For a task with an outputSchema, provide output as a JSON string matching that schema; it is stored verbatim as terminal output, while deferral details remain visible in the task log. A one-off schedule wakes you up later with a child task that carries this task as its parent. Optionally provide wakeOn with taskId or taskIds to wake early on task outcomes; mode defaults to all, or use any for the first match. delayMs or runAt remains required as the ceiling for the whole set. Provide delayMs or runAt, a summary of what you did, and a note that says what is pending and what to check.",
       inputSchema: z.object({
         taskId: z.string().describe("The ID of the task you are working on."),
         delayMs: z
@@ -51,12 +156,20 @@ export const registerDeferTaskTool = (server: McpServer) => {
         wakeOn: z
           .object({
             event: z.enum(["task.completed", "task.failed", "settled"]),
-            taskId: z.string().min(1),
+            taskId: z.string().min(1).optional(),
+            taskIds: z.array(z.string().min(1)).min(1).optional(),
+            mode: z.enum(["all", "any"]).optional(),
           })
           .strict()
+          .refine((wake) => (wake.taskId !== undefined) !== (wake.taskIds !== undefined), {
+            message: "Provide exactly one of wakeOn.taskId or wakeOn.taskIds.",
+          })
+          .refine((wake) => !wake.taskIds || new Set(wake.taskIds).size === wake.taskIds.length, {
+            message: "wakeOn.taskIds must not contain duplicates.",
+          })
           .optional()
           .describe(
-            "Wake early on this task event. settled covers completed or failed. Already-terminal tasks are rejected; a delayMs/runAt ceiling is still required.",
+            "Wake early on a task event. Provide taskId or nonempty, unique taskIds. mode defaults to all (every member must match); any wakes on the first match. settled covers completed, failed, or cancelled. Deferred and superseded members follow their continuations; a superseded member without a resume child holds to the ceiling. Any already-terminal member rejects the request; one delayMs/runAt ceiling is still required for the whole set.",
           ),
         summary: z
           .string()
@@ -144,8 +257,10 @@ export const registerDeferTaskTool = (server: McpServer) => {
       }
       const nextRunAt = delayMs ? new Date(Date.now() + delayMs).toISOString() : runAt!;
 
+      const watchedTaskIds = wakeOn?.taskIds ?? (wakeOn?.taskId ? [wakeOn.taskId] : []);
+      const wakeMode = wakeOn?.mode ?? "all";
       const wakeDescription = wakeOn
-        ? `on ${wakeOn.event} for task ${wakeOn.taskId}, or by ${nextRunAt}`
+        ? `on ${wakeOn.event} for ${wakeMode} of tasks ${watchedTaskIds.join(", ")}, or by ${nextRunAt}`
         : `at ${nextRunAt}`;
       const checksBlock = renderChecks(checks);
       const taskTemplate = `Resume task ${taskId}: ${note}${checksBlock}`;
@@ -163,16 +278,20 @@ export const registerDeferTaskTool = (server: McpServer) => {
         if (outputValidationError) return toolErr(outputValidationError);
       }
 
+      const { tz: requesterTz, isFallback: isFallbackTz } = await resolveRequesterTimezone(
+        task.requestedByUserId,
+      );
+
       try {
         const committed = await getDbClient().transaction(async () => {
-          if (wakeOn) {
-            if (wakeOn.taskId === taskId)
+          for (const watchedId of watchedTaskIds) {
+            if (watchedId === taskId)
               throw new DeferAbortedError("Cannot wake on the task being deferred.");
-            const watched = await getTaskById(wakeOn.taskId);
-            if (!watched) throw new DeferAbortedError(`Watched task ${wakeOn.taskId} not found.`);
+            const watched = await getTaskById(watchedId);
+            if (!watched) throw new DeferAbortedError(`Watched task ${watchedId} not found.`);
             if (isTerminalTaskStatus(watched.status))
               throw new DeferAbortedError(
-                `Watched task ${wakeOn.taskId} is already ${watched.status}; read its result instead of deferring.`,
+                `Watched task ${watchedId} is already ${watched.status}; read its result instead of deferring.`,
               );
           }
           const schedule = await createScheduledTask({
@@ -200,20 +319,35 @@ export const registerDeferTaskTool = (server: McpServer) => {
 
           if (wakeOn) {
             await getDbClient().run(
-              "INSERT INTO deferred_task_waits (scheduleId, taskId, eventName, created_by, updated_by) VALUES (?, ?, ?, ?, ?)",
-              [schedule.id, wakeOn.taskId, wakeOn.event, createdBy ?? null, createdBy ?? null],
+              "INSERT INTO deferred_task_waits (scheduleId, eventName, mode, created_by, updated_by) VALUES (?, ?, ?, ?, ?)",
+              [schedule.id, wakeOn.event, wakeMode, createdBy ?? null, createdBy ?? null],
             );
+            for (const watchedId of watchedTaskIds) {
+              await getDbClient().run(
+                "INSERT INTO deferred_task_wait_members (scheduleId, taskId, created_by, updated_by) VALUES (?, ?, ?, ?)",
+                [schedule.id, watchedId, createdBy ?? null, createdBy ?? null],
+              );
+            }
             getDbClient().afterCommit(() => {
-              void reconcileDeferredTaskWaits(wakeOn.taskId).catch((err) => {
-                console.error("[defer-task] Event wake reconciliation failed:", err);
-              });
+              void Promise.all(watchedTaskIds.map((id) => reconcileDeferredTaskWaits(id))).catch(
+                (err) => {
+                  console.error("[defer-task] Event wake reconciliation failed:", err);
+                },
+              );
             });
           }
 
+          // Full detail for the task log — ISO timestamp, schedule id, checks.
+          // Never shown to a human directly; the wake-up task gets note+checks
+          // through taskTemplate instead.
           const deferralDetails = `${summary}\n\nDeferred until ${nextRunAt} (schedule ${schedule.id}). Pending: ${note}${checksBlock}`;
 
-          const terminalOutput = task.outputSchema ? output! : deferralDetails;
-          const completed = await completeTask(taskId, terminalOutput);
+          const terminalOutput = task.outputSchema
+            ? output!
+            : renderHumanFacingDeferral(note, nextRunAt, schedule.id, requesterTz, isFallbackTz);
+          const completed = await completeTask(taskId, terminalOutput, {
+            addTags: ["deferred"],
+          });
           if (!completed) {
             // Another writer terminally completed/failed/cancelled this task
             // between our early check and this transaction's write. Abort:
@@ -225,14 +359,12 @@ export const registerDeferTaskTool = (server: McpServer) => {
             );
           }
 
-          if (task.outputSchema) {
-            await createLogEntry({
-              eventType: "task_progress",
-              taskId,
-              agentId: requestInfo.agentId,
-              newValue: deferralDetails,
-            });
-          }
+          await createLogEntry({
+            eventType: "task_progress",
+            taskId,
+            agentId: requestInfo.agentId,
+            newValue: deferralDetails,
+          });
 
           // afterCommit: the transaction can still roll back; business-use must
           // not be told the task completed for a write that never landed.

package/src/tools/extension-common.ts

@@ -0,0 +1,84 @@
+import * as z from "zod";
+import { proxySwarmApi } from "./script-common";
+import { type RequestInfo, type SwarmToolResult, swarmToolOutputSchema, toolErr } from "./utils";
+
+export const EXTENSION_TRANSPORT_ERROR =
+  "extension_* tools require HTTP MCP transport because agent identity is unavailable over stdio. Use MCP_BASE_URL=http://... or invoke the HTTP API directly.";
+
+const extensionListItemSchema = z.looseObject({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  version: z.number().optional(),
+  activeVersion: z.number().optional(),
+  enabled: z.boolean().optional(),
+  status: z.string().optional(),
+  priority: z.number().optional(),
+  consecutiveFailures: z.number().optional(),
+});
+
+export const extensionToolOutputSchema = swarmToolOutputSchema({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  version: z.number().optional(),
+  activeVersion: z.number().optional(),
+  enabled: z.boolean().optional(),
+  status: z.string().optional(),
+  priority: z.number().optional(),
+  consecutiveFailures: z.number().optional(),
+  contentDeduped: z.boolean().optional(),
+  extensions: z.array(extensionListItemSchema).optional(),
+});
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function coerceExtensionSummary(entry: unknown) {
+  const extension = isRecord(entry) ? entry : {};
+  return {
+    id: typeof extension.id === "string" ? extension.id : undefined,
+    name: typeof extension.name === "string" ? extension.name : undefined,
+    version: typeof extension.version === "number" ? extension.version : undefined,
+    activeVersion:
+      typeof extension.activeVersion === "number" ? extension.activeVersion : undefined,
+    enabled: typeof extension.enabled === "boolean" ? extension.enabled : undefined,
+    status: typeof extension.status === "string" ? extension.status : undefined,
+    priority: typeof extension.priority === "number" ? extension.priority : undefined,
+    consecutiveFailures:
+      typeof extension.consecutiveFailures === "number" ? extension.consecutiveFailures : undefined,
+  };
+}
+
+function errorMessage(data: unknown, status: number): string {
+  if (isRecord(data) && typeof data.error === "string" && data.error) return data.error;
+  return `Extensions API request failed with ${status}`;
+}
+
+function renderDiagnostics(data: unknown): string | undefined {
+  if (!isRecord(data) || !Array.isArray(data.diagnostics)) return undefined;
+  const diagnostics = data.diagnostics.map(String).filter(Boolean);
+  return diagnostics.length > 0 ? diagnostics.join("\n") : undefined;
+}
+
+export async function proxyExtensionsApi<T>(args: {
+  method: "GET" | "POST";
+  path: string;
+  body?: unknown;
+  requestInfo: RequestInfo;
+  success: (data: unknown) => SwarmToolResult<T & Record<string, unknown>>;
+}): Promise<SwarmToolResult<T & Record<string, unknown>>> {
+  return proxySwarmApi({
+    ...args,
+    transportError: EXTENSION_TRANSPORT_ERROR,
+    respond: (data, response) => {
+      if (!response.ok) {
+        const diagnostics = renderDiagnostics(data);
+        if (response.status === 400 && diagnostics) {
+          return toolErr("Extension rejected by typecheck.", { details: diagnostics });
+        }
+        return toolErr(errorMessage(data, response.status), { details: diagnostics });
+      }
+      return args.success(data);
+    },
+  });
+}

package/src/tools/extension-install.ts

@@ -0,0 +1,65 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import { ExtensionManifestSchema } from "@/types";
+import {
+  coerceExtensionSummary,
+  extensionToolOutputSchema,
+  proxyExtensionsApi,
+} from "./extension-common";
+
+export const EXTENSION_INSTALL_DESCRIPTION =
+  "Validate and store a TypeScript extension bundle (manifest plus a files map with one hooks.ts). Fetch the hook contract first: GET /api/extensions/type-defs returns swarm-extension.d.ts with every event and modify shape. The extension remains disabled until an operator enables it.";
+
+function extensionInstallResult(data: unknown, fallbackName: string) {
+  const body = data as {
+    extension?: unknown;
+    contentDeduped?: unknown;
+  };
+  const extension = coerceExtensionSummary(body.extension);
+  const name = extension.name ?? fallbackName;
+  const version = typeof extension.version === "number" ? ` v${extension.version}` : "";
+  const deduped = body.contentDeduped === true ? " Content was unchanged." : "";
+  const enableInstruction =
+    "An operator must enable it from the dashboard or `POST /api/extensions/{id}/enable`.";
+
+  return toolOk(`Extension \`${name}\`${version} installed.${deduped} ${enableInstruction}`, {
+    data: {
+      ...extension,
+      name,
+      contentDeduped: body.contentDeduped === true,
+    },
+  });
+}
+
+export const registerExtensionInstallTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-install",
+    {
+      title: "Extension Install",
+      description: EXTENSION_INSTALL_DESCRIPTION,
+      annotations: { openWorldHint: false },
+      inputSchema: z
+        .object({
+          manifest: ExtensionManifestSchema.describe("Extension bundle manifest."),
+          files: z.record(z.string(), z.string()).describe("Bundle files keyed by relative path."),
+          priority: z
+            .number()
+            .int()
+            .optional()
+            .describe("Handler priority. Lower values run first."),
+          config: z.record(z.string(), z.unknown()).optional().describe("Extension configuration."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyExtensionsApi({
+        method: "POST",
+        path: "/api/extensions/install",
+        body: args,
+        requestInfo,
+        success: (data) => extensionInstallResult(data, args.manifest.name),
+      }),
+  );
+};

package/src/tools/extension-list.ts

@@ -0,0 +1,66 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import {
+  coerceExtensionSummary,
+  extensionToolOutputSchema,
+  proxyExtensionsApi,
+} from "./extension-common";
+
+export const EXTENSION_LIST_DESCRIPTION =
+  "List installed extensions and their activation state. To write a new one, fetch GET /api/extensions/type-defs for the hook contract and install it with extension-install.";
+
+type ExtensionListItem = ReturnType<typeof coerceExtensionSummary>;
+
+function extensionListItems(data: unknown): ExtensionListItem[] {
+  if (
+    typeof data !== "object" ||
+    data === null ||
+    !Array.isArray((data as { extensions?: unknown }).extensions)
+  ) {
+    return [];
+  }
+  return (data as { extensions: unknown[] }).extensions.map(coerceExtensionSummary);
+}
+
+function renderExtensionsTable(extensions: ExtensionListItem[]): string {
+  const header = "| Name | Version | Active | Enabled | Status | Priority | Failures |";
+  const divider = "| --- | ---: | ---: | --- | --- | ---: | ---: |";
+  const rows = extensions.map(
+    (extension) =>
+      `| ${extension.name ?? "?"} | ${extension.version ?? "?"} | ${extension.activeVersion ?? "?"} | ${extension.enabled ?? false} | ${extension.status ?? "unknown"} | ${extension.priority ?? "?"} | ${extension.consecutiveFailures ?? 0} |`,
+  );
+  return [header, divider, ...rows].join("\n");
+}
+
+export const registerExtensionListTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-list",
+    {
+      title: "Extension List",
+      description: EXTENSION_LIST_DESCRIPTION,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      inputSchema: z
+        .object({
+          enabledOnly: z.boolean().optional().describe("Return only enabled extensions."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async ({ enabledOnly }, requestInfo) =>
+      proxyExtensionsApi({
+        method: "GET",
+        path: "/api/extensions",
+        requestInfo,
+        success: (data) => {
+          const extensions = extensionListItems(data).filter(
+            (extension) => !enabledOnly || extension.enabled,
+          );
+          return toolOk(`Found ${extensions.length} extension(s).`, {
+            details: renderExtensionsTable(extensions),
+            data: { extensions },
+          });
+        },
+      }),
+  );
+};

package/src/tools/script-common.ts

@@ -3,6 +3,7 @@ import { getApiKey } from "@/utils/api-key";
 import { getMcpBaseUrl } from "@/utils/constants";
 import {
   type RequestInfo,
+  type SwarmToolData,
   type SwarmToolResult,
   swarmToolOutputSchema,
   toolErr,
@@ -161,7 +162,37 @@ export async function proxyScriptsApi(args: {
    */
   uncappedDetails?: boolean;
 }): Promise<SwarmToolResult> {
-  if (!args.requestInfo.agentId) return toolErr(SCRIPT_TRANSPORT_ERROR);
+  return proxySwarmApi({
+    ...args,
+    transportError: SCRIPT_TRANSPORT_ERROR,
+    respond: (data, res) => {
+      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,
+        });
+      }
+
+      const successDetails = args.successDetails?.(data);
+      return toolOk(args.successMessage(data), {
+        details: args.uncappedDetails ? successDetails : capDetails(successDetails),
+        data: toolData,
+      });
+    },
+  });
+}
+
+export async function proxySwarmApi<T extends Record<string, unknown>>(args: {
+  method: "GET" | "POST" | "PATCH" | "DELETE";
+  path: string;
+  body?: unknown;
+  requestInfo: RequestInfo;
+  transportError: string;
+  respond: (data: unknown, response: { ok: boolean; status: number }) => SwarmToolResult<T>;
+}): Promise<SwarmToolResult<T>> {
+  if (!args.requestInfo.agentId) return toolErr(args.transportError);
 
   const apiKey = getApiKey();
   const headers: Record<string, string> = {
@@ -172,8 +203,7 @@ export async function proxyScriptsApi(args: {
   if (args.requestInfo.sourceTaskId) {
     headers["X-Source-Task-Id"] = args.requestInfo.sourceTaskId;
   }
-  // Runtime identity is process context from the worker's MCP session — it
-  // rides the proxy like the agent identity, never as tool or script input.
+  // Forward runtime identity from the worker's MCP session, like agent identity.
   if (args.requestInfo.runtimeInstanceId) {
     headers["X-Runtime-Instance-ID"] = args.requestInfo.runtimeInstanceId;
   }
@@ -189,22 +219,17 @@ export async function proxyScriptsApi(args: {
     try {
       data = JSON.parse(text);
     } catch {
-      data = { error: text };
+      const contentType = res.headers.get("content-type") ?? "unknown";
+      // Transport-level failure: only `{ status }` is known here, and that shape
+      // is not statically related to the caller's `T`. Tool output schemas are
+      // loose with every data field optional, so the wire result stays valid.
+      const transportData: SwarmToolData = { status: res.status };
+      return toolErr<T>(
+        `Swarm API returned non-JSON response (HTTP ${res.status}, Content-Type: ${contentType}). Check API/proxy routing.`,
+        { details: capDetails(text), data: transportData as T },
+      );
     }
   }
 
-  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,
-    });
-  }
-
-  const successDetails = args.successDetails?.(data);
-  return toolOk(args.successMessage(data), {
-    details: args.uncappedDetails ? successDetails : capDetails(successDetails),
-    data: toolData,
-  });
+  return args.respond(data, res);
 }