@vellumai/assistant 0.8.7 → 0.8.8

package/src/runtime/routes/integrations/twilio.ts

@@ -36,6 +36,41 @@ import { ACTOR_PRINCIPALS } from "../../auth/route-policy.js";
 import { BadRequestError, InternalError } from "../errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "../types.js";
 
+// ---------------------------------------------------------------------------
+// Response schemas
+// ---------------------------------------------------------------------------
+
+const TwilioPhoneNumberSchema = z.object({
+  phoneNumber: z.string(),
+  friendlyName: z.string(),
+  capabilities: z.object({ voice: z.boolean() }),
+});
+
+const TwilioConfigResultSchema = z.object({
+  success: z.boolean(),
+  hasCredentials: z.boolean(),
+  accountSid: z.string().optional(),
+  phoneNumber: z.string().optional(),
+});
+
+const TwilioCredentialsResultSchema = z.object({
+  success: z.boolean(),
+  hasCredentials: z.boolean(),
+});
+
+const TwilioNumbersResultSchema = z.object({
+  success: z.boolean(),
+  hasCredentials: z.boolean(),
+  numbers: z.array(TwilioPhoneNumberSchema),
+});
+
+const TwilioNumberMutationResultSchema = z.object({
+  success: z.boolean(),
+  hasCredentials: z.boolean(),
+  phoneNumber: z.string().optional(),
+  warning: z.string().optional(),
+});
+
 // ---------------------------------------------------------------------------
 // Shared helpers
 // ---------------------------------------------------------------------------
@@ -362,6 +397,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Get Twilio config",
     description: "Return current Twilio configuration status.",
     tags: ["integrations"],
+    responseBody: TwilioConfigResultSchema,
     handler: () => handleGetTwilioConfig(),
   },
   {
@@ -380,6 +416,7 @@ export const ROUTES: RouteDefinition[] = [
       accountSid: z.string().describe("Twilio account SID"),
       authToken: z.string().describe("Twilio auth token"),
     }),
+    responseBody: TwilioCredentialsResultSchema,
   },
   {
     operationId: "integrations_twilio_credentials_delete",
@@ -392,6 +429,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Clear Twilio credentials",
     description: "Remove stored Twilio credentials.",
     tags: ["integrations"],
+    responseBody: TwilioCredentialsResultSchema,
     handler: () => handleClearTwilioCredentials(),
   },
   {
@@ -405,6 +443,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "List Twilio numbers",
     description: "List phone numbers on the Twilio account.",
     tags: ["integrations"],
+    responseBody: TwilioNumbersResultSchema,
     handler: () => handleListTwilioNumbers(),
   },
   {
@@ -418,6 +457,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Provision Twilio number",
     description: "Search for and provision a new phone number.",
     tags: ["integrations"],
+    responseBody: TwilioNumberMutationResultSchema,
     handler: handleProvisionTwilioNumber,
   },
   {
@@ -431,6 +471,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Assign Twilio number",
     description: "Assign an existing phone number to this assistant.",
     tags: ["integrations"],
+    responseBody: TwilioNumberMutationResultSchema,
     handler: handleAssignTwilioNumber,
   },
   {
@@ -444,6 +485,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Release Twilio number",
     description: "Release a phone number back to Twilio.",
     tags: ["integrations"],
+    responseBody: TwilioNumberMutationResultSchema,
     handler: handleReleaseTwilioNumber,
   },
 ];

package/src/runtime/routes/internal-telemetry-routes.ts

