@vellumai/assistant 0.12.3-staging.1 → 0.12.3-staging.2

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

@@ -9,6 +9,7 @@ import { z } from "zod";
 
 import type { HostProxyCapability } from "../../channels/types.js";
 import { isHttpAuthDisabled } from "../../config/env.js";
+import { listClientConnectionHistory } from "../../persistence/client-connection-events-store.js";
 import { datesToISO } from "../../util/json.js";
 import { getLogger } from "../../util/logger.js";
 import {
@@ -112,6 +113,8 @@ export const ROUTES: RouteDefinition[] = [
             interfaceId: c.interfaceId,
             capabilities: c.capabilities,
             machineName: c.machineName,
+            clientVersion: c.clientVersion,
+            sseWatchdog: c.sseWatchdog,
             connectedAt: c.connectedAt,
             lastActiveAt: c.lastActiveAt,
             degraded: isClientDegraded(
@@ -151,6 +154,79 @@ export const ROUTES: RouteDefinition[] = [
       return { disconnected: count };
     },
   },
+  {
+    operationId: "list_client_history",
+    endpoint: "clients/history",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "List client connection history",
+    description:
+      "Return persisted client subscribe/dispose events and coalesced sessions. Reconnects shorter than 60 seconds are flaps, not outages.",
+    tags: ["clients"],
+    queryParams: [
+      {
+        name: "clientId",
+        type: "string",
+        required: false,
+        description: "Restrict history to one client UUID.",
+      },
+      {
+        name: "interfaceId",
+        type: "string",
+        required: false,
+        description: "Restrict history to one interface (e.g. chrome-extension).",
+      },
+      {
+        name: "since",
+        type: "string",
+        required: false,
+        description:
+          "ISO-8601 or epoch-ms lower bound. Sessions already open at this time are included.",
+      },
+      {
+        name: "limit",
+        type: "string",
+        required: false,
+        description: "Max coalesced sessions to return (1-500, default 50).",
+      },
+    ],
+    responseBody: z.object({
+      sessions: z.array(z.object({}).passthrough()),
+      events: z.array(z.object({}).passthrough()),
+    }),
+    handler: ({ queryParams, headers }) => {
+      const since = parseHistorySince(queryParams?.since);
+      const limit = parseHistoryLimit(queryParams?.limit);
+      const callerPrincipalId = headers?.["x-vellum-actor-principal-id"];
+      const history = listClientConnectionHistory({
+        clientId: queryParams?.clientId?.trim() || undefined,
+        interfaceId: queryParams?.interfaceId?.trim() || undefined,
+        actorPrincipalId: isHttpAuthDisabled()
+          ? undefined
+          : callerPrincipalId || "__none__",
+        since,
+        limit,
+      });
+
+      return {
+        sessions: history.sessions.map((session) => ({
+          ...session,
+          startedAt: new Date(session.startedAt).toISOString(),
+          endedAt:
+            session.endedAt == null
+              ? null
+              : new Date(session.endedAt).toISOString(),
+        })),
+        events: history.events.map((event) => ({
+          ...event,
+          occurredAt: new Date(event.occurredAt).toISOString(),
+        })),
+      };
+    },
+  },
   {
     operationId: "report_client_presence",
     endpoint: "clients/presence",
@@ -342,3 +418,35 @@ export const ROUTES: RouteDefinition[] = [
     },
   },
 ];
+
+function parseHistorySince(raw: string | undefined): number | undefined {
+  if (!raw?.trim()) {
+    return undefined;
+  }
+  const trimmed = raw.trim();
+  if (/^\d+$/.test(trimmed)) {
+    const epoch = Number(trimmed);
+    if (!Number.isFinite(epoch) || epoch < 0) {
+      throw new BadRequestError("since must be a non-negative epoch-ms value");
+    }
+    return epoch;
+  }
+  const parsed = Date.parse(trimmed);
+  if (Number.isNaN(parsed)) {
+    throw new BadRequestError(
+      "since must be an ISO-8601 timestamp or epoch milliseconds",
+    );
+  }
+  return parsed;
+}
+
+function parseHistoryLimit(raw: string | undefined): number | undefined {
+  if (!raw?.trim()) {
+    return undefined;
+  }
+  const parsed = Number(raw.trim());
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new BadRequestError("limit must be a positive integer");
+  }
+  return parsed;
+}

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

