@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/src/http/ecosystem.ts

@@ -1,10 +1,22 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
 import { getServicesByAgentId } from "../be/db";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
+const EcosystemAppSchema = z.object({
+  name: z.string(),
+  script: z.string(),
+  cwd: z.string().optional(),
+  interpreter: z.string().optional(),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional(),
+});
+
+type EcosystemApp = z.infer<typeof EcosystemAppSchema>;
+
 const getEcosystem = route({
   method: "get",
   path: "/ecosystem",
@@ -13,7 +25,10 @@ const getEcosystem = route({
   tags: ["Ecosystem"],
   auth: { apiKey: true, agentId: true },
   responses: {
-    200: { description: "PM2 ecosystem config" },
+    200: {
+      description: "PM2 ecosystem config",
+      schema: z.object({ apps: z.array(EcosystemAppSchema) }),
+    },
     400: { description: "Missing X-Agent-ID" },
   },
 });
@@ -39,7 +54,7 @@ export async function handleEcosystem(
       apps: services
         .filter((s) => s.script) // Only include services with script path
         .map((s) => {
-          const app: Record<string, unknown> = {
+          const app: EcosystemApp = {
             name: s.name,
             script: s.script,
           };
@@ -48,14 +63,13 @@ export async function handleEcosystem(
           if (s.interpreter) app.interpreter = s.interpreter;
           if (s.args && s.args.length > 0) app.args = s.args;
           if (s.env && Object.keys(s.env).length > 0) app.env = s.env;
-          if (s.port)
-            app.env = { ...((app.env as Record<string, string>) || {}), PORT: String(s.port) };
+          if (s.port) app.env = { ...(app.env || {}), PORT: String(s.port) };
 
           return app;
         }),
     };
 
-    json(res, ecosystem);
+    getEcosystem.respond(res, 200, ecosystem);
     return true;
   }
 

package/src/http/events.ts

@@ -11,9 +11,10 @@ import {
   EventNameSchema,
   EventSourceSchema,
   EventStatusSchema,
+  SwarmEventSchema,
 } from "../types";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
@@ -39,7 +40,10 @@ const createEventRoute = route({
   tags: ["Events"],
   body: eventBodySchema,
   responses: {
-    201: { description: "Event stored" },
+    201: {
+      description: "Event stored",
+      schema: z.object({ success: z.literal(true), event: SwarmEventSchema }),
+    },
     400: { description: "Validation error" },
   },
   auth: { apiKey: true },
@@ -55,7 +59,10 @@ const createEventsBatchRoute = route({
     events: z.array(eventBodySchema).min(1).max(500),
   }),
   responses: {
-    201: { description: "Events stored" },
+    201: {
+      description: "Events stored",
+      schema: z.object({ success: z.literal(true), count: z.number().int() }),
+    },
     400: { description: "Validation error" },
   },
   auth: { apiKey: true },
@@ -80,7 +87,10 @@ const getEventsRoute = route({
     limit: z.coerce.number().int().min(1).max(1000).optional(),
   }),
   responses: {
-    200: { description: "List of events" },
+    200: {
+      description: "List of events",
+      schema: z.object({ events: z.array(SwarmEventSchema) }),
+    },
   },
   auth: { apiKey: true },
 });
@@ -101,7 +111,12 @@ const getEventCountsRoute = route({
     until: z.string().optional(),
   }),
   responses: {
-    200: { description: "Event counts" },
+    200: {
+      description: "Event counts",
+      schema: z.object({
+        counts: z.array(z.object({ event: z.string(), count: z.number().int() })),
+      }),
+    },
   },
   auth: { apiKey: true },
 });
@@ -122,7 +137,7 @@ export async function handleEvents(
 
     try {
       const count = createEventsBatch(parsed.body.events);
-      json(res, { success: true, count }, 201);
+      createEventsBatchRoute.respond(res, 201, { success: true, count });
     } catch (error) {
       console.error("[HTTP] Failed to create events batch:", error);
       jsonError(res, "Failed to store events batch", 500);
@@ -144,7 +159,7 @@ export async function handleEvents(
       since: parsed.query.since || undefined,
       until: parsed.query.until || undefined,
     });
-    json(res, { counts });
+    getEventCountsRoute.respond(res, 200, { counts });
     return true;
   }
 
@@ -155,7 +170,7 @@ export async function handleEvents(
 
     try {
       const event = createEvent(parsed.body);
-      json(res, { success: true, event }, 201);
+      createEventRoute.respond(res, 201, { success: true, event });
     } catch (error) {
       console.error("[HTTP] Failed to create event:", error);
       jsonError(res, "Failed to store event", 500);
@@ -180,7 +195,7 @@ export async function handleEvents(
       until: parsed.query.until || undefined,
       limit: parsed.query.limit ?? 100,
     });
-    json(res, { events });
+    getEventsRoute.respond(res, 200, { events });
     return true;
   }
 

package/src/http/favorites.ts

@@ -1,10 +1,10 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { listFavorites as listFavoriteRows, setFavorite } from "../be/db";
-import { FavoriteItemTypeSchema } from "../types";
+import { FavoriteItemTypeSchema, UserFavoriteSchema } from "../types";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 const listFavorites = route({
   method: "get",
@@ -17,7 +17,13 @@ const listFavorites = route({
     itemIds: z.string().optional(),
   }),
   responses: {
-    200: { description: "Favorite rows and favorite item ids" },
+    200: {
+      description: "Favorite rows and favorite item ids",
+      schema: z.object({
+        favorites: z.array(UserFavoriteSchema),
+        favoriteIds: z.array(z.string()),
+      }),
+    },
     401: { description: "No authenticated principal context" },
   },
 });
@@ -35,7 +41,15 @@ const putFavorite = route({
     favorite: z.boolean(),
   }),
   responses: {
-    200: { description: "Favorite state" },
+    200: {
+      description: "Favorite state",
+      schema: z.object({
+        favorite: z.boolean(),
+        itemType: FavoriteItemTypeSchema,
+        itemId: z.string(),
+        row: UserFavoriteSchema.nullable(),
+      }),
+    },
     401: { description: "No authenticated principal context" },
   },
 });