@@ -0,0 +1,88 @@
+/**
+ * Internal telemetry routes — receive operational signals forwarded from the
+ * gateway over the internal (service-token) transport.
+ *
+ * POST /v1/internal/telemetry/auth-fallback — record aggregated counts of
+ * requests served via the legacy loopback auth fallback. The gateway counts
+ * fallbacks in memory and flushes them here per window; the usage telemetry
+ * reporter ships the persisted rows to the platform.
+ */
+
+import { z } from "zod";
+
+import {
+  type AuthFallbackCount,
+  recordAuthFallbackCounts,
+} from "../../memory/auth-fallback-events-store.js";
+import { getLogger } from "../../util/logger.js";
+import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
+import { BadRequestError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const log = getLogger("internal-telemetry-routes");
+
+const authFallbackBody = z.object({
+  window_start: z.number().int().nonnegative(),
+  window_end: z.number().int().nonnegative(),
+  counts: z
+    .array(
+      z.object({
+        guard: z.string().min(1),
+        path: z.string().min(1),
+        failure_kind: z.string().min(1),
+        count: z.number().int().positive(),
+      }),
+    )
+    .min(1),
+});
+
+function handleRecordAuthFallback({ body }: RouteHandlerArgs) {
+  const parsed = authFallbackBody.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      `Invalid auth-fallback payload: ${parsed.error.message}`,
+    );
+  }
+  const { window_start, window_end, counts } = parsed.data;
+  const mapped: AuthFallbackCount[] = counts.map((c) => ({
+    guard: c.guard,
+    path: c.path,
+    failureKind: c.failure_kind,
+    count: c.count,
+  }));
+
+  const recorded = recordAuthFallbackCounts(window_start, window_end, mapped);
+  if (recorded === 0) {
+    // collectUsageData disabled — counts dropped to honor the opt-out.
+    return { skipped: true };
+  }
+  log.debug({ recorded }, "Recorded auth-fallback counts");
+  return { recorded };
+}
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "internal_telemetry_auth_fallback",
+    endpoint: "internal/telemetry/auth-fallback",
+    method: "POST",
+    policy: {
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+    },
+    summary: "Record auth-fallback counts",
+    description:
+      "Receives aggregated legacy-loopback auth-fallback counts forwarded by " +
+      "the gateway and persists them for telemetry reporting.",
+    tags: ["internal", "telemetry"],
+    requestBody: authFallbackBody,
+    responseBody: z.union([
+      z.object({ recorded: z.number().int().nonnegative() }),
+      z.object({
+        skipped: z
+          .literal(true)
+          .describe("Counts dropped because usage data collection is disabled"),
+      }),
+    ]),
+    handler: handleRecordAuthFallback,
+  },
+];

package/src/runtime/routes/log-export-routes.ts

