realtime-voice-agents 2.1.0 → 2.2.0

package/README.md

@@ -104,6 +104,26 @@ geminiLive({ model: 'gemini-2.5-flash-native-audio-preview-12-2025', voice: 'Aoe
 
 One `SessionOptions` surface configures all three; where a provider can't honor a knob, the fallback is documented and pinned by the parity test suite.
 
+## Provider fallbacks
+
+One bad API key, an exhausted quota, or a provider outage should not send your calls to dead air. Give the bridge backup providers and it tries them in order while the call is being established:
+
+```ts
+const bridge = new TwilioRealtimeBridge({
+  agent,
+  provider: openaiRealtime(), // primary
+  fallbacks: [xaiRealtime(), geminiLive()], // tried in order if it fails to come up
+});
+```
+
+- **Covers the real failure modes.** A missing API key (the factories defer their credential check to call time precisely so the chain can absorb it), an expired/revoked key (HTTP 401), exhausted credits/quota (403/429), a provider internal error (5xx or a dropped socket), and a hung endpoint (connect timeout) all walk the chain — anything that keeps a provider from coming up.
+- **Connect-time only.** A dead provider is dropped and the next one is tried immediately — no backoff between attempts. Once a provider answers, the call stays with it: mid-call reconnects reuse the same provider (per the `session.reconnect` policy), and a mid-call death past that budget fails the call rather than switching voices mid-conversation.
+- **Observable.** Each advance emits `provider.fallback` (`{ from, to, error }`) on the session — count these to alarm on a degraded primary.
+- **Voices don't cross vendors.** Configure the voice per factory (`openaiRealtime({ voice: 'marin' })`, `xaiRealtime({ voice: 'eve' })`) rather than on the `Agent` — an OpenAI voice name would fail the xAI/Gemini connect and the chain would skip past a healthy provider.
+- **Latency.** Each dead provider costs up to its `connectTimeoutMs` (default 10s) before the next is tried — set a tighter one on the primary if its endpoint tends to hang rather than refuse. A [pre-synthesized greeting](#pre-synthesized-greeting-15s-to-first-word) bursts onto the line before any handshake, so the caller hears a voice while the chain walks.
+
+Testing it: `FakeOpenAIServer.start({ refuseConnections: true })` gives you a provider that is "down", and `{ rejectUpgrade: { status: 401, body: 'invalid_api_key' } }` one that rejects like a real auth/quota failure (both flippable at runtime to script recoveries) — see `src/bridge/fallback.test.ts` for ready-made scenarios.
+
 ## Tools: Zod schemas + execution strategies
 
 ```ts
@@ -252,7 +272,7 @@ Bundled presets (all synthesized, license-free, seamless loops): `elevator-jazz`
 
 ## Events (session)
 
-`call.started/ended/failed` · `provider.connected/reconnecting/reconnected/closed` · `agent.speech.started/ended` (generation) · **`playback.started/finished/interrupted`** (what the caller heard, mark-confirmed) · `user.speech.started/ended` · `transcript.user/agent` · `tool.started/completed/failed` · `tool.approval.required` · `agent.handoff` · `interruption` / `interruption.blocked` · `vad.suggestion` / `vad.adjusted` (noise-adaptive VAD) · `background_audio.started/stopped` · `dtmf` · `usage.updated` · `error`.
+`call.started/ended/failed` · `provider.connected/fallback/reconnecting/reconnected/closed` · `agent.speech.started/ended` (generation) · **`playback.started/finished/interrupted`** (what the caller heard, mark-confirmed) · `user.speech.started/ended` · `transcript.user/agent` · `tool.started/completed/failed` · `tool.approval.required` · `agent.handoff` · `interruption` / `interruption.blocked` · `vad.suggestion` / `vad.adjusted` (noise-adaptive VAD) · `background_audio.started/stopped` · `dtmf` · `usage.updated` · `error`.
 
 ```ts
 bridge.on('session.started', (session) => {
@@ -296,7 +316,7 @@ Outbound calls: the greeting waits for a human — feed your status callback int
 `realtime-voice-agents/testing` ships the harness this package is tested with:
 
 - **`FakeTwilioMediaStream`** — a scripted caller with an exact playout simulation: marks echo only after the media before them "plays"; `clear` discards buffered audio and echoes pending marks, like real Twilio.
-- **`FakeOpenAIServer`** — a real-WebSocket GA-protocol server you script (`sendAudioResponse`, `sendToolCall`, `sendSpeechStarted`, drops).
+- **`FakeOpenAIServer`** — a real-WebSocket GA-protocol server you script (`sendAudioResponse`, `sendToolCall`, `sendSpeechStarted`, drops, `refuseConnections` for down-provider/fallback scenarios).
 - **`FakeGeminiLive`** — a scripted `@google/genai` seam for the Gemini provider.
 
 ```ts

package/dist/gemini.cjs

@@ -373,12 +373,14 @@ const GEMINI_VOICES = [
 	"Kore",
 	"Puck"
 ];
-/** Create a Gemini Live provider factory for the bridge. */
+/**
+* Create a Gemini Live provider factory for the bridge. Credentials are
+* resolved per call (see `openaiRealtime` — missing credentials fail that
+* call's connect so a fallback chain can absorb it, instead of crashing
+* config construction).
+*/
 function geminiLive(options = {}) {
-	const apiKey = require_env.resolveApiKey(options.apiKey, GEMINI_KEY_ENV_VARS);
-	if (!apiKey && !options.vertex && !options.connector) throw new Error(`geminiLive: credentials missing (pass apiKey, set one of ${GEMINI_KEY_ENV_VARS.join("/")}, or configure vertex)`);
 	const config = {
-		apiKey,
 		vertex: options.vertex,
 		model: options.model ?? "gemini-2.5-flash-native-audio-preview-12-2025",
 		voice: options.voice ?? "Aoede",
@@ -391,7 +393,14 @@ function geminiLive(options = {}) {
 		connectTimeoutMs: options.connectTimeoutMs,
 		connector: options.connector
 	};
-	return ({ logger }) => new GeminiLiveProvider(config, logger);
+	return ({ logger }) => {
+		const apiKey = require_env.resolveApiKey(options.apiKey, GEMINI_KEY_ENV_VARS);
+		if (!apiKey && !options.vertex && !options.connector) throw new Error(`geminiLive: credentials missing (pass apiKey, set one of ${GEMINI_KEY_ENV_VARS.join("/")}, or configure vertex)`);
+		return new GeminiLiveProvider({
+			...config,
+			apiKey
+		}, logger);
+	};
 }
 //#endregion
 exports.GEMINI_DEFAULT_MODEL = GEMINI_DEFAULT_MODEL;

package/dist/gemini.d.cts

@@ -35,7 +35,12 @@ interface GeminiLiveOptions {
   /** Test seam: replaces the @google/genai live connection. */
   connector?: GeminiLiveConnector;
 }
-/** Create a Gemini Live provider factory for the bridge. */
+/**
+ * Create a Gemini Live provider factory for the bridge. Credentials are
+ * resolved per call (see `openaiRealtime` — missing credentials fail that
+ * call's connect so a fallback chain can absorb it, instead of crashing
+ * config construction).
+ */
 declare function geminiLive(options?: GeminiLiveOptions): ProviderFactory;
 //#endregion
 export { GEMINI_DEFAULT_MODEL, GEMINI_DEFAULT_VOICE, GEMINI_KEY_ENV_VARS, GEMINI_VOICES, type GeminiConnectParams, type GeminiLiveConnector, GeminiLiveOptions, GeminiLiveProvider, type GeminiLiveProviderConfig, type GeminiLiveSessionLike, geminiLive };

package/dist/gemini.d.mts

@@ -35,7 +35,12 @@ interface GeminiLiveOptions {
   /** Test seam: replaces the @google/genai live connection. */
   connector?: GeminiLiveConnector;
 }
-/** Create a Gemini Live provider factory for the bridge. */
+/**
+ * Create a Gemini Live provider factory for the bridge. Credentials are
+ * resolved per call (see `openaiRealtime` — missing credentials fail that
+ * call's connect so a fallback chain can absorb it, instead of crashing
+ * config construction).
+ */
 declare function geminiLive(options?: GeminiLiveOptions): ProviderFactory;
 //#endregion
 export { GEMINI_DEFAULT_MODEL, GEMINI_DEFAULT_VOICE, GEMINI_KEY_ENV_VARS, GEMINI_VOICES, type GeminiConnectParams, type GeminiLiveConnector, GeminiLiveOptions, GeminiLiveProvider, type GeminiLiveProviderConfig, type GeminiLiveSessionLike, geminiLive };

package/dist/gemini.mjs

@@ -372,12 +372,14 @@ const GEMINI_VOICES = [
 	"Kore",
 	"Puck"
 ];
-/** Create a Gemini Live provider factory for the bridge. */
+/**
+* Create a Gemini Live provider factory for the bridge. Credentials are
+* resolved per call (see `openaiRealtime` — missing credentials fail that
+* call's connect so a fallback chain can absorb it, instead of crashing
+* config construction).
+*/
 function geminiLive(options = {}) {
-	const apiKey = resolveApiKey(options.apiKey, GEMINI_KEY_ENV_VARS);
-	if (!apiKey && !options.vertex && !options.connector) throw new Error(`geminiLive: credentials missing (pass apiKey, set one of ${GEMINI_KEY_ENV_VARS.join("/")}, or configure vertex)`);
 	const config = {
-		apiKey,
 		vertex: options.vertex,
 		model: options.model ?? "gemini-2.5-flash-native-audio-preview-12-2025",
 		voice: options.voice ?? "Aoede",
@@ -390,7 +392,14 @@ function geminiLive(options = {}) {
 		connectTimeoutMs: options.connectTimeoutMs,
 		connector: options.connector
 	};
-	return ({ logger }) => new GeminiLiveProvider(config, logger);
+	return ({ logger }) => {
+		const apiKey = resolveApiKey(options.apiKey, GEMINI_KEY_ENV_VARS);
+		if (!apiKey && !options.vertex && !options.connector) throw new Error(`geminiLive: credentials missing (pass apiKey, set one of ${GEMINI_KEY_ENV_VARS.join("/")}, or configure vertex)`);
+		return new GeminiLiveProvider({
+			...config,
+			apiKey
+		}, logger);
+	};
 }
 //#endregion
 export { GEMINI_DEFAULT_MODEL, GEMINI_DEFAULT_VOICE, GEMINI_KEY_ENV_VARS, GEMINI_VOICES, GeminiLiveProvider, geminiLive };

package/dist/index.cjs

@@ -907,6 +907,8 @@ var CallSession = class extends require_events.TypedEmitter {
 	runningTools = /* @__PURE__ */ new Map();
 	timers = /* @__PURE__ */ new Set();
 	provider = null;
+	/** Primary + fallbacks, in try-order. Only walked while connecting. */
+	providerChain;
 	activeAgentValue;
 	generating = false;
 	currentResponseId = null;
@@ -965,6 +967,7 @@ var CallSession = class extends require_events.TypedEmitter {
 		this.callSid = deps.start.start.callSid;
 		this.streamSid = deps.start.start.streamSid ?? deps.start.streamSid;
 		this.log = require_BaseRealtimeProvider.childLogger(deps.logger, { callSid: this.callSid });
+		this.providerChain = [deps.providerFactory, ...deps.fallbacks ?? []];
 		this.activeAgentValue = deps.agent;
 		this.context = new SessionContext(deps.options.context);
 		this.interruptions = new InterruptionController(deps.options.interruptions);
@@ -1003,17 +1006,7 @@ var CallSession = class extends require_events.TypedEmitter {
 	/** Connect the provider and activate the call. Called by the bridge. */
 	async begin() {
 		this.playPreGreeting();
-		try {
-			this.provider = this.deps.providerFactory({
-				logger: this.log,
-				callSid: this.callSid
-			});
-			this.wireProvider(this.provider);
-			await this.provider.connect(this.buildProviderInit());
-		} catch (error) {
-			this.fail(error instanceof Error ? error : new Error(String(error)), "provider-failed");
-			return;
-		}
+		if (!await this.connectInitialProvider()) return;
 		if (this.stateValue !== "connecting") return;
 		this.stateValue = "active";
 		this.emit("provider.connected");
@@ -1039,6 +1032,55 @@ var CallSession = class extends require_events.TypedEmitter {
 		this.saveSnapshot();
 		this.maybeGreet();
 	}
+	/**
+	* Walk primary + fallbacks until one connects. A provider that fails to
+	* come up is detached BEFORE the chain advances, so a half-open socket's
+	* late events can never reach the session once the next provider owns the
+	* call. Connect-time only by design: once a provider has answered, the
+	* call stays with it. Returns false after failing the call (chain
+	* exhausted) or when the call was torn down while connecting.
+	*/
+	async connectInitialProvider() {
+		let lastFrom = "provider";
+		let lastError = null;
+		for (const factory of this.providerChain) {
+			let provider;
+			try {
+				provider = factory({
+					logger: this.log,
+					callSid: this.callSid
+				});
+			} catch (error) {
+				lastError = toError(error);
+				this.log.warn("provider factory threw — trying the next fallback", { error: String(lastError) });
+				continue;
+			}
+			if (lastError) this.emit("provider.fallback", {
+				from: lastFrom,
+				to: provider.name,
+				error: lastError
+			});
+			this.provider = provider;
+			this.wireProvider(provider);
+			try {
+				await provider.connect(this.buildProviderInit());
+				return true;
+			} catch (error) {
+				provider.removeAllListeners();
+				provider.close().catch(() => {});
+				this.provider = null;
+				if (this.stateValue !== "connecting") return false;
+				lastFrom = provider.name;
+				lastError = toError(error);
+				this.log.warn("provider failed to connect", {
+					provider: provider.name,
+					error: String(lastError)
+				});
+			}
+		}
+		this.fail(lastError ?? /* @__PURE__ */ new Error("provider connect failed"), "provider-failed");
+		return false;
+	}
 	/** The outbound leg was answered (host's Twilio status callback). */
 	notifyAnswered() {
 		if (this.answered) return;
@@ -2159,6 +2201,9 @@ var CallSession = class extends require_events.TypedEmitter {
 const PREGREETING_MARK = "pre:greeting";
 /** 400ms per frame — matches production burst-write implementations. */
 const PREGREETING_CHUNK_BYTES = 3200;
+function toError(value) {
+	return value instanceof Error ? value : new Error(String(value));
+}
 function safeJsonStringify(value) {
 	try {
 		return JSON.stringify(value) ?? "null";
@@ -2293,6 +2338,7 @@ var TwilioRealtimeBridge = class extends require_events.TypedEmitter {
 				transport,
 				start,
 				providerFactory: this.config.provider,
+				fallbacks: this.config.fallbacks,
 				agent,
 				options,
 				store: this.store,

package/dist/index.d.cts

@@ -535,6 +535,19 @@ interface BridgeConfig {
   /** The (root) agent, or a resolver for multi-tenant routing per call. */
   agent: Agent | ((start: TwilioStartEvent) => Agent | Promise<Agent>);
   provider: ProviderFactory;
+  /**
+   * Backup providers tried in order when `provider` fails to come up at call
+   * start (bad key, exhausted quota, outage, connect timeout). Each attempt
+   * emits `provider.fallback`; the call fails only when every fallback is
+   * exhausted. Connect-time only: once a provider answers, the call stays
+   * with it (mid-call reconnects keep using the same provider).
+   *
+   * ```ts
+   * provider: openaiRealtime(),
+   * fallbacks: [xaiRealtime(), geminiLive()],
+   * ```
+   */
+  fallbacks?: ProviderFactory[];
   session?: Partial<SessionOptions> | ((start: TwilioStartEvent) => Partial<SessionOptions> | Promise<Partial<SessionOptions>>);
   /** Twilio REST credentials — enables clean hangup, transfer, SMS/WhatsApp. */
   twilio?: TwilioRestOptions;
@@ -593,6 +606,19 @@ interface ApprovalRequestInfo {
 type VadSuggestionInfo = VadAdjustment & {
   willAutoApply: boolean;
 };
+/**
+ * While ESTABLISHING the call, a provider failed to come up and the session
+ * is trying the next factory in the fallback chain. Fires only before the
+ * call is active — once a provider has connected, the call stays with it.
+ */
+interface ProviderFallbackInfo {
+  /** Name of the provider whose connect failed. */
+  from: string;
+  /** Name of the provider being tried instead. */
+  to: string;
+  /** The connect error that triggered the fallback. */
+  error: Error;
+}
 interface SessionEventMap {
   'call.started': (info: CallStartedInfo) => void;
   'call.ended': (info: {
@@ -611,6 +637,8 @@ interface SessionEventMap {
     code?: number;
     reason?: string;
   }) => void;
+  /** Connect-time fallback: trying the next provider in the configured chain. */
+  'provider.fallback': (info: ProviderFallbackInfo) => void;
   /** Generation-side: the model started/finished producing a response. */
   'agent.speech.started': (info: {
     responseId: string;
@@ -683,6 +711,8 @@ interface CallSessionDeps {
   transport: TwilioMediaTransport;
   start: TwilioStartEvent;
   providerFactory: ProviderFactory;
+  /** Backup factories tried in order when `providerFactory` fails to connect. */
+  fallbacks?: readonly ProviderFactory[];
   agent: Agent;
   options: SessionOptions;
   store: SessionStore;
@@ -713,6 +743,8 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private readonly runningTools;
   private readonly timers;
   private provider;
+  /** Primary + fallbacks, in try-order. Only walked while connecting. */
+  private readonly providerChain;
   private activeAgentValue;
   private generating;
   private currentResponseId;
@@ -772,6 +804,15 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   get transcript(): readonly TranscriptEntry[];
   /** Connect the provider and activate the call. Called by the bridge. */
   begin(): Promise<void>;
+  /**
+   * Walk primary + fallbacks until one connects. A provider that fails to
+   * come up is detached BEFORE the chain advances, so a half-open socket's
+   * late events can never reach the session once the next provider owns the
+   * call. Connect-time only by design: once a provider has answered, the
+   * call stays with it. Returns false after failing the call (chain
+   * exhausted) or when the call was torn down while connecting.
+   */
+  private connectInitialProvider;
   /** The outbound leg was answered (host's Twilio status callback). */
   notifyAnswered(): void;
   sendText(text: string, options?: {
@@ -1085,4 +1126,4 @@ declare class PlaybackTracker {
   private maybeForget;
 }
 //#endregion
-export { Agent, type AgentDefinition, type ApprovalRequestInfo, type BackgroundAudioOptions, type BackgroundAudioPreset, type BackgroundAudioSpec, BaseRealtimeProvider, type BridgeConfig, type BridgeEventMap, type BuiltinToolsConfig, type CallEndReason, CallSession, type CallSessionFacade, type CallSnapshot, type CallStartedInfo, type CallState, type CaptureGreetingOptions, type CapturedGreeting, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, type DeafnessOptions, type FinishCallToolOptions, type GreetingOptions, type HandoffDirective, type HangupOptions, type IdleOptions, InMemorySessionStore, type InferSchema, type InterruptionBlockCause, InterruptionController, type InterruptionDecision, type InterruptionRateLimit, type InterruptionSettings, type Logger, type MarkEchoResult, NoiseAdaptiveVadController, type NoiseAdaptiveVadOptions, PlaybackTracker, type ProviderAudioDelta, type ProviderCapabilities, type ProviderCloseInfo, type ProviderEvents, type ProviderFactory, type ProviderFactoryContext, type ProviderSessionInit, type ProviderToolCall, type ProviderToolSchema, type ProviderUsage, type ReconnectPolicy, type SendTextOptions, type SendToolResultOptions, SessionContext, type SessionEventMap, type SessionOptions, type SessionStore, type SessionUpdateOptions, type Tool, type ToolCallInfo, type ToolContext, type ToolDecoration, type ToolDefinition, type ToolMiddleware, type ToolRunInfo, type ToolStrategy, type TranscriptEntry, type TransferCallToolOptions, TwilioRealtimeBridge, type TwilioRestOptions, type TwilioStartEvent, type UsageInfo, type VadAdjustment, type VadConfig, type VadNoiseMetrics, type VadSuggestionInfo, type VadTuningProfile, type WebSocketLike, type ZodSchemaLike, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };
+export { Agent, type AgentDefinition, type ApprovalRequestInfo, type BackgroundAudioOptions, type BackgroundAudioPreset, type BackgroundAudioSpec, BaseRealtimeProvider, type BridgeConfig, type BridgeEventMap, type BuiltinToolsConfig, type CallEndReason, CallSession, type CallSessionFacade, type CallSnapshot, type CallStartedInfo, type CallState, type CaptureGreetingOptions, type CapturedGreeting, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, type DeafnessOptions, type FinishCallToolOptions, type GreetingOptions, type HandoffDirective, type HangupOptions, type IdleOptions, InMemorySessionStore, type InferSchema, type InterruptionBlockCause, InterruptionController, type InterruptionDecision, type InterruptionRateLimit, type InterruptionSettings, type Logger, type MarkEchoResult, NoiseAdaptiveVadController, type NoiseAdaptiveVadOptions, PlaybackTracker, type ProviderAudioDelta, type ProviderCapabilities, type ProviderCloseInfo, type ProviderEvents, type ProviderFactory, type ProviderFactoryContext, type ProviderFallbackInfo, type ProviderSessionInit, type ProviderToolCall, type ProviderToolSchema, type ProviderUsage, type ReconnectPolicy, type SendTextOptions, type SendToolResultOptions, SessionContext, type SessionEventMap, type SessionOptions, type SessionStore, type SessionUpdateOptions, type Tool, type ToolCallInfo, type ToolContext, type ToolDecoration, type ToolDefinition, type ToolMiddleware, type ToolRunInfo, type ToolStrategy, type TranscriptEntry, type TransferCallToolOptions, TwilioRealtimeBridge, type TwilioRestOptions, type TwilioStartEvent, type UsageInfo, type VadAdjustment, type VadConfig, type VadNoiseMetrics, type VadSuggestionInfo, type VadTuningProfile, type WebSocketLike, type ZodSchemaLike, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };

package/dist/index.d.mts

@@ -535,6 +535,19 @@ interface BridgeConfig {
   /** The (root) agent, or a resolver for multi-tenant routing per call. */
   agent: Agent | ((start: TwilioStartEvent) => Agent | Promise<Agent>);
   provider: ProviderFactory;
+  /**
+   * Backup providers tried in order when `provider` fails to come up at call
+   * start (bad key, exhausted quota, outage, connect timeout). Each attempt
+   * emits `provider.fallback`; the call fails only when every fallback is
+   * exhausted. Connect-time only: once a provider answers, the call stays
+   * with it (mid-call reconnects keep using the same provider).
+   *
+   * ```ts
+   * provider: openaiRealtime(),
+   * fallbacks: [xaiRealtime(), geminiLive()],
+   * ```
+   */
+  fallbacks?: ProviderFactory[];
   session?: Partial<SessionOptions> | ((start: TwilioStartEvent) => Partial<SessionOptions> | Promise<Partial<SessionOptions>>);
   /** Twilio REST credentials — enables clean hangup, transfer, SMS/WhatsApp. */
   twilio?: TwilioRestOptions;
@@ -593,6 +606,19 @@ interface ApprovalRequestInfo {
 type VadSuggestionInfo = VadAdjustment & {
   willAutoApply: boolean;
 };
+/**
+ * While ESTABLISHING the call, a provider failed to come up and the session
+ * is trying the next factory in the fallback chain. Fires only before the
+ * call is active — once a provider has connected, the call stays with it.
+ */
+interface ProviderFallbackInfo {
+  /** Name of the provider whose connect failed. */
+  from: string;
+  /** Name of the provider being tried instead. */
+  to: string;
+  /** The connect error that triggered the fallback. */
+  error: Error;
+}
 interface SessionEventMap {
   'call.started': (info: CallStartedInfo) => void;
   'call.ended': (info: {
@@ -611,6 +637,8 @@ interface SessionEventMap {
     code?: number;
     reason?: string;
   }) => void;
+  /** Connect-time fallback: trying the next provider in the configured chain. */
+  'provider.fallback': (info: ProviderFallbackInfo) => void;
   /** Generation-side: the model started/finished producing a response. */
   'agent.speech.started': (info: {
     responseId: string;
@@ -683,6 +711,8 @@ interface CallSessionDeps {
   transport: TwilioMediaTransport;
   start: TwilioStartEvent;
   providerFactory: ProviderFactory;
+  /** Backup factories tried in order when `providerFactory` fails to connect. */
+  fallbacks?: readonly ProviderFactory[];
   agent: Agent;
   options: SessionOptions;
   store: SessionStore;
@@ -713,6 +743,8 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private readonly runningTools;
   private readonly timers;
   private provider;
+  /** Primary + fallbacks, in try-order. Only walked while connecting. */
+  private readonly providerChain;
   private activeAgentValue;
   private generating;
   private currentResponseId;
@@ -772,6 +804,15 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   get transcript(): readonly TranscriptEntry[];
   /** Connect the provider and activate the call. Called by the bridge. */
   begin(): Promise<void>;
+  /**
+   * Walk primary + fallbacks until one connects. A provider that fails to
+   * come up is detached BEFORE the chain advances, so a half-open socket's
+   * late events can never reach the session once the next provider owns the
+   * call. Connect-time only by design: once a provider has answered, the
+   * call stays with it. Returns false after failing the call (chain
+   * exhausted) or when the call was torn down while connecting.
+   */
+  private connectInitialProvider;
   /** The outbound leg was answered (host's Twilio status callback). */
   notifyAnswered(): void;
   sendText(text: string, options?: {
@@ -1085,4 +1126,4 @@ declare class PlaybackTracker {
   private maybeForget;
 }
 //#endregion
-export { Agent, type AgentDefinition, type ApprovalRequestInfo, type BackgroundAudioOptions, type BackgroundAudioPreset, type BackgroundAudioSpec, BaseRealtimeProvider, type BridgeConfig, type BridgeEventMap, type BuiltinToolsConfig, type CallEndReason, CallSession, type CallSessionFacade, type CallSnapshot, type CallStartedInfo, type CallState, type CaptureGreetingOptions, type CapturedGreeting, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, type DeafnessOptions, type FinishCallToolOptions, type GreetingOptions, type HandoffDirective, type HangupOptions, type IdleOptions, InMemorySessionStore, type InferSchema, type InterruptionBlockCause, InterruptionController, type InterruptionDecision, type InterruptionRateLimit, type InterruptionSettings, type Logger, type MarkEchoResult, NoiseAdaptiveVadController, type NoiseAdaptiveVadOptions, PlaybackTracker, type ProviderAudioDelta, type ProviderCapabilities, type ProviderCloseInfo, type ProviderEvents, type ProviderFactory, type ProviderFactoryContext, type ProviderSessionInit, type ProviderToolCall, type ProviderToolSchema, type ProviderUsage, type ReconnectPolicy, type SendTextOptions, type SendToolResultOptions, SessionContext, type SessionEventMap, type SessionOptions, type SessionStore, type SessionUpdateOptions, type Tool, type ToolCallInfo, type ToolContext, type ToolDecoration, type ToolDefinition, type ToolMiddleware, type ToolRunInfo, type ToolStrategy, type TranscriptEntry, type TransferCallToolOptions, TwilioRealtimeBridge, type TwilioRestOptions, type TwilioStartEvent, type UsageInfo, type VadAdjustment, type VadConfig, type VadNoiseMetrics, type VadSuggestionInfo, type VadTuningProfile, type WebSocketLike, type ZodSchemaLike, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };
+export { Agent, type AgentDefinition, type ApprovalRequestInfo, type BackgroundAudioOptions, type BackgroundAudioPreset, type BackgroundAudioSpec, BaseRealtimeProvider, type BridgeConfig, type BridgeEventMap, type BuiltinToolsConfig, type CallEndReason, CallSession, type CallSessionFacade, type CallSnapshot, type CallStartedInfo, type CallState, type CaptureGreetingOptions, type CapturedGreeting, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, type DeafnessOptions, type FinishCallToolOptions, type GreetingOptions, type HandoffDirective, type HangupOptions, type IdleOptions, InMemorySessionStore, type InferSchema, type InterruptionBlockCause, InterruptionController, type InterruptionDecision, type InterruptionRateLimit, type InterruptionSettings, type Logger, type MarkEchoResult, NoiseAdaptiveVadController, type NoiseAdaptiveVadOptions, PlaybackTracker, type ProviderAudioDelta, type ProviderCapabilities, type ProviderCloseInfo, type ProviderEvents, type ProviderFactory, type ProviderFactoryContext, type ProviderFallbackInfo, type ProviderSessionInit, type ProviderToolCall, type ProviderToolSchema, type ProviderUsage, type ReconnectPolicy, type SendTextOptions, type SendToolResultOptions, SessionContext, type SessionEventMap, type SessionOptions, type SessionStore, type SessionUpdateOptions, type Tool, type ToolCallInfo, type ToolContext, type ToolDecoration, type ToolDefinition, type ToolMiddleware, type ToolRunInfo, type ToolStrategy, type TranscriptEntry, type TransferCallToolOptions, TwilioRealtimeBridge, type TwilioRestOptions, type TwilioStartEvent, type UsageInfo, type VadAdjustment, type VadConfig, type VadNoiseMetrics, type VadSuggestionInfo, type VadTuningProfile, type WebSocketLike, type ZodSchemaLike, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };

package/dist/index.mjs

@@ -903,6 +903,8 @@ var CallSession = class extends TypedEmitter {
 	runningTools = /* @__PURE__ */ new Map();
 	timers = /* @__PURE__ */ new Set();
 	provider = null;
+	/** Primary + fallbacks, in try-order. Only walked while connecting. */
+	providerChain;
 	activeAgentValue;
 	generating = false;
 	currentResponseId = null;
@@ -961,6 +963,7 @@ var CallSession = class extends TypedEmitter {
 		this.callSid = deps.start.start.callSid;
 		this.streamSid = deps.start.start.streamSid ?? deps.start.streamSid;
 		this.log = childLogger(deps.logger, { callSid: this.callSid });
+		this.providerChain = [deps.providerFactory, ...deps.fallbacks ?? []];
 		this.activeAgentValue = deps.agent;
 		this.context = new SessionContext(deps.options.context);
 		this.interruptions = new InterruptionController(deps.options.interruptions);
@@ -999,17 +1002,7 @@ var CallSession = class extends TypedEmitter {
 	/** Connect the provider and activate the call. Called by the bridge. */
 	async begin() {
 		this.playPreGreeting();
-		try {
-			this.provider = this.deps.providerFactory({
-				logger: this.log,
-				callSid: this.callSid
-			});
-			this.wireProvider(this.provider);
-			await this.provider.connect(this.buildProviderInit());
-		} catch (error) {
-			this.fail(error instanceof Error ? error : new Error(String(error)), "provider-failed");
-			return;
-		}
+		if (!await this.connectInitialProvider()) return;
 		if (this.stateValue !== "connecting") return;
 		this.stateValue = "active";
 		this.emit("provider.connected");
@@ -1035,6 +1028,55 @@ var CallSession = class extends TypedEmitter {
 		this.saveSnapshot();
 		this.maybeGreet();
 	}
+	/**
+	* Walk primary + fallbacks until one connects. A provider that fails to
+	* come up is detached BEFORE the chain advances, so a half-open socket's
+	* late events can never reach the session once the next provider owns the
+	* call. Connect-time only by design: once a provider has answered, the
+	* call stays with it. Returns false after failing the call (chain
+	* exhausted) or when the call was torn down while connecting.
+	*/
+	async connectInitialProvider() {
+		let lastFrom = "provider";
+		let lastError = null;
+		for (const factory of this.providerChain) {
+			let provider;
+			try {
+				provider = factory({
+					logger: this.log,
+					callSid: this.callSid
+				});
+			} catch (error) {
+				lastError = toError(error);
+				this.log.warn("provider factory threw — trying the next fallback", { error: String(lastError) });
+				continue;
+			}
+			if (lastError) this.emit("provider.fallback", {
+				from: lastFrom,
+				to: provider.name,
+				error: lastError
+			});
+			this.provider = provider;
+			this.wireProvider(provider);
+			try {
+				await provider.connect(this.buildProviderInit());
+				return true;
+			} catch (error) {
+				provider.removeAllListeners();
+				provider.close().catch(() => {});
+				this.provider = null;
+				if (this.stateValue !== "connecting") return false;
+				lastFrom = provider.name;
+				lastError = toError(error);
+				this.log.warn("provider failed to connect", {
+					provider: provider.name,
+					error: String(lastError)
+				});
+			}
+		}
+		this.fail(lastError ?? /* @__PURE__ */ new Error("provider connect failed"), "provider-failed");
+		return false;
+	}
 	/** The outbound leg was answered (host's Twilio status callback). */
 	notifyAnswered() {
 		if (this.answered) return;
@@ -2155,6 +2197,9 @@ var CallSession = class extends TypedEmitter {
 const PREGREETING_MARK = "pre:greeting";
 /** 400ms per frame — matches production burst-write implementations. */
 const PREGREETING_CHUNK_BYTES = 3200;
+function toError(value) {
+	return value instanceof Error ? value : new Error(String(value));
+}
 function safeJsonStringify(value) {
 	try {
 		return JSON.stringify(value) ?? "null";
@@ -2289,6 +2334,7 @@ var TwilioRealtimeBridge = class extends TypedEmitter {
 				transport,
 				start,
 				providerFactory: this.config.provider,
+				fallbacks: this.config.fallbacks,
 				agent,
 				options,
 				store: this.store,

package/dist/openai.cjs

@@ -30,12 +30,16 @@ const OPENAI_REALTIME_VOICES = [
 	"shimmer",
 	"verse"
 ];
-/** Create a provider factory for the bridge (`provider: openaiRealtime({...})`). */
+/**
+* Create a provider factory for the bridge (`provider: openaiRealtime({...})`).
+*
+* Credentials are resolved per call, when the factory runs — not while the
+* config is being built. A missing key therefore fails THAT provider's
+* connect (with a clear error) instead of crashing config construction, so a
+* fallback chain (`BridgeConfig.fallbacks`) can absorb it.
+*/
 function openaiRealtime(options = {}) {
-	const apiKey = require_env.resolveApiKey(options.apiKey, OPENAI_KEY_ENV_VARS);
-	if (!apiKey) throw new Error(`openaiRealtime: apiKey missing (pass apiKey or set one of ${OPENAI_KEY_ENV_VARS.join("/")})`);
 	const config = {
-		apiKey,
 		model: options.model ?? "gpt-realtime",
 		voice: options.voice ?? "marin",
 		baseUrl: options.baseUrl,
@@ -52,7 +56,12 @@ function openaiRealtime(options = {}) {
 		} }
 	};
 	return ({ logger }) => {
-		return new require_OpenAICompatibleProvider.OpenAICompatibleProvider(config, logger);
+		const apiKey = require_env.resolveApiKey(options.apiKey, OPENAI_KEY_ENV_VARS);
+		if (!apiKey) throw new Error(`openaiRealtime: apiKey missing (pass apiKey or set one of ${OPENAI_KEY_ENV_VARS.join("/")})`);
+		return new require_OpenAICompatibleProvider.OpenAICompatibleProvider({
+			...config,
+			apiKey
+		}, logger);
 	};
 }
 //#endregion

package/dist/openai.d.cts

@@ -136,7 +136,14 @@ interface OpenAIRealtimeOptions {
   sessionOptions?: Record<string, unknown>;
   connectTimeoutMs?: number;
 }
-/** Create a provider factory for the bridge (`provider: openaiRealtime({...})`). */
+/**
+ * Create a provider factory for the bridge (`provider: openaiRealtime({...})`).
+ *
+ * Credentials are resolved per call, when the factory runs — not while the
+ * config is being built. A missing key therefore fails THAT provider's
+ * connect (with a clear error) instead of crashing config construction, so a
+ * fallback chain (`BridgeConfig.fallbacks`) can absorb it.
+ */
 declare function openaiRealtime(options?: OpenAIRealtimeOptions): ProviderFactory;
 //#endregion
 export { OPENAI_DEFAULT_MODEL, OPENAI_DEFAULT_VOICE, OPENAI_KEY_ENV_VARS, OPENAI_REALTIME_VOICES, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIRealtimeOptions, OpenAIRealtimeVoice, buildSessionUpdate, buildTurnDetection, openaiRealtime };

package/dist/openai.d.mts

@@ -136,7 +136,14 @@ interface OpenAIRealtimeOptions {
   sessionOptions?: Record<string, unknown>;
   connectTimeoutMs?: number;
 }
-/** Create a provider factory for the bridge (`provider: openaiRealtime({...})`). */
+/**
+ * Create a provider factory for the bridge (`provider: openaiRealtime({...})`).
+ *
+ * Credentials are resolved per call, when the factory runs — not while the
+ * config is being built. A missing key therefore fails THAT provider's
+ * connect (with a clear error) instead of crashing config construction, so a
+ * fallback chain (`BridgeConfig.fallbacks`) can absorb it.
+ */
 declare function openaiRealtime(options?: OpenAIRealtimeOptions): ProviderFactory;
 //#endregion
 export { OPENAI_DEFAULT_MODEL, OPENAI_DEFAULT_VOICE, OPENAI_KEY_ENV_VARS, OPENAI_REALTIME_VOICES, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIRealtimeOptions, OpenAIRealtimeVoice, buildSessionUpdate, buildTurnDetection, openaiRealtime };

package/dist/openai.mjs

@@ -29,12 +29,16 @@ const OPENAI_REALTIME_VOICES = [
 	"shimmer",
 	"verse"
 ];
-/** Create a provider factory for the bridge (`provider: openaiRealtime({...})`). */
+/**
+* Create a provider factory for the bridge (`provider: openaiRealtime({...})`).
+*
+* Credentials are resolved per call, when the factory runs — not while the
+* config is being built. A missing key therefore fails THAT provider's
+* connect (with a clear error) instead of crashing config construction, so a
+* fallback chain (`BridgeConfig.fallbacks`) can absorb it.
+*/
 function openaiRealtime(options = {}) {
-	const apiKey = resolveApiKey(options.apiKey, OPENAI_KEY_ENV_VARS);
-	if (!apiKey) throw new Error(`openaiRealtime: apiKey missing (pass apiKey or set one of ${OPENAI_KEY_ENV_VARS.join("/")})`);
 	const config = {
-		apiKey,
 		model: options.model ?? "gpt-realtime",
 		voice: options.voice ?? "marin",
 		baseUrl: options.baseUrl,
@@ -51,7 +55,12 @@ function openaiRealtime(options = {}) {
 		} }
 	};
 	return ({ logger }) => {
-		return new OpenAICompatibleProvider(config, logger);
+		const apiKey = resolveApiKey(options.apiKey, OPENAI_KEY_ENV_VARS);
+		if (!apiKey) throw new Error(`openaiRealtime: apiKey missing (pass apiKey or set one of ${OPENAI_KEY_ENV_VARS.join("/")})`);
+		return new OpenAICompatibleProvider({
+			...config,
+			apiKey
+		}, logger);
 	};
 }
 //#endregion

package/dist/testing.cjs

@@ -358,6 +358,14 @@ var FakeOpenAIConnection = class {
 };
 var FakeOpenAIServer = class FakeOpenAIServer {
 	connections = [];
+	/** Flip at runtime to start/stop refusing sessions (see the option's docs). */
+	refuseConnections;
+	/** Sockets closed by `refuseConnections` before a session was created. */
+	refusedConnections = 0;
+	/** Set at runtime to start rejecting HTTP upgrades; null re-accepts. */
+	rejectUpgrade;
+	/** Upgrades rejected by `rejectUpgrade`. */
+	rejectedUpgrades = 0;
 	wss;
 	options;
 	url;
@@ -365,7 +373,14 @@ var FakeOpenAIServer = class FakeOpenAIServer {
 		this.wss = wss;
 		this.url = url;
 		this.options = options;
+		this.refuseConnections = options.refuseConnections ?? false;
+		this.rejectUpgrade = options.rejectUpgrade ?? null;
 		wss.on("connection", (socket, request) => {
+			if (this.refuseConnections) {
+				this.refusedConnections++;
+				socket.close(1011, "fake server refusing sessions");
+				return;
+			}
 			const connection = new FakeOpenAIConnection(this, socket, request.headers);
 			this.connections.push(connection);
 			socket.on("message", (raw) => {
@@ -388,9 +403,19 @@ var FakeOpenAIServer = class FakeOpenAIServer {
 		});
 	}
 	static async start(options = {}) {
+		const holder = {};
 		const wss = new ws.WebSocketServer({
 			port: 0,
-			host: "127.0.0.1"
+			host: "127.0.0.1",
+			verifyClient: (_info, done) => {
+				const reject = holder.server?.rejectUpgrade;
+				if (reject) {
+					holder.server.rejectedUpgrades++;
+					done(false, reject.status, reject.body ?? "rejected by fake server");
+					return;
+				}
+				done(true);
+			}
 		});
 		await new Promise((resolve, reject) => {
 			wss.once("listening", resolve);
@@ -398,7 +423,9 @@ var FakeOpenAIServer = class FakeOpenAIServer {
 		});
 		const address = wss.address();
 		if (typeof address === "string" || address === null) throw new Error("no server address");
-		return new FakeOpenAIServer(wss, `ws://127.0.0.1:${address.port}`, options);
+		const server = new FakeOpenAIServer(wss, `ws://127.0.0.1:${address.port}`, options);
+		holder.server = server;
+		return server;
 	}
 	get latest() {
 		const connection = this.connections[this.connections.length - 1];

package/dist/testing.d.cts

@@ -76,6 +76,25 @@ declare class FakeTwilioMediaStream implements WebSocketLike {
 interface FakeOpenAIServerOptions {
   /** Auto-ack session.update with session.updated. Default true. */
   autoAckSessionUpdate?: boolean;
+  /**
+   * Refuse sessions: close each new socket immediately, before
+   * session.created — a provider that is down or rejecting (exercises
+   * connect failures and provider fallback chains). Mutable at runtime via
+   * the server's `refuseConnections` field; refused sockets are counted in
+   * `refusedConnections` and never appear in `connections`.
+   */
+  refuseConnections?: boolean;
+  /**
+   * Reject the HTTP upgrade itself with this status + body — how real
+   * providers surface an invalid/expired key (401), exhausted credits
+   * (403/429), or an internal error (5xx). Mutable at runtime via the
+   * server's `rejectUpgrade` field (null re-accepts); rejections are counted
+   * in `rejectedUpgrades` and never appear in `connections`.
+   */
+  rejectUpgrade?: {
+    status: number;
+    body?: string;
+  };
 }
 interface FakeAudioResponseOptions {
   responseId?: string;
@@ -119,6 +138,17 @@ declare class FakeOpenAIConnection {
 }
 declare class FakeOpenAIServer {
   readonly connections: FakeOpenAIConnection[];
+  /** Flip at runtime to start/stop refusing sessions (see the option's docs). */
+  refuseConnections: boolean;
+  /** Sockets closed by `refuseConnections` before a session was created. */
+  refusedConnections: number;
+  /** Set at runtime to start rejecting HTTP upgrades; null re-accepts. */
+  rejectUpgrade: {
+    status: number;
+    body?: string;
+  } | null;
+  /** Upgrades rejected by `rejectUpgrade`. */
+  rejectedUpgrades: number;
   private readonly wss;
   private readonly options;
   readonly url: string;

package/dist/testing.d.mts

@@ -76,6 +76,25 @@ declare class FakeTwilioMediaStream implements WebSocketLike {
 interface FakeOpenAIServerOptions {
   /** Auto-ack session.update with session.updated. Default true. */
   autoAckSessionUpdate?: boolean;
+  /**
+   * Refuse sessions: close each new socket immediately, before
+   * session.created — a provider that is down or rejecting (exercises
+   * connect failures and provider fallback chains). Mutable at runtime via
+   * the server's `refuseConnections` field; refused sockets are counted in
+   * `refusedConnections` and never appear in `connections`.
+   */
+  refuseConnections?: boolean;
+  /**
+   * Reject the HTTP upgrade itself with this status + body — how real
+   * providers surface an invalid/expired key (401), exhausted credits
+   * (403/429), or an internal error (5xx). Mutable at runtime via the
+   * server's `rejectUpgrade` field (null re-accepts); rejections are counted
+   * in `rejectedUpgrades` and never appear in `connections`.
+   */
+  rejectUpgrade?: {
+    status: number;
+    body?: string;
+  };
 }
 interface FakeAudioResponseOptions {
   responseId?: string;
@@ -119,6 +138,17 @@ declare class FakeOpenAIConnection {
 }
 declare class FakeOpenAIServer {
   readonly connections: FakeOpenAIConnection[];
+  /** Flip at runtime to start/stop refusing sessions (see the option's docs). */
+  refuseConnections: boolean;
+  /** Sockets closed by `refuseConnections` before a session was created. */
+  refusedConnections: number;
+  /** Set at runtime to start rejecting HTTP upgrades; null re-accepts. */
+  rejectUpgrade: {
+    status: number;
+    body?: string;
+  } | null;
+  /** Upgrades rejected by `rejectUpgrade`. */
+  rejectedUpgrades: number;
   private readonly wss;
   private readonly options;
   readonly url: string;

package/dist/testing.mjs

@@ -357,6 +357,14 @@ var FakeOpenAIConnection = class {
 };
 var FakeOpenAIServer = class FakeOpenAIServer {
 	connections = [];
+	/** Flip at runtime to start/stop refusing sessions (see the option's docs). */
+	refuseConnections;
+	/** Sockets closed by `refuseConnections` before a session was created. */
+	refusedConnections = 0;
+	/** Set at runtime to start rejecting HTTP upgrades; null re-accepts. */
+	rejectUpgrade;
+	/** Upgrades rejected by `rejectUpgrade`. */
+	rejectedUpgrades = 0;
 	wss;
 	options;
 	url;
@@ -364,7 +372,14 @@ var FakeOpenAIServer = class FakeOpenAIServer {
 		this.wss = wss;
 		this.url = url;
 		this.options = options;
+		this.refuseConnections = options.refuseConnections ?? false;
+		this.rejectUpgrade = options.rejectUpgrade ?? null;
 		wss.on("connection", (socket, request) => {
+			if (this.refuseConnections) {
+				this.refusedConnections++;
+				socket.close(1011, "fake server refusing sessions");
+				return;
+			}
 			const connection = new FakeOpenAIConnection(this, socket, request.headers);
 			this.connections.push(connection);
 			socket.on("message", (raw) => {
@@ -387,9 +402,19 @@ var FakeOpenAIServer = class FakeOpenAIServer {
 		});
 	}
 	static async start(options = {}) {
+		const holder = {};
 		const wss = new WebSocketServer({
 			port: 0,
-			host: "127.0.0.1"
+			host: "127.0.0.1",
+			verifyClient: (_info, done) => {
+				const reject = holder.server?.rejectUpgrade;
+				if (reject) {
+					holder.server.rejectedUpgrades++;
+					done(false, reject.status, reject.body ?? "rejected by fake server");
+					return;
+				}
+				done(true);
+			}
 		});
 		await new Promise((resolve, reject) => {
 			wss.once("listening", resolve);
@@ -397,7 +422,9 @@ var FakeOpenAIServer = class FakeOpenAIServer {
 		});
 		const address = wss.address();
 		if (typeof address === "string" || address === null) throw new Error("no server address");
-		return new FakeOpenAIServer(wss, `ws://127.0.0.1:${address.port}`, options);
+		const server = new FakeOpenAIServer(wss, `ws://127.0.0.1:${address.port}`, options);
+		holder.server = server;
+		return server;
 	}
 	get latest() {
 		const connection = this.connections[this.connections.length - 1];

package/dist/xai.cjs

@@ -59,13 +59,15 @@ function buildXaiSessionUpdate(init, config = {}) {
 		session
 	};
 }
-/** Create an xAI Grok Voice provider factory for the bridge. */
+/**
+* Create an xAI Grok Voice provider factory for the bridge. Credentials are
+* resolved per call (see `openaiRealtime` — a missing key fails that call's
+* connect so a fallback chain can absorb it, instead of crashing config
+* construction).
+*/
 function xaiRealtime(options = {}) {
-	const apiKey = require_env.resolveApiKey(options.apiKey, XAI_KEY_ENV_VARS);
-	if (!apiKey) throw new Error(`xaiRealtime: apiKey missing (pass apiKey or set one of ${XAI_KEY_ENV_VARS.join("/")})`);
 	const transcription = options.transcription === false ? false : options.transcription ? { language: options.transcription.languageHint } : void 0;
 	const config = {
-		apiKey,
 		model: options.model ?? "grok-voice-latest",
 		voice: options.voice ?? "eve",
 		baseUrl: options.baseUrl ?? "wss://api.x.ai/v1/realtime",
@@ -86,7 +88,14 @@ function xaiRealtime(options = {}) {
 			}
 		}
 	};
-	return ({ logger }) => new require_OpenAICompatibleProvider.OpenAICompatibleProvider(config, logger);
+	return ({ logger }) => {
+		const apiKey = require_env.resolveApiKey(options.apiKey, XAI_KEY_ENV_VARS);
+		if (!apiKey) throw new Error(`xaiRealtime: apiKey missing (pass apiKey or set one of ${XAI_KEY_ENV_VARS.join("/")})`);
+		return new require_OpenAICompatibleProvider.OpenAICompatibleProvider({
+			...config,
+			apiKey
+		}, logger);
+	};
 }
 //#endregion
 exports.XAI_BASE_URL = XAI_BASE_URL;

package/dist/xai.d.cts

@@ -29,7 +29,12 @@ declare function buildXaiSessionUpdate(init: ProviderSessionInit, config?: {
   defaultVoice?: string;
   extraSessionOptions?: Record<string, unknown>;
 }): Record<string, unknown>;
-/** Create an xAI Grok Voice provider factory for the bridge. */
+/**
+ * Create an xAI Grok Voice provider factory for the bridge. Credentials are
+ * resolved per call (see `openaiRealtime` — a missing key fails that call's
+ * connect so a fallback chain can absorb it, instead of crashing config
+ * construction).
+ */
 declare function xaiRealtime(options?: XaiRealtimeOptions): ProviderFactory;
 //#endregion
 export { XAI_BASE_URL, XAI_DEFAULT_MODEL, XAI_DEFAULT_VOICE, XAI_KEY_ENV_VARS, XaiRealtimeOptions, buildXaiSessionUpdate, xaiRealtime };

package/dist/xai.d.mts

@@ -29,7 +29,12 @@ declare function buildXaiSessionUpdate(init: ProviderSessionInit, config?: {
   defaultVoice?: string;
   extraSessionOptions?: Record<string, unknown>;
 }): Record<string, unknown>;
-/** Create an xAI Grok Voice provider factory for the bridge. */
+/**
+ * Create an xAI Grok Voice provider factory for the bridge. Credentials are
+ * resolved per call (see `openaiRealtime` — a missing key fails that call's
+ * connect so a fallback chain can absorb it, instead of crashing config
+ * construction).
+ */
 declare function xaiRealtime(options?: XaiRealtimeOptions): ProviderFactory;
 //#endregion
 export { XAI_BASE_URL, XAI_DEFAULT_MODEL, XAI_DEFAULT_VOICE, XAI_KEY_ENV_VARS, XaiRealtimeOptions, buildXaiSessionUpdate, xaiRealtime };

package/dist/xai.mjs

@@ -58,13 +58,15 @@ function buildXaiSessionUpdate(init, config = {}) {
 		session
 	};
 }
-/** Create an xAI Grok Voice provider factory for the bridge. */
+/**
+* Create an xAI Grok Voice provider factory for the bridge. Credentials are
+* resolved per call (see `openaiRealtime` — a missing key fails that call's
+* connect so a fallback chain can absorb it, instead of crashing config
+* construction).
+*/
 function xaiRealtime(options = {}) {
-	const apiKey = resolveApiKey(options.apiKey, XAI_KEY_ENV_VARS);
-	if (!apiKey) throw new Error(`xaiRealtime: apiKey missing (pass apiKey or set one of ${XAI_KEY_ENV_VARS.join("/")})`);
 	const transcription = options.transcription === false ? false : options.transcription ? { language: options.transcription.languageHint } : void 0;
 	const config = {
-		apiKey,
 		model: options.model ?? "grok-voice-latest",
 		voice: options.voice ?? "eve",
 		baseUrl: options.baseUrl ?? "wss://api.x.ai/v1/realtime",
@@ -85,7 +87,14 @@ function xaiRealtime(options = {}) {
 			}
 		}
 	};
-	return ({ logger }) => new OpenAICompatibleProvider(config, logger);
+	return ({ logger }) => {
+		const apiKey = resolveApiKey(options.apiKey, XAI_KEY_ENV_VARS);
+		if (!apiKey) throw new Error(`xaiRealtime: apiKey missing (pass apiKey or set one of ${XAI_KEY_ENV_VARS.join("/")})`);
+		return new OpenAICompatibleProvider({
+			...config,
+			apiKey
+		}, logger);
+	};
 }
 //#endregion
 export { XAI_BASE_URL, XAI_DEFAULT_MODEL, XAI_DEFAULT_VOICE, XAI_KEY_ENV_VARS, buildXaiSessionUpdate, xaiRealtime };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-voice-agents",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Provider-agnostic bridge between Twilio Media Streams and realtime speech-to-speech AI APIs (OpenAI Realtime, xAI Grok Voice, Gemini Live). Multi-agent handoffs, Zod tools with execution strategies, mark-based playback tracking, interruption guards, and hold audio — for Node.js voice agents over the phone.",
   "keywords": [
     "twilio",