@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/src/http/users.ts

@@ -9,6 +9,7 @@
  *
  * Endpoint set:
  *
+ *   GET    /api/whoami
  *   GET    /api/users
  *   POST   /api/users
  *   GET    /api/users/unmapped                       (must precede /:id)
@@ -47,9 +48,11 @@ import {
   revokeToken,
   unlinkIdentity,
 } from "../be/users";
+import { UserSchema } from "../types";
+import { getRequestAuth } from "../utils/request-auth-context";
 import { getOperatorActor } from "./operator-actor";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Response composition ────────────────────────────────────────────────────
 
@@ -78,8 +81,85 @@ function syncUserBudgetMirror(userId: string, dailyBudgetUsd: number | null | un
   upsertBudget("user", userId, dailyBudgetUsd);
 }
 
+// ─── Response schemas ────────────────────────────────────────────────────────
+
+const UserIdentityLinkSchema = z.object({
+  kind: z.string(),
+  externalId: z.string(),
+});
+
+const UserTokenSummarySchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  label: z.string().nullable(),
+  tokenPreview: z.string(),
+  createdAt: z.string(),
+  lastUsedAt: z.string().nullable(),
+  revokedAt: z.string().nullable(),
+});
+
+const IdentityEventSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  // `IdentityEvent.eventType` is read back from the DB as a plain `string`
+  // (the CHECK constraint guarantees membership in `IdentityEventTypeSchema`,
+  // but the read path's static type is not narrowed to the enum).
+  eventType: z.string(),
+  actor: z.string(),
+  before: z.unknown().nullable(),
+  after: z.unknown().nullable(),
+  createdAt: z.string(),
+});
+
+/** `composeUser()`'s shape — base user row + identities + token summaries + recent events. */
+const ComposedUserSchema = UserSchema.extend({
+  identities: z.array(UserIdentityLinkSchema),
+  tokens: z.array(UserTokenSummarySchema),
+  recentEvents: z.array(IdentityEventSchema),
+});
+
+/** `collectUnmappedForKind()`'s per-externalId grouped shape. */
+const UnmappedIdentitySchema = z.object({
+  kind: z.string(),
+  externalId: z.string(),
+  lastSeenAt: z.string().nullable(),
+  count: z.number(),
+  sampleEventType: z.string().nullable(),
+  sampleContext: z.unknown().nullable(),
+});
+
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
+/**
+ * DES-771: identity resolution for embedded dashboards. A client holding a
+ * user-bound `aswt_` token learns which user the server attributes its
+ * requests to (the token forces requester/audit attribution server-side, so
+ * this is the only identity the client can act as). The operator key resolves
+ * to `kind: "operator"` with no bound user.
+ */
+const whoamiRoute = route({
+  method: "get",
+  path: "/api/whoami",
+  pattern: ["api", "whoami"],
+  summary: "Resolve the authenticated principal behind the presented bearer",
+  tags: ["Users"],
+  responses: {
+    200: {
+      description: "Authenticated principal",
+      schema: z.object({
+        kind: z.enum(["operator", "user"]),
+        // `z.union([UserSchema, z.null()])`, NOT `UserSchema.nullable()`:
+        // .nullable() on a registered schema rewrites the shared
+        // `components.schemas.User` to `object | null` for every consumer;
+        // the union keeps nullability local to this response field.
+        user: z.union([UserSchema, z.null()]),
+      }),
+    },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
 const listUsers = route({
   method: "get",
   path: "/api/users",
@@ -90,7 +170,10 @@ const listUsers = route({
     recentEvents: z.coerce.number().int().min(0).max(50).optional(),
   }),
   responses: {
-    200: { description: "List of users" },
+    200: {
+      description: "List of users",
+      schema: z.object({ users: z.array(ComposedUserSchema.nullable()) }),
+    },
     401: { description: "Unauthorized" },
   },
   auth: { apiKey: true },
@@ -118,7 +201,10 @@ const createUserRoute = route({
       .optional(),
   }),
   responses: {
-    200: { description: "User created" },
+    200: {
+      description: "User created",
+      schema: z.object({ user: ComposedUserSchema.nullable() }),
+    },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
   },
@@ -136,7 +222,10 @@ const listUnmapped = route({
     limit: z.coerce.number().int().min(1).max(1000).optional(),
   }),
   responses: {
-    200: { description: "List of unmapped identities sorted by count DESC, lastSeenAt DESC" },
+    200: {
+      description: "List of unmapped identities sorted by count DESC, lastSeenAt DESC",
+      schema: z.object({ unmapped: z.array(UnmappedIdentitySchema) }),
+    },
     401: { description: "Unauthorized" },
   },
   auth: { apiKey: true },
@@ -158,7 +247,10 @@ const resolveUnmapped = route({
     }),
   ]),
   responses: {
-    200: { description: "Identity linked + kv entries cleared" },
+    200: {
+      description: "Identity linked + kv entries cleared",
+      schema: z.object({ user: ComposedUserSchema.nullable() }),
+    },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
     404: { description: "Target user not found" },
@@ -177,7 +269,10 @@ const getUserRoute = route({
     recentEvents: z.coerce.number().int().min(0).max(200).optional(),
   }),
   responses: {
-    200: { description: "User row" },
+    200: {
+      description: "User row",
+      schema: z.object({ user: ComposedUserSchema }),
+    },
     401: { description: "Unauthorized" },
     404: { description: "User not found" },
   },
@@ -213,7 +308,10 @@ const updateUserRoute = route({
       message: "At least one field must be provided",
     }),
   responses: {
-    200: { description: "User updated" },
+    200: {
+      description: "User updated",
+      schema: z.object({ user: ComposedUserSchema.nullable() }),
+    },
     400: { description: "Validation error or empty body" },
     401: { description: "Unauthorized" },
     404: { description: "User not found" },
@@ -234,7 +332,14 @@ const mintUserMcpTokenRoute = route({
     label: z.string().nullable().optional(),
   }),
   responses: {
-    200: { description: "Minted token plaintext, token summary and composed user" },
+    200: {
+      description: "Minted token plaintext, token summary and composed user",
+      schema: z.object({
+        plaintext: z.string(),
+        token: UserTokenSummarySchema.optional(),
+        user: ComposedUserSchema.nullable(),
+      }),
+    },
     401: { description: "Unauthorized" },
     404: { description: "User not found" },
   },
@@ -249,7 +354,10 @@ const revokeUserMcpTokenRoute = route({
   tags: ["Users"],
   params: z.object({ id: z.string(), tokenId: z.string() }),
   responses: {
-    200: { description: "Composed user after token revocation" },
+    200: {
+      description: "Composed user after token revocation",
+      schema: z.object({ user: ComposedUserSchema.nullable() }),
+    },
     401: { description: "Unauthorized" },
     404: { description: "User or token not found" },
   },
@@ -265,7 +373,10 @@ const mergeUsersRoute = route({
   params: z.object({ id: z.string() }),
   body: z.object({ sourceUserId: z.string().min(1) }),
   responses: {
-    200: { description: "Merged user" },
+    200: {
+      description: "Merged user",
+      schema: z.object({ user: ComposedUserSchema.nullable() }),
+    },
     400: { description: "Validation error (e.g. target == source)" },
     401: { description: "Unauthorized" },
     404: { description: "Target or source user not found" },
@@ -285,7 +396,10 @@ const listEventsRoute = route({
     before: z.string().optional(),
   }),
   responses: {
-    200: { description: "Array of identity events" },
+    200: {
+      description: "Array of identity events",
+      schema: z.object({ events: z.array(IdentityEventSchema) }),
+    },
     401: { description: "Unauthorized" },
     404: { description: "User not found" },
   },
@@ -301,7 +415,10 @@ const addIdentityRoute = route({
   params: z.object({ id: z.string() }),
   body: z.object({ kind: z.string().min(1), externalId: z.string().min(1) }),
   responses: {
-    200: { description: "Updated identity list" },
+    200: {
+      description: "Updated identity list",
+      schema: z.object({ identities: z.array(UserIdentityLinkSchema) }),
+    },
     400: { description: "Validation error or PK collision" },
     401: { description: "Unauthorized" },
     404: { description: "User not found" },
@@ -317,7 +434,10 @@ const deleteIdentityRoute = route({
   tags: ["Users"],
   params: z.object({ id: z.string(), kind: z.string(), externalId: z.string() }),
   responses: {
-    200: { description: "Updated identity list" },
+    200: {
+      description: "Updated identity list",
+      schema: z.object({ identities: z.array(UserIdentityLinkSchema) }),
+    },
     401: { description: "Unauthorized" },
     404: { description: "User not found" },
   },
@@ -403,13 +523,26 @@ export async function handleUsers(
   pathSegments: string[],
   queryParams: URLSearchParams,
 ): Promise<boolean> {
+  // ─── GET /api/whoami ───────────────────────────────────────────────────────
+  if (whoamiRoute.match(req.method, pathSegments)) {
+    const parsed = await whoamiRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const auth = getRequestAuth(req);
+    if (auth?.kind === "user") {
+      whoamiRoute.respond(res, 200, { kind: "user", user: auth.user });
+    } else {
+      whoamiRoute.respond(res, 200, { kind: "operator", user: null });
+    }
+    return true;
+  }
+
   // ─── GET /api/users ────────────────────────────────────────────────────────
   if (listUsers.match(req.method, pathSegments)) {
     const parsed = await listUsers.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     const recentLimit = parsed.query.recentEvents ?? 5;
     const users = getAllUsers().map((u) => composeUser(u.id, recentLimit));
-    json(res, { users });
+    listUsers.respond(res, 200, { users });
     return true;
   }
 
@@ -433,7 +566,7 @@ export async function handleUsers(
         });
       }
       const composed = composeUser(user.id);
-      json(res, { user: composed });
+      createUserRoute.respond(res, 200, { user: composed });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to create user", 500);
     }
@@ -454,7 +587,7 @@ export async function handleUsers(
       const bl = b.lastSeenAt ?? "";
       return bl.localeCompare(al);
     });
-    json(res, { unmapped: rows.slice(0, limit) });
+    listUnmapped.respond(res, 200, { unmapped: rows.slice(0, limit) });
     return true;
   }
 
@@ -494,7 +627,7 @@ export async function handleUsers(
       deleteKv(ns, `${externalId}:meta`);
       deleteKv(ns, `${externalId}:count`);
       const user = composeUser(targetUserId);
-      json(res, { user });
+      resolveUnmapped.respond(res, 200, { user });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to resolve unmapped", 500);
     }
@@ -513,7 +646,7 @@ export async function handleUsers(
       limit: parsed.query.limit,
       before: parsed.query.before,
     });
-    json(res, { events });
+    listEventsRoute.respond(res, 200, { events });
     return true;
   }
 
@@ -531,7 +664,11 @@ export async function handleUsers(
     try {
       const { tokenId, plaintext } = mintToken(parsed.params.id, parsed.body.label ?? null, actor);
       const token = listUserTokens(parsed.params.id).find((t) => t.id === tokenId);
-      json(res, { plaintext, token, user: composeUser(parsed.params.id) });
+      mintUserMcpTokenRoute.respond(res, 200, {
+        plaintext,
+        token,
+        user: composeUser(parsed.params.id),
+      });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to mint token", 500);
     }
@@ -559,7 +696,7 @@ export async function handleUsers(
 
     try {
       revokeToken(parsed.params.tokenId, actor);
-      json(res, { user: composeUser(parsed.params.id) });
+      revokeUserMcpTokenRoute.respond(res, 200, { user: composeUser(parsed.params.id) });
     } catch (err) {
       const message = err instanceof Error ? err.message : "Failed to revoke token";
       if (message.includes("Token not found")) {
@@ -583,7 +720,7 @@ export async function handleUsers(
     }
     try {
       linkIdentity(parsed.params.id, parsed.body.kind, parsed.body.externalId, actor);
-      json(res, { identities: getUserIdentities(parsed.params.id) });
+      addIdentityRoute.respond(res, 200, { identities: getUserIdentities(parsed.params.id) });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to link identity", 400);
     }
@@ -607,7 +744,7 @@ export async function handleUsers(
       const kind = decodeURIComponent(parsed.params.kind);
       const externalId = decodeURIComponent(parsed.params.externalId);
       unlinkIdentity(parsed.params.id, kind, externalId, actor);
-      json(res, { identities: getUserIdentities(parsed.params.id) });
+      deleteIdentityRoute.respond(res, 200, { identities: getUserIdentities(parsed.params.id) });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to unlink identity", 500);
     }
@@ -692,7 +829,7 @@ export async function handleUsers(
 
       // Re-compose AFTER the event so the response surfaces the merge event in
       // recentEvents (otherwise the timeline is missing the event we just wrote).
-      json(res, { user: composeUser(targetId) });
+      mergeUsersRoute.respond(res, 200, { user: composeUser(targetId) });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to merge users", 500);
     }
@@ -708,7 +845,7 @@ export async function handleUsers(
       jsonError(res, "User not found", 404);
       return true;
     }
-    json(res, { user: composed });
+    getUserRoute.respond(res, 200, { user: composed });
     return true;
   }
 
@@ -826,7 +963,7 @@ export async function handleUsers(
       }
 
       const composed = composeUser(parsed.params.id);
-      json(res, { user: composed });
+      updateUserRoute.respond(res, 200, { user: composed });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : "Failed to update user", 500);
     }

package/src/http/utils.ts

@@ -79,13 +79,23 @@ export function agentWithCapacity<T extends { id: string; maxTasks?: number }>(
   };
 }
 
-/** Parse JSON body from incoming request */
+/**
+ * Parse the JSON body of an incoming request.
+ *
+ * An empty (or whitespace-only) body parses as `{}` rather than throwing:
+ * `JSON.parse("")` raises a SyntaxError, and the `route()` factory only
+ * converts ZodErrors — so a bodyless POST used to escape as a 500. Yielding
+ * `{}` lets an all-optional body schema accept a bodyless request and turns a
+ * required-body schema's failure into the honest 400 its validation produces.
+ */
 export async function parseBody<T = unknown>(req: IncomingMessage): Promise<T> {
   const chunks: Buffer[] = [];
   for await (const chunk of req) {
     chunks.push(chunk as Buffer);
   }
-  return JSON.parse(Buffer.concat(chunks).toString()) as T;
+  const raw = Buffer.concat(chunks).toString();
+  if (raw.trim() === "") return {} as T;
+  return JSON.parse(raw) as T;
 }
 
 /**

package/src/http/webhooks.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
 import type { AgentMailWebhookPayload } from "../agentmail";
 import {
   handleMessageReceived,
@@ -57,6 +58,16 @@ import { route } from "./route-def";
 
 // ─── Route Definitions (documentation only — webhooks handle their own body parsing) ─
 
+/**
+ * Shared shape returned by the GitHub/GitLab dispatch handlers in
+ * ../github/handlers.ts and ../gitlab/handlers.ts — `{ created: boolean;
+ * taskId?: string }`, echoed back verbatim as the webhook ack body.
+ */
+const WebhookDispatchResultSchema = z.object({
+  created: z.boolean(),
+  taskId: z.string().optional(),
+});
+
 const githubWebhook = route({
   method: "post",
   path: "/api/github/webhook",
@@ -65,7 +76,10 @@ const githubWebhook = route({
   tags: ["Webhooks"],
   auth: { apiKey: false },
   responses: {
-    200: { description: "Event processed" },
+    200: {
+      description: "Event processed",
+      schema: z.union([z.object({ message: z.literal("pong") }), WebhookDispatchResultSchema]),
+    },
     401: { description: "Invalid signature" },
     503: { description: "GitHub integration not configured" },
   },
@@ -79,7 +93,7 @@ const gitlabWebhook = route({
   tags: ["Webhooks"],
   auth: { apiKey: false },
   responses: {
-    200: { description: "Event processed" },
+    200: { description: "Event processed", schema: WebhookDispatchResultSchema },
     401: { description: "Invalid token" },
     503: { description: "GitLab integration not configured" },
   },
@@ -93,7 +107,7 @@ const agentmailWebhook = route({
   tags: ["Webhooks"],
   auth: { apiKey: false },
   responses: {
-    200: { description: "Event received" },
+    200: { description: "Event received", schema: z.object({ received: z.literal(true) }) },
     401: { description: "Invalid signature" },
     503: { description: "AgentMail integration not configured" },
   },
@@ -107,7 +121,13 @@ const kapsoWebhook = route({
   tags: ["Webhooks"],
   auth: { apiKey: false },
   responses: {
-    200: { description: "Event received" },
+    200: {
+      description: "Event received",
+      schema: z.object({
+        received: z.literal(true),
+        routing: z.enum(["skip", "duplicate", "workflow", "task", "no_mapping", "error"]),
+      }),
+    },
     401: { description: "Invalid signature" },
     503: { description: "Kapso integration not configured" },
   },
@@ -213,8 +233,7 @@ export async function handleWebhooks(
 
     if (eventType === "ping") {
       console.log("[GitHub] Received ping event - webhook configured successfully");
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ message: "pong" }));
+      githubWebhook.respond(res, 200, { message: "pong" });
       return true;
     }
 
@@ -309,8 +328,7 @@ export async function handleWebhooks(
         }
       }
 
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify(result));
+      githubWebhook.respond(res, 200, result);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : String(err);
       console.error(`[GitHub] Error handling ${eventType} event: ${errorMessage}`);
@@ -425,8 +443,7 @@ export async function handleWebhooks(
         }
       }
 
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify(result));
+      gitlabWebhook.respond(res, 200, result);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : String(err);
       console.error(`[GitLab] Error handling ${objectKind} event: ${errorMessage}`);
@@ -471,8 +488,7 @@ export async function handleWebhooks(
 
     // Return 200 immediately — Svix best practice to avoid retries.
     // Processing happens asynchronously below; dedup is handled in handlers.ts.
-    res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ received: true }));
+    agentmailWebhook.respond(res, 200, { received: true });
 
     const payload = verified as AgentMailWebhookPayload;
 
@@ -602,8 +618,7 @@ export async function handleWebhooks(
           console.log(`[Kapso] Skipping event: ${routing.reason}`);
           break;
       }
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ received: true, routing: routing.kind }));
+      kapsoWebhook.respond(res, 200, { received: true, routing: routing.kind });
     } catch (err) {
       // Never fail the delivery on a downstream dispatch error — we already
       // verified + deduped. Log and ack so Kapso doesn't hammer retries.
@@ -613,8 +628,7 @@ export async function handleWebhooks(
       } else {
         console.error(`[Kapso] Error handling inbound event: ${errorMessage}`);
       }
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ received: true, routing: "error" }));
+      kapsoWebhook.respond(res, 200, { received: true, routing: "error" });
     }
     return true;
   }

package/src/http/workflow-events.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { getWorkflowRun } from "../be/db";
 import { workflowEventBus } from "../workflows/event-bus";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
@@ -30,7 +30,14 @@ const runScopedSignalRoute = route({
     payload: z.record(z.string(), z.unknown()).optional(),
   }),
   responses: {
-    200: { description: "Event emitted" },
+    200: {
+      description: "Event emitted",
+      schema: z.object({
+        ok: z.literal(true),
+        name: z.string(),
+        runId: z.string(),
+      }),
+    },
     404: { description: "Workflow run not found" },
     400: { description: "Validation error" },
   },
@@ -56,7 +63,13 @@ const globalSignalRoute = route({
     payload: z.record(z.string(), z.unknown()).optional(),
   }),
   responses: {
-    200: { description: "Event emitted" },
+    200: {
+      description: "Event emitted",
+      schema: z.object({
+        ok: z.literal(true),
+        name: z.string(),
+      }),
+    },
     400: { description: "Validation error" },
   },
   auth: { apiKey: true },
@@ -84,7 +97,7 @@ export async function handleWorkflowEvents(
     const payload = { ...(parsed.body.payload ?? {}), _runId: parsed.params.runId };
     workflowEventBus.emit(parsed.body.name, payload);
 
-    json(res, {
+    runScopedSignalRoute.respond(res, 200, {
       ok: true,
       name: parsed.body.name,
       runId: parsed.params.runId,
@@ -99,7 +112,7 @@ export async function handleWorkflowEvents(
 
     workflowEventBus.emit(parsed.body.name, parsed.body.payload ?? {});
 
-    json(res, { ok: true, name: parsed.body.name });
+    globalSignalRoute.respond(res, 200, { ok: true, name: parsed.body.name });
     return true;
   }