@vellumai/assistant 0.8.5 → 0.8.6

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

@@ -26,6 +26,7 @@ import {
 } from "../../conversations/message-consolidation.js";
 import { createApprovalConversationGenerator } from "../../daemon/approval-generators.js";
 import type { Conversation } from "../../daemon/conversation.js";
+import { persistQueuedMessageBody } from "../../daemon/conversation-messaging.js";
 import {
   buildModelInfoEvent,
   formatCleanResult,
@@ -75,6 +76,7 @@ import {
 } from "../../memory/canonical-guardian-store.js";
 import {
   addMessage,
+  extractImageSourcePaths,
   getConversation,
   getMessages,
   getMessagesPaginated,
@@ -82,8 +84,6 @@ import {
   type MessageRow,
   provenanceFromTrustContext,
   setConversationInferenceProfile,
-  setConversationOriginChannelIfUnset,
-  setConversationOriginInterfaceIfUnset,
 } from "../../memory/conversation-crud.js";
 import {
   getConversationByKey,
@@ -395,23 +395,10 @@ async function tryConsumeCanonicalGuardianReply(params: {
   // is not re-processed as a new user turn.
   let messageId: string | undefined;
   try {
-    const guardianImageSourcePaths: Record<string, string> = {};
-    for (let i = 0; i < attachments.length; i++) {
-      const a = attachments[i];
-      if (a.filePath && a.mimeType.toLowerCase().startsWith("image/")) {
-        guardianImageSourcePaths[`${i}:${a.filename}`] = a.filePath;
-      }
-    }
-    const channelMeta = {
-      userMessageChannel: sourceChannel,
-      assistantMessageChannel: sourceChannel,
-      userMessageInterface: sourceInterface,
-      assistantMessageInterface: sourceInterface,
-      provenanceTrustClass: "guardian" as const,
-      ...(Object.keys(guardianImageSourcePaths).length > 0
-        ? { imageSourcePaths: guardianImageSourcePaths }
-        : {}),
-    };
+    const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
+      provenanceOverride: { provenanceTrustClass: "guardian" },
+      attachments,
+    });
 
     const cleanUserMessage = createUserMessage(content, attachments);
     const llmUserMessage = enrichMessageWithSourcePaths(
@@ -538,6 +525,10 @@ export function handleListMessages({
 
   let rawMessages: MessageRow[];
   let hasMore = false;
+  // Resume cursor surfaced when the paginated scan stops on its row cap with a
+  // (possibly empty) page — lets us still emit an oldest cursor so the client
+  // can request the next window instead of stalling.
+  let scanResumeCursor: { createdAt: number; id: string } | undefined;
 
   // Drop messages flagged as hidden in metadata (e.g. internal scaffolding
   // like retrospective instructions). The LLM-side history loader
@@ -561,6 +552,7 @@ export function handleListMessages({
     );
     rawMessages = result.messages;
     hasMore = result.hasMore;
+    scanResumeCursor = result.nextCursor;
   } else {
     rawMessages = getMessages(resolvedConversationId).filter(visibleFilter);
   }
@@ -755,10 +747,13 @@ export function handleListMessages({
 
     // Align msgAttachments order with the file-block order captured by
     // renderHistoryContent. When a file block was persisted with
-    // `_attachmentId`, we can join on that id to position the chip inline
-    // (the `attachment:N` entries in contentOrder index into msgAttachments).
-    // DB rows without a matching ref go to the tail as orphan chips;
-    // unmatched refs drop their contentOrder entry and trigger a remap.
+    // `_attachmentId` (user-message uploads), we join on that id to position
+    // the chip inline (the `attachment:N` entries in contentOrder index into
+    // msgAttachments). DB rows without a matching ref go to the tail as orphan
+    // chips; unmatched refs drop their contentOrder entry and trigger a remap.
+    // Assistant-authored file blocks carry no `_attachmentId`, so when no ids
+    // match we fall back to positional alignment if the ref and row counts
+    // agree; otherwise we strip the markers and let chips fall to the tail.
     let alignedContentOrder = m.contentOrder;
     if (
       m.attachmentRefs.length > 0 &&
@@ -809,14 +804,18 @@ export function handleListMessages({
               : undefined;
           })
           .filter((e): e is string => e !== undefined);
-      } else {
-        // No refs carried an attachmentId we could match — strip any
-        // attachment:N entries so the client doesn't try to position
-        // attachments inline against a misaligned array.
+      } else if (m.attachmentRefs.length !== msgAttachments.length) {
+        // No ref carried an attachmentId we could match and the counts
+        // disagree, so positional mapping can't be trusted — strip any
+        // attachment:N entries so the client doesn't position attachments
+        // inline against a misaligned array (they fall to the tail instead).
         alignedContentOrder = m.contentOrder.filter(
           (entry) => !ATTACHMENT_ENTRY_RE.test(entry),
         );
       }
+      // Otherwise no ref matched an id but the counts agree (the
+      // assistant-authored case): the Nth marker maps to the Nth row
+      // positionally, so the original contentOrder is left untouched.
     } else if (m.attachmentRefs.length > 0 && msgAttachments.length === 0) {
       // Refs were captured but no DB rows came back — drop the
       // contentOrder entries to avoid out-of-bounds renders.
@@ -855,10 +854,16 @@ export function handleListMessages({
   });
 
   if (isPaginated) {
+    // Prefer the page's oldest visible row (the documented cursor semantic).
+    // When a scan-cap-truncated page comes back empty there's no visible row
+    // to anchor on, so fall back to the resume cursor so the client still gets
+    // a `(timestamp, id)` to continue paginating from instead of stalling.
     const oldestTimestamp =
-      rawMessages.length > 0 ? rawMessages[0].createdAt : undefined;
+      rawMessages.length > 0
+        ? rawMessages[0].createdAt
+        : scanResumeCursor?.createdAt;
     const oldestMessageId =
-      rawMessages.length > 0 ? rawMessages[0].id : undefined;
+      rawMessages.length > 0 ? rawMessages[0].id : scanResumeCursor?.id;
     // `page=latest` always emits both metadata fields so the web client has
     // a stable contract; emit `null` when the conversation is empty.
     // The existing `beforeTimestamp` branch keeps its conditional shape to
@@ -1002,13 +1007,15 @@ export async function handleSendMessage(
       cohort?: string;
       websiteUrl?: string;
       contentSourceUrl?: string;
+      bootstrapTemplate?: string;
+      initialMessage?: string;
+      skills?: string[];
     };
   };
 
   const actorPrincipalId = headers?.["x-vellum-actor-principal-id"];
   const principalType = headers?.["x-vellum-principal-type"];
-  const originClientId =
-    headers?.["x-vellum-client-id"]?.trim() || undefined;
+  const originClientId = headers?.["x-vellum-client-id"]?.trim() || undefined;
 
   const { conversationKey, content, attachmentIds } = body;
   const inboundConversationId =
@@ -1149,10 +1156,13 @@ export async function handleSendMessage(
   // assistant-minted internal id) when the client supplies it — clients
   // must obtain this id from a prior daemon response, so a missing row
   // is a 404. Otherwise fall through to the external-key path: the
-  // client-supplied `conversationKey` (used by non-vellum channels and
-  // the web idempotency flow) or, when neither is provided, a stable
-  // default keyed on sourceChannel + sourceInterface so repeated calls
-  // from the same channel/interface share a single thread.
+  // client-supplied `conversationKey` (external-key lookup; materializes
+  // on first use) or, when neither is provided, a channel-dependent
+  // default. The vellum channel mints a fresh conversation on every
+  // empty-handed send so first-message-of-a-new-chat surfaces with a
+  // server-minted id; other channels (phone, slack, …) share a stable
+  // `default:<channel>:<interface>` thread so repeated calls from the
+  // same channel/interface stay co-located.
   let mapping: {
     conversationId: string;
     conversationType: string;
@@ -1174,7 +1184,9 @@ export async function handleSendMessage(
     const resolvedConversationKey =
       conversationKey && conversationKey.length > 0
         ? conversationKey
-        : `default:${sourceChannel}:${sourceInterface}`;
+        : sourceChannel === "vellum"
+          ? crypto.randomUUID()
+          : `default:${sourceChannel}:${sourceInterface}`;
     mapping = getOrCreateConversation(resolvedConversationKey, {
       conversationType: "standard",
     });
@@ -1388,48 +1400,35 @@ export async function handleSendMessage(
       : ("content-source" as const);
     effectiveContent = buildScanFirstMessage(scanUrl, scanVariant);
     // Fall through to normal inference path below
-  } else if (isWakeUp && body.onboarding?.cohort === "content-automation") {
-    effectiveContent = "I want to write articles that rank better in GEO";
-    // Fall through to normal inference path — the bootstrap template
-    // and geo-writing skill handle this message.
+  } else if (isWakeUp && body.onboarding?.initialMessage) {
+    effectiveContent = body.onboarding.initialMessage;
   } else if (isWakeUp) {
     const cannedGreeting = getCannedFirstGreeting(body.onboarding ?? undefined);
 
     conversation.processing = true;
     let cleanupDeferred = false;
     try {
-      const provenance = provenanceFromTrustContext(conversation.trustContext);
-      const channelMeta = {
-        ...provenance,
+      const rawContent = content ?? "";
+      const attachments = hasAttachments
+        ? smDeps.resolveAttachments(attachmentIds)
+        : [];
+      const greetingMeta = {
         userMessageChannel: sourceChannel,
         assistantMessageChannel: sourceChannel,
         userMessageInterface: sourceInterface,
         assistantMessageInterface: sourceInterface,
       };
-
-      const rawContent = content ?? "";
-      const attachments = hasAttachments
-        ? smDeps.resolveAttachments(attachmentIds)
-        : [];
-      const userMsg = createUserMessage(rawContent, attachments);
-      const persisted = await addMessage(
-        mapping.conversationId,
-        "user",
-        JSON.stringify(userMsg.content),
-        channelMeta,
-      );
-      conversation.getMessages().push(userMsg);
-
-      setConversationOriginChannelIfUnset(
-        mapping.conversationId,
-        sourceChannel,
-      );
-      setConversationOriginInterfaceIfUnset(
-        mapping.conversationId,
-        sourceInterface,
-      );
+      const persisted = await persistQueuedMessageBody(conversation, {
+        content: rawContent,
+        attachments,
+        requestId: crypto.randomUUID(),
+        metadata: greetingMeta,
+      });
 
       const conversationId = mapping.conversationId;
+      const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
+        trustContext: conversation.trustContext,
+      });
 
       const assistantMsg = createAssistantMessage(cannedGreeting);
       const persistedAssistant = await addMessage(
@@ -1580,25 +1579,22 @@ export async function handleSendMessage(
   if (conversation.isProcessing()) {
     // Queue the message so it's processed when the current turn completes
     const requestId = crypto.randomUUID();
-    const enqueueResult = conversation.enqueueMessage(
-      contentAfterScan,
+    const enqueueResult = conversation.enqueueMessage({
+      content: contentAfterScan,
       attachments,
-      broadcastMessage,
+      onEvent: broadcastMessage,
       requestId,
-      undefined, // activeSurfaceId
-      undefined, // currentPage
-      {
+      metadata: {
         userMessageChannel: sourceChannel,
         assistantMessageChannel: sourceChannel,
         userMessageInterface: sourceInterface,
         assistantMessageInterface: sourceInterface,
         ...(body.automated === true ? { automated: true } : {}),
       },
-      { isInteractive },
-      undefined, // displayContent
+      isInteractive,
       transport,
       clientMessageId,
-    );
+    });
     if (enqueueResult.rejected) {
       return new RouteResponse(
         JSON.stringify({ accepted: false, error: "queue_full" }),
@@ -1718,35 +1714,31 @@ export async function handleSendMessage(
     conversation.processing = true;
     let cleanupDeferred = false;
     try {
-      const provenance = provenanceFromTrustContext(conversation.trustContext);
-      const imageSourcePaths: Record<string, string> = {};
-      for (let i = 0; i < attachments.length; i++) {
-        const a = attachments[i];
-        if (a.filePath && a.mimeType.toLowerCase().startsWith("image/")) {
-          imageSourcePaths[`${i}:${a.filename}`] = a.filePath;
-        }
-      }
-      const channelMeta = {
-        ...provenance,
+      const slashMeta = {
         userMessageChannel: sourceChannel,
         assistantMessageChannel: sourceChannel,
         userMessageInterface: sourceInterface,
         assistantMessageInterface: sourceInterface,
         ...(body.automated === true ? { automated: true } : {}),
-        ...(Object.keys(imageSourcePaths).length > 0
-          ? { imageSourcePaths }
-          : {}),
       };
-      const cleanMsg = createUserMessage(rawContent, attachments);
-      const llmMsg = enrichMessageWithSourcePaths(cleanMsg, attachments);
-      const persisted = await addMessage(
-        mapping.conversationId,
-        "user",
-        JSON.stringify(cleanMsg.content),
-        channelMeta,
-      );
-      conversation.getMessages().push(llmMsg);
+      const persisted = await persistQueuedMessageBody(conversation, {
+        content: rawContent,
+        attachments,
+        requestId: crypto.randomUUID(),
+        metadata: slashMeta,
+        clientMessageId,
+      });
+      if (persisted.deduplicated) {
+        return {
+          accepted: true,
+          messageId: persisted.id,
+          conversationId: mapping.conversationId,
+        };
+      }
 
+      const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
+        trustContext: conversation.trustContext,
+      });
       const assistantMsg = createAssistantMessage(slashResult.message);
       const persistedAssistant = await addMessage(
         mapping.conversationId,
@@ -1756,15 +1748,6 @@ export async function handleSendMessage(
       );
       conversation.getMessages().push(assistantMsg);
 
-      setConversationOriginChannelIfUnset(
-        mapping.conversationId,
-        sourceChannel,
-      );
-      setConversationOriginInterfaceIfUnset(
-        mapping.conversationId,
-        sourceInterface,
-      );
-
       // Snapshot model info now so the deferred callback cannot observe
       // a config change from a concurrent request.
       const modelInfoEvent = isModelSlashCommand(rawContent)
@@ -1827,23 +1810,21 @@ export async function handleSendMessage(
 
   if (slashResult.kind === "compact") {
     conversation.processing = true;
-    const provenance = provenanceFromTrustContext(conversation.trustContext);
-    const channelMeta = {
-      ...provenance,
+    const slashMeta = {
       userMessageChannel: sourceChannel,
       assistantMessageChannel: sourceChannel,
       userMessageInterface: sourceInterface,
       assistantMessageInterface: sourceInterface,
     };
-    const cleanMsg = createUserMessage(rawContent, attachments);
-    let persisted: Awaited<ReturnType<typeof addMessage>>;
+    let persisted: Awaited<ReturnType<typeof persistQueuedMessageBody>>;
     try {
-      persisted = await addMessage(
-        mapping.conversationId,
-        "user",
-        JSON.stringify(cleanMsg.content),
-        channelMeta,
-      );
+      persisted = await persistQueuedMessageBody(conversation, {
+        content: rawContent,
+        attachments,
+        requestId: crypto.randomUUID(),
+        metadata: slashMeta,
+        clientMessageId,
+      });
     } catch (err) {
       // The fire-and-forget compaction below owns clearing `processing`, but a
       // throw from this initial persist never reaches it — reset here so the
@@ -1852,9 +1833,20 @@ export async function handleSendMessage(
       silentlyWithLog(conversation.drainQueue(), "compact-command queue drain");
       throw err;
     }
-    conversation.getMessages().push(cleanMsg);
+    if (persisted.deduplicated) {
+      conversation.processing = false;
+      silentlyWithLog(conversation.drainQueue(), "compact-dedup queue drain");
+      return {
+        accepted: true,
+        messageId: persisted.id,
+        conversationId: mapping.conversationId,
+      };
+    }
 
     const conversationId = mapping.conversationId;
+    const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
+      trustContext: conversation.trustContext,
+    });
 
     // Fire-and-forget: return 202 immediately, run compaction async.
     // forceCompact() makes an LLM call that can exceed the client's
@@ -1937,23 +1929,30 @@ export async function handleSendMessage(
     // initial user-message persist below, which would otherwise leave the
     // conversation stuck in queued mode indefinitely.
     try {
-      const provenance = provenanceFromTrustContext(conversation.trustContext);
-      const channelMeta = {
-        ...provenance,
+      const slashMeta = {
         userMessageChannel: sourceChannel,
         assistantMessageChannel: sourceChannel,
         userMessageInterface: sourceInterface,
         assistantMessageInterface: sourceInterface,
       };
-      const cleanMsg = createUserMessage(rawContent, attachments);
-      const persisted = await addMessage(
-        mapping.conversationId,
-        "user",
-        JSON.stringify(cleanMsg.content),
-        channelMeta,
-      );
-      conversation.getMessages().push(cleanMsg);
+      const persisted = await persistQueuedMessageBody(conversation, {
+        content: rawContent,
+        attachments,
+        requestId: crypto.randomUUID(),
+        metadata: slashMeta,
+        clientMessageId,
+      });
+      if (persisted.deduplicated) {
+        return {
+          accepted: true,
+          messageId: persisted.id,
+          conversationId,
+        };
+      }
 
+      const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
+        trustContext: conversation.trustContext,
+      });
       let assistantMessagePersisted = false;
       try {
         broadcastMessage({
@@ -2017,16 +2016,22 @@ export async function handleSendMessage(
   const resolvedContent = slashResult.content;
 
   const requestId = crypto.randomUUID();
-  let messageId: string;
-  try {
-    messageId = await conversation.persistUserMessage(
-      resolvedContent,
-      attachments,
-      requestId,
-      body.automated === true ? { automated: true } : undefined,
-    );
-  } catch (err) {
-    throw err;
+  const persistResult = await conversation.persistUserMessage({
+    content: resolvedContent,
+    attachments,
+    requestId,
+    metadata: body.automated === true ? { automated: true } : undefined,
+    clientMessageId,
+  });
+
+  const messageId = persistResult.id;
+
+  if (persistResult.deduplicated) {
+    return {
+      accepted: true,
+      messageId,
+      conversationId: mapping.conversationId,
+    };
   }
 
   broadcastMessage({
@@ -2088,8 +2093,8 @@ async function generateLlmSuggestion(
     "",
     "CRITICAL — write from the USER'S perspective only, NEVER from the assistant's:",
     "- The suggestion is what the USER will type into the chat input",
-    "- Use first-person \"I\" only if the user has used it in their prior messages",
-    "- NEVER start with phrases like \"I can help\", \"Here's what\", \"Let me\", \"I'd suggest\" — those are assistant-voice",
+    '- Use first-person "I" only if the user has used it in their prior messages',
+    '- NEVER start with phrases like "I can help", "Here\'s what", "Let me", "I\'d suggest" — those are assistant-voice',
     "- Think: if you were the user reading the assistant's reply, what question or follow-up would you ask next?",
     "",
     "Output only the reply text inside the requested tags — no preamble, no commentary.",
@@ -2342,6 +2347,47 @@ function handleSearchConversations({
   return { query, results };
 }
 
+// ---------------------------------------------------------------------------
+// Metadata helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Assemble the standard channel metadata object for message persistence.
+ *
+ * Combines provenance (trust context), channel/interface routing, and
+ * optional per-message fields (automated flag, image source paths) into the
+ * Record that `addMessage` stores in the `metadata` column.
+ */
+function buildChannelMetadata(
+  sourceChannel: string,
+  sourceInterface: string,
+  opts?: {
+    trustContext?: Parameters<typeof provenanceFromTrustContext>[0];
+    provenanceOverride?: Record<string, unknown>;
+    automated?: boolean;
+    attachments?: ReadonlyArray<{
+      filename: string;
+      mimeType: string;
+      filePath?: string;
+    }>;
+  },
+): Record<string, unknown> {
+  const provenance =
+    opts?.provenanceOverride ?? provenanceFromTrustContext(opts?.trustContext);
+  const imageSourcePaths = opts?.attachments
+    ? extractImageSourcePaths(opts.attachments)
+    : undefined;
+  return {
+    ...provenance,
+    userMessageChannel: sourceChannel,
+    assistantMessageChannel: sourceChannel,
+    userMessageInterface: sourceInterface,
+    assistantMessageInterface: sourceInterface,
+    ...(opts?.automated ? { automated: true } : {}),
+    ...(imageSourcePaths ? { imageSourcePaths } : {}),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Module-level state
 // ---------------------------------------------------------------------------

package/src/runtime/routes/conversations-import-routes.ts

@@ -2,7 +2,11 @@ import { eq } from "drizzle-orm";
 import { z } from "zod";
 
 import { getConfig } from "../../config/loader.js";
-import { addMessage, createConversation } from "../../memory/conversation-crud.js";
+import {
+  addMessage,
+  createConversation,
+  type MessageRole,
+} from "../../memory/conversation-crud.js";
 import {
   getConversationByKey,
   setConversationKey,
@@ -22,7 +26,7 @@ const log = getLogger("conversations-import-routes");
 // -- Types --
 
 interface ImportMessage {
-  role: string;
+  role: MessageRole;
   content: string | Array<{ type: string; text: string }>;
   createdAt?: number;
 }
@@ -59,7 +63,10 @@ function resolveTimestamps(conv: ImportConversation): {
 // -- Handler --
 
 async function handleConversationsImport({ body }: RouteHandlerArgs) {
-  if (!body || !Array.isArray((body as Record<string, unknown>).conversations)) {
+  if (
+    !body ||
+    !Array.isArray((body as Record<string, unknown>).conversations)
+  ) {
     throw new BadRequestError("conversations array required");
   }
 
@@ -70,7 +77,8 @@ async function handleConversationsImport({ body }: RouteHandlerArgs) {
   let imported = 0;
   let skipped = 0;
   let totalMessages = 0;
-  const errors: Array<{ index: number; sourceKey?: string; error: string }> = [];
+  const errors: Array<{ index: number; sourceKey?: string; error: string }> =
+    [];
 
   for (let idx = 0; idx < payload.conversations.length; idx++) {
     const conv = payload.conversations[idx];
@@ -90,7 +98,8 @@ async function handleConversationsImport({ body }: RouteHandlerArgs) {
         }
       }
 
-      const { convCreatedAt, convUpdatedAt, messageTimestamps } = resolveTimestamps(conv);
+      const { convCreatedAt, convUpdatedAt, messageTimestamps } =
+        resolveTimestamps(conv);
 
       const conversation = createConversation(conv.title);
 
@@ -122,7 +131,11 @@ async function handleConversationsImport({ body }: RouteHandlerArgs) {
         .orderBy(messagesTable.createdAt)
         .all();
 
-      for (let i = 0; i < dbMessages.length && i < messageTimestamps.length; i++) {
+      for (
+        let i = 0;
+        i < dbMessages.length && i < messageTimestamps.length;
+        i++
+      ) {
         db.update(messagesTable)
           .set({ createdAt: messageTimestamps[i] })
           .where(eq(messagesTable.id, dbMessages[i].id))

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

@@ -82,7 +82,16 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      documents: z.array(z.unknown()).describe("Document summary objects"),
+      documents: z.array(
+        z.object({
+          surfaceId: z.string(),
+          conversationId: z.string(),
+          title: z.string(),
+          wordCount: z.number(),
+          createdAt: z.number(),
+          updatedAt: z.number(),
+        }),
+      ),
     }),
     handler: ({ queryParams }) => {
       const conversationId = queryParams?.conversationId ?? undefined;

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

@@ -22,6 +22,13 @@ import { publishConversationListChanged } from "../sync/resource-sync-events.js"
 import { BadRequestError, ForbiddenError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
+const groupSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  sortPosition: z.number(),
+  isSystemGroup: z.boolean(),
+});
+
 function serializeGroup(group: ReturnType<typeof getGroup>) {
   if (!group) return null;
   return {
@@ -169,6 +176,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "List groups",
     description: "Return all conversation groups.",
     tags: ["groups"],
+    responseBody: z.object({ groups: z.array(groupSchema) }),
   },
   {
     operationId: "groups_create",
@@ -184,6 +192,7 @@ export const ROUTES: RouteDefinition[] = [
     requestBody: z.object({
       name: z.string().describe("Group name"),
     }),
+    responseBody: groupSchema,
     additionalResponses: {
       "400": {
         description:
@@ -204,6 +213,7 @@ export const ROUTES: RouteDefinition[] = [
       name: z.string().optional(),
       sortPosition: z.number().optional(),
     }),
+    responseBody: groupSchema,
     additionalResponses: {
       "403": {
         description: "System group sort position cannot be changed",
@@ -251,6 +261,7 @@ export const ROUTES: RouteDefinition[] = [
         )
         .describe("Array of { groupId, sortPosition } objects"),
     }),
+    responseBody: z.object({ ok: z.boolean() }),
     additionalResponses: {
       "403": {
         description: "Cannot reorder system groups",