@vellumai/assistant 0.5.9 → 0.5.11

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

@@ -10,6 +10,7 @@
 
 import { and, asc, count, desc, eq, inArray, like, ne, or } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
+import { z } from "zod";
 
 import { getConfig } from "../../config/loader.js";
 import { getDb } from "../../memory/db.js";
@@ -597,7 +598,11 @@ export async function handleUpdateMemoryItem(
   // If sourceType was set (either directly or via mapping), also write verificationState
   if (body.sourceType !== undefined && body.verificationState === undefined) {
     set.verificationState =
-      body.sourceType === "tool" ? "user_confirmed" : "assistant_inferred";
+      body.sourceType === "tool"
+        ? "user_confirmed"
+        : existing.verificationState === "user_reported"
+          ? "user_reported"
+          : "assistant_inferred";
   }
 
   // If subject, statement, or kind changed, recompute fingerprint
@@ -717,29 +722,122 @@ export function memoryItemRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "memory-items",
       method: "GET",
+      summary: "List memory items",
+      description:
+        "Return memory items with filtering, search, sorting, and pagination.",
+      tags: ["memory"],
+      queryParams: [
+        {
+          name: "kind",
+          schema: { type: "string" },
+          description: "Filter by kind",
+        },
+        {
+          name: "status",
+          schema: { type: "string" },
+          description: "Filter by status (default active)",
+        },
+        {
+          name: "search",
+          schema: { type: "string" },
+          description: "Full-text search query",
+        },
+        {
+          name: "sort",
+          schema: { type: "string" },
+          description: "Sort field (default lastSeenAt)",
+        },
+        {
+          name: "order",
+          schema: { type: "string" },
+          description: "asc or desc (default desc)",
+        },
+        {
+          name: "limit",
+          schema: { type: "integer" },
+          description: "Max results (default 100)",
+        },
+        {
+          name: "offset",
+          schema: { type: "integer" },
+          description: "Pagination offset",
+        },
+      ],
+      responseBody: z.object({
+        items: z.array(z.unknown()).describe("Memory item objects"),
+        total: z.number(),
+      }),
       handler: (ctx) => handleListMemoryItems(ctx.url),
     },
     {
       endpoint: "memory-items/:id",
       method: "GET",
       policyKey: "memory-items",
+      summary: "Get a memory item",
+      description:
+        "Return a single memory item by ID with supersession metadata.",
+      tags: ["memory"],
+      responseBody: z.object({
+        item: z
+          .object({})
+          .passthrough()
+          .describe("Memory item with scopeLabel and supersession info"),
+      }),
       handler: (ctx) => handleGetMemoryItem(ctx),
     },
     {
       endpoint: "memory-items",
       method: "POST",
+      summary: "Create a memory item",
+      description: "Create a new memory item and enqueue embedding.",
+      tags: ["memory"],
+      requestBody: z.object({
+        kind: z
+          .string()
+          .describe("Memory kind (identity, preference, project, etc.)"),
+        subject: z.string().describe("Subject line"),
+        statement: z.string().describe("Statement content"),
+        importance: z
+          .number()
+          .describe("Importance score (default 0.8)")
+          .optional(),
+      }),
+      responseBody: z.object({
+        item: z.object({}).passthrough().describe("Created memory item"),
+      }),
       handler: (ctx) => handleCreateMemoryItem(ctx),
     },
     {
       endpoint: "memory-items/:id",
       method: "PATCH",
       policyKey: "memory-items",
+      summary: "Update a memory item",
+      description: "Partially update fields on an existing memory item.",
+      tags: ["memory"],
+      requestBody: z.object({
+        subject: z.string(),
+        statement: z.string(),
+        kind: z.string(),
+        status: z.string(),
+        importance: z.number(),
+        sourceType: z.string(),
+        verificationState: z.string(),
+      }),
+      responseBody: z.object({
+        item: z.object({}).passthrough().describe("Updated memory item"),
+      }),
       handler: (ctx) => handleUpdateMemoryItem(ctx),
     },
     {
       endpoint: "memory-items/:id",
       method: "DELETE",
       policyKey: "memory-items",
+      summary: "Delete a memory item",
+      description: "Delete a memory item and its embeddings.",
+      tags: ["memory"],
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: (ctx) => handleDeleteMemoryItem(ctx),
     },
   ];

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() === "") {
@@ -159,7 +163,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),
     },
   ];