@vellumai/assistant 0.6.5 → 0.7.0

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

@@ -1,7 +1,13 @@
 /**
  * Route handlers for conversation messages and suggestions.
  */
-import { existsSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { join, relative } from "node:path";
 
 import { z } from "zod";
@@ -13,6 +19,7 @@ import {
 } from "../../agent/message-types.js";
 import {
   canServiceRegistryBrowser,
+  canServiceSseBrowser,
   CHANNEL_IDS,
   INTERFACE_IDS,
   type InterfaceId,
@@ -23,6 +30,7 @@ import {
 } from "../../channels/types.js";
 import { isHttpAuthDisabled } from "../../config/env.js";
 import { getConfig } from "../../config/loader.js";
+import { createApprovalConversationGenerator } from "../../daemon/approval-generators.js";
 import type { Conversation } from "../../daemon/conversation.js";
 import {
   buildModelInfoEvent,
@@ -33,6 +41,7 @@ import {
   resolveSlash,
   type SlashContext,
 } from "../../daemon/conversation-slash.js";
+import { getOrCreateConversation as getOrCreateConversationInstance } from "../../daemon/conversation-store.js";
 import {
   getCannedFirstGreeting,
   isWakeUpGreeting,
@@ -42,17 +51,26 @@ import { HostBashProxy } from "../../daemon/host-bash-proxy.js";
 import { HostBrowserProxy } from "../../daemon/host-browser-proxy.js";
 import { HostCuProxy } from "../../daemon/host-cu-proxy.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
+import { HostTransferProxy } from "../../daemon/host-transfer-proxy.js";
 import type { ServerMessage } from "../../daemon/message-protocol.js";
 import type {
   HostProxyTransportMetadata,
   NonHostProxyTransportMetadata,
 } from "../../daemon/message-types/conversations.js";
-import type { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
+import { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
+import { emitFeedEvent } from "../../home/emit-feed-event.js";
 import {
   writeOnboardingSidecar,
   writeRelationshipState,
 } from "../../home/relationship-state-writer.js";
-import * as attachmentsStore from "../../memory/attachments-store.js";
+import { rewriteCommandPreview } from "../../home/rewrite-command-preview.js";
+import { ipcCall } from "../../ipc/gateway-client.js";
+import {
+  getAttachmentById,
+  getAttachmentMetadataForMessage,
+  getAttachmentsByIds,
+  getSourcePathsForAttachments,
+} from "../../memory/attachments-store.js";
 import {
   createCanonicalGuardianRequest,
   generateCanonicalRequestCode,
@@ -68,6 +86,7 @@ import {
   hasMessages,
   type MessageRow,
   provenanceFromTrustContext,
+  setConversationInferenceProfile,
   setConversationOriginChannelIfUnset,
   setConversationOriginInterfaceIfUnset,
 } from "../../memory/conversation-crud.js";
@@ -82,17 +101,19 @@ import { checkIngressForSecrets } from "../../security/secret-ingress.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
 import { summarizeToolInput } from "../../tools/tool-input-summary.js";
 import { getLogger } from "../../util/logger.js";
-import { getWorkspacePromptPath } from "../../util/platform.js";
+import {
+  getInterfacesDir,
+  getWorkspacePromptPath,
+} from "../../util/platform.js";
 import { silentlyWithLog } from "../../util/silently.js";
 import { buildAssistantEvent } from "../assistant-event.js";
+import { assistantEventHub } from "../assistant-event-hub.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
-import type { AuthContext } from "../auth/types.js";
 import { getChromeExtensionRegistry } from "../chrome-extension-registry.js";
+import { getClientRegistry } from "../client-registry.js";
 import { bridgeConfirmationRequestToGuardian } from "../confirmation-request-guardian-bridge.js";
 import { routeGuardianReply } from "../guardian-reply-router.js";
 import { healGuardianBindingDrift } from "../guardian-vellum-migration.js";
-import { httpError } from "../http-errors.js";
-import type { RouteDefinition } from "../http-router.js";
 import type {
   ApprovalConversationGenerator,
   RuntimeAttachmentMetadata,
@@ -105,6 +126,9 @@ import {
   resolveTrustContext,
   withSourceChannel,
 } from "../trust-context-resolver.js";
+import { BadRequestError, InternalError, RouteError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+import { RouteResponse } from "./types.js";
 
 const log = getLogger("conversation-routes");
 
@@ -112,6 +136,15 @@ const log = getLogger("conversation-routes");
 const NO_RESPONSE_INLINE_RE = /<no_response\s*\/?>/g;
 
 const SUGGESTION_CACHE_MAX = 100;
+const VALID_RISK_THRESHOLDS = ["none", "low", "medium", "high"] as const;
+type RiskThreshold = (typeof VALID_RISK_THRESHOLDS)[number];
+
+function isValidRiskThreshold(value: unknown): value is RiskThreshold {
+  return (
+    typeof value === "string" &&
+    VALID_RISK_THRESHOLDS.includes(value as RiskThreshold)
+  );
+}
 
 function collectCanonicalGuardianRequestHintIds(
   conversationId: string,
@@ -359,11 +392,11 @@ function getInterfaceFilesWithMtimes(
 }
 
 export function handleListMessages(
-  url: URL,
+  { queryParams }: RouteHandlerArgs,
   interfacesDir: string | null,
-): Response {
-  const conversationId = url.searchParams.get("conversationId");
-  const conversationKey = url.searchParams.get("conversationKey");
+): Record<string, unknown> {
+  const conversationId = queryParams?.conversationId;
+  const conversationKey = queryParams?.conversationKey;
 
   let resolvedConversationId: string | undefined;
   if (conversationId) {
@@ -372,30 +405,40 @@ export function handleListMessages(
     const mapping = getConversationByKey(conversationKey);
     resolvedConversationId = mapping?.conversationId;
   } else {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       "conversationKey or conversationId query parameter is required",
-      400,
     );
   }
 
-  if (!resolvedConversationId) {
-    return Response.json({ messages: [] });
-  }
-
-  const beforeTimestampRaw = url.searchParams.get("beforeTimestamp");
-  const limitRaw = url.searchParams.get("limit");
+  const beforeTimestampRaw = queryParams?.beforeTimestamp;
+  const limitRaw = queryParams?.limit;
+  const pageRaw = queryParams?.page;
 
   // Validate: reject NaN values with 400
-  if (beforeTimestampRaw !== null && isNaN(Number(beforeTimestampRaw))) {
-    return httpError(
-      "BAD_REQUEST",
-      "beforeTimestamp must be a valid number",
-      400,
-    );
+  if (beforeTimestampRaw != null && isNaN(Number(beforeTimestampRaw))) {
+    throw new BadRequestError("beforeTimestamp must be a valid number");
+  }
+  if (limitRaw != null && isNaN(Number(limitRaw))) {
+    throw new BadRequestError("limit must be a valid number");
   }
-  if (limitRaw !== null && isNaN(Number(limitRaw))) {
-    return httpError("BAD_REQUEST", "limit must be a valid number", 400);
+  if (pageRaw != null && pageRaw !== "latest") {
+    throw new BadRequestError("page must be 'latest' when provided");
+  }
+  const isLatestPage = pageRaw === "latest";
+
+  if (!resolvedConversationId) {
+    // Unresolved conversation keys still need to advertise the stable
+    // `page=latest` contract so the web client can rely on metadata fields
+    // being present even before any message is persisted.
+    if (isLatestPage && beforeTimestampRaw == null) {
+      return {
+        messages: [],
+        hasMore: false,
+        oldestTimestamp: null,
+        oldestMessageId: null,
+      };
+    }
+    return { messages: [] };
   }
 
   const beforeTimestamp = beforeTimestampRaw
@@ -406,10 +449,12 @@ export function handleListMessages(
     ? Math.min(Math.max(Math.floor(Number(limitRaw)), 1), 500)
     : undefined;
 
-  // Option A: only paginate when beforeTimestamp is present.
-  // Initial load and reconnect send limit but no beforeTimestamp — those must continue
-  // returning all messages for zero regression risk.
-  const isPaginated = beforeTimestamp != null;
+  // Paginate when either `beforeTimestamp` (older-page request) or
+  // `page=latest` (initial newest-N request) is set. When both are sent,
+  // `beforeTimestamp` wins because the caller is explicitly asking for an
+  // older page; `getMessagesPaginated` ignores `beforeTimestamp === undefined`
+  // and returns the newest `limit` messages in chronological order.
+  const isPaginated = beforeTimestamp != null || isLatestPage;
 
   let rawMessages: MessageRow[];
   let hasMore = false;
@@ -574,12 +619,12 @@ export function handleListMessages(
       // aren't lost before DB compaction relinks them.
       const idsToQuery = [m.id, ...(mergedIdMap.get(m.id) ?? [])];
       const linked = idsToQuery.flatMap((id) =>
-        attachmentsStore.getAttachmentMetadataForMessage(id),
+        getAttachmentMetadataForMessage(id),
       );
       if (linked.length > 0) {
         msgAttachments = linked.map((a) => {
           if (a.mimeType.startsWith("image/")) {
-            const full = attachmentsStore.getAttachmentById(a.id, {
+            const full = getAttachmentById(a.id, {
               hydrateFileData: true,
             });
             return {
@@ -655,15 +700,28 @@ export function handleListMessages(
       rawMessages.length > 0 ? rawMessages[0].createdAt : undefined;
     const oldestMessageId =
       rawMessages.length > 0 ? rawMessages[0].id : undefined;
-    return Response.json({
+    // `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
+    // avoid disturbing current callers.
+    if (isLatestPage && beforeTimestamp == null) {
+      return {
+        messages,
+        hasMore,
+        oldestTimestamp: oldestTimestamp ?? null,
+        oldestMessageId: oldestMessageId ?? null,
+      };
+    }
+
+    return {
       messages,
       hasMore,
       ...(oldestTimestamp != null ? { oldestTimestamp } : {}),
       ...(oldestMessageId != null ? { oldestMessageId } : {}),
-    });
+    };
   }
 
-  return Response.json({ messages });
+  return { messages };
 }
 
 // ── Tool-result merging ─────────────────────────────────────────────
@@ -994,10 +1052,59 @@ function makeHubPublisher(
           allowlistOptions: msg.allowlistOptions,
           scopeOptions: msg.scopeOptions,
           persistentDecisionsAllowed: msg.persistentDecisionsAllowed,
-          temporaryOptionsAvailable: msg.temporaryOptionsAvailable,
         },
       });
 
+      const inputRecord = msg.input as Record<string, unknown>;
+      const commandPreview =
+        redactSecrets(summarizeToolInput(msg.toolName, inputRecord)) ||
+        undefined;
+      const technicalTitle = commandPreview
+        ? `Requesting permission: ${commandPreview}`
+        : `Requesting approval to use ${msg.toolName}.`;
+      const dedupKey = `tool-approval:${msg.requestId}`;
+
+      // Emit immediately with the technical preview.
+      void emitFeedEvent({
+        source: "assistant",
+        title: technicalTitle,
+        summary: technicalTitle,
+        dedupKey,
+        urgency: msg.riskLevel === "high" ? "high" : "medium",
+        conversationId,
+        detailPanel: { kind: "toolPermission" },
+      }).catch((err) => {
+        log.warn(
+          { err, requestId: msg.requestId },
+          "Failed to emit tool approval request feed event",
+        );
+      });
+
+      // Background: rewrite into prose and update the feed item.
+      if (commandPreview) {
+        void rewriteCommandPreview(msg.toolName, commandPreview)
+          .then((prose) => {
+            if (prose) {
+              const proseTitle = `Requesting permission: ${prose}`;
+              return emitFeedEvent({
+                source: "assistant",
+                title: proseTitle,
+                summary: proseTitle,
+                dedupKey,
+                urgency: msg.riskLevel === "high" ? "high" : "medium",
+                conversationId,
+                detailPanel: { kind: "toolPermission" },
+              });
+            }
+          })
+          .catch((err) => {
+            log.warn(
+              { err, requestId: msg.requestId },
+              "Failed to update feed event with prose rewrite",
+            );
+          });
+      }
+
       // Create a canonical guardian request so HTTP handlers can find it
       // via applyCanonicalGuardianDecision.
       try {
@@ -1168,83 +1275,93 @@ function registerHostProxyPendingInteraction(
     });
     return msg.requestId;
   }
+  if (msg.type === "host_transfer_request") {
+    pendingInteractions.register(msg.requestId, {
+      conversation,
+      conversationId,
+      kind: "host_transfer",
+    });
+    return msg.requestId;
+  }
   return undefined;
 }
 
 /**
  * Resolve the host_browser sender function for a conversation turn.
  *
- * When the guardian has an active extension connection in the
- * ChromeExtensionRegistry, returns a registry-routed sender that forwards
- * `host_browser_request` / `host_browser_cancel` frames through the
- * WebSocket to the connected extension. Otherwise returns the SSE hub
- * emitter (`onEvent`).
+ * Transport selection:
+ *   1. **WebSocket registry** — when the guardian has an active entry in
+ *      ChromeExtensionRegistry (self-hosted direct WS connection), the
+ *      registry-routed sender is returned. Frames go directly over the
+ *      WebSocket to the extension.
+ *   2. **SSE event hub** — when no WebSocket connection exists but a
+ *      chrome-extension client is connected via SSE (cloud/platform mode),
+ *      the SSE hub sender (`onEvent`) is returned. The extension receives
+ *      `host_browser_request` frames as SSE events and POSTs results back
+ *      to `/v1/host-browser-result`.
  *
- * For `chrome-extension` turns the registry sender is **always** returned
- * regardless of the POST-time connection check. The chrome-extension
- * interface has no SSE consumer for `host_browser_request` frames, so
- * falling back to `onEvent` would cause CDP calls to stall until the proxy
- * timeout (30 s) instead of failing immediately at send time when the
- * registry throws on a missing connection.
- *
- * This helper is interface-agnostic: both chrome-extension and macOS turns
- * can obtain a registry-routed sender when extension connectivity exists.
- * The `isRegistryRouted` flag lets the caller decide whether to set
- * `hostBrowserSenderOverride` and whether to provision a `HostBrowserProxy`
- * for interfaces that don't statically support host_browser (e.g. macOS).
+ * When neither transport is available, `onEvent` is returned as the
+ * default sender (used by macOS for its native host_browser path).
+ * `hasSseExtension` is `false` in that case so the caller can avoid
+ * provisioning a stale `HostBrowserProxy` for interfaces that don't
+ * natively support host_browser.
  */
 function resolveHostBrowserSender(
   conversation: Conversation,
   conversationId: string,
-  authContext: AuthContext,
+  actorPrincipalId: string | undefined,
   onEvent: (msg: ServerMessage) => void,
   sourceInterface: InterfaceId,
-): { sender: (msg: ServerMessage) => void; isRegistryRouted: boolean } {
-  // Check whether the guardian has any active extension connection.
+): {
+  sender: (msg: ServerMessage) => void;
+  isRegistryRouted: boolean;
+  hasSseExtension: boolean;
+} {
   const guardianId =
-    conversation.trustContext?.guardianPrincipalId ??
-    authContext.actorPrincipalId;
+    conversation.trustContext?.guardianPrincipalId ?? actorPrincipalId;
   const hasExtensionConnection =
     !!guardianId && !!getChromeExtensionRegistry().get(guardianId);
 
-  // For chrome-extension, always use the registry sender so that send-time
-  // failures produce immediate errors rather than 30-second proxy timeouts.
-  // The SSE hub has no extension consumer, so falling back to onEvent is
-  // never correct for this interface.
-  if (!hasExtensionConnection && sourceInterface !== "chrome-extension") {
-    return { sender: onEvent, isRegistryRouted: false };
-  }
-
-  // Build a registry-routed sender. The guardian principal ID is resolved
-  // at send time rather than captured here so that queue-drain restores
-  // (which re-fire this closure outside the original POST context) follow
-  // the conversation's bound guardian identity rather than a stale
-  // authContext.actorPrincipalId.
-  const registrySender = (msg: ServerMessage): void => {
-    const requestId = registerHostProxyPendingInteraction(
-      msg,
-      conversation,
-      conversationId,
-    );
-    const gid =
-      conversation.trustContext?.guardianPrincipalId ??
-      authContext.actorPrincipalId;
-    if (!gid) {
-      if (requestId) pendingInteractions.resolve(requestId);
-      throw new Error(
-        "host_browser send skipped: no guardianId on AuthContext",
-      );
-    }
-    const ok = getChromeExtensionRegistry().send(gid, msg);
-    if (!ok) {
-      if (requestId) pendingInteractions.resolve(requestId);
-      throw new Error(
-        `host_browser send failed: no active connection for guardian ${gid}`,
+  // Priority 1: WebSocket registry — direct WS to the extension.
+  if (hasExtensionConnection) {
+    const registrySender = (msg: ServerMessage): void => {
+      const requestId = registerHostProxyPendingInteraction(
+        msg,
+        conversation,
+        conversationId,
       );
-    }
-  };
+      const gid =
+        conversation.trustContext?.guardianPrincipalId ?? actorPrincipalId;
+      if (!gid) {
+        if (requestId) pendingInteractions.resolve(requestId);
+        throw new Error(
+          "host_browser send skipped: no guardianId on AuthContext",
+        );
+      }
+      const ok = getChromeExtensionRegistry().send(gid, msg);
+      if (!ok) {
+        if (requestId) pendingInteractions.resolve(requestId);
+        throw new Error(
+          `host_browser send failed: no active connection for guardian ${gid}`,
+        );
+      }
+    };
+    return {
+      sender: registrySender,
+      isRegistryRouted: true,
+      hasSseExtension: false,
+    };
+  }
 
-  return { sender: registrySender, isRegistryRouted: true };
+  // Priority 2: SSE-connected chrome extension (cloud/platform mode).
+  // Check the ClientRegistry for a chrome-extension client specifically —
+  // getMostRecentByCapability("host_browser") would also match macOS
+  // clients, which handle browser frames through their own native path.
+  const hasSseExtension =
+    canServiceSseBrowser(sourceInterface) &&
+    !!getClientRegistry().getMostRecentByInterface("chrome-extension");
+
+  return { sender: onEvent, isRegistryRouted: false, hasSseExtension };
 }
 
 /**
@@ -1271,7 +1388,7 @@ function resolveHostBrowserSender(
  * failure. The route handler path must never reject because of a
  * best-effort persistence step.
  */
-function persistOnboardingArtifacts(onboarding: {
+export function persistOnboardingArtifacts(onboarding: {
   tools: string[];
   tasks: string[];
   tone: string;
@@ -1283,31 +1400,49 @@ function persistOnboardingArtifacts(onboarding: {
   const assistantName = onboarding.assistantName?.trim();
   if (assistantName) {
     const identityPath = getWorkspacePromptPath("IDENTITY.md");
-    if (!existsSync(identityPath)) {
-      try {
+    try {
+      if (existsSync(identityPath)) {
+        const content = readFileSync(identityPath, "utf-8");
+        const updated = content.replace(
+          /^- (?:\*\*)?Name:(?:\*\*)?\s*.*$/m,
+          () => `- **Name:** ${assistantName}`,
+        );
+        if (updated !== content) {
+          writeFileSync(identityPath, updated, "utf-8");
+        }
+      } else {
         writeFileSync(
           identityPath,
-          `# Identity\n\n- Name: ${assistantName}\n`,
+          `# Identity\n\n- **Name:** ${assistantName}\n`,
           "utf-8",
         );
-      } catch (err) {
-        log.warn(
-          { err, identityPath },
-          "Failed to seed IDENTITY.md from onboarding",
-        );
       }
+    } catch (err) {
+      log.warn(
+        { err, identityPath },
+        "Failed to seed IDENTITY.md from onboarding",
+      );
     }
   }
 
   const userName = onboarding.userName?.trim();
   if (userName) {
     const userPath = getWorkspacePromptPath("USER.md");
-    if (!existsSync(userPath)) {
-      try {
-        writeFileSync(userPath, `# User\n\n- Name: ${userName}\n`, "utf-8");
-      } catch (err) {
-        log.warn({ err, userPath }, "Failed to seed USER.md from onboarding");
+    try {
+      if (existsSync(userPath)) {
+        const content = readFileSync(userPath, "utf-8");
+        const updated = content.replace(
+          /^- (?:\*\*)?Name:(?:\*\*)?\s*.*$/m,
+          () => `- **Name:** ${userName}`,
+        );
+        if (updated !== content) {
+          writeFileSync(userPath, updated, "utf-8");
+        }
+      } else {
+        writeFileSync(userPath, `# User\n\n- **Name:** ${userName}\n`, "utf-8");
       }
+    } catch (err) {
+      log.warn({ err, userPath }, "Failed to seed USER.md from onboarding");
     }
   }
 
@@ -1320,15 +1455,13 @@ function persistOnboardingArtifacts(onboarding: {
 }
 
 export async function handleSendMessage(
-  req: Request,
+  { body: rawBody, headers }: RouteHandlerArgs,
   deps: {
     sendMessageDeps?: SendMessageDeps;
     approvalConversationGenerator?: ApprovalConversationGenerator;
-    heartbeatService?: HeartbeatService;
   },
-  authContext: AuthContext,
-): Promise<Response> {
-  const body = (await req.json()) as {
+): Promise<unknown> {
+  const body = (rawBody ?? {}) as {
     conversationKey?: string;
     content?: string;
     attachmentIds?: string[];
@@ -1339,7 +1472,10 @@ export async function handleSendMessage(
     bypassSecretCheck?: boolean;
     hostHomeDir?: string;
     hostUsername?: string;
+    clientId?: string;
     clientMessageId?: string;
+    inferenceProfile?: string | null;
+    riskThreshold?: string;
     onboarding?: {
       tools: string[];
       tasks: string[];
@@ -1349,35 +1485,70 @@ export async function handleSendMessage(
     };
   };
 
+  const actorPrincipalId = headers?.["x-vellum-actor-principal-id"];
+  const principalType = headers?.["x-vellum-principal-type"];
+
   const { conversationKey, content, attachmentIds } = body;
   const clientMessageId =
     typeof body.clientMessageId === "string" ? body.clientMessageId : undefined;
+  const requestedInferenceProfile =
+    typeof body.inferenceProfile === "string"
+      ? body.inferenceProfile
+      : undefined;
+  const requestedRiskThreshold = body.riskThreshold;
+  if (
+    body.inferenceProfile != null &&
+    typeof body.inferenceProfile !== "string"
+  ) {
+    throw new BadRequestError(
+      "inferenceProfile must be a non-empty string or null",
+    );
+  }
+  if (requestedInferenceProfile === "") {
+    throw new BadRequestError(
+      "inferenceProfile must be a non-empty string or null",
+    );
+  }
+  if (requestedInferenceProfile !== undefined) {
+    const profiles = getConfig().llm.profiles ?? {};
+    if (
+      !Object.prototype.hasOwnProperty.call(profiles, requestedInferenceProfile)
+    ) {
+      throw new BadRequestError(
+        `Profile "${requestedInferenceProfile}" is not defined in llm.profiles`,
+      );
+    }
+  }
+  if (
+    requestedRiskThreshold !== undefined &&
+    !isValidRiskThreshold(requestedRiskThreshold)
+  ) {
+    throw new BadRequestError(
+      `riskThreshold must be one of: ${VALID_RISK_THRESHOLDS.join(", ")}`,
+    );
+  }
   if (!body.sourceChannel || typeof body.sourceChannel !== "string") {
-    return httpError("BAD_REQUEST", "sourceChannel is required", 400);
+    throw new BadRequestError("sourceChannel is required");
   }
   const sourceChannel = parseChannelId(body.sourceChannel);
 
   if (!sourceChannel) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       `Invalid sourceChannel: ${
         body.sourceChannel
       }. Valid values: ${CHANNEL_IDS.join(", ")}`,
-      400,
     );
   }
 
   if (!body.interface || typeof body.interface !== "string") {
-    return httpError("BAD_REQUEST", "interface is required", 400);
+    throw new BadRequestError("interface is required");
   }
   const sourceInterface = parseInterfaceId(body.interface);
   if (!sourceInterface) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       `Invalid interface: ${body.interface}. Valid values: ${INTERFACE_IDS.join(
         ", ",
       )}`,
-      400,
     );
   }
 
@@ -1389,7 +1560,7 @@ export async function handleSendMessage(
 
   // Reject non-string content values (numbers, objects, etc.)
   if (content != null && typeof content !== "string") {
-    return httpError("BAD_REQUEST", "content must be a string", 400);
+    throw new BadRequestError("content must be a string");
   }
 
   const trimmedContent = typeof content === "string" ? content.trim() : "";
@@ -1397,23 +1568,17 @@ export async function handleSendMessage(
     Array.isArray(attachmentIds) && attachmentIds.length > 0;
 
   if (trimmedContent.length === 0 && !hasAttachments) {
-    return httpError(
-      "BAD_REQUEST",
-      "content or attachmentIds is required",
-      400,
-    );
+    throw new BadRequestError("content or attachmentIds is required");
   }
 
   // Validate that all attachment IDs resolve
   if (hasAttachments) {
-    const resolved = attachmentsStore.getAttachmentsByIds(attachmentIds);
+    const resolved = getAttachmentsByIds(attachmentIds);
     if (resolved.length !== attachmentIds.length) {
       const resolvedIds = new Set(resolved.map((a) => a.id));
       const missing = attachmentIds.filter((id) => !resolvedIds.has(id));
-      return httpError(
-        "BAD_REQUEST",
+      throw new BadRequestError(
         `Attachment IDs not found: ${missing.join(", ")}`,
-        400,
       );
     }
   }
@@ -1422,36 +1587,52 @@ export async function handleSendMessage(
   if (trimmedContent.length > 0 && !body.bypassSecretCheck) {
     const ingressResult = checkIngressForSecrets(trimmedContent);
     if (ingressResult.blocked) {
-      return Response.json(
-        {
+      return new RouteResponse(
+        JSON.stringify({
           accepted: false,
           error: "secret_blocked",
           message: ingressResult.userNotice,
           detectedTypes: ingressResult.detectedTypes,
-        },
-        { status: 422 },
+        }),
+        { "content-type": "application/json" },
+        422,
       );
     }
   }
 
   if (!deps.sendMessageDeps) {
-    return httpError(
-      "SERVICE_UNAVAILABLE",
+    throw new RouteError(
       "Message processing is not available",
+      "SERVICE_UNAVAILABLE",
       503,
     );
   }
 
   // Desktop messages are always from the guardian — reset the heartbeat
   // timer so the next heartbeat is a full interval after this interaction.
-  deps.heartbeatService?.resetTimer();
+  HeartbeatService.getInstance()?.resetTimer();
 
-  const conversationType =
-    body.conversationType === "private" ? ("private" as const) : undefined;
   const mapping = getOrCreateConversation(resolvedConversationKey, {
-    conversationType,
+    conversationType: "standard",
   });
 
+  if (requestedRiskThreshold !== undefined) {
+    const result = await ipcCall("set_conversation_threshold", {
+      conversationId: mapping.conversationId,
+      threshold: requestedRiskThreshold,
+    });
+    if (result === undefined) {
+      log.error(
+        {
+          conversationId: mapping.conversationId,
+          threshold: requestedRiskThreshold,
+        },
+        "Failed to set conversation risk threshold override via gateway IPC",
+      );
+      throw new InternalError("Failed to persist risk threshold override");
+    }
+  }
+
   const smDeps = deps.sendMessageDeps;
 
   // Notify all connected clients that the conversation list changed when
@@ -1500,25 +1681,33 @@ export async function handleSendMessage(
     { transport },
   );
 
+  if (requestedInferenceProfile !== undefined) {
+    setConversationInferenceProfile(
+      mapping.conversationId,
+      requestedInferenceProfile,
+    );
+  }
+
   // Store pre-chat onboarding context on the conversation when this is the
-  // very first message (no prior messages loaded). Also persist the
-  // onboarding selections so the Home page shows onboarding-sourced
-  // chips immediately, and seed IDENTITY.md / USER.md so subsequent
-  // turn-boundary recomputes of relationship-state have a stable
-  // persona source beyond the in-memory conversation object.
-  if (body.onboarding && conversation.messages.length === 0) {
-    conversation.setOnboardingContext(body.onboarding);
-    persistOnboardingArtifacts(body.onboarding);
+  // very first message (no prior messages loaded). Artifact persistence
+  // (IDENTITY.md, USER.md, sidecar) is deferred: on the canned greeting
+  // path it runs inside the setTimeout right before warmPromptCache() so
+  // the warmed system prompt includes the identity; on the normal LLM
+  // path it runs immediately before inference starts.
+  const isFirstOnboarding =
+    !!body.onboarding && conversation.messages.length === 0;
+  if (isFirstOnboarding) {
+    conversation.setOnboardingContext(body.onboarding!);
   }
 
   // Resolve guardian context from the AuthContext's actorPrincipalId.
   // The JWT-verified principal is used as the sender identity through
   // the same trust resolution pipeline that channel ingress uses.
-  if (authContext.actorPrincipalId) {
+  if (actorPrincipalId) {
     // Dev bypass (HTTP auth disabled): the synthetic "dev-bypass" principal
     // won't match any guardian binding. Resolve from the local guardian
     // binding instead, which produces the correct guardian trust context.
-    if (isHttpAuthDisabled() && authContext.actorPrincipalId === "dev-bypass") {
+    if (isHttpAuthDisabled() && actorPrincipalId === "dev-bypass") {
       conversation.setTrustContext(resolveLocalTrustContext(sourceChannel));
     } else {
       const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
@@ -1526,24 +1715,24 @@ export async function handleSendMessage(
         assistantId,
         sourceChannel: "vellum",
         conversationExternalId: "local",
-        actorExternalId: authContext.actorPrincipalId,
+        actorExternalId: actorPrincipalId,
       });
       if (trustCtx.trustClass === "unknown") {
         // Attempt to heal guardian binding drift: after a DB reset the
         // guardian binding gets a new vellum-principal-* UUID while the
         // client still holds a valid JWT with the old one. The signing
         // key survives the reset, so the JWT is authentic — just stale.
-        const healed = healGuardianBindingDrift(authContext.actorPrincipalId);
+        const healed = healGuardianBindingDrift(actorPrincipalId);
         if (healed) {
           trustCtx = resolveTrustContext({
             assistantId,
             sourceChannel: "vellum",
             conversationExternalId: "local",
-            actorExternalId: authContext.actorPrincipalId,
+            actorExternalId: actorPrincipalId,
           });
           log.info(
             {
-              actorPrincipalId: authContext.actorPrincipalId,
+              actorPrincipalId: actorPrincipalId,
               trustClass: trustCtx.trustClass,
             },
             "Trust re-resolved after guardian binding drift heal",
@@ -1551,10 +1740,10 @@ export async function handleSendMessage(
         } else {
           log.warn(
             {
-              actorPrincipalId: authContext.actorPrincipalId,
+              actorPrincipalId: actorPrincipalId,
               sourceChannel,
               trustClass: trustCtx.trustClass,
-              principalType: authContext.principalType,
+              principalType: principalType,
             },
             "JWT-verified actor resolved to unknown trust class — possible guardian binding drift (e.g. DB reset without re-bootstrap)",
           );
@@ -1593,17 +1782,19 @@ export async function handleSendMessage(
     conversation.setHostBashProxy(undefined);
   }
   // Resolve the host_browser sender — registry-routed when the guardian has
-  // an active extension connection, SSE hub otherwise. This applies to both
-  // chrome-extension and macOS interfaces so that macOS turns can route
-  // browser automation through the user's real Chrome session when available.
-  const { sender: browserProxySendToClient, isRegistryRouted } =
-    resolveHostBrowserSender(
-      conversation,
-      mapping.conversationId,
-      authContext,
-      onEvent,
-      sourceInterface,
-    );
+  // an active WS extension connection, SSE hub when a chrome-extension is
+  // connected via SSE (cloud mode), or SSE hub as default for macOS.
+  const {
+    sender: browserProxySendToClient,
+    isRegistryRouted,
+    hasSseExtension,
+  } = resolveHostBrowserSender(
+    conversation,
+    mapping.conversationId,
+    actorPrincipalId,
+    onEvent,
+    sourceInterface,
+  );
 
   // Stash the registry-routed sender on the conversation so queue-drain
   // restores (which run outside of conversation-routes.ts and only have
@@ -1618,17 +1809,18 @@ export async function handleSendMessage(
     conversation.hostBrowserSenderOverride = undefined;
   }
 
-  // Provision the host browser proxy. For interfaces that natively support
-  // host_browser (chrome-extension), always provision it. For macOS, the
-  // static capability check returns false (supportsHostProxy("macos",
-  // "host_browser") === false) because the extension isn't guaranteed to be
-  // attached — but when the registry confirms an active extension
-  // connection, we provision the proxy anyway so macOS turns can drive the
-  // user's real Chrome session. When no extension is connected, macOS skips
-  // provisioning and browser tools fall through to cdp-inspect/local.
+  // Provision the host browser proxy when a viable transport exists:
+  //   - macOS: natively supports host_browser via its own SSE path
+  //   - WS registry: extension connected via direct WebSocket
+  //   - SSE extension: chrome extension connected via SSE (cloud mode)
+  //
+  // For chrome-extension, require an active transport (WS or SSE). Without
+  // one, host_browser_request frames would be emitted to the SSE hub with
+  // no consumer, causing a 30s proxy timeout instead of failing fast.
   const shouldProvisionBrowserProxy =
-    supportsHostProxy(sourceInterface, "host_browser") ||
-    (canServiceRegistryBrowser(sourceInterface) && isRegistryRouted);
+    supportsHostProxy(sourceInterface) ||
+    (canServiceRegistryBrowser(sourceInterface) && isRegistryRouted) ||
+    hasSseExtension;
   if (shouldProvisionBrowserProxy) {
     if (!conversation.isProcessing() || !conversation.hostBrowserProxy) {
       const browserProxy = new HostBrowserProxy(
@@ -1649,8 +1841,15 @@ export async function handleSendMessage(
       });
       conversation.setHostFileProxy(fileProxy);
     }
+    if (!conversation.isProcessing() || !conversation.getHostTransferProxy()) {
+      const transferProxy = new HostTransferProxy(onEvent, (requestId) => {
+        pendingInteractions.resolve(requestId);
+      });
+      conversation.setHostTransferProxy(transferProxy);
+    }
   } else if (!conversation.isProcessing()) {
     conversation.setHostFileProxy(undefined);
+    conversation.setHostTransferProxy(undefined);
   }
   if (supportsHostProxy(sourceInterface, "host_cu")) {
     if (!conversation.isProcessing() || !conversation.hostCuProxy) {
@@ -1688,9 +1887,10 @@ export async function handleSendMessage(
     skipProxySenderUpdate: preservingProxies,
   });
   // Re-enable the browser proxy for turns that provisioned one. This covers:
+  // - macOS: always provisioned (SSE sender or registry-routed when extension
+  //   is connected)
   // - chrome-extension: natively supports host_browser (non-interactive but
   //   has a connected client for host_browser_request events)
-  // - macOS with extension: provisioned above when isRegistryRouted is true
   //
   // The helper bypasses the `hasNoClient` gate so chrome-extension turns can
   // drive the browser via CDP without leaking host_bash/host_file tool
@@ -1703,97 +1903,103 @@ export async function handleSendMessage(
 
   // ── Canned first-greeting fast path ──
   // On a completely fresh workspace, skip LLM inference for the macOS
-  // wake-up greeting and return a pre-written response. This eliminates
-  // 10-30s of inference latency on first boot.
+  // wake-up greeting and return a pre-written response. When onboarding
+  // context is present the greeting is personalized using the selections;
+  // otherwise a generic greeting is served. Both paths are instant.
   if (isWakeUpGreeting(trimmedContent, conversation.getMessages().length)) {
-    const cannedGreeting = getCannedFirstGreeting();
-    if (cannedGreeting) {
-      conversation.processing = true;
-      let cleanupDeferred = false;
-      try {
-        const provenance = provenanceFromTrustContext(
-          conversation.trustContext,
-        );
-        const channelMeta = {
-          ...provenance,
-          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);
+    const cannedGreeting = getCannedFirstGreeting(body.onboarding ?? undefined);
 
-        setConversationOriginChannelIfUnset(
-          mapping.conversationId,
-          sourceChannel,
-        );
-        setConversationOriginInterfaceIfUnset(
-          mapping.conversationId,
-          sourceInterface,
-        );
+    conversation.processing = true;
+    let cleanupDeferred = false;
+    try {
+      const provenance = provenanceFromTrustContext(conversation.trustContext);
+      const channelMeta = {
+        ...provenance,
+        userMessageChannel: sourceChannel,
+        assistantMessageChannel: sourceChannel,
+        userMessageInterface: sourceInterface,
+        assistantMessageInterface: sourceInterface,
+      };
 
-        const assistantMsg = createAssistantMessage(cannedGreeting);
-        await addMessage(
-          mapping.conversationId,
-          "assistant",
-          JSON.stringify(assistantMsg.content),
-          channelMeta,
-        );
-        conversation.getMessages().push(assistantMsg);
+      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);
 
-        const conversationId = mapping.conversationId;
-        const response = Response.json(
-          { accepted: true, messageId: persisted.id, conversationId },
-          { status: 202 },
-        );
+      setConversationOriginChannelIfUnset(
+        mapping.conversationId,
+        sourceChannel,
+      );
+      setConversationOriginInterfaceIfUnset(
+        mapping.conversationId,
+        sourceInterface,
+      );
 
-        // Defer event publishing to next tick (same pattern as unknown-slash
-        // fast path) so the HTTP response reaches the client before SSE
-        // events arrive.
-        setTimeout(() => {
-          onEvent({
-            type: "user_message_echo",
-            text: rawContent,
-            conversationId,
-            messageId: persisted.id,
-            clientMessageId,
-          });
-          onEvent({ type: "assistant_text_delta", text: cannedGreeting });
-          onEvent({ type: "message_complete", conversationId });
-          conversation.processing = false;
-          silentlyWithLog(
-            conversation.drainQueue(),
-            "canned-greeting queue drain",
-          );
-        }, 0);
+      const conversationId = mapping.conversationId;
+
+      const assistantMsg = createAssistantMessage(cannedGreeting);
+      await addMessage(
+        mapping.conversationId,
+        "assistant",
+        JSON.stringify(assistantMsg.content),
+        channelMeta,
+      );
+      conversation.getMessages().push(assistantMsg);
+
+      const response = {
+        accepted: true,
+        messageId: persisted.id,
+        conversationId,
+      };
 
-        log.info(
-          { conversationId },
-          "Served canned first greeting — skipped LLM inference",
+      setTimeout(() => {
+        onEvent({
+          type: "user_message_echo",
+          text: rawContent,
+          conversationId,
+          messageId: persisted.id,
+          clientMessageId,
+        });
+        onEvent({ type: "assistant_text_delta", text: cannedGreeting });
+        onEvent({ type: "message_complete", conversationId });
+        conversation.processing = false;
+        silentlyWithLog(
+          conversation.drainQueue(),
+          "canned-greeting queue drain",
         );
-        cleanupDeferred = true;
-        return response;
-      } finally {
-        if (!cleanupDeferred && conversation.processing) {
-          conversation.processing = false;
-          silentlyWithLog(conversation.drainQueue(), "error-path queue drain");
+
+        if (isFirstOnboarding) {
+          persistOnboardingArtifacts(body.onboarding!);
         }
+        conversation.warmPromptCache();
+      }, 0);
+
+      log.info(
+        { conversationId, personalized: !!body.onboarding },
+        "Served canned first greeting — skipped LLM inference",
+      );
+      cleanupDeferred = true;
+      return response;
+    } finally {
+      if (!cleanupDeferred && conversation.processing) {
+        conversation.processing = false;
+        silentlyWithLog(conversation.drainQueue(), "error-path queue drain");
       }
     }
   }
 
+  if (isFirstOnboarding) {
+    persistOnboardingArtifacts(body.onboarding!);
+  }
+
   const attachments = hasAttachments
     ? smDeps.resolveAttachments(attachmentIds)
     : [];
@@ -1828,16 +2034,13 @@ export async function handleSendMessage(
       verifiedActorPrincipalId,
     });
     if (inlineReplyResult.consumed) {
-      return Response.json(
-        {
-          accepted: true,
-          conversationId: mapping.conversationId,
-          ...(inlineReplyResult.messageId
-            ? { messageId: inlineReplyResult.messageId }
-            : {}),
-        },
-        { status: 202 },
-      );
+      return {
+        accepted: true,
+        conversationId: mapping.conversationId,
+        ...(inlineReplyResult.messageId
+          ? { messageId: inlineReplyResult.messageId }
+          : {}),
+      };
     }
   } catch (err) {
     log.warn(
@@ -1869,9 +2072,10 @@ export async function handleSendMessage(
       clientMessageId,
     );
     if (enqueueResult.rejected) {
-      return Response.json(
-        { accepted: false, error: "queue_full" },
-        { status: 429 },
+      return new RouteResponse(
+        JSON.stringify({ accepted: false, error: "queue_full" }),
+        { "content-type": "application/json" },
+        429,
       );
     }
 
@@ -1920,10 +2124,11 @@ export async function handleSendMessage(
       );
     }
 
-    return Response.json(
-      { accepted: true, queued: true, conversationId: mapping.conversationId },
-      { status: 202 },
-    );
+    return {
+      accepted: true,
+      queued: true,
+      conversationId: mapping.conversationId,
+    };
   }
 
   // Auto-deny pending confirmations for idle conversations. The legacy
@@ -2044,14 +2249,11 @@ export async function handleSendMessage(
         ? await buildModelInfoEvent()
         : null;
 
-      const response = Response.json(
-        {
-          accepted: true,
-          messageId: persisted.id,
-          conversationId: mapping.conversationId,
-        },
-        { status: 202 },
-      );
+      const response = {
+        accepted: true,
+        messageId: persisted.id,
+        conversationId: mapping.conversationId,
+      };
 
       // Defer event publishing to next tick so the HTTP response reaches the
       // client first. This ensures the client's serverToLocalConversationMap is
@@ -2165,14 +2367,11 @@ export async function handleSendMessage(
       }
     })();
 
-    return Response.json(
-      {
-        accepted: true,
-        messageId: persisted.id,
-        conversationId,
-      },
-      { status: 202 },
-    );
+    return {
+      accepted: true,
+      messageId: persisted.id,
+      conversationId,
+    };
   }
 
   const resolvedContent = slashResult.content;
@@ -2212,10 +2411,11 @@ export async function handleSendMessage(
       );
     });
 
-  return Response.json(
-    { accepted: true, messageId, conversationId: mapping.conversationId },
-    { status: 202 },
-  );
+  return {
+    accepted: true,
+    messageId,
+    conversationId: mapping.conversationId,
+  };
 }
 
 function escapeXmlContent(text: string): string {
@@ -2251,11 +2451,15 @@ async function generateLlmSuggestion(
     `Write the user's next reply, focusing on the LAST question or call-to-action in the assistant message. Keep it short (under 15 words), casual, and in the user's voice. Respond in this exact format:\n\n` +
     `<reply>YOUR_REPLY_HERE</reply>`;
 
+  // Single user message only — no assistant-role prefill. Anthropic
+  // rejects assistant prefill whenever the request triggers extended
+  // thinking (e.g. Opus 4.x at `effort: "xhigh"`), and the call-site
+  // config is user-controlled, so we can't statically guarantee a
+  // prefill-safe model. Keep `stop_sequences: ["</reply>"]` as an
+  // early-termination hint; the parser below handles both tagged and
+  // untagged responses so untagged "casual answer" replies still work.
   const response = await provider.sendMessage(
-    [
-      { role: "user", content: [{ type: "text", text: userPrompt }] },
-      { role: "assistant", content: [{ type: "text", text: "<reply>" }] },
-    ],
+    [{ role: "user", content: [{ type: "text", text: userPrompt }] }],
     [], // no tools
     systemPrompt,
     {
@@ -2270,7 +2474,12 @@ async function generateLlmSuggestion(
 
   const textBlock = response.content.find((b) => b.type === "text");
   const raw = textBlock && "text" in textBlock ? textBlock.text : "";
-  const stripped = raw
+  // Prefer the content inside <reply>…</reply> when the model honors the
+  // tag format. If the response has no tags, fall back to the raw text —
+  // a plain "Sure, tomorrow works" without tags is still a valid chip.
+  const tagMatch = raw.match(/<reply>([\s\S]*?)(?:<\/reply>|$)/i);
+  const extracted = tagMatch ? tagMatch[1] : raw;
+  const stripped = extracted
     .replace(/<\/?reply>/gi, "")
     .replace(/^["'`]+|["'`]+$/g, "")
     .trim();
@@ -2293,54 +2502,39 @@ async function generateLlmSuggestion(
 }
 
 export async function handleGetSuggestion(
-  url: URL,
+  { queryParams }: RouteHandlerArgs,
   deps: {
     suggestionCache: Map<string, string>;
     suggestionInFlight: Map<string, Promise<string | null>>;
   },
-): Promise<Response> {
-  const conversationKey = url.searchParams.get("conversationKey");
+): Promise<Record<string, unknown>> {
+  const noSuggestion = {
+    suggestion: null,
+    messageId: null,
+    source: "none" as const,
+  };
+
+  const conversationKey = queryParams?.conversationKey;
   if (!conversationKey) {
-    return httpError(
-      "BAD_REQUEST",
-      "conversationKey query parameter is required",
-      400,
-    );
+    throw new BadRequestError("conversationKey query parameter is required");
   }
 
   const mapping = getConversationByKey(conversationKey);
-  if (!mapping) {
-    return Response.json({
-      suggestion: null,
-      messageId: null,
-      source: "none" as const,
-    });
-  }
+  if (!mapping) return noSuggestion;
 
   const rawMessages = getMessages(mapping.conversationId);
-  if (rawMessages.length === 0) {
-    return Response.json({
-      suggestion: null,
-      messageId: null,
-      source: "none" as const,
-    });
-  }
+  if (rawMessages.length === 0) return noSuggestion;
 
   // Staleness check: compare requested messageId against the latest
   // assistant message BEFORE filtering by text content.  This ensures
   // that a newer tool-only assistant turn (empty text) still causes
   // older messageId requests to be correctly marked as stale.
-  const requestedMessageId = url.searchParams.get("messageId");
+  const requestedMessageId = queryParams?.messageId;
   if (requestedMessageId) {
     for (let i = rawMessages.length - 1; i >= 0; i--) {
       if (rawMessages[i].role === "assistant") {
         if (rawMessages[i].id !== requestedMessageId) {
-          return Response.json({
-            suggestion: null,
-            messageId: null,
-            source: "none" as const,
-            stale: true,
-          });
+          return { ...noSuggestion, stale: true };
         }
         break;
       }
@@ -2368,22 +2562,13 @@ export async function handleGetSuggestion(
     // If a messageId was requested and the first text-bearing assistant
     // message is a *different* message, the request is stale.
     if (requestedMessageId && msg.id !== requestedMessageId) {
-      return Response.json({
-        suggestion: null,
-        messageId: null,
-        source: "none" as const,
-        stale: true,
-      });
+      return { ...noSuggestion, stale: true };
     }
 
     // Return cached suggestion if we already generated one for this message
     const cached = suggestionCache.get(msg.id);
     if (cached !== undefined) {
-      return Response.json({
-        suggestion: cached,
-        messageId: msg.id,
-        source: "llm" as const,
-      });
+      return { suggestion: cached, messageId: msg.id, source: "llm" as const };
     }
 
     // Find the most recent user message preceding this assistant turn so the
@@ -2427,11 +2612,11 @@ export async function handleGetSuggestion(
           }
           suggestionCache.set(msg.id, llmSuggestion);
 
-          return Response.json({
+          return {
             suggestion: llmSuggestion,
             messageId: msg.id,
             source: "llm" as const,
-          });
+          };
         }
       } catch (err) {
         suggestionInFlight.delete(msg.id);
@@ -2447,18 +2632,10 @@ export async function handleGetSuggestion(
       );
     }
 
-    return Response.json({
-      suggestion: null,
-      messageId: null,
-      source: "none" as const,
-    });
+    return noSuggestion;
   }
 
-  return Response.json({
-    suggestion: null,
-    messageId: null,
-    source: "none" as const,
-  });
+  return noSuggestion;
 }
 
 /**
@@ -2467,19 +2644,17 @@ export async function handleGetSuggestion(
  * Full-text search across all conversations (message content + titles).
  * Returns ranked results grouped by conversation, each with matching message excerpts.
  */
-function handleSearchConversations(url: URL): Response {
-  const query = url.searchParams.get("q") ?? "";
+function handleSearchConversations({
+  queryParams,
+}: RouteHandlerArgs): Record<string, unknown> {
+  const query = queryParams?.q ?? "";
   if (!query.trim()) {
-    return httpError("BAD_REQUEST", "q query parameter is required", 400);
+    throw new BadRequestError("q query parameter is required");
   }
 
-  const limit = url.searchParams.has("limit")
-    ? Number(url.searchParams.get("limit"))
-    : undefined;
-  const maxMessagesPerConversation = url.searchParams.has(
-    "maxMessagesPerConversation",
-  )
-    ? Number(url.searchParams.get("maxMessagesPerConversation"))
+  const limit = queryParams?.limit ? Number(queryParams.limit) : undefined;
+  const maxMessagesPerConversation = queryParams?.maxMessagesPerConversation
+    ? Number(queryParams.maxMessagesPerConversation)
     : undefined;
 
   const results = searchConversations(query, {
@@ -2490,105 +2665,125 @@ function handleSearchConversations(url: URL): Response {
       : {}),
   });
 
-  return Response.json({ query, results });
+  return { query, results };
+}
+
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
+
+const suggestionCache = new Map<string, string>();
+const suggestionInFlight = new Map<string, Promise<string | null>>();
+
+function resolveAttachments(attachmentIds: string[]) {
+  const resolved = getAttachmentsByIds(attachmentIds, {
+    hydrateFileData: true,
+  });
+  const sourcePaths = getSourcePathsForAttachments(attachmentIds);
+  return resolved.map((a) => ({
+    id: a.id,
+    filename: a.originalFilename,
+    mimeType: a.mimeType,
+    data: a.dataBase64,
+    ...(sourcePaths.has(a.id) ? { filePath: sourcePaths.get(a.id) } : {}),
+  }));
 }
 
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
 
-export function conversationRouteDefinitions(deps: {
-  interfacesDir: string | null;
-  sendMessageDeps?: SendMessageDeps;
-  approvalConversationGenerator?: ApprovalConversationGenerator;
-  suggestionCache: Map<string, string>;
-  suggestionInFlight: Map<string, Promise<string | null>>;
-  getHeartbeatService?: () => HeartbeatService | undefined;
-}): RouteDefinition[] {
-  return [
-    {
-      endpoint: "messages",
-      method: "GET",
-      summary: "List messages",
-      description:
-        "Return messages for a conversation, including attachments and interface file metadata.",
-      tags: ["messages"],
-      responseBody: z.object({
-        messages: z.array(z.unknown()).describe("Array of message objects"),
-        hasMore: z
-          .boolean()
-          .optional()
-          .describe("Whether older messages exist beyond this page"),
-        oldestTimestamp: z
-          .number()
-          .optional()
-          .describe(
-            "Timestamp of the oldest message in this page (ms since epoch)",
-          ),
-        oldestMessageId: z
-          .string()
-          .optional()
-          .describe("ID of the oldest message in this page"),
-      }),
-      handler: ({ url }) => handleListMessages(url, deps.interfacesDir),
-    },
-    {
-      endpoint: "messages",
-      method: "POST",
-      summary: "Send a message",
-      description:
-        "Send a user message to a conversation and trigger the assistant response.",
-      tags: ["messages"],
-      requestBody: z.object({
-        conversationKey: z.string().optional(),
-        content: z.string().describe("Message text content"),
-        attachments: z
-          .array(z.unknown())
-          .describe("Optional file attachments")
-          .optional(),
-        conversationType: z.string().optional(),
-        slashCommand: z.string().optional(),
-      }),
-      handler: async ({ req, authContext }) =>
-        handleSendMessage(
-          req,
-          {
-            sendMessageDeps: deps.sendMessageDeps,
-            approvalConversationGenerator: deps.approvalConversationGenerator,
-            heartbeatService: deps.getHeartbeatService?.(),
-          },
-          authContext,
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "messages_get",
+    endpoint: "messages",
+    method: "GET",
+    summary: "List messages",
+    description:
+      "Return messages for a conversation, including attachments and interface file metadata.",
+    tags: ["messages"],
+    responseBody: z.object({
+      messages: z.array(z.unknown()).describe("Array of message objects"),
+      hasMore: z
+        .boolean()
+        .optional()
+        .describe("Whether older messages exist beyond this page"),
+      oldestTimestamp: z
+        .number()
+        .nullable()
+        .optional()
+        .describe(
+          "Timestamp of the oldest message in this page (ms since epoch). Null when page=latest is used on an empty conversation.",
         ),
-    },
-    {
-      endpoint: "search",
-      method: "GET",
-      summary: "Search conversations",
-      description: "Full-text search across all conversations.",
-      tags: ["conversations"],
-      responseBody: z.object({
-        query: z.string(),
-        results: z.array(z.unknown()),
+      oldestMessageId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("ID of the oldest message in this page"),
+    }),
+    handler: (args) => handleListMessages(args, getInterfacesDir()),
+  },
+  {
+    operationId: "messages_post",
+    endpoint: "messages",
+    method: "POST",
+    summary: "Send a message",
+    description:
+      "Send a user message to a conversation and trigger the assistant response.",
+    tags: ["messages"],
+    responseStatus: "202",
+    requestBody: z.object({
+      conversationKey: z.string().optional(),
+      content: z.string().describe("Message text content"),
+      attachments: z
+        .array(z.unknown())
+        .describe("Optional file attachments")
+        .optional(),
+      conversationType: z.string().optional(),
+      slashCommand: z.string().optional(),
+      inferenceProfile: z.string().nullable().optional(),
+      riskThreshold: z.enum(VALID_RISK_THRESHOLDS).optional(),
+    }),
+    handler: async (args) =>
+      handleSendMessage(args, {
+        sendMessageDeps: {
+          getOrCreateConversation: getOrCreateConversationInstance,
+          assistantEventHub,
+          resolveAttachments,
+        },
+        approvalConversationGenerator: createApprovalConversationGenerator(),
       }),
-      handler: ({ url }) => handleSearchConversations(url),
-    },
-    {
-      endpoint: "suggestion",
-      method: "GET",
-      summary: "Get reply suggestion",
-      description:
-        "Return an LLM-generated follow-up suggestion for the most recent assistant message.",
-      tags: ["messages"],
-      responseBody: z.object({
-        suggestion: z.string(),
-        messageId: z.string(),
-        source: z.string(),
+  },
+  {
+    operationId: "search_get",
+    endpoint: "search",
+    method: "GET",
+    summary: "Search conversations",
+    description: "Full-text search across all conversations.",
+    tags: ["conversations"],
+    responseBody: z.object({
+      query: z.string(),
+      results: z.array(z.unknown()),
+    }),
+    handler: handleSearchConversations,
+  },
+  {
+    operationId: "suggestion_get",
+    endpoint: "suggestion",
+    method: "GET",
+    summary: "Get reply suggestion",
+    description:
+      "Return an LLM-generated follow-up suggestion for the most recent assistant message.",
+    tags: ["messages"],
+    responseBody: z.object({
+      suggestion: z.string(),
+      messageId: z.string(),
+      source: z.string(),
+    }),
+    handler: async (args) =>
+      handleGetSuggestion(args, {
+        suggestionCache,
+        suggestionInFlight,
       }),
-      handler: async ({ url }) =>
-        handleGetSuggestion(url, {
-          suggestionCache: deps.suggestionCache,
-          suggestionInFlight: deps.suggestionInFlight,
-        }),
-    },
-  ];
-}
+  },
+];