@@ -19,7 +19,6 @@
  * POST   /v1/conversations/:id/retry      — retry the last assistant turn
  * POST   /v1/conversations/reorder        — reorder / pin conversations
  */
-
 import { v7 as uuidv7 } from "uuid";
 import { z } from "zod";
 
@@ -43,6 +42,7 @@ import {
   undoLastMessage,
 } from "../../daemon/handlers/conversations.js";
 import { normalizeConversationType } from "../../daemon/message-types/shared.js";
+import { bestEffortModeSessionTracking } from "../../daemon/mode-session-tracking.js";
 import { stripConversationIds } from "../../home/feed-writer.js";
 import {
   archiveConversation,
@@ -732,6 +732,9 @@ async function handleRetryLastAssistantTurn({
     if (!discarded) {
       throw new UnprocessableEntityError("No user message to retry from");
     }
+    bestEffortModeSessionTracking("conversation wait invalidation", () =>
+      conversation.modeSessions.invalidateAllStructuralWaits(),
+    );
   } catch (err) {
     if (conversation.abortController === abortController) {
       conversation.abortController = null;

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

@@ -18,6 +18,7 @@ import {
   createUserMessage,
 } from "../../agent/message-types.js";
 import type { AssistantEvent } from "../../api/index.js";
+import { ModeSessionDescriptorSchema } from "../../api/mode-session.js";
 import {
   BackgroundToolCompletionSchema,
   type ConversationContentBlock,
@@ -44,10 +45,8 @@ import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-fl
 import { getUserSelectableProfilesForProvider } from "../../config/default-profile-catalog.js";
 import { isHttpAuthDisabled } from "../../config/env.js";
 import { getConfig } from "../../config/loader.js";
-import {
-  mergeConsecutiveAssistantMessages,
-  mergeToolResultsIntoAssistantMessages,
-} from "../../conversations/message-consolidation.js";
+import { isModeSessionRecoveryHealthy } from "../../config/session-groups-gate.js";
+import { consolidateMessageRows } from "../../conversations/message-consolidation.js";
 import { resolveTurnCommitWaitMs } from "../../daemon/abort-watchdog.js";
 import { createApprovalConversationGenerator } from "../../daemon/approval-generators.js";
 import type { Conversation } from "../../daemon/conversation.js";
@@ -140,6 +139,7 @@ import {
   getConversationByKey,
   getOrCreateConversation,
 } from "../../persistence/conversation-key-store.js";
+import { listConversationModeSessionsByIds } from "../../persistence/conversation-mode-sessions.js";
 import { searchConversations } from "../../persistence/conversation-queries.js";
 import {
   computerUseScreenshotAttachmentIdsFromMetadata,
@@ -147,6 +147,10 @@ import {
   messageMetadataIsAmbientSightKeep,
 } from "../../persistence/conversation-types.js";
 import { linkRequestLogsToMessage } from "../../persistence/llm-request-log-store.js";
+import {
+  mergeMessageMetadata,
+  readModeSessionMetadata,
+} from "../../persistence/message-metadata.js";
 import { assistantTextVisibilityOf } from "../../persistence/user-facing-content.js";
 import { MEMORY_RETROSPECTIVE_FORK_SOURCE } from "../../plugins/defaults/memory/memory-retrospective-constants.js";
 import { normalizeOnboardingContext } from "../../prompts/normalize-onboarding.js";
@@ -881,10 +885,31 @@ function displayRowFilter(conversationId: string): (m: MessageRow) => boolean {
 function consolidateDisplayTurns(rows: MessageRow[]): {
   messages: MessageRow[];
   mergedIdMap: Map<string, string[]>;
+  modeSessionActivityMap: Map<string, { firstAt: number; lastAt: number }>;
 } {
-  return mergeConsecutiveAssistantMessages(
-    mergeToolResultsIntoAssistantMessages(rows),
-  );
+  return consolidateMessageRows(rows);
+}
+
+const MAX_REQUESTED_MODE_SESSION_IDS = 100;
+const MAX_MODE_SESSION_ID_LENGTH = 200;
+
+function parseRequestedModeSessionIds(raw: unknown): string[] {
+  if (raw === undefined) {
+    return [];
+  }
+  if (typeof raw !== "string") {
+    throw new BadRequestError(
+      "modeSessionIds must be a comma-separated string",
+    );
+  }
+  const ids = [...new Set(raw.split(",").map((id) => id.trim()))];
+  if (
+    ids.length > MAX_REQUESTED_MODE_SESSION_IDS ||
+    ids.some((id) => id.length === 0 || id.length > MAX_MODE_SESSION_ID_LENGTH)
+  ) {
+    throw new BadRequestError("modeSessionIds contains an invalid session ID");
+  }
+  return ids;
 }
 
 export async function handleListMessages({
@@ -920,6 +945,9 @@ export async function handleListMessages({
   const beforeTimestampRaw = queryParams?.beforeTimestamp;
   const limitRaw = queryParams?.limit;
   const pageRaw = queryParams?.page;
+  const requestedModeSessionIds = parseRequestedModeSessionIds(
+    queryParams?.modeSessionIds,
+  );
 
   // Validate: reject NaN values with 400
   if (beforeTimestampRaw != null && isNaN(Number(beforeTimestampRaw))) {
@@ -1023,8 +1051,47 @@ export async function handleListMessages({
   // consolidation is deferred to compaction for prefix-cache stability.
   // Merge here at query time so renderHistoryContent produces the same
   // contentOrder shape as streaming (consecutive tool refs grouped together).
-  const { messages: consolidatedMessages, mergedIdMap } =
-    consolidateDisplayTurns(rawMessages);
+  const pageModeSessionIds = rawMessages.flatMap((message) => {
+    const owner = readModeSessionMetadata(message.metadata);
+    return owner ? [owner.id] : [];
+  });
+  const summaries = listConversationModeSessionsByIds(resolvedConversationId, [
+    ...new Set([...pageModeSessionIds, ...requestedModeSessionIds]),
+  ]);
+  const validOwners = new Map(
+    summaries.map((summary) => [summary.id, summary.mode]),
+  );
+  const projectionMessages = rawMessages.map((message) => {
+    const owner = readModeSessionMetadata(message.metadata);
+    if (!owner || validOwners.get(owner.id) === owner.mode) {
+      return message;
+    }
+    return {
+      ...message,
+      metadata: mergeMessageMetadata(message.metadata, {
+        modeSession: undefined,
+      }),
+    };
+  });
+  const {
+    messages: consolidatedMessages,
+    mergedIdMap,
+    modeSessionActivityMap,
+  } = consolidateDisplayTurns(projectionMessages);
+  const liveConversation = findConversation(resolvedConversationId);
+  const modeSessions = summaries
+    .filter(
+      (summary) =>
+        isModeSessionRecoveryHealthy() || summary.status !== "active",
+    )
+    .flatMap((summary) => {
+      const descriptor = liveConversation?.modeSessions
+        ? liveConversation.modeSessions.describeSummary(summary)
+        : summary.status !== "active"
+          ? { summary }
+          : undefined;
+      return descriptor ? [descriptor] : [];
+    });
   const assistantSlackDisplayName = getAssistantName()?.trim() || undefined;
 
   // Parse each row's stored content and per-message metadata. Rendering is
@@ -1152,6 +1219,7 @@ export async function handleListMessages({
       deletedAt,
       clientMessageId: msg.clientMessageId ?? undefined,
       assistantTextVisibility: assistantTextVisibilityOf(msg.metadata),
+      modeSession: readModeSessionMetadata(msg.metadata),
       // The row's raw stored envelope, carried to the render pass below so it
       // can read the row's own `assistantTextVisibility` marker. Never part of
       // the wire payload, which the serializer builds field by field.
@@ -1172,6 +1240,9 @@ export async function handleListMessages({
   const messages: RuntimeMessagePayload[] = await Promise.all(
     parsed.map(async (m) => {
       const mergedMessageIds = m.id ? (mergedIdMap.get(m.id) ?? []) : [];
+      const modeSessionActivity = m.id
+        ? modeSessionActivityMap.get(m.id)
+        : undefined;
 
       // Hydrate the row's attachments from the DB. A metadata-only query avoids
       // loading large base64 blobs for non-image attachments (documents, audio);
@@ -1183,26 +1254,18 @@ export async function handleListMessages({
       if (m.id) {
         const idsToQuery = [m.id, ...mergedMessageIds];
         const linkedRows = getAttachmentMetadataForMessages(idsToQuery);
-        const computerUseScreenshotIdsByMessage = new Map<
-          string,
-          Set<string>
-        >();
+        const computerUseScreenshotIds = new Set(
+          linkedRows.flatMap((row) =>
+            computerUseScreenshotAttachmentIdsFromMetadata(
+              parseMessageMetadata(row.messageMetadata),
+            ),
+          ),
+        );
         const linked = linkedRows.map((row) => {
-          let screenshotIds = computerUseScreenshotIdsByMessage.get(
-            row.messageId,
-          );
-          if (!screenshotIds) {
-            screenshotIds = new Set(
-              computerUseScreenshotAttachmentIdsFromMetadata(
-                parseMessageMetadata(row.messageMetadata),
-              ),
-            );
-            computerUseScreenshotIdsByMessage.set(row.messageId, screenshotIds);
-          }
           return {
             ...row.attachment,
             computerUseScreenshot:
-              screenshotIds.has(row.attachment.id) || undefined,
+              computerUseScreenshotIds.has(row.attachment.id) || undefined,
           };
         });
         if (linked.length > 0) {
@@ -1358,6 +1421,8 @@ export async function handleListMessages({
       return {
         id: m.id ?? "",
         ...(mergedMessageIds.length > 0 ? { mergedMessageIds } : {}),
+        ...(m.modeSession ? { modeSession: m.modeSession } : {}),
+        ...(modeSessionActivity ? { modeSessionActivity } : {}),
         ...(m.clientMessageId ? { clientMessageId: m.clientMessageId } : {}),
         role: m.role,
         timestamp: new Date(displayTimestamp).toISOString(),
@@ -1447,6 +1512,7 @@ export async function handleListMessages({
         oldestMessageId: oldestMessageId ?? null,
         seq: persistedSeq,
         processing,
+        ...(modeSessions.length > 0 ? { modeSessions } : {}),
       };
     }
 
@@ -1457,10 +1523,16 @@ export async function handleListMessages({
       ...(oldestMessageId != null ? { oldestMessageId } : {}),
       seq: persistedSeq,
       processing,
+      ...(modeSessions.length > 0 ? { modeSessions } : {}),
     };
   }
 
-  return { messages, seq: persistedSeq, processing };
+  return {
+    messages,
+    seq: persistedSeq,
+    processing,
+    ...(modeSessions.length > 0 ? { modeSessions } : {}),
+  };
 }
 
 /**
@@ -2192,7 +2264,7 @@ export async function handleSendMessage(
           publishConversationMessagesChanged(conversationId, originClientId);
         },
         afterRelease: () => {
-          conversation.warmPromptCache();
+          void conversation.warmPromptCache();
         },
       });
 
@@ -3052,6 +3124,7 @@ export async function handleSendMessage(
           messageId,
           requestId,
           clientMessageId,
+          modeSession: conversation.modeSessions.getTurnOwner(requestId),
         });
         // The row this echo announces was durably persisted above, so advance
         // the snapshot↔stream anchor to the echo's seq (stamped inline by
@@ -3676,6 +3749,13 @@ export const ROUTES: RouteDefinition[] = [
         required: false,
         description: "Maximum number of messages to return.",
       },
+      {
+        name: "modeSessionIds",
+        type: "string",
+        required: false,
+        description:
+          "Comma-separated mode-session IDs to include with summaries for loaded active groups outside this page.",
+      },
     ],
     responseBody: z.object({
       messages: z
@@ -3710,6 +3790,12 @@ export const ROUTES: RouteDefinition[] = [
         .describe(
           "Whether the agent is currently mid-turn for this conversation, sourced authoritatively from the persisted `processing_started_at` column. `true` means a turn is in flight; `false` means the conversation is idle. Clients use this to recover from a dropped SSE stream: if a turn appears to be running locally but the server reports `processing: false`, the turn has ended (or died) and the UI should stop waiting rather than spin indefinitely. Absent on older daemons that predate this field.",
         ),
+      modeSessions: z
+        .array(ModeSessionDescriptorSchema)
+        .optional()
+        .describe(
+          "Conversation-owned mode-session summaries referenced by this page or explicitly requested by ID.",
+        ),
     }),
     handler: (args) => handleListMessages(args),
   },

package/src/runtime/routes/credential-prompt-routes.ts

@@ -177,13 +177,14 @@ async function handleCredentialPrompt({ body = {} }: RouteHandlerArgs) {
           expiresAt: result.collectionExpiresAt,
           service: validated.service,
           field: validated.field,
-          message: `This channel does not support secure input. The credential has NOT been stored yet. Share this one-time link with the user to collect it securely (single-use${expiresInMinutes ? `, expires in ${expiresInMinutes} minutes` : ""}): ${result.collectionUrl}`,
+          message: `${validated.conversationId ? "This channel does not support secure input." : "No conversation is attached to this invocation, so no secure prompt can be shown."} The credential has NOT been stored yet. Share this one-time link with the user to collect it securely (single-use${expiresInMinutes ? `, expires in ${expiresInMinutes} minutes` : ""}): ${result.collectionUrl}`,
         };
       }
       return {
         ok: false,
-        error:
-          "This conversation's channel does not support secure credential entry",
+        error: validated.conversationId
+          ? "This conversation's channel does not support secure credential entry"
+          : "No conversation is attached to this invocation, so no secure prompt can be shown, and a one-time collection link could not be created. Ask the user to add the credential in the app under Settings > Credentials. Never ask them to paste it into chat.",
       };
     }
     // An explicit user cancel is a valid flow, not a failure. Keep it distinct

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

@@ -607,8 +607,7 @@ async function handleCredentialsDelete({ body }: RouteHandlerArgs) {
 }
 
 async function handleCredentialsStatus() {
-  const info = await getActiveBackendInfoAsync();
-  return info;
+  return getActiveBackendInfoAsync();
 }
 
 // ---------------------------------------------------------------------------

package/src/runtime/routes/desktop-setup-routes.test.ts

@@ -9,25 +9,22 @@ import {
 } from "bun:test";
 
 import { setOverridesForTesting } from "../../__tests__/feature-flag-test-helpers.js";
-import { desktopDependencyInstaller } from "../../desktop/desktop-dependencies.js";
+import { desktopDependencies } from "../../desktop/desktop-dependencies.js";
 import { ROUTES } from "./desktop-setup-routes.js";
 import { NotFoundError } from "./errors.js";
 
 const originalContainerized = process.env.IS_CONTAINERIZED;
 const originalPlatform = process.env.IS_PLATFORM;
-const status = spyOn(desktopDependencyInstaller, "getStatus");
-const start = spyOn(desktopDependencyInstaller, "start");
+const status = spyOn(desktopDependencies, "getStatus");
 
 afterAll(() => {
   status.mockRestore();
-  start.mockRestore();
 });
 
 beforeEach(() => {
   process.env.IS_CONTAINERIZED = "true";
   process.env.IS_PLATFORM = "true";
-  status.mockReturnValue({ state: "required" });
-  start.mockReturnValue({ state: "installing", stage: "packages" });
+  status.mockReturnValue({ state: "ready" });
 });
 
 afterEach(() => {
@@ -43,7 +40,6 @@ afterEach(() => {
   }
   setOverridesForTesting({});
   status.mockClear();
-  start.mockClear();
 });
 
 describe("desktop setup route feature gate", () => {
@@ -55,7 +51,6 @@ describe("desktop setup route feature gate", () => {
         );
         expect(() => route.handler({})).toThrow(NotFoundError);
         expect(status).not.toHaveBeenCalled();
-        expect(start).not.toHaveBeenCalled();
       });
     }
 
@@ -64,26 +59,22 @@ describe("desktop setup route feature gate", () => {
       setOverridesForTesting({ "assistant-desktop": true });
       expect(() => route.handler({})).toThrow(NotFoundError);
       expect(status).not.toHaveBeenCalled();
-      expect(start).not.toHaveBeenCalled();
     });
 
-    test(`${route.method} rejects self-hosted Docker assistants without inspecting or installing dependencies`, () => {
+    test(`${route.method} rejects self-hosted Docker assistants without inspecting dependencies`, () => {
       process.env.IS_PLATFORM = "false";
       setOverridesForTesting({ "assistant-desktop": true });
       expect(() => route.handler({})).toThrow(NotFoundError);
       expect(status).not.toHaveBeenCalled();
-      expect(start).not.toHaveBeenCalled();
     });
 
     test(`${route.method} serves setup only for enabled platform containers`, () => {
       setOverridesForTesting({ "assistant-desktop": true });
-      expect(route.handler({})).toEqual(
-        route.method === "GET"
-          ? { state: "required", automationActive: false }
-          : { state: "installing", stage: "packages", automationActive: false },
-      );
-      expect(route.method === "GET" ? status : start).toHaveBeenCalledTimes(1);
-      expect(route.method === "GET" ? start : status).not.toHaveBeenCalled();
+      expect(route.handler({})).toEqual({
+        state: "ready",
+        automationActive: false,
+      });
+      expect(status).toHaveBeenCalledTimes(1);
     });
   }
 });

package/src/runtime/routes/desktop-setup-routes.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 import { desktopAutomationLease } from "../../desktop/desktop-automation-lease.js";
-import { desktopDependencyInstaller } from "../../desktop/desktop-dependencies.js";
+import { desktopDependencies } from "../../desktop/desktop-dependencies.js";
 import { isVirtualDesktopEnabled } from "../../desktop/virtual-desktop-feature.js";
 import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import { NotFoundError } from "./errors.js";
@@ -13,6 +13,7 @@ const statusSchema = z.object({
   stage: z.enum(["packages", "chrome", "checking"]).optional(),
 });
 
+// POST and its wire schema support released clients; both methods only read readiness.
 export const ROUTES: RouteDefinition[] = ["GET", "POST"].map((method) => ({
   operationId:
     method === "GET" ? "desktop_setup_status" : "desktop_setup_install",
@@ -25,16 +26,13 @@ export const ROUTES: RouteDefinition[] = ["GET", "POST"].map((method) => ({
         "Virtual desktop is available only on enabled platform-hosted assistants",
       );
     }
-    const status =
-      method === "GET"
-        ? desktopDependencyInstaller.getStatus()
-        : desktopDependencyInstaller.start();
+    const status = desktopDependencies.getStatus();
     return { ...status, automationActive: desktopAutomationLease.isActive };
   },
   summary:
     method === "GET"
       ? "Get virtual desktop setup status"
-      : "Install virtual desktop components",
+      : "Check virtual desktop readiness (legacy POST)",
   tags: ["desktop"],
   responseBody: statusSchema,
 }));

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

@@ -8,10 +8,13 @@ import { z } from "zod";
 
 import {
   addDocumentConversation,
+  createDocument,
+  DEFAULT_DOCUMENT_TITLE,
   getDocumentById,
   getDocumentsForConversation,
   saveDocument,
 } from "../../documents/document-store.js";
+import { getConversation } from "../../persistence/conversation-crud.js";
 import { rawAll } from "../../persistence/raw-query.js";
 import { getLogger } from "../../util/logger.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
@@ -214,6 +217,54 @@ export const ROUTES: RouteDefinition[] = [
     },
   },
 
+  {
+    operationId: "createDocument",
+    endpoint: "documents/create",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Create a document",
+    description:
+      "Create an empty document owned by a conversation and return it with its new surface ID.",
+    tags: ["documents"],
+    requestBody: z.object({
+      conversationId: z.string().describe("Owning conversation"),
+      title: z
+        .string()
+        .optional()
+        .describe(`Document title. Defaults to "${DEFAULT_DOCUMENT_TITLE}".`),
+    }),
+    responseBody: documentPayloadSchema,
+    handler: ({ body, headers }) => {
+      const { conversationId, title } = (body ?? {}) as {
+        conversationId?: string;
+        title?: string;
+      };
+      if (!conversationId || typeof conversationId !== "string") {
+        throw new BadRequestError("conversationId is required");
+      }
+      if (title !== undefined && typeof title !== "string") {
+        throw new BadRequestError("title must be a string");
+      }
+      if (!getConversation(conversationId)) {
+        throw new NotFoundError("Conversation not found");
+      }
+
+      const result = createDocument({ conversationId, title: title?.trim() });
+      if (!result.success) {
+        throw new InternalError(result.error);
+      }
+      const doc = getDocumentById(result.surfaceId);
+      if (!doc) {
+        throw new InternalError("Created document could not be read back");
+      }
+      publishDocumentsChanged(getOriginClientId(headers));
+      return { success: true, ...doc };
+    },
+  },
+
   {
     operationId: "linkDocumentConversation",
     endpoint: "documents/:id/conversations",

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

@@ -169,7 +169,7 @@ async function handleEmailStatus(_args: RouteHandlerArgs) {
     );
   }
 
-  const statusData = (await statusResponse.json()) as {
+  return (await statusResponse.json()) as {
     address: string;
     status: string;
     created_at: string;
@@ -181,8 +181,6 @@ async function handleEmailStatus(_args: RouteHandlerArgs) {
       received_this_month: number;
     };
   };
-
-  return statusData;
 }
 
 async function handleEmailList({ queryParams = {} }: RouteHandlerArgs) {
@@ -239,8 +237,7 @@ async function handleEmailDownload({ queryParams = {} }: RouteHandlerArgs) {
     throw new RouteError(String(detail), "DOWNLOAD_FAILED", response.status);
   }
 
-  const msg = await response.json();
-  return msg;
+  return response.json();
 }
 
 async function handleEmailSend({ body = {} }: RouteHandlerArgs) {
@@ -323,11 +320,10 @@ async function handleEmailSend({ body = {} }: RouteHandlerArgs) {
     throw new BadRequestError(String(detail));
   }
 
-  const data = (await response.json()) as {
+  return (await response.json()) as {
     delivery_id: string;
     status: string;
   };
-  return data;
 }
 
 // ── Attachment handlers ───────────────────────────────────────────────