@vellumai/assistant 0.6.6 → 0.7.0

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

@@ -19,6 +19,7 @@ import {
 } from "../../agent/message-types.js";
 import {
   canServiceRegistryBrowser,
+  canServiceSseBrowser,
   CHANNEL_IDS,
   INTERFACE_IDS,
   type InterfaceId,
@@ -29,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,
@@ -39,6 +41,7 @@ import {
   resolveSlash,
   type SlashContext,
 } from "../../daemon/conversation-slash.js";
+import { getOrCreateConversation as getOrCreateConversationInstance } from "../../daemon/conversation-store.js";
 import {
   getCannedFirstGreeting,
   isWakeUpGreeting,
@@ -48,19 +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 { rewriteCommandPreview } from "../../home/rewrite-command-preview.js";
-import * as attachmentsStore from "../../memory/attachments-store.js";
+import { ipcCall } from "../../ipc/gateway-client.js";
+import {
+  getAttachmentById,
+  getAttachmentMetadataForMessage,
+  getAttachmentsByIds,
+  getSourcePathsForAttachments,
+} from "../../memory/attachments-store.js";
 import {
   createCanonicalGuardianRequest,
   generateCanonicalRequestCode,
@@ -76,6 +86,7 @@ import {
   hasMessages,
   type MessageRow,
   provenanceFromTrustContext,
+  setConversationInferenceProfile,
   setConversationOriginChannelIfUnset,
   setConversationOriginInterfaceIfUnset,
 } from "../../memory/conversation-crud.js";
@@ -90,18 +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,
@@ -114,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");
 
@@ -121,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,
@@ -368,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) {
@@ -381,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
@@ -415,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;
@@ -583,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 {
@@ -664,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 ─────────────────────────────────────────────
@@ -1003,7 +1052,6 @@ function makeHubPublisher(
           allowlistOptions: msg.allowlistOptions,
           scopeOptions: msg.scopeOptions,
           persistentDecisionsAllowed: msg.persistentDecisionsAllowed,
-          temporaryOptionsAvailable: msg.temporaryOptionsAvailable,
         },
       });
 
@@ -1024,6 +1072,7 @@ function makeHubPublisher(
         dedupKey,
         urgency: msg.riskLevel === "high" ? "high" : "medium",
         conversationId,
+        detailPanel: { kind: "toolPermission" },
       }).catch((err) => {
         log.warn(
           { err, requestId: msg.requestId },
@@ -1044,6 +1093,7 @@ function makeHubPublisher(
                 dedupKey,
                 urgency: msg.riskLevel === "high" ? "high" : "medium",
                 conversationId,
+                detailPanel: { kind: "toolPermission" },
               });
             }
           })
@@ -1225,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`).
- *
- * 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.
+ * 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`.
  *
- * 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,
+    };
+  }
+
+  // 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: registrySender, isRegistryRouted: true };
+  return { sender: onEvent, isRegistryRouted: false, hasSseExtension };
 }
 
 /**
@@ -1395,15 +1455,13 @@ export 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[];
@@ -1416,6 +1474,8 @@ export async function handleSendMessage(
     hostUsername?: string;
     clientId?: string;
     clientMessageId?: string;
+    inferenceProfile?: string | null;
+    riskThreshold?: string;
     onboarding?: {
       tools: string[];
       tasks: string[];
@@ -1425,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,
     );
   }
 
@@ -1465,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() : "";
@@ -1473,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,
       );
     }
   }
@@ -1498,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
@@ -1571,27 +1676,18 @@ export async function handleSendMessage(
         interfaceId: sourceInterface,
       } satisfies NonHostProxyTransportMetadata);
 
-  // Register/refresh the client in the unified client registry so
-  // `assistant clients list` can discover all connected interfaces.
-  // Uses the client-supplied clientId when available (stable per-install
-  // UUID), falling back to a synthetic key derived from interfaceId so
-  // older clients that don't send clientId still appear in the registry.
-  const effectiveClientId =
-    typeof body.clientId === "string" && body.clientId.length > 0
-      ? body.clientId
-      : `synthetic:${sourceInterface}`;
-  getClientRegistry().register({
-    clientId: effectiveClientId,
-    interfaceId: sourceInterface,
-    hostHomeDir: body.hostHomeDir,
-    hostUsername: body.hostUsername,
-  });
-
   const conversation = await smDeps.getOrCreateConversation(
     mapping.conversationId,
     { 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). Artifact persistence
   // (IDENTITY.md, USER.md, sidecar) is deferred: on the canned greeting
@@ -1607,11 +1703,11 @@ export async function handleSendMessage(
   // 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;
@@ -1619,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",
@@ -1644,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)",
           );
@@ -1686,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
@@ -1711,16 +1809,18 @@ export async function handleSendMessage(
     conversation.hostBrowserSenderOverride = undefined;
   }
 
-  // Provision the host browser proxy. Both macOS and chrome-extension
-  // natively support host_browser. For macOS, the proxy is wired to the
-  // SSE sender by default so `host_browser_request` frames reach the
-  // desktop client directly. When the guardian also has an active extension
-  // connection (isRegistryRouted), the registry-routed sender is used
-  // instead so browser tools route through the user's real Chrome session.
-  // For chrome-extension, the registry sender is always used.
+  // 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(
@@ -1741,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) {
@@ -1847,10 +1954,11 @@ export async function handleSendMessage(
       );
       conversation.getMessages().push(assistantMsg);
 
-      const response = Response.json(
-        { accepted: true, messageId: persisted.id, conversationId },
-        { status: 202 },
-      );
+      const response = {
+        accepted: true,
+        messageId: persisted.id,
+        conversationId,
+      };
 
       setTimeout(() => {
         onEvent({
@@ -1926,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(
@@ -1967,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,
       );
     }
 
@@ -2018,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
@@ -2142,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
@@ -2263,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;
@@ -2310,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 {
@@ -2400,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;
       }
@@ -2475,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
@@ -2534,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);
@@ -2554,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;
 }
 
 /**
@@ -2574,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, {
@@ -2597,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,
-        }),
-    },
-  ];
-}
+  },
+];