@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/src/http/pages.ts

@@ -23,13 +23,15 @@ import {
   type Page,
   PageAuthModeSchema,
   PageContentTypeSchema,
+  PageSchema,
   type PageSummary,
+  PageVersionSchema,
 } from "../types";
 import { getAppUrl, getPublicMcpBaseUrl } from "../utils/constants";
 import { issuePageSessionCookie } from "../utils/page-session";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
 import { route } from "./route-def";
-import { BODY_TOO_LARGE, enforceContentLengthCap, json, jsonError } from "./utils";
+import { BODY_TOO_LARGE, enforceContentLengthCap, jsonError } from "./utils";
 
 /**
  * Per-page body-size cap. Page bodies are stored as a TEXT column with no
@@ -57,6 +59,32 @@ function slugify(input: string): string {
   return slug || "page";
 }
 
+// ─── Response Schemas ───────────────────────────────────────────────────────
+
+/**
+ * Shape of a single page row as returned by the get-by-id / resolve-by-slug
+ * routes: the `Page` row (with its already-optional `favorite`, populated by
+ * `withFavoriteFlags` on the normal path but structurally optional to match
+ * the `decorated ?? page` defensive fallback in the handler) plus the two
+ * share-URL pointers added by `withShareUrls`.
+ */
+const PageWithShareUrlsSchema = PageSchema.extend({
+  api_url: z.string(),
+  app_url: z.string(),
+});
+
+/**
+ * `/api/pages` list item. `body` / `passwordHash` are only present when the
+ * caller passes `?fields=full` (otherwise the slim `PageSummary` shape is
+ * used, which omits them entirely) — modeled as optional rather than a union
+ * since both shapes share every other field verbatim.
+ */
+const PageListItemSchema = PageSchema.partial({ body: true, passwordHash: true }).extend({
+  favorite: z.boolean(),
+  api_url: z.string(),
+  app_url: z.string(),
+});
+
 // ─── Route Definitions ──────────────────────────────────────────────────────
 
 const createPageRoute = route({
@@ -77,7 +105,16 @@ const createPageRoute = route({
     needsCredentials: z.array(z.string()).optional(),
   }),
   responses: {
-    201: { description: "Page created" },
+    201: {
+      description: "Page created",
+      schema: z.object({
+        id: z.string(),
+        key: AssetKeySchema,
+        version: z.literal(1),
+        api_url: z.string(),
+        app_url: z.string(),
+      }),
+    },
     400: { description: "Invalid body" },
     409: { description: "Slug already exists for this agent" },
   },
@@ -91,7 +128,7 @@ const getPageRoute = route({
   tags: ["Pages"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Page row" },
+    200: { description: "Page row", schema: PageWithShareUrlsSchema },
     404: { description: "Page not found" },
   },
 });
@@ -107,7 +144,7 @@ const resolvePageRoute = route({
     agentId: z.string().min(1).optional(),
   }),
   responses: {
-    200: { description: "Resolved page row" },
+    200: { description: "Resolved page row", schema: PageWithShareUrlsSchema },
     404: { description: "Page not found" },
   },
 });
@@ -164,7 +201,10 @@ const updatePageRoute = route({
     needsCredentials: z.array(z.string()).nullable().optional(),
   }),
   responses: {
-    200: { description: "Page updated" },
+    200: {
+      description: "Page updated",
+      schema: z.object({ id: z.string(), key: AssetKeySchema, version: z.number().int().min(1) }),
+    },
     404: { description: "Page not found" },
     413: { description: "Payload too large" },
   },
@@ -201,7 +241,15 @@ const listPagesRoute = route({
     fields: z.enum(["full", "slim"]).optional(),
   }),
   responses: {
-    200: { description: "Page list with totals + share-URL pointers" },
+    200: {
+      description: "Page list with totals + share-URL pointers",
+      schema: z.object({
+        pages: z.array(PageListItemSchema),
+        total: z.number().int(),
+        limit: z.number().int(),
+        offset: z.number().int(),
+      }),
+    },
   },
 });
 
