realtime-voice-agents 2.1.0 → 2.3.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
@@ -250,9 +270,38 @@ session: { greeting: { mode: 'agent-initiates',
 
 Bundled presets (all synthesized, license-free, seamless loops): `elevator-jazz`, `lofi`, `keyboard-typing`, `thinking-hum`, `ringing` — or `{ custom: bufferOrPath }` with your own 8 kHz μ-law. Drift-corrected 20 ms pacing, refcounted across concurrent tools, ~1 s start delay so fast tools stay silent, fade in/out, 60 s failsafe, and instant preemption when real speech arrives. Manual control: `session.playBackgroundAudio('lofi')` / `stopBackgroundAudio()`.
 
+## Keypad input (DTMF, opt-in)
+
+Callers type an ID, a phone number, a confirmation code — Twilio delivers each key as its own `dtmf` frame, ~1s apart, and a model that sees ten fragments answers "I didn't get that" ten times. `keypad` turns keypresses into one entry: digits buffer, `#` submits, `*` clears, `maxDigits` auto-submits, 4s without a key flushes what's there (so the agent can say "that's only 7 digits — again, please"). Each keypress stops the agent mid-sentence (typing means "I'm answering"), and the entry reaches the model as a **user** turn — `[keypad] I typed on my phone keypad: 0541234567 — 10 digits. Digit by digit: 0 5 4 …` — that triggers the response answering it. A short note appended to the agent instructions tells the model what `[keypad]` messages are.
+
+```ts
+session: {
+  keypad: {},                              // {} = defaults below
+  // maxDigits: 9,                         // auto-submit at N digits (no # needed)
+  // interDigitTimeoutMs: 4000, submitKey: '#', clearKey: '*',
+  // interruptOnKeypress: true,            // false: the agent keeps talking while the caller types
+  // message: (entry) => string | false,   // wording of the injected user turn; false = events only
+  // clearMessage: string | false,         // what the model hears on *; false = nothing
+  // instructions: string | false,         // the appended note; false = your prompt says it
+}
+```
+
+Observe or take over with events and the `session.keypad` handle (`digits`, `clear()`, `submit()`):
+
+```ts
+session.on('keypad.entry', ({ digits, reason }) => { /* reason: 'submit' | 'timeout' | 'maxDigits' */ });
+session.on('keypad.cleared', ({ discarded }) => { /* caller pressed * */ });
+// Raw keypresses still fire per key — AFTER the collector consumed them, so the handle is current:
+session.on('dtmf', ({ digit }) => {
+  if (digit === '0' && session.keypad.digits === '0') { session.keypad.clear(); void session.transferTo(OPERATOR); }
+});
+```
+
+`message: false` keeps the collection and events but injects nothing — validate the entry yourself and `session.sendText(..., { role: 'user', triggerResponse: true })` what the model should hear. Role `user`, not `system`: a trailing system item is skipped by the response it triggers and only lands one response later (field-tested on xAI). Without `keypad` configured nothing changes: raw `dtmf` events only, as before. Letters A–D are ignored; the buffer dies with the call.
+
 ## 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` (raw keypress) · `keypad.entry` / `keypad.cleared` (keypad input) · `usage.updated` · `error`.
 
 ```ts
 bridge.on('session.started', (session) => {
@@ -280,6 +329,7 @@ session: {
   hangup: { markTimeoutMs: 7000 },              // goodbye watchdog
   vad: undefined,                               // normalized VAD, mapped per provider
   noiseAdaptiveVad: undefined,                  // opt-in noise → VAD escalation ({} enables; see its section)
+  keypad: undefined,                            // opt-in DTMF → one user turn per entry ({} enables; see its section)
   toolResultDelivery: 'afterPlayback',          // or 'immediate'
   toolBackgroundAudio: undefined,               // default hold audio for tools
   handoffVoicePolicy: 'keep',                   // or 'reconnect' to switch voices
@@ -296,7 +346,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

@@ -193,6 +193,105 @@ function createHandoffTool(target) {
 	});
 }
 //#endregion
+//#region src/dtmf/KeypadCollector.ts
+const DEFAULT_KEYPAD_OPTIONS = {
+	submitKey: "#",
+	clearKey: "*",
+	interDigitTimeoutMs: 4e3,
+	interruptOnKeypress: true
+};
+/**
+* Appended to the agent instructions when keypad input is enabled. Short and
+* neutral on purpose: what the messages are, not how to run the dialog.
+*/
+const DEFAULT_KEYPAD_INSTRUCTIONS = "Keypad input: the caller may type on their phone keypad instead of speaking. Keypresses arrive as a user message starting with \"[keypad]\" that contains the typed digits — treat it as the caller's answer.";
+/** Default text of the user turn injected for a completed entry. */
+function defaultKeypadMessage(entry) {
+	const { digits } = entry;
+	return `[keypad] I typed on my phone keypad: ${digits} — ${digits.length} digit${digits.length === 1 ? "" : "s"}. Digit by digit: ${[...digits].join(" ")}`;
+}
+/** Default text of the user turn injected when the caller presses the clear key. */
+const DEFAULT_KEYPAD_CLEAR_MESSAGE = "[keypad] I pressed star — I want to start over and retype from the beginning.";
+var KeypadCollector = class {
+	submitKey;
+	clearKey;
+	interDigitTimeoutMs;
+	maxDigits;
+	hooks;
+	buffer = "";
+	timer = null;
+	disposed = false;
+	constructor(options, hooks) {
+		this.submitKey = options.submitKey ?? DEFAULT_KEYPAD_OPTIONS.submitKey;
+		this.clearKey = options.clearKey ?? DEFAULT_KEYPAD_OPTIONS.clearKey;
+		this.interDigitTimeoutMs = options.interDigitTimeoutMs ?? DEFAULT_KEYPAD_OPTIONS.interDigitTimeoutMs;
+		this.maxDigits = options.maxDigits !== void 0 && options.maxDigits > 0 ? options.maxDigits : void 0;
+		this.hooks = hooks;
+	}
+	get digits() {
+		return this.buffer;
+	}
+	/** Feed one keypress (a Twilio `dtmf` frame). Returns what the key meant. */
+	press(key) {
+		if (this.disposed) return "ignored";
+		if (key === this.submitKey) {
+			this.cancelTimer();
+			this.complete("submit");
+			return "submit";
+		}
+		if (key === this.clearKey) {
+			this.cancelTimer();
+			const discarded = this.buffer;
+			this.buffer = "";
+			this.hooks.onClear({ discarded });
+			return "clear";
+		}
+		if (!/^[0-9]$/.test(key)) return "ignored";
+		this.cancelTimer();
+		this.buffer += key;
+		if (this.maxDigits !== void 0 && this.buffer.length >= this.maxDigits) this.complete("maxDigits");
+		else this.armTimer();
+		return "digit";
+	}
+	clear() {
+		this.cancelTimer();
+		this.buffer = "";
+	}
+	submit() {
+		if (this.disposed) return;
+		this.cancelTimer();
+		this.complete("submit");
+	}
+	/** Release the timer; pending digits are dropped (the call is over). */
+	dispose() {
+		this.disposed = true;
+		this.cancelTimer();
+		this.buffer = "";
+	}
+	complete(reason) {
+		if (!this.buffer) return;
+		const digits = this.buffer;
+		this.buffer = "";
+		this.hooks.onEntry({
+			digits,
+			reason
+		});
+	}
+	armTimer() {
+		this.timer = setTimeout(() => {
+			this.timer = null;
+			this.complete("timeout");
+		}, this.interDigitTimeoutMs);
+		this.timer.unref?.();
+	}
+	cancelTimer() {
+		if (this.timer) {
+			clearTimeout(this.timer);
+			this.timer = null;
+		}
+	}
+};
+//#endregion
 //#region src/interruption/InterruptionController.ts
 var InterruptionController = class {
 	settings;
@@ -893,11 +992,17 @@ var CallSession = class extends require_events.TypedEmitter {
 	streamSid;
 	callInfo;
 	context;
+	/**
+	* Keypad (DTMF) input handle: digits buffered so far, `clear()`, `submit()`.
+	* Inert (empty, no-ops) unless the `keypad` session option is configured.
+	*/
+	keypad;
 	stateValue = "connecting";
 	deps;
 	log;
 	tracker = new PlaybackTracker();
 	interruptions;
+	keypadCollector;
 	usageAccumulator = new UsageAccumulator();
 	toolQueue = new ToolResultQueue();
 	transcriptEntries = [];
@@ -907,6 +1012,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,9 +1072,22 @@ 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);
+		this.keypadCollector = deps.options.keypad ? new KeypadCollector(deps.options.keypad, {
+			onEntry: (entry) => this.onKeypadEntry(entry),
+			onClear: (info) => this.onKeypadCleared(info)
+		}) : null;
+		const collector = this.keypadCollector;
+		this.keypad = {
+			get digits() {
+				return collector?.digits ?? "";
+			},
+			clear: () => collector?.clear(),
+			submit: () => collector?.submit()
+		};
 		const params = deps.start.start.customParameters ?? {};
 		this.callInfo = {
 			direction: params.direction === "outbound" ? "outbound" : "inbound",
@@ -1003,17 +1123,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 +1149,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;
@@ -1170,9 +1329,16 @@ var CallSession = class extends require_events.TypedEmitter {
 		}
 		return tools;
 	}
+	/** Agent instructions plus the kit's own notes that must survive handoffs (keypad). */
+	composeInstructions() {
+		const base = this.activeAgentValue.resolveInstructions(this.context);
+		const keypad = this.deps.options.keypad;
+		if (!keypad || keypad.instructions === false) return base;
+		return `${base}\n\n${keypad.instructions ?? "Keypad input: the caller may type on their phone keypad instead of speaking. Keypresses arrive as a user message starting with \"[keypad]\" that contains the typed digits — treat it as the caller's answer."}`;
+	}
 	buildProviderInit() {
 		return {
-			instructions: this.activeAgentValue.resolveInstructions(this.context) + (this.pregreeting ? `\n\nYou already opened the call by saying: "${this.pregreeting.text}". Do not greet again — continue the conversation from there.` : ""),
+			instructions: this.composeInstructions() + (this.pregreeting ? `\n\nYou already opened the call by saying: "${this.pregreeting.text}". Do not greet again — continue the conversation from there.` : ""),
 			voice: this.activeAgentValue.voice,
 			vad: this.vadOverride !== void 0 ? this.vadOverride : this.deps.options.vad,
 			bridgeOwnsInterruptions: true,
@@ -1195,7 +1361,9 @@ var CallSession = class extends require_events.TypedEmitter {
 		transport.on("dtmf", (event) => {
 			this.clearIdleTimer();
 			this.nudgeCount = 0;
-			this.emit("dtmf", { digit: event.dtmf.digit });
+			const digit = event.dtmf.digit;
+			this.handleKeypress(digit);
+			this.emit("dtmf", { digit });
 		});
 		transport.on("stop", () => void this.teardown("caller-hangup"));
 		transport.on("close", () => void this.teardown("caller-hangup"));
@@ -1969,7 +2137,7 @@ var CallSession = class extends require_events.TypedEmitter {
 		if (!(!this.provider.capabilities.sessionUpdate || voiceChanges && !this.provider.capabilities.voiceChangeMidSession && this.deps.options.handoffVoicePolicy === "reconnect")) {
 			if (voiceChanges && !this.provider.capabilities.voiceChangeMidSession) this.log.warn(`agent "${target.id}" declares voice "${target.voice}" but the provider cannot change voice mid-session — keeping the current voice (set handoffVoicePolicy: 'reconnect' to switch)`);
 			await this.provider.updateSession({
-				instructions: this.activeAgentValue.resolveInstructions(this.context),
+				instructions: this.composeInstructions(),
 				tools: this.buildProviderInit().tools,
 				providerOptions: target.providerOptions
 			});
@@ -2045,6 +2213,29 @@ var CallSession = class extends require_events.TypedEmitter {
 		this.transcriptEntries.push(entry);
 		this.emit("transcript.agent", entry);
 	}
+	handleKeypress(key) {
+		if (!this.keypadCollector) return;
+		if (this.deps.options.keypad?.interruptOnKeypress !== false) this.interrupt();
+		this.keypadCollector.press(key);
+	}
+	onKeypadEntry(entry) {
+		this.emit("keypad.entry", entry);
+		const message = this.deps.options.keypad?.message;
+		if (message === false) return;
+		this.provider?.sendText((message ?? defaultKeypadMessage)(entry), {
+			role: "user",
+			triggerResponse: true
+		});
+	}
+	onKeypadCleared(info) {
+		this.emit("keypad.cleared", info);
+		const clearMessage = this.deps.options.keypad?.clearMessage;
+		if (clearMessage === false) return;
+		this.provider?.sendText(clearMessage ?? "[keypad] I pressed star — I want to start over and retype from the beginning.", {
+			role: "user",
+			triggerResponse: true
+		});
+	}
 	/** Armed whenever the agent goes quiet and we're waiting on the caller. */
 	armIdleTimer() {
 		const idle = this.deps.options.idle;
@@ -2104,6 +2295,7 @@ var CallSession = class extends require_events.TypedEmitter {
 		for (const timer of this.timers) clearTimeout(timer);
 		this.timers.clear();
 		this.clearIdleTimer();
+		this.keypadCollector?.dispose();
 		this.bgAudio.stop({ immediate: true });
 		for (const controller of this.runningTools.values()) controller.abort(/* @__PURE__ */ new Error("call ended"));
 		this.runningTools.clear();
@@ -2159,6 +2351,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 +2488,7 @@ var TwilioRealtimeBridge = class extends require_events.TypedEmitter {
 				transport,
 				start,
 				providerFactory: this.config.provider,
+				fallbacks: this.config.fallbacks,
 				agent,
 				options,
 				store: this.store,
@@ -2410,10 +2606,14 @@ async function captureGreetingAudio(options) {
 exports.Agent = Agent;
 exports.BaseRealtimeProvider = require_BaseRealtimeProvider.BaseRealtimeProvider;
 exports.CallSession = CallSession;
+exports.DEFAULT_KEYPAD_CLEAR_MESSAGE = DEFAULT_KEYPAD_CLEAR_MESSAGE;
+exports.DEFAULT_KEYPAD_INSTRUCTIONS = DEFAULT_KEYPAD_INSTRUCTIONS;
+exports.DEFAULT_KEYPAD_OPTIONS = DEFAULT_KEYPAD_OPTIONS;
 exports.DEFAULT_RECONNECT_POLICY = DEFAULT_RECONNECT_POLICY;
 exports.DEFAULT_SESSION_OPTIONS = DEFAULT_SESSION_OPTIONS;
 exports.InMemorySessionStore = require_InMemorySessionStore.InMemorySessionStore;
 exports.InterruptionController = InterruptionController;
+exports.KeypadCollector = KeypadCollector;
 exports.NoiseAdaptiveVadController = NoiseAdaptiveVadController;
 exports.PlaybackTracker = PlaybackTracker;
 exports.SessionContext = SessionContext;
@@ -2427,6 +2627,7 @@ exports.createFinishCallTool = createFinishCallTool;
 exports.createHandoffTool = createHandoffTool;
 exports.createTransferCallTool = createTransferCallTool;
 exports.decorateTool = decorateTool;
+exports.defaultKeypadMessage = defaultKeypadMessage;
 exports.emptyUsage = emptyUsage;
 exports.handoffToolName = handoffToolName;
 exports.isHandoffDirective = isHandoffDirective;