@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/src/http/agents.ts

@@ -23,12 +23,15 @@ import {
   upsertSwarmConfig,
 } from "../be/db";
 import { reasoningCapability } from "../providers/reasoning-effort";
-import { getEnabledCapabilities } from "../server";
+import { ALL_CAPABILITIES, getEnabledCapabilities } from "../server";
 import { telemetry } from "../telemetry";
 import {
   AgentAvatarSchema,
   AgentCredStatusSchema,
   AgentLatestModelSchema,
+  AgentSchema,
+  AgentStatusSchema,
+  AgentWithTasksSchema,
   type ProviderName,
   ProviderNameSchema,
   ReasoningEffortSchema,
@@ -39,6 +42,47 @@ import { agentWithCapacity, json, jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
+/** Mirrors `CAPABILITIES_T` (src/server.ts) — the server's registered MCP tool-group flags. */
+const CapabilitySchema = z.enum(ALL_CAPABILITIES);
+
+const AgentCapacitySchema = z.object({
+  current: z.number().int(),
+  max: z.number().int(),
+  available: z.number().int(),
+});
+
+/** Shape sent by `agentWithCapacity()` (src/http/utils.ts) for a plain Agent row. */
+const AgentWithCapacitySchema = AgentSchema.extend({
+  capacity: AgentCapacitySchema,
+});
+
+/**
+ * Same as `AgentWithCapacitySchema`, plus the `tasks` array added by
+ * `getAgentWithTasks`/`getAllAgentsWithTasks` when `?include=tasks` is used.
+ * Reuses the canonical `AgentWithTasksSchema` (src/types.ts) rather than
+ * re-declaring the `tasks` field inline.
+ */
+const AgentWithCapacityAndTasksSchema = AgentWithTasksSchema.extend({
+  capacity: AgentCapacitySchema,
+});
+
+/** POST /api/agents response: the agent row plus the server's capability flags. */
+const RegisterAgentResponseSchema = AgentSchema.extend({
+  enabledCapabilities: z.array(CapabilitySchema),
+});
+
+/** Shape shared by the single- and bulk- credential-status endpoints. */
+const AgentCredentialStatusEntrySchema = z.object({
+  agentId: z.string(),
+  name: z.string(),
+  status: AgentStatusSchema,
+  missing: z.array(z.string()),
+  provider: ProviderNameSchema.nullable(),
+  harnessProvider: ProviderNameSchema.nullable(),
+  credStatus: AgentCredStatusSchema.nullable(),
+  lastCheckedAt: z.string(),
+});
+
 const registerAgent = route({
   method: "post",
   path: "/api/agents",
@@ -64,8 +108,12 @@ const registerAgent = route({
     200: {
       description:
         "Agent re-registered (already existed). Response includes `enabledCapabilities` — the server's capability flags (registered MCP tool groups), not the agent's declared skill tags.",
+      schema: RegisterAgentResponseSchema,
+    },
+    201: {
+      description: "Agent created. Response includes `enabledCapabilities` (see 200).",
+      schema: RegisterAgentResponseSchema,
     },
-    201: { description: "Agent created. Response includes `enabledCapabilities` (see 200)." },
     400: { description: "Validation error" },
   },
 });
@@ -83,7 +131,7 @@ const setAgentHarnessProviderRoute = route({
     harness_provider: ProviderNameSchema,
   }),
   responses: {
-    200: { description: "Updated agent row" },
+    200: { description: "Updated agent row", schema: AgentWithCapacitySchema },
     400: { description: "Validation error (unknown provider)" },
     404: { description: "Agent not found" },
   },
@@ -107,7 +155,7 @@ const updateAgentRuntimeRoute = route({
     reasoning_effort: ReasoningEffortSchema.nullable().optional(),
   }),
   responses: {
-    200: { description: "Updated agent row" },
+    200: { description: "Updated agent row", schema: AgentWithCapacitySchema },
     400: { description: "Validation error" },
     404: { description: "Agent not found" },
   },
@@ -127,7 +175,10 @@ const listAgents = route({
     fields: z.enum(["full", "slim"]).optional(),
   }),
   responses: {
-    200: { description: "Agent list with capacity info" },
+    200: {
+      description: "Agent list with capacity info",
+      schema: z.object({ agents: z.array(AgentWithCapacityAndTasksSchema) }),
+    },
   },
 });
 
@@ -140,7 +191,7 @@ const updateAgentNameRoute = route({
   params: z.object({ id: z.string() }),
   body: z.object({ name: z.string().min(1) }),
   responses: {
-    200: { description: "Agent updated" },
+    200: { description: "Agent updated", schema: AgentWithCapacitySchema },
     404: { description: "Agent not found" },
     409: { description: "Name conflict" },
   },
@@ -154,7 +205,13 @@ const getAgentSetupScript = route({
   tags: ["Agents"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Setup scripts" },
+    200: {
+      description: "Setup scripts",
+      schema: z.object({
+        setupScript: z.string().nullable(),
+        globalSetupScript: z.string().nullable(),
+      }),
+    },
     404: { description: "Agent not found" },
   },
 });
@@ -183,7 +240,7 @@ const updateAgentProfileRoute = route({
     changeReason: z.string().optional(),
   }),
   responses: {
-    200: { description: "Profile updated" },
+    200: { description: "Profile updated", schema: AgentWithCapacitySchema },
     400: { description: "Validation error" },
     404: { description: "Agent not found" },
   },
@@ -212,7 +269,7 @@ const getAgent = route({
     include: z.enum(["tasks"]).optional(),
   }),
   responses: {
-    200: { description: "Agent with capacity info" },
+    200: { description: "Agent with capacity info", schema: AgentWithCapacityAndTasksSchema },
     404: { description: "Agent not found" },
   },
 });
@@ -246,7 +303,10 @@ const updateAgentCredentialStatusRoute = route({
   params: z.object({ id: z.string() }),
   body: credentialStatusBody,
   responses: {
-    200: { description: "State updated; returns the agent row." },
+    200: {
+      description: "State updated; returns the agent row.",
+      schema: AgentWithCapacitySchema,
+    },
     404: { description: "Agent not found" },
   },
 });
@@ -259,7 +319,7 @@ const getAgentCredentialStatusRoute = route({
   tags: ["Agents"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Credential status payload" },
+    200: { description: "Credential status payload", schema: AgentCredentialStatusEntrySchema },
     404: { description: "Agent not found" },
   },
 });
@@ -274,7 +334,10 @@ const listCredentialStatusRoute = route({
     status: z.enum(["idle", "busy", "offline", "waiting_for_credentials"]).optional(),
   }),
   responses: {
-    200: { description: "List of {agentId, status, missing[], lastCheckedAt}" },
+    200: {
+      description: "List of {agentId, status, missing[], lastCheckedAt}",
+      schema: z.object({ agents: z.array(AgentCredentialStatusEntrySchema) }),
+    },
   },
 });
 
