@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/src/http/route-def.ts

@@ -10,12 +10,26 @@ type HttpMethod = "get" | "post" | "put" | "delete" | "patch";
 interface RouteResponseDef {
   description: string;
   schema?: z.ZodType;
+  /**
+   * Reason this response intentionally carries no JSON schema — SSE stream,
+   * binary download, HTML, redirect, proxied upstream body, intentionally
+   * dynamic shape, etc. Mutually exclusive with `schema`. Every 2xx response
+   * (except bodiless 204/205/304) must declare one of the two — enforced by
+   * `bun run check:openapi-response-coverage` (CI).
+   */
+  unstructured?: string;
 }
 
+type ResponsesDef = Record<number, RouteResponseDef>;
+
+/** Extracts the payload type respond() accepts for one response def. */
+type ResponseData<R> = R extends { schema: infer S extends z.ZodType } ? z.input<S> : never;
+
 export interface RouteDef<
   TParams extends z.ZodType = z.ZodType,
   TQuery extends z.ZodType = z.ZodType,
   TBody extends z.ZodType = z.ZodType,
+  TResponses extends ResponsesDef = ResponsesDef,
 > {
   method: HttpMethod;
   path: string; // OpenAPI-style: "/api/tasks/{id}"
@@ -28,7 +42,7 @@ export interface RouteDef<
   params?: TParams;
   query?: TQuery;
   body?: TBody;
-  responses: Record<number, RouteResponseDef>;
+  responses: TResponses;
   auth?: {
     apiKey?: boolean; // default true
     agentId?: boolean; // requires X-Agent-ID
@@ -49,7 +63,7 @@ interface ParsedRequest<TParams, TQuery, TBody> {
   body: TBody;
 }
 
-interface RouteHandle<TParams, TQuery, TBody> {
+interface RouteHandle<TParams, TQuery, TBody, TResponses extends ResponsesDef = ResponsesDef> {
   /** Check if this route matches the request */
   match(method: string | undefined, pathSegments: string[]): boolean;
 
@@ -61,6 +75,24 @@ interface RouteHandle<TParams, TQuery, TBody> {
     queryParams: URLSearchParams,
   ): Promise<ParsedRequest<TParams, TQuery, TBody> | null>;
 
+  /**
+   * Typed JSON egress: send `data` as the response body for `code`, with `data`
+   * compile-time checked against the `schema` declared for that code — the
+   * declared OpenAPI shape and the wire shape cannot drift silently. Only
+   * callable for codes that declare a `schema`; keep `jsonError` for error
+   * paths and raw `res` for bodiless/unstructured responses.
+   *
+   * Outside production the payload is additionally runtime-validated against
+   * the schema (throws → 500 + test failure), catching mismatches the type
+   * system can't see through `any`-typed DB rows. Always sends the raw `data`
+   * object, never the parsed output — validation must not change the wire.
+   */
+  respond<C extends keyof TResponses & number>(
+    res: ServerResponse,
+    code: C,
+    data: ResponseData<TResponses[C]>,
+  ): void;
+
   /** The raw definition (for OpenAPI generation) */
   def: RouteDef;
 }
@@ -154,18 +186,49 @@ export function describeRequestRoute(
 
 // ─── Factory ─────────────────────────────────────────────────────────────────
 
+/**
+ * Runtime response validation gate for `respond()`. NODE_ENV is deliberately
+ * unset on prod deploys, so this is opt-in outside `bun test` (which sets
+ * NODE_ENV=test): response schemas must never introduce a production failure
+ * mode — they fail loudly in tests and (opt-in) local dev instead.
+ */
+const VALIDATE_RESPONSES =
+  process.env.NODE_ENV === "test" ||
+  process.env.NODE_ENV === "development" ||
+  process.env.VALIDATE_HTTP_RESPONSES === "true";
+
 export function route<
   TParams extends z.ZodType = z.ZodUndefined,
   TQuery extends z.ZodType = z.ZodUndefined,
   TBody extends z.ZodType = z.ZodUndefined,
+  TResponses extends ResponsesDef = ResponsesDef,
 >(
-  def: RouteDef<TParams, TQuery, TBody>,
-): RouteHandle<z.infer<TParams>, z.infer<TQuery>, z.infer<TBody>> {
+  def: RouteDef<TParams, TQuery, TBody, TResponses>,
+): RouteHandle<z.infer<TParams>, z.infer<TQuery>, z.infer<TBody>, TResponses> {
   routeRegistry.push(def as RouteDef);
 
   return {
     def: def as RouteDef,
 
+    respond(res, code, data) {
+      if (VALIDATE_RESPONSES) {
+        const schema = (def.responses as ResponsesDef)[code]?.schema;
+        if (schema) {
+          const result = schema.safeParse(data);
+          if (!result.success) {
+            throw new Error(
+              `Response schema violation: ${def.method.toUpperCase()} ${def.path} ${code} — ` +
+                result.error.issues
+                  .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+                  .join("; "),
+            );
+          }
+        }
+      }
+      res.writeHead(code, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(data));
+    },
+
     match(method, pathSegments) {
       return matchRoute(
         method,

package/src/http/schedules.ts

@@ -18,14 +18,16 @@ import { mergeScheduleTiming, validateRecurringTiming } from "../be/schedules/va
 import { getScript } from "../be/scripts/db";
 import { calculateNextRun, dispatchScheduleTarget } from "../scheduler/scheduler";
 import {
+  AgentTaskSchema,
   AssetKeySchema,
   ModelTierSchema,
+  ScheduledTaskSchema,
   ScheduledTaskTargetTypeSchema,
   splitLegacyModelAlias,
 } from "../types";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
@@ -51,6 +53,34 @@ const scheduleUpdateBodySchema = z.object({
   scriptArgs: z.record(z.string(), z.unknown()).nullable().optional(),
 });
 
+// `ScheduledTaskSchema` carries `.refine()` checks, so Zod v4 forbids the
+// plain `.extend()` / `.omit()` chain-builders here (they throw at call
+// time: "Object schemas containing refinements cannot be extended/omitted.
+// Use `.safeExtend()` instead."). Use `.safeExtend()` for additive shapes,
+// and build the taskTemplate-dropping summary shape from `.shape` directly.
+
+/** Full schedule row decorated with the caller's favorite flag (full-mode `listSchedules`). */
+const scheduleWithFavoriteSchema = ScheduledTaskSchema.safeExtend({ favorite: z.boolean() });
+
+/**
+ * `getSchedule` response: `favorite` is optional because the handler falls
+ * back to the undecorated row (`decorated ?? schedule`) if `withFavoriteFlags`
+ * ever returned an empty array — structurally unreachable for a 1-row input,
+ * but the schema stays honest about what the code could send.
+ */
+const scheduleWithOptionalFavoriteSchema = ScheduledTaskSchema.safeExtend({
+  favorite: z.boolean().optional(),
+});
+
+/** Slim list row — `taskTemplate` swapped for a bounded preview (see `ScheduledTaskSummary`). */
+const { taskTemplate: _omittedTaskTemplate, ...scheduleShapeWithoutTemplate } =
+  ScheduledTaskSchema.shape;
+const scheduleSummaryWithFavoriteSchema = z.object({
+  ...scheduleShapeWithoutTemplate,
+  taskTemplatePreview: z.string(),
+  favorite: z.boolean(),
+});
+
 const createSchedule = route({
   method: "post",
   path: "/api/schedules",
@@ -81,7 +111,7 @@ const createSchedule = route({
     runAt: z.string().optional(),
   }),
   responses: {
-    201: { description: "Schedule created" },
+    201: { description: "Schedule created", schema: ScheduledTaskSchema },
     400: { description: "Validation error" },
     409: { description: "Duplicate name" },
   },
@@ -95,7 +125,14 @@ const runScheduleNow = route({
   tags: ["Schedules"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Schedule run triggered" },
+    200: {
+      description: "Schedule run triggered",
+      schema: z.object({
+        schedule: ScheduledTaskSchema.nullable(),
+        workflowRunIds: z.array(z.string()).optional(),
+        task: AgentTaskSchema.optional(),
+      }),
+    },
     400: { description: "Schedule is disabled" },
     404: { description: "Schedule not found" },
   },
@@ -131,7 +168,16 @@ const listSchedules = route({
     keyPrefix: AssetKeySchema.optional(),
   }),
   responses: {
-    200: { description: "List of schedules" },
+    200: {
+      description: "List of schedules",
+      schema: z.object({
+        schedules: z.union([
+          z.array(scheduleSummaryWithFavoriteSchema),
+          z.array(scheduleWithFavoriteSchema),
+        ]),
+        count: z.number().int(),
+      }),
+    },
   },
 });
 
@@ -143,7 +189,7 @@ const getSchedule = route({
   tags: ["Schedules"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Schedule details" },
+    200: { description: "Schedule details", schema: scheduleWithOptionalFavoriteSchema },
     404: { description: "Schedule not found" },
   },
 });
@@ -157,7 +203,7 @@ const updateSchedule = route({
   params: z.object({ id: z.string() }),
   body: scheduleUpdateBodySchema,
   responses: {
-    200: { description: "Schedule updated" },
+    200: { description: "Schedule updated", schema: ScheduledTaskSchema.nullable() },
     400: { description: "Validation error" },
     404: { description: "Schedule not found" },
     409: { description: "Duplicate name" },
@@ -175,7 +221,7 @@ const patchSchedule = route({
   params: z.object({ id: z.string() }),
   body: scheduleUpdateBodySchema,
   responses: {
-    200: { description: "Schedule patched" },
+    200: { description: "Schedule patched", schema: ScheduledTaskSchema.nullable() },
     400: { description: "Validation error" },
     404: { description: "Schedule not found" },
     409: { description: "Duplicate name" },
@@ -194,7 +240,7 @@ const deleteSchedule = route({
   tags: ["Schedules"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Schedule deleted" },
+    200: { description: "Schedule deleted", schema: z.object({ success: z.literal(true) }) },
     404: { description: "Schedule not found" },
   },
 });
@@ -234,7 +280,10 @@ export async function handleSchedules(
       favoriteScope,
       itemType: "schedule",
     });
-    json(res, { schedules: decoratedSchedules, count: decoratedSchedules.length });
+    listSchedules.respond(res, 200, {
+      schedules: decoratedSchedules,
+      count: decoratedSchedules.length,
+    });
     return true;
   }
 
@@ -379,7 +428,7 @@ export async function handleSchedules(
         createdBy: resolveHttpAuditUserId(req, myAgentId) ?? undefined,
       });
 
-      json(res, schedule, 201);
+      createSchedule.respond(res, 201, schedule);
     } catch (_error) {
       jsonError(res, "Failed to create schedule", 500);
     }
@@ -420,7 +469,7 @@ export async function handleSchedules(
       }
 
       const updatedSchedule = getScheduledTaskById(parsed.params.id);
-      json(res, { schedule: updatedSchedule, workflowRunIds, task });
+      runScheduleNow.respond(res, 200, { schedule: updatedSchedule, workflowRunIds, task });
     } catch (error) {
       jsonError(res, error instanceof Error ? error.message : "Failed to run schedule", 500);
     }
@@ -439,7 +488,7 @@ export async function handleSchedules(
 
     const favoriteScope = resolveHttpFavoriteOwner(req, myAgentId)?.scope;
     const [decorated] = withFavoriteFlags([schedule], { favoriteScope, itemType: "schedule" });
-    json(res, decorated ?? schedule);
+    getSchedule.respond(res, 200, decorated ?? schedule);
     return true;
   }
 
@@ -601,7 +650,7 @@ export async function handleSchedules(
     const updatedBy = resolveHttpAuditUserId(req, myAgentId);
     if (updatedBy !== null) body.updatedBy = updatedBy;
     const schedule = updateScheduledTask(parsed.params.id, body);
-    json(res, schedule);
+    routeHandle.respond(res, 200, schedule);
     return true;
   }
 
@@ -615,7 +664,7 @@ export async function handleSchedules(
       return true;
     }
 
-    json(res, { success: true });
+    deleteSchedule.respond(res, 200, { success: true });
     return true;
   }
 

package/src/http/script-connection-proxy.ts

@@ -5,7 +5,30 @@ import { callMcpServerTool } from "@/be/mcp-proxy";
 import { getScriptConnectionById } from "@/be/script-connections";
 import { can } from "@/rbac";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
+
+// Mirrors `McpToolCallResult` from `src/mcp-client/http-client.ts`.
+const McpToolCallResultSchema = z.object({
+  content: z.array(z.object({ type: z.string(), text: z.string().optional() })),
+  isError: z.boolean().optional(),
+});
+
+// Mirrors `McpJsonRpcError` from `src/mcp-client/http-client.ts`.
+const McpJsonRpcErrorSchema = z.object({
+  code: z.number().optional(),
+  message: z.string().optional(),
+  data: z.unknown().optional(),
+});
+
+// Mirrors `McpToolCallEnvelope` from `src/mcp-client/http-client.ts` — the
+// success/failure envelope returned by `callMcpServerTool`, plus the
+// `{ ok: false, error: string }` shape the catch block below constructs
+// directly (a subtype of the `ok: false` branch, since `error` accepts a
+// plain string there too).
+const McpToolCallEnvelopeSchema = z.union([
+  z.object({ ok: z.literal(true), result: McpToolCallResultSchema }),
+  z.object({ ok: z.literal(false), error: z.union([McpJsonRpcErrorSchema, z.string()]) }),
+]);
 
 const mcpCallRoute = route({
   method: "post",
@@ -21,7 +44,7 @@ const mcpCallRoute = route({
     arguments: z.record(z.string(), z.unknown()).optional(),
   }),
   responses: {
-    200: { description: "MCP call result" },
+    200: { description: "MCP call result", schema: McpToolCallEnvelopeSchema },
     400: { description: "Invalid MCP connection or request" },
     403: { description: "Not allowed to invoke this MCP connection" },
     404: { description: "Script connection or agent not found" },
@@ -108,9 +131,12 @@ export async function handleScriptConnectionProxy(
       parsed.body.arguments ?? {},
       { agentId, timeoutMs: 30_000 },
     );
-    json(res, result);
+    mcpCallRoute.respond(res, 200, result);
   } catch (err) {
-    json(res, { ok: false, error: err instanceof Error ? err.message : String(err) });
+    mcpCallRoute.respond(res, 200, {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
   }
   return true;
 }