@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/src/http/metrics.ts

@@ -17,14 +17,16 @@ import {
   type Metric,
   MetricDefinitionSchema,
   type MetricParam,
+  MetricSchema,
   type MetricSummary,
   type MetricVariable,
   MetricVersionSchema,
   type MetricWidget,
+  MetricWidgetSchema,
 } from "../types";
 import { assertSelectOnlyQuery, executeReadOnlyQuery } from "./db-query";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 const DEFAULT_METRIC_MAX_ROWS = 100;
 const HARD_METRIC_MAX_ROWS = 500;
@@ -192,6 +194,18 @@ const metricDefinitionBody = z.object({
   definition: MetricDefinitionSchema,
 });
 
+// `{ id, version }` shape sent by both create (always version 1) and update
+// (the next edit counter) — see `metricEditCounter` below.
+const metricIdVersionSchema = z.object({
+  id: z.string(),
+  version: z.number().int().min(1),
+});
+
+// `MetricSummary` (see ../types) is `Omit<Metric, "definition">` — the "slim"
+// list projection returned by `listMetricsByAgent`/`listAllMetrics` when
+// `fields=slim`.
+const metricSummarySchema = MetricSchema.omit({ definition: true });
+
 const createMetricRoute = route({
   method: "post",
   path: "/api/metrics/definitions",
@@ -200,7 +214,7 @@ const createMetricRoute = route({
   tags: ["Metrics"],
   body: metricDefinitionBody,
   responses: {
-    201: { description: "Metric created" },
+    201: { description: "Metric created", schema: metricIdVersionSchema },
     400: { description: "Invalid metric definition" },
     409: { description: "Slug already exists for this agent" },
   },
@@ -219,7 +233,15 @@ const listMetricsRoute = route({
     fields: z.enum(["full", "slim"]).optional(),
   }),
   responses: {
-    200: { description: "Metric definitions" },
+    200: {
+      description: "Metric definitions",
+      schema: z.object({
+        metrics: z.array(z.union([MetricSchema, metricSummarySchema])),
+        total: z.number(),
+        limit: z.number(),
+        offset: z.number(),
+      }),
+    },
   },
 });
 
@@ -231,7 +253,7 @@ const getMetricRoute = route({
   tags: ["Metrics"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Metric definition" },
+    200: { description: "Metric definition", schema: MetricSchema },
     404: { description: "Metric not found" },
   },
 });
@@ -245,7 +267,7 @@ const updateMetricRoute = route({
   params: z.object({ id: z.string() }),
   body: metricDefinitionBody.partial(),
   responses: {
-    200: { description: "Metric updated" },
+    200: { description: "Metric updated", schema: metricIdVersionSchema },
     404: { description: "Metric not found" },
   },
 });
@@ -263,6 +285,32 @@ const deleteMetricRoute = route({
   },
 });
 
+// Wire shape of a single widget's query result inside a `run` response — see
+// `runMetricWidget` below. `rows` is re-keyed from column-array form to
+// column-name-keyed objects, so each row's field set is query-dependent.
+const metricRunWidgetResultSchema = z.object({
+  columns: z.array(z.string()),
+  rows: z.array(z.record(z.string(), z.unknown())),
+  elapsed: z.number(),
+  total: z.number(),
+  truncated: z.boolean(),
+  maxRows: z.number(),
+});
+
+// Full `runMetric()` response — see that function below.
+const metricRunResultSchema = z.object({
+  metric: MetricSchema,
+  variables: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])),
+  widgets: z.array(
+    z.object({
+      widget: MetricWidgetSchema,
+      result: metricRunWidgetResultSchema,
+    }),
+  ),
+  // Kept as the first widget result for older callers during the PR cycle.
+  result: metricRunWidgetResultSchema.optional(),
+});
+
 const runMetricRoute = route({
   method: "post",
   path: "/api/metrics/definitions/{id}/run",
@@ -272,7 +320,7 @@ const runMetricRoute = route({
   params: z.object({ id: z.string() }),
   body: MetricRunBodySchema,
   responses: {
-    200: { description: "Metric result" },
+    200: { description: "Metric result", schema: metricRunResultSchema },
     400: { description: "Invalid or disallowed query" },
     404: { description: "Metric not found" },
   },
@@ -286,7 +334,10 @@ const listMetricVersionsRoute = route({
   tags: ["Metrics"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Metric version list" },
+    200: {
+      description: "Metric version list",
+      schema: z.object({ versions: z.array(MetricVersionSchema) }),
+    },
     404: { description: "Metric not found" },
   },
 });
@@ -299,11 +350,18 @@ const getMetricVersionRoute = route({
   tags: ["Metrics"],
   params: z.object({ id: z.string(), version: z.coerce.number().int().min(1) }),
   responses: {
-    200: { description: "Metric version" },
+    200: { description: "Metric version", schema: MetricVersionSchema },
     404: { description: "Metric or version not found" },
   },
 });
 
+// z.toJSONSchema() output is always a JSON object at the root (draft-7 for an
+// object-typed zod schema); nested shape is JSON-Schema-generic, not modeled
+// field-by-field here.
+const metricJsonSchemaResponseSchema = z.object({
+  schema: z.record(z.string(), z.unknown()),
+});
+
 const metricSchemaRoute = route({
   method: "get",
   path: "/api/metrics/schema",
@@ -311,7 +369,7 @@ const metricSchemaRoute = route({
   summary: "Get the metric definition JSON Schema",
   tags: ["Metrics"],
   responses: {
-    200: { description: "Metric definition JSON Schema" },
+    200: { description: "Metric definition JSON Schema", schema: metricJsonSchemaResponseSchema },
   },
 });
 
@@ -328,7 +386,9 @@ export async function handleMetrics(
   myAgentId: string | undefined,
 ): Promise<boolean> {
   if (metricSchemaRoute.match(req.method, pathSegments)) {
-    json(res, { schema: z.toJSONSchema(MetricDefinitionSchema, { target: "draft-7" }) });
+    metricSchemaRoute.respond(res, 200, {
+      schema: z.toJSONSchema(MetricDefinitionSchema, { target: "draft-7" }),
+    });
     return true;
   }
 
@@ -347,7 +407,7 @@ export async function handleMetrics(
         description: parsed.body.description ?? undefined,
         definition,
       });
-      json(res, { id: metric.id, version: 1 }, 201);
+      createMetricRoute.respond(res, 201, { id: metric.id, version: 1 });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       if (msg.includes("UNIQUE")) {
@@ -379,7 +439,7 @@ export async function handleMetrics(
         : listAllMetrics(limit, offset, { slim: true });
       total = countAllMetrics();
     }
-    json(res, { metrics, total, limit, offset });
+    listMetricsRoute.respond(res, 200, { metrics, total, limit, offset });
     return true;
   }
 
@@ -393,7 +453,7 @@ export async function handleMetrics(
       return true;
     }
     try {
-      json(res, runMetric(metric, parsed.body?.variables ?? {}));
+      runMetricRoute.respond(res, 200, runMetric(metric, parsed.body?.variables ?? {}));
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : String(err));
     }
@@ -414,7 +474,7 @@ export async function handleMetrics(
       res.end();
       return true;
     }
-    json(res, MetricVersionSchema.parse(version));
+    getMetricVersionRoute.respond(res, 200, MetricVersionSchema.parse(version));
     return true;
   }
 
@@ -426,7 +486,7 @@ export async function handleMetrics(
       res.end();
       return true;
     }
-    json(res, { versions: getMetricVersions(parsed.params.id) });
+    listMetricVersionsRoute.respond(res, 200, { versions: getMetricVersions(parsed.params.id) });
     return true;
   }
 
@@ -439,7 +499,7 @@ export async function handleMetrics(
       res.end();
       return true;
     }
-    json(res, metric);
+    getMetricRoute.respond(res, 200, metric);
     return true;
   }
 
@@ -472,7 +532,10 @@ export async function handleMetrics(
         res.end();
         return true;
       }
-      json(res, { id: updated.id, version: metricEditCounter(updated.id) });
+      updateMetricRoute.respond(res, 200, {
+        id: updated.id,
+        version: metricEditCounter(updated.id),
+      });
     } catch (err) {
       jsonError(res, err instanceof Error ? err.message : String(err));
     }

package/src/http/oauth-callback.ts

@@ -17,7 +17,7 @@ import { getPublicMcpBaseUrl } from "@/utils/constants";
 import { registerVolatileSecret, scrubSecrets } from "@/utils/secret-scrubber";
 import { completeMcpOAuthCallback } from "./mcp-oauth";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── The single static callback + redirect-uri display ───────────────────────
 
@@ -41,7 +41,10 @@ const callbackRoute = route({
     error_description: z.string().optional(),
   }),
   responses: {
-    200: { description: "OAuth authorization completed" },
+    200: {
+      description: "OAuth authorization completed",
+      unstructured: "HTML success page (sendAuthorizedHtml) — not JSON",
+    },
     302: { description: "Redirect back to the final destination" },
     400: { description: "Missing or invalid OAuth callback parameters" },
     404: { description: "OAuth app not configured" },
@@ -57,7 +60,10 @@ const redirectUriRoute = route({
   summary: "The static OAuth callback URL to register with providers (pre-creation display)",
   tags: ["OAuth"],
   responses: {
-    200: { description: "{ redirectUri: string }" },
+    200: {
+      description: "{ redirectUri: string }",
+      schema: z.object({ redirectUri: z.string() }),
+    },
   },
 });
 
@@ -280,7 +286,7 @@ export async function handleOAuthCallback(
   queryParams: URLSearchParams,
 ): Promise<boolean> {
   if (redirectUriRoute.match(req.method, pathSegments)) {
-    json(res, { redirectUri: staticOAuthCallbackUri() });
+    redirectUriRoute.respond(res, 200, { redirectUri: staticOAuthCallbackUri() });
     return true;
   }
 

package/src/http/oauth-generic.ts

@@ -34,7 +34,11 @@ const genericOAuthCallbackRoute = route({
     error_description: z.string().optional(),
   }),
   responses: {
-    200: { description: "OAuth authorization completed" },
+    200: {
+      description: "OAuth authorization completed",
+      unstructured:
+        "delegates to completeGenericOAuthCallback, which sends an HTML success page or a 302 redirect to the caller-supplied finalRedirect — never JSON",
+    },
     400: { description: "Missing or invalid OAuth callback parameters" },
     404: { description: "OAuth app not configured" },
     502: { description: "Token exchange failed" },

package/src/http/oauth-locks.ts

@@ -2,7 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { acquireOAuthRefreshLock, releaseOAuthRefreshLock } from "../be/db-queries/oauth";
 import { route } from "./route-def";
-import { json, jsonError } from "./utils";
+import { jsonError } from "./utils";
 
 /**
  * HTTP surface for the cross-process OAuth refresh-token lock
@@ -39,7 +39,10 @@ const acquireLockRoute = route({
   params: LockKeySchema,
   body: acquireBodySchema,
   responses: {
-    200: { description: "Lock acquired; returns the owner token" },
+    200: {
+      description: "Lock acquired; returns the owner token",
+      schema: z.object({ owner: z.string() }),
+    },
     409: { description: "Lock is currently held by another caller" },
     400: { description: "Validation error" },
   },
@@ -73,7 +76,7 @@ export async function handleOAuthLocks(
       jsonError(res, "lock is held by another caller", 409);
       return true;
     }
-    json(res, { owner });
+    acquireLockRoute.respond(res, 200, { owner });
     return true;
   }
 

package/src/http/openapi.ts

@@ -1,13 +1,17 @@
-import {
-  extendZodWithOpenApi,
-  OpenAPIRegistry,
-  OpenApiGeneratorV31,
-} from "@asteasolutions/zod-to-openapi";
-import { z } from "zod";
+import { OpenAPIRegistry, OpenApiGeneratorV31 } from "@asteasolutions/zod-to-openapi";
 import { getPublicMcpBaseUrl } from "../utils/constants";
+import { z } from "../utils/zod-openapi";
 import { routeRegistry } from "./route-def";
 
-extendZodWithOpenApi(z);
+/**
+ * Default component for 4xx/5xx responses that declare no schema of their own:
+ * the `jsonError()` envelope every error path emits. Loose because a few
+ * handlers attach extra diagnostic fields (e.g. TriggerSchemaError's
+ * `message`/`details`) — those may declare an explicit schema instead.
+ */
+const ErrorResponseSchema = z
+  .looseObject({ error: z.string() })
+  .openapi("ErrorResponse", { description: "Standard error envelope" });
 
 let cachedSpec: string | null = null;
 
@@ -43,11 +47,16 @@ export function generateOpenApiSpec(opts: OpenApiOptions): string {
       { description: string; content?: Record<string, { schema: z.ZodType }> }
     > = {};
     for (const [code, resDef] of Object.entries(routeDef.responses)) {
+      const schema =
+        resDef.schema ??
+        // Untyped error responses default to the shared jsonError envelope;
+        // `unstructured` (non-JSON body) opts out.
+        (Number(code) >= 400 && !resDef.unstructured ? ErrorResponseSchema : undefined);
       responses[code] = {
         description: resDef.description,
-        ...(resDef.schema && {
+        ...(schema && {
           content: {
-            "application/json": { schema: resDef.schema },
+            "application/json": { schema },
           },
         }),
       };
@@ -77,6 +86,42 @@ export function generateOpenApiSpec(opts: OpenApiOptions): string {
 
   const serverUrl = opts.serverUrl || getPublicMcpBaseUrl();
 
+  /**
+   * zod-to-openapi emits `.nullable()` on an `.extend()`ed (or `$ref`ed)
+   * schema as `allOf: [{$ref}, {type: ["object","null"], ...delta}]` — an
+   * allOf member allowing null is semantically wrong (the intersection with
+   * the non-null base can never be null), and TS-definition generators
+   * (fumadocs-openapi) collapse it to `never`. Rewrite to the intended
+   * `anyOf: [<intersection>, {type: "null"}]`.
+   */
+  function fixNullableAllOf(node: unknown): void {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const item of node) fixNullableAllOf(item);
+      return;
+    }
+    const obj = node as Record<string, unknown>;
+    const allOf = obj.allOf;
+    if (Array.isArray(allOf)) {
+      let hadNull = false;
+      for (const member of allOf) {
+        if (member && Array.isArray(member.type) && member.type.includes("null")) {
+          hadNull = true;
+          const rest = member.type.filter((t: string) => t !== "null");
+          member.type = rest.length === 1 ? rest[0] : rest;
+        }
+      }
+      if (hadNull) {
+        // Drop members reduced to a bare `{type: "object"}` (no constraints left).
+        const members = allOf.filter((m) => !(Object.keys(m).length === 1 && m.type === "object"));
+        const intersection = members.length === 1 ? members[0] : { allOf: members };
+        delete obj.allOf;
+        obj.anyOf = [intersection, { type: "null" }];
+      }
+    }
+    for (const value of Object.values(obj)) fixNullableAllOf(value);
+  }
+
   const generator = new OpenApiGeneratorV31(registry.definitions);
   const doc = generator.generateDocument({
     openapi: "3.1.0",
@@ -96,6 +141,9 @@ export function generateOpenApiSpec(opts: OpenApiOptions): string {
     ],
   });
 
+  fixNullableAllOf(doc.paths);
+  fixNullableAllOf(doc.components);
+
   cachedSpec = JSON.stringify(doc, null, 2);
   return cachedSpec;
 }

package/src/http/page-proxy.ts

@@ -40,7 +40,11 @@ route({
   summary: "Cookie-gated proxy to the swarm API (used by db-backed page iframes)",
   tags: ["Pages"],
   responses: {
-    200: { description: "Proxied response from the underlying /api/* endpoint" },
+    200: {
+      description: "Proxied response from the underlying /api/* endpoint",
+      unstructured:
+        "Body is forwarded verbatim from the proxied /api/* endpoint; shape and content-type vary per target route",
+    },
     401: { description: "No or invalid page-session cookie" },
     404: { description: "Page referenced by the cookie no longer exists" },
   },
@@ -54,7 +58,11 @@ route({
   summary: "Cookie-gated proxy to the swarm API (POST)",
   tags: ["Pages"],
   responses: {
-    200: { description: "Proxied response" },
+    200: {
+      description: "Proxied response",
+      unstructured:
+        "Body is forwarded verbatim from the proxied /api/* endpoint; shape and content-type vary per target route",
+    },
     401: { description: "No or invalid page-session cookie" },
   },
   auth: { apiKey: false },
@@ -67,7 +75,11 @@ route({
   summary: "Cookie-gated proxy to the swarm API (PUT)",
   tags: ["Pages"],
   responses: {
-    200: { description: "Proxied response" },
+    200: {
+      description: "Proxied response",
+      unstructured:
+        "Body is forwarded verbatim from the proxied /api/* endpoint; shape and content-type vary per target route",
+    },
     401: { description: "No or invalid page-session cookie" },
   },
   auth: { apiKey: false },
@@ -80,7 +92,11 @@ route({
   summary: "Cookie-gated proxy to the swarm API (DELETE)",
   tags: ["Pages"],
   responses: {
-    200: { description: "Proxied response" },
+    200: {
+      description: "Proxied response",
+      unstructured:
+        "Body is forwarded verbatim from the proxied /api/* endpoint; shape and content-type vary per target route",
+    },
     401: { description: "No or invalid page-session cookie" },
   },
   auth: { apiKey: false },
@@ -93,7 +109,11 @@ route({
   summary: "Cookie-gated proxy to the swarm API (PATCH)",
   tags: ["Pages"],
   responses: {
-    200: { description: "Proxied response" },
+    200: {
+      description: "Proxied response",
+      unstructured:
+        "Body is forwarded verbatim from the proxied /api/* endpoint; shape and content-type vary per target route",
+    },
     401: { description: "No or invalid page-session cookie" },
   },
   auth: { apiKey: false },

package/src/http/pages-public.ts

@@ -24,7 +24,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { BROWSER_SDK_JS, SWARM_UI_JS } from "../artifact-sdk/browser-sdk";
 import { getPage, incrementPageViewCount } from "../be/db";
-import type { Page } from "../types";
+import { type Page, PageSchema } from "../types";
 import { getAppUrl, getConfiguredAppUrls } from "../utils/constants";
 import { extractAndVerifyCookie, issuePageSessionCookie } from "../utils/page-session";
 import { scrubSecrets } from "../utils/secret-scrubber";
@@ -32,6 +32,22 @@ import { route } from "./route-def";
 
 // ─── Route definitions (registered with auth: { apiKey: false }) ────────────
 
+/**
+ * Wire shape sent by the `/p/{id}.json` 200 response — a subset of `Page`
+ * fields plus a hardcoded `version: 1` (edit-counter is API-internal; the SPA
+ * reads real version numbers via `/api/pages/:id/versions`, NOT this field).
+ */
+const PublicPageJsonSchema = PageSchema.pick({
+  id: true,
+  title: true,
+  description: true,
+  contentType: true,
+  authMode: true,
+  body: true,
+}).extend({
+  version: z.literal(1),
+});
+
 const publicPageRoute = route({
   method: "get",
   path: "/p/{id}",
@@ -40,7 +56,11 @@ const publicPageRoute = route({
   tags: ["Pages"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Rendered HTML page" },
+    200: {
+      description: "Rendered HTML page",
+      unstructured:
+        "Serves the page's raw agent-authored HTML body (SDK-injected) or, for ?print=1 on a JSON-content page, a standalone printable HTML document — not a JSON shape",
+    },
     302: { description: "Redirect to SPA for JSON content" },
     401: { description: "Page requires an authenticated session" },
     403: { description: "Cookie does not match this page id" },
@@ -57,7 +77,7 @@ const publicPageJsonRoute = route({
   tags: ["Pages"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Page JSON" },
+    200: { description: "Page JSON", schema: PublicPageJsonSchema },
     401: { description: "Page requires an authenticated session" },
     403: { description: "Cookie does not match this page id" },
     404: { description: "Page not found" },
@@ -545,23 +565,20 @@ export async function handlePagesPublic(
     // Returns the current head state (no version history). Body included
     // verbatim. NOTE: passwordHash / agentId are NOT exposed here — these
     // are private. step-4 may revisit if needed.
-    const headers: Record<string, string> = {
-      "Content-Type": "application/json",
-      "Cache-Control": "no-store",
-    };
-    if (inlineSetCookie) headers["Set-Cookie"] = inlineSetCookie;
-    res.writeHead(200, headers);
-    res.end(
-      JSON.stringify({
-        id: page.id,
-        version: 1, // edit-counter is API-internal; SPA reads via /api/pages/:id/versions
-        title: page.title,
-        description: page.description,
-        contentType: page.contentType,
-        authMode: page.authMode,
-        body: page.body,
-      }),
-    );
+    // `res.setHeader` merges with the `Content-Type: application/json` header
+    // that `respond()` writes via `res.writeHead()` — Node gives the latter
+    // precedence, which is the value we want here anyway.
+    res.setHeader("Cache-Control", "no-store");
+    if (inlineSetCookie) res.setHeader("Set-Cookie", inlineSetCookie);
+    publicPageJsonRoute.respond(res, 200, {
+      id: page.id,
+      version: 1, // edit-counter is API-internal; SPA reads via /api/pages/:id/versions
+      title: page.title,
+      description: page.description,
+      contentType: page.contentType,
+      authMode: page.authMode,
+      body: page.body,
+    });
     bumpViewCount(page.id);
     return true;
   }