@@ -64,7 +78,7 @@ export async function handleFavorites(
       itemType: parsed.query.itemType,
       itemIds,
     });
-    json(res, {
+    listFavorites.respond(res, 200, {
       favorites,
       favoriteIds: favorites.map((favorite) => favorite.itemId),
     });
@@ -87,7 +101,7 @@ export async function handleFavorites(
       favorite: parsed.body.favorite,
       actorId: owner.actorId,
     });
-    json(res, {
+    putFavorite.respond(res, 200, {
       favorite: parsed.body.favorite,
       itemType: parsed.body.itemType,
       itemId: parsed.body.itemId,

package/src/http/fs.ts

@@ -15,12 +15,12 @@ import {
 import { type FileObject, type FileScope, FilesError, normalizeFilesError } from "../fs/provider";
 import { getFileStorageProvider } from "../fs/registry";
 import { can, type RbacPrincipal, type RbacResource } from "../rbac";
-import type { TaskAttachment } from "../types";
+import { type TaskAttachment, TaskAttachmentSchema } from "../types";
 import { attachmentContentDisposition } from "../utils/content-disposition";
 import { getCurrentRequestAuth, getRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { route } from "./route-def";
-import { BODY_TOO_LARGE, enforceContentLengthCap, json, jsonError } from "./utils";
+import { BODY_TOO_LARGE, enforceContentLengthCap, jsonError } from "./utils";
 
 const MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 
@@ -38,6 +38,37 @@ const signedUrlQuery = z.object({
   expiresIn: z.coerce.number().int().positive().max(3600).optional(),
 });
 
+// Mirrors `ProviderCapabilities` from src/fs/capabilities.ts — no zod schema
+// exists there (it's a plain TS type consumed by provider implementations).
+const providerCapabilitiesSchema = z.object({
+  signedUrl: z.object({
+    supported: z.boolean(),
+    maxExpiresIn: z.number().optional(),
+  }),
+  search: z.boolean().optional(),
+  comments: z.boolean().optional(),
+  versioning: z.boolean().optional(),
+});
+
+const agentFsCredentialStateSchema = z.object({
+  enabled: z.boolean(),
+  created: z.boolean(),
+  agentId: z.string(),
+  email: z.string().optional(),
+  orgId: z.string().optional(),
+  driveId: z.string().optional(),
+});
+
+const agentFsInviteStateSchema = z.object({
+  orgId: z.string(),
+  invited: z.boolean(),
+});
+
+const signedUrlResponseSchema = z.object({
+  url: z.string(),
+  expiresIn: z.number(),
+});
+
 const capabilitiesRoute = route({
   method: "get",
   path: "/api/fs/capabilities",
@@ -45,7 +76,10 @@ const capabilitiesRoute = route({
   summary: "Get active file-storage provider capabilities",
   tags: ["FS"],
   responses: {
-    200: { description: "Active provider capabilities" },
+    200: {
+      description: "Active provider capabilities",
+      schema: z.object({ providerId: z.string(), capabilities: providerCapabilitiesSchema }),
+    },
     401: { description: "Unauthorized" },
   },
 });
@@ -60,7 +94,7 @@ const ensureAgentCredentialsRoute = route({
   tags: ["FS"],
   body: z.object({}).optional(),
   responses: {
-    200: { description: "Credential state" },
+    200: { description: "Credential state", schema: agentFsCredentialStateSchema },
     400: { description: "Missing agent id" },
     500: { description: "Provisioning failed" },
   },
@@ -80,7 +114,7 @@ const inviteMemberRoute = route({
     role: z.enum(["viewer", "editor", "admin"]).default("editor"),
   }),
   responses: {
-    200: { description: "Invite state ({ orgId, invited })" },
+    200: { description: "Invite state ({ orgId, invited })", schema: agentFsInviteStateSchema },
     400: { description: "Invalid body" },
     500: { description: "Provisioning or invite failed" },
   },
@@ -99,7 +133,10 @@ const listTaskFilesRoute = route({
   tags: ["FS"],
   params: taskParams,
   responses: {
-    200: { description: "Task file attachments" },
+    200: {
+      description: "Task file attachments",
+      schema: z.object({ attachments: z.array(TaskAttachmentSchema) }),
+    },
     404: { description: "Task not found" },
   },
 });
@@ -115,7 +152,7 @@ const uploadTaskFileRoute = route({
   params: taskParams,
   query: uploadQuery,
   responses: {
-    201: { description: "Uploaded task attachment" },
+    201: { description: "Uploaded task attachment", schema: TaskAttachmentSchema },
     400: { description: "Validation error" },
     403: { description: "Caller cannot mutate this task" },
     404: { description: "Task not found" },
@@ -133,7 +170,7 @@ const getTaskFileRoute = route({
   tags: ["FS"],
   params: attachmentParams,
   responses: {
-    200: { description: "Task attachment metadata" },
+    200: { description: "Task attachment metadata", schema: TaskAttachmentSchema },
     404: { description: "Task or attachment not found" },
   },
 });
@@ -147,7 +184,10 @@ const downloadTaskFileRoute = route({
   tags: ["FS"],
   params: attachmentParams,
   responses: {
-    200: { description: "Raw file bytes" },
+    200: {
+      description: "Raw file bytes",
+      unstructured: "Streams raw binary file bytes (Content-Type varies per attachment)",
+    },
     404: { description: "Task, attachment, or provider object not found" },
   },
 });
@@ -161,7 +201,7 @@ const signedUrlTaskFileRoute = route({
   params: attachmentParams,
   query: signedUrlQuery,
   responses: {
-    200: { description: "Signed URL" },
+    200: { description: "Signed URL", schema: signedUrlResponseSchema },
     404: { description: "Task, attachment, or provider object not found" },
     501: { description: "Active provider does not support signed URLs" },
   },
@@ -202,7 +242,7 @@ export async function handleFs(
     }
     try {
       const result = await ensureAgentFsCredentialsForAgent(agentId);
-      json(res, result);
+      ensureAgentCredentialsRoute.respond(res, 200, result);
     } catch (error) {
       const message = scrubSecrets(error instanceof Error ? error.message : String(error));
       jsonError(res, `Failed to provision agent-fs credentials: ${message}`, 500);
@@ -215,7 +255,7 @@ export async function handleFs(
     if (!parsed) return true;
     try {
       const result = await inviteEmailToSharedOrg(parsed.body.email, parsed.body.role);
-      json(res, result);
+      inviteMemberRoute.respond(res, 200, result);
     } catch (error) {
       const message = scrubSecrets(error instanceof Error ? error.message : String(error));
       jsonError(res, `Failed to invite member to agent-fs shared org: ${message}`, 500);
@@ -244,7 +284,7 @@ export async function handleFs(
     if (!parsed) return true;
     const attachment = findAttachment(parsed.params.taskId, parsed.params.attachmentId, res);
     if (!attachment) return true;
-    json(res, attachment);
+    getTaskFileRoute.respond(res, 200, attachment);
     return true;
   }
 
@@ -275,13 +315,16 @@ export async function handleFs(
     const parsed = await listTaskFilesRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     if (!getTaskById(parsed.params.taskId)) return notFound(res, "Task not found");
-    json(res, { attachments: getTaskAttachments(parsed.params.taskId) });
+    listTaskFilesRoute.respond(res, 200, { attachments: getTaskAttachments(parsed.params.taskId) });
     return true;
   }
 
   if (capabilitiesRoute.match(req.method, pathSegments)) {
     const provider = getFileStorageProvider();
-    json(res, { providerId: provider.id, capabilities: provider.capabilities });
+    capabilitiesRoute.respond(res, 200, {
+      providerId: provider.id,
+      capabilities: provider.capabilities,
+    });
     return true;
   }
 
@@ -338,7 +381,7 @@ async function sendUpload(
       isPrimary: query.isPrimary === "true",
       createdBy: auth?.kind === "user" ? auth.userId : undefined,
     });
-    json(res, attachment, 201);
+    uploadTaskFileRoute.respond(res, 201, attachment);
   } catch (error) {
     try {
       await provider.delete(scope);
@@ -397,7 +440,7 @@ async function sendSignedUrl(
   }
   try {
     const url = await provider.url(scopeFromAttachment(attachment), { expiresIn });
-    json(res, { url, expiresIn: Math.min(expiresIn ?? 3600, 3600) });
+    signedUrlTaskFileRoute.respond(res, 200, { url, expiresIn: Math.min(expiresIn ?? 3600, 3600) });
   } catch (error) {
     return sendProviderError(res, error);
   }

package/src/http/heartbeat.ts

@@ -1,8 +1,16 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
 import { checkHeartbeatChecklist, runHeartbeatSweep } from "../heartbeat/heartbeat";
 import { route } from "./route-def";
 import { json } from "./utils";
 
+// ─── Response schemas ───────────────────────────────────────────────────────
+
+const HeartbeatActionResultSchema = z.object({
+  success: z.literal(true),
+  message: z.string(),
+});
+
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
 const triggerSweep = route({
@@ -12,7 +20,7 @@ const triggerSweep = route({
   summary: "Trigger an immediate heartbeat sweep",
   tags: ["Heartbeat"],
   responses: {
-    200: { description: "Sweep completed successfully" },
+    200: { description: "Sweep completed successfully", schema: HeartbeatActionResultSchema },
     401: { description: "Unauthorized" },
   },
   auth: { apiKey: true },
@@ -25,7 +33,10 @@ const triggerChecklist = route({
   summary: "Trigger an immediate heartbeat checklist check",
   tags: ["Heartbeat"],
   responses: {
-    200: { description: "Checklist check completed successfully" },
+    200: {
+      description: "Checklist check completed successfully",
+      schema: HeartbeatActionResultSchema,
+    },
     401: { description: "Unauthorized" },
   },
   auth: { apiKey: true },
@@ -44,7 +55,7 @@ export async function handleHeartbeat(
 
     try {
       await runHeartbeatSweep();
-      json(res, { success: true, message: "Heartbeat sweep completed" });
+      triggerSweep.respond(res, 200, { success: true, message: "Heartbeat sweep completed" });
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unknown error during heartbeat sweep";
       json(res, { success: false, error: message }, 500);
@@ -58,7 +69,10 @@ export async function handleHeartbeat(
 
     try {
       await checkHeartbeatChecklist();
-      json(res, { success: true, message: "Heartbeat checklist check completed" });
+      triggerChecklist.respond(res, 200, {
+        success: true,
+        message: "Heartbeat checklist check completed",
+      });
     } catch (err) {
       const message =
         err instanceof Error ? err.message : "Unknown error during heartbeat checklist check";

package/src/http/inbox-state.ts

@@ -1,9 +1,9 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { listInboxState, upsertInboxState } from "../be/db";
-import { InboxItemStatusSchema, InboxItemTypeSchema } from "../types";
+import { InboxItemStateSchema, InboxItemStatusSchema, InboxItemTypeSchema } from "../types";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
@@ -19,7 +19,10 @@ const listState = route({
     itemType: InboxItemTypeSchema.optional(),
   }),
   responses: {
-    200: { description: "Inbox state rows" },
+    200: {
+      description: "Inbox state rows",
+      schema: z.object({ items: z.array(InboxItemStateSchema) }),
+    },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
   },
@@ -40,7 +43,10 @@ const upsertState = route({
     snoozeUntil: z.string().datetime().optional(),
   }),
   responses: {
-    200: { description: "Upserted inbox state row" },
+    200: {
+      description: "Upserted inbox state row",
+      schema: z.object({ item: InboxItemStateSchema }),
+    },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
   },
@@ -63,7 +69,7 @@ export async function handleInboxState(
       status: parsed.query.status,
       itemType: parsed.query.itemType,
     });
-    json(res, { items });
+    listState.respond(res, 200, { items });
     return true;
   }
 
@@ -78,7 +84,7 @@ export async function handleInboxState(
         status: parsed.body.status,
         snoozeUntil: parsed.body.snoozeUntil,
       });
-      json(res, { item });
+      upsertState.respond(res, 200, { item });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to upsert inbox state", 500);
     }

package/src/http/integrations.ts

@@ -3,7 +3,6 @@ import Anthropic from "@anthropic-ai/sdk";
 import { z } from "zod";
 import { getResolvedConfig } from "../be/db";
 import { route } from "./route-def";
-import { json } from "./utils";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -27,6 +26,25 @@ interface TestConnectionDeps {
   buildClient?: (apiKey: string) => ClaudeManagedTestClient;
 }
 
+// ─── Response schemas ────────────────────────────────────────────────────────
+
+const ClaudeManagedTestResultSchema = z.union([
+  z.object({
+    ok: z.literal(true),
+    agentName: z.string().nullable(),
+    model: z.string().nullable(),
+  }),
+  z.object({
+    ok: z.literal(false),
+    error: z.string(),
+  }),
+]);
+
+const McpUserConfigSchema = z.object({
+  mcpBaseUrl: z.string(),
+  mcpUserUrl: z.string(),
+});
+
 // ─── Route Definition ────────────────────────────────────────────────────────
 
 const claudeManagedTestRoute = route({
@@ -41,6 +59,7 @@ const claudeManagedTestRoute = route({
     200: {
       description:
         "Connection result — `{ ok: true, agentName, model }` on success or `{ ok: false, error }` on any failure (missing config, Anthropic API error). Always 200 OK.",
+      schema: ClaudeManagedTestResultSchema,
     },
   },
 });
@@ -55,6 +74,7 @@ const mcpUserConfigRoute = route({
     200: {
       description:
         "Server-derived MCP user config. `mcpBaseUrl` is the API server base URL and `mcpUserUrl` appends `/mcp-user`.",
+      schema: McpUserConfigSchema,
     },
   },
 });
@@ -116,7 +136,7 @@ export function createIntegrationsHandler(deps: TestConnectionDeps = {}) {
   ): Promise<boolean> {
     if (mcpUserConfigRoute.match(req.method, pathSegments)) {
       const mcpBaseUrl = resolveMcpBaseUrl();
-      json(res, { mcpBaseUrl, mcpUserUrl: `${mcpBaseUrl}/mcp-user` });
+      mcpUserConfigRoute.respond(res, 200, { mcpBaseUrl, mcpUserUrl: `${mcpBaseUrl}/mcp-user` });
       return true;
     }
 
@@ -128,7 +148,7 @@ export function createIntegrationsHandler(deps: TestConnectionDeps = {}) {
         const missing: string[] = [];
         if (!apiKey) missing.push("ANTHROPIC_API_KEY");
         if (!agentId) missing.push("MANAGED_AGENT_ID");
-        json(res, {
+        claudeManagedTestRoute.respond(res, 200, {
           ok: false,
           error: `Missing required config: ${missing.join(", ")}. Run \`bun run src/cli.tsx claude-managed-setup\` to populate.`,
         });
@@ -144,14 +164,14 @@ export function createIntegrationsHandler(deps: TestConnectionDeps = {}) {
           typeof agent.model === "string"
             ? agent.model
             : ((agent.model as { id?: string } | null | undefined)?.id ?? null);
-        json(res, {
+        claudeManagedTestRoute.respond(res, 200, {
           ok: true,
           agentName: agent.name ?? null,
           model: modelId,
         });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        json(res, { ok: false, error: message });
+        claudeManagedTestRoute.respond(res, 200, { ok: false, error: message });
       }
       return true;
     }