@vellumai/assistant 0.6.6 → 0.7.1

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

@@ -18,10 +18,8 @@ import {
   createUserMessage,
 } from "../../agent/message-types.js";
 import {
-  canServiceRegistryBrowser,
   CHANNEL_IDS,
   INTERFACE_IDS,
-  type InterfaceId,
   isInteractiveInterface,
   parseChannelId,
   parseInterfaceId,
@@ -29,6 +27,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,
@@ -36,34 +35,34 @@ import {
   isModelSlashCommand,
 } from "../../daemon/conversation-process.js";
 import {
+  buildSlashContextForContent,
   resolveSlash,
-  type SlashContext,
 } from "../../daemon/conversation-slash.js";
+import { getOrCreateConversation as getOrCreateConversationInstance } from "../../daemon/conversation-store.js";
 import {
   getCannedFirstGreeting,
   isWakeUpGreeting,
 } from "../../daemon/first-greeting.js";
 import { renderHistoryContent } from "../../daemon/handlers/shared.js";
-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 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 { emitFeedEvent } from "../../home/emit-feed-event.js";
+import { HeartbeatService } from "../../heartbeat/heartbeat-service.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,
   listCanonicalGuardianRequests,
   listPendingRequestsByConversationScope,
   resolveCanonicalGuardianRequest,
@@ -76,6 +75,7 @@ import {
   hasMessages,
   type MessageRow,
   provenanceFromTrustContext,
+  setConversationInferenceProfile,
   setConversationOriginChannelIfUnset,
   setConversationOriginInterfaceIfUnset,
 } from "../../memory/conversation-crud.js";
@@ -87,21 +87,17 @@ import { searchConversations } from "../../memory/conversation-queries.js";
 import { getConfiguredProvider } from "../../providers/provider-send-message.js";
 import type { Provider } from "../../providers/types.js";
 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, broadcastMessage } 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 +110,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 +120,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,