@@ -508,6 +508,10 @@ export const ROUTES: RouteDefinition[] = [
       "Export audit records, assistant logs, and config as a tar.gz archive.",
     tags: ["export"],
     requestBody: exportRequestBody,
+    responseBody: {
+      contentType: "application/gzip",
+      schema: { type: "string", format: "binary" },
+    },
     responseHeaders: {
       "Content-Type": "application/gzip",
       "Content-Disposition": 'attachment; filename="logs.tar.gz"',
@@ -532,6 +536,10 @@ export const ROUTES: RouteDefinition[] = [
       "Alias for /v1/export. Export audit records, assistant logs, and config as a tar.gz archive.",
     tags: ["export"],
     requestBody: exportRequestBody,
+    responseBody: {
+      contentType: "application/gzip",
+      schema: { type: "string", format: "binary" },
+    },
     responseHeaders: {
       "Content-Type": "application/gzip",
       "Content-Disposition": 'attachment; filename="logs.tar.gz"',

package/src/runtime/routes/memory-v2-routes.ts

@@ -210,14 +210,20 @@ async function handleGetConceptPage({
 
 const MemoryV2ListConceptPagesParams = z.object({}).strict();
 
-export type MemoryV2ListConceptPagesResult = {
-  pages: Array<{
-    slug: string;
-    bodyBytes: number;
-    edgeCount: number;
-    updatedAtMs: number;
-  }>;
-};
+export const MemoryV2ListConceptPagesResultSchema = z.object({
+  pages: z.array(
+    z.object({
+      slug: z.string(),
+      bodyBytes: z.number(),
+      edgeCount: z.number(),
+      updatedAtMs: z.number(),
+    }),
+  ),
+});
+
+export type MemoryV2ListConceptPagesResult = z.infer<
+  typeof MemoryV2ListConceptPagesResultSchema
+>;
 
 async function handleListConceptPages({
   body = {},
@@ -732,6 +738,7 @@ export const ROUTES: RouteDefinition[] = [
       "Returns slugs, body sizes, edge counts, and last-modified timestamps for every concept page on disk. Read-only; used by the desktop About → Memories surface to render a browse-able list.",
     tags: ["memory"],
     requestBody: MemoryV2ListConceptPagesParams,
+    responseBody: MemoryV2ListConceptPagesResultSchema,
   },
   {
     operationId: "memory_v2_reembed_skills",

package/src/runtime/routes/memory-v3-routes.ts

@@ -18,6 +18,8 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { z } from "zod";
+
 import { getPageIndex } from "../../memory/v2/page-index.js";
 import { loadCore } from "../../memory/v3/core.js";
 import { computeV3Health, renderV3Health } from "../../memory/v3/health.js";
@@ -88,18 +90,19 @@ async function loadTreeAndSlugs(deps?: MemoryV3Deps): Promise<{
 // health
 // ---------------------------------------------------------------------------
 
-export interface MemoryV3HealthResult {
+const MemoryV3HealthResultSchema = z.object({
   /** Pre-rendered, human-readable report. Empty string when all-green. */
-  rendered: string;
+  rendered: z.string(),
   /** The structural counts, for `--json` consumers. */
-  counts: {
-    unassigned: number;
-    danglingRefs: number;
-    novelClusters: number;
-    oversizedLeaves: number;
-    tinyLeaves: number;
-  };
-}
+  counts: z.object({
+    unassigned: z.number(),
+    danglingRefs: z.number(),
+    novelClusters: z.number(),
+    oversizedLeaves: z.number(),
+    tinyLeaves: z.number(),
+  }),
+});
+export type MemoryV3HealthResult = z.infer<typeof MemoryV3HealthResultSchema>;
 
 export async function handleMemoryV3Health(
   deps?: MemoryV3Deps,
@@ -123,26 +126,28 @@ export async function handleMemoryV3Health(
 // set-core
 // ---------------------------------------------------------------------------
 
-export interface MemoryV3SetCoreBody {
+const MemoryV3SetCoreBodySchema = z.object({
   /** Leaves to add to the always-on core set. */
-  add?: LeafPath[];
+  add: z.array(z.string()).optional(),
   /** Leaves to remove from the always-on core set. */
-  remove?: LeafPath[];
+  remove: z.array(z.string()).optional(),
   /**
    * When true, persist the new core to `core.json` and invalidate the lanes.
    * When false (default), compute the preview WITHOUT writing.
    */
-  write?: boolean;
-}
+  write: z.boolean().optional(),
+});
+export type MemoryV3SetCoreBody = z.infer<typeof MemoryV3SetCoreBodySchema>;
 
-export interface MemoryV3SetCoreResult {
+const MemoryV3SetCoreResultSchema = z.object({
   /** The core leaf set that would result (or did result, when `write`). */
-  nextCore: LeafPath[];
+  nextCore: z.array(z.string()),
   /** Number of unique page slugs the new core set pins always-on. */
-  alwaysOnPageCount: number;
+  alwaysOnPageCount: z.number(),
   /** Whether `core.json` was written. */
-  written: boolean;
-}
+  written: z.boolean(),
+});
+export type MemoryV3SetCoreResult = z.infer<typeof MemoryV3SetCoreResultSchema>;
 
 /** Wire-format error code for a `set-core` add referencing an unknown leaf. */
 export const MEMORY_V3_UNKNOWN_LEAF_CODE = "MEMORY_V3_UNKNOWN_LEAF";
@@ -206,11 +211,20 @@ export async function handleMemoryV3SetCore(
 // reconcile
 // ---------------------------------------------------------------------------
 
-export interface MemoryV3ReconcileResult {
-  renames: Array<{ id?: string; oldPath: LeafPath; newPath: LeafPath }>;
-  deleted: LeafPath[];
-  prunedCore: LeafPath[];
-}
+const MemoryV3ReconcileResultSchema = z.object({
+  renames: z.array(
+    z.object({
+      id: z.string().optional(),
+      oldPath: z.string(),
+      newPath: z.string(),
+    }),
+  ),
+  deleted: z.array(z.string()),
+  prunedCore: z.array(z.string()),
+});
+export type MemoryV3ReconcileResult = z.infer<
+  typeof MemoryV3ReconcileResultSchema
+>;
 
 /**
  * Reconcile page + core references against the live on-disk tree.
@@ -253,9 +267,12 @@ async function loadPrevLeaves(dataDir: string): Promise<LeafRef[]> {
 // rebuild-index
 // ---------------------------------------------------------------------------
 
-export interface MemoryV3RebuildIndexResult {
-  ok: true;
-}
+const MemoryV3RebuildIndexResultSchema = z.object({
+  ok: z.literal(true),
+});
+export type MemoryV3RebuildIndexResult = z.infer<
+  typeof MemoryV3RebuildIndexResultSchema
+>;
 
 /**
  * Invalidate the v3 shadow lanes so the next turn rebuilds the tree/needle
@@ -299,6 +316,7 @@ export const ROUTES: RouteDefinition[] = [
     handler: () => handleMemoryV3Health(),
     summary: "Print the v3 structural health report (read-only)",
     tags: ["memory"],
+    responseBody: MemoryV3HealthResultSchema,
   },
   {
     operationId: "memory_v3_set_core",
@@ -317,6 +335,8 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Add/remove always-on core leaves (validates + previews cost)",
     tags: ["memory"],
+    requestBody: MemoryV3SetCoreBodySchema,
+    responseBody: MemoryV3SetCoreResultSchema,
   },
   {
     operationId: "memory_v3_reconcile",
@@ -327,6 +347,7 @@ export const ROUTES: RouteDefinition[] = [
     summary:
       "v1 convergence/prune pass over page+core refs (no rename detection without a prior snapshot)",
     tags: ["memory"],
+    responseBody: MemoryV3ReconcileResultSchema,
   },
   {
     operationId: "memory_v3_rebuild_index",
@@ -336,5 +357,6 @@ export const ROUTES: RouteDefinition[] = [
     handler: () => handleMemoryV3RebuildIndex(),
     summary: "Invalidate the v3 lanes so the next turn rebuilds",
     tags: ["memory"],
+    responseBody: MemoryV3RebuildIndexResultSchema,
   },
 ];

package/src/runtime/routes/oauth-apps.ts

@@ -6,6 +6,8 @@
  * bearer-token authenticated via the standard runtime auth middleware.
  */
 
+import { z } from "zod";
+
 import { orchestrateOAuthConnect } from "../../oauth/connect-orchestrator.js";
 import {
   deleteApp,
@@ -22,11 +24,8 @@ import {
 } from "../../oauth/oauth-store.js";
 import { serializeProviderSummary } from "../../oauth/provider-serializer.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
-import {
-  BadRequestError,
-  InternalError,
-  NotFoundError,
-} from "./errors.js";
+import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
+import { oauthProviderSummarySchema } from "./oauth-providers.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 function parseGrantedScopes(
@@ -131,17 +130,14 @@ async function handleUpsertApp({ body = {} }: RouteHandlerArgs) {
   const clientId = b.client_id as string | undefined;
 
   if (!providerKey || !clientId) {
-    throw new BadRequestError(
-      "provider_key and client_id are required",
-    );
+    throw new BadRequestError("provider_key and client_id are required");
   }
 
   const clientSecretOpts = b.client_secret
     ? { clientSecretValue: b.client_secret as string }
     : b.client_secret_credential_path
       ? {
-          clientSecretCredentialPath:
-            b.client_secret_credential_path as string,
+          clientSecretCredentialPath: b.client_secret_credential_path as string,
         }
       : undefined;
 
@@ -297,6 +293,38 @@ async function handleConnectApp({ pathParams = {}, body }: RouteHandlerArgs) {
   return { ok: true };
 }
 
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+/** Custom OAuth app registration (snake_case wire shape from `formatAppRow`). */
+const oauthAppSchema = z.object({
+  id: z.string(),
+  provider_key: z.string(),
+  client_id: z.string(),
+  created_at: z.number(),
+  updated_at: z.number(),
+});
+
+/** OAuth connection linked to a custom OAuth app. */
+const oauthAppConnectionSchema = z.object({
+  id: z.string(),
+  provider_key: z.string(),
+  account_info: z.string().nullable(),
+  granted_scopes: z.array(z.string()),
+  status: z.string(),
+  has_refresh_token: z.boolean(),
+  expires_at: z.number().nullable(),
+  created_at: z.number(),
+  updated_at: z.number(),
+});
+
+const oauthAppCredentialsSchema = z.object({
+  provider_key: z.string(),
+  client_id: z.string(),
+  client_secret: z.string(),
+});
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
@@ -321,6 +349,10 @@ export const ROUTES: RouteDefinition[] = [
         description: "OAuth provider key to filter by",
       },
     ],
+    responseBody: z.object({
+      provider: oauthProviderSummarySchema.nullable(),
+      apps: z.array(oauthAppSchema),
+    }),
     handler: handleListApps,
   },
   {
@@ -352,6 +384,7 @@ export const ROUTES: RouteDefinition[] = [
         description: "OAuth client ID (requires provider)",
       },
     ],
+    responseBody: z.object({ app: oauthAppSchema }),
     handler: handleGetApp,
   },
   {
@@ -366,6 +399,13 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Create or return an existing OAuth app registration. Updates client secret if provided.",
     tags: ["oauth"],
+    requestBody: z.object({
+      provider_key: z.string(),
+      client_id: z.string(),
+      client_secret: z.string().optional(),
+      client_secret_credential_path: z.string().optional(),
+    }),
+    responseBody: z.object({ app: oauthAppSchema }),
     handler: handleUpsertApp,
   },
   {
@@ -379,6 +419,8 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Create OAuth app",
     description: "Register a new OAuth app with client credentials.",
     tags: ["oauth"],
+    requestBody: oauthAppCredentialsSchema,
+    responseBody: z.object({ app: oauthAppSchema }),
     responseStatus: "201",
     handler: handleCreateApp,
   },
@@ -391,9 +433,9 @@ export const ROUTES: RouteDefinition[] = [
       allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
     summary: "Delete OAuth app",
-    description:
-      "Delete an OAuth app and disconnect all its connections.",
+    description: "Delete an OAuth app and disconnect all its connections.",
     tags: ["oauth"],
+    responseBody: z.object({ ok: z.boolean() }),
     handler: handleDeleteApp,
   },
   {
@@ -407,6 +449,9 @@ export const ROUTES: RouteDefinition[] = [
     summary: "List OAuth connections",
     description: "List connections for an OAuth app.",
     tags: ["oauth"],
+    responseBody: z.object({
+      connections: z.array(oauthAppConnectionSchema),
+    }),
     handler: handleListConnections,
   },
   {
@@ -420,6 +465,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Disconnect OAuth connection",
     description: "Disconnect a single OAuth connection.",
     tags: ["oauth"],
+    responseBody: z.object({ ok: z.boolean() }),
     handler: handleDeleteConnection,
   },
   {
@@ -433,6 +479,14 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Start OAuth connect",
     description: "Start an OAuth connect flow for an app.",
     tags: ["oauth"],
+    requestBody: z.object({
+      scopes: z.array(z.string()).optional(),
+      callback_transport: z.enum(["loopback", "gateway"]).optional(),
+    }),
+    responseBody: z.union([
+      z.object({ auth_url: z.string(), state: z.string() }),
+      z.object({ ok: z.literal(true) }),
+    ]),
     handler: handleConnectApp,
   },
 ];

package/src/runtime/routes/oauth-providers.ts

@@ -6,6 +6,8 @@
  * the standard runtime auth middleware.
  */
 
+import { z } from "zod";
+
 import { loadConfig } from "../../config/loader.js";
 import { getOAuthCallbackUrl } from "../../inbound/public-ingress-urls.js";
 import {
@@ -220,7 +222,8 @@ function handleUpdateProvider({
   if (b.default_scopes !== undefined) params.defaultScopes = b.default_scopes;
   if (b.available_scopes !== undefined)
     params.availableScopes = b.available_scopes;
-  if (b.scope_separator !== undefined) params.scopeSeparator = b.scope_separator;
+  if (b.scope_separator !== undefined)
+    params.scopeSeparator = b.scope_separator;
   if (b.token_endpoint_auth_method !== undefined)
     params.tokenEndpointAuthMethod = b.token_endpoint_auth_method;
   if (b.token_exchange_body_format !== undefined)
@@ -245,13 +248,15 @@ function handleUpdateProvider({
     params.injectionTemplates = b.injection_templates;
   if (b.app_type !== undefined) params.appType = b.app_type;
   if (b.identity_url !== undefined) params.identityUrl = b.identity_url;
-  if (b.identity_method !== undefined) params.identityMethod = b.identity_method;
+  if (b.identity_method !== undefined)
+    params.identityMethod = b.identity_method;
   if (b.identity_headers !== undefined)
     params.identityHeaders = b.identity_headers;
   if (b.identity_body !== undefined) params.identityBody = b.identity_body;
   if (b.identity_response_paths !== undefined)
     params.identityResponsePaths = b.identity_response_paths;
-  if (b.identity_format !== undefined) params.identityFormat = b.identity_format;
+  if (b.identity_format !== undefined)
+    params.identityFormat = b.identity_format;
   if (b.identity_ok_field !== undefined)
     params.identityOkField = b.identity_ok_field;
   if (b.setup_notes !== undefined) params.setupNotes = b.setup_notes;
@@ -321,6 +326,37 @@ async function handleDeleteProvider({
 // Route definitions
 // ---------------------------------------------------------------------------
 
+/**
+ * Lightweight summary projection of an OAuth provider returned by the catalog
+ * list endpoint. Mirrors `SerializedProviderSummary` from the provider
+ * serializer (snake_case to match the HTTP API convention).
+ */
+export const oauthProviderSummarySchema = z.object({
+  provider_key: z.string(),
+  display_name: z.string().nullable(),
+  description: z.string().nullable(),
+  dashboard_url: z.string().nullable(),
+  client_id_placeholder: z.string().nullable(),
+  requires_client_secret: z.boolean(),
+  logo_url: z.string().nullable(),
+  supports_managed_mode: z.boolean(),
+  managed_service_is_paid: z.boolean(),
+  feature_flag: z.string().nullable(),
+});
+
+/**
+ * Response for the single-provider detail endpoint. The `provider` field is the
+ * full serialized provider configuration — an open-ended, admin-defined object
+ * whose keys depend on the stored row (parsed JSON blobs, identity templates,
+ * and forwarded columns), so it is intentionally typed as an open record rather
+ * than a closed schema. `oauth_callback_url` is the ingress callback URL the
+ * web UI consumes (null when ingress is not configured).
+ */
+export const oauthProviderDetailSchema = z.object({
+  provider: z.record(z.string(), z.unknown()),
+  oauth_callback_url: z.string().nullable(),
+});
+
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "oauth_providers_get",
@@ -331,8 +367,7 @@ export const ROUTES: RouteDefinition[] = [
       allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
     summary: "List OAuth providers",
-    description:
-      "List all registered OAuth providers with optional filtering.",
+    description: "List all registered OAuth providers with optional filtering.",
     tags: ["oauth"],
     handler: handleListProviders,
     queryParams: [
@@ -342,6 +377,9 @@ export const ROUTES: RouteDefinition[] = [
         description: "Filter by managed mode support (true/false)",
       },
     ],
+    responseBody: z.object({
+      providers: z.array(oauthProviderSummarySchema),
+    }),
   },
   {
     operationId: "oauth_providers_by_providerKey_get",
@@ -355,6 +393,7 @@ export const ROUTES: RouteDefinition[] = [
     description: "Get a single OAuth provider by key.",
     tags: ["oauth"],
     handler: handleGetProvider,
+    responseBody: oauthProviderDetailSchema,
   },
   {
     operationId: "oauth_providers_post",