@absolutejs/voice 0.0.22-beta.24 → 0.0.22-beta.241

package/dist/testing/index.js

@@ -2105,6 +2105,17 @@ var serverMessageToAction = (message) => {
         sessionId: message.sessionId,
         type: "complete"
       };
+    case "connection":
+      return {
+        reconnect: message.reconnect,
+        type: "connection"
+      };
+    case "call_lifecycle":
+      return {
+        event: message.event,
+        sessionId: message.sessionId,
+        type: "call_lifecycle"
+      };
     case "error":
       return {
         message: normalizeErrorMessage(message.message),
@@ -2120,6 +2131,17 @@ var serverMessageToAction = (message) => {
         transcript: message.transcript,
         type: "partial"
       };
+    case "replay":
+      return {
+        assistantTexts: message.assistantTexts,
+        call: message.call,
+        partial: message.partial,
+        scenarioId: message.scenarioId,
+        sessionId: message.sessionId,
+        status: message.status,
+        turns: message.turns,
+        type: "replay"
+      };
     case "session":
       return {
         sessionId: message.sessionId,
@@ -2148,7 +2170,7 @@ var DEFAULT_SCENARIO_QUERY_PARAM = "scenarioId";
 var noop = () => {};
 var noopUnsubscribe = () => noop;
 var NOOP_CONNECTION = {
-  start: () => {},
+  callControl: noop,
   close: noop,
   endTurn: noop,
   getReadyState: () => WS_CLOSED,
@@ -2156,6 +2178,7 @@ var NOOP_CONNECTION = {
   getSessionId: () => "",
   send: noop,
   sendAudio: noop,
+  start: () => {},
   subscribe: noopUnsubscribe
 };
 var createSessionId = () => crypto.randomUUID();
@@ -2177,11 +2200,14 @@ var isVoiceServerMessage = (value) => {
   switch (value.type) {
     case "audio":
     case "assistant":
+    case "call_lifecycle":
     case "complete":
+    case "connection":
     case "error":
     case "final":
     case "partial":
     case "pong":
+    case "replay":
     case "session":
     case "turn":
       return true;
@@ -2218,6 +2244,9 @@ var createVoiceConnection = (path, options = {}) => {
     sessionId: options.sessionId ?? createSessionId(),
     ws: null
   };
+  const emitConnection = (reconnect) => {
+    listeners.forEach((listener) => listener(reconnect));
+  };
   const clearTimers = () => {
     if (state.pingInterval) {
       clearInterval(state.pingInterval);
@@ -2240,9 +2269,28 @@ var createVoiceConnection = (path, options = {}) => {
     }
   };
   const scheduleReconnect = () => {
+    const nextAttemptAt = Date.now() + RECONNECT_DELAY_MS;
     state.reconnectAttempts += 1;
+    emitConnection({
+      reconnect: {
+        attempts: state.reconnectAttempts,
+        lastDisconnectAt: Date.now(),
+        maxAttempts: maxReconnectAttempts,
+        nextAttemptAt,
+        status: "reconnecting"
+      },
+      type: "connection"
+    });
     state.reconnectTimeout = setTimeout(() => {
       if (state.reconnectAttempts > maxReconnectAttempts) {
+        emitConnection({
+          reconnect: {
+            attempts: state.reconnectAttempts,
+            maxAttempts: maxReconnectAttempts,
+            status: "exhausted"
+          },
+          type: "connection"
+        });
         return;
       }
       connect();
@@ -2252,9 +2300,21 @@ var createVoiceConnection = (path, options = {}) => {
     const ws = new WebSocket(buildWsUrl(path, state.sessionId, state.scenarioId));
     ws.binaryType = "arraybuffer";
     ws.onopen = () => {
+      const wasReconnecting = state.reconnectAttempts > 0;
       state.isConnected = true;
-      state.reconnectAttempts = 0;
       flushPendingMessages();
+      if (wasReconnecting) {
+        emitConnection({
+          reconnect: {
+            attempts: state.reconnectAttempts,
+            lastResumedAt: Date.now(),
+            maxAttempts: maxReconnectAttempts,
+            status: "resumed"
+          },
+          type: "connection"
+        });
+        state.reconnectAttempts = 0;
+      }
       listeners.forEach((listener) => listener({
         scenarioId: state.scenarioId ?? undefined,
         sessionId: state.sessionId,
@@ -2284,6 +2344,16 @@ var createVoiceConnection = (path, options = {}) => {
       const reconnectable = shouldReconnect && event.code !== WS_NORMAL_CLOSURE && state.reconnectAttempts < maxReconnectAttempts;
       if (reconnectable) {
         scheduleReconnect();
+      } else if (shouldReconnect && event.code !== WS_NORMAL_CLOSURE) {
+        emitConnection({
+          reconnect: {
+            attempts: state.reconnectAttempts,
+            lastDisconnectAt: Date.now(),
+            maxAttempts: maxReconnectAttempts,
+            status: "exhausted"
+          },
+          type: "connection"
+        });
       }
     };
     state.ws = ws;
@@ -2317,6 +2387,12 @@ var createVoiceConnection = (path, options = {}) => {
   const endTurn = () => {
     send({ type: "end_turn" });
   };
+  const callControl = (message) => {
+    send({
+      ...message,
+      type: "call_control"
+    });
+  };
   const close = () => {
     clearTimers();
     if (state.ws) {
@@ -2334,7 +2410,7 @@ var createVoiceConnection = (path, options = {}) => {
   };
   connect();
   return {
-    start,
+    callControl,
     close,
     endTurn,
     getReadyState: () => state.ws?.readyState ?? WS_CLOSED,
@@ -2342,18 +2418,26 @@ var createVoiceConnection = (path, options = {}) => {
     getSessionId: () => state.sessionId,
     send,
     sendAudio,
+    start,
     subscribe
   };
 };
 
 // src/client/store.ts
+var createInitialReconnectState = () => ({
+  attempts: 0,
+  maxAttempts: 0,
+  status: "idle"
+});
 var createInitialState2 = () => ({
   assistantAudio: [],
   assistantTexts: [],
+  call: null,
   error: null,
   isConnected: false,
   scenarioId: null,
   partial: "",
+  reconnect: createInitialReconnectState(),
   sessionId: null,
   status: "idle",
   turns: []
@@ -2393,10 +2477,36 @@ var createVoiceStreamStore = () => {
           status: "completed"
         };
         break;
+      case "call_lifecycle":
+        state = {
+          ...state,
+          call: {
+            ...state.call,
+            disposition: action.event.type === "end" ? action.event.disposition : state.call?.disposition,
+            endedAt: action.event.type === "end" ? action.event.at : state.call?.endedAt,
+            events: [...state.call?.events ?? [], action.event],
+            lastEventAt: action.event.at,
+            startedAt: state.call?.startedAt ?? action.event.at
+          },
+          sessionId: action.sessionId
+        };
+        break;
       case "connected":
         state = {
           ...state,
-          isConnected: true
+          isConnected: true,
+          reconnect: state.reconnect.status === "reconnecting" ? {
+            ...state.reconnect,
+            lastResumedAt: Date.now(),
+            nextAttemptAt: undefined,
+            status: "resumed"
+          } : state.reconnect
+        };
+        break;
+      case "connection":
+        state = {
+          ...state,
+          reconnect: action.reconnect
         };
         break;
       case "disconnected":
@@ -2424,6 +2534,26 @@ var createVoiceStreamStore = () => {
           partial: action.transcript.text
         };
         break;
+      case "replay":
+        state = {
+          ...state,
+          assistantTexts: [...action.assistantTexts],
+          call: action.call ?? null,
+          error: null,
+          isConnected: action.status === "active",
+          partial: action.partial,
+          reconnect: state.reconnect.status === "reconnecting" ? {
+            ...state.reconnect,
+            lastResumedAt: Date.now(),
+            nextAttemptAt: undefined,
+            status: "resumed"
+          } : state.reconnect,
+          scenarioId: action.scenarioId ?? state.scenarioId,
+          sessionId: action.sessionId,
+          status: action.status,
+          turns: [...action.turns]
+        };
+        break;
       case "session":
         state = {
           ...state,
@@ -2471,14 +2601,41 @@ var createVoiceStream = (path, options = {}) => {
   const notify = () => {
     subscribers.forEach((subscriber) => subscriber());
   };
+  const reportReconnect = () => {
+    if (!options.reconnectReportPath || typeof fetch === "undefined") {
+      return;
+    }
+    const snapshot = store.getSnapshot();
+    const body = JSON.stringify({
+      at: Date.now(),
+      reconnect: snapshot.reconnect,
+      scenarioId: snapshot.scenarioId,
+      sessionId: connection.getSessionId(),
+      turnIds: snapshot.turns.map((turn) => turn.id)
+    });
+    fetch(options.reconnectReportPath, {
+      body,
+      headers: {
+        "Content-Type": "application/json"
+      },
+      keepalive: true,
+      method: "POST"
+    }).catch(() => {});
+  };
   const unsubscribeConnection = connection.subscribe((message) => {
     const action = serverMessageToAction(message);
     if (action) {
       store.dispatch(action);
+      if (message.type === "connection") {
+        reportReconnect();
+      }
       notify();
     }
   });
   return {
+    callControl(message) {
+      connection.callControl(message);
+    },
     close() {
       unsubscribeConnection();
       connection.close();
@@ -2507,6 +2664,9 @@ var createVoiceStream = (path, options = {}) => {
     get partial() {
       return store.getSnapshot().partial;
     },
+    get reconnect() {
+      return store.getSnapshot().reconnect;
+    },
     get sessionId() {
       return connection.getSessionId();
     },
@@ -2522,6 +2682,9 @@ var createVoiceStream = (path, options = {}) => {
     get assistantAudio() {
       return store.getSnapshot().assistantAudio;
     },
+    get call() {
+      return store.getSnapshot().call;
+    },
     sendAudio(audio) {
       connection.sendAudio(audio);
     },
@@ -2854,10 +3017,12 @@ var resolveVoiceRuntimePreset = (name = "default") => {
 var createInitialState3 = (stream) => ({
   assistantAudio: [...stream.assistantAudio],
   assistantTexts: [...stream.assistantTexts],
+  call: stream.call,
   error: stream.error,
   isConnected: stream.isConnected,
   isRecording: false,
   partial: stream.partial,
+  reconnect: stream.reconnect,
   recordingError: null,
   sessionId: stream.sessionId,
   scenarioId: stream.scenarioId,
@@ -2883,9 +3048,11 @@ var createVoiceController = (path, options = {}) => {
       ...state,
       assistantAudio: [...stream.assistantAudio],
       assistantTexts: [...stream.assistantTexts],
+      call: stream.call,
       error: stream.error,
       isConnected: stream.isConnected,
       partial: stream.partial,
+      reconnect: stream.reconnect,
       sessionId: stream.sessionId,
       scenarioId: stream.scenarioId,
       status: stream.status,
@@ -2910,7 +3077,13 @@ var createVoiceController = (path, options = {}) => {
     capture = createMicrophoneCapture({
       channelCount: options.capture?.channelCount ?? preset.capture.channelCount,
       onLevel: options.capture?.onLevel,
-      onAudio: (audio) => stream.sendAudio(audio),
+      onAudio: (audio) => {
+        if (options.capture?.onAudio) {
+          options.capture.onAudio(audio, stream.sendAudio);
+          return;
+        }
+        stream.sendAudio(audio);
+      },
       sampleRateHz: options.capture?.sampleRateHz ?? preset.capture.sampleRateHz
     });
     return capture;
@@ -2960,6 +3133,7 @@ var createVoiceController = (path, options = {}) => {
     bindHTMX(bindingOptions) {
       return bindVoiceHTMX(stream, bindingOptions);
     },
+    callControl: (message) => stream.callControl(message),
     close,
     endTurn: () => stream.endTurn(),
     get error() {
@@ -2979,6 +3153,9 @@ var createVoiceController = (path, options = {}) => {
     get recordingError() {
       return state.recordingError;
     },
+    get reconnect() {
+      return state.reconnect;
+    },
     sendAudio: (audio) => stream.sendAudio(audio),
     get sessionId() {
       return state.sessionId;
@@ -3012,6 +3189,9 @@ var createVoiceController = (path, options = {}) => {
     },
     get assistantAudio() {
       return state.assistantAudio;
+    },
+    get call() {
+      return state.call;
     }
   };
 };
@@ -3021,11 +3201,26 @@ var DEFAULT_INTERRUPT_THRESHOLD = 0.08;
 var shouldInterruptForLevel = (level, options = {}) => (options.enabled ?? true) && level >= (options.interruptThreshold ?? DEFAULT_INTERRUPT_THRESHOLD);
 var bindVoiceBargeIn = (controller, player, options = {}) => {
   let lastPartial = controller.partial;
-  const interruptIfPlaying = () => {
+  const interruptIfPlaying = (reason) => {
     if (!player.isPlaying || options.enabled === false) {
+      options.monitor?.recordSkipped({
+        reason,
+        sessionId: controller.sessionId
+      });
       return;
     }
-    player.interrupt();
+    options.monitor?.recordRequested({
+      reason,
+      sessionId: controller.sessionId
+    });
+    player.interrupt().then(() => {
+      options.monitor?.recordStopped({
+        latencyMs: player.lastInterruptLatencyMs,
+        playbackStopLatencyMs: player.lastPlaybackStopLatencyMs,
+        reason,
+        sessionId: controller.sessionId
+      });
+    });
   };
   const unsubscribe = controller.subscribe(() => {
     if (options.interruptOnPartial === false) {
@@ -3033,7 +3228,7 @@ var bindVoiceBargeIn = (controller, player, options = {}) => {
       return;
     }
     if (!lastPartial && controller.partial) {
-      interruptIfPlaying();
+      interruptIfPlaying("partial-transcript");
     }
     lastPartial = controller.partial;
   });
@@ -3043,11 +3238,11 @@ var bindVoiceBargeIn = (controller, player, options = {}) => {
     },
     handleLevel: (level) => {
       if (shouldInterruptForLevel(level, options)) {
-        interruptIfPlaying();
+        interruptIfPlaying("input-level");
       }
     },
     sendAudio: (audio) => {
-      interruptIfPlaying();
+      interruptIfPlaying("manual-audio");
       controller.sendAudio(audio);
     }
   };
@@ -3077,7 +3272,17 @@ var createVoiceDuplexController = (path, options = {}) => {
     audioPlayer,
     close,
     interruptAssistant: async () => {
+      options.bargeIn?.monitor?.recordRequested({
+        reason: "manual-interrupt",
+        sessionId: controller.sessionId
+      });
       await audioPlayer.interrupt();
+      options.bargeIn?.monitor?.recordStopped({
+        latencyMs: audioPlayer.lastInterruptLatencyMs,
+        playbackStopLatencyMs: audioPlayer.lastPlaybackStopLatencyMs,
+        reason: "manual-interrupt",
+        sessionId: controller.sessionId
+      });
     },
     sendAudio: (audio) => {
       bargeInBinding?.sendAudio(audio);
@@ -3468,7 +3673,165 @@ var loadVoiceTestFixtures = async (fixtureDirectory) => {
   }
   return fixtures;
 };
+// src/testing/ioProviderSimulator.ts
+var defaultFailureMessage = (input) => `Simulated ${input.provider} ${input.kind.toUpperCase()} ${input.operation} failure.`;
+var resolveRecoveryElapsedMs = (value, provider) => {
+  if (typeof value === "number") {
+    return value;
+  }
+  return value?.[provider] ?? 25;
+};
+var createHealth = (input) => ({
+  consecutiveFailures: input.status === "healthy" ? 0 : 1,
+  lastFailureAt: input.status === "healthy" ? undefined : input.now,
+  provider: input.provider,
+  status: input.status,
+  suppressedUntil: input.suppressedUntil
+});
+var resolveFallback = async (options, provider) => {
+  const configured = typeof options.fallback === "function" ? await options.fallback(provider) : options.fallback;
+  return (configured ?? options.providers).find((candidate) => candidate !== provider);
+};
+var createVoiceIOProviderFailureSimulator = (options) => {
+  if (options.providers.length === 0) {
+    throw new Error("At least one provider is required.");
+  }
+  const now = options.now ?? Date.now;
+  const operation = options.operation ?? "open";
+  const cooldownMs = Math.max(0, options.cooldownMs ?? 30000);
+  const emit = async (event, input) => {
+    await options.onProviderEvent?.(event, input);
+  };
+  const run = async (provider, mode) => {
+    if (!options.providers.includes(provider)) {
+      throw new Error(`${provider} is not configured for simulation.`);
+    }
+    const startedAt = now();
+    const sessionId = options.sessionId?.({ mode, now: startedAt, provider }) ?? `${options.kind}-provider-sim-${startedAt}`;
+    if (mode === "recovery") {
+      await emit({
+        at: startedAt,
+        attempt: 0,
+        elapsedMs: resolveRecoveryElapsedMs(options.recoveryElapsedMs, provider),
+        kind: options.kind,
+        latencyBudgetMs: options.latencyBudgets?.[provider],
+        operation,
+        provider,
+        providerHealth: createHealth({
+          now: startedAt,
+          provider,
+          status: "healthy"
+        }),
+        selectedProvider: provider,
+        status: "success"
+      }, { mode, provider, sessionId });
+      return {
+        mode,
+        provider,
+        sessionId,
+        status: "simulated"
+      };
+    }
+    const fallbackProvider = await resolveFallback(options, provider);
+    const suppressedUntil = startedAt + cooldownMs;
+    await emit({
+      at: startedAt,
+      attempt: 0,
+      elapsedMs: options.failureElapsedMs ?? 10,
+      error: (options.failureMessage ?? defaultFailureMessage)({
+        kind: options.kind,
+        operation,
+        provider
+      }),
+      fallbackProvider,
+      kind: options.kind,
+      latencyBudgetMs: options.latencyBudgets?.[provider],
+      operation,
+      provider,
+      providerHealth: createHealth({
+        now: startedAt,
+        provider,
+        status: "suppressed",
+        suppressedUntil
+      }),
+      selectedProvider: provider,
+      status: "error",
+      suppressedUntil
+    }, { mode, provider, sessionId });
+    if (fallbackProvider) {
+      await emit({
+        at: startedAt + 1,
+        attempt: 1,
+        elapsedMs: resolveRecoveryElapsedMs(options.recoveryElapsedMs, fallbackProvider),
+        fallbackProvider,
+        kind: options.kind,
+        latencyBudgetMs: options.latencyBudgets?.[fallbackProvider],
+        operation,
+        provider: fallbackProvider,
+        providerHealth: createHealth({
+          now: startedAt + 1,
+          provider: fallbackProvider,
+          status: "healthy"
+        }),
+        selectedProvider: provider,
+        status: "fallback"
+      }, { mode, provider, sessionId });
+    }
+    return {
+      fallbackProvider,
+      mode,
+      provider,
+      sessionId,
+      status: "simulated",
+      suppressedUntil
+    };
+  };
+  return {
+    run
+  };
+};
 // src/modelAdapters.ts
+var resolveVoiceProviderRoutingPolicyPreset = (preset, options = {}) => {
+  switch (preset) {
+    case "balanced":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "balanced",
+        weights: {
+          cost: 1,
+          latencyMs: 0.005,
+          priority: 1,
+          quality: 10,
+          ...options.weights
+        },
+        ...options
+      };
+    case "cost-cap":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "prefer-cheapest",
+        ...options
+      };
+    case "cost-first":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "prefer-cheapest",
+        ...options
+      };
+    case "latency-first":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "prefer-fastest",
+        ...options
+      };
+    case "quality-first":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "quality-first",
+        ...options
+      };
+  }
+};
 var OUTPUT_SCHEMA = {
   additionalProperties: false,
   properties: {
@@ -3559,6 +3922,17 @@ var parseJSONValue = (value) => {
     return value;
   }
 };
+
+class VoiceProviderTimeoutError extends Error {
+  provider;
+  timeoutMs;
+  constructor(provider, timeoutMs) {
+    super(`Voice provider ${provider} exceeded ${timeoutMs}ms latency budget.`);
+    this.name = "VoiceProviderTimeoutError";
+    this.provider = provider;
+    this.timeoutMs = timeoutMs;
+  }
+}
 var getMessageToolCalls = (message) => {
   const toolCalls = message.metadata?.toolCalls;
   return Array.isArray(toolCalls) ? toolCalls.filter((toolCall) => toolCall && typeof toolCall === "object" && typeof toolCall.name === "string") : [];
@@ -3625,7 +3999,7 @@ var createJSONVoiceAssistantModel = (options) => ({
 var createVoiceProviderRouter = (options) => {
   const providerIds = Object.keys(options.providers);
   const firstProvider = providerIds[0];
-  const policy = typeof options.policy === "string" ? {
+  const policy = typeof options.policy === "string" ? options.policy === "balanced" || options.policy === "cost-cap" || options.policy === "cost-first" || options.policy === "latency-first" || options.policy === "quality-first" ? resolveVoiceProviderRoutingPolicyPreset(options.policy) : {
     strategy: options.policy
   } : options.policy;
   const strategy = policy?.strategy ?? "prefer-selected";
@@ -3636,6 +4010,10 @@ var createVoiceProviderRouter = (options) => {
   const failureThreshold = Math.max(1, healthOptions?.failureThreshold ?? 1);
   const cooldownMs = Math.max(0, healthOptions?.cooldownMs ?? 30000);
   const rateLimitCooldownMs = Math.max(0, healthOptions?.rateLimitCooldownMs ?? 60000);
+  const getProviderTimeoutMs = (provider) => {
+    const timeoutMs = options.providerProfiles?.[provider]?.timeoutMs ?? options.timeoutMs;
+    return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined;
+  };
   const getHealth = (provider) => {
     const existing = healthState.get(provider);
     if (existing) {
@@ -3703,13 +4081,40 @@ var createVoiceProviderRouter = (options) => {
     const allowed = typeof allowProviders === "function" ? await allowProviders(input) : allowProviders;
     return new Set(allowed ?? providerIds);
   };
+  const passesBudgetFilters = (provider) => {
+    const profile = options.providerProfiles?.[provider];
+    if (typeof policy?.maxCost === "number" && typeof profile?.cost === "number" && profile.cost > policy.maxCost) {
+      return false;
+    }
+    if (typeof policy?.maxLatencyMs === "number" && typeof profile?.latencyMs === "number" && profile.latencyMs > policy.maxLatencyMs) {
+      return false;
+    }
+    if (typeof policy?.minQuality === "number" && typeof profile?.quality === "number" && profile.quality < policy.minQuality) {
+      return false;
+    }
+    return true;
+  };
+  const getBalancedScore = (provider) => {
+    const profile = options.providerProfiles?.[provider];
+    if (policy?.scoreProvider) {
+      return policy.scoreProvider(provider, profile);
+    }
+    const weights = policy?.weights ?? {};
+    return (profile?.cost ?? Number.MAX_SAFE_INTEGER) * (weights.cost ?? 1) + (profile?.latencyMs ?? Number.MAX_SAFE_INTEGER) * (weights.latencyMs ?? 0.005) + (profile?.priority ?? 0) * (weights.priority ?? 1) - (profile?.quality ?? 0) * (weights.quality ?? 10);
+  };
   const sortProviders = (providers) => {
-    if (strategy !== "prefer-cheapest" && strategy !== "prefer-fastest") {
+    if (strategy !== "prefer-cheapest" && strategy !== "prefer-fastest" && strategy !== "quality-first" && strategy !== "balanced") {
       return providers;
     }
     return [...providers].sort((left, right) => {
       const leftProfile = options.providerProfiles?.[left];
       const rightProfile = options.providerProfiles?.[right];
+      if (strategy === "quality-first") {
+        return (rightProfile?.quality ?? Number.MIN_SAFE_INTEGER) - (leftProfile?.quality ?? Number.MIN_SAFE_INTEGER) || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.cost ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.cost ?? Number.MAX_SAFE_INTEGER);
+      }
+      if (strategy === "balanced") {
+        return getBalancedScore(left) - getBalancedScore(right);
+      }
       const leftValue = strategy === "prefer-cheapest" ? leftProfile?.cost ?? Number.MAX_SAFE_INTEGER : leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER;
       const rightValue = strategy === "prefer-cheapest" ? rightProfile?.cost ?? Number.MAX_SAFE_INTEGER : rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER;
       return leftValue - rightValue || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER);
@@ -3719,12 +4124,13 @@ var createVoiceProviderRouter = (options) => {
     const selectedProvider = await options.selectProvider?.(input);
     const allowedProviders = await resolveAllowedProviders(input);
     const fallbackOrder = typeof options.fallback === "function" ? await options.fallback(input) : options.fallback;
-    const rankedProviders = sortProviders([
+    const allowedRankedProviders = sortProviders([
       ...fallbackOrder ?? providerIds
     ]).filter((provider) => allowedProviders.has(provider));
+    const rankedProviders = allowedRankedProviders.filter(passesBudgetFilters);
     const healthyRankedProviders = healthOptions ? rankedProviders.filter((provider) => !isSuppressed(provider)) : rankedProviders;
     const candidateRankedProviders = healthyRankedProviders.length ? healthyRankedProviders : rankedProviders;
-    const preferred = selectedProvider && allowedProviders.has(selectedProvider) && (!healthOptions || !isSuppressed(selectedProvider)) ? selectedProvider : candidateRankedProviders[0] ?? firstProvider;
+    const preferred = selectedProvider && allowedProviders.has(selectedProvider) && passesBudgetFilters(selectedProvider) && (!healthOptions || !isSuppressed(selectedProvider)) ? selectedProvider : candidateRankedProviders[0] ?? firstProvider;
     const seen = new Set;
     const order = [];
     const candidates = strategy === "ordered" ? candidateRankedProviders : [
@@ -3747,6 +4153,25 @@ var createVoiceProviderRouter = (options) => {
   const emit = async (event, input) => {
     await options.onProviderEvent?.(event, input);
   };
+  const runProvider = async (provider, model, input) => {
+    const timeoutMs = getProviderTimeoutMs(provider);
+    if (!timeoutMs) {
+      return model.generate(input);
+    }
+    let timeout;
+    try {
+      return await Promise.race([
+        model.generate(input),
+        new Promise((_, reject) => {
+          timeout = setTimeout(() => reject(new VoiceProviderTimeoutError(provider, timeoutMs)), timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  };
   return {
     generate: async (input) => {
       const { order, selectedProvider } = await resolveOrder(input);
@@ -3761,12 +4186,14 @@ var createVoiceProviderRouter = (options) => {
         }
         const startedAt = Date.now();
         try {
-          const output = await model.generate(input);
+          const output = await runProvider(provider, model, input);
           const providerHealth = recordProviderSuccess(provider);
           await emit({
             at: Date.now(),
+            attempt: index + 1,
             elapsedMs: Date.now() - startedAt,
             fallbackProvider: provider === selectedProvider ? undefined : provider,
+            latencyBudgetMs: getProviderTimeoutMs(provider),
             provider,
             providerHealth,
             recovered: provider !== selectedProvider,
@@ -3778,22 +4205,26 @@ var createVoiceProviderRouter = (options) => {
           lastError = error;
           const hasNextProvider = index < order.length - 1;
           const isProviderError = options.isProviderError?.(error, provider) ?? true;
+          const timedOut = options.isTimeoutError?.(error, provider) ?? error instanceof VoiceProviderTimeoutError;
           const rateLimited = options.isRateLimitError?.(error, provider) ?? defaultIsRateLimitError(error);
           const shouldFallback = fallbackMode === "provider-error" ? isProviderError : fallbackMode === "rate-limit" ? isProviderError && rateLimited : false;
           const providerHealth = recordProviderError(provider, isProviderError, rateLimited);
           const nextProvider = hasNextProvider ? order[index + 1] : undefined;
           await emit({
             at: Date.now(),
+            attempt: index + 1,
             elapsedMs: Date.now() - startedAt,
             error: errorMessage(error),
             fallbackProvider: shouldFallback ? nextProvider : undefined,
+            latencyBudgetMs: getProviderTimeoutMs(provider),
             provider,
             providerHealth,
             rateLimited,
             selectedProvider,
             suppressionRemainingMs: getSuppressionRemainingMs(provider),
             suppressedUntil: providerHealth?.suppressedUntil,
-            status: "error"
+            status: "error",
+            timedOut
           }, input);
           if (!hasNextProvider || !shouldFallback) {
             throw error;
@@ -4415,7 +4846,290 @@ var createVoiceMemoryStore = () => {
 };
 
 // src/session.ts
-import { Buffer } from "buffer";
+import { Buffer as Buffer2 } from "buffer";
+
+// src/handoff.ts
+var toHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+var signHandoffBody = async (input) => {
+  const encoder = new TextEncoder;
+  const key = await crypto.subtle.importKey("raw", encoder.encode(input.secret), {
+    hash: "SHA-256",
+    name: "HMAC"
+  }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(`${input.timestamp}.${input.body}`));
+  return `sha256=${toHex(new Uint8Array(signature))}`;
+};
+var toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+var createSkippedDelivery = (adapter) => ({
+  adapterId: adapter.id,
+  adapterKind: adapter.kind,
+  status: "skipped"
+});
+var aggregateHandoffStatus = (deliveries) => {
+  const statuses = Object.values(deliveries).map((delivery) => delivery.status);
+  if (statuses.some((status) => status === "failed")) {
+    return "failed";
+  }
+  if (statuses.some((status) => status === "delivered")) {
+    return "delivered";
+  }
+  return "skipped";
+};
+var createHandoffDeliveryId = (input) => [
+  "voice-handoff",
+  input.sessionId,
+  input.action,
+  Date.now(),
+  crypto.randomUUID()
+].join(":");
+var resolveHandoffDeliveryError = (deliveries) => Object.values(deliveries).map((delivery) => delivery.error).find(Boolean);
+var defaultWebhookBody = (input) => ({
+  action: input.action,
+  metadata: input.metadata,
+  reason: input.reason,
+  result: input.result,
+  session: {
+    id: input.session.id,
+    scenarioId: input.session.scenarioId,
+    status: input.session.status
+  },
+  source: "absolutejs-voice",
+  target: input.target
+});
+var deliverVoiceHandoff = async (input) => {
+  if (!input.config || input.config.adapters.length === 0) {
+    return;
+  }
+  const deliveries = {};
+  for (const adapter of input.config.adapters) {
+    if (adapter.actions && !adapter.actions.includes(input.handoff.action)) {
+      deliveries[adapter.id] = createSkippedDelivery(adapter);
+      continue;
+    }
+    try {
+      const result = await adapter.handoff(input.handoff);
+      deliveries[adapter.id] = {
+        ...result,
+        adapterId: adapter.id,
+        adapterKind: adapter.kind
+      };
+    } catch (error) {
+      deliveries[adapter.id] = {
+        adapterId: adapter.id,
+        adapterKind: adapter.kind,
+        error: toErrorMessage(error),
+        status: "failed"
+      };
+      if (input.config.failMode === "throw") {
+        throw error;
+      }
+    }
+  }
+  return {
+    action: input.handoff.action,
+    deliveries,
+    status: aggregateHandoffStatus(deliveries)
+  };
+};
+var createVoiceHandoffDeliveryRecord = (input) => {
+  const now = Date.now();
+  return {
+    action: input.action,
+    context: input.context,
+    createdAt: now,
+    deliveryAttempts: 0,
+    deliveryStatus: "pending",
+    id: input.id ?? createHandoffDeliveryId({
+      action: input.action,
+      sessionId: input.session.id
+    }),
+    metadata: input.metadata,
+    reason: input.reason,
+    result: input.result,
+    session: input.session,
+    sessionId: input.session.id,
+    target: input.target,
+    updatedAt: now
+  };
+};
+var applyVoiceHandoffDeliveryResult = (delivery, result) => ({
+  ...delivery,
+  deliveredAt: result.status === "delivered" || result.status === "skipped" ? Date.now() : delivery.deliveredAt,
+  deliveries: result.deliveries,
+  deliveryAttempts: (delivery.deliveryAttempts ?? 0) + 1,
+  deliveryError: result.status === "failed" ? resolveHandoffDeliveryError(result.deliveries) : undefined,
+  deliveryStatus: result.status,
+  updatedAt: Date.now()
+});
+var deliverVoiceHandoffDelivery = async (options) => {
+  const result = await deliverVoiceHandoff({
+    config: {
+      adapters: options.adapters,
+      failMode: options.failMode
+    },
+    handoff: {
+      action: options.delivery.action,
+      api: options.api,
+      context: options.delivery.context,
+      metadata: options.delivery.metadata,
+      reason: options.delivery.reason,
+      result: options.delivery.result,
+      session: options.delivery.session,
+      target: options.delivery.target
+    }
+  });
+  return result ? applyVoiceHandoffDeliveryResult(options.delivery, result) : {
+    ...options.delivery,
+    deliveryAttempts: (options.delivery.deliveryAttempts ?? 0) + 1,
+    deliveryStatus: "skipped",
+    updatedAt: Date.now()
+  };
+};
+var createVoiceMemoryHandoffDeliveryStore = () => {
+  const deliveries = new Map;
+  return {
+    get: async (id) => deliveries.get(id),
+    list: async () => [...deliveries.values()].sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id)),
+    remove: async (id) => {
+      deliveries.delete(id);
+    },
+    set: async (id, delivery) => {
+      deliveries.set(id, delivery);
+    }
+  };
+};
+var createVoiceWebhookHandoffAdapter = (options) => ({
+  actions: options.actions,
+  handoff: async (input) => {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      return {
+        deliveredTo: options.url,
+        error: "Handoff delivery failed: fetch is not available in this runtime.",
+        status: "failed"
+      };
+    }
+    const body = JSON.stringify(await options.body?.(input) ?? defaultWebhookBody(input));
+    const headers = {
+      "content-type": "application/json",
+      ...options.headers
+    };
+    if (options.signingSecret) {
+      const timestamp = String(Date.now());
+      headers["x-absolutejs-timestamp"] = timestamp;
+      headers["x-absolutejs-signature"] = await signHandoffBody({
+        body,
+        secret: options.signingSecret,
+        timestamp
+      });
+    }
+    const controller = options.timeoutMs && options.timeoutMs > 0 ? new AbortController : undefined;
+    const timeout = controller && options.timeoutMs ? setTimeout(() => controller.abort(), options.timeoutMs) : undefined;
+    try {
+      const response = await fetchImpl(options.url, {
+        body,
+        headers,
+        method: options.method ?? "POST",
+        signal: controller?.signal
+      });
+      if (!response.ok) {
+        return {
+          deliveredTo: options.url,
+          error: `Handoff delivery failed with response ${response.status}.`,
+          status: "failed"
+        };
+      }
+      return {
+        deliveredAt: Date.now(),
+        deliveredTo: options.url,
+        status: "delivered"
+      };
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  },
+  id: options.id,
+  kind: options.kind ?? "webhook"
+});
+var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+var defaultTwilioTransferTwiML = (input) => {
+  if (!input.target) {
+    return "<Response><Hangup /></Response>";
+  }
+  return `<Response><Dial>${escapeXml(input.target)}</Dial></Response>`;
+};
+var resolveTwilioCallSid = async (resolver, input) => {
+  if (typeof resolver === "function") {
+    return resolver(input);
+  }
+  if (typeof resolver === "string" && resolver.length > 0) {
+    return resolver;
+  }
+  const metadataSid = typeof input.metadata?.callSid === "string" ? input.metadata.callSid : undefined;
+  const sessionMetadata = input.session.metadata && typeof input.session.metadata === "object" ? input.session.metadata : undefined;
+  const sessionSid = typeof sessionMetadata?.callSid === "string" ? sessionMetadata.callSid : undefined;
+  return metadataSid ?? sessionSid;
+};
+var createVoiceTwilioRedirectHandoffAdapter = (options) => ({
+  actions: options.actions ?? ["transfer"],
+  handoff: async (input) => {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const callSid = await resolveTwilioCallSid(options.callSid, input);
+    if (!callSid) {
+      return {
+        error: "Twilio handoff requires a callSid.",
+        status: "failed"
+      };
+    }
+    if (typeof fetchImpl !== "function") {
+      return {
+        error: "Twilio handoff failed: fetch is not available in this runtime.",
+        status: "failed"
+      };
+    }
+    const url = `https://api.twilio.com/2010-04-01/Accounts/${encodeURIComponent(options.accountSid)}/Calls/${encodeURIComponent(callSid)}.json`;
+    const body = new URLSearchParams({
+      Twiml: await (options.buildTwiML?.(input) ?? defaultTwilioTransferTwiML(input))
+    });
+    const auth = btoa(`${options.accountSid}:${options.authToken}`);
+    const controller = options.timeoutMs && options.timeoutMs > 0 ? new AbortController : undefined;
+    const timeout = controller && options.timeoutMs ? setTimeout(() => controller.abort(), options.timeoutMs) : undefined;
+    try {
+      const response = await fetchImpl(url, {
+        body,
+        headers: {
+          authorization: `Basic ${auth}`,
+          "content-type": "application/x-www-form-urlencoded"
+        },
+        method: "POST",
+        signal: controller?.signal
+      });
+      if (!response.ok) {
+        return {
+          deliveredTo: url,
+          error: `Twilio handoff failed with response ${response.status}.`,
+          status: "failed"
+        };
+      }
+      return {
+        deliveredAt: Date.now(),
+        deliveredTo: url,
+        metadata: {
+          callSid
+        },
+        status: "delivered"
+      };
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  },
+  id: options.id ?? "twilio-redirect",
+  kind: "twilio-redirect"
+});
 
 // src/logger.ts
 var noop2 = () => {};
@@ -4451,6 +5165,12 @@ var DEFAULT_FORMAT = {
   encoding: "pcm_s16le",
   sampleRateHz: 16000
 };
+var DEFAULT_REALTIME_FORMAT = {
+  channels: 1,
+  container: "raw",
+  encoding: "pcm_s16le",
+  sampleRateHz: 24000
+};
 var toError = (value) => value instanceof Error ? value : new Error(String(value));
 var createEmptyCurrentTurn = () => ({
   finalText: "",
@@ -4463,7 +5183,7 @@ var createEmptyCurrentTurn = () => ({
   transcripts: []
 });
 var cloneTranscript = (transcript) => ({ ...transcript });
-var encodeBase64 = (chunk) => Buffer.from(chunk).toString("base64");
+var encodeBase64 = (chunk) => Buffer2.from(chunk).toString("base64");
 var countWords2 = (text) => text.trim().split(/\s+/).filter(Boolean).length;
 var normalizeText2 = (text) => text.trim().replace(/\s+/g, " ");
 var getAudioChunkDurationMs = (chunk) => chunk.byteLength / (DEFAULT_FORMAT.sampleRateHz * DEFAULT_FORMAT.channels * 2) * 1000;
@@ -4609,6 +5329,7 @@ var pushCallLifecycleEvent = (session, input) => {
   }
   return lifecycle;
 };
+var getLatestCallLifecycleEvent = (session) => session.call?.events.at(-1);
 var createVoiceSession = (options) => {
   const logger = resolveLogger(options.logger);
   const reconnect = {
@@ -4633,7 +5354,7 @@ var createVoiceSession = (options) => {
   } : undefined;
   const appendTrace = async (input) => {
     await options.trace?.append({
-      at: Date.now(),
+      at: input.at ?? Date.now(),
       metadata: input.metadata,
       payload: input.payload,
       scenarioId: input.session?.scenarioId ?? options.scenarioId,
@@ -4642,6 +5363,13 @@ var createVoiceSession = (options) => {
       type: input.type
     });
   };
+  const appendTurnLatencyStage = async (input) => appendTrace({
+    at: input.at,
+    payload: { stage: input.stage },
+    session: input.session,
+    turnId: input.turnId,
+    type: "turn_latency.stage"
+  });
   const phraseHints = options.phraseHints ?? [];
   const lexicon = options.lexicon ?? [];
   let socket = options.socket;
@@ -4709,35 +5437,105 @@ var createVoiceSession = (options) => {
       });
     }
   };
-  const readSession = async () => options.store.getOrCreate(options.id);
-  const writeSession = async (mutate) => {
-    const session = await options.store.getOrCreate(options.id);
-    mutate(session);
-    await options.store.set(options.id, session);
-    return session;
-  };
-  const runSerial = (phase, operation) => {
-    const result = operationQueue.then(async () => {
-      logger.debug("voice session operation", {
-        phase,
-        sessionId: options.id
-      });
-      return await operation();
-    });
-    operationQueue = result.then(() => {
-      return;
-    }, () => {
+  const sendCallLifecycle = async (session) => {
+    const event = getLatestCallLifecycleEvent(session);
+    if (!event) {
       return;
+    }
+    await send({
+      event,
+      sessionId: options.id,
+      type: "call_lifecycle"
     });
-    return result;
   };
-  const closeAdapter = async (reason) => {
-    if (!sttSession) {
-      return;
-    }
-    const activeSession = sttSession;
-    sttSession = null;
-    activeAdapterGeneration = 0;
+  const sendReplay = async (session) => {
+    await send({
+      assistantTexts: session.turns.flatMap((turn) => turn.assistantText ? [turn.assistantText] : []),
+      call: session.call,
+      partial: session.currentTurn.partialText,
+      scenarioId: session.scenarioId,
+      sessionId: options.id,
+      status: session.status,
+      turns: session.turns,
+      type: "replay"
+    });
+  };
+  const runHandoff = async (input) => {
+    const queuedDelivery = options.handoff?.deliveryQueue ? createVoiceHandoffDeliveryRecord({
+      action: input.action,
+      context: options.context,
+      metadata: input.metadata,
+      reason: input.reason,
+      result: input.result,
+      session: input.session,
+      target: input.target
+    }) : undefined;
+    if (queuedDelivery) {
+      await options.handoff?.deliveryQueue?.set(queuedDelivery.id, queuedDelivery);
+    }
+    if (options.handoff?.enqueueOnly) {
+      return;
+    }
+    const result = await deliverVoiceHandoff({
+      config: options.handoff,
+      handoff: {
+        action: input.action,
+        api,
+        context: options.context,
+        metadata: input.metadata,
+        reason: input.reason,
+        result: input.result,
+        session: input.session,
+        target: input.target
+      }
+    });
+    if (!result) {
+      return;
+    }
+    if (queuedDelivery) {
+      const updatedDelivery = applyVoiceHandoffDeliveryResult(queuedDelivery, result);
+      await options.handoff?.deliveryQueue?.set(updatedDelivery.id, updatedDelivery);
+    }
+    await appendTrace({
+      metadata: input.metadata,
+      payload: {
+        ...result,
+        reason: input.reason,
+        target: input.target
+      },
+      session: input.session,
+      type: "call.handoff"
+    });
+  };
+  const readSession = async () => options.store.getOrCreate(options.id);
+  const writeSession = async (mutate) => {
+    const session = await options.store.getOrCreate(options.id);
+    mutate(session);
+    await options.store.set(options.id, session);
+    return session;
+  };
+  const runSerial = (phase, operation) => {
+    const result = operationQueue.then(async () => {
+      logger.debug("voice session operation", {
+        phase,
+        sessionId: options.id
+      });
+      return await operation();
+    });
+    operationQueue = result.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return result;
+  };
+  const closeAdapter = async (reason) => {
+    if (!sttSession) {
+      return;
+    }
+    const activeSession = sttSession;
+    sttSession = null;
+    activeAdapterGeneration = 0;
     try {
       await activeSession.close(reason);
     } catch (error) {
@@ -4765,6 +5563,23 @@ var createVoiceSession = (options) => {
       });
     }
   };
+  const sendAssistantAudio = async (chunk, input) => {
+    const normalizedChunk = chunk instanceof Uint8Array ? new Uint8Array(chunk) : chunk instanceof ArrayBuffer ? new Uint8Array(chunk.slice(0)) : new Uint8Array(chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength));
+    await send({
+      chunkBase64: encodeBase64(normalizedChunk),
+      format: input.format,
+      receivedAt: input.receivedAt,
+      turnId: activeTTSTurnId,
+      type: "audio"
+    });
+    if (activeTTSTurnId) {
+      await appendTurnLatencyStage({
+        at: input.receivedAt,
+        stage: "assistant_audio_received",
+        turnId: activeTTSTurnId
+      });
+    }
+  };
   const scheduleTurnCommit = (delayMs, reason, reset = true) => {
     if (!reset && silenceTimer) {
       return;
@@ -4899,6 +5714,7 @@ var createVoiceSession = (options) => {
     await appendTrace({
       payload: {
         disposition,
+        metadata: input.metadata,
         reason: input.reason,
         target: input.target,
         type: "end"
@@ -4906,6 +5722,7 @@ var createVoiceSession = (options) => {
       session,
       type: "call.lifecycle"
     });
+    await sendCallLifecycle(session);
     await send({
       sessionId: options.id,
       type: "complete"
@@ -4985,6 +5802,15 @@ var createVoiceSession = (options) => {
       session,
       type: "call.lifecycle"
     });
+    await sendCallLifecycle(session);
+    await runHandoff({
+      action: "transfer",
+      metadata: input.metadata,
+      reason: input.reason,
+      result: input.result,
+      session,
+      target: input.target
+    });
     await completeInternal(input.result, {
       disposition: "transferred",
       invokeOnComplete: false,
@@ -5010,6 +5836,14 @@ var createVoiceSession = (options) => {
       session,
       type: "call.lifecycle"
     });
+    await sendCallLifecycle(session);
+    await runHandoff({
+      action: "escalate",
+      metadata: input.metadata,
+      reason: input.reason,
+      result: input.result,
+      session
+    });
     await completeInternal(input.result, {
       disposition: "escalated",
       invokeOnComplete: false,
@@ -5032,6 +5866,13 @@ var createVoiceSession = (options) => {
       session,
       type: "call.lifecycle"
     });
+    await sendCallLifecycle(session);
+    await runHandoff({
+      action: "no-answer",
+      metadata: input?.metadata,
+      result: input?.result,
+      session
+    });
     await completeInternal(input?.result, {
       disposition: "no-answer",
       invokeOnComplete: false,
@@ -5053,6 +5894,13 @@ var createVoiceSession = (options) => {
       session,
       type: "call.lifecycle"
     });
+    await sendCallLifecycle(session);
+    await runHandoff({
+      action: "voicemail",
+      metadata: input?.metadata,
+      result: input?.result,
+      session
+    });
     await completeInternal(input?.result, {
       disposition: "voicemail",
       invokeOnComplete: false,
@@ -5433,8 +6281,12 @@ var createVoiceSession = (options) => {
     if (sttSession) {
       return sttSession;
     }
-    const openedSession = await options.stt.open({
-      format: DEFAULT_FORMAT,
+    const inputAdapter = options.realtime ?? options.stt;
+    if (!inputAdapter) {
+      throw new Error("Voice session requires either an stt or realtime adapter.");
+    }
+    const openedSession = await inputAdapter.open({
+      format: options.realtime ? options.realtimeInputFormat ?? DEFAULT_REALTIME_FORMAT : DEFAULT_FORMAT,
       languageStrategy: options.languageStrategy,
       lexicon,
       phraseHints,
@@ -5469,6 +6321,16 @@ var createVoiceSession = (options) => {
     openedSession.on("close", (event) => {
       runAdapterEvent("adapter.close", () => handleClose(event));
     });
+    if (options.realtime) {
+      openedSession.on("audio", ({ chunk, format, receivedAt }) => {
+        runAdapterEvent("adapter.audio", async () => {
+          await sendAssistantAudio(chunk, {
+            format,
+            receivedAt
+          });
+        });
+      });
+    }
     return openedSession;
   };
   const ensureTTSSession = async () => {
@@ -5493,13 +6355,9 @@ var createVoiceSession = (options) => {
           if (ttsSession !== openedSession) {
             return;
           }
-          const normalizedChunk = chunk instanceof Uint8Array ? new Uint8Array(chunk) : chunk instanceof ArrayBuffer ? new Uint8Array(chunk.slice(0)) : new Uint8Array(chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength));
-          await send({
-            chunkBase64: encodeBase64(normalizedChunk),
+          await sendAssistantAudio(chunk, {
             format,
-            receivedAt,
-            turnId: activeTTSTurnId,
-            type: "audio"
+            receivedAt
           });
         });
       });
@@ -5543,9 +6401,32 @@ var createVoiceSession = (options) => {
     });
   };
   const completeTurn = async (session, turn) => {
+    const liveOpsControl = await options.liveOps?.getControl(options.id);
+    if (liveOpsControl?.assistantPaused || liveOpsControl?.operatorTakeover) {
+      await appendTrace({
+        metadata: {
+          source: "voice-live-ops"
+        },
+        payload: {
+          action: "turn.skipped",
+          control: liveOpsControl,
+          reason: liveOpsControl.operatorTakeover ? "operator-takeover" : "assistant-paused",
+          status: "skipped"
+        },
+        session,
+        turnId: turn.id,
+        type: "operator.action"
+      });
+      return;
+    }
+    const injectedInstruction = liveOpsControl?.injectedInstruction?.trim();
     const committedOutput = await options.route.onTurn({
       api,
       context: options.context,
+      liveOps: liveOpsControl ? {
+        control: liveOpsControl,
+        injectedInstruction
+      } : undefined,
       session,
       turn
     });
@@ -5559,6 +6440,7 @@ var createVoiceSession = (options) => {
       voicemail: committedOutput?.voicemail
     };
     if (output?.assistantText) {
+      const assistantTextStartedAt = Date.now();
       await writeSession((currentSession) => {
         setTurnResult(currentSession, turn.id, {
           assistantText: output.assistantText
@@ -5569,10 +6451,17 @@ var createVoiceSession = (options) => {
         turnId: turn.id,
         type: "assistant"
       });
+      await appendTurnLatencyStage({
+        at: assistantTextStartedAt,
+        session,
+        stage: "assistant_text_started",
+        turnId: turn.id
+      });
       await appendTrace({
         payload: {
           text: output.assistantText,
-          ttsConfigured: Boolean(options.tts)
+          ttsConfigured: Boolean(options.tts),
+          realtimeConfigured: Boolean(options.realtime)
         },
         session,
         turnId: turn.id,
@@ -5583,7 +6472,18 @@ var createVoiceSession = (options) => {
         if (activeTTSSession) {
           const ttsStartedAt = Date.now();
           activeTTSTurnId = turn.id;
+          await appendTurnLatencyStage({
+            at: ttsStartedAt,
+            session,
+            stage: "tts_send_started",
+            turnId: turn.id
+          });
           await activeTTSSession.send(output.assistantText);
+          await appendTurnLatencyStage({
+            session,
+            stage: "tts_send_completed",
+            turnId: turn.id
+          });
           await appendTrace({
             payload: {
               elapsedMs: Date.now() - ttsStartedAt,
@@ -5593,9 +6493,35 @@ var createVoiceSession = (options) => {
             turnId: turn.id,
             type: "turn.assistant"
           });
+        } else if (options.realtime) {
+          const activeRealtimeSession = await ensureAdapter();
+          const realtimeStartedAt = Date.now();
+          activeTTSTurnId = turn.id;
+          await appendTurnLatencyStage({
+            at: realtimeStartedAt,
+            session,
+            stage: "tts_send_started",
+            turnId: turn.id
+          });
+          await activeRealtimeSession.send(output.assistantText);
+          await appendTurnLatencyStage({
+            session,
+            stage: "tts_send_completed",
+            turnId: turn.id
+          });
+          await appendTrace({
+            payload: {
+              elapsedMs: Date.now() - realtimeStartedAt,
+              mode: "realtime",
+              status: "sent"
+            },
+            session,
+            turnId: turn.id,
+            type: "turn.assistant"
+          });
         }
       } catch (error) {
-        logger.warn("voice tts send failed", {
+        logger.warn("voice assistant audio send failed", {
           error: toError(error).message,
           sessionId: options.id,
           turnId: turn.id
@@ -5603,7 +6529,7 @@ var createVoiceSession = (options) => {
         await appendTrace({
           payload: {
             error: toError(error).message,
-            status: "tts-send-failed"
+            status: options.realtime ? "realtime-send-failed" : "tts-send-failed"
           },
           session,
           turnId: turn.id,
@@ -5780,11 +6706,35 @@ var createVoiceSession = (options) => {
       turnId: turn.id,
       type: "turn.cost"
     });
+    const firstTranscriptAt = turn.transcripts.map((transcript) => transcript.endedAtMs ?? transcript.startedAtMs).filter((value) => typeof value === "number").sort((left, right) => left - right)[0];
+    const finalTranscriptAt = turn.transcripts.filter((transcript) => transcript.isFinal).map((transcript) => transcript.endedAtMs ?? transcript.startedAtMs).filter((value) => typeof value === "number").sort((left, right) => left - right)[0];
+    if (firstTranscriptAt !== undefined) {
+      await appendTurnLatencyStage({
+        at: firstTranscriptAt,
+        session: updatedSession,
+        stage: "speech_detected",
+        turnId: turn.id
+      });
+    }
+    if (finalTranscriptAt !== undefined) {
+      await appendTurnLatencyStage({
+        at: finalTranscriptAt,
+        session: updatedSession,
+        stage: "final_transcript",
+        turnId: turn.id
+      });
+    }
+    await appendTurnLatencyStage({
+      at: turn.committedAt,
+      session: updatedSession,
+      stage: "turn_committed",
+      turnId: turn.id
+    });
     await send({
       turn,
       type: "turn"
     });
-    if (options.sttLifecycle === "turn-scoped") {
+    if (options.stt && options.sttLifecycle === "turn-scoped") {
       await closeAdapter("turn-commit");
     }
     await completeTurn(updatedSession, turn);
@@ -5839,6 +6789,7 @@ var createVoiceSession = (options) => {
         session,
         type: "call.lifecycle"
       });
+      await sendCallLifecycle(session);
     }
     await send({
       sessionId: options.id,
@@ -5846,6 +6797,7 @@ var createVoiceSession = (options) => {
       scenarioId: session.scenarioId,
       type: "session"
     });
+    await sendReplay(session);
     if (shouldFireOnSession) {
       await options.route.onCallStart?.({
         api,
@@ -6429,7 +7381,7 @@ var createVoiceCallReviewFromLiveTelephonyReport = (report, options = {}) => {
     }
   };
 };
-var toErrorMessage = (error) => {
+var toErrorMessage2 = (error) => {
   if (typeof error === "string" && error.trim().length > 0) {
     return error;
   }
@@ -6516,7 +7468,7 @@ var createVoiceCallReviewRecorder = (options = {}) => {
       };
     },
     recordError: (error) => {
-      const message = toErrorMessage(error);
+      const message = toErrorMessage2(error);
       errors.push(message);
       push("turn", "error", {
         reason: message
@@ -7222,10 +8174,870 @@ var runVoiceSessionBenchmarkSeries = async (input) => {
   });
 };
 // src/telephony/twilio.ts
-import { Buffer as Buffer2 } from "buffer";
+import { Buffer as Buffer3 } from "buffer";
+import { Elysia as Elysia2 } from "elysia";
+
+// src/telephonyOutcome.ts
+import { Elysia } from "elysia";
+var DEFAULT_COMPLETED_STATUSES = [
+  "answered",
+  "completed",
+  "complete",
+  "connected",
+  "in-progress",
+  "live"
+];
+var DEFAULT_NO_ANSWER_STATUSES = [
+  "busy",
+  "canceled",
+  "cancelled",
+  "failed",
+  "no-answer",
+  "no_answer",
+  "not-answered",
+  "ring-no-answer",
+  "timeout",
+  "unanswered"
+];
+var DEFAULT_VOICEMAIL_STATUSES = [
+  "answering-machine",
+  "machine",
+  "voicemail",
+  "voice-mail"
+];
+var DEFAULT_TRANSFER_STATUSES = ["bridged", "forwarded", "transferred"];
+var DEFAULT_ESCALATION_STATUSES = ["escalated", "human-required", "operator"];
+var DEFAULT_FAILED_STATUSES = ["busy", "failed", "no-answer"];
+var DEFAULT_MACHINE_VOICEMAIL_VALUES = [
+  "answering-machine",
+  "fax",
+  "machine",
+  "machine-end-beep",
+  "machine-end-other",
+  "machine-start",
+  "voicemail"
+];
+var DEFAULT_NO_ANSWER_SIP_CODES = [408, 480, 486, 487, 603];
+var isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+class VoiceTelephonyWebhookVerificationError extends Error {
+  result;
+  constructor(result) {
+    super(result.ok ? "telephony webhook verified" : result.reason);
+    this.name = "VoiceTelephonyWebhookVerificationError";
+    this.result = result;
+  }
+}
+var createMemoryVoiceTelephonyWebhookIdempotencyStore = () => {
+  const decisions = new Map;
+  return {
+    get: (key) => decisions.get(key),
+    set: (key, decision) => {
+      decisions.set(key, decision);
+    }
+  };
+};
+var normalizeToken = (value) => typeof value === "string" ? value.trim().toLowerCase().replace(/\s+/g, "-").replace(/_+/g, "-") : undefined;
+var firstString = (source, keys) => {
+  for (const key of keys) {
+    const value = source[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return String(value);
+    }
+  }
+};
+var firstNumber = (source, keys) => {
+  for (const key of keys) {
+    const value = source[key];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "string" && value.trim()) {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) {
+        return parsed;
+      }
+    }
+  }
+};
+var parseMaybeJSON = (value) => {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return;
+  }
+};
+var flattenPayload = (value) => {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const data = isRecord(value.data) ? value.data : undefined;
+  const payload = isRecord(value.payload) ? value.payload : undefined;
+  const event = isRecord(value.event) ? value.event : undefined;
+  return {
+    ...value,
+    ...payload,
+    ...event,
+    ...data,
+    ...isRecord(data?.payload) ? data.payload : undefined
+  };
+};
+var toBase64 = (bytes) => Buffer.from(new Uint8Array(bytes)).toString("base64");
+var timingSafeEqual = (left, right) => {
+  const encoder = new TextEncoder;
+  const leftBytes = encoder.encode(left);
+  const rightBytes = encoder.encode(right);
+  if (leftBytes.length !== rightBytes.length) {
+    return false;
+  }
+  let diff = 0;
+  for (let index = 0;index < leftBytes.length; index += 1) {
+    diff |= leftBytes[index] ^ rightBytes[index];
+  }
+  return diff === 0;
+};
+var signHmacSHA1Base64 = async (secret, payload) => {
+  const encoder = new TextEncoder;
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+    hash: "SHA-1",
+    name: "HMAC"
+  }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  return toBase64(signature);
+};
+var sortedParamsForSignature = (body) => Object.entries(flattenPayload(body)).filter(([, value]) => value !== undefined && value !== null).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}${String(value)}`).join("");
+var normalizeList = (values, fallback) => new Set((values ?? fallback).map(normalizeToken).filter(Boolean));
+var metadataValue = (metadata, keys) => {
+  for (const key of keys) {
+    const value = metadata?.[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+};
+var resolveTransferTarget = (event, policy) => {
+  if (typeof event.target === "string" && event.target.trim()) {
+    return event.target.trim();
+  }
+  const metadataTarget = metadataValue(event.metadata, [
+    "transferTarget",
+    "target",
+    "queue",
+    "department"
+  ]);
+  if (metadataTarget) {
+    return metadataTarget;
+  }
+  if (typeof policy.transferTarget === "function") {
+    const target = policy.transferTarget(event);
+    return typeof target === "string" && target.trim() ? target.trim() : undefined;
+  }
+  return typeof policy.transferTarget === "string" && policy.transferTarget.trim() ? policy.transferTarget.trim() : undefined;
+};
+var mergeMetadata = (event, policy) => ({
+  ...policy.includeProviderPayload ? {
+    answeredBy: event.answeredBy,
+    durationMs: event.durationMs,
+    provider: event.provider,
+    reason: event.reason,
+    sipCode: event.sipCode,
+    status: event.status
+  } : undefined,
+  ...policy.metadata,
+  ...event.metadata
+});
+var withDecisionDefaults = (decision, input) => {
+  if (typeof decision === "string") {
+    return buildDecision(decision, input);
+  }
+  return {
+    ...buildDecision(decision.action, input),
+    ...decision,
+    confidence: decision.confidence ?? "high",
+    metadata: {
+      ...mergeMetadata(input.event, input.policy),
+      ...decision.metadata
+    },
+    source: decision.source ?? input.source,
+    target: decision.target ?? (decision.action === "transfer" ? resolveTransferTarget(input.event, input.policy) : undefined)
+  };
+};
+var dispositionForAction = (action) => {
+  switch (action) {
+    case "complete":
+      return "completed";
+    case "escalate":
+      return "escalated";
+    case "no-answer":
+      return "no-answer";
+    case "transfer":
+      return "transferred";
+    case "voicemail":
+      return "voicemail";
+    default:
+      return;
+  }
+};
+var buildDecision = (action, input) => ({
+  action,
+  confidence: action === "ignore" ? "low" : "high",
+  disposition: dispositionForAction(action),
+  metadata: mergeMetadata(input.event, input.policy),
+  reason: input.event.reason,
+  source: input.source,
+  target: action === "transfer" ? resolveTransferTarget(input.event, input.policy) : undefined
+});
+var createVoiceTelephonyOutcomePolicy = (policy = {}) => ({
+  completedStatuses: policy.completedStatuses ?? DEFAULT_COMPLETED_STATUSES,
+  escalationStatuses: policy.escalationStatuses ?? DEFAULT_ESCALATION_STATUSES,
+  failedAsNoAnswer: policy.failedAsNoAnswer ?? true,
+  failedStatuses: policy.failedStatuses ?? DEFAULT_FAILED_STATUSES,
+  includeProviderPayload: policy.includeProviderPayload ?? true,
+  machineDetectionVoicemailValues: policy.machineDetectionVoicemailValues ?? DEFAULT_MACHINE_VOICEMAIL_VALUES,
+  metadata: policy.metadata,
+  minAnsweredDurationMs: policy.minAnsweredDurationMs,
+  noAnswerOnZeroDuration: policy.noAnswerOnZeroDuration ?? true,
+  noAnswerSipCodes: policy.noAnswerSipCodes ?? DEFAULT_NO_ANSWER_SIP_CODES,
+  noAnswerStatuses: policy.noAnswerStatuses ?? DEFAULT_NO_ANSWER_STATUSES,
+  statusMap: policy.statusMap,
+  transferStatuses: policy.transferStatuses ?? DEFAULT_TRANSFER_STATUSES,
+  transferTarget: policy.transferTarget,
+  voicemailStatuses: policy.voicemailStatuses ?? DEFAULT_VOICEMAIL_STATUSES
+});
+var resolveVoiceTelephonyOutcome = (event, policyInput = {}) => {
+  const policy = createVoiceTelephonyOutcomePolicy(policyInput);
+  const status = normalizeToken(event.status);
+  const provider = normalizeToken(event.provider);
+  const answeredBy = normalizeToken(event.answeredBy);
+  const target = resolveTransferTarget(event, policy);
+  if (status) {
+    const mapped = policy.statusMap?.[status] ?? (provider ? policy.statusMap?.[`${provider}:${status}`] : undefined);
+    if (mapped) {
+      return withDecisionDefaults(mapped, {
+        event,
+        policy,
+        source: "policy"
+      });
+    }
+  }
+  if (answeredBy && normalizeList(policy.machineDetectionVoicemailValues, []).has(answeredBy)) {
+    return buildDecision("voicemail", { event, policy, source: "answered-by" });
+  }
+  if (typeof event.sipCode === "number" && policy.noAnswerSipCodes.includes(event.sipCode)) {
+    return buildDecision("no-answer", { event, policy, source: "sip" });
+  }
+  if (target && status && normalizeList(policy.transferStatuses, []).has(status)) {
+    return buildDecision("transfer", { event, policy, source: "status" });
+  }
+  if (status && normalizeList(policy.voicemailStatuses, []).has(status)) {
+    return buildDecision("voicemail", { event, policy, source: "status" });
+  }
+  if (status && normalizeList(policy.escalationStatuses, []).has(status)) {
+    return buildDecision("escalate", { event, policy, source: "status" });
+  }
+  if (status && (policy.failedAsNoAnswer ? normalizeList(policy.noAnswerStatuses, []).has(status) || normalizeList(policy.failedStatuses, []).has(status) : normalizeList(policy.noAnswerStatuses, []).has(status))) {
+    return buildDecision("no-answer", { event, policy, source: "status" });
+  }
+  if (policy.noAnswerOnZeroDuration && typeof event.durationMs === "number" && event.durationMs <= 0) {
+    return buildDecision("no-answer", { event, policy, source: "duration" });
+  }
+  if (typeof policy.minAnsweredDurationMs === "number" && typeof event.durationMs === "number" && event.durationMs < policy.minAnsweredDurationMs) {
+    return {
+      ...buildDecision("no-answer", { event, policy, source: "duration" }),
+      confidence: "medium"
+    };
+  }
+  if (status && normalizeList(policy.completedStatuses, []).has(status)) {
+    return buildDecision("complete", { event, policy, source: "status" });
+  }
+  if (target) {
+    return {
+      ...buildDecision("transfer", { event, policy, source: "explicit-target" }),
+      confidence: "medium"
+    };
+  }
+  return buildDecision("ignore", { event, policy, source: "status" });
+};
+var voiceTelephonyOutcomeToRouteResult = (decision, result) => {
+  switch (decision.action) {
+    case "complete":
+      return { complete: true, result };
+    case "escalate":
+      return {
+        escalate: {
+          metadata: decision.metadata,
+          reason: decision.reason ?? "telephony-escalation"
+        },
+        result
+      };
+    case "no-answer":
+      return {
+        noAnswer: {
+          metadata: decision.metadata
+        },
+        result
+      };
+    case "transfer":
+      if (!decision.target) {
+        return { result };
+      }
+      return {
+        result,
+        transfer: {
+          metadata: decision.metadata,
+          reason: decision.reason,
+          target: decision.target
+        }
+      };
+    case "voicemail":
+      return {
+        result,
+        voicemail: {
+          metadata: decision.metadata
+        }
+      };
+    default:
+      return { result };
+  }
+};
+var applyVoiceTelephonyOutcome = async (api, decision, result) => {
+  switch (decision.action) {
+    case "complete":
+      await api.complete(result);
+      break;
+    case "escalate":
+      await api.escalate({
+        metadata: decision.metadata,
+        reason: decision.reason ?? "telephony-escalation",
+        result
+      });
+      break;
+    case "no-answer":
+      await api.markNoAnswer({
+        metadata: decision.metadata,
+        result
+      });
+      break;
+    case "transfer":
+      if (!decision.target) {
+        return;
+      }
+      await api.transfer({
+        metadata: decision.metadata,
+        reason: decision.reason,
+        result,
+        target: decision.target
+      });
+      break;
+    case "voicemail":
+      await api.markVoicemail({
+        metadata: decision.metadata,
+        result
+      });
+      break;
+    default:
+      break;
+  }
+};
+var parseRequestBodyText = (input) => {
+  const { contentType, text } = input;
+  if (!text) {
+    return {};
+  }
+  if (contentType.includes("application/json")) {
+    return parseMaybeJSON(text) ?? {};
+  }
+  if (contentType.includes("application/x-www-form-urlencoded") || contentType.includes("multipart/form-data")) {
+    return Object.fromEntries(new URLSearchParams(text));
+  }
+  return parseMaybeJSON(text) ?? Object.fromEntries(new URLSearchParams(text));
+};
+var readRequestBody = async (request) => {
+  const contentType = request.headers.get("content-type") ?? "";
+  const text = await request.text();
+  return {
+    body: parseRequestBodyText({ contentType, text }),
+    rawBody: text
+  };
+};
+var signVoiceTwilioWebhook = async (input) => signHmacSHA1Base64(input.authToken, `${input.url}${sortedParamsForSignature(input.body ?? {})}`);
+var verifyVoiceTwilioWebhookSignature = async (input) => {
+  if (!input.authToken) {
+    return { ok: false, reason: "missing-secret" };
+  }
+  const signature = input.headers.get("x-twilio-signature");
+  if (!signature) {
+    return { ok: false, reason: "missing-signature" };
+  }
+  const expected = await signVoiceTwilioWebhook({
+    authToken: input.authToken,
+    body: input.body,
+    url: input.url
+  });
+  return timingSafeEqual(signature, expected) ? { ok: true } : { ok: false, reason: "invalid-signature" };
+};
+var resolveVerificationUrl = (option, input) => typeof option === "function" ? option(input) : option ?? input.request.url;
+var verifyVoiceTelephonyWebhook = async (input) => {
+  if (input.options.verify) {
+    return input.options.verify({
+      body: input.body,
+      headers: input.request.headers,
+      provider: input.provider,
+      query: input.query,
+      rawBody: input.rawBody,
+      request: input.request
+    });
+  }
+  if (!input.options.signingSecret) {
+    return input.options.requireVerification ? { ok: false, reason: "missing-secret" } : { ok: true };
+  }
+  if (input.provider !== "twilio") {
+    return { ok: false, reason: "unsupported-provider" };
+  }
+  return verifyVoiceTwilioWebhookSignature({
+    authToken: input.options.signingSecret,
+    body: input.body,
+    headers: input.request.headers,
+    url: resolveVerificationUrl(input.options.verificationUrl, {
+      query: input.query,
+      request: input.request
+    })
+  });
+};
+var durationMsFromSeconds = (value) => typeof value === "number" ? value * 1000 : undefined;
+var parseVoiceTelephonyWebhookEvent = (input) => {
+  const payload = flattenPayload(input.body);
+  const provider = firstString(payload, ["provider", "Provider"]) ?? input.provider;
+  const status = firstString(payload, [
+    "CallStatus",
+    "call_status",
+    "callStatus",
+    "DialCallStatus",
+    "dial_call_status",
+    "status",
+    "event_type",
+    "type"
+  ]);
+  const durationMs = firstNumber(payload, ["durationMs", "duration_ms"]) ?? durationMsFromSeconds(firstNumber(payload, [
+    "CallDuration",
+    "call_duration",
+    "callDuration",
+    "DialCallDuration",
+    "dial_call_duration",
+    "duration"
+  ]));
+  const sipCode = firstNumber(payload, [
+    "SipResponseCode",
+    "sip_response_code",
+    "sipCode",
+    "sip_code",
+    "hangupCauseCode"
+  ]);
+  const from = firstString(payload, ["From", "from", "caller_id", "callerId"]);
+  const to = firstString(payload, ["To", "to", "called_number", "calledNumber"]);
+  const target = firstString(payload, [
+    "transferTarget",
+    "TransferTarget",
+    "target",
+    "queue",
+    "department"
+  ]);
+  return {
+    answeredBy: firstString(payload, [
+      "AnsweredBy",
+      "answered_by",
+      "answeredBy",
+      "machineDetection",
+      "machine_detection"
+    ]),
+    durationMs,
+    from,
+    metadata: {
+      ...input.query,
+      ...payload
+    },
+    provider,
+    reason: firstString(payload, [
+      "Reason",
+      "reason",
+      "HangupCause",
+      "hangup_cause",
+      "hangupCause"
+    ]),
+    sipCode,
+    status,
+    target,
+    to
+  };
+};
+var defaultSessionId = (input) => {
+  const payload = flattenPayload(input.body);
+  const metadataSessionId = input.event.metadata?.sessionId;
+  return firstString(input.query, ["sessionId", "session_id"]) ?? firstString(payload, [
+    "sessionId",
+    "session_id",
+    "SessionId",
+    "CallSid",
+    "call_sid",
+    "callSid",
+    "CallUUID",
+    "call_uuid",
+    "callControlId",
+    "call_control_id"
+  ]) ?? (typeof metadataSessionId === "string" ? metadataSessionId : undefined);
+};
+var defaultIdempotencyKey = (input) => {
+  const payload = flattenPayload(input.body);
+  const eventId = firstString(payload, [
+    "id",
+    "event_id",
+    "eventId",
+    "EventSid",
+    "event_sid",
+    "MessageSid",
+    "message_sid",
+    "CallSid",
+    "call_sid",
+    "CallUUID",
+    "call_uuid",
+    "callControlId",
+    "call_control_id"
+  ]);
+  const status = normalizeToken(input.event.status) ?? "unknown";
+  if (eventId) {
+    return `${input.provider}:${eventId}:${status}`;
+  }
+  if (input.sessionId) {
+    return `${input.provider}:${input.sessionId}:${status}`;
+  }
+};
+var createVoiceTelephonyWebhookHandler = (options = {}) => async (input) => {
+  const provider = options.provider ?? "generic";
+  const query = input.query ?? {};
+  const { body, rawBody } = await readRequestBody(input.request);
+  const verification = await verifyVoiceTelephonyWebhook({
+    body,
+    options,
+    provider,
+    query,
+    rawBody,
+    request: input.request
+  });
+  if (!verification.ok) {
+    throw new VoiceTelephonyWebhookVerificationError(verification);
+  }
+  const event = options.parse ? await options.parse({
+    body,
+    headers: input.request.headers,
+    provider,
+    query,
+    request: input.request
+  }) : parseVoiceTelephonyWebhookEvent({
+    body,
+    headers: input.request.headers,
+    provider,
+    query,
+    request: input.request
+  });
+  const sessionId = await (options.resolveSessionId?.({
+    body,
+    event,
+    query,
+    request: input.request
+  }) ?? defaultSessionId({ body, event, query }));
+  const idempotencyEnabled = options.idempotency?.enabled !== false;
+  const idempotencyKey = idempotencyEnabled ? await (options.idempotency?.key?.({
+    body,
+    event,
+    provider,
+    query,
+    request: input.request,
+    sessionId
+  }) ?? defaultIdempotencyKey({ body, event, provider, sessionId })) : undefined;
+  const idempotencyStore = options.idempotency?.store;
+  if (idempotencyKey && idempotencyStore) {
+    const existing = await idempotencyStore.get(idempotencyKey);
+    if (existing) {
+      const duplicateDecision = {
+        ...existing,
+        duplicate: true
+      };
+      await options.onDecision?.({
+        ...duplicateDecision,
+        context: options.context,
+        request: input.request
+      });
+      return duplicateDecision;
+    }
+  }
+  const decision = resolveVoiceTelephonyOutcome(event, options.policy);
+  const resultResolver = options.result;
+  const result = typeof resultResolver === "function" ? await resultResolver({
+    decision,
+    event,
+    sessionId
+  }) : resultResolver;
+  const routeResult = voiceTelephonyOutcomeToRouteResult(decision, result);
+  const shouldApply = typeof options.apply === "function" ? options.apply({
+    applied: false,
+    decision,
+    event,
+    routeResult,
+    sessionId
+  }) : options.apply === true;
+  let applied = false;
+  if (shouldApply && decision.action !== "ignore" && options.getSessionHandle) {
+    const api = await options.getSessionHandle({
+      context: options.context,
+      decision,
+      event,
+      request: input.request,
+      sessionId
+    });
+    if (api) {
+      await applyVoiceTelephonyOutcome(api, decision, result);
+      applied = true;
+    }
+  }
+  const webhookDecision = {
+    applied,
+    decision,
+    event,
+    idempotencyKey,
+    routeResult,
+    sessionId
+  };
+  if (idempotencyKey && idempotencyStore) {
+    const now = Date.now();
+    await idempotencyStore.set(idempotencyKey, {
+      ...webhookDecision,
+      createdAt: now,
+      updatedAt: now
+    });
+  }
+  await options.onDecision?.({
+    ...webhookDecision,
+    context: options.context,
+    request: input.request
+  });
+  return webhookDecision;
+};
+var createVoiceTelephonyWebhookRoutes = (options = {}) => {
+  const path = options.path ?? "/api/voice/telephony/webhook";
+  const handler = createVoiceTelephonyWebhookHandler(options);
+  return new Elysia({
+    name: options.name ?? "absolutejs-voice-telephony-webhooks"
+  }).post(path, async ({ query, request }) => {
+    try {
+      return await handler({ query, request });
+    } catch (error) {
+      if (error instanceof VoiceTelephonyWebhookVerificationError) {
+        return new Response(JSON.stringify({ verification: error.result }), {
+          headers: {
+            "content-type": "application/json"
+          },
+          status: 401
+        });
+      }
+      throw error;
+    }
+  }, {
+    parse: "none"
+  });
+};
+
+// src/telephony/twilio.ts
 var TWILIO_MULAW_SAMPLE_RATE = 8000;
 var VOICE_PCM_SAMPLE_RATE = 16000;
-var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+var escapeXml2 = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+var resolveRequestOrigin = (request) => {
+  const url = new URL(request.url);
+  const forwardedHost = request.headers.get("x-forwarded-host");
+  const forwardedProto = request.headers.get("x-forwarded-proto");
+  const host = forwardedHost ?? request.headers.get("host") ?? url.host;
+  const protocol = forwardedProto ?? url.protocol.replace(":", "");
+  return `${protocol}://${host}`;
+};
+var resolveTwilioStreamUrl = async (options, input) => {
+  if (typeof options.twiml?.streamUrl === "function") {
+    return options.twiml.streamUrl(input);
+  }
+  if (typeof options.twiml?.streamUrl === "string") {
+    return options.twiml.streamUrl;
+  }
+  const origin = resolveRequestOrigin(input.request);
+  const wsOrigin = origin.replace(/^http:/, "ws:").replace(/^https:/, "wss:");
+  return `${wsOrigin}${input.streamPath}`;
+};
+var resolveTwilioStreamParameters = async (parameters, input) => {
+  if (typeof parameters === "function") {
+    return parameters(input);
+  }
+  return parameters;
+};
+var joinUrlPath = (origin, path) => `${origin.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+var escapeHtml2 = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&#39;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+var getWebhookVerificationUrl = (webhook, input) => {
+  if (!webhook?.verificationUrl) {
+    return;
+  }
+  if (typeof webhook.verificationUrl === "function") {
+    return webhook.verificationUrl(input);
+  }
+  return webhook.verificationUrl;
+};
+var buildTwilioVoiceSetupStatus = async (options, input) => {
+  const origin = resolveRequestOrigin(input.request);
+  const stream = await resolveTwilioStreamUrl(options, input);
+  const twiml = joinUrlPath(origin, input.twimlPath);
+  const webhook = joinUrlPath(origin, input.webhookPath);
+  const verificationUrl = getWebhookVerificationUrl(options.webhook, input);
+  const missing = Object.entries(options.setup?.requiredEnv ?? {}).filter((entry) => !entry[1]).map(([name]) => name);
+  const signingConfigured = Boolean(options.webhook?.signingSecret || options.webhook?.verify);
+  const warnings = [
+    ...stream.startsWith("wss://") ? [] : ["Twilio media streams should use wss:// in production."],
+    ...signingConfigured ? [] : ["Webhook signature verification is not configured."],
+    ...verificationUrl || !signingConfigured ? [] : ["Webhook signing is configured without an explicit verification URL."]
+  ];
+  return {
+    generatedAt: Date.now(),
+    missing,
+    provider: "twilio",
+    ready: missing.length === 0 && signingConfigured && warnings.length === 0,
+    signing: {
+      configured: signingConfigured,
+      mode: options.webhook?.verify ? "custom" : options.webhook?.signingSecret ? "twilio-signature" : "none",
+      verificationUrl
+    },
+    urls: {
+      stream,
+      twiml,
+      webhook
+    },
+    warnings
+  };
+};
+var renderTwilioVoiceSetupHTML = (status, title) => `<main style="font-family: ui-sans-serif, system-ui; max-width: 860px; margin: 40px auto; padding: 0 20px;">
+<p style="letter-spacing: .12em; text-transform: uppercase; color: #52606d;">Twilio setup</p>
+<h1>${escapeHtml2(title)}</h1>
+<p><strong>Status:</strong> ${status.ready ? "Ready" : "Needs attention"}</p>
+<section>
+<h2>URLs</h2>
+<ul>
+<li><strong>TwiML:</strong> <code>${escapeHtml2(status.urls.twiml)}</code></li>
+<li><strong>Media stream:</strong> <code>${escapeHtml2(status.urls.stream)}</code></li>
+<li><strong>Status webhook:</strong> <code>${escapeHtml2(status.urls.webhook)}</code></li>
+</ul>
+</section>
+<section>
+<h2>Signing</h2>
+<p>Mode: <code>${status.signing.mode}</code></p>
+${status.signing.verificationUrl ? `<p>Verification URL: <code>${escapeHtml2(status.signing.verificationUrl)}</code></p>` : ""}
+</section>
+${status.missing.length ? `<section><h2>Missing env</h2><ul>${status.missing.map((name) => `<li><code>${escapeHtml2(name)}</code></li>`).join("")}</ul></section>` : ""}
+${status.warnings.length ? `<section><h2>Warnings</h2><ul>${status.warnings.map((warning) => `<li>${escapeHtml2(warning)}</li>`).join("")}</ul></section>` : ""}
+</main>`;
+var extractTwilioStreamUrl = (twiml) => twiml.match(/<Stream\b[^>]*\surl="([^"]+)"/i)?.[1]?.replaceAll("&amp;", "&");
+var createSmokeCheck = (name, status, message, details) => ({
+  details,
+  message,
+  name,
+  status
+});
+var renderTwilioVoiceSmokeHTML = (report, title) => `<main style="font-family: ui-sans-serif, system-ui; max-width: 860px; margin: 40px auto; padding: 0 20px;">
+<p style="letter-spacing: .12em; text-transform: uppercase; color: #52606d;">Twilio smoke test</p>
+<h1>${escapeHtml2(title)}</h1>
+<p><strong>Status:</strong> ${report.pass ? "Pass" : "Fail"}</p>
+<section>
+<h2>Checks</h2>
+<ul>
+${report.checks.map((check) => `<li><strong>${escapeHtml2(check.name)}</strong>: ${escapeHtml2(check.status)}${check.message ? ` - ${escapeHtml2(check.message)}` : ""}</li>`).join("")}
+</ul>
+</section>
+<section>
+<h2>Observed URLs</h2>
+<ul>
+<li><strong>TwiML:</strong> <code>${escapeHtml2(report.setup.urls.twiml)}</code></li>
+<li><strong>Stream:</strong> <code>${escapeHtml2(report.twiml?.streamUrl ?? report.setup.urls.stream)}</code></li>
+<li><strong>Webhook:</strong> <code>${escapeHtml2(report.setup.urls.webhook)}</code></li>
+</ul>
+</section>
+</main>`;
+var runTwilioVoiceSmokeTest = async (input) => {
+  const setup = await buildTwilioVoiceSetupStatus(input.options, input);
+  const checks = [];
+  const twimlUrl = new URL(setup.urls.twiml);
+  twimlUrl.searchParams.set("scenarioId", input.options.smoke?.scenarioId ?? "smoke");
+  twimlUrl.searchParams.set("sessionId", input.options.smoke?.sessionId ?? "smoke-session");
+  const twimlResponse = await input.app.handle(new Request(twimlUrl, {
+    headers: input.request.headers
+  }));
+  const twiml = await twimlResponse.text();
+  const streamUrl = extractTwilioStreamUrl(twiml);
+  checks.push(createSmokeCheck("twiml", twimlResponse.ok && Boolean(streamUrl) ? "pass" : "fail", streamUrl ? "TwiML includes a media stream URL." : 'TwiML is missing <Stream url="...">.', {
+    status: twimlResponse.status,
+    streamUrl
+  }));
+  checks.push(createSmokeCheck("stream-url", streamUrl?.startsWith("wss://") ? "pass" : "fail", streamUrl?.startsWith("wss://") ? "Media stream URL uses wss://." : "Media stream URL should use wss:// for Twilio.", {
+    streamUrl
+  }));
+  const webhookBody = {
+    CallSid: input.options.smoke?.callSid ?? "CA_SMOKE_TEST",
+    CallStatus: input.options.smoke?.status ?? "busy",
+    SipResponseCode: String(input.options.smoke?.sipCode ?? 486)
+  };
+  const webhookHeaders = new Headers({
+    "content-type": "application/x-www-form-urlencoded"
+  });
+  const verificationUrl = setup.signing.verificationUrl ?? setup.urls.webhook;
+  if (input.options.webhook?.signingSecret) {
+    webhookHeaders.set("x-twilio-signature", await signVoiceTwilioWebhook({
+      authToken: input.options.webhook.signingSecret,
+      body: webhookBody,
+      url: verificationUrl
+    }));
+  }
+  const webhookResponse = await input.app.handle(new Request(setup.urls.webhook, {
+    body: new URLSearchParams(webhookBody),
+    headers: webhookHeaders,
+    method: "POST"
+  }));
+  const webhookText = await webhookResponse.text();
+  const webhookPayload = (() => {
+    try {
+      return JSON.parse(webhookText);
+    } catch {
+      return webhookText;
+    }
+  })();
+  checks.push(createSmokeCheck("webhook", webhookResponse.ok ? "pass" : "fail", webhookResponse.ok ? "Synthetic Twilio status callback was accepted." : "Synthetic Twilio status callback failed.", {
+    status: webhookResponse.status
+  }));
+  for (const warning of setup.warnings) {
+    checks.push(createSmokeCheck("setup-warning", "warn", warning));
+  }
+  for (const name of setup.missing) {
+    checks.push(createSmokeCheck("missing-env", "fail", `${name} is missing.`));
+  }
+  return {
+    checks,
+    generatedAt: Date.now(),
+    pass: checks.every((check) => check.status !== "fail"),
+    provider: "twilio",
+    setup,
+    twiml: {
+      status: twimlResponse.status,
+      streamUrl
+    },
+    webhook: {
+      body: webhookPayload,
+      status: webhookResponse.status
+    }
+  };
+};
 var normalizeOnTurn = (handler) => {
   if (handler.length > 1) {
     const directHandler = handler;
@@ -7327,7 +9139,7 @@ var bytesToInt16Array = (bytes) => {
   return output;
 };
 var decodeTwilioMulawBase64 = (payload) => {
-  const bytes = Uint8Array.from(Buffer2.from(payload, "base64"));
+  const bytes = Uint8Array.from(Buffer3.from(payload, "base64"));
   const samples = new Int16Array(bytes.length);
   for (let index = 0;index < bytes.length; index += 1) {
     samples[index] = decodeMulawSample(bytes[index] ?? 0);
@@ -7339,7 +9151,7 @@ var encodeTwilioMulawBase64 = (samples) => {
   for (let index = 0;index < samples.length; index += 1) {
     bytes[index] = encodeMulawSample(samples[index] ?? 0);
   }
-  return Buffer2.from(bytes).toString("base64");
+  return Buffer3.from(bytes).toString("base64");
 };
 var transcodeTwilioInboundPayloadToPCM16 = (payload) => {
   const narrowband = decodeTwilioMulawBase64(payload);
@@ -7348,7 +9160,7 @@ var transcodeTwilioInboundPayloadToPCM16 = (payload) => {
 };
 var transcodePCMToTwilioOutboundPayload = (chunk, format) => {
   if (format.container === "raw" && format.encoding === "mulaw" && format.channels === 1 && format.sampleRateHz === TWILIO_MULAW_SAMPLE_RATE) {
-    return Buffer2.from(chunk).toString("base64");
+    return Buffer3.from(chunk).toString("base64");
   }
   if (format.encoding !== "pcm_s16le") {
     throw new Error(`Unsupported outbound telephony audio format: ${format.container}/${format.encoding}`);
@@ -7389,7 +9201,7 @@ var createTwilioSocketAdapter = (socket, getState) => ({
       return;
     }
     if (message.type === "audio") {
-      const payload = transcodePCMToTwilioOutboundPayload(Uint8Array.from(Buffer2.from(message.chunkBase64, "base64")), message.format);
+      const payload = transcodePCMToTwilioOutboundPayload(Uint8Array.from(Buffer3.from(message.chunkBase64, "base64")), message.format);
       state.hasOutboundAudioSinceLastInbound = true;
       state.reviewRecorder?.recordTwilioOutbound({
         bytes: payload.length,
@@ -7421,8 +9233,8 @@ var createTwilioSocketAdapter = (socket, getState) => ({
   }
 });
 var createTwilioVoiceResponse = (options) => {
-  const parameters = Object.entries(options.parameters ?? {}).filter((entry) => entry[1] !== undefined).map(([name, value]) => `<Parameter name="${escapeXml(name)}" value="${escapeXml(String(value))}" />`).join("");
-  return `<?xml version="1.0" encoding="UTF-8"?><Response><Connect><Stream url="${escapeXml(options.streamUrl)}"${options.track ? ` track="${escapeXml(options.track)}"` : ""}${options.streamName ? ` name="${escapeXml(options.streamName)}"` : ""}>${parameters}</Stream></Connect></Response>`;
+  const parameters = Object.entries(options.parameters ?? {}).filter((entry) => entry[1] !== undefined).map(([name, value]) => `<Parameter name="${escapeXml2(name)}" value="${escapeXml2(String(value))}" />`).join("");
+  return `<?xml version="1.0" encoding="UTF-8"?><Response><Connect><Stream url="${escapeXml2(options.streamUrl)}"${options.track ? ` track="${escapeXml2(options.track)}"` : ""}${options.streamName ? ` name="${escapeXml2(options.streamName)}"` : ""}>${parameters}</Stream></Connect></Response>`;
 };
 var createTwilioMediaStreamBridge = (socket, options) => {
   const runtimePreset = resolveVoiceRuntimePreset(options.preset);
@@ -7602,6 +9414,148 @@ var createTwilioMediaStreamBridge = (socket, options) => {
     }
   };
 };
+var createTwilioVoiceRoutes = (options) => {
+  const streamPath = options.streamPath ?? "/api/voice/twilio/stream";
+  const twimlPath = options.twiml?.path ?? "/api/voice/twilio";
+  const webhookPath = options.webhook?.path ?? "/api/voice/twilio/webhook";
+  const setupPath = options.setup?.path === false ? false : options.setup?.path ?? "/api/voice/twilio/setup";
+  const smokePath = options.smoke?.path === false ? false : options.smoke?.path ?? "/api/voice/twilio/smoke";
+  const bridges = new WeakMap;
+  const webhookPolicy = options.webhook?.policy ?? options.outcomePolicy ?? createVoiceTelephonyOutcomePolicy();
+  const app = new Elysia2({
+    name: options.name ?? "absolutejs-voice-twilio"
+  }).get(twimlPath, async ({ query, request }) => {
+    const streamUrl = await resolveTwilioStreamUrl(options, {
+      query,
+      request,
+      streamPath
+    });
+    const parameters = await resolveTwilioStreamParameters(options.twiml?.parameters, {
+      query,
+      request
+    });
+    return new Response(createTwilioVoiceResponse({
+      parameters,
+      streamName: options.twiml?.streamName,
+      streamUrl,
+      track: options.twiml?.track
+    }), {
+      headers: {
+        "content-type": "text/xml; charset=utf-8"
+      }
+    });
+  }).post(twimlPath, async ({ query, request }) => {
+    const streamUrl = await resolveTwilioStreamUrl(options, {
+      query,
+      request,
+      streamPath
+    });
+    const parameters = await resolveTwilioStreamParameters(options.twiml?.parameters, {
+      query,
+      request
+    });
+    return new Response(createTwilioVoiceResponse({
+      parameters,
+      streamName: options.twiml?.streamName,
+      streamUrl,
+      track: options.twiml?.track
+    }), {
+      headers: {
+        "content-type": "text/xml; charset=utf-8"
+      }
+    });
+  }).ws(streamPath, {
+    close: async (ws, _code, reason) => {
+      const bridge = bridges.get(ws);
+      bridges.delete(ws);
+      await bridge?.close(reason);
+    },
+    message: async (ws, raw) => {
+      let bridge = bridges.get(ws);
+      if (!bridge) {
+        bridge = createTwilioMediaStreamBridge({
+          close: (code, reason) => {
+            ws.close(code, reason);
+          },
+          send: (data) => {
+            ws.send(data);
+          }
+        }, options);
+        bridges.set(ws, bridge);
+      }
+      await bridge.handleMessage(raw);
+    }
+  }).use(createVoiceTelephonyWebhookRoutes({
+    ...options.webhook ?? {},
+    context: options.context,
+    path: webhookPath,
+    policy: webhookPolicy,
+    provider: "twilio"
+  }));
+  if (!setupPath) {
+    if (!smokePath) {
+      return app;
+    }
+    return app.get(smokePath, async ({ query, request }) => {
+      const report = await runTwilioVoiceSmokeTest({
+        app,
+        options,
+        query,
+        request,
+        streamPath,
+        twimlPath,
+        webhookPath
+      });
+      if (query.format === "html") {
+        return new Response(renderTwilioVoiceSmokeHTML(report, options.smoke?.title ?? "AbsoluteJS Twilio Voice Smoke Test"), {
+          headers: {
+            "content-type": "text/html; charset=utf-8"
+          }
+        });
+      }
+      return report;
+    });
+  }
+  const withSetup = app.get(setupPath, async ({ query, request }) => {
+    const status = await buildTwilioVoiceSetupStatus(options, {
+      query,
+      request,
+      streamPath,
+      twimlPath,
+      webhookPath
+    });
+    if (query.format === "html") {
+      return new Response(renderTwilioVoiceSetupHTML(status, options.setup?.title ?? "AbsoluteJS Twilio Voice Setup"), {
+        headers: {
+          "content-type": "text/html; charset=utf-8"
+        }
+      });
+    }
+    return status;
+  });
+  if (!smokePath) {
+    return withSetup;
+  }
+  return withSetup.get(smokePath, async ({ query, request }) => {
+    const report = await runTwilioVoiceSmokeTest({
+      app,
+      options,
+      query,
+      request,
+      streamPath,
+      twimlPath,
+      webhookPath
+    });
+    if (query.format === "html") {
+      return new Response(renderTwilioVoiceSmokeHTML(report, options.smoke?.title ?? "AbsoluteJS Twilio Voice Smoke Test"), {
+        headers: {
+          "content-type": "text/html; charset=utf-8"
+        }
+      });
+    }
+    return report;
+  });
+};
 
 // src/testing/telephony.ts
 var DEFAULT_PCM16_FORMAT = {
@@ -7867,7 +9821,7 @@ var runVoiceTelephonyBenchmark = async (scenarios = getDefaultVoiceTelephonyBenc
   };
 };
 // src/testing/tts.ts
-var DEFAULT_REALTIME_FORMAT = {
+var DEFAULT_REALTIME_FORMAT2 = {
   channels: 1,
   container: "raw",
   encoding: "pcm_s16le",
@@ -7926,7 +9880,7 @@ var runTTSAdapterFixture = async (adapter, fixture, options = {}) => {
   let audioDurationMs = 0;
   let audioChunkCount = 0;
   const session = adapter.kind === "realtime" ? await adapter.open({
-    format: options.realtimeFormat ?? DEFAULT_REALTIME_FORMAT,
+    format: options.realtimeFormat ?? DEFAULT_REALTIME_FORMAT2,
     sessionId: `tts-benchmark:${fixture.id}`,
     ...openOptions ?? {}
   }) : await adapter.open({
@@ -8093,6 +10047,7 @@ export {
   getDefaultTTSBenchmarkFixtures,
   evaluateSTTBenchmarkAcceptance,
   createVoiceProviderFailureSimulator,
+  createVoiceIOProviderFailureSimulator,
   createVoiceCallReviewRecorder,
   createVoiceCallReviewFromLiveTelephonyReport,
   createTelephonyVoiceTestFixtures,