@vellumai/assistant 0.6.6 → 0.7.0

package/src/runtime/http-server.ts

@@ -5,15 +5,6 @@
  * configured port (default: 7821).
  */
 
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import { dirname, resolve } from "node:path";
 
 import type { ServerWebSocket } from "bun";
 
@@ -35,75 +26,40 @@ import {
   handleStatusCallback,
   handleVoiceWebhook,
 } from "../calls/twilio-routes.js";
-import { parseChannelId } from "../channels/types.js";
-import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import {
-  getGatewayInternalBaseUrl,
   hasUngatedHttpAuthDisabled,
   isHttpAuthDisabled,
 } from "../config/env.js";
 import { getConfig } from "../config/loader.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
-import { PairingStore } from "../daemon/pairing-store.js";
-import {
-  type AttentionState,
-  type Confidence,
-  getAttentionStateByConversationIds,
-  markConversationUnread,
-  recordConversationSeenSignal,
-  type SignalType,
-} from "../memory/conversation-attention-store.js";
-import {
-  addMessage,
-  type ConversationRow,
-  createConversation,
-  deleteConversation,
-  forkConversation as forkConversationInStore,
-  getConversation,
-  getDisplayMetaForConversations,
-} from "../memory/conversation-crud.js";
-import { resolveConversationId } from "../memory/conversation-key-store.js";
+import { processMessage } from "../daemon/process-message.js";
+import { createLiveVoiceSession } from "../live-voice/live-voice-session.js";
+import { LiveVoiceSessionManager } from "../live-voice/live-voice-session-manager.js";
 import {
-  countConversations,
-  listConversations,
-  listConversationsByTitlePrefix,
-  listPinnedConversations,
-} from "../memory/conversation-queries.js";
-import type { ExternalConversationBinding } from "../memory/external-conversation-store.js";
-import * as externalConversationStore from "../memory/external-conversation-store.js";
-import { listGroups } from "../memory/group-crud.js";
-import { enqueueMemoryJob } from "../memory/jobs-store.js";
+  type LiveVoiceClientFrame,
+  type LiveVoiceProtocolError,
+  LiveVoiceProtocolErrorCode,
+  type LiveVoiceServerFrame,
+  parseLiveVoiceBinaryAudioFrame,
+  parseLiveVoiceClientTextFrame,
+} from "../live-voice/protocol.js";
 import { resolveStreamingTranscriber } from "../providers/speech-to-text/resolve.js";
-import {
-  consumeCallback,
-  consumeCallbackError,
-} from "../security/oauth-callback-registry.js";
 import {
   activeSttStreamSessions,
   SttStreamSession,
 } from "../stt/stt-stream-session.js";