@@ -223,7 +271,21 @@ const listPageActionsRoute = route({
   summary: "List JSON-page action allowlist (with param JSON Schemas)",
   tags: ["Pages"],
   responses: {
-    200: { description: "Action allowlist" },
+    200: {
+      description: "Action allowlist",
+      schema: z.object({
+        actions: z.array(
+          z.object({
+            name: z.string(),
+            description: z.string(),
+            // Rendered via `z.toJSONSchema()` — a draft-7 JSON Schema document,
+            // not otherwise modeled as a zod entity.
+            params: z.record(z.string(), z.unknown()),
+            sdkMethods: z.array(z.string()).optional(),
+          }),
+        ),
+      }),
+    },
   },
 });
 
@@ -265,7 +327,10 @@ const listPageVersionsRoute = route({
   tags: ["Pages"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Version list (newest first)" },
+    200: {
+      description: "Version list (newest first)",
+      schema: z.object({ versions: z.array(PageVersionSchema) }),
+    },
     404: { description: "Page not found" },
   },
 });
@@ -278,7 +343,7 @@ const getPageVersionRoute = route({
   tags: ["Pages"],
   params: z.object({ id: z.string(), version: z.coerce.number().int().min(1) }),
   responses: {
-    200: { description: "Version snapshot" },
+    200: { description: "Version snapshot", schema: PageVersionSchema },
     404: { description: "Page or version not found" },
   },
 });
@@ -412,17 +477,13 @@ export async function handlePages(
       });
       // First write has no prior snapshot — version 1 is implicit (the parent
       // IS v1). Subsequent edits land via PUT and bump the counter.
