@vellumai/assistant 0.5.10 → 0.5.12

package/src/runtime/routes/channel-verification-routes.ts

@@ -8,6 +8,8 @@
  * GET    /v1/channel-verification-sessions/status   — check guardian binding status
  */
 
+import { z } from "zod";
+
 import type { ChannelId } from "../../channels/types.js";
 import {
   createInboundChallenge,
@@ -243,31 +245,77 @@ export async function handleRevokeVerificationBinding(
 
 export function channelVerificationRouteDefinitions(): RouteDefinition[] {
   return [
-    // Channel verification (unified session API)
     {
       endpoint: "channel-verification-sessions",
       method: "POST",
+      summary: "Create verification session",
+      description:
+        "Create a channel verification session (inbound challenge, outbound, or trusted contact).",
+      tags: ["channel-verification"],
+      requestBody: z.object({
+        channel: z.string().describe("Channel ID"),
+        destination: z.string().describe("Outbound destination"),
+        rebind: z.boolean(),
+        conversationId: z.string(),
+        originConversationId: z.string(),
+        purpose: z.string().describe("guardian or trusted_contact"),
+        contactChannelId: z.string(),
+      }),
       handler: async ({ req, authContext }) =>
         handleCreateVerificationSession(req, authContext.assistantId),
     },
     {
       endpoint: "channel-verification-sessions/resend",
       method: "POST",
+      summary: "Resend verification code",
+      description: "Resend the outbound verification code.",
+      tags: ["channel-verification"],
+      requestBody: z.object({
+        channel: z.string(),
+        originConversationId: z.string().optional(),
+      }),
       handler: async ({ req }) => handleResendVerificationSession(req),
     },
     {
       endpoint: "channel-verification-sessions",
       method: "DELETE",
+      summary: "Cancel verification sessions",
+      description:
+        "Cancel all active inbound and outbound verification sessions.",
+      tags: ["channel-verification"],
+      requestBody: z.object({
+        channel: z.string(),
+      }),
+      responseBody: z.object({
+        success: z.boolean(),
+        channel: z.string(),
+      }),
       handler: async ({ req }) => handleCancelVerificationSession(req),
     },
     {
       endpoint: "channel-verification-sessions/revoke",
       method: "POST",
+      summary: "Revoke verification binding",
+      description: "Cancel all sessions and revoke the guardian binding.",
+      tags: ["channel-verification"],
+      requestBody: z.object({
+        channel: z.string(),
+      }),
       handler: async ({ req }) => handleRevokeVerificationBinding(req),
     },
     {
       endpoint: "channel-verification-sessions/status",
       method: "GET",
+      summary: "Get verification status",
+      description: "Check guardian binding and verification session status.",
+      tags: ["channel-verification"],
+      queryParams: [
+        {
+          name: "channel",
+          schema: { type: "string" },
+          description: "Optional channel ID filter",
+        },
+      ],
       handler: ({ url }) => handleGetVerificationStatus(url),
     },
   ];

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

@@ -9,6 +9,8 @@
  * PATCH  /v1/contact-channels/:contactChannelId — update a contact channel's status/policy
  */
 
+import { z } from "zod";
+
 import {
   deleteContact,
   getAssistantContactMetadata,
@@ -417,22 +419,82 @@ export function contactRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "contacts",
       method: "GET",
+      summary: "List contacts",
+      description:
+        "Return all contacts, optionally filtered by type or channel status.",
+      tags: ["contacts"],
+      responseBody: z.object({
+        ok: z.boolean(),
+        contacts: z
+          .array(z.unknown())
+          .describe("Contact objects with channels and metadata"),
+      }),
       handler: ({ url }) => handleListContacts(url),
     },
     {
       endpoint: "contacts",
       method: "POST",
+      summary: "Create or update a contact",
+      description:
+        "Create a new contact or update an existing one. Supports upsert by contactId or channel handle.",
+      tags: ["contacts"],
+      requestBody: z.object({
+        contactId: z.string().describe("Existing contact ID (for update)"),
+        displayName: z.string().describe("Display name"),
+        channels: z
+          .array(z.unknown())
+          .describe("Channel objects with channelId, handle, displayName"),
+        assistantMetadata: z
+          .object({})
+          .passthrough()
+          .describe("Assistant-side metadata"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+        contact: z
+          .object({})
+          .passthrough()
+          .describe("Created or updated contact"),
+      }),
       handler: async ({ req }) => handleUpsertContact(req),
     },
     {
       endpoint: "contacts/merge",
       method: "POST",
+      summary: "Merge two contacts",
+      description: "Merge two contacts, keeping one and absorbing the other.",
+      tags: ["contacts"],
+      requestBody: z.object({
+        keepId: z.string().describe("ID of the contact to keep"),
+        mergeId: z
+          .string()
+          .describe("ID of the contact to merge into the kept one"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+        contact: z.object({}).passthrough().describe("Merged contact"),
+      }),
       handler: async ({ req }) => handleMergeContacts(req),
     },
     {
       endpoint: "contact-channels/:contactChannelId",
       method: "PATCH",
       policyKey: "contact-channels",
+      summary: "Update a contact channel",
+      description: "Update status, policy, or reason on a contact's channel.",
+      tags: ["contacts"],
+      requestBody: z.object({
+        status: z.string().describe("Channel status"),
+        policy: z.string().describe("Channel policy"),
+        reason: z.string().describe("Reason for the change"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+        contact: z
+          .object({})
+          .passthrough()
+          .describe("Updated contact (if applicable)"),
+      }),
       handler: async ({ req, params }) =>
         handleUpdateContactChannel(req, params.contactChannelId),
     },
@@ -450,12 +512,27 @@ export function contactCatchAllRouteDefinitions(): RouteDefinition[] {
       endpoint: "contacts/:id",
       method: "GET",
       policyKey: "contacts",
+      summary: "Get a contact",
+      description:
+        "Return a single contact with its channels and assistant metadata.",
+      tags: ["contacts"],
+      responseBody: z.object({
+        ok: z.boolean(),
+        contact: z.object({}).passthrough().describe("Contact details"),
+        assistantMetadata: z
+          .object({})
+          .passthrough()
+          .describe("Assistant-side metadata"),
+      }),
       handler: ({ params }) => handleGetContact(params.id),
     },
     {
       endpoint: "contacts/:id",
       method: "DELETE",
       policyKey: "contacts",
+      summary: "Delete a contact",
+      description: "Delete a contact by ID.",
+      tags: ["contacts"],
       handler: ({ params }) => handleDeleteContact(params.id),
     },
   ];

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

@@ -4,6 +4,8 @@
  * useful for assistant/LLM reporting and UI indicators.
  */
 
+import { z } from "zod";
+
 import {
   type AttentionFilterState,
   listConversationAttention,
@@ -134,6 +136,41 @@ export function conversationAttentionRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "conversations/attention",
       method: "GET",
+      summary: "List conversation attention states",
+      description:
+        "Return attention state (seen/unseen) for conversations, with pagination.",
+      tags: ["conversations"],
+      queryParams: [
+        {
+          name: "state",
+          schema: { type: "string" },
+          description: "Filter: seen, unseen, or all (default all)",
+        },
+        {
+          name: "source",
+          schema: { type: "string" },
+          description: "Filter by source (default all)",
+        },
+        {
+          name: "channel",
+          schema: { type: "string" },
+          description: "Filter by source channel",
+        },
+        {
+          name: "limit",
+          schema: { type: "integer" },
+          description: "Max results (1–100, default 20)",
+        },
+        {
+          name: "before",
+          schema: { type: "number" },
+          description: "Cursor for pagination (timestamp)",
+        },
+      ],
+      responseBody: z.object({
+        conversations: z.array(z.unknown()).describe("Attention state objects"),
+        hasMore: z.boolean(),
+      }),
       handler: ({ url }) => handleListConversationAttention(url),
     },
   ];

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

@@ -14,9 +14,13 @@
  * POST   /v1/conversations/reorder        — reorder / pin conversations
  */
 
+import { z } from "zod";
+
 import {
   batchSetDisplayOrders,
+  countConversationsByScheduleJobId,
   deleteConversation,
+  getConversation,
   PRIVATE_CONVERSATION_FORK_ERROR,
   wipeConversation,
 } from "../../memory/conversation-crud.js";
@@ -27,6 +31,7 @@ import {
   setConversationKeyIfAbsent,
 } from "../../memory/conversation-key-store.js";
 import { enqueueMemoryJob } from "../../memory/jobs-store.js";
+import { deleteSchedule } from "../../schedule/schedule-store.js";
 import { UserError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
 import { httpError } from "../http-errors.js";
@@ -73,6 +78,22 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations",
       method: "POST",
       policyKey: "conversations",
+      summary: "Create a conversation",
+      description: "Create or get an existing conversation by key.",
+      tags: ["conversations"],
+      requestBody: z.object({
+        conversationKey: z
+          .string()
+          .describe("Idempotency key for the conversation"),
+        conversationType: z
+          .string()
+          .describe("'standard' (default) or 'private'"),
+      }),
+      responseBody: z.object({
+        id: z.string(),
+        conversationKey: z.string(),
+        conversationType: z.string(),
+      }),
       handler: async ({ req }) => {
         let body: { conversationKey?: string; conversationType?: string } = {};
         try {
@@ -111,6 +132,17 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations/fork",
       method: "POST",
       policyKey: "conversations/fork",
+      summary: "Fork a conversation",
+      description:
+        "Create a copy of a conversation, optionally truncated at a specific message.",
+      tags: ["conversations"],
+      requestBody: z.object({
+        conversationId: z.string(),
+        throughMessageId: z
+          .string()
+          .describe("Truncate the fork at this message")
+          .optional(),
+      }),
       handler: async ({ req }) => {
         if (!deps.forkConversation) {
           return httpError(
@@ -172,6 +204,21 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations/switch",
       method: "POST",
       policyKey: "conversations/switch",
+      summary: "Switch active conversation",
+      description: "Set the active conversation for the current session.",
+      tags: ["conversations"],
+      requestBody: z.object({
+        conversationId: z.string(),
+        conversationKey: z
+          .string()
+          .describe("Optional key to register for this conversation")
+          .optional(),
+      }),
+      responseBody: z.object({
+        conversationId: z.string(),
+        title: z.string(),
+        conversationType: z.string(),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as {
           conversationId?: string;
@@ -206,6 +253,12 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations/:id/name",
       method: "PATCH",
       policyKey: "conversations/name",
+      summary: "Rename a conversation",
+      description: "Update the display name of a conversation.",
+      tags: ["conversations"],
+      requestBody: z.object({
+        name: z.string(),
+      }),
       handler: async ({ req, params }) => {
         const body = (await req.json()) as { name?: string };
         const name = body.name;
@@ -227,6 +280,10 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations",
       method: "DELETE",
       policyKey: "conversations/clear-all",
+      summary: "Clear all conversations",
+      description:
+        "Permanently delete ALL conversations, messages, and memory. Requires X-Confirm-Destructive header.",
+      tags: ["conversations"],
       handler: ({ req }) => {
         const confirm = req.headers.get("x-confirm-destructive");
         if (confirm !== "clear-all-conversations") {
@@ -245,6 +302,16 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations/:id/wipe",
       method: "POST",
       policyKey: "conversations/wipe",
+      summary: "Wipe a conversation",
+      description:
+        "Delete all messages in a conversation and revert associated memory changes.",
+      tags: ["conversations"],
+      responseBody: z.object({
+        wiped: z.boolean(),
+        unsupersededItems: z.number().int(),
+        deletedSummaries: z.number().int(),
+        cancelledJobs: z.number().int(),
+      }),
       handler: async ({ params }) => {
         const resolvedId = resolveConversationId(params.id);
         if (!resolvedId) {
@@ -254,6 +321,20 @@ export function conversationManagementRouteDefinitions(
             404,
           );
         }
+
+        // Cancel the associated schedule job (if any) before wiping the
+        // conversation — but only when this is the last conversation that
+        // references the schedule.  Recurring schedules create a new
+        // conversation per run, so we must not cancel the schedule when
+        // earlier run conversations are cleaned up.
+        const conv = getConversation(resolvedId);
+        if (
+          conv?.scheduleJobId &&
+          countConversationsByScheduleJobId(conv.scheduleJobId) <= 1
+        ) {
+          deleteSchedule(conv.scheduleJobId);
+        }
+
         deps.destroyConversation(resolvedId);
         const result = wipeConversation(resolvedId);
         // Enqueue Qdrant vector cleanup jobs
@@ -296,6 +377,9 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations/:id",
       method: "DELETE",
       policyKey: "conversations",
+      summary: "Delete a conversation",
+      description: "Permanently delete a single conversation and its messages.",
+      tags: ["conversations"],
       handler: async ({ params }) => {
         const resolvedId = resolveConversationId(params.id);
         if (!resolvedId) {
@@ -305,6 +389,20 @@ export function conversationManagementRouteDefinitions(
             404,
           );
         }
+
+        // Cancel the associated schedule job (if any) before deleting the
+        // conversation — but only when this is the last conversation that
+        // references the schedule.  Recurring schedules create a new
+        // conversation per run, so we must not cancel the schedule when
+        // earlier run conversations are cleaned up.
+        const conv = getConversation(resolvedId);
+        if (
+          conv?.scheduleJobId &&
+          countConversationsByScheduleJobId(conv.scheduleJobId) <= 1
+        ) {
+          deleteSchedule(conv.scheduleJobId);
+        }
+
         // Tear down the in-memory conversation (abort + dispose) before removing
         // persistence so that a running agent loop doesn't write to a deleted
         // conversation row, tripping FK constraints.
@@ -339,6 +437,10 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations/:id/cancel",
       method: "POST",
       policyKey: "conversations/cancel",
+      summary: "Cancel generation",
+      description:
+        "Abort the in-progress assistant response for a conversation.",
+      tags: ["conversations"],
       handler: ({ params }) => {
         const resolvedId = resolveConversationId(params.id) ?? params.id;
         deps.cancelGeneration(resolvedId);
@@ -349,6 +451,14 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations/:id/undo",
       method: "POST",
       policyKey: "conversations/undo",
+      summary: "Undo last message",
+      description:
+        "Remove the most recent user+assistant message pair from the conversation.",
+      tags: ["conversations"],
+      responseBody: z.object({
+        removedCount: z.number().int(),
+        conversationId: z.string(),
+      }),
       handler: async ({ params }) => {
         const result = await deps.undoLastMessage(params.id);
         if (!result) {
@@ -368,6 +478,10 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations/:id/regenerate",
       method: "POST",
       policyKey: "conversations/regenerate",
+      summary: "Regenerate response",
+      description:
+        "Re-run the assistant for the last user message in a conversation.",
+      tags: ["conversations"],
       handler: async ({ params }) => {
         try {
           const result = await deps.regenerateResponse(params.id);
@@ -397,6 +511,17 @@ export function conversationManagementRouteDefinitions(
       endpoint: "conversations/reorder",
       method: "POST",
       policyKey: "conversations/reorder",
+      summary: "Reorder conversations",
+      description:
+        "Batch-update display order and pin state for conversations.",
+      tags: ["conversations"],
+      requestBody: z.object({
+        updates: z
+          .array(z.unknown())
+          .describe(
+            "Array of { conversationId, displayOrder?, isPinned? } objects",
+          ),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as {
           updates?: Array<{

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

@@ -20,6 +20,8 @@
  * DELETE /v1/messages/queued/:id        — delete queued message
  */
 
+import { z } from "zod";
+
 import {
   deepMergeOverwrite,
   getConfig,
@@ -43,7 +45,9 @@ import {
   performConversationSearch,
 } from "../../daemon/handlers/conversation-history.js";
 import { deleteQueuedMessage } from "../../daemon/handlers/conversations.js";
+import { getAssistantMessageIdsInTurn } from "../../memory/conversation-crud.js";
 import { getRequestLogsByMessageId } from "../../memory/llm-request-log-store.js";
+import { getMemoryRecallLogByMessageIds } from "../../memory/memory-recall-log-store.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 import { normalizeLlmContextPayloads } from "./llm-context-normalization.js";
@@ -109,6 +113,10 @@ export function conversationQueryRouteDefinitions(
       endpoint: "model",
       method: "GET",
       policyKey: "model",
+      summary: "Get current model config",
+      description:
+        "Return the active LLM model ID, provider, and available models.",
+      tags: ["config"],
       handler: async () => {
         const info = await getModelInfo();
         return Response.json(info);
@@ -118,6 +126,13 @@ export function conversationQueryRouteDefinitions(
       endpoint: "model",
       method: "PUT",
       policyKey: "model",
+      summary: "Set LLM model",
+      description: "Change the active LLM model and optionally its provider.",
+      tags: ["config"],
+      requestBody: z.object({
+        modelId: z.string(),
+        provider: z.string().describe("Optional provider override").optional(),
+      }),
       handler: async ({ req }) => {
         if (!deps.getModelSetContext) {
           return httpError("INTERNAL_ERROR", "Model set not available", 500);
@@ -165,6 +180,12 @@ export function conversationQueryRouteDefinitions(
       endpoint: "model/image-gen",
       method: "PUT",
       policyKey: "model/image-gen",
+      summary: "Set image generation model",
+      description: "Change the active image generation model.",
+      tags: ["config"],
+      requestBody: z.object({
+        modelId: z.string(),
+      }),
       handler: async ({ req }) => {
         if (!deps.getModelSetContext) {
           return httpError(
@@ -200,6 +221,10 @@ export function conversationQueryRouteDefinitions(
       endpoint: "config/embeddings",
       method: "GET",
       policyKey: "config/embeddings",
+      summary: "Get embedding config",
+      description:
+        "Return the active embedding provider, model, and available options.",
+      tags: ["config"],
       handler: async () => {
         const info = await getEmbeddingConfigInfo();
         return Response.json(info);
@@ -209,6 +234,13 @@ export function conversationQueryRouteDefinitions(
       endpoint: "config/embeddings",
       method: "PUT",
       policyKey: "config/embeddings",
+      summary: "Set embedding config",
+      description: "Change the embedding provider and optionally model.",
+      tags: ["config"],
+      requestBody: z.object({
+        provider: z.string(),
+        model: z.string().optional(),
+      }),
       handler: async ({ req }) => {
         if (!deps.getModelSetContext) {
           return httpError(
@@ -265,6 +297,12 @@ export function conversationQueryRouteDefinitions(
       endpoint: "config/permissions/skip",
       method: "GET",
       policyKey: "config/permissions/skip",
+      summary: "Get permission-skip flag",
+      description: "Return whether dangerouslySkipPermissions is enabled.",
+      tags: ["config"],
+      responseBody: z.object({
+        enabled: z.boolean(),
+      }),
       handler: () => {
         const config = getConfig();
         return Response.json({
@@ -276,6 +314,12 @@ export function conversationQueryRouteDefinitions(
       endpoint: "config/permissions/skip",
       method: "PUT",
       policyKey: "config/permissions/skip",
+      summary: "Set permission-skip flag",
+      description: "Enable or disable dangerouslySkipPermissions.",
+      tags: ["config"],
+      requestBody: z.object({
+        enabled: z.boolean(),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as { enabled?: unknown };
         if (typeof body.enabled !== "boolean") {
@@ -304,6 +348,9 @@ export function conversationQueryRouteDefinitions(
       endpoint: "config",
       method: "GET",
       policyKey: "config",
+      summary: "Get full config",
+      description: "Return the raw settings.json configuration object.",
+      tags: ["config"],
       handler: () => {
         try {
           const raw = loadRawConfig();
@@ -324,6 +371,10 @@ export function conversationQueryRouteDefinitions(
       endpoint: "config",
       method: "PATCH",
       policyKey: "config",
+      summary: "Patch config",
+      description:
+        "Deep-merge a partial JSON object into the settings.json configuration.",
+      tags: ["config"],
       handler: async ({ req }) => {
         const body = (await req.json()) as Record<string, unknown>;
         if (
@@ -359,6 +410,14 @@ export function conversationQueryRouteDefinitions(
       endpoint: "conversations/search",
       method: "GET",
       policyKey: "conversations/search",
+      summary: "Search conversations",
+      description:
+        "Full-text search across conversation titles and message content.",
+      tags: ["conversations"],
+      responseBody: z.object({
+        query: z.string(),
+        results: z.array(z.unknown()),
+      }),
       handler: ({ url }) => {
         const q = url.searchParams.get("q");
         if (!q) {
@@ -388,6 +447,9 @@ export function conversationQueryRouteDefinitions(
       endpoint: "messages/:id/content",
       method: "GET",
       policyKey: "messages/content",
+      summary: "Get message content",
+      description: "Return the full content of a single message by ID.",
+      tags: ["messages"],
       handler: ({ url, params }) => {
         const conversationId = url.searchParams.get("conversationId");
         const result = getMessageContent(
@@ -406,12 +468,23 @@ export function conversationQueryRouteDefinitions(
       endpoint: "messages/:id/llm-context",
       method: "GET",
       policyKey: "messages/llm-context",
+      summary: "Get LLM context for a message",
+      description:
+        "Return request/response logs and memory recall data for a specific message.",
+      tags: ["messages"],
+      responseBody: z.object({
+        messageId: z.string(),
+        logs: z.array(z.unknown()),
+        memoryRecall: z.object({}).passthrough(),
+      }),
       handler: ({ params }) => {
         const messageId = params.id;
         if (!messageId) {
           return httpError("BAD_REQUEST", "message id is required", 400);
         }
         const logs = getRequestLogsByMessageId(messageId);
+        const turnMessageIds = getAssistantMessageIdsInTurn(messageId);
+        const memoryRecallLog = getMemoryRecallLogByMessageIds(turnMessageIds);
         return Response.json({
           messageId,
           logs: logs.map((log) => {
@@ -444,6 +517,7 @@ export function conversationQueryRouteDefinitions(
               ...result,
             };
           }),
+          memoryRecall: memoryRecallLog ?? null,
         });
       },
     },
@@ -453,6 +527,10 @@ export function conversationQueryRouteDefinitions(
       endpoint: "messages/queued/:id",
       method: "DELETE",
       policyKey: "messages/queued",
+      summary: "Delete a queued message",
+      description:
+        "Remove a pending message from the conversation queue before it is processed.",
+      tags: ["messages"],
       handler: ({ url, params }) => {
         if (!deps.findConversationForQueue) {
           return httpError(