@vellumai/assistant 0.5.10 → 0.5.12

package/src/runtime/routes/migration-rollback-routes.ts

@@ -7,6 +7,8 @@
  * the same pattern as other gateway-forwarded control-plane endpoints.
  */
 
+import { z } from "zod";
+
 import { getDb } from "../../memory/db-connection.js";
 import { getMaxMigrationVersion } from "../../memory/migrations/registry.js";
 import { rollbackMemoryMigration } from "../../memory/migrations/validate-migration-state.js";
@@ -25,6 +27,29 @@ export function migrationRollbackRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "admin/rollback-migrations",
       method: "POST",
+      summary: "Rollback migrations",
+      description:
+        "Roll back DB and/or workspace migrations to a specified target version. Restricted to gateway service principals.",
+      tags: ["admin"],
+      requestBody: z.object({
+        targetDbVersion: z
+          .number()
+          .int()
+          .describe("Target DB migration version"),
+        targetWorkspaceMigrationId: z
+          .string()
+          .describe("Target workspace migration ID"),
+        rollbackToRegistryCeiling: z
+          .boolean()
+          .describe("Auto-determine targets from daemon registry ceilings"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+        rolledBack: z
+          .object({})
+          .passthrough()
+          .describe("Lists of rolled-back DB and workspace migrations"),
+      }),
       handler: async ({ req }) => {
         let body: unknown;
         try {

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

@@ -14,6 +14,8 @@
 import { join } from "node:path";
 import { Database } from "bun:sqlite";
 
+import { z } from "zod";
+
 import { invalidateConfigCache } from "../../config/loader.js";
 import { getDb, resetDb } from "../../memory/db-connection.js";
 import { validateMigrationState } from "../../memory/migrations/validate-migration-state.js";
@@ -474,21 +476,59 @@ export function migrationRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "migrations/validate",
       method: "POST",
+      summary: "Validate a .vbundle archive",
+      description:
+        "Upload a .vbundle archive for validation. Accepts raw binary or multipart form data.",
+      tags: ["migrations"],
+      responseBody: z.object({
+        is_valid: z.boolean(),
+        errors: z.array(z.unknown()),
+        manifest: z.object({}).passthrough(),
+      }),
       handler: async ({ req }) => handleMigrationValidate(req),
     },
     {
       endpoint: "migrations/export",
       method: "POST",
+      summary: "Export a .vbundle archive",
+      description:
+        "Generate and download a .vbundle archive of the assistant's data. Optional JSON body for metadata.",
+      tags: ["migrations"],
+      requestBody: z.object({
+        description: z.string().describe("Human-readable export description"),
+      }),
       handler: async ({ req }) => handleMigrationExport(req),
     },
     {
       endpoint: "migrations/import-preflight",
       method: "POST",
+      summary: "Dry-run import analysis",
+      description:
+        "Validate a .vbundle archive and return a report of what would change on import without modifying data.",
+      tags: ["migrations"],
+      responseBody: z.object({
+        can_import: z.boolean(),
+        summary: z.object({}).passthrough(),
+        files: z.array(z.unknown()),
+        conflicts: z.array(z.unknown()),
+        manifest: z.object({}).passthrough(),
+      }),
       handler: async ({ req }) => handleMigrationImportPreflight(req),
     },
     {
       endpoint: "migrations/import",
       method: "POST",
+      summary: "Import a .vbundle archive",
+      description:
+        "Commit a .vbundle archive import to disk — destructive. Backs up existing files before overwriting.",
+      tags: ["migrations"],
+      responseBody: z.object({
+        success: z.boolean(),
+        summary: z.object({}).passthrough(),
+        files: z.array(z.unknown()),
+        manifest: z.object({}).passthrough(),
+        warnings: z.array(z.unknown()),
+      }),
       handler: async ({ req }) => handleMigrationImport(req),
     },
   ];

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

@@ -6,6 +6,7 @@
  */
 
 import { eq } from "drizzle-orm";
+import { z } from "zod";
 
 import { getDb } from "../../memory/db.js";
 import { notificationDeliveries } from "../../memory/schema.js";
@@ -19,6 +20,25 @@ export function notificationRouteDefinitions(): RouteDefinition[] {
       endpoint: "notification-intent-result",
       method: "POST",
       policyKey: "notification-intent-result",
+      summary: "Report notification delivery result",
+      description:
+        "Client acknowledgment for local notification delivery outcome.",
+      tags: ["notifications"],
+      requestBody: z.object({
+        deliveryId: z.string().describe("Notification delivery ID"),
+        success: z.boolean().describe("Whether delivery succeeded").optional(),
+        errorMessage: z
+          .string()
+          .describe("Error message if delivery failed")
+          .optional(),
+        errorCode: z
+          .string()
+          .describe("Error code if delivery failed")
+          .optional(),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as {
           deliveryId?: string;

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

@@ -21,9 +21,13 @@ import {
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 
-function parseGrantedScopes(grantedScopes: string | string[] | null | undefined): string[] {
+function parseGrantedScopes(
+  grantedScopes: string | string[] | null | undefined,
+): string[] {
   if (Array.isArray(grantedScopes)) {
-    return grantedScopes.filter((scope): scope is string => typeof scope === "string");
+    return grantedScopes.filter(
+      (scope): scope is string => typeof scope === "string",
+    );
   }
 
   if (typeof grantedScopes !== "string" || grantedScopes.trim() === "") {
@@ -77,7 +81,8 @@ export function oauthAppsRouteDefinitions(): RouteDefinition[] {
               description: providerRow.description ?? null,
               dashboard_url: providerRow.dashboardUrl ?? null,
               client_id_placeholder: providerRow.clientIdPlaceholder ?? null,
-              requires_client_secret: providerRow.requiresClientSecret ?? 1,
+              requires_client_secret: !!(providerRow.requiresClientSecret ?? 1),
+              supports_managed_mode: !!providerRow.managedServiceConfigKey,
             }
           : null;
 
@@ -159,7 +164,11 @@ export function oauthAppsRouteDefinitions(): RouteDefinition[] {
       handler: async ({ params }) => {
         const app = getApp(params.id);
         if (!app) {
-          return httpError("NOT_FOUND", `OAuth app not found: ${params.id}`, 404);
+          return httpError(
+            "NOT_FOUND",
+            `OAuth app not found: ${params.id}`,
+            404,
+          );
         }
 
         // Disconnect all connections for this app first to clean up tokens.

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

@@ -2,6 +2,8 @@
  * Pairing HTTP route handlers for device pairing flow.
  */
 
+import { z } from "zod";
+
 import {
   hashDeviceId,
   isDeviceApproved,
@@ -417,6 +419,19 @@ export function pairingRouteDefinitions(deps: {
     {
       endpoint: "pairing/register",
       method: "POST",
+      summary: "Register pairing request",
+      description:
+        "Pre-register a pairing request when the QR code is displayed.",
+      tags: ["pairing"],
+      requestBody: z.object({
+        pairingRequestId: z.string(),
+        pairingSecret: z.string(),
+        gatewayUrl: z.string(),
+        localLanUrl: z.string().optional(),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req }) =>
         handlePairingRegister(req, deps.getPairingContext()),
     },

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

@@ -9,6 +9,8 @@
  * require `settings.read`.
  */
 
+import { z } from "zod";
+
 import {
   getActiveRestartToken,
   handleRecordingPause,
@@ -298,36 +300,106 @@ export function recordingRouteDefinitions(deps: {
       endpoint: "recordings/start",
       method: "POST",
       policyKey: "recordings/start",
+      summary: "Start recording",
+      description: "Start a screen recording for a conversation.",
+      tags: ["recordings"],
+      requestBody: z.object({
+        conversationId: z.string(),
+        options: z
+          .object({})
+          .passthrough()
+          .describe("Recording options")
+          .optional(),
+      }),
+      responseBody: z.object({
+        recordingId: z.string(),
+      }),
       handler: async ({ req }) => handleStartRecording(req, getDeps()),
     },
     {
       endpoint: "recordings/stop",
       method: "POST",
       policyKey: "recordings/stop",
+      summary: "Stop recording",
+      description: "Stop the active screen recording.",
+      tags: ["recordings"],
+      requestBody: z.object({
+        conversationId: z.string(),
+      }),
+      responseBody: z.object({
+        recordingId: z.string(),
+        stopped: z.boolean(),
+      }),
       handler: async ({ req }) => handleStopRecording(req, getDeps()),
     },
     {
       endpoint: "recordings/pause",
       method: "POST",
       policyKey: "recordings/pause",
+      summary: "Pause recording",
+      description: "Pause the active screen recording.",
+      tags: ["recordings"],
+      requestBody: z.object({
+        conversationId: z.string(),
+      }),
+      responseBody: z.object({
+        recordingId: z.string(),
+        paused: z.boolean(),
+      }),
       handler: async ({ req }) => handlePauseRecording(req, getDeps()),
     },
     {
       endpoint: "recordings/resume",
       method: "POST",
       policyKey: "recordings/resume",
+      summary: "Resume recording",
+      description: "Resume a paused screen recording.",
+      tags: ["recordings"],
+      requestBody: z.object({
+        conversationId: z.string(),
+      }),
+      responseBody: z.object({
+        recordingId: z.string(),
+        resumed: z.boolean(),
+      }),
       handler: async ({ req }) => handleResumeRecording(req, getDeps()),
     },
     {
       endpoint: "recordings/status",
       method: "GET",
       policyKey: "recordings/status",
+      summary: "Get recording status",
+      description: "Return the current recording state.",
+      tags: ["recordings"],
+      responseBody: z.object({
+        idle: z.boolean(),
+        restartInProgress: z.boolean(),
+      }),
       handler: () => handleGetRecordingStatus(),
     },
     {
       endpoint: "recordings/status",
       method: "POST",
       policyKey: "recordings/status:POST",
+      summary: "Post recording status",
+      description: "Recording lifecycle callback from the client.",
+      tags: ["recordings"],
+      requestBody: z.object({
+        conversationId: z.string(),
+        status: z
+          .string()
+          .describe(
+            "started, stopped, failed, restart_cancelled, paused, resumed",
+          ),
+        filePath: z.string().optional(),
+        durationMs: z.number().optional(),
+        error: z.string().optional(),
+        attachToConversationId: z.string().optional(),
+        operationToken: z.string().optional(),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req }) => handlePostRecordingStatus(req, getDeps()),
     },
   ];

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

@@ -4,6 +4,8 @@
  * HTTP route handlers for schedule management.
  */
 
+import { z } from "zod";
+
 import { bootstrapConversation } from "../../memory/conversation-bootstrap.js";
 import {
   cancelSchedule,
@@ -112,11 +114,27 @@ function handleUpdateSchedule(
 ): Response {
   const updates: Record<string, unknown> = {};
 
-  if ("mode" in body && !VALID_MODES.includes(body.mode as (typeof VALID_MODES)[number])) {
-    return httpError("BAD_REQUEST", `Invalid mode: must be one of ${VALID_MODES.join(", ")}`, 400);
+  if (
+    "mode" in body &&
+    !VALID_MODES.includes(body.mode as (typeof VALID_MODES)[number])
+  ) {
+    return httpError(
+      "BAD_REQUEST",
+      `Invalid mode: must be one of ${VALID_MODES.join(", ")}`,
+      400,
+    );
   }
-  if ("routingIntent" in body && !VALID_ROUTING_INTENTS.includes(body.routingIntent as (typeof VALID_ROUTING_INTENTS)[number])) {
-    return httpError("BAD_REQUEST", `Invalid routingIntent: must be one of ${VALID_ROUTING_INTENTS.join(", ")}`, 400);
+  if (
+    "routingIntent" in body &&
+    !VALID_ROUTING_INTENTS.includes(
+      body.routingIntent as (typeof VALID_ROUTING_INTENTS)[number],
+    )
+  ) {
+    return httpError(
+      "BAD_REQUEST",
+      `Invalid routingIntent: must be one of ${VALID_ROUTING_INTENTS.join(", ")}`,
+      400,
+    );
   }
 
   for (const key of [
@@ -276,12 +294,27 @@ export function scheduleRouteDefinitions(deps: {
       endpoint: "schedules",
       method: "GET",
       policyKey: "schedules",
+      summary: "List schedules",
+      description: "Return all scheduled jobs.",
+      tags: ["schedules"],
+      responseBody: z.object({
+        schedules: z.array(z.unknown()).describe("Schedule objects"),
+      }),
       handler: () => handleListSchedules(),
     },
     {
       endpoint: "schedules/:id/toggle",
       method: "POST",
       policyKey: "schedules/toggle",
+      summary: "Toggle schedule",
+      description: "Enable or disable a schedule.",
+      tags: ["schedules"],
+      requestBody: z.object({
+        enabled: z.boolean().describe("New enabled state"),
+      }),
+      responseBody: z.object({
+        schedules: z.array(z.unknown()).describe("Updated schedule list"),
+      }),
       handler: async ({ req, params }) => {
         const body = (await req.json()) as { enabled?: boolean };
         if (body.enabled === undefined) {
@@ -294,16 +327,43 @@ export function scheduleRouteDefinitions(deps: {
       endpoint: "schedules/:id",
       method: "DELETE",
       policyKey: "schedules",
+      summary: "Delete schedule",
+      description: "Remove a schedule by ID.",
+      tags: ["schedules"],
+      responseBody: z.object({
+        schedules: z.array(z.unknown()).describe("Updated schedule list"),
+      }),
       handler: ({ params }) => handleDeleteSchedule(params.id),
     },
     {
       endpoint: "schedules/:id",
       method: "PATCH",
       policyKey: "schedules",
+      summary: "Update schedule",
+      description: "Partially update fields on a schedule.",
+      tags: ["schedules"],
+      requestBody: z.object({
+        name: z.string(),
+        expression: z.string(),
+        timezone: z.string(),
+        message: z.string(),
+        mode: z.string().describe("notify or execute"),
+        routingIntent: z
+          .string()
+          .describe("single_channel, multi_channel, or all_channels"),
+        quiet: z.boolean(),
+      }),
+      responseBody: z.object({
+        schedules: z.array(z.unknown()).describe("Updated schedule list"),
+      }),
       handler: async ({ req, params }) => {
         const body: unknown = await req.json();
         if (typeof body !== "object" || !body || Array.isArray(body)) {
-          return httpError("BAD_REQUEST", "Request body must be a JSON object", 400);
+          return httpError(
+            "BAD_REQUEST",
+            "Request body must be a JSON object",
+            400,
+          );
         }
         return handleUpdateSchedule(params.id, body as Record<string, unknown>);
       },
@@ -312,6 +372,12 @@ export function scheduleRouteDefinitions(deps: {
       endpoint: "schedules/:id/run",
       method: "POST",
       policyKey: "schedules/run",
+      summary: "Run schedule now",
+      description: "Trigger an immediate execution of a schedule.",
+      tags: ["schedules"],
+      responseBody: z.object({
+        schedules: z.array(z.unknown()).describe("Updated schedule list"),
+      }),
       handler: async ({ params }) =>
         handleRunScheduleNow(params.id, deps.sendMessageDeps),
     },
@@ -319,6 +385,12 @@ export function scheduleRouteDefinitions(deps: {
       endpoint: "schedules/:id/cancel",
       method: "POST",
       policyKey: "schedules/cancel",
+      summary: "Cancel schedule",
+      description: "Cancel a pending schedule.",
+      tags: ["schedules"],
+      responseBody: z.object({
+        schedules: z.array(z.unknown()).describe("Updated schedule list"),
+      }),
       handler: ({ params }) => handleCancelSchedule(params.id),
     },
   ];

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

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 import {
   setPlatformAssistantId,
   setPlatformBaseUrl,
@@ -104,7 +106,7 @@ async function queueApiKeyPropagation(
 
 export async function handleAddSecret(
   req: Request,
-  getCesClient?: () => CesClient | undefined,
+  deps?: SecretRouteDeps,
 ): Promise<Response> {
   let body: { type?: string; name?: string; value?: string };
   try {
@@ -190,9 +192,7 @@ export async function handleAddSecret(
           500,
         );
       }
-      clearEmbeddingBackendCache();
-      invalidateConfigCache();
-      await initializeProviders(getConfig());
+      await refreshProvidersAfterSecretChange(deps);
       log.info({ provider: name }, "API key updated via HTTP");
       return Response.json({ success: true, type, name }, { status: 201 });
     }
@@ -273,12 +273,12 @@ export async function handleAddSecret(
         }
       }
       if (isManagedProxyCredential(service, field)) {
-        await initializeProviders(getConfig());
+        await refreshProvidersAfterSecretChange(deps);
         if (service === "vellum" && field === "assistant_api_key") {
           // Push the API key to CES so managed credential materialization
           // works even though the handshake ran before the key was available.
           const generation = ++apiKeyGeneration;
-          const cesClient = getCesClient?.();
+          const cesClient = deps?.getCesClient?.();
           if (cesClient) {
             if (cesClient.isReady()) {
               try {
@@ -392,7 +392,10 @@ export async function handleReadSecret(req: Request): Promise<Response> {
   }
 }
 
-export async function handleDeleteSecret(req: Request): Promise<Response> {
+export async function handleDeleteSecret(
+  req: Request,
+  deps?: SecretRouteDeps,
+): Promise<Response> {
   let body: { type?: string; name?: string };
   try {
     body = (await req.json()) as { type?: string; name?: string };
@@ -436,9 +439,7 @@ export async function handleDeleteSecret(req: Request): Promise<Response> {
           500,
         );
       }
-      clearEmbeddingBackendCache();
-      invalidateConfigCache();
-      await initializeProviders(getConfig());
+      await refreshProvidersAfterSecretChange(deps);
       log.info({ provider: name }, "API key deleted via HTTP");
       return Response.json({ success: true, type, name });
     }
@@ -486,7 +487,7 @@ export async function handleDeleteSecret(req: Request): Promise<Response> {
         setSentryUserId(undefined);
       }
       if (isManagedProxyCredential(service, field)) {
-        await initializeProviders(getConfig());
+        await refreshProvidersAfterSecretChange(deps);
       }
       log.info({ service, field }, "Credential deleted via HTTP");
       return Response.json({ success: true, type, name });
@@ -532,7 +533,7 @@ export async function handleListSecrets(): Promise<Response> {
       return { type: "api_key" as const, name: account };
     });
 
-    return Response.json({ secrets });
+    return Response.json({ secrets, accounts: secrets });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return httpError("INTERNAL_ERROR", message, 500);
@@ -546,6 +547,30 @@ export async function handleListSecrets(): Promise<Response> {
 export interface SecretRouteDeps {
   /** Accessor for the CES client, used to push API key updates after hatch. */
   getCesClient?: () => CesClient | undefined;
+  /**
+   * Called after provider-affecting credentials change so live conversations
+   * can be reloaded with fresh provider instances.
+   */
+  onProviderCredentialsChanged?: () => void | Promise<void>;
+}
+
+async function refreshProvidersAfterSecretChange(
+  deps?: SecretRouteDeps,
+): Promise<void> {
+  clearEmbeddingBackendCache();
+  invalidateConfigCache();
+  await initializeProviders(getConfig());
+
+  if (!deps?.onProviderCredentialsChanged) return;
+
+  try {
+    await deps.onProviderCredentialsChanged();
+  } catch (err) {
+    log.warn(
+      { error: err instanceof Error ? err.message : String(err) },
+      "Failed to refresh live conversations after provider credential change",
+    );
+  }
 }
 
 export function secretRouteDefinitions(
@@ -555,22 +580,82 @@ export function secretRouteDefinitions(
     {
       endpoint: "secrets",
       method: "POST",
-      handler: async ({ req }) => handleAddSecret(req, deps?.getCesClient),
+      handler: async ({ req }) => handleAddSecret(req, deps),
+      summary: "Add a secret",
+      description:
+        "Store a new secret (API key, OAuth token, etc.) in the credential vault.",
+      tags: ["secrets"],
+      requestBody: z.object({
+        type: z.string().describe("Secret type: 'api_key' or 'credential'"),
+        name: z.string().describe("Unique name for the secret"),
+        value: z.string().describe("Secret value to store"),
+      }),
+      responseBody: z.object({
+        success: z.boolean(),
+        type: z.string(),
+        name: z.string(),
+      }),
     },
     {
       endpoint: "secrets",
       method: "DELETE",
-      handler: async ({ req }) => handleDeleteSecret(req),
+      handler: async ({ req }) => handleDeleteSecret(req, deps),
+      summary: "Delete a secret",
+      description: "Remove a secret from the credential vault by name.",
+      tags: ["secrets"],
+      requestBody: z.object({
+        type: z.string().describe("Secret type: 'api_key' or 'credential'"),
+        name: z.string().describe("Name of the secret to delete"),
+      }),
+      responseBody: z.object({
+        success: z.boolean(),
+        type: z.string(),
+        name: z.string(),
+      }),
     },
     {
       endpoint: "secrets",
       method: "GET",
       handler: async () => handleListSecrets(),
+      summary: "List secrets",
+      description: "Return the names (not values) of all stored secrets.",
+      tags: ["secrets"],
+      responseBody: z.object({
+        secrets: z
+          .array(z.unknown())
+          .describe("List of secret metadata entries, each with type and name"),
+        accounts: z
+          .array(z.unknown())
+          .describe("Alias for secrets (same data)"),
+      }),
     },
     {
       endpoint: "secrets/read",
       method: "POST",
       handler: async ({ req }) => handleReadSecret(req),
+      summary: "Read a secret value",
+      description: "Retrieve the decrypted value of a stored secret by name.",
+      tags: ["secrets"],
+      requestBody: z.object({
+        type: z.string().describe("Secret type: 'api_key' or 'credential'"),
+        name: z.string().describe("Name of the secret to read"),
+        reveal: z
+          .boolean()
+          .describe(
+            "If true, return the decrypted value; otherwise return a masked version",
+          )
+          .optional(),
+      }),
+      responseBody: z.object({
+        found: z.boolean(),
+        value: z
+          .string()
+          .describe("Decrypted value (only when reveal=true and found)"),
+        masked: z
+          .string()
+          .describe("Masked value (when reveal=false and found)"),
+        unreachable: z.boolean(),
+      }),
     },
   ];
 }