-      json(
-        res,
-        {
-          id: page.id,
-          key: page.key,
-          version: 1,
-          api_url: `${getApiBaseUrl()}/p/${page.id}`,
-          app_url: `${getAppBaseUrl()}/pages/${page.slug}`,
-        },
-        201,
-      );
+      createPageRoute.respond(res, 201, {
+        id: page.id,
+        key: page.key,
+        version: 1,
+        api_url: `${getApiBaseUrl()}/p/${page.id}`,
+        app_url: `${getAppBaseUrl()}/pages/${page.slug}`,
+      });
     } catch (err) {
       if (err instanceof AssetKeyAuthorizationError) {
         jsonError(res, err.message, err.statusCode);
@@ -444,13 +505,13 @@ export async function handlePages(
   if (listPageActionsRoute.match(req.method, pathSegments)) {
     const sdkSchema = z.toJSONSchema(swarmSdkActionParamsSchema, { target: "draft-7" });
     const callSchema = z.toJSONSchema(swarmCallActionParamsSchema, { target: "draft-7" });
-    json(res, {
+    listPageActionsRoute.respond(res, 200, {
       actions: [
         {
           name: "swarm.sdk",
           description: "Invoke a method on the in-SPA Swarm SDK with the viewer's bearer.",
           params: sdkSchema,
-          sdkMethods: SDK_METHODS,
+          sdkMethods: [...SDK_METHODS],
         },
         {
           name: "swarm.call",
@@ -478,7 +539,7 @@ export async function handlePages(
     }
     const favoriteScope = resolveHttpFavoriteOwner(req, myAgentId)?.scope;
     const [decorated] = withFavoriteFlags([page], { favoriteScope, itemType: "page" });
-    json(res, withShareUrls(decorated ?? page));
+    resolvePageRoute.respond(res, 200, withShareUrls(decorated ?? page));
     return true;
   }
 
@@ -513,7 +574,7 @@ export async function handlePages(
     }
     const favoriteScope = resolveHttpFavoriteOwner(req, myAgentId)?.scope;
     const decoratedPages = withFavoriteFlags(pages, { favoriteScope, itemType: "page" });
-    json(res, {
+    listPagesRoute.respond(res, 200, {
       pages: decoratedPages.map(withShareUrls),
       // Filter-aware total (real row count, not the current page's length) so
       // the UI pager reflects all pages, not just what this request returned.
@@ -545,7 +606,7 @@ export async function handlePages(
       res.end();
       return true;
     }
-    json(res, version);
+    getPageVersionRoute.respond(res, 200, version);
     return true;
   }
 
@@ -564,7 +625,7 @@ export async function handlePages(
       return true;
     }
     const versions = getPageVersions(parsed.params.id);
-    json(res, { versions });
+    listPageVersionsRoute.respond(res, 200, { versions });
     return true;
   }
 
@@ -586,7 +647,7 @@ export async function handlePages(
     }
     const favoriteScope = resolveHttpFavoriteOwner(req, myAgentId)?.scope;
     const [decorated] = withFavoriteFlags([page], { favoriteScope, itemType: "page" });
-    json(res, withShareUrls(decorated ?? page));
+    getPageRoute.respond(res, 200, withShareUrls(decorated ?? page));
     return true;
   }
 
@@ -651,7 +712,11 @@ export async function handlePages(
       res.end();
       return true;
     }
-    json(res, { id: updated.id, key: updated.key, version: pageEditCounter(updated.id) });
+    updatePageRoute.respond(res, 200, {
+      id: updated.id,
+      key: updated.key,
+      version: pageEditCounter(updated.id),
+    });
     return true;
   }
 

package/src/http/poll.ts

@@ -29,8 +29,14 @@ import { renderIdentity, resolveIdentity } from "../be/identity";
 import { hasCapability } from "../server";
 import { fetchChannelActivity } from "../slack/channel-activity";
 import { telemetry } from "../telemetry";
+import {
+  AgentTaskSchema,
+  BudgetRefusedTriggerSchema,
+  TaskAttachmentSchema,
+  UserSchema,
+} from "../types";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Budget-refused trigger envelope ────────────────────────────────────────
 
@@ -70,6 +76,78 @@ function buildBudgetRefusedTrigger(refusal: {
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
+// Slim attachment projection sent on `task_assigned` triggers — mirrors the
+// fields built by `attachmentsForTrigger` below (id, name, mimeType, sizeBytes).
+const PollTriggerAttachmentSchema = TaskAttachmentSchema.pick({
+  id: true,
+  name: true,
+  mimeType: true,
+  sizeBytes: true,
+});
+
+// Requester projection sent on `task_assigned` triggers — either the resolved
+// user's identity fields, or (when no `requestedByUserId` is recorded) just a
+// rendered `name` for the UNKNOWN-identity sentinel.
+const PollRequestedBySchema = UserSchema.pick({
+  name: true,
+  email: true,
+  role: true,
+  notes: true,
+});
+
+const PollTaskOfferedTriggerSchema = z.object({
+  type: z.literal("task_offered"),
+  taskId: z.string(),
+  task: AgentTaskSchema,
+});
+
+const PollTaskAssignedTriggerSchema = z.object({
+  type: z.literal("task_assigned"),
+  taskId: z.string(),
+  task: AgentTaskSchema.extend({
+    attachments: z.array(PollTriggerAttachmentSchema),
+  }),
+  requestedBy: PollRequestedBySchema.optional(),
+});
+
+// `budget_refused` reuses the canonical `BudgetRefusedTriggerSchema` entity
+// (src/types.ts) — it was already defined as the wire shape for this exact
+// `/api/poll` trigger back in Phase 3, mirrored by `buildBudgetRefusedTrigger`
+// below.
+
+const PollUnreadMentionsTriggerSchema = z.object({
+  type: z.literal("unread_mentions"),
+  mentionsCount: z.number(),
+  claimedChannels: z.array(z.string()),
+});
+
+const PollChannelActivityTriggerSchema = z.object({
+  type: z.literal("channel_activity"),
+  count: z.number(),
+  messages: z.array(
+    z.object({
+      channelId: z.string(),
+      channelName: z.string().optional(),
+      ts: z.string(),
+      user: z.string(),
+      text: z.string(),
+    }),
+  ),
+  cursorUpdates: z.array(z.object({ channelId: z.string(), ts: z.string() })),
+});
+
+const PollTriggerSchema = z.discriminatedUnion("type", [
+  PollTaskOfferedTriggerSchema,
+  PollTaskAssignedTriggerSchema,
+  BudgetRefusedTriggerSchema,
+  PollUnreadMentionsTriggerSchema,
+  PollChannelActivityTriggerSchema,
+]);
+
+const pollResponseSchema = z.object({
+  trigger: PollTriggerSchema.nullable(),
+});
+
 const pollTriggers = route({
   method: "get",
   path: "/api/poll",
@@ -78,7 +156,7 @@ const pollTriggers = route({
   tags: ["Poll"],
   auth: { apiKey: true, agentId: true },
   responses: {
-    200: { description: "Trigger data or null" },
+    200: { description: "Trigger data or null", schema: pollResponseSchema },
     400: { description: "Missing X-Agent-ID" },
     404: { description: "Agent not found" },
   },
@@ -128,7 +206,10 @@ const commitCursorsRoute = route({
     ),
   }),
   responses: {
-    200: { description: "Cursors committed" },
+    200: {
+      description: "Cursors committed",
+      schema: z.object({ success: z.literal(true), committed: z.number().int().nonnegative() }),
+    },
     400: { description: "Invalid request" },
   },
 });
@@ -151,7 +232,10 @@ export async function handlePoll(
         upsertChannelActivityCursor(channelId, ts);
       }
     }
-    json(res, { success: true, committed: parsed.body.cursorUpdates.length });
+    commitCursorsRoute.respond(res, 200, {
+      success: true,
+      committed: parsed.body.cursorUpdates.length,
+    });
     return true;
   }
 
@@ -535,7 +619,7 @@ export async function handlePoll(
       refusalSideEffects?: unknown;
       [key: string]: unknown;
     };
-    json(res, publicResult);
+    pollTriggers.respond(res, 200, publicResult as z.infer<typeof pollResponseSchema>);
     return true;
   }
 

package/src/http/pricing.ts

@@ -22,7 +22,7 @@ import {
 import { PricingProviderSchema, PricingRowSchema, PricingTokenClassSchema } from "../types";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -61,7 +61,10 @@ const listPricingForTriple = route({
   tags: ["Pricing"],
   params: PricingTriplePathParams,
   responses: {
-    200: { description: "Pricing rows (latest first)" },
+    200: {
+      description: "Pricing rows (latest first)",
+      schema: z.object({ rows: z.array(PricingRowSchema) }),
+    },
   },
 });
 
@@ -128,7 +131,7 @@ export async function handlePricing(
   if (listAllPricing.match(req.method, pathSegments)) {
     const parsed = await listAllPricing.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    json(res, { rows: getAllPricingRows() });
+    listAllPricing.respond(res, 200, { rows: getAllPricingRows() });
     return true;
   }
 
@@ -147,7 +150,7 @@ export async function handlePricing(
       jsonError(res, "No pricing row in effect", 404);
       return true;
     }
-    json(res, row);
+    getActivePricing.respond(res, 200, row);
     return true;
   }
 
@@ -193,7 +196,7 @@ export async function handlePricing(
       parsed.params.model,
       parsed.params.tokenClass,
     );
-    json(res, { rows });
+    listPricingForTriple.respond(res, 200, { rows });
     return true;
   }
 
@@ -224,7 +227,7 @@ export async function handlePricing(
         },
       });
 
-      json(res, row, 201);
+      insertPricing.respond(res, 201, row);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       // bun:sqlite raises SQLITE_CONSTRAINT for PK collision. Surface as 409.

package/src/http/prompt-templates.ts

@@ -12,9 +12,42 @@ import {
 } from "../be/db";
 import { getAllTemplateDefinitions, getTemplateDefinition } from "../prompts/registry";
 import { resolveTemplate } from "../prompts/resolver";
+import { PromptTemplateHistorySchema, PromptTemplateSchema } from "../types";
 import { interpolate } from "../utils/template";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
+
+// ─── Response Schemas ────────────────────────────────────────────────────────
+
+/** Mirrors `EventTemplateDefinition["variables"]` entries from src/prompts/registry.ts */
+const VariableDefinitionSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  example: z.string().optional(),
+});
+
+/** Mirrors the plain-object projection of `EventTemplateDefinition` the handlers send. */
+const EventTemplateDefinitionResponseSchema = z.object({
+  eventType: z.string(),
+  header: z.string(),
+  defaultBody: z.string(),
+  variables: z.array(VariableDefinitionSchema),
+  category: z.enum(["event", "system", "common", "task_lifecycle", "session"]),
+});
+
+/** Mirrors `ResolveResult` from src/prompts/resolver.ts */
+const ResolveResultSchema = z.object({
+  text: z.string(),
+  templateId: z.string().optional(),
+  scope: z.string().optional(),
+  skipped: z.boolean(),
+  unresolved: z.array(z.string()),
+});
+
+/** Mirrors the return type of `resolvePromptTemplate` in src/be/db.ts */
+const DbResolveResultSchema = z
+  .union([z.object({ template: PromptTemplateSchema }), z.object({ skip: z.literal(true) })])
+  .nullable();
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
@@ -30,7 +63,14 @@ const resolvedRoute = route({
     repoId: z.string().optional(),
   }),
   responses: {
-    200: { description: "Resolved template info" },
+    200: {
+      description: "Resolved template info",
+      schema: z.object({
+        resolution: ResolveResultSchema,
+        dbResult: DbResolveResultSchema,
+        definition: EventTemplateDefinitionResponseSchema.nullable(),
+      }),
+    },
     400: { description: "Missing eventType" },
   },
   auth: { apiKey: true },
@@ -43,7 +83,10 @@ const eventsRoute = route({
   summary: "List all registered event types with their available variables",
   tags: ["PromptTemplates"],
   responses: {
-    200: { description: "List of event template definitions" },
+    200: {
+      description: "List of event template definitions",
+      schema: z.object({ events: z.array(EventTemplateDefinitionResponseSchema) }),
+    },
   },
   auth: { apiKey: true },
 });
@@ -60,7 +103,10 @@ const previewRoute = route({
     variables: z.record(z.string(), z.unknown()).optional(),
   }),
   responses: {
-    200: { description: "Rendered template preview" },
+    200: {
+      description: "Rendered template preview",
+      schema: z.object({ rendered: z.string(), unresolved: z.array(z.string()) }),
+    },
     400: { description: "Validation error" },
   },
   auth: { apiKey: true },
@@ -79,7 +125,7 @@ const renderRoute = route({
     repoId: z.string().optional(),
   }),
   responses: {
-    200: { description: "Fully resolved and interpolated template" },
+    200: { description: "Fully resolved and interpolated template", schema: ResolveResultSchema },
     400: { description: "Validation error" },
   },
   auth: { apiKey: true },
@@ -94,7 +140,10 @@ const checkoutRoute = route({
   params: z.object({ id: z.string() }),
   body: z.object({ version: z.number() }),
   responses: {
-    200: { description: "Checked-out template" },
+    200: {
+      description: "Checked-out template",
+      schema: z.object({ template: PromptTemplateSchema }),
+    },
     400: { description: "Validation error" },
     404: { description: "Template or version not found" },
   },
@@ -109,7 +158,7 @@ const resetRoute = route({
   tags: ["PromptTemplates"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Reset template" },
+    200: { description: "Reset template", schema: z.object({ template: PromptTemplateSchema }) },
     404: { description: "Template not found or no code default available" },
   },
   auth: { apiKey: true },
@@ -123,7 +172,13 @@ const getByIdRoute = route({
   tags: ["PromptTemplates"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Template with history" },
+    200: {
+      description: "Template with history",
+      schema: z.object({
+        template: PromptTemplateSchema,
+        history: z.array(PromptTemplateHistorySchema),
+      }),
+    },
     404: { description: "Template not found" },
   },
   auth: { apiKey: true },
@@ -137,7 +192,10 @@ const deleteByIdRoute = route({
   tags: ["PromptTemplates"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Template deleted" },
+    200: {
+      description: "Template deleted",
+      schema: z.object({ deleted: z.literal(true) }),
+    },
     400: { description: "Cannot delete default template" },
     404: { description: "Template not found" },
   },
@@ -157,7 +215,10 @@ const listRoute = route({
     isDefault: z.enum(["true", "false"]).optional(),
   }),
   responses: {
-    200: { description: "List of prompt templates" },
+    200: {
+      description: "List of prompt templates",
+      schema: z.object({ templates: z.array(PromptTemplateSchema) }),
+    },
   },
   auth: { apiKey: true },
 });
@@ -178,7 +239,10 @@ const upsertRoute = route({
     changeReason: z.string().optional(),
   }),
   responses: {
-    200: { description: "Upserted template" },
+    200: {
+      description: "Upserted template",
+      schema: z.object({ template: PromptTemplateSchema }),
+    },
     400: { description: "Validation error" },
   },
   auth: { apiKey: true },
@@ -207,7 +271,7 @@ export async function handlePromptTemplates(
     const dbResult = resolvePromptTemplate(eventType, agentId, repoId);
     const definition = getTemplateDefinition(eventType);
 
-    json(res, {
+    resolvedRoute.respond(res, 200, {
       resolution: result,
       dbResult,
       definition: definition
@@ -229,7 +293,7 @@ export async function handlePromptTemplates(
     if (!parsed) return true;
 
     const definitions = getAllTemplateDefinitions();
-    json(res, {
+    eventsRoute.respond(res, 200, {
       events: definitions.map((d) => ({
         eventType: d.eventType,
         header: d.header,
@@ -253,7 +317,7 @@ export async function handlePromptTemplates(
     const composed = header ? `${header}\n\n${templateBody}` : templateBody;
     const { result: rendered, unresolved } = interpolate(composed, variables ?? {});
 
-    json(res, { rendered, unresolved });
+    previewRoute.respond(res, 200, { rendered, unresolved });
     return true;
   }
 
@@ -264,7 +328,7 @@ export async function handlePromptTemplates(
 
     const { eventType, variables, agentId, repoId } = parsed.body;
     const result = resolveTemplate(eventType, variables ?? {}, { agentId, repoId });
-    json(res, result);
+    renderRoute.respond(res, 200, result);
     return true;
   }
 
@@ -275,7 +339,7 @@ export async function handlePromptTemplates(
 
     try {
       const template = checkoutPromptTemplate(parsed.params.id, parsed.body.version);
-      json(res, { template });
+      checkoutRoute.respond(res, 200, { template });
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
       if (message.includes("not found")) {
@@ -306,7 +370,7 @@ export async function handlePromptTemplates(
 
     try {
       const template = resetPromptTemplateToDefault(parsed.params.id, definition.defaultBody);
-      json(res, { template });
+      resetRoute.respond(res, 200, { template });
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
       jsonError(res, message, 400);
@@ -326,7 +390,7 @@ export async function handlePromptTemplates(
     }
 
     const history = getPromptTemplateHistory(parsed.params.id);
-    json(res, { template, history });
+    getByIdRoute.respond(res, 200, { template, history });
     return true;
   }
 
@@ -341,7 +405,7 @@ export async function handlePromptTemplates(
         jsonError(res, "Prompt template not found", 404);
         return true;
       }
-      json(res, { deleted: true });
+      deleteByIdRoute.respond(res, 200, { deleted: true });
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
       jsonError(res, message, 400);
@@ -361,7 +425,7 @@ export async function handlePromptTemplates(
       isDefault: parsed.query.isDefault ? parsed.query.isDefault === "true" : undefined,
     });
 
-    json(res, { templates });
+    listRoute.respond(res, 200, { templates });
     return true;
   }
 
@@ -400,7 +464,7 @@ export async function handlePromptTemplates(
         changedBy,
         changeReason,
       });
-      json(res, { template });
+      upsertRoute.respond(res, 200, { template });
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
       jsonError(res, message, 500);