@openclaw/voice-call 2026.3.13 → 2026.5.2-beta.1

package/src/webhook.ts

@@ -1,29 +1,82 @@
 import http from "node:http";
 import { URL } from "node:url";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveConfiguredCapabilityProvider } from "openclaw/plugin-sdk/provider-selection-runtime";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import {
+  createWebhookInFlightLimiter,
+  WEBHOOK_BODY_READ_DEFAULTS,
+} from "openclaw/plugin-sdk/webhook-ingress";
 import {
   isRequestBodyLimitError,
   readRequestBodyWithLimit,
   requestBodyErrorToText,
-} from "openclaw/plugin-sdk/voice-call";
-import { normalizeVoiceCallConfig, type VoiceCallConfig } from "./config.js";
-import type { CoreConfig } from "./core-bridge.js";
+} from "../api.js";
+import { isAllowlistedCaller, normalizePhoneNumber } from "./allowlist.js";
+import {
+  normalizeVoiceCallConfig,
+  resolveVoiceCallEffectiveConfig,
+  type VoiceCallConfig,
+} from "./config.js";
+import type { CoreAgentDeps, CoreConfig } from "./core-bridge.js";
+import { getHeader } from "./http-headers.js";
 import type { CallManager } from "./manager.js";
 import type { MediaStreamConfig } from "./media-stream.js";
 import { MediaStreamHandler } from "./media-stream.js";
 import type { VoiceCallProvider } from "./providers/base.js";
-import { OpenAIRealtimeSTTProvider } from "./providers/stt-openai-realtime.js";
+import { isProviderStatusTerminal } from "./providers/shared/call-status.js";
 import type { TwilioProvider } from "./providers/twilio.js";
-import type { NormalizedEvent, WebhookContext } from "./types.js";
+import type { CallRecord, NormalizedEvent, WebhookContext } from "./types.js";
+import type { WebhookResponsePayload } from "./webhook.types.js";
+import type { RealtimeCallHandler } from "./webhook/realtime-handler.js";
 import { startStaleCallReaper } from "./webhook/stale-call-reaper.js";
 