@@ -333,18 +341,6 @@ async function tryConsumeCanonicalGuardianReply(params: {
   return { consumed: true, messageId };
 }
 
-function resolveCanonicalRequestSourceType(
-  sourceChannel: string | undefined,
-): "desktop" | "channel" | "voice" {
-  if (sourceChannel === "phone") {
-    return "voice";
-  }
-  if (sourceChannel === "vellum") {
-    return "desktop";
-  }
-  return "channel";
-}
-
 function getInterfaceFilesWithMtimes(
   interfacesDir: string | null,
 ): Array<{ path: string; mtimeMs: number }> {
@@ -368,11 +364,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 +377,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))) {
-    return httpError("BAD_REQUEST", "limit must be a valid number", 400);
+  if (limitRaw != null && isNaN(Number(limitRaw))) {
+    throw new BadRequestError("limit must be a valid number");
+  }
+  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 +421,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 +591,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 +672,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 ─────────────────────────────────────────────
@@ -973,337 +994,6 @@ function mergeConsecutiveAssistantMessages(messages: MessageRow[]): {
   return { messages: result, mergedIdMap };
 }
 
-/**
- * Build an `onEvent` callback that publishes every outbound event to the
- * assistant event hub, maintaining ordered delivery through a serial chain.
- *
- * Also registers pending interactions when confirmation_request,
- * secret_request, host_bash_request, host_browser_request, host_file_request,
- * or host_cu_request events flow through, so standalone approval/result
- * endpoints can look up the conversation by requestId.
- */
-function makeHubPublisher(
-  deps: SendMessageDeps,
-  conversationId: string,
-  conversation: Conversation,
-): (msg: ServerMessage) => void {
-  let hubChain: Promise<void> = Promise.resolve();
-  return (msg: ServerMessage) => {
-    // Register pending interactions for approval events
-    if (msg.type === "confirmation_request") {
-      pendingInteractions.register(msg.requestId, {
-        conversation,
-        conversationId,
-        kind: "confirmation",
-        confirmationDetails: {
-          toolName: msg.toolName,
-          input: msg.input,
-          riskLevel: msg.riskLevel,
-          executionTarget: msg.executionTarget,
-          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,
-      }).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,
-              });
-            }
-          })
-          .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 {
-        const trustContext = conversation.trustContext;
-        const sourceChannel = trustContext?.sourceChannel ?? "vellum";
-        const inputRecord = msg.input as Record<string, unknown>;
-        const activityRaw =
-          (typeof inputRecord.activity === "string"
-            ? inputRecord.activity
-            : undefined) ??
-          (typeof inputRecord.reason === "string"
-            ? inputRecord.reason
-            : undefined);
-        const canonicalRequest = createCanonicalGuardianRequest({
-          id: msg.requestId,
-          kind: "tool_approval",
-          sourceType: resolveCanonicalRequestSourceType(sourceChannel),
-          sourceChannel,
-          conversationId,
-          requesterExternalUserId: trustContext?.requesterExternalUserId,
-          requesterChatId: trustContext?.requesterChatId,
-          guardianExternalUserId: trustContext?.guardianExternalUserId,
-          guardianPrincipalId: trustContext?.guardianPrincipalId ?? undefined,
-          toolName: msg.toolName,
-          commandPreview:
-            redactSecrets(summarizeToolInput(msg.toolName, inputRecord)) ||
-            undefined,
-          riskLevel: msg.riskLevel,
-          activityText: activityRaw ? redactSecrets(activityRaw) : undefined,
-          executionTarget: msg.executionTarget,
-          status: "pending",
-          requestCode: generateCanonicalRequestCode(),
-          expiresAt: Date.now() + 5 * 60 * 1000,
-        });
-
-        // For trusted-contact conversations, bridge to guardian.question so the
-        // guardian gets notified and can approve via callback/request-code.
-        if (trustContext) {
-          bridgeConfirmationRequestToGuardian({
-            canonicalRequest,
-            trustContext,
-            conversationId,
-            toolName: msg.toolName,
-            assistantId:
-              conversation.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
-          });
-        }
-      } catch (err) {
-        log.debug(
-          { err, requestId: msg.requestId, conversationId },
-          "Failed to create canonical request from hub publisher",
-        );
-      }
-    } else if (msg.type === "secret_request") {
-      pendingInteractions.register(msg.requestId, {
-        conversation,
-        conversationId,
-        kind: "secret",
-      });
-    } else {
-      registerHostProxyPendingInteraction(msg, conversation, conversationId);
-    }
-
-    // ServerMessage is a large union; conversationId exists on most but not all variants.
-    const msgConversationId =
-      "conversationId" in msg &&
-      typeof (msg as { conversationId?: unknown }).conversationId === "string"
-        ? (msg as { conversationId: string }).conversationId
-        : undefined;
-    // `conversation_list_invalidated` is a list-level system event: it
-    // describes no particular conversation and every connected client
-    // should refresh its sidebar. Publish it unscoped so the SSE hub does
-    // not filter it out by the subscriber's `filter.conversationId`.
-    // Other events (including `conversation_title_updated`) stay scoped to
-    // their conversation — unscoped scoped-events would leak foreign
-    // `conversationId` values to native clients' speculative ID-resolution
-    // path. For `conversation_title_updated` we instead enqueue a matching
-    // unscoped `conversation_list_invalidated` below so other clients'
-    // sidebars can refresh and pick up the new title.
-    const resolvedConversationId =
-      msg.type === "conversation_list_invalidated"
-        ? undefined
-        : (msgConversationId ?? conversationId);
-    const event = buildAssistantEvent(
-      DAEMON_INTERNAL_ASSISTANT_ID,
-      msg,
-      resolvedConversationId,
-    );
-    hubChain = (async () => {
-      await hubChain;
-      try {
-        await deps.assistantEventHub.publish(event);
-      } catch (err) {
-        log.warn(
-          { err },
-          "assistant-events hub subscriber threw during POST /messages",
-        );
-      }
-
-      // When the agent loop auto-generates a conversation title, also
-      // broadcast an unscoped `conversation_list_invalidated` so every
-      // connected client's sidebar can refresh and pick up the new title.
-      // Without this, clients viewing other conversations (or a draft)
-      // would never learn that the title for this conversation changed.
-      // The scoped `conversation_title_updated` above still handles the
-      // in-place update for the client currently viewing this conversation.
-      if (msg.type === "conversation_title_updated") {
-        try {
-          await deps.assistantEventHub.publish(
-            buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, {
-              type: "conversation_list_invalidated",
-              reason: "renamed",
-            }),
-          );
-        } catch (err) {
-          log.warn(
-            { err },
-            "Failed to publish conversation_list_invalidated after title update",
-          );
-        }
-      }
-    })();
-  };
-}
-
-/**
- * Register pending interactions for host proxy request envelopes so
- * standalone result endpoints can resolve by requestId.
- *
- * Returns the registered requestId when a host proxy request was registered.
- * Callers that route through non-hub transports (e.g. registry-routed
- * host_browser sends) can use this to clean up the registration if send fails.
- */
-function registerHostProxyPendingInteraction(
-  msg: ServerMessage,
-  conversation: Conversation,
-  conversationId: string,
-): string | undefined {
-  if (msg.type === "host_bash_request") {
-    pendingInteractions.register(msg.requestId, {
-      conversation,
-      conversationId,
-      kind: "host_bash",
-    });
-    return msg.requestId;
-  }
-  if (msg.type === "host_browser_request") {
-    pendingInteractions.register(msg.requestId, {
-      conversation,
-      conversationId,
-      kind: "host_browser",
-    });
-    return msg.requestId;
-  }
-  if (msg.type === "host_file_request") {
-    pendingInteractions.register(msg.requestId, {
-      conversation,
-      conversationId,
-      kind: "host_file",
-    });
-    return msg.requestId;
-  }
-  if (msg.type === "host_cu_request") {
-    pendingInteractions.register(msg.requestId, {
-      conversation,
-      conversationId,
-      kind: "host_cu",
-    });
-    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.
- *
- * 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).
- */
-function resolveHostBrowserSender(
-  conversation: Conversation,
-  conversationId: string,
-  authContext: AuthContext,
-  onEvent: (msg: ServerMessage) => void,
-  sourceInterface: InterfaceId,
-): { sender: (msg: ServerMessage) => void; isRegistryRouted: boolean } {
-  // Check whether the guardian has any active extension connection.
-  const guardianId =
-    conversation.trustContext?.guardianPrincipalId ??
-    authContext.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}`,
-      );
-    }
-  };
-
-  return { sender: registrySender, isRegistryRouted: true };
-}
-
 /**
  * Persist the pre-chat onboarding payload to disk.
  *
@@ -1395,15 +1085,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 +1104,8 @@ export async function handleSendMessage(
     hostUsername?: string;
     clientId?: string;
     clientMessageId?: string;
+    inferenceProfile?: string | null;
+    riskThreshold?: string;
     onboarding?: {
       tools: string[];
       tasks: string[];
@@ -1425,35 +1115,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 +1190,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 +1198,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 +1217,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
@@ -1542,7 +1277,7 @@ export async function handleSendMessage(
     if (!hasMessages(mapping.conversationId)) {
       smDeps.assistantEventHub
         .publish(
-          buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, {
+          buildAssistantEvent({
             type: "conversation_list_invalidated",
             reason: "created",
           }),
@@ -1571,27 +1306,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 +1333,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 +1345,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 +1370,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)",
           );
@@ -1661,95 +1387,13 @@ export async function handleSendMessage(
     conversation.setTrustContext({ trustClass: "guardian", sourceChannel });
   }
 
-  const onEvent = makeHubPublisher(
-    smDeps,
-    mapping.conversationId,
-    conversation,
-  );
   const isInteractive = isInteractiveInterface(sourceInterface);
-  // Only create each host proxy for interfaces that support the matching
-  // capability. macOS supports all four; the chrome-extension interface only
-  // supports host_browser. Non-desktop conversations (CLI, channels, headless)
-  // fall back to local execution.
-  // Set the proxy BEFORE updateClient so updateClient's call to
-  // hostBashProxy.updateSender targets the correct (new) proxy.
-  if (supportsHostProxy(sourceInterface, "host_bash")) {
-    // Reuse the existing proxy if the conversation is actively processing a
-    // host bash request to avoid orphaning in-flight requests.
-    if (!conversation.isProcessing() || !conversation.hostBashProxy) {
-      const proxy = new HostBashProxy(onEvent, (requestId) => {
-        pendingInteractions.resolve(requestId);
-      });
-      conversation.setHostBashProxy(proxy);
-    }
-  } else if (!conversation.isProcessing()) {
-    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,
-    );
-
-  // Stash the registry-routed sender on the conversation so queue-drain
-  // restores (which run outside of conversation-routes.ts and only have
-  // access to `sendToClient`) can preserve it when calling
-  // `restoreBrowserProxyAvailability()`. The override is set when the
-  // sender is registry-routed (regardless of interface) and cleared when
-  // the SSE hub sender is used, so the drain path always restores the
-  // correct transport.
-  if (isRegistryRouted) {
-    conversation.hostBrowserSenderOverride = browserProxySendToClient;
-  } else {
-    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.
-  const shouldProvisionBrowserProxy =
-    supportsHostProxy(sourceInterface, "host_browser") ||
-    (canServiceRegistryBrowser(sourceInterface) && isRegistryRouted);
-  if (shouldProvisionBrowserProxy) {
-    if (!conversation.isProcessing() || !conversation.hostBrowserProxy) {
-      const browserProxy = new HostBrowserProxy(
-        browserProxySendToClient,
-        (requestId) => {
-          pendingInteractions.resolve(requestId);
-        },
-      );
-      conversation.setHostBrowserProxy(browserProxy);
-    }
-  } else if (!conversation.isProcessing()) {
-    conversation.setHostBrowserProxy(undefined);
-  }
-  if (supportsHostProxy(sourceInterface, "host_file")) {
-    if (!conversation.isProcessing() || !conversation.hostFileProxy) {
-      const fileProxy = new HostFileProxy(onEvent, (requestId) => {
-        pendingInteractions.resolve(requestId);
-      });
-      conversation.setHostFileProxy(fileProxy);
-    }
-  } else if (!conversation.isProcessing()) {
-    conversation.setHostFileProxy(undefined);
-  }
+  // Bash/File/Transfer singletons are globally available via isAvailable() —
+  // no per-conversation gating needed. CU is per-conversation (owns step
+  // count, AX tree history, loop detection).
   if (supportsHostProxy(sourceInterface, "host_cu")) {
     if (!conversation.isProcessing() || !conversation.hostCuProxy) {
-      const cuProxy = new HostCuProxy(onEvent, (requestId) => {
-        pendingInteractions.resolve(requestId);
-      });
-      conversation.setHostCuProxy(cuProxy);
+      conversation.setHostCuProxy(new HostCuProxy());
     }
     // Only preactivate CU when the conversation is idle — if the conversation is
     // processing, this message will be queued and preactivation is deferred
@@ -1761,14 +1405,6 @@ export async function handleSendMessage(
     conversation.setHostCuProxy(undefined);
   }
   // Wire sendToClient to the SSE hub so all subsystems can reach the HTTP client.
-  // Called after setHostBashProxy so updateSender targets the current proxy.
-  // When proxies are preserved during an active turn (non-desktop request while
-  // processing), skip updating proxy senders to avoid degrading them. The gate
-  // matches the host_bash capability because the legacy "reject send during
-  // host bash" flow is what this is really protecting.
-  const preservingProxies =
-    conversation.isProcessing() &&
-    !supportsHostProxy(sourceInterface, "host_bash");
   // hasNoClient must remain `!isInteractive` so downstream tool gating
   // (`isToolActiveForContext` for HOST_TOOL_NAMES, `createToolExecutor`'s
   // `isInteractive: !ctx.hasNoClient`) keeps host_bash/host_file/host_cu
@@ -1776,23 +1412,7 @@ export async function handleSendMessage(
   // is non-interactive (no SSE prompter UI) but still has a connected client
   // that can service host_browser_request events; we restore that single
   // proxy explicitly below without relaxing `hasNoClient`.
-  conversation.updateClient(onEvent, !isInteractive, {
-    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)
-  //
-  // The helper bypasses the `hasNoClient` gate so chrome-extension turns can
-  // drive the browser via CDP without leaking host_bash/host_file tool
-  // availability. It reads `hostBrowserSenderOverride` (set above when
-  // registry-routed) and applies the correct sender — including after
-  // queue-drain restores run from conversation-process.ts.
-  if (shouldProvisionBrowserProxy) {
-    conversation.restoreBrowserProxyAvailability?.();
-  }
+  conversation.updateClient(broadcastMessage, !isInteractive);
 
   // ── Canned first-greeting fast path ──
   // On a completely fresh workspace, skip LLM inference for the macOS
@@ -1847,21 +1467,26 @@ 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({
+        broadcastMessage({
           type: "user_message_echo",
           text: rawContent,
           conversationId,
           messageId: persisted.id,
           clientMessageId,
         });
-        onEvent({ type: "assistant_text_delta", text: cannedGreeting });
-        onEvent({ type: "message_complete", conversationId });
+        broadcastMessage({
+          type: "assistant_text_delta",
+          text: cannedGreeting,
+          conversationId,
+        });
+        broadcastMessage({ type: "message_complete", conversationId });
         conversation.processing = false;
         silentlyWithLog(
           conversation.drainQueue(),
@@ -1914,7 +1539,7 @@ export async function handleSendMessage(
       content: content ?? "",
       attachments,
       conversation,
-      onEvent,
+      onEvent: broadcastMessage,
       // Desktop path: disable NL classification to avoid consuming non-decision
       // messages while a tool confirmation is pending. Deterministic code-prefix
       // and callback parsing remain active. Mirrors conversation-process.ts behavior.
@@ -1926,16 +1551,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(
@@ -1950,7 +1572,7 @@ export async function handleSendMessage(
     const enqueueResult = conversation.enqueueMessage(
       content ?? "",
       attachments,
-      onEvent,
+      broadcastMessage,
       requestId,
       undefined, // activeSurfaceId
       undefined, // currentPage
@@ -1967,9 +1589,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,
       );
     }
 
@@ -1987,10 +1610,7 @@ export async function handleSendMessage(
         for (const interaction of pendingInteractions.getByConversation(
           mapping.conversationId,
         )) {
-          if (
-            interaction.conversation === conversation &&
-            interaction.kind === "confirmation"
-          ) {
+          if (interaction.kind === "confirmation") {
             conversation.emitConfirmationStateChanged({
               conversationId: mapping.conversationId,
               requestId: interaction.requestId,
@@ -2005,7 +1625,7 @@ export async function handleSendMessage(
           }
         }
         conversation.denyAllPendingConfirmations();
-        pendingInteractions.removeByConversation(conversation);
+        pendingInteractions.removeByConversation(mapping.conversationId);
       }
 
       // Expire any orphaned canonical requests that survived without a
@@ -2018,10 +1638,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
@@ -2033,10 +1654,7 @@ export async function handleSendMessage(
     for (const interaction of pendingInteractions.getByConversation(
       mapping.conversationId,
     )) {
-      if (
-        interaction.conversation === conversation &&
-        interaction.kind === "confirmation"
-      ) {
+      if (interaction.kind === "confirmation") {
         conversation.emitConfirmationStateChanged({
           conversationId: mapping.conversationId,
           requestId: interaction.requestId,
@@ -2051,7 +1669,7 @@ export async function handleSendMessage(
       }
     }
     conversation.denyAllPendingConfirmations();
-    pendingInteractions.removeByConversation(conversation);
+    pendingInteractions.removeByConversation(mapping.conversationId);
   }
 
   // Expire any orphaned canonical requests that survived without a
@@ -2072,17 +1690,14 @@ export async function handleSendMessage(
 
   // Resolve slash commands before persisting or running the agent loop.
   const rawContent = content ?? "";
-  const config = getConfig();
-  const slashContext: SlashContext = {
+  const slashContext = buildSlashContextForContent(rawContent, {
+    conversationId: mapping.conversationId,
     messageCount: conversation.getMessages().length,
     inputTokens: conversation.usageStats.inputTokens,
     outputTokens: conversation.usageStats.outputTokens,
-    maxInputTokens: config.llm.default.contextWindow.maxInputTokens,
-    model: config.llm.default.model,
-    provider: config.llm.default.provider,
     estimatedCost: conversation.usageStats.estimatedCost,
     userMessageInterface: sourceInterface,
-  };
+  });
   const slashResult = await resolveSlash(rawContent, slashContext);
 
   if (slashResult.kind === "unknown") {
@@ -2139,17 +1754,14 @@ export async function handleSendMessage(
       // Snapshot model info now so the deferred callback cannot observe
       // a config change from a concurrent request.
       const modelInfoEvent = isModelSlashCommand(rawContent)
-        ? await buildModelInfoEvent()
+        ? await buildModelInfoEvent(mapping.conversationId)
         : 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
@@ -2162,7 +1774,7 @@ export async function handleSendMessage(
       const conversationId = mapping.conversationId;
       const message = slashResult.message;
       setTimeout(() => {
-        onEvent({
+        broadcastMessage({
           type: "user_message_echo",
           text: rawContent,
           conversationId,
@@ -2170,10 +1782,14 @@ export async function handleSendMessage(
           clientMessageId,
         });
         if (modelInfoEvent) {
-          onEvent(modelInfoEvent);
+          broadcastMessage(modelInfoEvent);
         }
-        onEvent({ type: "assistant_text_delta", text: message });
-        onEvent({
+        broadcastMessage({
+          type: "assistant_text_delta",
+          text: message,
+          conversationId,
+        });
+        broadcastMessage({
           type: "message_complete",
           conversationId: conversationId,
         });
@@ -2219,7 +1835,7 @@ export async function handleSendMessage(
     // HTTP timeout on large contexts, causing a false "Failed to send".
     (async () => {
       try {
-        onEvent({
+        broadcastMessage({
           type: "user_message_echo",
           text: rawContent,
           conversationId,
@@ -2243,11 +1859,15 @@ export async function handleSendMessage(
         );
         conversation.getMessages().push(assistantMsg);
 
-        onEvent({ type: "assistant_text_delta", text: responseText });
-        onEvent({ type: "message_complete", conversationId });
+        broadcastMessage({
+          type: "assistant_text_delta",
+          text: responseText,
+          conversationId,
+        });
+        broadcastMessage({ type: "message_complete", conversationId });
       } catch (err) {
         log.error({ err, conversationId }, "Compact command failed");
-        onEvent({
+        broadcastMessage({
           type: "conversation_error",
           conversationId,
           code: "UNKNOWN",
@@ -2263,14 +1883,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;
@@ -2288,7 +1905,7 @@ export async function handleSendMessage(
     throw err;
   }
 
-  onEvent({
+  broadcastMessage({
     type: "user_message_echo",
     text: resolvedContent,
     conversationId: mapping.conversationId,
@@ -2297,9 +1914,9 @@ export async function handleSendMessage(
     clientMessageId,
   });
 
-  // Fire-and-forget the agent loop; events flow to the hub via onEvent.
+  // Fire-and-forget the agent loop; events flow to the hub via broadcastMessage.
   conversation
-    .runAgentLoop(resolvedContent, messageId, onEvent, {
+    .runAgentLoop(resolvedContent, messageId, broadcastMessage, {
       isInteractive,
       isUserMessage: true,
     })
@@ -2310,10 +1927,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 +2018,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 +2078,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 +2128,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 +2148,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 +2160,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 +2181,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,
-        }),
-    },
-  ];
-}
+  },
+];