@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

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",

package/src/runtime/routes/platform-routes.ts

@@ -14,6 +14,8 @@
  *     registered callback routes for this assistant.
  */
 
+import { z } from "zod";
+
 import { isPlatformRemote } from "../../config/env-registry.js";
 import {
   registerCallbackRoute,
@@ -47,13 +49,80 @@ const CREDENTIAL_KEYS = {
   userId: { service: "vellum", field: "platform_user_id" },
 } as const;
 
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const VelayTunnelStatusSchema = z.object({
+  connected: z.boolean(),
+  publicUrl: z.string().nullable(),
+});
+
+const PlatformStatusResponseSchema = z.object({
+  isPlatform: z.boolean(),
+  baseUrl: z.string(),
+  assistantId: z.string(),
+  hasAssistantApiKey: z.boolean(),
+  hasWebhookSecret: z.boolean(),
+  available: z.boolean(),
+  organizationId: z.string().nullable(),
+  userId: z.string().nullable(),
+  velayTunnel: VelayTunnelStatusSchema.nullable(),
+});
+type PlatformStatusResponse = z.infer<typeof PlatformStatusResponseSchema>;
+
+const PlatformConnectResponseSchema = z.object({
+  alreadyConnected: z.boolean().optional(),
+  baseUrl: z.string().optional(),
+  showPlatformLogin: z.boolean().optional(),
+});
+type PlatformConnectResponse = z.infer<typeof PlatformConnectResponseSchema>;
+
+const PlatformDisconnectResponseSchema = z.object({
+  disconnected: z.literal(true),
+  previousBaseUrl: z.string().nullable(),
+});
+type PlatformDisconnectResponse = z.infer<
+  typeof PlatformDisconnectResponseSchema
+>;
+
+const CallbackRouteRegisterRequestSchema = z.object({
+  path: z.string(),
+  type: z.string(),
+});
+
+const CallbackRouteRegisterResponseSchema = z.object({
+  callbackUrl: z.string(),
+  callbackPath: z.string(),
+  type: z.string(),
+});
+type CallbackRouteRegisterResponse = z.infer<
+  typeof CallbackRouteRegisterResponseSchema
+>;
+
+const CallbackRouteSchema = z.object({
+  id: z.string(),
+  assistant_id: z.string(),
+  type: z.string(),
+  callback_path: z.string(),
+  callback_url: z.string(),
+  source_identifier: z.string().nullable(),
+});
+
+const CallbackRoutesListResponseSchema = z.object({
+  routes: z.array(CallbackRouteSchema),
+});
+type CallbackRoutesListResponse = z.infer<
+  typeof CallbackRoutesListResponseSchema
+>;
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
 
 async function handlePlatformStatus(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<PlatformStatusResponse> {
   const [context, velayTunnel] = await Promise.all([
     resolvePlatformCallbackRegistrationContext(),
     ipcGetVelayStatus().catch(() => null),
@@ -94,7 +163,7 @@ async function handlePlatformStatus(
 
 async function handlePlatformConnect(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<PlatformConnectResponse> {
   // Check if already connected
   const [existingUrl, existingApiKey] = await Promise.all([
     getSecureKeyAsync(
@@ -128,7 +197,7 @@ async function handlePlatformConnect(
 
 async function handlePlatformDisconnect(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<PlatformDisconnectResponse> {
   // Reject if running inside a platform host
   if (isPlatformRemote()) {
     throw new UnprocessableEntityError(
@@ -197,7 +266,7 @@ async function handlePlatformDisconnect(
 
 async function handleCallbackRoutesRegister(
   args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<CallbackRouteRegisterResponse> {
   const { path, type } = (args.body ?? {}) as {
     path?: string;
     type?: string;
@@ -235,7 +304,7 @@ async function handleCallbackRoutesRegister(
 
 async function handleCallbackRoutesList(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<CallbackRoutesListResponse> {
   const context = await resolvePlatformCallbackRegistrationContext();
 
   if (!context.platformBaseUrl || !context.authHeader) {
@@ -274,6 +343,7 @@ async function handleCallbackRoutesList(
     type: string;
     callback_path: string;
     callback_url: string;
+    source_identifier: string | null;
   }>;
 
   return { routes };
@@ -297,6 +367,7 @@ export const ROUTES: RouteDefinition[] = [
       "Aggregates platform context, credentials, assistant ID, webhook secret, and Velay tunnel status.",
     tags: ["platform"],
     handler: handlePlatformStatus,
+    responseBody: PlatformStatusResponseSchema,
   },
   {
     operationId: "platform_connect",
@@ -311,6 +382,7 @@ export const ROUTES: RouteDefinition[] = [
       "Checks existing credentials and emits the show_platform_login signal for connected clients to show a login UI.",
     tags: ["platform"],
     handler: handlePlatformConnect,
+    responseBody: PlatformConnectResponseSchema,
   },
   {
     operationId: "platform_disconnect",
@@ -325,6 +397,7 @@ export const ROUTES: RouteDefinition[] = [
       "Deletes stored platform credentials and emits platform_disconnected signal to connected clients.",
     tags: ["platform"],
     handler: handlePlatformDisconnect,
+    responseBody: PlatformDisconnectResponseSchema,
   },
   {
     operationId: "platform_callback_routes_register",
@@ -339,6 +412,8 @@ export const ROUTES: RouteDefinition[] = [
       "Registers a callback route with the platform gateway for inbound provider webhooks.",
     tags: ["platform"],
     handler: handleCallbackRoutesRegister,
+    requestBody: CallbackRouteRegisterRequestSchema,
+    responseBody: CallbackRouteRegisterResponseSchema,
   },
   {
     operationId: "platform_callback_routes_list",
@@ -353,5 +428,6 @@ export const ROUTES: RouteDefinition[] = [
       "Lists all callback routes registered with the platform for this assistant.",
     tags: ["platform"],
     handler: handleCallbackRoutesList,
+    responseBody: CallbackRoutesListResponseSchema,
   },
 ];

package/src/runtime/routes/playground/__tests__/force-compact.test.ts

@@ -65,8 +65,12 @@ function makeFakeConversation(
     ...options.result,
   };
 
+  let processing = options.processing ?? false;
   const fake = {
-    processing: options.processing ?? false,
+    isProcessing: () => processing,
+    setProcessing: (value: boolean) => {
+      processing = value;
+    },
     getMessages(): Message[] {
       if (!returnedAfter && calls === 0) return messagesBefore;
       return messagesAfter;
@@ -85,9 +89,7 @@ function makeFakeConversation(
 }
 
 function findRoute() {
-  const route = ROUTES.find(
-    (r) => r.operationId === "playgroundForceCompact",
-  );
+  const route = ROUTES.find((r) => r.operationId === "playgroundForceCompact");
   if (!route) throw new Error("force-compact route not registered");
   return route;
 }

package/src/runtime/routes/playground/force-compact.ts

@@ -35,7 +35,7 @@ export const ROUTES: RouteDefinition[] = [
         throwConversationNotFound(id);
       }
 
-      if (conversation.processing) {
+      if (conversation.isProcessing()) {
         throw new ConflictError(
           "Compaction already in progress for this conversation",
         );

package/src/runtime/routes/playground/helpers.ts

@@ -7,9 +7,9 @@
  */
 
 import type { Conversation } from "../../../daemon/conversation.js";
+import { findConversation } from "../../../daemon/conversation-registry.js";
 import {
   destroyActiveConversation,
-  findConversation,
   getOrCreateConversation,
 } from "../../../daemon/conversation-store.js";
 import {

package/src/runtime/routes/rename-conversation-routes.ts

@@ -23,6 +23,10 @@ const RenameConversationBody = z.object({
   title: z.string().min(1),
 });
 
+const RenameConversationResponse = z.object({
+  ok: z.literal(true),
+});
+
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "rename_conversation",
@@ -36,6 +40,7 @@ export const ROUTES: RouteDefinition[] = [
     description: "Update the display title of a conversation.",
     tags: ["conversations"],
     requestBody: RenameConversationBody,
+    responseBody: RenameConversationResponse,
     handler: ({ body, headers }) => {
       const parsed = RenameConversationBody.safeParse(body);
       if (!parsed.success) {