-const MAX_WEBHOOK_BODY_BYTES = 1024 * 1024;
-
-type WebhookResponsePayload = {
-  statusCode: number;
-  body: string;
-  headers?: Record<string, string>;
+const MAX_WEBHOOK_BODY_BYTES = WEBHOOK_BODY_READ_DEFAULTS.preAuth.maxBytes;
+const WEBHOOK_BODY_TIMEOUT_MS = WEBHOOK_BODY_READ_DEFAULTS.preAuth.timeoutMs;
+const MISSING_REMOTE_ADDRESS_IN_FLIGHT_KEY = "__voice_call_no_remote__";
+const STREAM_DISCONNECT_HANGUP_GRACE_MS = 2000;
+const TRANSCRIPT_LOG_MAX_CHARS = 200;
+
+type RealtimeTranscriptionRuntime = typeof import("./realtime-transcription.runtime.js");
+type ResponseGeneratorModule = typeof import("./response-generator.js");
+type Logger = {
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+  debug?: (message: string) => void;
 };
 
+let realtimeTranscriptionRuntimePromise: Promise<RealtimeTranscriptionRuntime> | undefined;
+let responseGeneratorModulePromise: Promise<ResponseGeneratorModule> | undefined;
+
+function loadRealtimeTranscriptionRuntime(): Promise<RealtimeTranscriptionRuntime> {
+  realtimeTranscriptionRuntimePromise ??= import("./realtime-transcription.runtime.js");
+  return realtimeTranscriptionRuntimePromise;
+}
+
+function loadResponseGeneratorModule(): Promise<ResponseGeneratorModule> {
+  responseGeneratorModulePromise ??= import("./response-generator.js");
+  return responseGeneratorModulePromise;
+}
+
+type WebhookHeaderGateResult =
+  | { ok: true }
+  | {
+      ok: false;
+      reason: string;
+    };
+
+function sanitizeTranscriptForLog(value: string): string {
+  const sanitized = value
+    .replace(/\p{Cc}/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (sanitized.length <= TRANSCRIPT_LOG_MAX_CHARS) {
+    return sanitized;
+  }
+  return `${sanitized.slice(0, TRANSCRIPT_LOG_MAX_CHARS)}...`;
+}
+
 function buildRequestUrl(
   requestUrl: string | undefined,
   requestHost: string | undefined,
@@ -32,6 +85,55 @@ function buildRequestUrl(
   return new URL(requestUrl ?? "/", `http://${requestHost ?? fallbackHost}`);
 }
 
+function normalizeProxyIp(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const unwrapped =
+    trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed;
+  const normalized = unwrapped.toLowerCase();
+  const mappedIpv4Prefix = "::ffff:";
+  if (normalized.startsWith(mappedIpv4Prefix)) {
+    const mappedIpv4 = normalized.slice(mappedIpv4Prefix.length);
+    if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(mappedIpv4)) {
+      return mappedIpv4;
+    }
+  }
+  return normalized;
+}
+
+function resolveForwardedClientIp(
+  request: http.IncomingMessage,
+  trustedProxyIPs: readonly string[],
+): string | undefined {
+  const normalizedTrustedProxyIps = new Set(
+    trustedProxyIPs.map((ip) => normalizeProxyIp(ip)).filter((ip): ip is string => Boolean(ip)),
+  );
+  const forwardedFor = getHeader(request.headers, "x-forwarded-for");
+  if (forwardedFor) {
+    const forwardedIps = forwardedFor
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean);
+    if (forwardedIps.length > 0) {
+      if (normalizedTrustedProxyIps.size === 0) {
+        return forwardedIps[0];
+      }
+      for (let index = forwardedIps.length - 1; index >= 0; index -= 1) {
+        const hop = forwardedIps[index];
+        if (!normalizedTrustedProxyIps.has(normalizeProxyIp(hop) ?? "")) {
+          return hop;
+        }
+      }
+      return forwardedIps[0];
+    }
+  }
+
+  const realIp = getHeader(request.headers, "x-real-ip")?.trim();
+  return realIp || undefined;
+}
+
 function normalizeWebhookResponse(parsed: {
   statusCode?: number;
   providerResponseHeaders?: Record<string, string>;
@@ -44,6 +146,14 @@ function normalizeWebhookResponse(parsed: {
   };
 }
 
+function buildRealtimeRejectedTwiML(): WebhookResponsePayload {
+  return {
+    statusCode: 200,
+    headers: { "Content-Type": "text/xml" },
+    body: '<?xml version="1.0" encoding="UTF-8"?><Response><Reject reason="rejected" /></Response>',
+  };
+}
+
 /**
  * HTTP server for receiving voice call webhooks from providers.
  * Supports WebSocket upgrades for media streams when streaming is enabled.
@@ -51,30 +161,45 @@ function normalizeWebhookResponse(parsed: {
 export class VoiceCallWebhookServer {
   private server: http.Server | null = null;
   private listeningUrl: string | null = null;
+  private startPromise: Promise<string> | null = null;
   private config: VoiceCallConfig;
   private manager: CallManager;
   private provider: VoiceCallProvider;
   private coreConfig: CoreConfig | null;
+  private fullConfig: OpenClawConfig | null;
+  private agentRuntime: CoreAgentDeps | null;
+  private logger: Logger;
   private stopStaleCallReaper: (() => void) | null = null;
+  private readonly webhookInFlightLimiter = createWebhookInFlightLimiter();
 
   /** Media stream handler for bidirectional audio (when streaming enabled) */
   private mediaStreamHandler: MediaStreamHandler | null = null;
+  /** Delayed auto-hangup timers keyed by provider call ID after stream disconnect. */
+  private pendingDisconnectHangups = new Map<string, ReturnType<typeof setTimeout>>();
+  /** Realtime voice handler for duplex provider bridges. */
+  private realtimeHandler: RealtimeCallHandler | null = null;
 
   constructor(
     config: VoiceCallConfig,
     manager: CallManager,
     provider: VoiceCallProvider,
     coreConfig?: CoreConfig,
+    fullConfig?: OpenClawConfig,
+    agentRuntime?: CoreAgentDeps,
+    logger?: Logger,
   ) {
     this.config = normalizeVoiceCallConfig(config);
     this.manager = manager;
     this.provider = provider;
     this.coreConfig = coreConfig ?? null;
-
-    // Initialize media stream handler if streaming is enabled
-    if (this.config.streaming.enabled) {
-      this.initializeMediaStreaming();
-    }
+    this.fullConfig = fullConfig ?? null;
+    this.agentRuntime = agentRuntime ?? null;
+    this.logger = logger ?? {
+      info: console.log,
+      warn: console.warn,
+      error: console.error,
+      debug: console.debug,
+    };
   }
 
   /**
@@ -84,31 +209,125 @@ export class VoiceCallWebhookServer {
     return this.mediaStreamHandler;
   }
 
-  /**
-   * Initialize media streaming with OpenAI Realtime STT.
-   */
-  private initializeMediaStreaming(): void {
-    const streaming = this.config.streaming;
-    const apiKey = streaming.openaiApiKey ?? process.env.OPENAI_API_KEY;
+  getRealtimeHandler(): RealtimeCallHandler | null {
+    return this.realtimeHandler;
+  }
+
+  speakRealtime(callId: string, instructions: string): { success: boolean; error?: string } {
+    if (!this.realtimeHandler) {
+      return { success: false, error: "Realtime voice handler is not configured" };
+    }
+    return this.realtimeHandler.speak(callId, instructions);
+  }
 
-    if (!apiKey) {
-      console.warn("[voice-call] Streaming enabled but no OpenAI API key found");
+  setRealtimeHandler(handler: RealtimeCallHandler): void {
+    this.realtimeHandler = handler;
+  }
+
+  private clearPendingDisconnectHangup(providerCallId: string): void {
+    const existing = this.pendingDisconnectHangups.get(providerCallId);
+    if (!existing) {
       return;
     }
+    clearTimeout(existing);
+    this.pendingDisconnectHangups.delete(providerCallId);
+  }
 
-    const sttProvider = new OpenAIRealtimeSTTProvider({
-      apiKey,
-      model: streaming.sttModel,
-      silenceDurationMs: streaming.silenceDurationMs,
-      vadThreshold: streaming.vadThreshold,
+  private resolveMediaStreamClientIp(request: http.IncomingMessage): string | undefined {
+    const remoteIp = request.socket.remoteAddress ?? undefined;
+    const trustedProxyIPs = this.config.webhookSecurity.trustedProxyIPs.filter(Boolean);
+    const normalizedTrustedProxyIps = new Set(
+      trustedProxyIPs.map((ip) => normalizeProxyIp(ip)).filter((ip): ip is string => Boolean(ip)),
+    );
+    const normalizedRemoteIp = normalizeProxyIp(remoteIp);
+    const fromTrustedProxy =
+      normalizedTrustedProxyIps.size > 0 &&
+      normalizedRemoteIp !== undefined &&
+      normalizedTrustedProxyIps.has(normalizedRemoteIp);
+    const shouldTrustForwardingHeaders =
+      this.config.webhookSecurity.trustForwardingHeaders && fromTrustedProxy;
+
+    if (shouldTrustForwardingHeaders) {
+      const forwardedIp = resolveForwardedClientIp(request, trustedProxyIPs);
+      if (forwardedIp) {
+        return forwardedIp;
+      }
+    }
+
+    return remoteIp;
+  }
+
+  private shouldSuppressBargeInForInitialMessage(call: CallRecord | undefined): boolean {
+    if (!call || call.direction !== "outbound") {
+      return false;
+    }
+
+    // Suppress only while the initial greeting is actively being played.
+    // If playback fails and the call leaves "speaking", do not block auto-response.
+    if (call.state !== "speaking") {
+      return false;
+    }
+
+    const mode = (call.metadata?.mode as string | undefined) ?? "conversation";
+    if (mode !== "conversation") {
+      return false;
+    }
+
+    const initialMessage = normalizeOptionalString(call.metadata?.initialMessage) ?? "";
+    return initialMessage.length > 0;
+  }
+
+  /**
+   * Initialize media streaming with the selected realtime transcription provider.
+   */
+  private async initializeMediaStreaming(): Promise<void> {
+    const streaming = this.config.streaming;
+    const pluginConfig =
+      this.fullConfig ?? (this.coreConfig as unknown as OpenClawConfig | undefined);
+    const { getRealtimeTranscriptionProvider, listRealtimeTranscriptionProviders } =
+      await loadRealtimeTranscriptionRuntime();
+    const resolution = resolveConfiguredCapabilityProvider({
+      configuredProviderId: streaming.provider,
+      providerConfigs: streaming.providers,
+      cfg: pluginConfig,
+      cfgForResolve: pluginConfig ?? ({} as OpenClawConfig),
+      getConfiguredProvider: (providerId) =>
+        getRealtimeTranscriptionProvider(providerId, pluginConfig),
+      listProviders: () => listRealtimeTranscriptionProviders(pluginConfig),
+      resolveProviderConfig: ({ provider, cfg, rawConfig }) =>
+        provider.resolveConfig?.({ cfg, rawConfig }) ?? rawConfig,
+      isProviderConfigured: ({ provider, cfg, providerConfig }) =>
+        provider.isConfigured({ cfg, providerConfig }),
     });
+    if (!resolution.ok && resolution.code === "missing-configured-provider") {
+      console.warn(
+        `[voice-call] Streaming enabled but realtime transcription provider "${resolution.configuredProviderId}" is not registered`,
+      );
+      return;
+    }
+    if (!resolution.ok && resolution.code === "no-registered-provider") {
+      console.warn(
+        "[voice-call] Streaming enabled but no realtime transcription provider is registered",
+      );
+      return;
+    }
+    if (!resolution.ok) {
+      console.warn(
+        `[voice-call] Streaming enabled but provider "${resolution.provider?.id}" is not configured`,
+      );
+      return;
+    }
+    const provider = resolution.provider;
+    const providerConfig = resolution.providerConfig;
 
     const streamConfig: MediaStreamConfig = {
-      sttProvider,
+      transcriptionProvider: provider,
+      providerConfig,
       preStartTimeoutMs: streaming.preStartTimeoutMs,
       maxPendingConnections: streaming.maxPendingConnections,
       maxPendingConnectionsPerIp: streaming.maxPendingConnectionsPerIp,
       maxConnections: streaming.maxConnections,
+      resolveClientIp: (request) => this.resolveMediaStreamClientIp(request),
       shouldAcceptStream: ({ callId, token }) => {
         const call = this.manager.getCallByProviderCallId(callId);
         if (!call) {
@@ -124,19 +343,27 @@ export class VoiceCallWebhookServer {
         return true;
       },
       onTranscript: (providerCallId, transcript) => {
-        console.log(`[voice-call] Transcript for ${providerCallId}: ${transcript}`);
-
-        // Clear TTS queue on barge-in (user started speaking, interrupt current playback)
-        if (this.provider.name === "twilio") {
-          (this.provider as TwilioProvider).clearTtsQueue(providerCallId);
-        }
-
-        // Look up our internal call ID from the provider call ID
+        const safeTranscript = sanitizeTranscriptForLog(transcript);
+        console.log(
+          `[voice-call] Transcript for ${providerCallId}: ${safeTranscript} (chars=${transcript.length})`,
+        );
         const call = this.manager.getCallByProviderCallId(providerCallId);
         if (!call) {
           console.warn(`[voice-call] No active call found for provider ID: ${providerCallId}`);
           return;
         }
+        const suppressBargeIn = this.shouldSuppressBargeInForInitialMessage(call);
+        if (suppressBargeIn) {
+          console.log(
+            `[voice-call] Ignoring barge transcript while initial message is still playing (${providerCallId})`,
+          );
+          return;
+        }
+
+        // Clear TTS queue on barge-in (user started speaking, interrupt current playback)
+        if (this.provider.name === "twilio") {
+          (this.provider as TwilioProvider).clearTtsQueue(providerCallId);
+        }
 
         // Create a speech event and process it through the manager
         const event: NormalizedEvent = {
@@ -160,44 +387,63 @@ export class VoiceCallWebhookServer {
         }
       },
       onSpeechStart: (providerCallId) => {
-        if (this.provider.name === "twilio") {
-          (this.provider as TwilioProvider).clearTtsQueue(providerCallId);
+        if (this.provider.name !== "twilio") {
+          return;
+        }
+        const call = this.manager.getCallByProviderCallId(providerCallId);
+        if (this.shouldSuppressBargeInForInitialMessage(call)) {
+          return;
         }
+        (this.provider as TwilioProvider).clearTtsQueue(providerCallId);
       },
       onPartialTranscript: (callId, partial) => {
-        console.log(`[voice-call] Partial for ${callId}: ${partial}`);
+        const safePartial = sanitizeTranscriptForLog(partial);
+        console.log(`[voice-call] Partial for ${callId}: ${safePartial} (chars=${partial.length})`);
       },
       onConnect: (callId, streamSid) => {
         console.log(`[voice-call] Media stream connected: ${callId} -> ${streamSid}`);
+        this.clearPendingDisconnectHangup(callId);
+
         // Register stream with provider for TTS routing
         if (this.provider.name === "twilio") {
           (this.provider as TwilioProvider).registerCallStream(callId, streamSid);
         }
-
-        // Speak initial message if one was provided when call was initiated
-        // Use setTimeout to allow stream setup to complete
-        setTimeout(() => {
-          this.manager.speakInitialMessage(callId).catch((err) => {
-            console.warn(`[voice-call] Failed to speak initial message:`, err);
-          });
-        }, 500);
       },
-      onDisconnect: (callId) => {
-        console.log(`[voice-call] Media stream disconnected: ${callId}`);
-        // Auto-end call when media stream disconnects to prevent stuck calls.
-        // Without this, calls can remain active indefinitely after the stream closes.
-        const disconnectedCall = this.manager.getCallByProviderCallId(callId);
-        if (disconnectedCall) {
+      onTranscriptionReady: (callId) => {
+        this.manager.speakInitialMessage(callId).catch((err) => {
+          console.warn(`[voice-call] Failed to speak initial message:`, err);
+        });
+      },
+      onDisconnect: (callId, streamSid) => {
+        console.log(`[voice-call] Media stream disconnected: ${callId} (${streamSid})`);
+        if (this.provider.name === "twilio") {
+          (this.provider as TwilioProvider).unregisterCallStream(callId, streamSid);
+        }
+
+        this.clearPendingDisconnectHangup(callId);
+        const timer = setTimeout(() => {
+          this.pendingDisconnectHangups.delete(callId);
+          const disconnectedCall = this.manager.getCallByProviderCallId(callId);
+          if (!disconnectedCall) {
+            return;
+          }
+
+          if (this.provider.name === "twilio") {
+            const twilio = this.provider as TwilioProvider;
+            if (twilio.hasRegisteredStream(callId)) {
+              return;
+            }
+          }
+
           console.log(
-            `[voice-call] Auto-ending call ${disconnectedCall.callId} on stream disconnect`,
+            `[voice-call] Auto-ending call ${disconnectedCall.callId} after stream disconnect grace`,
           );
           void this.manager.endCall(disconnectedCall.callId).catch((err) => {
             console.warn(`[voice-call] Failed to auto-end call ${disconnectedCall.callId}:`, err);
           });
-        }
-        if (this.provider.name === "twilio") {
-          (this.provider as TwilioProvider).unregisterCallStream(callId);
-        }
+        }, STREAM_DISCONNECT_HANGUP_GRACE_MS);
+        timer.unref?.();
+        this.pendingDisconnectHangups.set(callId, timer);
       },
     };
 
@@ -220,7 +466,15 @@ export class VoiceCallWebhookServer {
       return this.listeningUrl ?? this.resolveListeningUrl(bind, webhookPath);
     }
 
-    return new Promise((resolve, reject) => {
+    if (this.config.streaming.enabled && !this.mediaStreamHandler) {
+      await this.initializeMediaStreaming();
+    }
+
+    if (this.startPromise) {
+      return this.startPromise;
+    }
+
+    this.startPromise = new Promise((resolve, reject) => {
       this.server = http.createServer((req, res) => {
         this.handleRequest(req, res, webhookPath).catch((err) => {
           console.error("[voice-call] Webhook error:", err);
@@ -229,12 +483,15 @@ export class VoiceCallWebhookServer {
         });
       });
 
-      // Handle WebSocket upgrades for media streams
-      if (this.mediaStreamHandler) {
+      // Handle WebSocket upgrades for realtime voice and media streams.
+      if (this.realtimeHandler || this.mediaStreamHandler) {
         this.server.on("upgrade", (request, socket, head) => {
+          if (this.realtimeHandler && this.isRealtimeWebSocketUpgrade(request)) {
+            this.realtimeHandler.handleWebSocketUpgrade(request, socket, head);
+            return;
+          }
           const path = this.getUpgradePathname(request);
-          if (path === streamPath) {
-            console.log("[voice-call] WebSocket upgrade for media stream");
+          if (path === streamPath && this.mediaStreamHandler) {
             this.mediaStreamHandler?.handleUpgrade(request, socket, head);
           } else {
             socket.destroy();
@@ -242,17 +499,23 @@ export class VoiceCallWebhookServer {
         });
       }
 
-      this.server.on("error", reject);
+      this.server.on("error", (err) => {
+        this.server = null;
+        this.listeningUrl = null;
+        this.startPromise = null;
+        reject(err);
+      });
 
       this.server.listen(port, bind, () => {
         const url = this.resolveListeningUrl(bind, webhookPath);
         this.listeningUrl = url;
-        console.log(`[voice-call] Webhook server listening on ${url}`);
+        this.startPromise = null;
+        this.logger.info(`[voice-call] Webhook server listening on ${url}`);
         if (this.mediaStreamHandler) {
           const address = this.server?.address();
           const actualPort =
             address && typeof address === "object" ? address.port : this.config.serve.port;
-          console.log(
+          this.logger.info(
             `[voice-call] Media stream WebSocket on ws://${bind}:${actualPort}${streamPath}`,
           );
         }
@@ -265,12 +528,21 @@ export class VoiceCallWebhookServer {
         });
       });
     });
+
+    return this.startPromise;
   }
 
   /**
    * Stop the webhook server.
    */
   async stop(): Promise<void> {
+    for (const timer of this.pendingDisconnectHangups.values()) {
+      clearTimeout(timer);
+    }
+    this.pendingDisconnectHangups.clear();
+    this.webhookInFlightLimiter.clear();
+    this.startPromise = null;
+
     if (this.stopStaleCallReaper) {
       this.stopStaleCallReaper();
       this.stopStaleCallReaper = null;
@@ -364,49 +636,189 @@ export class VoiceCallWebhookServer {
       return { statusCode: 405, body: "Method Not Allowed" };
     }
 
-    let body = "";
+    const headerGate = this.verifyPreAuthWebhookHeaders(req.headers);
+    if (!headerGate.ok) {
+      console.warn(`[voice-call] Webhook rejected before body read: ${headerGate.reason}`);
+      return { statusCode: 401, body: "Unauthorized" };
+    }
+
+    // createWebhookInFlightLimiter intentionally treats an empty key as fail-open.
+    // Missing socket metadata must still share one bucket instead of bypassing
+    // the pre-auth limiter entirely.
+    const remoteAddress = req.socket.remoteAddress;
+    if (!remoteAddress) {
+      console.warn(
+        `[voice-call] Webhook accepted with no remote address; using shared fallback in-flight key`,
+      );
+    }
+    const inFlightKey = remoteAddress || MISSING_REMOTE_ADDRESS_IN_FLIGHT_KEY;
+    if (!this.webhookInFlightLimiter.tryAcquire(inFlightKey)) {
+      console.warn(`[voice-call] Webhook rejected before body read: too many in-flight requests`);
+      return { statusCode: 429, body: "Too Many Requests" };
+    }
+
     try {
-      body = await this.readBody(req, MAX_WEBHOOK_BODY_BYTES);
-    } catch (err) {
-      if (isRequestBodyLimitError(err, "PAYLOAD_TOO_LARGE")) {
-        return { statusCode: 413, body: "Payload Too Large" };
+      let body = "";
+      try {
+        body = await this.readBody(req, MAX_WEBHOOK_BODY_BYTES, WEBHOOK_BODY_TIMEOUT_MS);
+      } catch (err) {
+        if (isRequestBodyLimitError(err, "PAYLOAD_TOO_LARGE")) {
+          return { statusCode: 413, body: "Payload Too Large" };
+        }
+        if (isRequestBodyLimitError(err, "REQUEST_BODY_TIMEOUT")) {
+          return { statusCode: 408, body: requestBodyErrorToText("REQUEST_BODY_TIMEOUT") };
+        }
+        throw err;
+      }
+
+      const ctx: WebhookContext = {
+        headers: req.headers as Record<string, string | string[] | undefined>,
+        rawBody: body,
+        url: url.toString(),
+        method: "POST",
+        query: Object.fromEntries(url.searchParams),
+        remoteAddress: req.socket.remoteAddress ?? undefined,
+      };
+
+      const verification = this.provider.verifyWebhook(ctx);
+      if (!verification.ok) {
+        console.warn(`[voice-call] Webhook verification failed: ${verification.reason}`);
+        return { statusCode: 401, body: "Unauthorized" };
       }
-      if (isRequestBodyLimitError(err, "REQUEST_BODY_TIMEOUT")) {
-        return { statusCode: 408, body: requestBodyErrorToText("REQUEST_BODY_TIMEOUT") };
+      if (!verification.verifiedRequestKey) {
+        console.warn("[voice-call] Webhook verification succeeded without request identity key");
+        return { statusCode: 401, body: "Unauthorized" };
       }
-      throw err;
+
+      const initialTwiML = this.provider.consumeInitialTwiML?.(ctx);
+      if (initialTwiML !== undefined && initialTwiML !== null) {
+        const params = new URLSearchParams(ctx.rawBody);
+        console.log(
+          `[voice-call] Serving provider initial TwiML before realtime handling (callSid=${params.get("CallSid") ?? "unknown"}, direction=${params.get("Direction") ?? "unknown"})`,
+        );
+        return {
+          statusCode: 200,
+          headers: { "Content-Type": "application/xml" },
+          body: initialTwiML,
+        };
+      }
+
+      const realtimeParams = this.getRealtimeTwimlParams(ctx);
+      if (realtimeParams) {
+        const direction = realtimeParams.get("Direction");
+        const isInboundRealtimeRequest = !direction || direction === "inbound";
+        if (isInboundRealtimeRequest && !this.shouldAcceptRealtimeInboundRequest(realtimeParams)) {
+          console.log("[voice-call] Realtime inbound call rejected before stream setup");
+          return buildRealtimeRejectedTwiML();
+        }
+        console.log(
+          `[voice-call] Serving realtime TwiML for Twilio call ${realtimeParams.get("CallSid") ?? "unknown"} (direction=${direction ?? "unknown"})`,
+        );
+        return this.realtimeHandler!.buildTwiMLPayload(req, realtimeParams);
+      }
+
+      const parsed = this.provider.parseWebhookEvent(ctx, {
+        verifiedRequestKey: verification.verifiedRequestKey,
+      });
+
+      if (verification.isReplay) {
+        console.warn("[voice-call] Replay detected; skipping event side effects");
+      } else {
+        this.processParsedEvents(parsed.events);
+      }
+
+      return normalizeWebhookResponse(parsed);
+    } finally {
+      this.webhookInFlightLimiter.release(inFlightKey);
     }
+  }
 
-    const ctx: WebhookContext = {
-      headers: req.headers as Record<string, string | string[] | undefined>,
-      rawBody: body,
-      url: url.toString(),
-      method: "POST",
-      query: Object.fromEntries(url.searchParams),
-      remoteAddress: req.socket.remoteAddress ?? undefined,
-    };
+  private verifyPreAuthWebhookHeaders(headers: http.IncomingHttpHeaders): WebhookHeaderGateResult {
+    if (this.config.skipSignatureVerification) {
+      return { ok: true };
+    }
+    switch (this.provider.name) {
+      case "telnyx": {
+        const signature = getHeader(headers, "telnyx-signature-ed25519");
+        const timestamp = getHeader(headers, "telnyx-timestamp");
+        if (signature && timestamp) {
+          return { ok: true };
+        }
+        return { ok: false, reason: "missing Telnyx signature or timestamp header" };
+      }
+      case "twilio":
+        if (getHeader(headers, "x-twilio-signature")) {
+          return { ok: true };
+        }
+        return { ok: false, reason: "missing X-Twilio-Signature header" };
+      case "plivo": {
+        const hasV3 =
+          Boolean(getHeader(headers, "x-plivo-signature-v3")) &&
+          Boolean(getHeader(headers, "x-plivo-signature-v3-nonce"));
+        const hasV2 =
+          Boolean(getHeader(headers, "x-plivo-signature-v2")) &&
+          Boolean(getHeader(headers, "x-plivo-signature-v2-nonce"));
+        if (hasV3 || hasV2) {
+          return { ok: true };
+        }
+        return { ok: false, reason: "missing Plivo signature headers" };
+      }
+      default:
+        return { ok: true };
+    }
+  }
 
-    const verification = this.provider.verifyWebhook(ctx);
-    if (!verification.ok) {
-      console.warn(`[voice-call] Webhook verification failed: ${verification.reason}`);
-      return { statusCode: 401, body: "Unauthorized" };
+  private isRealtimeWebSocketUpgrade(req: http.IncomingMessage): boolean {
+    try {
+      const pathname = buildRequestUrl(req.url, req.headers.host).pathname;
+      const pattern = this.realtimeHandler?.getStreamPathPattern();
+      return Boolean(pattern && pathname.startsWith(pattern));
+    } catch {
+      return false;
     }
-    if (!verification.verifiedRequestKey) {
-      console.warn("[voice-call] Webhook verification succeeded without request identity key");
-      return { statusCode: 401, body: "Unauthorized" };
+  }
+
+  private getRealtimeTwimlParams(ctx: WebhookContext): URLSearchParams | null {
+    if (!this.realtimeHandler || this.provider.name !== "twilio") {
+      return null;
     }
 
-    const parsed = this.provider.parseWebhookEvent(ctx, {
-      verifiedRequestKey: verification.verifiedRequestKey,
-    });
+    const params = new URLSearchParams(ctx.rawBody);
+    const direction = params.get("Direction");
+    const isSupportedDirection =
+      !direction || direction === "inbound" || direction.startsWith("outbound");
+    if (!isSupportedDirection) {
+      return null;
+    }
 
-    if (verification.isReplay) {
-      console.warn("[voice-call] Replay detected; skipping event side effects");
-    } else {
-      this.processParsedEvents(parsed.events);
+    if (ctx.query?.type === "status") {
+      return null;
     }
 
-    return normalizeWebhookResponse(parsed);
+    const callStatus = params.get("CallStatus");
+    if (callStatus && isProviderStatusTerminal(callStatus)) {
+      return null;
+    }
+
+    // Replays must return the same TwiML body so Twilio retries reconnect cleanly.
+    // The one-time token still changes, but the behavior stays identical.
+    return !params.get("SpeechResult") && !params.get("Digits") ? params : null;
+  }
+
+  private shouldAcceptRealtimeInboundRequest(params: URLSearchParams): boolean {
+    switch (this.config.inboundPolicy) {
+      case "open":
+        return true;
+      case "allowlist":
+      case "pairing":
+        return isAllowlistedCaller(
+          normalizePhoneNumber(params.get("From") ?? undefined),
+          this.config.allowFrom,
+        );
+      case "disabled":
+      default:
+        return false;
+    }
   }
 
   private processParsedEvents(events: NormalizedEvent[]): void {
@@ -435,7 +847,7 @@ export class VoiceCallWebhookServer {
   private readBody(
     req: http.IncomingMessage,
     maxBytes: number,
-    timeoutMs = 30_000,
+    timeoutMs = WEBHOOK_BODY_TIMEOUT_MS,
   ): Promise<string> {
     return readRequestBodyWithLimit(req, { maxBytes, timeoutMs });
   }
@@ -458,14 +870,23 @@ export class VoiceCallWebhookServer {
       console.warn("[voice-call] Core config missing; skipping auto-response");
       return;
     }
+    if (!this.agentRuntime) {
+      console.warn("[voice-call] Agent runtime missing; skipping auto-response");
+      return;
+    }
 
     try {
-      const { generateVoiceResponse } = await import("./response-generator.js");
+      const { generateVoiceResponse } = await loadResponseGeneratorModule();
+      const numberRouteKey =
+        typeof call.metadata?.numberRouteKey === "string" ? call.metadata.numberRouteKey : call.to;
+      const effectiveConfig = resolveVoiceCallEffectiveConfig(this.config, numberRouteKey).config;
 
       const result = await generateVoiceResponse({
-        voiceConfig: this.config,
+        voiceConfig: effectiveConfig,
         coreConfig: this.coreConfig,
+        agentRuntime: this.agentRuntime,
         callId,
+        sessionKey: call.sessionKey,
         from: call.from,
         transcript: call.transcript,
         userMessage,