@@ -375,11 +438,15 @@ export async function handleAgentRegister(
     // `enabledCapabilities` = the server's capability flags (which MCP tool
     // groups are registered), NOT the agent's declared skill tags. Workers use
     // it to drop prompt sections that instruct unregistered tools.
-    json(
-      res,
-      { ...result.agent, enabledCapabilities: getEnabledCapabilities() },
-      result.created ? 201 : 200,
-    );
+    // Non-null assertion: `result.agent` is only `| null` in the TS union
+    // because the re-registration branch re-fetches by id inside the same
+    // transaction right after confirming the row exists — it cannot actually
+    // be null here. (Same value as before; this only affects the compile-time
+    // type used to check the response schema.)
+    registerAgent.respond(res, result.created ? 201 : 200, {
+      ...result.agent!,
+      enabledCapabilities: getEnabledCapabilities(),
+    });
     return true;
   }
 
@@ -401,7 +468,7 @@ export async function handleAgentsRest(
     const slim = parsed.query.fields !== "full";
     const agents = includeTasks ? getAllAgentsWithTasks({ slim }) : getAllAgents({ slim });
     const agentsWithCapacity = agents.map(agentWithCapacity);
-    json(res, { agents: agentsWithCapacity });
+    listAgents.respond(res, 200, { agents: agentsWithCapacity });
     return true;
   }
 
@@ -415,7 +482,7 @@ export async function handleAgentsRest(
         jsonError(res, "Agent not found", 404);
         return true;
       }
-      json(res, agentWithCapacity(agent));
+      updateAgentNameRoute.respond(res, 200, agentWithCapacity(agent));
     } catch (error) {
       jsonError(res, (error as Error).message, 409);
     }
