@absolutejs/voice 0.0.22-beta.7 → 0.0.22-beta.70

package/dist/testing/index.js

@@ -2105,6 +2105,12 @@ var serverMessageToAction = (message) => {
         sessionId: message.sessionId,
         type: "complete"
       };
+    case "call_lifecycle":
+      return {
+        event: message.event,
+        sessionId: message.sessionId,
+        type: "call_lifecycle"
+      };
     case "error":
       return {
         message: normalizeErrorMessage(message.message),
@@ -2148,7 +2154,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 +2162,7 @@ var NOOP_CONNECTION = {
   getSessionId: () => "",
   send: noop,
   sendAudio: noop,
+  start: () => {},
   subscribe: noopUnsubscribe
 };
 var createSessionId = () => crypto.randomUUID();
@@ -2177,6 +2184,7 @@ var isVoiceServerMessage = (value) => {
   switch (value.type) {
     case "audio":
     case "assistant":
+    case "call_lifecycle":
     case "complete":
     case "error":
     case "final":
@@ -2317,6 +2325,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 +2348,7 @@ var createVoiceConnection = (path, options = {}) => {
   };
   connect();
   return {
-    start,
+    callControl,
     close,
     endTurn,
     getReadyState: () => state.ws?.readyState ?? WS_CLOSED,
@@ -2342,6 +2356,7 @@ var createVoiceConnection = (path, options = {}) => {
     getSessionId: () => state.sessionId,
     send,
     sendAudio,
+    start,
     subscribe
   };
 };
@@ -2350,6 +2365,7 @@ var createVoiceConnection = (path, options = {}) => {
 var createInitialState2 = () => ({
   assistantAudio: [],
   assistantTexts: [],
+  call: null,
   error: null,
   isConnected: false,
   scenarioId: null,
@@ -2393,6 +2409,20 @@ 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,
@@ -2479,6 +2509,9 @@ var createVoiceStream = (path, options = {}) => {
     }
   });
   return {
+    callControl(message) {
+      connection.callControl(message);
+    },
     close() {
       unsubscribeConnection();
       connection.close();
@@ -2522,6 +2555,9 @@ var createVoiceStream = (path, options = {}) => {
     get assistantAudio() {
       return store.getSnapshot().assistantAudio;
     },
+    get call() {
+      return store.getSnapshot().call;
+    },
     sendAudio(audio) {
       connection.sendAudio(audio);
     },
@@ -2854,6 +2890,7 @@ var resolveVoiceRuntimePreset = (name = "default") => {
 var createInitialState3 = (stream) => ({
   assistantAudio: [...stream.assistantAudio],
   assistantTexts: [...stream.assistantTexts],
+  call: stream.call,
   error: stream.error,
   isConnected: stream.isConnected,
   isRecording: false,
@@ -2883,6 +2920,7 @@ var createVoiceController = (path, options = {}) => {
       ...state,
       assistantAudio: [...stream.assistantAudio],
       assistantTexts: [...stream.assistantTexts],
+      call: stream.call,
       error: stream.error,
       isConnected: stream.isConnected,
       partial: stream.partial,
@@ -2960,6 +2998,7 @@ var createVoiceController = (path, options = {}) => {
     bindHTMX(bindingOptions) {
       return bindVoiceHTMX(stream, bindingOptions);
     },
+    callControl: (message) => stream.callControl(message),
     close,
     endTurn: () => stream.endTurn(),
     get error() {
@@ -3012,6 +3051,9 @@ var createVoiceController = (path, options = {}) => {
     },
     get assistantAudio() {
       return state.assistantAudio;
+    },
+    get call() {
+      return state.call;
     }
   };
 };
@@ -3468,6 +3510,1004 @@ 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: {
+    assistantText: {
+      type: "string"
+    },
+    complete: {
+      type: "boolean"
+    },
+    escalate: {
+      additionalProperties: false,
+      properties: {
+        metadata: {
+          additionalProperties: true,
+          type: "object"
+        },
+        reason: {
+          type: "string"
+        }
+      },
+      required: ["reason"],
+      type: "object"
+    },
+    noAnswer: {
+      additionalProperties: false,
+      properties: {
+        metadata: {
+          additionalProperties: true,
+          type: "object"
+        }
+      },
+      type: "object"
+    },
+    result: {
+      additionalProperties: true,
+      type: "object"
+    },
+    transfer: {
+      additionalProperties: false,
+      properties: {
+        metadata: {
+          additionalProperties: true,
+          type: "object"
+        },
+        reason: {
+          type: "string"
+        },
+        target: {
+          type: "string"
+        }
+      },
+      required: ["target"],
+      type: "object"
+    },
+    voicemail: {
+      additionalProperties: false,
+      properties: {
+        metadata: {
+          additionalProperties: true,
+          type: "object"
+        }
+      },
+      type: "object"
+    }
+  },
+  type: "object"
+};
+var ROUTE_RESULT_INSTRUCTION = "Return only a JSON object with assistantText, complete, transfer, escalate, voicemail, noAnswer, and result when you are not calling tools. Only set transfer, escalate, voicemail, or noAnswer when the user explicitly asks for that lifecycle outcome or a tool result says that exact outcome. Do not infer voicemail from generic words like voice, voice app, or voice integration.";
+var stripJSONCodeFence = (value) => {
+  const trimmed = value.trim();
+  const match = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  return match?.[1]?.trim() ?? value;
+};
+var parseJSON = (value) => {
+  try {
+    const parsed = JSON.parse(stripJSONCodeFence(value));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {
+      assistantText: value
+    };
+  }
+};
+var parseJSONValue = (value) => {
+  try {
+    return JSON.parse(value);
+  } catch {
+    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") : [];
+};
+var createHTTPError = (provider, response) => new Error(`${provider} voice assistant model failed: HTTP ${response.status}`);
+var sleep = (ms) => new Promise((resolve2) => {
+  setTimeout(resolve2, ms);
+});
+var errorMessage = (error) => error instanceof Error ? error.message : String(error);
+var defaultIsRateLimitError = (error) => /(\b429\b|rate limit|quota|too many requests)/i.test(errorMessage(error));
+var normalizeRouteOutput = (output) => {
+  const result = {};
+  if (typeof output.assistantText === "string") {
+    result.assistantText = output.assistantText;
+  }
+  if (typeof output.complete === "boolean") {
+    result.complete = output.complete;
+  }
+  if (output.result !== undefined) {
+    result.result = output.result;
+  }
+  if (output.transfer && typeof output.transfer === "object") {
+    const transfer = output.transfer;
+    if (typeof transfer.target === "string") {
+      result.transfer = {
+        metadata: transfer.metadata && typeof transfer.metadata === "object" ? transfer.metadata : undefined,
+        reason: typeof transfer.reason === "string" ? transfer.reason : undefined,
+        target: transfer.target
+      };
+    }
+  }
+  if (output.escalate && typeof output.escalate === "object") {
+    const escalate = output.escalate;
+    if (typeof escalate.reason === "string") {
+      result.escalate = {
+        metadata: escalate.metadata && typeof escalate.metadata === "object" ? escalate.metadata : undefined,
+        reason: escalate.reason
+      };
+    }
+  }
+  if (output.voicemail && typeof output.voicemail === "object") {
+    const voicemail = output.voicemail;
+    result.voicemail = {
+      metadata: voicemail.metadata && typeof voicemail.metadata === "object" ? voicemail.metadata : undefined
+    };
+  }
+  if (output.noAnswer && typeof output.noAnswer === "object") {
+    const noAnswer = output.noAnswer;
+    result.noAnswer = {
+      metadata: noAnswer.metadata && typeof noAnswer.metadata === "object" ? noAnswer.metadata : undefined
+    };
+  }
+  return result;
+};
+var createJSONVoiceAssistantModel = (options) => ({
+  generate: async (input) => {
+    const output = await options.generate(input);
+    if ("assistantText" in output || "toolCalls" in output || "complete" in output || "transfer" in output || "escalate" in output) {
+      return output;
+    }
+    return options.mapOutput?.(output) ?? normalizeRouteOutput(output);
+  }
+});
+var createVoiceProviderRouter = (options) => {
+  const providerIds = Object.keys(options.providers);
+  const firstProvider = providerIds[0];
+  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";
+  const fallbackMode = policy?.fallbackMode ?? options.fallbackMode ?? "provider-error";
+  const healthOptions = typeof options.providerHealth === "object" ? options.providerHealth : options.providerHealth ? {} : undefined;
+  const healthState = new Map;
+  const now = () => healthOptions?.now?.() ?? Date.now();
+  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) {
+      return existing;
+    }
+    const next = {
+      consecutiveFailures: 0,
+      provider,
+      status: "healthy"
+    };
+    healthState.set(provider, next);
+    return next;
+  };
+  const cloneHealth = (provider) => {
+    if (!healthOptions) {
+      return;
+    }
+    return {
+      ...getHealth(provider)
+    };
+  };
+  const getSuppressionRemainingMs = (provider) => {
+    if (!healthOptions) {
+      return;
+    }
+    const suppressedUntil = getHealth(provider).suppressedUntil;
+    return typeof suppressedUntil === "number" ? Math.max(0, suppressedUntil - now()) : undefined;
+  };
+  const isSuppressed = (provider) => {
+    if (!healthOptions) {
+      return false;
+    }
+    const health = getHealth(provider);
+    return typeof health.suppressedUntil === "number" && health.suppressedUntil > now();
+  };
+  const recordProviderSuccess = (provider) => {
+    if (!healthOptions) {
+      return;
+    }
+    const health = getHealth(provider);
+    health.consecutiveFailures = 0;
+    health.status = "healthy";
+    health.suppressedUntil = undefined;
+    return cloneHealth(provider);
+  };
+  const recordProviderError = (provider, isProviderError, rateLimited) => {
+    if (!healthOptions || !isProviderError) {
+      return cloneHealth(provider);
+    }
+    const currentTime = now();
+    const health = getHealth(provider);
+    health.consecutiveFailures += 1;
+    health.lastFailureAt = currentTime;
+    if (rateLimited) {
+      health.lastRateLimitedAt = currentTime;
+    }
+    if (rateLimited || health.consecutiveFailures >= failureThreshold) {
+      health.status = "suppressed";
+      health.suppressedUntil = currentTime + (rateLimited ? rateLimitCooldownMs : cooldownMs);
+    }
+    return cloneHealth(provider);
+  };
+  const resolveAllowedProviders = async (input) => {
+    const allowProviders = policy?.allowProviders ?? options.allowProviders;
+    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" && 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);
+    });
+  };
+  const resolveOrder = async (input) => {
+    const selectedProvider = await options.selectProvider?.(input);
+    const allowedProviders = await resolveAllowedProviders(input);
+    const fallbackOrder = typeof options.fallback === "function" ? await options.fallback(input) : options.fallback;
+    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) && passesBudgetFilters(selectedProvider) && (!healthOptions || !isSuppressed(selectedProvider)) ? selectedProvider : candidateRankedProviders[0] ?? firstProvider;
+    const seen = new Set;
+    const order = [];
+    const candidates = strategy === "ordered" ? candidateRankedProviders : [
+      preferred,
+      ...candidateRankedProviders,
+      ...providerIds.filter((provider) => !healthOptions || !isSuppressed(provider))
+    ];
+    for (const provider of candidates) {
+      if (!provider || seen.has(provider) || !allowedProviders.has(provider) || !options.providers[provider]) {
+        continue;
+      }
+      seen.add(provider);
+      order.push(provider);
+    }
+    return {
+      order,
+      selectedProvider: preferred
+    };
+  };
+  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);
+      if (!selectedProvider || order.length === 0) {
+        throw new Error("Voice provider router has no available providers.");
+      }
+      let lastError;
+      for (const [index, provider] of order.entries()) {
+        const model = options.providers[provider];
+        if (!model) {
+          continue;
+        }
+        const startedAt = Date.now();
+        try {
+          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,
+            selectedProvider,
+            status: provider === selectedProvider ? "success" : "fallback"
+          }, input);
+          return output;
+        } catch (error) {
+          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",
+            timedOut
+          }, input);
+          if (!hasNextProvider || !shouldFallback) {
+            throw error;
+          }
+        }
+      }
+      throw lastError ?? new Error("Voice provider router did not run a provider.");
+    }
+  };
+};
+var messageToOpenAIInput = (message) => {
+  if (message.role === "tool") {
+    return [
+      {
+        call_id: message.toolCallId ?? message.name ?? crypto.randomUUID(),
+        output: message.content,
+        type: "function_call_output"
+      }
+    ];
+  }
+  const toolCalls = getMessageToolCalls(message);
+  if (message.role === "assistant" && toolCalls.length) {
+    return toolCalls.map((toolCall) => ({
+      arguments: JSON.stringify(toolCall.args),
+      call_id: toolCall.id ?? crypto.randomUUID(),
+      name: toolCall.name,
+      type: "function_call"
+    }));
+  }
+  return [
+    {
+      content: message.content,
+      role: message.role === "system" ? "developer" : message.role
+    }
+  ];
+};
+var messagesToOpenAIInput = (messages) => messages.flatMap(messageToOpenAIInput);
+var messageToAnthropicMessage = (message) => {
+  if (message.role === "system") {
+    return;
+  }
+  if (message.role === "tool") {
+    if (!message.toolCallId) {
+      return {
+        content: `Tool result from ${message.name ?? "tool"}: ${message.content}`,
+        role: "user"
+      };
+    }
+    return {
+      content: [
+        {
+          content: message.content,
+          tool_use_id: message.toolCallId,
+          type: "tool_result"
+        }
+      ],
+      role: "user"
+    };
+  }
+  const toolCalls = getMessageToolCalls(message);
+  if (message.role === "assistant" && toolCalls.length) {
+    return {
+      content: [
+        ...message.content ? [
+          {
+            text: message.content,
+            type: "text"
+          }
+        ] : [],
+        ...toolCalls.map((toolCall) => ({
+          id: toolCall.id ?? crypto.randomUUID(),
+          input: toolCall.args,
+          name: toolCall.name,
+          type: "tool_use"
+        }))
+      ],
+      role: "assistant"
+    };
+  }
+  return {
+    content: message.content,
+    role: message.role
+  };
+};
+var toGeminiSchema = (schema) => {
+  const next = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === "additionalProperties") {
+      continue;
+    }
+    if (key === "type" && typeof value === "string") {
+      next[key] = value.toUpperCase();
+      continue;
+    }
+    if (Array.isArray(value)) {
+      next[key] = value.map((item) => item && typeof item === "object" ? toGeminiSchema(item) : item);
+      continue;
+    }
+    if (value && typeof value === "object") {
+      next[key] = toGeminiSchema(value);
+      continue;
+    }
+    next[key] = value;
+  }
+  return next;
+};
+var messageToGeminiContent = (message) => {
+  if (message.role === "system") {
+    return;
+  }
+  if (message.role === "tool") {
+    return {
+      parts: [
+        {
+          functionResponse: {
+            id: message.toolCallId,
+            name: message.name ?? "tool",
+            response: {
+              result: parseJSONValue(message.content)
+            }
+          }
+        }
+      ],
+      role: "user"
+    };
+  }
+  const toolCalls = getMessageToolCalls(message);
+  if (message.role === "assistant" && toolCalls.length) {
+    return {
+      parts: [
+        ...message.content ? [
+          {
+            text: message.content
+          }
+        ] : [],
+        ...toolCalls.map((toolCall) => ({
+          functionCall: {
+            args: toolCall.args,
+            id: toolCall.id,
+            name: toolCall.name
+          }
+        }))
+      ],
+      role: "model"
+    };
+  }
+  return {
+    parts: [
+      {
+        text: message.content
+      }
+    ],
+    role: message.role === "assistant" ? "model" : "user"
+  };
+};
+var extractText = (response) => {
+  if (typeof response.output_text === "string") {
+    return response.output_text;
+  }
+  const output = Array.isArray(response.output) ? response.output : [];
+  for (const item of output) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const record = item;
+    const content = Array.isArray(record.content) ? record.content : [];
+    for (const contentItem of content) {
+      if (!contentItem || typeof contentItem !== "object") {
+        continue;
+      }
+      const contentRecord = contentItem;
+      if (typeof contentRecord.text === "string") {
+        return contentRecord.text;
+      }
+    }
+  }
+  return "";
+};
+var extractToolCalls = (response) => {
+  const output = Array.isArray(response.output) ? response.output : [];
+  const toolCalls = [];
+  for (const item of output) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const record = item;
+    if (record.type !== "function_call" || typeof record.name !== "string") {
+      continue;
+    }
+    const args = typeof record.arguments === "string" ? parseJSON(record.arguments) : {};
+    toolCalls.push({
+      args,
+      id: typeof record.call_id === "string" ? record.call_id : typeof record.id === "string" ? record.id : undefined,
+      name: record.name
+    });
+  }
+  return toolCalls;
+};
+var createOpenAIVoiceAssistantModel = (options) => {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const baseUrl = options.baseUrl ?? "https://api.openai.com/v1";
+  const model = options.model ?? "gpt-4.1-mini";
+  return {
+    generate: async (input) => {
+      const response = await fetchImpl(`${baseUrl.replace(/\/$/, "")}/responses`, {
+        body: JSON.stringify({
+          input: messagesToOpenAIInput(input.messages),
+          instructions: [
+            input.system,
+            "Return a JSON object with assistantText, complete, transfer, escalate, voicemail, noAnswer, and result when you are not calling tools."
+          ].filter(Boolean).join(`
+
+`),
+          max_output_tokens: options.maxOutputTokens,
+          model,
+          temperature: options.temperature,
+          text: {
+            format: {
+              name: "voice_route_result",
+              schema: OUTPUT_SCHEMA,
+              strict: false,
+              type: "json_schema"
+            }
+          },
+          tool_choice: input.tools.length ? "auto" : "none",
+          tools: input.tools.map((tool) => ({
+            description: tool.description,
+            name: tool.name,
+            parameters: tool.parameters ?? {
+              additionalProperties: true,
+              type: "object"
+            },
+            strict: false,
+            type: "function"
+          }))
+        }),
+        headers: {
+          authorization: `Bearer ${options.apiKey}`,
+          "content-type": "application/json"
+        },
+        method: "POST"
+      });
+      if (!response.ok) {
+        throw createHTTPError("OpenAI", response);
+      }
+      const body = await response.json();
+      if (body.usage && typeof body.usage === "object") {
+        await options.onUsage?.(body.usage);
+      }
+      const toolCalls = extractToolCalls(body);
+      if (toolCalls.length) {
+        return {
+          toolCalls
+        };
+      }
+      return normalizeRouteOutput(parseJSON(extractText(body)));
+    }
+  };
+};
+var extractAnthropicText = (response) => {
+  const content = Array.isArray(response.content) ? response.content : [];
+  return content.map((item) => item && typeof item === "object" && item.type === "text" && typeof item.text === "string" ? item.text : "").filter(Boolean).join(`
+`);
+};
+var extractAnthropicToolCalls = (response) => {
+  const content = Array.isArray(response.content) ? response.content : [];
+  const toolCalls = [];
+  for (const item of content) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const record = item;
+    if (record.type !== "tool_use" || typeof record.name !== "string") {
+      continue;
+    }
+    toolCalls.push({
+      args: record.input && typeof record.input === "object" ? record.input : {},
+      id: typeof record.id === "string" ? record.id : undefined,
+      name: record.name
+    });
+  }
+  return toolCalls;
+};
+var createAnthropicVoiceAssistantModel = (options) => {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const baseUrl = options.baseUrl ?? "https://api.anthropic.com/v1";
+  const model = options.model ?? "claude-sonnet-4-5";
+  return {
+    generate: async (input) => {
+      const response = await fetchImpl(`${baseUrl.replace(/\/$/, "")}/messages`, {
+        body: JSON.stringify({
+          max_tokens: options.maxOutputTokens ?? 1024,
+          messages: input.messages.map(messageToAnthropicMessage).filter(Boolean),
+          model,
+          system: [input.system, ROUTE_RESULT_INSTRUCTION].filter(Boolean).join(`
+
+`),
+          temperature: options.temperature,
+          tool_choice: input.tools.length ? { type: "auto" } : { type: "none" },
+          tools: input.tools.map((tool) => ({
+            description: tool.description,
+            input_schema: tool.parameters ?? {
+              additionalProperties: true,
+              type: "object"
+            },
+            name: tool.name
+          }))
+        }),
+        headers: {
+          "anthropic-version": options.version ?? "2023-06-01",
+          "content-type": "application/json",
+          "x-api-key": options.apiKey
+        },
+        method: "POST"
+      });
+      if (!response.ok) {
+        throw createHTTPError("Anthropic", response);
+      }
+      const body = await response.json();
+      if (body.usage && typeof body.usage === "object") {
+        await options.onUsage?.(body.usage);
+      }
+      const toolCalls = extractAnthropicToolCalls(body);
+      if (toolCalls.length) {
+        return {
+          assistantText: extractAnthropicText(body) || undefined,
+          toolCalls
+        };
+      }
+      return normalizeRouteOutput(parseJSON(extractAnthropicText(body)));
+    }
+  };
+};
+var extractGeminiCandidateParts = (response) => {
+  const candidates = Array.isArray(response.candidates) ? response.candidates : [];
+  const first = candidates[0];
+  if (!first || typeof first !== "object") {
+    return [];
+  }
+  const content = first.content;
+  if (!content || typeof content !== "object") {
+    return [];
+  }
+  const parts = content.parts;
+  return Array.isArray(parts) ? parts : [];
+};
+var extractGeminiText = (response) => extractGeminiCandidateParts(response).map((part) => part && typeof part === "object" && typeof part.text === "string" ? part.text : "").filter(Boolean).join(`
+`);
+var extractGeminiToolCalls = (response) => {
+  const toolCalls = [];
+  for (const part of extractGeminiCandidateParts(response)) {
+    if (!part || typeof part !== "object") {
+      continue;
+    }
+    const functionCall = part.functionCall;
+    if (!functionCall || typeof functionCall !== "object") {
+      continue;
+    }
+    const record = functionCall;
+    if (typeof record.name !== "string") {
+      continue;
+    }
+    toolCalls.push({
+      args: record.args && typeof record.args === "object" ? record.args : {},
+      id: typeof record.id === "string" ? record.id : undefined,
+      name: record.name
+    });
+  }
+  return toolCalls;
+};
+var createGeminiVoiceAssistantModel = (options) => {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const baseUrl = options.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta";
+  const model = options.model ?? "gemini-2.5-flash";
+  const maxRetries = Math.max(0, options.maxRetries ?? 2);
+  return {
+    generate: async (input) => {
+      const endpoint = `${baseUrl.replace(/\/$/, "")}/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(options.apiKey)}`;
+      let response;
+      for (let attempt = 0;attempt <= maxRetries; attempt += 1) {
+        response = await fetchImpl(endpoint, {
+          body: JSON.stringify({
+            contents: input.messages.map(messageToGeminiContent).filter(Boolean),
+            generationConfig: {
+              maxOutputTokens: options.maxOutputTokens,
+              ...input.tools.length ? {} : {
+                responseMimeType: "application/json",
+                responseSchema: toGeminiSchema(OUTPUT_SCHEMA)
+              },
+              temperature: options.temperature
+            },
+            systemInstruction: {
+              parts: [
+                {
+                  text: [input.system, ROUTE_RESULT_INSTRUCTION].filter(Boolean).join(`
+
+`)
+                }
+              ]
+            },
+            tools: input.tools.length ? [
+              {
+                functionDeclarations: input.tools.map((tool) => ({
+                  description: tool.description,
+                  name: tool.name,
+                  parameters: toGeminiSchema(tool.parameters ?? {
+                    additionalProperties: true,
+                    type: "object"
+                  })
+                }))
+              }
+            ] : undefined
+          }),
+          headers: {
+            "content-type": "application/json"
+          },
+          method: "POST"
+        });
+        if (response.ok || response.status !== 429 && response.status < 500 || attempt === maxRetries) {
+          break;
+        }
+        const retryAfter = Number(response.headers.get("retry-after"));
+        await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt);
+      }
+      if (!response) {
+        throw new Error("Gemini voice assistant model failed: no response");
+      }
+      if (!response.ok) {
+        throw createHTTPError("Gemini", response);
+      }
+      const body = await response.json();
+      if (body.usageMetadata && typeof body.usageMetadata === "object") {
+        await options.onUsage?.(body.usageMetadata);
+      }
+      const toolCalls = extractGeminiToolCalls(body);
+      if (toolCalls.length) {
+        return {
+          assistantText: extractGeminiText(body) || undefined,
+          toolCalls
+        };
+      }
+      return normalizeRouteOutput(parseJSON(extractGeminiText(body)));
+    }
+  };
+};
+
 // src/store.ts
 var createId = () => crypto.randomUUID();
 var createVoiceSessionRecord = (id, scenarioId) => ({
@@ -3508,6 +4548,118 @@ var toVoiceSessionSummary = (session) => ({
   turnCount: session.turns.length
 });
 
+// src/testing/providerSimulator.ts
+var getContextQuery = (context) => context.query;
+var titleCaseProvider = (provider) => provider.split(/[-_\s]+/).filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join(" ");
+var resolveRequestedProvider = (context, providers) => {
+  const provider = getContextQuery(context).provider;
+  return providers.includes(provider) ? provider : providers[0];
+};
+var createVoiceProviderFailureSimulator = (options) => {
+  if (options.providers.length === 0) {
+    throw new Error("At least one provider is required.");
+  }
+  const providerModels = Object.fromEntries(options.providers.map((provider) => [
+    provider,
+    {
+      generate: async (input) => {
+        const query = getContextQuery(input.context);
+        if (provider === query.simulateFailureProvider) {
+          const label = options.providerLabel?.(provider) ?? titleCaseProvider(provider);
+          throw new Error(`${label} voice assistant model failed: HTTP 429`);
+        }
+        if (options.response) {
+          return options.response({
+            ...input,
+            mode: query.recoverProvider === provider ? "recovery" : "failure",
+            provider
+          });
+        }
+        return {
+          assistantText: `Simulated ${provider} provider recovered.`
+        };
+      }
+    }
+  ]));
+  const router = createVoiceProviderRouter({
+    allowProviders: async (input) => {
+      const recoverProvider = getContextQuery(input.context).recoverProvider;
+      if (recoverProvider) {
+        return [recoverProvider];
+      }
+      if (typeof options.allowProviders === "function") {
+        return options.allowProviders(input);
+      }
+      return options.allowProviders ?? options.providers;
+    },
+    fallback: async (input) => {
+      const selectedProvider = resolveRequestedProvider(input.context, options.providers);
+      if (typeof options.fallback === "function") {
+        return options.fallback(selectedProvider, input);
+      }
+      return options.fallback ?? options.providers.filter((provider) => provider !== selectedProvider);
+    },
+    fallbackMode: "provider-error",
+    isProviderError: options.isProviderError,
+    isRateLimitError: options.isRateLimitError,
+    onProviderEvent: options.onProviderEvent,
+    policy: "prefer-selected",
+    providerHealth: options.providerHealth ?? {
+      cooldownMs: 30000,
+      failureThreshold: 1,
+      rateLimitCooldownMs: 120000
+    },
+    providers: providerModels,
+    selectProvider: ({ context }) => resolveRequestedProvider(context, options.providers)
+  });
+  const run = async (provider, mode) => {
+    const now = Date.now();
+    const session = createVoiceSessionRecord(`provider-sim-${now}`, "provider-simulation");
+    const turn = {
+      committedAt: now,
+      id: `provider-sim-turn-${now}`,
+      text: mode === "failure" ? `Simulate ${provider} provider failure.` : `Simulate ${provider} provider recovery.`,
+      transcripts: []
+    };
+    const context = {
+      query: {
+        provider,
+        ...mode === "recovery" ? { recoverProvider: provider } : {},
+        ...mode === "failure" ? { simulateFailureProvider: provider } : {}
+      }
+    };
+    const result = await router.generate({
+      agentId: "provider-simulator",
+      context,
+      messages: [
+        {
+          content: turn.text,
+          role: "user"
+        }
+      ],
+      session,
+      system: "Simulate provider routing without calling external APIs.",
+      tools: [],
+      turn
+    });
+    return {
+      mode,
+      provider,
+      replayHref: options.replayHref === false ? undefined : typeof options.replayHref === "function" ? options.replayHref({
+        provider,
+        sessionId: session.id,
+        turnId: turn.id
+      }) : `${options.replayHref ?? "/api/voice-sessions"}/${encodeURIComponent(session.id)}/replay/htmx`,
+      result,
+      sessionId: session.id,
+      status: "simulated",
+      turnId: turn.id
+    };
+  };
+  return {
+    run
+  };
+};
 // src/memoryStore.ts
 var createVoiceMemoryStore = () => {
   const sessions = new Map;
@@ -3533,6 +4685,289 @@ var createVoiceMemoryStore = () => {
 // src/session.ts
 import { Buffer } 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 = () => {};
 var createNoopLogger = () => ({
@@ -3725,6 +5160,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 = {
@@ -3825,6 +5261,64 @@ var createVoiceSession = (options) => {
       });
     }
   };
+  const sendCallLifecycle = async (session) => {
+    const event = getLatestCallLifecycleEvent(session);
+    if (!event) {
+      return;
+    }
+    await send({
+      event,
+      sessionId: options.id,
+      type: "call_lifecycle"
+    });
+  };
+  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);
@@ -4015,6 +5509,7 @@ var createVoiceSession = (options) => {
     await appendTrace({
       payload: {
         disposition,
+        metadata: input.metadata,
         reason: input.reason,
         target: input.target,
         type: "end"
@@ -4022,6 +5517,7 @@ var createVoiceSession = (options) => {
       session,
       type: "call.lifecycle"
     });
+    await sendCallLifecycle(session);
     await send({
       sessionId: options.id,
       type: "complete"
@@ -4101,6 +5597,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,
@@ -4126,6 +5631,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,
@@ -4148,6 +5661,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,
@@ -4169,6 +5689,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,
@@ -4955,6 +6482,7 @@ var createVoiceSession = (options) => {
         session,
         type: "call.lifecycle"
       });
+      await sendCallLifecycle(session);
     }
     await send({
       sessionId: options.id,
@@ -5545,7 +7073,7 @@ var createVoiceCallReviewFromLiveTelephonyReport = (report, options = {}) => {
     }
   };
 };
-var toErrorMessage = (error) => {
+var toErrorMessage2 = (error) => {
   if (typeof error === "string" && error.trim().length > 0) {
     return error;
   }
@@ -5632,7 +7160,7 @@ var createVoiceCallReviewRecorder = (options = {}) => {
       };
     },
     recordError: (error) => {
-      const message = toErrorMessage(error);
+      const message = toErrorMessage2(error);
       errors.push(message);
       push("turn", "error", {
         reason: message
@@ -6341,7 +7869,7 @@ var runVoiceSessionBenchmarkSeries = async (input) => {
 import { Buffer as Buffer2 } from "buffer";
 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 normalizeOnTurn = (handler) => {
   if (handler.length > 1) {
     const directHandler = handler;
@@ -6537,8 +8065,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);
@@ -7208,6 +8736,8 @@ export {
   getDefaultVoiceDuplexBenchmarkScenarios,
   getDefaultTTSBenchmarkFixtures,
   evaluateSTTBenchmarkAcceptance,
+  createVoiceProviderFailureSimulator,
+  createVoiceIOProviderFailureSimulator,
   createVoiceCallReviewRecorder,
   createVoiceCallReviewFromLiveTelephonyReport,
   createTelephonyVoiceTestFixtures,