@vellumai/assistant 0.3.5 → 0.3.7

package/src/runtime/http-server.ts

@@ -1,20 +1,19 @@
 /**
  * Optional HTTP server that exposes the canonical runtime API.
  *
- * Runs in the same process as the daemon. Started only when
- * `RUNTIME_HTTP_PORT` is set (default: disabled).
+ * Runs in the same process as the daemon. Always started on the
+ * configured port (default: 7821).
  */
 
-import { existsSync, readFileSync, statSync, statfsSync } from 'node:fs';
-import { resolve, join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { timingSafeEqual } from 'node:crypto';
-import { ConfigError, IngressBlockedError } from '../util/errors.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseChannelId } from '../channels/types.js';
 import { getLogger } from '../util/logger.js';
-import { getWorkspacePromptPath, readLockfile } from '../util/platform.js';
-import { TwilioConversationRelayProvider } from '../calls/twilio-provider.js';
-import { loadConfig } from '../config/loader.js';
-import { getPublicBaseUrl } from '../inbound/public-ingress-urls.js';
+import {
+  getGatewayInternalBaseUrl,
+  isHttpAuthDisabled,
+  getRuntimeGatewayOriginSecret,
+} from '../config/env.js';
 import type { RunOrchestrator } from './run-orchestrator.js';
 
 // Route handlers — grouped by domain
@@ -22,6 +21,7 @@ import {
   handleListMessages,
   handleSendMessage,
   handleGetSuggestion,
+  handleSearchConversations,
 } from './routes/conversation-routes.js';
 import {
   handleUploadAttachment,
@@ -44,12 +44,12 @@ import {
   startGuardianExpirySweep,
   stopGuardianExpirySweep,
 } from './routes/channel-routes.js';
-import * as channelDeliveryStore from '../memory/channel-delivery-store.js';
+import {
+  startGuardianActionSweep,
+  stopGuardianActionSweep,
+} from '../calls/guardian-action-sweep.js';
 import * as conversationStore from '../memory/conversation-store.js';
 import * as externalConversationStore from '../memory/external-conversation-store.js';
-import * as attachmentsStore from '../memory/attachments-store.js';
-import { renderHistoryContent } from '../daemon/handlers.js';
-import { deliverChannelReply } from './gateway-client.js';
 import {
   handleServePage,
   handleShareApp,
@@ -72,9 +72,45 @@ import {
 } from '../calls/twilio-routes.js';
 import { RelayConnection, activeRelayConnections } from '../calls/relay-server.js';
 import type { RelayWebSocketData } from '../calls/relay-server.js';
+import { extensionRelayServer } from '../browser-extension-relay/server.js';
+import type { BrowserRelayWebSocketData } from '../browser-extension-relay/server.js';
 import { handleSubscribeAssistantEvents } from './routes/events-routes.js';
 import { consumeCallback, consumeCallbackError } from '../security/oauth-callback-registry.js';
-import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
+import { PairingStore } from '../daemon/pairing-store.js';
+import type { ServerMessage } from '../daemon/ipc-contract.js';
+import { assistantEventHub } from './assistant-event-hub.js';
+import { buildAssistantEvent } from './assistant-event.js';
+
+// Middleware
+import {
+  verifyBearerToken,
+  isLoopbackHost,
+  isPrivateNetworkPeer,
+  isPrivateNetworkOrigin,
+  extractBearerToken,
+} from './middleware/auth.js';
+import { withErrorHandling } from './middleware/error-handler.js';
+import {
+  TWILIO_WEBHOOK_RE,
+  TWILIO_GATEWAY_WEBHOOK_RE,
+  GATEWAY_SUBPATH_MAP,
+  GATEWAY_ONLY_BLOCKED_SUBPATHS,
+  validateTwilioWebhook,
+  cloneRequestWithBody,
+} from './middleware/twilio-validation.js';
+
+// Extracted route handlers
+import {
+  handlePairingRegister,
+  handlePairingRequest,
+  handlePairingStatus,
+} from './routes/pairing-routes.js';
+import type { PairingHandlerContext } from './routes/pairing-routes.js';
+import { handleHealth, handleGetIdentity } from './routes/identity-routes.js';
+import { sweepFailedEvents } from './channel-retry-sweep.js';
+
+// Re-export for consumers
+export { isPrivateAddress } from './middleware/auth.js';
 
 // Re-export shared types so existing consumers don't need to update imports
 export type {
@@ -83,12 +119,16 @@ export type {
   NonBlockingMessageProcessor,
   RuntimeHttpServerOptions,
   RuntimeAttachmentMetadata,
+  ApprovalCopyGenerator,
+  ApprovalConversationGenerator,
 } from './http-types.js';
 
 import type {
   MessageProcessor,
   NonBlockingMessageProcessor,
   RuntimeHttpServerOptions,
+  ApprovalCopyGenerator,
+  ApprovalConversationGenerator,
 } from './http-types.js';
 
 const log = getLogger('runtime-http');
@@ -96,282 +136,9 @@ const log = getLogger('runtime-http');
 const DEFAULT_PORT = 7821;
 const DEFAULT_HOSTNAME = '127.0.0.1';
 
-/** Resolve the gateway base URL for internal delivery callbacks. */
-function getGatewayBaseUrl(): string {
-  if (process.env.GATEWAY_INTERNAL_BASE_URL) {
-    return process.env.GATEWAY_INTERNAL_BASE_URL.replace(/\/+$/, '');
-  }
-  const port = Number(process.env.GATEWAY_PORT) || 7830;
-  return `http://127.0.0.1:${port}`;
-}
-
-/** Global hard cap on request body size (50 MB). Bun rejects larger payloads before they reach handlers. */
+/** Global hard cap on request body size (50 MB). */
 const MAX_REQUEST_BODY_BYTES = 50 * 1024 * 1024;
 
-function parseGuardianRuntimeContext(value: unknown): GuardianRuntimeContext | undefined {
-  if (!value || typeof value !== 'object') return undefined;
-  const raw = value as Record<string, unknown>;
-  const actorRole = raw.actorRole;
-  if (
-    actorRole !== 'guardian'
-    && actorRole !== 'non-guardian'
-    && actorRole !== 'unverified_channel'
-  ) {
-    return undefined;
-  }
-  const sourceChannel = typeof raw.sourceChannel === 'string' && raw.sourceChannel.trim().length > 0
-    ? raw.sourceChannel
-    : undefined;
-  if (!sourceChannel) return undefined;
-  const denialReason =
-    raw.denialReason === 'no_binding' || raw.denialReason === 'no_identity'
-      ? raw.denialReason
-      : undefined;
-  return {
-    sourceChannel,
-    actorRole,
-    guardianChatId: typeof raw.guardianChatId === 'string' ? raw.guardianChatId : undefined,
-    guardianExternalUserId: typeof raw.guardianExternalUserId === 'string' ? raw.guardianExternalUserId : undefined,
-    requesterIdentifier: typeof raw.requesterIdentifier === 'string' ? raw.requesterIdentifier : undefined,
-    requesterExternalUserId: typeof raw.requesterExternalUserId === 'string' ? raw.requesterExternalUserId : undefined,
-    requesterChatId: typeof raw.requesterChatId === 'string' ? raw.requesterChatId : undefined,
-    denialReason,
-  };
-}
-
-interface DiskSpaceInfo {
-  path: string;
-  totalMb: number;
-  usedMb: number;
-  freeMb: number;
-}
-
-function getDiskSpaceInfo(): DiskSpaceInfo | null {
-  try {
-    const baseDataDir = process.env.BASE_DATA_DIR?.trim();
-    const diskPath = baseDataDir && existsSync(baseDataDir) ? baseDataDir : '/';
-    const stats = statfsSync(diskPath);
-    const totalBytes = stats.bsize * stats.blocks;
-    const freeBytes = stats.bsize * stats.bavail;
-    const bytesToMb = (b: number) => Math.round((b / (1024 * 1024)) * 100) / 100;
-    return {
-      path: diskPath,
-      totalMb: bytesToMb(totalBytes),
-      usedMb: bytesToMb(totalBytes - freeBytes),
-      freeMb: bytesToMb(freeBytes),
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Regex to extract the Twilio webhook subpath from both top-level and
- * assistant-scoped route shapes:
- *   /v1/calls/twilio/<subpath>
- *   /v1/assistants/<id>/calls/twilio/<subpath>
- */
-const TWILIO_WEBHOOK_RE = /^\/v1\/(?:assistants\/[^/]+\/)?calls\/twilio\/(.+)$/;
-
-/**
- * Gateway-compatible Twilio webhook paths:
- *   /webhooks/twilio/<subpath>
- *
- * Maps gateway path segments to the internal subpath names used by the
- * dispatcher below (e.g. "voice" -> "voice-webhook").
- */
-const TWILIO_GATEWAY_WEBHOOK_RE = /^\/webhooks\/twilio\/(.+)$/;
-const GATEWAY_SUBPATH_MAP: Record<string, string> = {
-  voice: 'voice-webhook',
-  status: 'status',
-  'connect-action': 'connect-action',
-  sms: 'sms',
-};
-
-/**
- * Direct Twilio webhook subpaths that are blocked in gateway_only mode.
- * Includes all public-facing webhook paths (voice, status, connect-action, SMS)
- * because the runtime must never serve as a direct ingress for external webhooks.
- * Internal forwarding endpoints (gateway→runtime) are unaffected.
- */
-const GATEWAY_ONLY_BLOCKED_SUBPATHS = new Set(['voice-webhook', 'status', 'connect-action', 'sms']);
-
-/**
- * Check if a request origin is from a private/internal network address.
- * Extracts the hostname from the Origin header and validates it against
- * isPrivateAddress(), consistent with the isPrivateNetworkPeer check.
- */
-function isPrivateNetworkOrigin(req: Request): boolean {
-  const origin = req.headers.get('origin');
-  // No origin header (e.g., server-initiated or same-origin) — allow
-  if (!origin) return true;
-  try {
-    const url = new URL(origin);
-    const host = url.hostname;
-    if (host === 'localhost') return true;
-    // URL.hostname wraps IPv6 addresses in brackets (e.g. "[::1]") — strip them
-    const rawHost = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
-    return isPrivateAddress(rawHost);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if a hostname is a loopback address.
- */
-function isLoopbackHost(hostname: string): boolean {
-  return hostname === '127.0.0.1' || hostname === '::1' || hostname === 'localhost';
-}
-
-/**
- * Check if the actual peer/remote address of a connection is from a
- * private/internal network. Uses Bun's server.requestIP() to get the
- * real peer address, which cannot be spoofed unlike the Origin header.
- *
- * Accepts loopback, RFC 1918 private IPv4, link-local, and RFC 4193
- * unique-local IPv6 — including their IPv4-mapped IPv6 forms. This
- * supports container/pod deployments (e.g. Kubernetes sidecars) where
- * gateway and runtime communicate over pod-internal private IPs.
- */
-function isPrivateNetworkPeer(server: { requestIP(req: Request): { address: string; family: string; port: number } | null }, req: Request): boolean {
-  const ip = server.requestIP(req);
-  if (!ip) return false;
-  return isPrivateAddress(ip.address);
-}
-
-/**
- * @internal Exported for testing.
- *
- * Determine whether an IP address string belongs to a private/internal
- * network range:
- *   - Loopback: 127.0.0.0/8, ::1
- *   - RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
- *   - Link-local: 169.254.0.0/16
- *   - IPv6 unique local: fc00::/7 (fc00::–fdff::)
- *   - IPv4-mapped IPv6 variants of all of the above (::ffff:x.x.x.x)
- */
-export function isPrivateAddress(addr: string): boolean {
-  // Handle IPv4-mapped IPv6 (e.g. ::ffff:10.0.0.1) — extract the IPv4 part
-  const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
-  const normalized = v4Mapped ? v4Mapped[1] : addr;
-
-  // IPv4 checks
-  if (normalized.includes('.')) {
-    const parts = normalized.split('.').map(Number);
-    if (parts.length !== 4 || parts.some(p => isNaN(p) || p < 0 || p > 255)) return false;
-
-    // Loopback: 127.0.0.0/8
-    if (parts[0] === 127) return true;
-    // 10.0.0.0/8
-    if (parts[0] === 10) return true;
-    // 172.16.0.0/12 (172.16.x.x – 172.31.x.x)
-    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
-    // 192.168.0.0/16
-    if (parts[0] === 192 && parts[1] === 168) return true;
-    // Link-local: 169.254.0.0/16
-    if (parts[0] === 169 && parts[1] === 254) return true;
-
-    return false;
-  }
-
-  // IPv6 checks
-  const lower = normalized.toLowerCase();
-  // Loopback
-  if (lower === '::1') return true;
-  // Unique local: fc00::/7 (fc00:: through fdff::)
-  if (lower.startsWith('fc') || lower.startsWith('fd')) return true;
-  // Link-local: fe80::/10
-  if (lower.startsWith('fe80')) return true;
-
-  return false;
-}
-
-/**
- * Validate a Twilio webhook request's X-Twilio-Signature header.
- *
- * Returns the raw body text on success so callers can reconstruct the Request
- * for downstream handlers (which also need to read the body).
- * Returns a 403 Response if signature validation fails.
- *
- * Fail-closed: if the auth token is not configured, the request is rejected
- * with 403 rather than silently skipping validation. An explicit local-dev
- * bypass is available via TWILIO_WEBHOOK_VALIDATION_DISABLED=true.
- */
-async function validateTwilioWebhook(
-  req: Request,
-): Promise<{ body: string } | Response> {
-  const rawBody = await req.text();
-
-  // Allow explicit local-dev bypass — must be exactly "true"
-  if (process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED === 'true') {
-    log.warn('Twilio webhook signature validation explicitly disabled via TWILIO_WEBHOOK_VALIDATION_DISABLED');
-    return { body: rawBody };
-  }
-
-  const authToken = TwilioConversationRelayProvider.getAuthToken();
-
-  // Fail-closed: reject if no auth token is configured
-  if (!authToken) {
-    log.error('Twilio auth token not configured — rejecting webhook request (fail-closed)');
-    return Response.json({ error: 'Forbidden' }, { status: 403 });
-  }
-
-  const signature = req.headers.get('x-twilio-signature');
-  if (!signature) {
-    log.warn('Twilio webhook request missing X-Twilio-Signature header');
-    return Response.json({ error: 'Forbidden' }, { status: 403 });
-  }
-
-  // Parse form-urlencoded body into key-value params for signature computation
-  const params: Record<string, string> = {};
-  const formData = new URLSearchParams(rawBody);
-  for (const [key, value] of formData.entries()) {
-    params[key] = value;
-  }
-
-  // Reconstruct the public-facing URL that Twilio signed against.
-  // Behind proxies/gateways, req.url is the local server URL (e.g.
-  // http://127.0.0.1:7821/...) which differs from the public URL Twilio
-  // used to compute the HMAC-SHA1 signature.
-  let publicBaseUrl: string | undefined;
-  try {
-    publicBaseUrl = getPublicBaseUrl(loadConfig());
-  } catch {
-    // No webhook base URL configured — fall back to using req.url as-is
-  }
-  const parsedUrl = new URL(req.url);
-  const publicUrl = publicBaseUrl
-    ? publicBaseUrl + parsedUrl.pathname + parsedUrl.search
-    : req.url;
-
-  const isValid = TwilioConversationRelayProvider.verifyWebhookSignature(
-    publicUrl,
-    params,
-    signature,
-    authToken,
-  );
-
-  if (!isValid) {
-    log.warn('Twilio webhook signature validation failed');
-    return Response.json({ error: 'Forbidden' }, { status: 403 });
-  }
-
-  return { body: rawBody };
-}
-
-/**
- * Re-create a Request with the same method, headers, and URL but with a
- * pre-read body string so downstream handlers can call req.text() again.
- */
-function cloneRequestWithBody(original: Request, body: string): Request {
-  return new Request(original.url, {
-    method: original.method,
-    headers: original.headers,
-    body,
-  });
-}
-
 export class RuntimeHttpServer {
   private server: ReturnType<typeof Bun.serve> | null = null;
   private port: number;
@@ -380,11 +147,15 @@ export class RuntimeHttpServer {
   private processMessage?: MessageProcessor;
   private persistAndProcessMessage?: NonBlockingMessageProcessor;
   private runOrchestrator?: RunOrchestrator;
+  private approvalCopyGenerator?: ApprovalCopyGenerator;
+  private approvalConversationGenerator?: ApprovalConversationGenerator;
   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;
 
   constructor(options: RuntimeHttpServerOptions = {}) {
     this.port = options.port ?? DEFAULT_PORT;
@@ -393,6 +164,8 @@ export class RuntimeHttpServer {
     this.processMessage = options.processMessage;
     this.persistAndProcessMessage = options.persistAndProcessMessage;
     this.runOrchestrator = options.runOrchestrator;
+    this.approvalCopyGenerator = options.approvalCopyGenerator;
+    this.approvalConversationGenerator = options.approvalConversationGenerator;
     this.interfacesDir = options.interfacesDir ?? null;
   }
 
@@ -401,30 +174,78 @@ export class RuntimeHttpServer {
     return this.server?.port ?? this.port;
   }
 
+  /** Expose the pairing store so the daemon server can wire IPC handlers. */
+  getPairingStore(): PairingStore {
+    return this.pairingStore;
+  }
+
+  /** Set a callback for broadcasting IPC messages (wired by daemon server). */
+  setPairingBroadcast(fn: (msg: ServerMessage) => void): void {
+    this.pairingBroadcast = fn;
+  }
+
+  private get pairingContext(): PairingHandlerContext {
+    const ipcBroadcast = this.pairingBroadcast;
+    return {
+      pairingStore: this.pairingStore,
+      bearerToken: this.bearerToken,
+      pairingBroadcast: ipcBroadcast
+        ? (msg) => {
+            // Broadcast to IPC socket clients (local Unix socket)
+            ipcBroadcast(msg);
+            // Also publish to the event hub so HTTP/SSE clients (e.g. macOS
+            // app with localHttpEnabled) receive pairing approval requests.
+            void assistantEventHub.publish(buildAssistantEvent('self', msg));
+          }
+        : undefined,
+    };
+  }
+
   async start(): Promise<void> {
-    this.server = Bun.serve<RelayWebSocketData>({
+    type AllWebSocketData = RelayWebSocketData | BrowserRelayWebSocketData;
+    this.server = Bun.serve<AllWebSocketData>({
       port: this.port,
       hostname: this.hostname,
       maxRequestBodySize: MAX_REQUEST_BODY_BYTES,
       fetch: (req, server) => this.handleRequest(req, server),
       websocket: {
         open(ws) {
-          const callSessionId = ws.data?.callSessionId;
+          const data = ws.data as AllWebSocketData;
+          if ('wsType' in data && data.wsType === 'browser-relay') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            extensionRelayServer.handleOpen(ws as any);
+            return;
+          }
+          const callSessionId = (data as RelayWebSocketData).callSessionId;
           log.info({ callSessionId }, 'ConversationRelay WebSocket opened');
           if (callSessionId) {
-            const connection = new RelayConnection(ws, callSessionId);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const connection = new RelayConnection(ws as any, callSessionId);
             activeRelayConnections.set(callSessionId, connection);
           }
         },
         message(ws, message) {
-          const callSessionId = ws.data?.callSessionId;
+          const data = ws.data as AllWebSocketData;
+          const raw = typeof message === 'string' ? message : new TextDecoder().decode(message);
+          if ('wsType' in data && data.wsType === 'browser-relay') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            extensionRelayServer.handleMessage(ws as any, raw);
+            return;
+          }
+          const callSessionId = (data as RelayWebSocketData).callSessionId;
           if (callSessionId) {
             const connection = activeRelayConnections.get(callSessionId);
-            connection?.handleMessage(typeof message === 'string' ? message : new TextDecoder().decode(message));
+            connection?.handleMessage(raw);
           }
         },
         close(ws, code, reason) {
-          const callSessionId = ws.data?.callSessionId;
+          const data = ws.data as AllWebSocketData;
+          if ('wsType' in data && data.wsType === 'browser-relay') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            extensionRelayServer.handleClose(ws as any, code, reason?.toString());
+            return;
+          }
+          const callSessionId = (data as RelayWebSocketData).callSessionId;
           log.info({ callSessionId, code, reason: reason?.toString() }, 'ConversationRelay WebSocket closed');
           if (callSessionId) {
             const connection = activeRelayConnections.get(callSessionId);
@@ -436,34 +257,38 @@ export class RuntimeHttpServer {
       },
     });
 
-    // Sweep failed channel inbound events for retry every 30 seconds
     if (this.processMessage) {
+      const pm = this.processMessage;
+      const bt = this.bearerToken;
       this.retrySweepTimer = setInterval(() => {
         if (this.sweepInProgress) return;
         this.sweepInProgress = true;
-        this.sweepFailedEvents().finally(() => { this.sweepInProgress = false; });
+        sweepFailedEvents(pm, bt).finally(() => { this.sweepInProgress = false; });
       }, 30_000);
     }
 
-    // Start proactive guardian approval expiry sweep whenever orchestrator
-    // support is available. Guardian approvals can be created even when the
-    // generic channel-approval UX flag is disabled.
     if (this.runOrchestrator) {
-      startGuardianExpirySweep(this.runOrchestrator, getGatewayBaseUrl(), this.bearerToken);
+      startGuardianExpirySweep(this.runOrchestrator, getGatewayInternalBaseUrl(), this.bearerToken, this.approvalCopyGenerator);
       log.info('Guardian approval expiry sweep started');
     }
 
-    // Startup guard: log gateway-only mode warnings
+    startGuardianActionSweep(getGatewayInternalBaseUrl(), this.bearerToken);
+    log.info('Guardian action expiry sweep started');
+
     log.info('Running in gateway-only ingress mode. Direct webhook routes disabled.');
     if (!isLoopbackHost(this.hostname)) {
       log.warn('RUNTIME_HTTP_HOST is not bound to loopback. This may expose the runtime to direct public access.');
     }
 
+    this.pairingStore.start();
+
     log.info({ port: this.actualPort, hostname: this.hostname, auth: !!this.bearerToken }, 'Runtime HTTP server listening');
   }
 
   async stop(): Promise<void> {
+    this.pairingStore.stop();
     stopGuardianExpirySweep();
+    stopGuardianActionSweep();
     if (this.retrySweepTimer) {
       clearInterval(this.retrySweepTimer);
       this.retrySweepTimer = null;
@@ -475,104 +300,51 @@ export class RuntimeHttpServer {
     }
   }
 
-  /**
-   * Constant-time comparison of two bearer tokens to prevent timing attacks.
-   */
-  private verifyToken(provided: string): boolean {
-    const expected = this.bearerToken!;
-    const a = Buffer.from(provided);
-    const b = Buffer.from(expected);
-    if (a.length !== b.length) return false;
-    return timingSafeEqual(a, b);
-  }
-
   private async handleRequest(req: Request, server: ReturnType<typeof Bun.serve>): Promise<Response> {
     const url = new URL(req.url);
     const path = url.pathname;
 
-    // Health checks are unauthenticated — they expose no sensitive data.
     if (path === '/healthz' && req.method === 'GET') {
-      return this.handleHealth();
+      return handleHealth();
+    }
+
+    // WebSocket upgrade for the Chrome extension browser relay.
+    if (path === '/v1/browser-relay' && req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+      return this.handleBrowserRelayUpgrade(req, server);
     }
 
     // WebSocket upgrade for ConversationRelay — before auth check because
     // Twilio WebSocket connections don't use bearer tokens.
     if (path.startsWith('/v1/calls/relay') && req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
-      // Only allow relay connections from private network peers.
-      // Primary check: actual peer address (cannot be spoofed) — accepts loopback
-      // and RFC 1918/4193 private addresses to support container deployments.
-      // Secondary check: Origin header (defense in depth).
-      if (!isPrivateNetworkPeer(server, req) || !isPrivateNetworkOrigin(req)) {
-        return Response.json(
-          { error: 'Direct relay access disabled — only private network peers allowed', code: 'GATEWAY_ONLY' },
-          { status: 403 },
-        );
-      }
-
-      const wsUrl = new URL(req.url);
-      const callSessionId = wsUrl.searchParams.get('callSessionId');
-      if (!callSessionId) {
-        return new Response('Missing callSessionId', { status: 400 });
-      }
-      const upgraded = server.upgrade(req, { data: { callSessionId } });
-      if (!upgraded) {
-        return new Response('WebSocket upgrade failed', { status: 500 });
-      }
-      // Bun handles the response after a successful upgrade.
-      // The RelayConnection is created in the websocket.open handler.
-      return undefined as unknown as Response;
+      return this.handleRelayUpgrade(req, server);
     }
 
-    // ── Twilio webhook endpoints — before auth check because Twilio
-    //    webhook POSTs don't include bearer tokens.
-    //    Supports /v1/calls/twilio/*, /v1/assistants/:id/calls/twilio/*,
-    //    and gateway-compatible /webhooks/twilio/* paths.
-    //    Validates X-Twilio-Signature to prevent unauthorized access. ──
-    const twilioMatch = path.match(TWILIO_WEBHOOK_RE);
-    const gatewayTwilioMatch = !twilioMatch ? path.match(TWILIO_GATEWAY_WEBHOOK_RE) : null;
-    const resolvedTwilioSubpath = twilioMatch
-      ? twilioMatch[1]
-      : gatewayTwilioMatch
-        ? GATEWAY_SUBPATH_MAP[gatewayTwilioMatch[1]]
-        : null;
-    if (resolvedTwilioSubpath && req.method === 'POST') {
-      const twilioSubpath = resolvedTwilioSubpath;
-
-      // Block direct Twilio webhook routes — must go through the gateway
-      if (GATEWAY_ONLY_BLOCKED_SUBPATHS.has(twilioSubpath)) {
-        return Response.json(
-          { error: 'Direct webhook access disabled. Use the gateway.', code: 'GATEWAY_ONLY' },
-          { status: 410 },
-        );
-      }
-
-      // Validate Twilio request signature before dispatching
-      const validation = await validateTwilioWebhook(req);
-      if (validation instanceof Response) return validation;
-
-      // Reconstruct request so handlers can read the body
-      const validatedReq = cloneRequestWithBody(req, validation.body);
+    // 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;
 
-      if (twilioSubpath === 'voice-webhook') {
-        return await handleVoiceWebhook(validatedReq);
-      }
-      if (twilioSubpath === 'status') {
-        return await handleStatusCallback(validatedReq);
-      }
-      if (twilioSubpath === 'connect-action') {
-        return await handleConnectAction(validatedReq);
-      }
+    // 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);
     }
 
     // Require bearer token when configured
-    if ((process.env.DISABLE_HTTP_AUTH ?? "").toLowerCase() !== "true" && this.bearerToken) {
-      const authHeader = req.headers.get('authorization');
-      const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : null;
-      if (!token || !this.verifyToken(token)) {
+    if (!isHttpAuthDisabled() && this.bearerToken) {
+      const token = extractBearerToken(req);
+      if (!token || !verifyBearerToken(token, this.bearerToken)) {
         return Response.json({ error: 'Unauthorized' }, { status: 401 });
       }
     }
 
+    // Pairing registration (bearer-authenticated)
+    if (path === '/v1/pairing/register' && req.method === 'POST') {
+      return await handlePairingRegister(req, this.pairingContext);
+    }
+
     // Serve shareable app pages
     const pagesMatch = path.match(/^\/pages\/([^/]+)$/);
     if (pagesMatch && req.method === 'GET') {
@@ -584,11 +356,9 @@ export class RuntimeHttpServer {
       }
     }
 
-    // ── Cloud sharing endpoints ───────────────────────────────────────
+    // Cloud sharing endpoints
     if (path === '/v1/apps/share' && req.method === 'POST') {
-      try {
-        return await handleShareApp(req);
-      } catch (err) {
+      try { return await handleShareApp(req); } catch (err) {
         log.error({ err }, 'Runtime HTTP handler error sharing app');
         return Response.json({ error: 'Internal server error' }, { status: 500 });
       }
@@ -598,17 +368,13 @@ export class RuntimeHttpServer {
     if (sharedTokenMatch) {
       const shareToken = sharedTokenMatch[1];
       if (req.method === 'GET') {
-        try {
-          return handleDownloadSharedApp(shareToken);
-        } catch (err) {
+        try { return handleDownloadSharedApp(shareToken); } catch (err) {
           log.error({ err, shareToken }, 'Runtime HTTP handler error downloading shared app');
           return Response.json({ error: 'Internal server error' }, { status: 500 });
         }
       }
       if (req.method === 'DELETE') {
-        try {
-          return handleDeleteSharedApp(shareToken);
-        } catch (err) {
+        try { return handleDeleteSharedApp(shareToken); } catch (err) {
           log.error({ err, shareToken }, 'Runtime HTTP handler error deleting shared app');
           return Response.json({ error: 'Internal server error' }, { status: 500 });
         }
@@ -617,27 +383,21 @@ export class RuntimeHttpServer {
 
     const sharedMetadataMatch = path.match(/^\/v1\/apps\/shared\/([^/]+)\/metadata$/);
     if (sharedMetadataMatch && req.method === 'GET') {
-      try {
-        return handleGetSharedAppMetadata(sharedMetadataMatch[1]);
-      } catch (err) {
+      try { return handleGetSharedAppMetadata(sharedMetadataMatch[1]); } catch (err) {
         log.error({ err, shareToken: sharedMetadataMatch[1] }, 'Runtime HTTP handler error getting shared app metadata');
         return Response.json({ error: 'Internal server error' }, { status: 500 });
       }
     }
 
-    // ── Secret management endpoint ─────────────────────────────────────
+    // Secret management endpoint
     if (path === '/v1/secrets' && req.method === 'POST') {
-      try {
-        return await handleAddSecret(req);
-      } catch (err) {
+      try { return await handleAddSecret(req); } catch (err) {
         log.error({ err }, 'Runtime HTTP handler error adding secret');
         return Response.json({ error: 'Internal server error' }, { status: 500 });
       }
     }
 
     // New assistant-less runtime routes: /v1/<endpoint>
-    // These supersede the legacy /v1/assistants/:assistantId/... shape.
-    // Paths already handled above (/v1/apps/..., /v1/secrets) will never reach here.
     const newRouteMatch = path.match(/^\/v1\/(?!assistants\/)(.+)$/);
     if (newRouteMatch) {
       return this.dispatchEndpoint(newRouteMatch[1], req, url);
@@ -655,10 +415,85 @@ export class RuntimeHttpServer {
     return this.dispatchEndpoint(endpoint, req, url, assistantId);
   }
 
+  private handleBrowserRelayUpgrade(req: Request, server: ReturnType<typeof Bun.serve>): Response {
+    if (!isLoopbackHost(new URL(req.url).hostname) && !isPrivateNetworkPeer(server, req)) {
+      return Response.json(
+        { error: 'Browser relay only accepts connections from localhost', code: 'LOCALHOST_ONLY' },
+        { status: 403 },
+      );
+    }
+
+    if ((process.env.DISABLE_HTTP_AUTH ?? '').toLowerCase() !== 'true' && this.bearerToken) {
+      const wsUrl = new URL(req.url);
+      const token = wsUrl.searchParams.get('token');
+      if (!token || !verifyBearerToken(token, this.bearerToken)) {
+        return Response.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+    }
+
+    const connectionId = crypto.randomUUID();
+    const upgraded = server.upgrade(req, {
+      data: { wsType: 'browser-relay', connectionId } satisfies BrowserRelayWebSocketData,
+    });
+    if (!upgraded) {
+      return new Response('WebSocket upgrade failed', { status: 500 });
+    }
+    return undefined as unknown as Response;
+  }
+
+  private handleRelayUpgrade(req: Request, server: ReturnType<typeof Bun.serve>): Response {
+    if (!isPrivateNetworkPeer(server, req) || !isPrivateNetworkOrigin(req)) {
+      return Response.json(
+        { error: 'Direct relay access disabled — only private network peers allowed', code: 'GATEWAY_ONLY' },
+        { status: 403 },
+      );
+    }
+
+    const wsUrl = new URL(req.url);
+    const callSessionId = wsUrl.searchParams.get('callSessionId');
+    if (!callSessionId) {
+      return new Response('Missing callSessionId', { status: 400 });
+    }
+    const upgraded = server.upgrade(req, { data: { callSessionId } });
+    if (!upgraded) {
+      return new Response('WebSocket upgrade failed', { status: 500 });
+    }
+    return undefined as unknown as Response;
+  }
+
+  private async handleTwilioWebhook(req: Request, path: string): Promise<Response | null> {
+    const twilioMatch = path.match(TWILIO_WEBHOOK_RE);
+    const gatewayTwilioMatch = !twilioMatch ? path.match(TWILIO_GATEWAY_WEBHOOK_RE) : null;
+    const resolvedTwilioSubpath = twilioMatch
+      ? twilioMatch[1]
+      : gatewayTwilioMatch
+        ? GATEWAY_SUBPATH_MAP[gatewayTwilioMatch[1]]
+        : null;
+    if (!resolvedTwilioSubpath || req.method !== 'POST') return null;
+
+    const twilioSubpath = resolvedTwilioSubpath;
+
+    if (GATEWAY_ONLY_BLOCKED_SUBPATHS.has(twilioSubpath)) {
+      return Response.json(
+        { error: 'Direct webhook access disabled. Use the gateway.', code: 'GATEWAY_ONLY' },
+        { status: 410 },
+      );
+    }
+
+    const validation = await validateTwilioWebhook(req);
+    if (validation instanceof Response) return validation;
+
+    const validatedReq = cloneRequestWithBody(req, validation.body);
+
+    if (twilioSubpath === 'voice-webhook') return await handleVoiceWebhook(validatedReq);
+    if (twilioSubpath === 'status') return await handleStatusCallback(validatedReq);
+    if (twilioSubpath === 'connect-action') return await handleConnectAction(validatedReq);
+
+    return null;
+  }
+
   /**
    * Dispatch a request to the appropriate endpoint handler.
-   * Used by both the new assistant-less routes (/v1/<endpoint>) and the
-   * legacy assistant-scoped routes (/v1/assistants/:assistantId/<endpoint>).
    */
   private async dispatchEndpoint(
     endpoint: string,
@@ -666,9 +501,21 @@ export class RuntimeHttpServer {
     url: URL,
     assistantId: string = 'self',
   ): Promise<Response> {
-    try {
-      if (endpoint === 'health' && req.method === 'GET') {
-        return this.handleHealth();
+    return withErrorHandling(endpoint, async () => {
+      if (endpoint === 'health' && req.method === 'GET') return handleHealth();
+
+      if (endpoint === 'browser-relay/status' && req.method === 'GET') {
+        return Response.json(extensionRelayServer.getStatus());
+      }
+
+      if (endpoint === 'browser-relay/command' && req.method === 'POST') {
+        try {
+          const body = await req.json() as Record<string, unknown>;
+          const resp = await extensionRelayServer.sendCommand(body as Omit<import('../browser-extension-relay/protocol.js').ExtensionCommand, 'id'>);
+          return Response.json(resp);
+        } catch (err) {
+          return Response.json({ success: false, error: err instanceof Error ? err.message : String(err) }, { status: 500 });
+        }
       }
 
       if (endpoint === 'conversations' && req.method === 'GET') {
@@ -682,6 +529,7 @@ export class RuntimeHttpServer {
         return Response.json({
           sessions: conversations.map((c) => {
             const binding = bindings.get(c.id);
+            const originChannel = parseChannelId(c.originChannel);
             return {
               id: c.id,
               title: c.title ?? 'Untitled',
@@ -696,15 +544,15 @@ export class RuntimeHttpServer {
                   username: binding.username,
                 },
               } : {}),
+              ...(originChannel ? { conversationOriginChannel: originChannel } : {}),
             };
           }),
           hasMore: offset + conversations.length < totalCount,
         });
       }
 
-      if (endpoint === 'messages' && req.method === 'GET') {
-        return handleListMessages(url, this.interfacesDir);
-      }
+      if (endpoint === 'messages' && req.method === 'GET') return handleListMessages(url, this.interfacesDir);
+      if (endpoint === 'search' && req.method === 'GET') return handleSearchConversations(url);
 
       if (endpoint === 'messages' && req.method === 'POST') {
         return await handleSendMessage(req, {
@@ -713,19 +561,11 @@ export class RuntimeHttpServer {
         });
       }
 
-      if (endpoint === 'attachments' && req.method === 'POST') {
-        return await handleUploadAttachment(req);
-      }
-
-      if (endpoint === 'attachments' && req.method === 'DELETE') {
-        return await handleDeleteAttachment(req);
-      }
+      if (endpoint === 'attachments' && req.method === 'POST') return await handleUploadAttachment(req);
+      if (endpoint === 'attachments' && req.method === 'DELETE') return await handleDeleteAttachment(req);
 
-      // Match attachments/:attachmentId
       const attachmentMatch = endpoint.match(/^attachments\/([^/]+)$/);
-      if (attachmentMatch && req.method === 'GET') {
-        return handleGetAttachment(attachmentMatch[1]);
-      }
+      if (attachmentMatch && req.method === 'GET') return handleGetAttachment(attachmentMatch[1]);
 
       if (endpoint === 'suggestion' && req.method === 'GET') {
         return await handleGetSuggestion(url, {
@@ -735,388 +575,93 @@ export class RuntimeHttpServer {
       }
 
       if (endpoint === 'runs' && req.method === 'POST') {
-        if (!this.runOrchestrator) {
-          return Response.json({ error: 'Run orchestration not configured' }, { status: 503 });
-        }
+        if (!this.runOrchestrator) return Response.json({ error: 'Run orchestration not configured' }, { status: 503 });
         return await handleCreateRun(req, this.runOrchestrator);
       }
 
-      // Match runs/:runId, runs/:runId/decision, runs/:runId/trust-rule, runs/:runId/secret
       const runsMatch = endpoint.match(/^runs\/([^/]+)(\/decision|\/trust-rule|\/secret)?$/);
       if (runsMatch) {
-        if (!this.runOrchestrator) {
-          return Response.json({ error: 'Run orchestration not configured' }, { status: 503 });
-        }
+        if (!this.runOrchestrator) return Response.json({ error: 'Run orchestration not configured' }, { status: 503 });
         const runId = runsMatch[1];
-        if (runsMatch[2] === '/decision' && req.method === 'POST') {
-          return await handleRunDecision(runId, req, this.runOrchestrator);
-        }
-        if (runsMatch[2] === '/secret' && req.method === 'POST') {
-          return await handleRunSecret(runId, req, this.runOrchestrator);
-        }
+        if (runsMatch[2] === '/decision' && req.method === 'POST') return await handleRunDecision(runId, req, this.runOrchestrator);
+        if (runsMatch[2] === '/secret' && req.method === 'POST') return await handleRunSecret(runId, req, this.runOrchestrator);
         if (runsMatch[2] === '/trust-rule' && req.method === 'POST') {
           const run = this.runOrchestrator.getRun(runId);
-          if (!run) {
-            return Response.json({ error: 'Run not found' }, { status: 404 });
-          }
+          if (!run) return Response.json({ error: 'Run not found' }, { status: 404 });
           return await handleAddTrustRule(runId, req);
         }
-        if (req.method === 'GET') {
-          return handleGetRun(runId, this.runOrchestrator);
-        }
+        if (req.method === 'GET') return handleGetRun(runId, this.runOrchestrator);
       }
 
       const interfacesMatch = endpoint.match(/^interfaces\/(.+)$/);
-      if (interfacesMatch && req.method === 'GET') {
-        return this.handleGetInterface(interfacesMatch[1]);
-      }
+      if (interfacesMatch && req.method === 'GET') return this.handleGetInterface(interfacesMatch[1]);
 
-      if (endpoint === 'channels/conversation' && req.method === 'DELETE') {
-        return await handleDeleteConversation(req, assistantId);
-      }
+      if (endpoint === 'channels/conversation' && req.method === 'DELETE') return await handleDeleteConversation(req, assistantId);
 
       if (endpoint === 'channels/inbound' && req.method === 'POST') {
-        const gatewayOriginSecret = process.env.RUNTIME_GATEWAY_ORIGIN_SECRET || undefined;
-        return await handleChannelInbound(req, this.processMessage, this.bearerToken, this.runOrchestrator, assistantId, gatewayOriginSecret);
-      }
-
-      if (endpoint === 'channels/delivery-ack' && req.method === 'POST') {
-        return await handleChannelDeliveryAck(req);
-      }
-
-      if (endpoint === 'channels/dead-letters' && req.method === 'GET') {
-        return handleListDeadLetters();
+        const gatewayOriginSecret = getRuntimeGatewayOriginSecret();
+        return await handleChannelInbound(req, this.processMessage, this.bearerToken, this.runOrchestrator, assistantId, gatewayOriginSecret, this.approvalCopyGenerator, this.approvalConversationGenerator);
       }
 
-      if (endpoint === 'channels/replay' && req.method === 'POST') {
-        return await handleReplayDeadLetters(req);
-      }
+      if (endpoint === 'channels/delivery-ack' && req.method === 'POST') return await handleChannelDeliveryAck(req);
+      if (endpoint === 'channels/dead-letters' && req.method === 'GET') return handleListDeadLetters();
+      if (endpoint === 'channels/replay' && req.method === 'POST') return await handleReplayDeadLetters(req);
 
-      // ── Call API routes ───────────────────────────────────────────
-      if (endpoint === 'calls/start' && req.method === 'POST') {
-        return await handleStartCall(req, assistantId);
-      }
+      if (endpoint === 'calls/start' && req.method === 'POST') return await handleStartCall(req, assistantId);
 
-      // Match calls/:callSessionId and calls/:callSessionId/cancel, calls/:callSessionId/answer, calls/:callSessionId/instruction
       const callsMatch = endpoint.match(/^calls\/([^/]+?)(\/cancel|\/answer|\/instruction)?$/);
       if (callsMatch) {
         const callSessionId = callsMatch[1];
-        // Skip known sub-paths that are handled elsewhere (twilio, relay)
         if (callSessionId !== 'twilio' && callSessionId !== 'relay' && callSessionId !== 'start') {
-          if (callsMatch[2] === '/cancel' && req.method === 'POST') {
-            return await handleCancelCall(req, callSessionId);
-          }
-          if (callsMatch[2] === '/answer' && req.method === 'POST') {
-            return await handleAnswerCall(req, callSessionId);
-          }
-          if (callsMatch[2] === '/instruction' && req.method === 'POST') {
-            return await handleInstructionCall(req, callSessionId);
-          }
-          if (!callsMatch[2] && req.method === 'GET') {
-            return handleGetCallStatus(callSessionId);
-          }
+          if (callsMatch[2] === '/cancel' && req.method === 'POST') return await handleCancelCall(req, callSessionId);
+          if (callsMatch[2] === '/answer' && req.method === 'POST') return await handleAnswerCall(req, callSessionId);
+          if (callsMatch[2] === '/instruction' && req.method === 'POST') return await handleInstructionCall(req, callSessionId);
+          if (!callsMatch[2] && req.method === 'GET') return handleGetCallStatus(callSessionId);
         }
       }
 
-      // ── Internal Twilio forwarding endpoints (gateway → runtime) ──
-      // These accept JSON payloads from the gateway (which already validated
-      // the Twilio signature) and reconstruct requests for the existing
-      // Twilio route handlers.
+      // Internal Twilio forwarding endpoints (gateway -> runtime)
       if (endpoint === 'internal/twilio/voice-webhook' && req.method === 'POST') {
-        const json = await req.json() as { params: Record<string, string>; originalUrl?: string };
+        const json = await req.json() as { params: Record<string, string>; originalUrl?: string; assistantId?: string };
         const formBody = new URLSearchParams(json.params).toString();
-        // Reconstruct request URL: keep the original URL query string (callSessionId)
         const reconstructedUrl = json.originalUrl ?? req.url;
-        const fakeReq = new Request(reconstructedUrl, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-          body: formBody,
-        });
-        return await handleVoiceWebhook(fakeReq);
+        const fakeReq = new Request(reconstructedUrl, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: formBody });
+        return await handleVoiceWebhook(fakeReq, json.assistantId);
       }
 
       if (endpoint === 'internal/twilio/status' && req.method === 'POST') {
         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,
-        });
+        const fakeReq = new Request(req.url, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: formBody });
         return await handleStatusCallback(fakeReq);
       }
 
       if (endpoint === 'internal/twilio/connect-action' && req.method === 'POST') {
         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,
-        });
+        const fakeReq = new Request(req.url, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: formBody });
         return await handleConnectAction(fakeReq);
       }
 
-      if (endpoint === 'identity' && req.method === 'GET') {
-        return this.handleGetIdentity();
-      }
-
-      if (endpoint === 'events' && req.method === 'GET') {
-        return handleSubscribeAssistantEvents(req, url);
-      }
+      if (endpoint === 'identity' && req.method === 'GET') return handleGetIdentity();
+      if (endpoint === 'events' && req.method === 'GET') return handleSubscribeAssistantEvents(req, url);
 
-      // ── Internal OAuth callback endpoint (gateway → runtime) ──
+      // Internal OAuth callback endpoint (gateway -> runtime)
       if (endpoint === 'internal/oauth/callback' && req.method === 'POST') {
         const json = await req.json() as { state: string; code?: string; error?: string };
-        if (!json.state) {
-          return Response.json({ error: 'Missing state parameter' }, { status: 400 });
-        }
+        if (!json.state) return Response.json({ error: 'Missing state parameter' }, { status: 400 });
         if (json.error) {
           const consumed = consumeCallbackError(json.state, json.error);
-          return consumed
-            ? Response.json({ ok: true })
-            : Response.json({ error: 'Unknown state' }, { status: 404 });
+          return consumed ? Response.json({ ok: true }) : Response.json({ error: 'Unknown state' }, { status: 404 });
         }
         if (json.code) {
           const consumed = consumeCallback(json.state, json.code);
-          return consumed
-            ? Response.json({ ok: true })
-            : Response.json({ error: 'Unknown state' }, { status: 404 });
+          return consumed ? Response.json({ ok: true }) : Response.json({ error: 'Unknown state' }, { status: 404 });
         }
         return Response.json({ error: 'Missing code or error parameter' }, { status: 400 });
       }
 
       return Response.json({ error: 'Not found', source: 'runtime' }, { status: 404 });
-    } catch (err) {
-      if (err instanceof IngressBlockedError) {
-        log.warn({ endpoint, detectedTypes: err.detectedTypes }, 'Blocked HTTP request containing secrets');
-        return Response.json({ error: err.message, code: err.code }, { status: 422 });
-      }
-      if (err instanceof ConfigError) {
-        log.warn({ err, endpoint }, 'Runtime HTTP config error');
-        return Response.json({ error: err.message, code: err.code }, { status: 422 });
-      }
-      log.error({ err, endpoint }, 'Runtime HTTP handler error');
-      const message = err instanceof Error ? err.message : 'Internal server error';
-      return Response.json({ error: message }, { status: 500 });
-    }
-  }
-
-  /**
-   * Periodically retry failed channel inbound events that have passed
-   * their exponential backoff delay.
-   */
-  private async sweepFailedEvents(): Promise<void> {
-    if (!this.processMessage) return;
-
-    const events = channelDeliveryStore.getRetryableEvents();
-    if (events.length === 0) return;
-
-    log.info({ count: events.length }, 'Retrying failed channel inbound events');
-
-    for (const event of events) {
-      if (!event.rawPayload) {
-        // No payload stored — can't replay, move to dead letter
-        channelDeliveryStore.recordProcessingFailure(
-          event.id,
-          new Error('No raw payload stored for replay'),
-        );
-        continue;
-      }
-
-      let payload: Record<string, unknown>;
-      try {
-        payload = JSON.parse(event.rawPayload) as Record<string, unknown>;
-      } catch {
-        channelDeliveryStore.recordProcessingFailure(
-          event.id,
-          new Error('Failed to parse stored raw payload'),
-        );
-        continue;
-      }
-
-      const content = typeof payload.content === 'string' ? payload.content.trim() : '';
-      const attachmentIds = Array.isArray(payload.attachmentIds) ? payload.attachmentIds as string[] : undefined;
-      const sourceChannel = payload.sourceChannel as string;
-      const sourceMetadata = payload.sourceMetadata as Record<string, unknown> | undefined;
-      const assistantId = typeof payload.assistantId === 'string'
-        ? payload.assistantId
-        : undefined;
-      const guardianContext = parseGuardianRuntimeContext(payload.guardianCtx);
-
-      const metadataHintsRaw = sourceMetadata?.hints;
-      const metadataHints = Array.isArray(metadataHintsRaw)
-        ? metadataHintsRaw.filter((h): h is string => typeof h === 'string' && h.trim().length > 0)
-        : [];
-      const metadataUxBrief = typeof sourceMetadata?.uxBrief === 'string' && sourceMetadata.uxBrief.trim().length > 0
-        ? sourceMetadata.uxBrief.trim()
-        : undefined;
-
-      try {
-        const { messageId: userMessageId } = await this.processMessage(
-          event.conversationId,
-          content,
-          attachmentIds,
-          {
-            transport: {
-              channelId: sourceChannel,
-              hints: metadataHints.length > 0 ? metadataHints : undefined,
-              uxBrief: metadataUxBrief,
-            },
-            assistantId,
-            guardianContext,
-          },
-        );
-        channelDeliveryStore.linkMessage(event.id, userMessageId);
-        channelDeliveryStore.markProcessed(event.id);
-        log.info({ eventId: event.id }, 'Successfully replayed failed channel event');
-
-        const replyCallbackUrl = typeof payload.replyCallbackUrl === 'string'
-          ? payload.replyCallbackUrl
-          : undefined;
-        if (replyCallbackUrl) {
-          const externalChatId = typeof payload.externalChatId === 'string'
-            ? payload.externalChatId
-            : undefined;
-          if (externalChatId) {
-            await this.deliverReplyViaCallback(
-              event.conversationId,
-              externalChatId,
-              replyCallbackUrl,
-              assistantId,
-            );
-          }
-        }
-      } catch (err) {
-        log.error({ err, eventId: event.id }, 'Retry failed for channel event');
-        channelDeliveryStore.recordProcessingFailure(event.id, err);
-      }
-    }
-  }
-
-  private async deliverReplyViaCallback(
-    conversationId: string,
-    externalChatId: string,
-    callbackUrl: string,
-    assistantId?: string,
-  ): Promise<void> {
-    const msgs = conversationStore.getMessages(conversationId);
-    for (let i = msgs.length - 1; i >= 0; i--) {
-      if (msgs[i].role === 'assistant') {
-        let parsed: unknown;
-        try { parsed = JSON.parse(msgs[i].content); } catch { parsed = msgs[i].content; }
-        const rendered = renderHistoryContent(parsed);
-
-        const linked = attachmentsStore.getAttachmentMetadataForMessage(msgs[i].id);
-        const replyAttachments = linked.map((a) => ({
-          id: a.id,
-          filename: a.originalFilename,
-          mimeType: a.mimeType,
-          sizeBytes: a.sizeBytes,
-          kind: a.kind,
-        }));
-
-        if (rendered.text || replyAttachments.length > 0) {
-          await deliverChannelReply(callbackUrl, {
-            chatId: externalChatId,
-            text: rendered.text || undefined,
-            attachments: replyAttachments.length > 0 ? replyAttachments : undefined,
-            assistantId,
-          }, this.bearerToken);
-        }
-        break;
-      }
-    }
-  }
-
-  private handleGetIdentity(): Response {
-    const identityPath = getWorkspacePromptPath('IDENTITY.md');
-    if (!existsSync(identityPath)) {
-      return Response.json({ error: 'IDENTITY.md not found' }, { status: 404 });
-    }
-
-    const content = readFileSync(identityPath, 'utf-8');
-    const fields: Record<string, string> = {};
-    for (const line of content.split('\n')) {
-      const trimmed = line.trim();
-      const lower = trimmed.toLowerCase();
-      const extract = (prefix: string): string | null => {
-        if (!lower.startsWith(prefix)) return null;
-        return trimmed.split(':**').pop()?.trim() ?? null;
-      };
-
-      const name = extract('- **name:**');
-      if (name) { fields.name = name; continue; }
-      const role = extract('- **role:**');
-      if (role) { fields.role = role; continue; }
-      const personality = extract('- **personality:**') ?? extract('- **vibe:**');
-      if (personality) { fields.personality = personality; continue; }
-      const emoji = extract('- **emoji:**');
-      if (emoji) { fields.emoji = emoji; continue; }
-      const home = extract('- **home:**');
-      if (home) { fields.home = home; continue; }
-    }
-
-    // Read version from package.json
-    let version: string | undefined;
-    try {
-      const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
-      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-      version = pkg.version;
-    } catch {
-      // ignore
-    }
-
-    // Read createdAt from IDENTITY.md file birthtime
-    let createdAt: string | undefined;
-    try {
-      const stats = statSync(identityPath);
-      createdAt = stats.birthtime.toISOString();
-    } catch {
-      // ignore
-    }
-
-    // Read lockfile for assistantId, cloud, and originSystem
-    let assistantId: string | undefined;
-    let cloud: string | undefined;
-    let originSystem: string | undefined;
-    try {
-      const lockData = readLockfile();
-      const assistants = lockData?.assistants as Array<Record<string, unknown>> | undefined;
-      if (assistants && assistants.length > 0) {
-        // Use the most recently hatched assistant
-        const sorted = [...assistants].sort((a, b) => {
-          const dateA = new Date(a.hatchedAt as string || 0).getTime();
-          const dateB = new Date(b.hatchedAt as string || 0).getTime();
-          return dateB - dateA;
-        });
-        const latest = sorted[0];
-        assistantId = latest.assistantId as string | undefined;
-        cloud = latest.cloud as string | undefined;
-        originSystem = cloud === 'local' ? 'local' : cloud;
-      }
-    } catch {
-      // ignore — lockfile may not exist
-    }
-
-    return Response.json({
-      name: fields.name ?? '',
-      role: fields.role ?? '',
-      personality: fields.personality ?? '',
-      emoji: fields.emoji ?? '',
-      home: fields.home ?? '',
-      version,
-      assistantId,
-      createdAt,
-      originSystem,
-    });
-  }
-
-  private handleHealth(): Response {
-    return Response.json({
-      status: 'healthy',
-      timestamp: new Date().toISOString(),
-      disk: getDiskSpaceInfo(),
     });
   }
 
@@ -1125,7 +670,6 @@ export class RuntimeHttpServer {
       return Response.json({ error: 'Interface not found' }, { status: 404 });
     }
     const fullPath = resolve(this.interfacesDir, interfacePath);
-    // Enforce directory boundary so prefix-sibling paths (e.g. "interfaces-other/") are rejected
     if (
       (fullPath !== this.interfacesDir && !fullPath.startsWith(this.interfacesDir + '/')) ||
       !existsSync(fullPath)