@@ -432,7 +499,7 @@ export async function handleAgentsRest(
     }
     const globalConfigs = getSwarmConfigs({ scope: "global", key: "SETUP_SCRIPT" });
     const globalSetupScript = globalConfigs[0]?.value ?? null;
-    json(res, {
+    getAgentSetupScript.respond(res, 200, {
       setupScript: agent.setupScript ?? null,
       globalSetupScript,
     });
@@ -502,7 +569,7 @@ export async function handleAgentsRest(
       return true;
     }
 
-    json(res, agentWithCapacity(agent));
+    updateAgentProfileRoute.respond(res, 200, agentWithCapacity(agent));
     return true;
   }
 
@@ -533,7 +600,7 @@ export async function handleAgentsRest(
       value: parsed.body.harness_provider,
       description: "Set via PATCH /api/agents/{id}/harness-provider",
     });
-    json(res, agentWithCapacity(agent));
+    setAgentHarnessProviderRoute.respond(res, 200, agentWithCapacity(agent));
     return true;
   }
 
@@ -624,7 +691,7 @@ export async function handleAgentsRest(
       jsonError(res, "Agent not found", 404);
       return true;
     }
-    json(res, agentWithCapacity(agent));
+    updateAgentRuntimeRoute.respond(res, 200, agentWithCapacity(agent));
     return true;
   }
 
@@ -646,7 +713,7 @@ export async function handleAgentsRest(
         credStatus: a.credStatus ?? null,
         lastCheckedAt: a.lastUpdatedAt,
       }));
-    json(res, { agents });
+    listCredentialStatusRoute.respond(res, 200, { agents });
     return true;
   }
 
@@ -709,7 +776,7 @@ export async function handleAgentsRest(
           latestModel: parsed.body.latest_model,
         }) ?? agent;
     }
-    json(res, agentWithCapacity(finalAgent));
+    updateAgentCredentialStatusRoute.respond(res, 200, agentWithCapacity(finalAgent));
     return true;
   }
 
@@ -721,7 +788,7 @@ export async function handleAgentsRest(
       jsonError(res, "Agent not found", 404);
       return true;
     }