-import { UserError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
-import { getRuntimePortFilePath } from "../util/platform.js";
-import { buildAssistantEvent } from "./assistant-event.js";
-import { assistantEventHub } from "./assistant-event-hub.js";
-import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
 // Auth
 import {
   authenticateHostBrowserResultRequest,
   authenticateRequest,
 } from "./auth/middleware.js";
 import { parseSub } from "./auth/subject.js";
-import {
-  mintDaemonDeliveryToken,
-  mintUiPageToken,
-  verifyToken,
-} from "./auth/token-service.js";
+import { verifyToken } from "./auth/token-service.js";
 import { verifyHostBrowserCapability } from "./capability-tokens.js";
 import { sweepFailedEvents } from "./channel-retry-sweep.js";
 import { getChromeExtensionRegistry } from "./chrome-extension-registry.js";
-import { httpError } from "./http-errors.js";
-import type { RouteDefinition } from "./http-router.js";
+import { httpError, type HttpErrorCode } from "./http-errors.js";
+import type { HTTPRouteDefinition } from "./http-router.js";
 import { HttpRouter } from "./http-router.js";
 // Middleware
 import {
@@ -129,111 +85,25 @@ import {
   TWILIO_WEBHOOK_RE,
   validateTwilioWebhook,
 } from "./middleware/twilio-validation.js";
-import { acpRouteDefinitions } from "./routes/acp-routes.js";
-import { appManagementRouteDefinitions } from "./routes/app-management-routes.js";
-import { handleServePage } from "./routes/app-routes.js";
-import { appRouteDefinitions } from "./routes/app-routes.js";
-import { approvalRouteDefinitions } from "./routes/approval-routes.js";
-import { attachmentRouteDefinitions } from "./routes/attachment-routes.js";
-import { handleGetAudio } from "./routes/audio-routes.js";
-import { avatarRouteDefinitions } from "./routes/avatar-routes.js";
-import { backupRouteDefinitions } from "./routes/backup-routes.js";
-import { brainGraphRouteDefinitions } from "./routes/brain-graph-routes.js";
-import { handleBrowserExtensionPair } from "./routes/browser-extension-pair-routes.js";
-import { btwRouteDefinitions } from "./routes/btw-routes.js";
-import { callRouteDefinitions } from "./routes/call-routes.js";
+import { ROUTES as APP_ROUTES } from "./routes/app-routes.js";
+import { ROUTES as AUDIO_ROUTES } from "./routes/audio-routes.js";
 import {
   startCanonicalGuardianExpirySweep,
   stopCanonicalGuardianExpirySweep,
 } from "./routes/canonical-guardian-expiry-sweep.js";
-import { channelReadinessRouteDefinitions } from "./routes/channel-readiness-routes.js";
 import {
-  channelRouteDefinitions,
   startGuardianExpirySweep,
   stopGuardianExpirySweep,
-} from "./routes/channel-routes.js";
-import { channelVerificationRouteDefinitions } from "./routes/channel-verification-routes.js";
+} from "./routes/channel-guardian-routes.js";
+import { RouteError } from "./routes/errors.js";
 import {
-  contactCatchAllRouteDefinitions,
-  contactRouteDefinitions,
-} from "./routes/contact-routes.js";
-import { conversationAnalysisRouteDefinitions } from "./routes/conversation-analysis-routes.js";
-import { conversationAttentionRouteDefinitions } from "./routes/conversation-attention-routes.js";
-import {
-  type ConversationManagementDeps,
-  conversationManagementRouteDefinitions,
-} from "./routes/conversation-management-routes.js";
-import { conversationQueryRouteDefinitions } from "./routes/conversation-query-routes.js";
-import { conversationRouteDefinitions } from "./routes/conversation-routes.js";
-import { conversationStarterRouteDefinitions } from "./routes/conversation-starter-routes.js";
-import { debugRouteDefinitions } from "./routes/debug-routes.js";
-import { diagnosticsRouteDefinitions } from "./routes/diagnostics-routes.js";
-import { documentRouteDefinitions } from "./routes/documents-routes.js";
-import { eventsRouteDefinitions } from "./routes/events-routes.js";
-import { filingRouteDefinitions } from "./routes/filing-routes.js";
-import { globalSearchRouteDefinitions } from "./routes/global-search-routes.js";
-import { groupRouteDefinitions } from "./routes/group-routes.js";
-import { guardianActionRouteDefinitions } from "./routes/guardian-action-routes.js";
-import { handleGuardianBootstrap } from "./routes/guardian-bootstrap-routes.js";
-import { handleGuardianRefresh } from "./routes/guardian-refresh-routes.js";
-import { heartbeatRouteDefinitions } from "./routes/heartbeat-routes.js";
-import { homeFeedRouteDefinitions } from "./routes/home-feed-routes.js";
-import { homeStateRouteDefinitions } from "./routes/home-state-routes.js";
-import { hostBashRouteDefinitions } from "./routes/host-bash-routes.js";
-import {
-  hostBrowserRouteDefinitions,
   resolveHostBrowserEvent,
   resolveHostBrowserResultByRequestId,
   resolveHostBrowserSessionInvalidated,
 } from "./routes/host-browser-routes.js";
-import { hostCuRouteDefinitions } from "./routes/host-cu-routes.js";
-import { hostFileRouteDefinitions } from "./routes/host-file-routes.js";
-import {
-  handleHealth,
-  handleReadyz,
-  identityRouteDefinitions,
-} from "./routes/identity-routes.js";
-import { slackChannelRouteDefinitions } from "./routes/integrations/slack/channel.js";
-import { slackShareRouteDefinitions } from "./routes/integrations/slack/share.js";
-import { telegramRouteDefinitions } from "./routes/integrations/telegram.js";
-import { twilioRouteDefinitions } from "./routes/integrations/twilio.js";
-import { vercelRouteDefinitions } from "./routes/integrations/vercel.js";
-import { inviteRouteDefinitions } from "./routes/invite-routes.js";
-import { logExportRouteDefinitions } from "./routes/log-export-routes.js";
-import { memoryItemRouteDefinitions } from "./routes/memory-item-routes.js";
-import { migrationRollbackRouteDefinitions } from "./routes/migration-rollback-routes.js";
-import { migrationRouteDefinitions } from "./routes/migration-routes.js";
-import { notificationRouteDefinitions } from "./routes/notification-routes.js";
-import { oauthAppsRouteDefinitions } from "./routes/oauth-apps.js";
-import { oauthProvidersRouteDefinitions } from "./routes/oauth-providers.js";
-import type { PairingHandlerContext } from "./routes/pairing-routes.js";
-import {
-  handlePairingRequest,
-  handlePairingStatus,
-  pairingRouteDefinitions,
-} from "./routes/pairing-routes.js";
-import { playgroundRouteDefinitions } from "./routes/playground/index.js";
-import { profilerRouteDefinitions } from "./routes/profiler-routes.js";
-import { recordingRouteDefinitions } from "./routes/recording-routes.js";
-import { scheduleRouteDefinitions } from "./routes/schedule-routes.js";
-import { secretRouteDefinitions } from "./routes/secret-routes.js";
-import { settingsRouteDefinitions } from "./routes/settings-routes.js";
-import { skillRouteDefinitions } from "./routes/skills-routes.js";
-import { sttRouteDefinitions } from "./routes/stt-routes.js";
-import { subagentRouteDefinitions } from "./routes/subagents-routes.js";
-import { surfaceActionRouteDefinitions } from "./routes/surface-action-routes.js";
-import { surfaceContentRouteDefinitions } from "./routes/surface-content-routes.js";
-import { telemetryRouteDefinitions } from "./routes/telemetry-routes.js";
-import { traceEventRouteDefinitions } from "./routes/trace-event-routes.js";
-import { trustRulesRouteDefinitions } from "./routes/trust-rules-routes.js";
-import { ttsRouteDefinitions } from "./routes/tts-routes.js";
-import { upgradeBroadcastRouteDefinitions } from "./routes/upgrade-broadcast-routes.js";
-import { usageRouteDefinitions } from "./routes/usage-routes.js";
-import { userRouteDefinitions } from "./routes/user-routes.js";
-import { workItemRouteDefinitions } from "./routes/work-items-routes.js";
-import { workspaceCommitRouteDefinitions } from "./routes/workspace-commit-routes.js";
-import { workspaceRouteDefinitions } from "./routes/workspace-routes.js";
-import { setAnalysisDeps } from "./services/analyze-deps-singleton.js";
+import { routeDefinitionsToHTTPRoutes } from "./routes/http-adapter.js";
+import { handleHealth, handleReadyz } from "./routes/identity-routes.js";
+import { ROUTES } from "./routes/index.js";
 import { matchSkillRoute } from "./skill-route-registry.js";
 
 // Re-export for consumers
@@ -249,7 +119,6 @@ export type {
   RuntimeAttachmentMetadata,
   RuntimeHttpServerOptions,
   RuntimeMessageConversationOptions,
-  SendMessageDeps,
 } from "./http-types.js";
 
 import type {
@@ -257,9 +126,7 @@ import type {
   ApprovalCopyGenerator,
   GuardianActionCopyGenerator,
   GuardianFollowUpConversationGenerator,
-  MessageProcessor,
   RuntimeHttpServerOptions,
-  SendMessageDeps,
 } from "./http-types.js";
 
 const log = getLogger("runtime-http");
@@ -338,59 +205,44 @@ interface SttStreamWebSocketData {
   session?: SttStreamSession;
 }
 
+/**
+ * WebSocket data attached to `/v1/live-voice` connections. The `wsType`
+ * discriminator routes frames to the live voice protocol shell instead of
+ * the other WebSocket handlers.
+ */
+interface LiveVoiceWebSocketData {
+  wsType: "live-voice";
+  sessionId?: string;
+  lastSeq: number;
+}
+
 export class RuntimeHttpServer {
   private server: ReturnType<typeof Bun.serve> | null = null;
   private port: number;
   private hostname: string;
-  /** Legacy shared secret for pairing routes (not used for delivery or auth). */
-  private bearerToken: string | undefined;
-  private processMessage?: MessageProcessor;
+
   private approvalCopyGenerator?: ApprovalCopyGenerator;
   private approvalConversationGenerator?: ApprovalConversationGenerator;
   private guardianActionCopyGenerator?: GuardianActionCopyGenerator;
   private guardianFollowUpConversationGenerator?: GuardianFollowUpConversationGenerator;
-  private interfacesDir: string | null;
-  private suggestionCache = new Map<string, string>();
-  private suggestionInFlight = new Map<string, Promise<string | null>>();
   private retrySweepTimer: ReturnType<typeof setInterval> | null = null;
   private sweepInProgress = false;
-  private pairingStore = new PairingStore();
-  private pairingBroadcast?: (msg: ServerMessage) => void;
-  private sendMessageDeps?: SendMessageDeps;
-  private findConversation?: RuntimeHttpServerOptions["findConversation"];
-  private findConversationBySurfaceId?: RuntimeHttpServerOptions["findConversationBySurfaceId"];
-  private getSkillContext?: RuntimeHttpServerOptions["getSkillContext"];
-  private conversationManagementDeps?: RuntimeHttpServerOptions["conversationManagementDeps"];
-  private getModelSetContext?: RuntimeHttpServerOptions["getModelSetContext"];
-  private getRecordingDeps?: RuntimeHttpServerOptions["getRecordingDeps"];
-  private getCesClient?: RuntimeHttpServerOptions["getCesClient"];
-  private onProviderCredentialsChanged?: RuntimeHttpServerOptions["onProviderCredentialsChanged"];
-  private getHeartbeatService?: RuntimeHttpServerOptions["getHeartbeatService"];
-  private getFilingService?: RuntimeHttpServerOptions["getFilingService"];
+
+  private readonly liveVoiceSessionManager: LiveVoiceSessionManager;
   private router: HttpRouter;
 
   constructor(options: RuntimeHttpServerOptions = {}) {
     this.port = options.port ?? DEFAULT_PORT;
     this.hostname = options.hostname ?? DEFAULT_HOSTNAME;
-    this.bearerToken = options.bearerToken;
-    this.processMessage = options.processMessage;
+
     this.approvalCopyGenerator = options.approvalCopyGenerator;
     this.approvalConversationGenerator = options.approvalConversationGenerator;
     this.guardianActionCopyGenerator = options.guardianActionCopyGenerator;
     this.guardianFollowUpConversationGenerator =
       options.guardianFollowUpConversationGenerator;
-    this.interfacesDir = options.interfacesDir ?? null;
-    this.sendMessageDeps = options.sendMessageDeps;
-    this.findConversation = options.findConversation;
-    this.findConversationBySurfaceId = options.findConversationBySurfaceId;
-    this.getSkillContext = options.getSkillContext;
-    this.conversationManagementDeps = options.conversationManagementDeps;
-    this.getModelSetContext = options.getModelSetContext;
-    this.getRecordingDeps = options.getRecordingDeps;
-    this.getCesClient = options.getCesClient;
-    this.onProviderCredentialsChanged = options.onProviderCredentialsChanged;
-    this.getHeartbeatService = options.getHeartbeatService;
-    this.getFilingService = options.getFilingService;
+    this.liveVoiceSessionManager = new LiveVoiceSessionManager({
+      createSession: (context) => createLiveVoiceSession(context),
+    });
     this.router = new HttpRouter(this.buildRouteTable());
   }
 
@@ -399,40 +251,13 @@ export class RuntimeHttpServer {
     return this.server?.port ?? this.port;
   }
 
-  /** Expose the pairing store so the daemon server can wire HTTP handlers. */
-  getPairingStore(): PairingStore {
-    return this.pairingStore;
-  }
-
-  /** Set a callback for broadcasting server messages (wired by daemon server). */
-  setPairingBroadcast(fn: (msg: ServerMessage) => void): void {
-    this.pairingBroadcast = fn;
-  }
-
-  private get pairingContext(): PairingHandlerContext {
-    const broadcast = this.pairingBroadcast;
-    return {
-      pairingStore: this.pairingStore,
-      bearerToken: this.bearerToken,
-      pairingBroadcast: broadcast
-        ? (msg) => {
-            // Broadcast to all clients via the event hub so HTTP/SSE clients
-            // (e.g. macOS app) receive pairing approval requests.
-            broadcast(msg);
-            void assistantEventHub.publish(
-              buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, msg),
-            );
-          }
-        : undefined,
-    };
-  }
-
   async start(): Promise<void> {
     type AllWebSocketData =
       | RelayWebSocketData
       | BrowserRelayWebSocketData
       | MediaStreamWebSocketData
-      | SttStreamWebSocketData;
+      | SttStreamWebSocketData
+      | LiveVoiceWebSocketData;
     this.server = Bun.serve<AllWebSocketData>({
       port: this.port,
       hostname: this.hostname,
@@ -440,7 +265,7 @@ export class RuntimeHttpServer {
       maxRequestBodySize: MAX_REQUEST_BODY_BYTES,
       fetch: (req, server) => this.handleRequest(req, server),
       websocket: {
-        open(ws) {
+        open: (ws) => {
           const data = ws.data as AllWebSocketData;
           if ("wsType" in data && data.wsType === "browser-relay") {
             // When the JWT sub resolved to a guardian principal at upgrade
@@ -547,6 +372,10 @@ export class RuntimeHttpServer {
             );
             return;
           }
+          if ("wsType" in data && data.wsType === "live-voice") {
+            log.info("Live voice WebSocket opened");
+            return;
+          }
           const callSessionId = (data as RelayWebSocketData).callSessionId;
           log.info({ callSessionId }, "ConversationRelay WebSocket opened");
           if (callSessionId) {
@@ -557,7 +386,7 @@ export class RuntimeHttpServer {
             activeRelayConnections.set(callSessionId, connection);
           }
         },
-        message(ws, message) {
+        message: (ws, message) => {
           const data = ws.data as AllWebSocketData;
           const raw =
             typeof message === "string"
@@ -708,13 +537,32 @@ export class RuntimeHttpServer {
             }
             return;
           }
+          if ("wsType" in data && data.wsType === "live-voice") {
+            void this.handleLiveVoiceMessage(
+              ws as ServerWebSocket<LiveVoiceWebSocketData>,
+              message,
+            ).catch((err) => {
+              log.warn(
+                { error: err instanceof Error ? err.message : String(err) },
+                "Live voice WebSocket message handler failed",
+              );
+              this.sendLiveVoiceError(
+                ws as ServerWebSocket<LiveVoiceWebSocketData>,
+                {
+                  code: LiveVoiceProtocolErrorCode.InvalidFrame,
+                  message: "Live voice frame handling failed",
+                },
+              );
+            });
+            return;
+          }
           const callSessionId = (data as RelayWebSocketData).callSessionId;
           if (callSessionId) {
             const connection = activeRelayConnections.get(callSessionId);
             connection?.handleMessage(raw);
           }
         },
-        close(ws, code, reason) {
+        close: (ws, code, reason) => {
           const data = ws.data as AllWebSocketData;
           if ("wsType" in data && data.wsType === "browser-relay") {
             // Always attempt to unregister — the registry uses connectionId
@@ -775,6 +623,18 @@ export class RuntimeHttpServer {
             }
             return;
           }
+          if ("wsType" in data && data.wsType === "live-voice") {
+            log.info(
+              {
+                sessionId: data.sessionId,
+                code,
+                reason: reason?.toString(),
+              },
+              "Live voice WebSocket closed",
+            );
+            this.releaseLiveVoiceSession(data, "websocket_close");
+            return;
+          }
           const callSessionId = (data as RelayWebSocketData).callSessionId;
           log.info(
             { callSessionId, code, reason: reason?.toString() },
@@ -801,8 +661,6 @@ export class RuntimeHttpServer {
       );
     }
 
-    this.pairingStore.start();
-
     if (hasUngatedHttpAuthDisabled()) {
       log.warn(
         "DISABLE_HTTP_AUTH is set but VELLUM_UNSAFE_AUTH_BYPASS=1 is not — auth bypass is IGNORED and HTTP authentication remains enabled. Set VELLUM_UNSAFE_AUTH_BYPASS=1 to confirm the bypass.",
@@ -817,15 +675,9 @@ export class RuntimeHttpServer {
       {
         port: this.actualPort,
         hostname: this.hostname,
-        auth: !!this.bearerToken,
       },
       "Runtime HTTP server listening",
     );
-
-    // Advertise the actual port to thin helpers that need to reach the
-    // runtime without inheriting the daemon's environment (e.g. the
-    // chrome-extension native messaging helper, spawned by Chrome).
-    this.writeRuntimePortFile(this.actualPort);
   }
 
   /**
@@ -834,108 +686,27 @@ export class RuntimeHttpServer {
    * Extracted from start() to allow future callers to defer sweep startup.
    */
   private startBackgroundSweeps(): void {
-    if (this.processMessage && !this.retrySweepTimer) {
-      const pm = this.processMessage;
-      const mintBt = () => mintDaemonDeliveryToken();
+    if (!this.retrySweepTimer) {
       this.retrySweepTimer = setInterval(() => {
         if (this.sweepInProgress) return;
         this.sweepInProgress = true;
-        sweepFailedEvents(pm, mintBt).finally(() => {
+        sweepFailedEvents(processMessage).finally(() => {
           this.sweepInProgress = false;
         });
       }, 30_000);
     }
 
-    startGuardianExpirySweep(
-      getGatewayInternalBaseUrl(),
-      () => mintDaemonDeliveryToken(),
-      this.approvalCopyGenerator,
-    );
+    startGuardianExpirySweep(this.approvalCopyGenerator);
     log.info("Guardian approval expiry sweep started");
 
-    startGuardianActionSweep(
-      getGatewayInternalBaseUrl(),
-      () => mintDaemonDeliveryToken(),
-      this.guardianActionCopyGenerator,
-    );
+    startGuardianActionSweep(this.guardianActionCopyGenerator);
     log.info("Guardian action expiry sweep started");
 
     startCanonicalGuardianExpirySweep();
     log.info("Canonical guardian request expiry sweep started");
   }
 
-  /**
-   * Atomically publish the runtime HTTP port to ~/.vellum/runtime-port so
-   * external helpers can locate a non-default `RUNTIME_HTTP_PORT` without
-   * any manifest changes. Best-effort — write failures never block
-   * daemon startup (see assistant/AGENTS.md "Daemon startup philosophy").
-   */
-  private writeRuntimePortFile(actualPort: number): void {
-    try {
-      const portFile = getRuntimePortFilePath();
-      const dir = dirname(portFile);
-      if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-      }
-      const tmpPath = `${portFile}.tmp.${process.pid}`;
-      writeFileSync(tmpPath, String(actualPort), { mode: 0o644 });
-      renameSync(tmpPath, portFile);
-      log.info({ portFile, actualPort }, "Wrote runtime port file");
-    } catch (err) {
-      log.warn(
-        { err },
-        "Failed to write runtime port file; non-default assistant ports may require --assistant-port on thin helpers",
-      );
-    }
-  }
-
-  /**
-   * Remove the runtime port file written by `writeRuntimePortFile`.
-   * Called from `stop()` on clean shutdown so a stale file does not
-   * point thin helpers (e.g. the chrome-extension native messaging
-   * helper) at a dead port until the next daemon start overwrites it.
-   * Best-effort — unlink failures never block shutdown.
-   *
-   * The unlink is conditional: we only remove the file if its current
-   * contents still match this server's port. The runtime-port file
-   * lives at the user-home level (`~/.vellum/runtime-port`) and is
-   * therefore shared across multiple daemon instances running on
-   * different `RUNTIME_HTTP_PORT`s. If a sibling instance has already
-   * rewritten the file with its own port, deleting it would strand
-   * thin helpers on the default port `7821` and break their ability
-   * to reach the still-running sibling.
-   *
-   * Note: this only runs on graceful shutdown. A crash leaves the
-   * file in place; the next successful startup overwrites it.
-   */
-  private removeRuntimePortFile(): void {
-    try {
-      const portFile = getRuntimePortFilePath();
-      if (!existsSync(portFile)) return;
-      // Read-then-compare-then-unlink. Race-safe enough: the worst case
-      // is that another instance writes the file between our read and
-      // our unlink, in which case we erroneously delete its mapping.
-      // That window is short (a few microseconds) and a sibling startup
-      // will rewrite the file on its next port-publish call. The much
-      // more common multi-instance race — sibling already overwrote
-      // before our stop() runs — is correctly handled here as a no-op.
-      const current = readFileSync(portFile, "utf-8").trim();
-      if (current !== String(this.actualPort)) {
-        log.info(
-          { portFile, current, actualPort: this.actualPort },
-          "Leaving runtime port file alone — owned by another instance",
-        );
-        return;
-      }
-      unlinkSync(portFile);
-      log.info({ portFile }, "Removed runtime port file");
-    } catch (err) {
-      log.warn({ err }, "Failed to remove runtime port file");
-    }
-  }
-
   async stop(): Promise<void> {
-    this.pairingStore.stop();
     stopGuardianExpirySweep();
     stopGuardianActionSweep();
     stopCanonicalGuardianExpirySweep();
@@ -952,12 +723,19 @@ export class RuntimeHttpServer {
       activeSttStreamSessions.delete(sessionId);
     }
 
+    const liveVoiceSessionId = this.liveVoiceSessionManager.activeSessionId;
+    if (liveVoiceSessionId) {
+      await this.liveVoiceSessionManager.releaseSession(
+        liveVoiceSessionId,
+        "manager_shutdown",
+      );
+    }
+
     if (this.server) {
       this.server.stop(true);
       this.server = null;
       log.info("Runtime HTTP server stopped");
     }
-    this.removeRuntimePortFile();
   }
 
   private async handleRequest(
@@ -1026,43 +804,48 @@ export class RuntimeHttpServer {
       return this.handleSttStreamUpgrade(req, server);
     }
 
+    // WebSocket upgrade for live voice — same private-network restrictions
+    // and gateway-service token verification as STT streaming.
+    if (
+      path === "/v1/live-voice" &&
+      req.headers.get("upgrade")?.toLowerCase() === "websocket"
+    ) {
+      return this.handleLiveVoiceUpgrade(req, server);
+    }
+
     // Twilio webhook endpoints — before auth check because Twilio
     // webhook POSTs don't include bearer tokens.
     const twilioResponse = await this.handleTwilioWebhook(req, path);
     if (twilioResponse) return twilioResponse;
 
     // Audio serving endpoint — before auth check because Twilio
-    // fetches these URLs directly. The audioId is an unguessable UUID.
+    // fetches these URLs directly (isPublic route, ATL-314).
     const audioMatch = path.match(/^\/v1\/audio\/([^/]+)$/);
     if (audioMatch && req.method === "GET") {
-      return handleGetAudio(audioMatch[1]);
-    }
-
-    // Pairing endpoints (unauthenticated, secret-gated)
-    if (path === "/v1/pairing/request" && req.method === "POST") {
-      return await handlePairingRequest(req, this.pairingContext);
-    }
-    if (path === "/v1/pairing/status" && req.method === "GET") {
-      return handlePairingStatus(url, this.pairingContext);
-    }
-
-    // Chrome extension capability-token pair endpoint — unauthenticated but
-    // restricted to loopback peers + an extension-id allowlist. Used by the
-    // native messaging helper to bootstrap a scoped token.
-    if (path === "/v1/browser-extension-pair") {
-      return await handleBrowserExtensionPair(req, server);
-    }
-
-    // Guardian bootstrap and refresh endpoints — before JWT auth because
-    // bootstrap is the first endpoint called to obtain a JWT, and refresh
-    // needs to work when the access token is expired. Bootstrap has its
-    // own loopback IP validation; refresh is secured by the refresh token
-    // in the request body (32 random bytes, hash-only storage).
-    if (path === "/v1/guardian/init" && req.method === "POST") {
-      return await handleGuardianBootstrap(req, server);
-    }
-    if (path === "/v1/guardian/refresh" && req.method === "POST") {
-      return await handleGuardianRefresh(req);
+      const audioDef = AUDIO_ROUTES.find((r) => r.operationId === "audio_get")!;
+      const args = { pathParams: { audioId: audioMatch[1] } };
+      try {
+        const result = await audioDef.handler(args);
+        const headers =
+          typeof audioDef.responseHeaders === "function"
+            ? audioDef.responseHeaders(args)
+            : audioDef.responseHeaders;
+        if (result instanceof ReadableStream) {
+          return new Response(result as ReadableStream<Uint8Array>, {
+            headers,
+          });
+        }
+        return new Response(result as BodyInit, { headers });
+      } catch (err) {
+        if (err instanceof RouteError) {
+          return httpError(
+            err.code as HttpErrorCode,
+            err.message,
+            err.statusCode,
+          );
+        }
+        throw err;
+      }
     }
 
     // Skill-registered routes (e.g. meet-bot event ingress). Handled before
@@ -1092,7 +875,7 @@ export class RuntimeHttpServer {
     const normalizedPath = path.endsWith("/") ? path.slice(0, -1) : path;
     const authResult =
       normalizedPath === "/v1/host-browser-result" && req.method === "POST"
-        ? authenticateHostBrowserResultRequest(req)
+        ? await authenticateHostBrowserResultRequest(req)
         : authenticateRequest(req);
     if (!authResult.ok) {
       return authResult.response;
@@ -1102,9 +885,18 @@ export class RuntimeHttpServer {
     // Serve shareable app pages (outside /v1/ namespace, no rate limiting)
     const pagesMatch = path.match(/^\/pages\/([^/]+)$/);
     if (pagesMatch && req.method === "GET") {
-      return withErrorHandling("pages", async () =>
-        handleServePage(pagesMatch[1]),
-      );
+      return withErrorHandling("pages", async () => {
+        const pageDef = APP_ROUTES.find(
+          (r) => r.operationId === "pages_serve",
+        )!;
+        const args = { pathParams: { appId: pagesMatch[1] } };
+        const body = pageDef.handler(args) as string;
+        const headers =
+          typeof pageDef.responseHeaders === "function"
+            ? pageDef.responseHeaders(args)
+            : pageDef.responseHeaders;
+        return new Response(body, { headers });
+      });
     }
 
     // Per-client-IP rate limiting for /v1/* endpoints. Authenticated requests
@@ -1166,10 +958,10 @@ export class RuntimeHttpServer {
     return routerResponse ?? httpError("NOT_FOUND", "Not found", 404);
   }
 
-  private handleBrowserRelayUpgrade(
+  private async handleBrowserRelayUpgrade(
     req: Request,
     server: ReturnType<typeof Bun.serve>,
-  ): Response {
+  ): Promise<Response> {
     if (
       !isLoopbackHost(new URL(req.url).hostname) &&
       !isPrivateNetworkPeer(server, req)
@@ -1185,8 +977,8 @@ export class RuntimeHttpServer {
     // `/v1/browser-relay` handshake:
     //
     //   1. **Capability token** — a signed `host_browser_command`
-    //      capability minted by `mintHostBrowserCapability()` and handed
-    //      to the chrome extension by the native-messaging pair flow
+    //      capability minted by the gateway and handed to the chrome
+    //      extension by the native-messaging pair flow
     //      (`/v1/browser-extension-pair`). This is the preferred,
     //      self-hosted default: the extension never has to touch a
     //      gateway JWT.
@@ -1235,7 +1027,7 @@ export class RuntimeHttpServer {
       //    messaging pair flow. We derive `guardianId` from the
       //    capability claims directly — the claims are HMAC-signed by
       //    the same daemon so there is no cross-tenant risk.
-      const capabilityClaims = verifyHostBrowserCapability(token);
+      const capabilityClaims = await verifyHostBrowserCapability(token);
       if (capabilityClaims) {
         guardianId = capabilityClaims.guardianId;
       } else {
@@ -1304,6 +1096,28 @@ export class RuntimeHttpServer {
     return undefined!;
   }
 
+  private verifyGatewayServiceToken(req: Request): Response | null {
+    if (isHttpAuthDisabled()) return null;
+
+    const wsUrl = new URL(req.url);
+    const token = wsUrl.searchParams.get("token");
+    if (!token) {
+      return httpError("UNAUTHORIZED", "Unauthorized", 401);
+    }
+
+    const jwtResult = verifyToken(token, "vellum-daemon");
+    if (!jwtResult.ok) {
+      return httpError("UNAUTHORIZED", "Unauthorized", 401);
+    }
+
+    const subResult = parseSub(jwtResult.claims.sub);
+    if (!subResult.ok || subResult.principalType !== "svc_gateway") {
+      return httpError("UNAUTHORIZED", "Unauthorized", 401);
+    }
+
+    return null;
+  }
+
   private handleRelayUpgrade(
     req: Request,
     server: ReturnType<typeof Bun.serve>,
@@ -1316,6 +1130,10 @@ export class RuntimeHttpServer {
       );
     }
 
+    // Verify the gateway service token before accepting the upgrade.
+    const tokenError = this.verifyGatewayServiceToken(req);
+    if (tokenError) return tokenError;
+
     const wsUrl = new URL(req.url);
     const callSessionId = wsUrl.searchParams.get("callSessionId");
     if (!callSessionId) {
@@ -1341,6 +1159,10 @@ export class RuntimeHttpServer {
       );
     }
 
+    // Verify the gateway service token before accepting the upgrade.
+    const tokenError = this.verifyGatewayServiceToken(req);
+    if (tokenError) return tokenError;
+
     const wsUrl = new URL(req.url);
     const callSessionId = wsUrl.searchParams.get("callSessionId");
     if (!callSessionId) {
@@ -1382,23 +1204,8 @@ export class RuntimeHttpServer {
     }
 
     // Verify the gateway service token before accepting the upgrade.
-    if (!isHttpAuthDisabled()) {
-      const wsUrl = new URL(req.url);
-      const token = wsUrl.searchParams.get("token");
-      if (!token) {
-        return httpError("UNAUTHORIZED", "Unauthorized", 401);
-      }
-      const jwtResult = verifyToken(token, "vellum-daemon");
-      if (!jwtResult.ok) {
-        return httpError("UNAUTHORIZED", "Unauthorized", 401);
-      }
-      // Accept gateway service tokens (svc:gateway:*) — these are the
-      // only tokens the gateway mints for upstream connections.
-      const subResult = parseSub(jwtResult.claims.sub);
-      if (!subResult.ok || subResult.principalType !== "svc_gateway") {
-        return httpError("UNAUTHORIZED", "Unauthorized", 401);
-      }
-    }
+    const tokenError = this.verifyGatewayServiceToken(req);
+    if (tokenError) return tokenError;
 
     const wsUrl = new URL(req.url);
     // provider is optional compatibility metadata — the runtime resolves
@@ -1431,6 +1238,175 @@ export class RuntimeHttpServer {
     return undefined!;
   }
 
+  /**
+   * Handle WebSocket upgrade for `/v1/live-voice`.
+   *
+   * The gateway owns downstream client auth and forwards this upstream with
+   * a short-lived gateway service token. The runtime accepts only private
+   * network peers/origins so the shell is not publicly reachable.
+   */
+  private handleLiveVoiceUpgrade(
+    req: Request,
+    server: ReturnType<typeof Bun.serve>,
+  ): Response {
+    if (!isPrivateNetworkPeer(server, req) || !isPrivateNetworkOrigin(req)) {
+      return httpError(
+        "FORBIDDEN",
+        "Direct live voice access disabled — only private network peers allowed",
+        403,
+      );
+    }
+
+    const tokenError = this.verifyGatewayServiceToken(req);
+    if (tokenError) return tokenError;
+
+    const upgraded = server.upgrade(req, {
+      data: {
+        wsType: "live-voice",
+        lastSeq: 0,
+      } satisfies LiveVoiceWebSocketData,
+    });
+    if (!upgraded) {
+      return new Response("WebSocket upgrade failed", { status: 500 });
+    }
+    return undefined!;
+  }
+
+  private async handleLiveVoiceMessage(
+    ws: ServerWebSocket<LiveVoiceWebSocketData>,
+    message: string | ArrayBuffer | ArrayBufferView,
+  ): Promise<void> {
+    if (typeof message === "string") {
+      const result = parseLiveVoiceClientTextFrame(message);
+      if (!result.ok) {
+        this.sendLiveVoiceError(ws, result.error);
+        return;
+      }
+      await this.dispatchLiveVoiceClientFrame(ws, result.frame);
+      return;
+    }
+
+    const result = parseLiveVoiceBinaryAudioFrame(message);
+    if (!result.ok) {
+      this.sendLiveVoiceError(ws, result.error);
+      return;
+    }
+
+    const sessionId = ws.data.sessionId;
+    if (!sessionId) {
+      this.sendLiveVoiceStateError(
+        ws,
+        "Live voice binary audio received before start",
+      );
+      return;
+    }
+
+    const handled = await this.liveVoiceSessionManager.handleBinaryAudio(
+      sessionId,
+      result.frame.data,
+    );
+    if (handled.status === "not_found") {
+      ws.data.sessionId = undefined;
+      this.sendLiveVoiceStateError(ws, "Live voice session is not active");
+    }
+  }
+
+  private async dispatchLiveVoiceClientFrame(
+    ws: ServerWebSocket<LiveVoiceWebSocketData>,
+    frame: LiveVoiceClientFrame,
+  ): Promise<void> {
+    if (frame.type === "start") {
+      if (ws.data.sessionId) {
+        this.sendLiveVoiceStateError(ws, "Live voice session already started");
+        return;
+      }
+
+      const result = await this.liveVoiceSessionManager.startSession(frame, {
+        sendFrame: async (serverFrame) => {
+          this.sendLiveVoiceFrame(ws, serverFrame);
+        },
+      });
+      if (result.status === "accepted") {
+        ws.data.sessionId = result.sessionId;
+      }
+      return;
+    }
+
+    const sessionId = ws.data.sessionId;
+    if (!sessionId) {
+      this.sendLiveVoiceStateError(
+        ws,
+        `Live voice ${frame.type} frame received before start`,
+      );
+      return;
+    }
+
+    const handled = await this.liveVoiceSessionManager.handleClientFrame(
+      sessionId,
+      frame,
+    );
+    if (handled.status === "not_found") {
+      ws.data.sessionId = undefined;
+      this.sendLiveVoiceStateError(ws, "Live voice session is not active");
+      return;
+    }
+
+    if (frame.type === "end") {
+      ws.data.sessionId = undefined;
+    }
+  }
+
+  private sendLiveVoiceStateError(
+    ws: ServerWebSocket<LiveVoiceWebSocketData>,
+    message: string,
+  ): void {
+    this.sendLiveVoiceError(ws, {
+      code: LiveVoiceProtocolErrorCode.InvalidFrame,
+      message,
+    });
+  }
+
+  private sendLiveVoiceError(
+    ws: ServerWebSocket<LiveVoiceWebSocketData>,
+    error: Pick<LiveVoiceProtocolError, "code" | "message">,
+  ): void {
+    this.sendLiveVoiceFrame(ws, {
+      type: "error",
+      seq: ws.data.lastSeq + 1,
+      code: error.code,
+      message: error.message,
+    });
+  }
+
+  private sendLiveVoiceFrame(
+    ws: ServerWebSocket<LiveVoiceWebSocketData>,
+    frame: LiveVoiceServerFrame,
+  ): void {
+    ws.data.lastSeq = Math.max(ws.data.lastSeq, frame.seq);
+    ws.send(JSON.stringify(frame));
+  }
+
+  private releaseLiveVoiceSession(
+    data: LiveVoiceWebSocketData,
+    reason: "websocket_close",
+  ): void {
+    const sessionId = data.sessionId;
+    data.sessionId = undefined;
+    if (!sessionId) return;
+
+    void this.liveVoiceSessionManager
+      .releaseSession(sessionId, reason)
+      .catch((err) => {
+        log.warn(
+          {
+            error: err instanceof Error ? err.message : String(err),
+            sessionId,
+          },
+          "Failed to release live voice session",
+        );
+      });
+  }
+
   private async handleTwilioWebhook(
     req: Request,
     path: string,
@@ -1471,202 +1447,6 @@ export class RuntimeHttpServer {
     return null;
   }
 
-  private handleGetInterface(interfacePath: string): Response {
-    if (!this.interfacesDir) {
-      return httpError("NOT_FOUND", "Interface not found", 404);
-    }
-    const fullPath = resolve(this.interfacesDir, interfacePath);
-    if (
-      (fullPath !== this.interfacesDir &&
-        !fullPath.startsWith(this.interfacesDir + "/")) ||
-      !existsSync(fullPath)
-    ) {
-      return httpError("NOT_FOUND", "Interface not found", 404);
-    }
-    const source = readFileSync(fullPath, "utf-8");
-    return new Response(source, {
-      headers: { "Content-Type": "text/plain; charset=utf-8" },
-    });
-  }
-
-  private buildAssistantAttention(attentionState: AttentionState | undefined):
-    | {
-        hasUnseenLatestAssistantMessage: boolean;
-        latestAssistantMessageAt?: number;
-        lastSeenAssistantMessageAt?: number;
-        lastSeenConfidence?: Confidence;
-        lastSeenSignalType?: SignalType;
-      }
-    | undefined {
-    if (!attentionState) return undefined;
-
-    return {
-      hasUnseenLatestAssistantMessage:
-        attentionState.latestAssistantMessageAt != null &&
-        (attentionState.lastSeenAssistantMessageAt == null ||
-          attentionState.lastSeenAssistantMessageAt <
-            attentionState.latestAssistantMessageAt),
-      ...(attentionState.latestAssistantMessageAt != null
-        ? {
-            latestAssistantMessageAt: attentionState.latestAssistantMessageAt,
-          }
-        : {}),
-      ...(attentionState.lastSeenAssistantMessageAt != null
-        ? {
-            lastSeenAssistantMessageAt:
-              attentionState.lastSeenAssistantMessageAt,
-          }
-        : {}),
-      ...(attentionState.lastSeenConfidence != null
-        ? { lastSeenConfidence: attentionState.lastSeenConfidence }
-        : {}),
-      ...(attentionState.lastSeenSignalType != null
-        ? { lastSeenSignalType: attentionState.lastSeenSignalType }
-        : {}),
-    };
-  }
-
-  private buildForkParent(
-    conversation: ConversationRow,
-    parentCache: Map<string, ConversationRow | null>,
-  ): { conversationId: string; messageId: string; title: string } | undefined {
-    const parentConversationId = conversation.forkParentConversationId;
-    const parentMessageId = conversation.forkParentMessageId;
-    if (!parentConversationId || !parentMessageId) return undefined;
-
-    let parentConversation: ConversationRow | null | undefined =
-      parentCache.get(parentConversationId);
-    if (parentConversation === undefined) {
-      parentConversation = getConversation(parentConversationId);
-      parentCache.set(parentConversationId, parentConversation);
-    }
-    if (
-      !parentConversation ||
-      parentConversation.conversationType === "private"
-    ) {
-      return undefined;
-    }
-
-    return {
-      conversationId: parentConversationId,
-      messageId: parentMessageId,
-      title: parentConversation.title ?? "Untitled",
-    };
-  }
-
-  private serializeConversationSummary(params: {
-    conversation: ConversationRow;
-    binding?: ExternalConversationBinding | null;
-    attentionState?: AttentionState;
-    displayMeta?: {
-      displayOrder: number | null;
-      isPinned: boolean;
-      groupId: string | null;
-    };
-    parentCache: Map<string, ConversationRow | null>;
-  }) {
-    const { conversation, binding, attentionState, displayMeta, parentCache } =
-      params;
-    const originChannel = parseChannelId(conversation.originChannel);
-    const assistantAttention = this.buildAssistantAttention(attentionState);
-    const forkParent = this.buildForkParent(conversation, parentCache);
-
-    return {
-      id: conversation.id,
-      title: conversation.title ?? "Untitled",
-      createdAt: conversation.createdAt,
-      updatedAt: conversation.updatedAt,
-      lastMessageAt: conversation.lastMessageAt,
-      conversationType: conversation.conversationType ?? "standard",
-      source: conversation.source ?? "user",
-      hostAccess: conversation.hostAccess === 1,
-      ...(conversation.scheduleJobId
-        ? { scheduleJobId: conversation.scheduleJobId }
-        : {}),
-      ...(binding
-        ? {
-            channelBinding: {
-              sourceChannel: binding.sourceChannel,
-              externalChatId: binding.externalChatId,
-              externalUserId: binding.externalUserId,
-              displayName: binding.displayName,
-              username: binding.username,
-            },
-          }
-        : {}),
-      ...(originChannel ? { conversationOriginChannel: originChannel } : {}),
-      ...(assistantAttention ? { assistantAttention } : {}),
-      ...(displayMeta?.isPinned
-        ? {
-            isPinned: true as const,
-            displayOrder: displayMeta.displayOrder,
-          }
-        : displayMeta?.displayOrder != null
-          ? {
-              displayOrder: displayMeta.displayOrder,
-            }
-          : {}),
-      groupId: displayMeta?.groupId ?? null,
-      ...(forkParent ? { forkParent } : {}),
-      ...(conversation.archivedAt != null
-        ? { archivedAt: conversation.archivedAt }
-        : {}),
-    };
-  }
-
-  private buildConversationDetailResponse(conversationId: string) {
-    const conversation = getConversation(conversationId);
-    if (!conversation) {
-      return null;
-    }
-
-    const bindings = externalConversationStore.getBindingsForConversations([
-      conversation.id,
-    ]);
-    const attentionStates = getAttentionStateByConversationIds([
-      conversation.id,
-    ]);
-    const displayMeta = getDisplayMetaForConversations([conversation.id]);
-    const parentCache = new Map<string, ConversationRow | null>();
-
-    return {
-      conversation: this.serializeConversationSummary({
-        conversation,
-        binding: bindings.get(conversation.id),
-        attentionState: attentionStates.get(conversation.id),
-        displayMeta: displayMeta.get(conversation.id),
-        parentCache,
-      }),
-    };
-  }
-
-  private getConversationManagementRouteDeps(): ConversationManagementDeps | null {
-    if (!this.conversationManagementDeps) {
-      return null;
-    }
-
-    return {
-      ...this.conversationManagementDeps,
-      forkConversation:
-        this.conversationManagementDeps.forkConversation ??
-        (async ({ conversationId, throughMessageId }) => {
-          const forkedConversation = forkConversationInStore({
-            conversationId,
-            throughMessageId,
-          });
-          const detail = this.buildConversationDetailResponse(
-            forkedConversation.id,
-          );
-          if (!detail) {
-            throw new Error(
-              `Forked conversation ${forkedConversation.id} could not be loaded`,
-            );
-          }
-          return detail.conversation;
-        }),
-    };
-  }
-
   // ---------------------------------------------------------------------------
   // Declarative route table
   // ---------------------------------------------------------------------------
@@ -1680,552 +1460,7 @@ export class RuntimeHttpServer {
    * `./routes/` and composed here via spread. The composition order
    * preserves the original top-to-bottom matching semantics.
    */
-  private buildRouteTable(): RouteDefinition[] {
-    const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
-    const conversationManagementDeps =
-      this.getConversationManagementRouteDeps();
-
-    return [
-      ...pairingRouteDefinitions({
-        getPairingContext: () => this.pairingContext,
-      }),
-      ...appRouteDefinitions(),
-      ...appManagementRouteDefinitions(),
-      ...secretRouteDefinitions({
-        getCesClient: this.getCesClient,
-        onProviderCredentialsChanged: this.onProviderCredentialsChanged,
-      }),
-      ...identityRouteDefinitions(),
-      ...upgradeBroadcastRouteDefinitions(),
-      ...workspaceCommitRouteDefinitions(),
-      ...migrationRollbackRouteDefinitions(),
-      ...debugRouteDefinitions(),
-      ...usageRouteDefinitions(),
-      ...telemetryRouteDefinitions(),
-      ...workspaceRouteDefinitions(),
-      ...memoryItemRouteDefinitions(),
-      ...conversationStarterRouteDefinitions(),
-      ...settingsRouteDefinitions(),
-      ...avatarRouteDefinitions(),
-      ...scheduleRouteDefinitions({
-        sendMessageDeps: this.sendMessageDeps,
-      }),
-      ...heartbeatRouteDefinitions({
-        getHeartbeatService: this.getHeartbeatService,
-      }),
-      ...filingRouteDefinitions({
-        getFilingService: this.getFilingService,
-      }),
-      ...homeStateRouteDefinitions(),
-      ...homeFeedRouteDefinitions(),
-      ...notificationRouteDefinitions(),
-      ...diagnosticsRouteDefinitions(),
-      ...logExportRouteDefinitions(),
-      ...profilerRouteDefinitions(),
-      ...documentRouteDefinitions(),
-      ...workItemRouteDefinitions(
-        this.sendMessageDeps
-          ? {
-              getOrCreateConversation: (conversationId) =>
-                this.sendMessageDeps!.getOrCreateConversation(conversationId),
-              findConversation: this.findConversation
-                ? (conversationId) => {
-                    const s = this.findConversation!(conversationId);
-                    if (!s || !("abort" in s)) return undefined;
-                    return s as import("../daemon/conversation.js").Conversation;
-                  }
-                : undefined,
-            }
-          : undefined,
-      ),
-      ...acpRouteDefinitions(),
-      ...subagentRouteDefinitions(),
-      ...conversationQueryRouteDefinitions({
-        getModelSetContext: this.getModelSetContext,
-        findConversationForQueue: this.findConversation
-          ? (id) => {
-              const s = this.findConversation!(id);
-              if (!s?.removeQueuedMessage) return undefined;
-              return { removeQueuedMessage: s.removeQueuedMessage.bind(s) };
-            }
-          : undefined,
-      }),
-      ...ttsRouteDefinitions(),
-      ...sttRouteDefinitions(),
-
-      // Conversation list and seen signal — kept inline because they
-      // depend on multiple cross-cutting stores that aren't grouped
-      // into a single domain module.
-      {
-        endpoint: "conversations",
-        method: "GET",
-        handler: ({ url }) => {
-          const limit = Number(url.searchParams.get("limit") ?? 50);
-          const offset = Number(url.searchParams.get("offset") ?? 0);
-          const backgroundOnly =
-            url.searchParams.get("conversationType") === "background";
-          let rows = listConversations(limit, backgroundOnly, offset);
-          const totalCount = countConversations(backgroundOnly);
-          // On the first page, ensure all pinned conversations are included
-          // even if they fall outside the paginated window.
-          if (offset === 0 && !backgroundOnly) {
-            const pinned = listPinnedConversations();
-            const seen = new Set(rows.map((c) => c.id));
-            const missing = pinned.filter((c) => !seen.has(c.id));
-            if (missing.length > 0) {
-              rows = [...rows, ...missing];
-            }
-          }
-          const conversationIds = rows.map((c) => c.id);
-          const displayMeta = getDisplayMetaForConversations(conversationIds);
-          const bindings =
-            externalConversationStore.getBindingsForConversations(
-              conversationIds,
-            );
-          const attentionStates =
-            getAttentionStateByConversationIds(conversationIds);
-          const parentCache = new Map<string, ConversationRow | null>();
-          const nextOffset = offset + limit;
-          const response: Record<string, unknown> = {
-            conversations: rows.map((conversation) =>
-              this.serializeConversationSummary({
-                conversation,
-                binding: bindings.get(conversation.id),
-                attentionState: attentionStates.get(conversation.id),
-                displayMeta: displayMeta.get(conversation.id),
-                parentCache,
-              }),
-            ),
-            nextOffset,
-            hasMore: nextOffset < totalCount,
-          };
-          // Include groups array on first page only
-          if (offset === 0) {
-            const groups = listGroups();
-            response.groups = groups.map((g) => ({
-              id: g.id,
-              name: g.name,
-              sortPosition: g.sortPosition,
-              isSystemGroup: g.isSystemGroup,
-            }));
-          }
-          return Response.json(response);
-        },
-      },
-      ...conversationAttentionRouteDefinitions(),
-
-      ...(conversationManagementDeps
-        ? conversationManagementRouteDefinitions(conversationManagementDeps)
-        : []),
-
-      ...((): RouteDefinition[] => {
-        const sendMessageDeps = this.sendMessageDeps;
-        if (!sendMessageDeps) return [];
-        const analysisDeps = {
-          sendMessageDeps,
-          buildConversationDetailResponse: (id: string) =>
-            this.buildConversationDetailResponse(id),
-        };
-        // Also expose via the module singleton so background callers
-        // (e.g. job handlers) can invoke analyzeConversation() without
-        // HTTP-layer wiring. Daemon startup must never block, so failures
-        // to register the singleton are logged and swallowed.
-        try {
-          setAnalysisDeps(analysisDeps);
-        } catch (err) {
-          log.warn(
-            { err },
-            "Failed to register analysis deps singleton; background analysis jobs will be skipped",
-          );
-        }
-        return conversationAnalysisRouteDefinitions(analysisDeps);
-      })(),
-
-      ...groupRouteDefinitions(),
-
-      {
-        endpoint: "conversations/seen",
-        method: "POST",
-        handler: async ({ req }) => {
-          const body = (await req.json()) as Record<string, unknown>;
-          const rawConversationId = body.conversationId as string | undefined;
-          if (!rawConversationId)
-            return httpError("BAD_REQUEST", "Missing conversationId", 400);
-          // The client may send a conversation key rather than the internal
-          // conversation ID. Resolve to the internal ID to satisfy FK constraints.
-          const conversationId = resolveConversationId(rawConversationId);
-          if (!conversationId)
-            return httpError(
-              "NOT_FOUND",
-              `Unknown conversation: ${rawConversationId}`,
-              404,
-            );
-          try {
-            // Snapshot current state to detect whether the seen cursor
-            // actually advances (avoids emitting on no-op signals).
-            // Only consider a conversation "unseen" when a latest assistant
-            // message exists and the seen cursor is behind it — matching
-            // the hasUnseenLatestAssistantMessage logic in buildAssistantAttention.
-            const priorState = getAttentionStateByConversationIds([
-              conversationId,
-            ]).get(conversationId);
-            const wasUnseen =
-              priorState != null &&
-              priorState.latestAssistantMessageAt != null &&
-              (priorState.lastSeenAssistantMessageAt == null ||
-                priorState.lastSeenAssistantMessageAt <
-                  priorState.latestAssistantMessageAt);
-
-            recordConversationSeenSignal({
-              conversationId,
-              sourceChannel: (body.sourceChannel as string) ?? "vellum",
-              signalType: ((body.signalType as string) ??
-                "macos_conversation_opened") as SignalType,
-              confidence: ((body.confidence as string) ??
-                "explicit") as Confidence,
-              source: (body.source as string) ?? "http-api",
-              evidenceText: body.evidenceText as string | undefined,
-              metadata: body.metadata as Record<string, unknown> | undefined,
-              observedAt: body.observedAt as number | undefined,
-            });
-            if (wasUnseen) {
-              assistantEventHub
-                .publish(
-                  buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, {
-                    type: "conversation_list_invalidated",
-                    reason: "seen_changed",
-                  }),
-                )
-                .catch((err) => {
-                  log.warn(
-                    { err },
-                    "Failed to publish conversation_list_invalidated (seen_changed)",
-                  );
-                });
-            }
-            return Response.json({ ok: true });
-          } catch (err) {
-            log.error(
-              { err, conversationId },
-              "POST /v1/conversations/seen: failed",
-            );
-            return httpError(
-              "INTERNAL_ERROR",
-              "Failed to record seen signal",
-              500,
-            );
-          }
-        },
-      },
-
-      {
-        endpoint: "conversations/unread",
-        method: "POST",
-        handler: async ({ req }) => {
-          const body = (await req.json()) as Record<string, unknown>;
-          const rawConversationId = body.conversationId as string | undefined;
-          if (!rawConversationId)
-            return httpError("BAD_REQUEST", "Missing conversationId", 400);
-          const conversationId = resolveConversationId(rawConversationId);
-          if (!conversationId)
-            return httpError(
-              "NOT_FOUND",
-              `Unknown conversation: ${rawConversationId}`,
-              404,
-            );
-          try {
-            const changed = markConversationUnread(conversationId);
-            if (changed) {
-              assistantEventHub
-                .publish(
-                  buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, {
-                    type: "conversation_list_invalidated",
-                    reason: "seen_changed",
-                  }),
-                )
-                .catch((err) => {
-                  log.warn(
-                    { err },
-                    "Failed to publish conversation_list_invalidated (seen_changed)",
-                  );
-                });
-            }
-            return Response.json({ ok: true });
-          } catch (err) {
-            if (err instanceof UserError) {
-              return httpError("UNPROCESSABLE_ENTITY", err.message, 422);
-            }
-            log.error(
-              { err, conversationId },
-              "POST /v1/conversations/unread: failed",
-            );
-            return httpError(
-              "INTERNAL_ERROR",
-              "Failed to mark conversation unread",
-              500,
-            );
-          }
-        },
-      },
-
-      // conversations/:id must be registered AFTER all literal conversations/<word>
-      // routes above (attention, seen, unread) so the parameterized :id does not
-      // shadow them.
-      {
-        endpoint: "conversations/:id",
-        method: "GET",
-        handler: ({ params }) => {
-          const detail = this.buildConversationDetailResponse(params.id);
-          if (!detail) {
-            return httpError(
-              "NOT_FOUND",
-              `Conversation ${params.id} not found`,
-              404,
-            );
-          }
-          return Response.json(detail);
-        },
-      },
-
-      ...btwRouteDefinitions({
-        sendMessageDeps: this.sendMessageDeps,
-      }),
-
-      ...conversationRouteDefinitions({
-        interfacesDir: this.interfacesDir,
-        sendMessageDeps: this.sendMessageDeps,
-        approvalConversationGenerator: this.approvalConversationGenerator,
-        suggestionCache: this.suggestionCache,
-        suggestionInFlight: this.suggestionInFlight,
-        getHeartbeatService: this.getHeartbeatService,
-      }),
-      ...playgroundRouteDefinitions({
-        getConversationById: async (id) => {
-          // Gate on DB existence first so genuinely-missing IDs return
-          // `undefined` (preserving the route handlers' 404 path) rather
-          // than triggering `getOrCreateConversation`'s create branch and
-          // masking the not-found case. For existing-but-not-loaded rows
-          // (e.g. freshly seeded by `POST /playground/seed-conversation`),
-          // hydrate the in-memory `Conversation` on demand so conv-scoped
-          // playground routes work without first opening the conversation
-          // in the main window.
-          if (!getConversation(id)) return undefined;
-          const sendDeps = this.sendMessageDeps;
-          if (!sendDeps) {
-            // Fall back to the in-memory active map when the daemon hasn't
-            // wired the hydration-capable accessor (e.g. unit tests).
-            const s = this.findConversation?.(id);
-            if (!s || !("abort" in s)) return undefined;
-            return s as import("../daemon/conversation.js").Conversation;
-          }
-          return sendDeps.getOrCreateConversation(id);
-        },
-        isPlaygroundEnabled: () =>
-          isAssistantFeatureFlagEnabled("compaction-playground", getConfig()),
-        listConversationsByTitlePrefix: (prefix) =>
-          listConversationsByTitlePrefix(prefix),
-        deleteConversationById: (id) => {
-          // Existence check first so we can report `false` for missing rows
-          // — `deleteConversation` always returns a result object even when
-          // no row matched.
-          if (!getConversation(id)) return false;
-          // Mirror the canonical DELETE /v1/conversations/:id handler in
-          // conversation-management-routes.ts: tear down the in-memory
-          // Conversation first (so a running agent loop can't write to a
-          // deleted row and trip FK constraints), then drop the DB row,
-          // then enqueue Qdrant vector cleanup for the returned segment
-          // and summary IDs. Without this, seeded-then-deleted playground
-          // conversations leak vectors and zombie Conversation objects.
-          if (this.findConversation?.(id)) {
-            this.conversationManagementDeps?.destroyConversation(id);
-          }
-          const deleted = deleteConversation(id);
-          for (const segId of deleted.segmentIds) {
-            enqueueMemoryJob("delete_qdrant_vectors", {
-              targetType: "segment",
-              targetId: segId,
-            });
-          }
-          for (const summaryId of deleted.deletedSummaryIds) {
-            enqueueMemoryJob("delete_qdrant_vectors", {
-              targetType: "summary",
-              targetId: summaryId,
-            });
-          }
-          return true;
-        },
-        createConversation: async (title) => {
-          const row = createConversation({ title });
-          return { id: row.id };
-        },
-        addMessage: async (conversationId, role, contentJson, options) => {
-          const persisted = await addMessage(
-            conversationId,
-            role,
-            contentJson,
-            undefined,
-            options,
-          );
-          return { id: persisted.id };
-        },
-      }),
-      ...globalSearchRouteDefinitions(),
-      ...approvalRouteDefinitions(),
-      ...hostBashRouteDefinitions(),
-      ...hostBrowserRouteDefinitions(),
-      ...hostCuRouteDefinitions(),
-      ...hostFileRouteDefinitions(),
-      ...(this.getSkillContext
-        ? skillRouteDefinitions({
-            getSkillContext: this.getSkillContext,
-          })
-        : []),
-      ...trustRulesRouteDefinitions(),
-      ...surfaceActionRouteDefinitions({
-        findConversation: this.findConversation,
-        findConversationBySurfaceId: this.findConversationBySurfaceId,
-      }),
-      ...surfaceContentRouteDefinitions({
-        findConversation: this.findConversation,
-      }),
-      ...guardianActionRouteDefinitions(),
-
-      ...contactRouteDefinitions(),
-      ...inviteRouteDefinitions(),
-      // contacts/:id catch-all must follow invite routes to avoid shadowing
-      ...contactCatchAllRouteDefinitions(),
-
-      ...telegramRouteDefinitions(),
-      ...channelVerificationRouteDefinitions(),
-      ...slackChannelRouteDefinitions(),
-      ...slackShareRouteDefinitions(),
-      ...twilioRouteDefinitions(),
-      ...vercelRouteDefinitions(),
-      ...channelReadinessRouteDefinitions(),
-      ...oauthProvidersRouteDefinitions(),
-      ...oauthAppsRouteDefinitions(),
-      ...attachmentRouteDefinitions(),
-
-      ...(this.getRecordingDeps
-        ? recordingRouteDefinitions({
-            getRecordingDeps: this.getRecordingDeps,
-          })
-        : []),
-
-      {
-        endpoint: "interfaces/:path*",
-        method: "GET",
-        policyKey: "interfaces",
-        handler: ({ params }) => this.handleGetInterface(params.path),
-      },
-
-      ...channelRouteDefinitions({
-        assistantId,
-        processMessage: this.processMessage,
-        approvalCopyGenerator: this.approvalCopyGenerator,
-        approvalConversationGenerator: this.approvalConversationGenerator,
-        guardianActionCopyGenerator: this.guardianActionCopyGenerator,
-        guardianFollowUpConversationGenerator:
-          this.guardianFollowUpConversationGenerator,
-        getHeartbeatService: this.getHeartbeatService,
-      }),
-      ...callRouteDefinitions({ assistantId }),
-
-      // Internal Twilio forwarding (gateway -> runtime) — kept inline
-      // because these reconstruct fake form-encoded requests from JSON,
-      // a pattern specific to the gateway-to-daemon bridge.
-      {
-        endpoint: "internal/twilio/voice-webhook",
-        method: "POST",
-        handler: async ({ req }) => {
-          const json = (await req.json()) as {
-            params: Record<string, string>;
-            originalUrl?: string;
-          };
-          const formBody = new URLSearchParams(json.params).toString();
-          const reconstructedUrl = json.originalUrl ?? req.url;
-          const fakeReq = new Request(reconstructedUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
-            body: formBody,
-          });
-          return handleVoiceWebhook(fakeReq);
-        },
-      },
-      {
-        endpoint: "internal/twilio/status",
-        method: "POST",
-        handler: async ({ req }) => {
-          const json = (await req.json()) as {
-            params: Record<string, string>;
-          };
-          const formBody = new URLSearchParams(json.params).toString();
-          const fakeReq = new Request(req.url, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
-            body: formBody,
-          });
-          return handleStatusCallback(fakeReq);
-        },
-      },
-      {
-        endpoint: "internal/twilio/connect-action",
-        method: "POST",
-        handler: async ({ req }) => {
-          const json = (await req.json()) as {
-            params: Record<string, string>;
-          };
-          const formBody = new URLSearchParams(json.params).toString();
-          const fakeReq = new Request(req.url, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
-            body: formBody,
-          });
-          return handleConnectAction(fakeReq);
-        },
-      },
-
-      ...brainGraphRouteDefinitions({ mintUiPageToken }),
-      ...eventsRouteDefinitions(),
-      ...traceEventRouteDefinitions(),
-      ...migrationRouteDefinitions(),
-      ...backupRouteDefinitions(),
-
-      // User-defined routes under /x/* — must be LAST so built-in routes
-      // always take priority.
-      ...userRouteDefinitions(),
-
-      // Internal OAuth callback (gateway -> runtime)
-      {
-        endpoint: "internal/oauth/callback",
-        method: "POST",
-        handler: async ({ req }) => {
-          const json = (await req.json()) as {
-            state: string;
-            code?: string;
-            error?: string;
-          };
-          if (!json.state)
-            return httpError("BAD_REQUEST", "Missing state parameter", 400);
-          if (json.error) {
-            const consumed = consumeCallbackError(json.state, json.error);
-            return consumed
-              ? Response.json({ ok: true })
-              : httpError("NOT_FOUND", "Unknown state", 404);
-          }
-          if (json.code) {
-            const consumed = consumeCallback(json.state, json.code);
-            return consumed
-              ? Response.json({ ok: true })
-              : httpError("NOT_FOUND", "Unknown state", 404);
-          }
-          return httpError(
-            "BAD_REQUEST",
-            "Missing code or error parameter",
-            400,
-          );
-        },
-      },
-    ];
+  private buildRouteTable(): HTTPRouteDefinition[] {
+    return [...routeDefinitionsToHTTPRoutes(ROUTES)];
   }
 }