-    json(res, {
+    getAgentCredentialStatusRoute.respond(res, 200, {
       agentId: agent.id,
       name: agent.name,
       status: agent.status,
@@ -747,7 +814,7 @@ export async function handleAgentsRest(
       return true;
     }
 
-    json(res, agentWithCapacity(agent));
+    getAgent.respond(res, 200, agentWithCapacity(agent));
     return true;
   }
 

package/src/http/api-keys.ts

@@ -11,10 +11,16 @@ import {
   setApiKeyName,
 } from "../be/db";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
+/** Wire shape sent by every `report-*` acknowledgement route. */
+const successMessageSchema = z.object({
+  success: z.literal(true),
+  message: z.string(),
+});
+
 const reportUsage = route({
   method: "post",
   path: "/api/keys/report-usage",
@@ -30,7 +36,7 @@ const reportUsage = route({
     scopeId: z.string().optional(),
   }),
   responses: {
-    200: { description: "Usage recorded" },
+    200: { description: "Usage recorded", schema: successMessageSchema },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
   },
@@ -52,7 +58,7 @@ const reportRateLimit = route({
     scopeId: z.string().optional(),
   }),
   responses: {
-    200: { description: "Key marked as rate-limited" },
+    200: { description: "Key marked as rate-limited", schema: successMessageSchema },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
   },
@@ -83,7 +89,10 @@ const reportRateLimitWindows = route({
     scopeId: z.string().optional(),
   }),
   responses: {
-    200: { description: "Rate-limit window telemetry recorded" },
+    200: {
+      description: "Rate-limit window telemetry recorded",
+      schema: successMessageSchema,
+    },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
   },
@@ -103,13 +112,44 @@ const getAvailable = route({
     scopeId: z.string().optional(),
   }),
   responses: {
-    200: { description: "List of available key indices" },
+    200: {
+      description: "List of available key indices",
+      schema: z.object({
+        success: z.literal(true),
+        availableIndices: z.array(z.number().int()),
+        totalKeys: z.number().int(),
+      }),
+    },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
   },
   auth: { apiKey: true },
 });
 
+/** Mirrors `ApiKeyStatus` in `src/be/db.ts` (not exported from `src/types.ts`). */
+const ApiKeyStatusSchema = z.object({
+  id: z.string(),
+  keyType: z.string(),
+  keySuffix: z.string(),
+  keyIndex: z.number().int(),
+  scope: z.string(),
+  scopeId: z.string().nullable(),
+  status: z.string(),
+  rateLimitedUntil: z.string().nullable(),
+  lastUsedAt: z.string().nullable(),
+  lastRateLimitAt: z.string().nullable(),
+  totalUsageCount: z.number().int(),
+  rateLimitCount: z.number().int(),
+  /** Optional human-friendly label set from the dashboard. */
+  name: z.string().nullable(),
+  /** Auto-derived harness provider (claude/pi/codex/...). */
+  provider: z.string(),
+  /** Latest provider-emitted rate-limit window snapshots, keyed by window type. */
+  rateLimitWindows: z.record(z.string(), rateLimitWindowSchema),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
 const listStatuses = route({
   method: "get",
   path: "/api/keys/status",
@@ -122,12 +162,25 @@ const listStatuses = route({
     scopeId: z.string().optional(),
   }),
   responses: {
-    200: { description: "List of key status records" },
+    200: {
+      description: "List of key status records",
+      schema: z.object({ success: z.literal(true), keys: z.array(ApiKeyStatusSchema) }),
+    },
     401: { description: "Unauthorized" },
   },
   auth: { apiKey: true },
 });
 
+/** Mirrors `KeyCostSummary` in `src/be/db.ts`. */
+const KeyCostSummarySchema = z.object({
+  keyType: z.string(),
+  keySuffix: z.string(),
+  totalCost: z.number().nonnegative(),
+  totalInputTokens: z.number().int().nonnegative(),
+  totalOutputTokens: z.number().int().nonnegative(),
+  taskCount: z.number().int().nonnegative(),
+});
+
 const getCosts = route({
   method: "get",
   path: "/api/keys/costs",
@@ -138,7 +191,10 @@ const getCosts = route({
     keyType: z.string().optional(),
   }),
   responses: {
-    200: { description: "Per-key cost aggregation" },
+    200: {
+      description: "Per-key cost aggregation",
+      schema: z.object({ success: z.literal(true), costs: z.array(KeyCostSummarySchema) }),
+    },
     401: { description: "Unauthorized" },
   },
   auth: { apiKey: true },
@@ -159,7 +215,15 @@ const setKeyName = route({
     scopeId: z.string().optional(),
   }),
   responses: {
-    200: { description: "Name updated" },
+    200: {
+      description: "Name updated",
+      schema: z.object({
+        success: z.literal(true),
+        keyType: z.string(),
+        keySuffix: z.string(),
+        name: z.string().nullable(),
+      }),
+    },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
     404: { description: "Key not found" },
@@ -180,7 +244,14 @@ const clearRateLimitRoute = route({
     scopeId: z.string().optional(),
   }),
   responses: {
-    200: { description: "Rate limit cleared (or key was not rate-limited)" },
+    200: {
+      description: "Rate limit cleared (or key was not rate-limited)",
+      schema: z.object({
+        success: z.literal(true),
+        cleared: z.boolean(),
+        message: z.string(),
+      }),
+    },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
   },
@@ -203,7 +274,7 @@ export async function handleApiKeys(
     const { keyType, keySuffix, keyIndex, taskId, scope, scopeId } = parsed.body;
     try {
       recordKeyUsage(keyType, keySuffix, keyIndex, taskId ?? null, scope, scopeId ?? null);
-      json(res, { success: true, message: "Key usage recorded" });
+      reportUsage.respond(res, 200, { success: true, message: "Key usage recorded" });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to record usage", 500);
     }
@@ -218,7 +289,7 @@ export async function handleApiKeys(
     const { keyType, keySuffix, keyIndex, rateLimitedUntil, scope, scopeId } = parsed.body;
     try {
       markKeyRateLimited(keyType, keySuffix, keyIndex, rateLimitedUntil, scope, scopeId ?? null);
-      json(res, {
+      reportRateLimit.respond(res, 200, {
         success: true,
         message: `Key ...${keySuffix} marked as rate-limited until ${rateLimitedUntil}`,
       });
@@ -236,7 +307,10 @@ export async function handleApiKeys(
     const { keyType, keySuffix, keyIndex, windows, scope, scopeId } = parsed.body;
     try {
       recordKeyRateLimitWindows(keyType, keySuffix, keyIndex, windows, scope, scopeId ?? null);
-      json(res, { success: true, message: `Rate-limit windows recorded for ...${keySuffix}` });
+      reportRateLimitWindows.respond(res, 200, {
+        success: true,
+        message: `Rate-limit windows recorded for ...${keySuffix}`,
+      });
     } catch (err) {
       jsonError(
         res,
@@ -255,7 +329,7 @@ export async function handleApiKeys(
     const { keyType, totalKeys, scope, scopeId } = parsed.query;
     try {
       const indices = getAvailableKeyIndices(keyType, totalKeys, scope, scopeId ?? null);
-      json(res, { success: true, availableIndices: indices, totalKeys });
+      getAvailable.respond(res, 200, { success: true, availableIndices: indices, totalKeys });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to get available keys", 500);
     }
@@ -270,7 +344,7 @@ export async function handleApiKeys(
     const { keyType } = parsed.query;
     try {
       const costs = getKeyCostSummary(keyType);
-      json(res, { success: true, costs });
+      getCosts.respond(res, 200, { success: true, costs });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to get key costs", 500);
     }
@@ -285,7 +359,7 @@ export async function handleApiKeys(
     const { keyType, scope, scopeId } = parsed.query;
     try {
       const statuses = getKeyStatuses(keyType, scope, scopeId ?? null);
-      json(res, { success: true, keys: statuses });
+      listStatuses.respond(res, 200, { success: true, keys: statuses });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to get key statuses", 500);
     }
@@ -307,7 +381,7 @@ export async function handleApiKeys(
         jsonError(res, `No key matching ${keyType} ...${keySuffix}`, 404);
         return true;
       }
-      json(res, { success: true, keyType, keySuffix, name: value });
+      setKeyName.respond(res, 200, { success: true, keyType, keySuffix, name: value });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to set key name", 500);
     }
@@ -322,7 +396,7 @@ export async function handleApiKeys(
     const { keyType, keySuffix, scope, scopeId } = parsed.body;
     try {
       const cleared = clearKeyRateLimit(keyType, keySuffix, scope, scopeId ?? null);
-      json(res, {
+      clearRateLimitRoute.respond(res, 200, {
         success: true,
         cleared,
         message: cleared

package/src/http/approval-requests.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { resolveTaskAuditUserId } from "../be/audit-user";
 import {
+  type ApprovalRequest,
   createApprovalRequest,
   createTaskExtended,
   getApprovalRequestById,
@@ -13,7 +14,7 @@ import { resolveTemplate } from "../prompts/resolver";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { workflowEventBus } from "../workflows/event-bus";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
@@ -41,6 +42,69 @@ const QuestionSchema = z.object({
 
 export type ApprovalQuestion = z.infer<typeof QuestionSchema>;
 
+// ─── Response Schemas ────────────────────────────────────────────────────────
+// `ApprovalRequest` (src/be/db.ts) types `questions`/`approvers`/`responses`/
+// `notificationChannels` as `unknown` — the DB layer stores opaque JSON blobs.
+// Reading every writer (this file's create route, tools/request-human-input.ts,
+// workflows/executors/human-in-the-loop.ts) confirms they always conform to the
+// shapes below, so we describe them precisely here and cast at the call sites
+// (matching the existing `existing.questions as ApprovalQuestion[]` pattern in
+// this file) rather than degrading the documented contract to `z.unknown()`.
+
+const ApproversSchema = z.object({
+  users: z.array(z.string()).optional(),
+  roles: z.array(z.string()).optional(),
+  policy: z.union([z.literal("any"), z.literal("all"), z.object({ min: z.number().int().min(1) })]),
+});
+type ApproversShape = z.infer<typeof ApproversSchema>;
+
+const NotificationChannelSchema = z.object({
+  channel: z.enum(["slack", "email"]),
+  target: z.string(),
+  // Added post-creation by workflows/executors/human-in-the-loop.ts once the
+  // notification message is sent (see `updateApprovalRequestNotifications`).
+  messageTs: z.string().optional(),
+});
+type NotificationChannelShape = z.infer<typeof NotificationChannelSchema>;
+
+const ApprovalRequestSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  questions: z.array(QuestionSchema),
+  workflowRunId: z.string().nullable(),
+  workflowRunStepId: z.string().nullable(),
+  sourceTaskId: z.string().nullable(),
+  approvers: ApproversSchema,
+  status: z.enum(["pending", "approved", "rejected", "timeout"]),
+  responses: z.record(z.string(), z.unknown()).nullable(),
+  resolvedBy: z.string().nullable(),
+  resolvedAt: z.string().nullable(),
+  timeoutSeconds: z.number().nullable(),
+  expiresAt: z.string().nullable(),
+  notificationChannels: z.array(NotificationChannelSchema).nullable(),
+  createdBy: z.string().optional(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+/**
+ * Reshapes a DB `ApprovalRequest` row for `respond()` — identical values,
+ * narrowed from the DB layer's `unknown` fields to the precise wire shape
+ * (see comment above `ApproversSchema`). Not a behavior change: same object
+ * contents, serialized the same way.
+ */
+function toApprovalRequestResponse(
+  request: ApprovalRequest,
+): z.infer<typeof ApprovalRequestSchema> {
+  return {
+    ...request,
+    questions: request.questions as ApprovalQuestion[],
+    approvers: request.approvers as ApproversShape,
+    responses: request.responses as Record<string, unknown> | null,
+    notificationChannels: request.notificationChannels as NotificationChannelShape[] | null,
+  };
+}
+
 function hasRequiredResponse(question: ApprovalQuestion, response: unknown): boolean {
   switch (question.type) {
     case "approval":
@@ -118,7 +182,10 @@ const createRoute = route({
       .optional(),
   }),
   responses: {
-    201: { description: "Approval request created" },
+    201: {
+      description: "Approval request created",
+      schema: z.object({ approvalRequest: ApprovalRequestSchema }),
+    },
     400: { description: "Validation error" },
   },
   auth: { apiKey: true },
@@ -132,7 +199,10 @@ const getByIdRoute = route({
   tags: ["ApprovalRequests"],
   params: z.object({ id: z.string().uuid() }),
   responses: {
-    200: { description: "Approval request details" },
+    200: {
+      description: "Approval request details",
+      schema: z.object({ approvalRequest: ApprovalRequestSchema }),
+    },
     404: { description: "Not found" },
   },
   auth: { apiKey: true },
@@ -150,7 +220,10 @@ const respondRoute = route({
     respondedBy: z.string().optional(),
   }),
   responses: {
-    200: { description: "Response recorded" },
+    200: {
+      description: "Response recorded",
+      schema: z.object({ approvalRequest: ApprovalRequestSchema }),
+    },
     400: { description: "Validation error" },
     404: { description: "Not found" },
     409: { description: "Already resolved" },
@@ -170,7 +243,10 @@ const listRoute = route({
     limit: z.coerce.number().optional(),
   }),
   responses: {
-    200: { description: "List of approval requests" },
+    200: {
+      description: "List of approval requests",
+      schema: z.object({ approvalRequests: z.array(ApprovalRequestSchema) }),
+    },
   },
   auth: { apiKey: true },
 });
@@ -278,7 +354,7 @@ export async function handleApprovalRequests(
       }
     }
 
-    json(res, { approvalRequest: updated });
+    respondRoute.respond(res, 200, { approvalRequest: toApprovalRequestResponse(updated) });
     return true;
   }
 
@@ -293,7 +369,7 @@ export async function handleApprovalRequests(
       return true;
     }
 
-    json(res, { approvalRequest: request });
+    getByIdRoute.respond(res, 200, { approvalRequest: toApprovalRequestResponse(request) });
     return true;
   }
 
@@ -325,8 +401,7 @@ export async function handleApprovalRequests(
       createdBy,
     });
 
-    res.writeHead(201, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ approvalRequest: request }));
+    createRoute.respond(res, 201, { approvalRequest: toApprovalRequestResponse(request) });
     return true;
   }
 
@@ -341,7 +416,9 @@ export async function handleApprovalRequests(
       limit: parsed.query.limit || undefined,
     });
 
-    json(res, { approvalRequests: requests });
+    listRoute.respond(res, 200, {
+      approvalRequests: requests.map(toApprovalRequestResponse),
+    });
     return true;
   }