realtime-voice-agents 2.1.0 → 2.3.0

package/dist/index.d.cts

@@ -193,6 +193,124 @@ declare function decorateTool(tool: Tool, middlewares: readonly ToolMiddleware[]
 /** Compose wrapExecute chains around an innermost executor. */
 declare function composeExecution(tool: Tool, input: unknown, ctx: ToolContext, middlewares: readonly ToolMiddleware[], innermost: () => Promise<unknown>): Promise<unknown>;
 //#endregion
+//#region src/dtmf/KeypadCollector.d.ts
+/**
+ * KeypadCollector — turns single DTMF keypresses into complete keypad entries.
+ *
+ * Callers type digits with ~1s pauses between them; the model should hear the
+ * whole number once, not ten fragments. The collector buffers digits and
+ * completes an entry on the submit key (`#`), on `maxDigits`, or after
+ * `interDigitTimeoutMs` of no keypresses (the caller stopped without `#` —
+ * flushing lets the agent react, typically "that's only N digits, please
+ * retype"). The clear key (`*`) discards the buffer so the caller can start
+ * over. Letters A–D and anything exotic are ignored.
+ *
+ * Pure state machine: no session, no transport. `CallSession` feeds it from
+ * the Twilio `dtmf` frame (before emitting the raw `dtmf` event), turns the
+ * hooks into `keypad.entry` / `keypad.cleared` events, and injects the default
+ * user-turn message. Field-tested shape (workshop DTMF agents, Aug 2026).
+ */
+type KeypadEntryReason = 'submit' | 'timeout' | 'maxDigits';
+interface KeypadEntry {
+  /** The digits typed, in order (0–9 only). */
+  digits: string;
+  /** What completed the entry: the submit key, the inter-digit timeout, or `maxDigits`. */
+  reason: KeypadEntryReason;
+}
+interface KeypadOptions {
+  /** Key that submits the current entry immediately. Default `'#'`. */
+  submitKey?: string;
+  /** Key that discards the current entry so the caller can start over. Default `'*'`. */
+  clearKey?: string;
+  /**
+   * Silence after the last keypress that completes the entry anyway. Callers
+   * pause ~1s between digits; default 4000.
+   */
+  interDigitTimeoutMs?: number;
+  /**
+   * Auto-submit once this many digits are buffered (an ID or phone number of
+   * known length — the caller never has to press `#`). Default: unlimited.
+   */
+  maxDigits?: number;
+  /**
+   * Stop the agent mid-sentence on every keypress — typing means "I'm
+   * answering". Bypasses the interruption guard like `session.interrupt()`.
+   * Without it a flushed entry queues its readback behind stale speech.
+   * Default true.
+   */
+  interruptOnKeypress?: boolean;
+  /**
+   * How a completed entry reaches the model: a function returning the text of
+   * the user turn injected for it (default `defaultKeypadMessage`), or `false`
+   * to inject nothing and handle `keypad.entry` yourself.
+   */
+  message?: ((entry: KeypadEntry) => string) | false;
+  /**
+   * User turn injected when the caller presses the clear key (default text
+   * tells the model the caller is starting over), or `false` for none.
+   */
+  clearMessage?: string | false;
+  /**
+   * Appended to the agent instructions so the model knows what `[keypad]`
+   * messages are (default `DEFAULT_KEYPAD_INSTRUCTIONS`), or `false` to leave
+   * the instructions untouched — say it in your own prompt instead.
+   */
+  instructions?: string | false;
+}
+/** Host-facing handle: `session.keypad`. */
+interface KeypadHandle {
+  /** Digits buffered so far (empty when keypad input is not configured). */
+  readonly digits: string;
+  /** Discard the buffer silently — no event, no message to the model. */
+  clear(): void;
+  /** Complete the buffered entry now (reason `'submit'`); no-op when empty. */
+  submit(): void;
+}
+declare const DEFAULT_KEYPAD_OPTIONS: {
+  readonly submitKey: "#";
+  readonly clearKey: "*";
+  readonly interDigitTimeoutMs: 4000;
+  readonly 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.
+ */
+declare const DEFAULT_KEYPAD_INSTRUCTIONS: string;
+/** Default text of the user turn injected for a completed entry. */
+declare function defaultKeypadMessage(entry: KeypadEntry): string;
+/** Default text of the user turn injected when the caller presses the clear key. */
+declare const DEFAULT_KEYPAD_CLEAR_MESSAGE = "[keypad] I pressed star — I want to start over and retype from the beginning.";
+/** What a keypress meant to the collector. */
+type KeypadKeyKind = 'digit' | 'submit' | 'clear' | 'ignored';
+interface KeypadCollectorHooks {
+  onEntry: (entry: KeypadEntry) => void;
+  onClear: (info: {
+    discarded: string;
+  }) => void;
+}
+declare class KeypadCollector implements KeypadHandle {
+  private readonly submitKey;
+  private readonly clearKey;
+  private readonly interDigitTimeoutMs;
+  private readonly maxDigits;
+  private readonly hooks;
+  private buffer;
+  private timer;
+  private disposed;
+  constructor(options: KeypadOptions, hooks: KeypadCollectorHooks);
+  get digits(): string;
+  /** Feed one keypress (a Twilio `dtmf` frame). Returns what the key meant. */
+  press(key: string): KeypadKeyKind;
+  clear(): void;
+  submit(): void;
+  /** Release the timer; pending digits are dropped (the call is over). */
+  dispose(): void;
+  private complete;
+  private armTimer;
+  private cancelTimer;
+}
+//#endregion
 //#region src/interruption/InterruptionController.d.ts
 /**
  * InterruptionController — decides whether a barge-in is honored.
@@ -462,6 +580,15 @@ interface SessionOptions {
    * this also serializes ALL mid-call session updates for the session.
    */
   noiseAdaptiveVad?: NoiseAdaptiveVadOptions;
+  /**
+   * Opt-in keypad (DTMF) input: buffer keypresses into complete entries —
+   * `#` submits, `*` clears, `maxDigits` auto-submits, 4s of no keypresses
+   * flushes — stop the agent on every keypress, and inject each entry as a
+   * `[keypad] ...` user turn the model answers. Emits `keypad.entry` /
+   * `keypad.cleared`; the raw `dtmf` event keeps firing per key. Set `{}` to
+   * enable with defaults; unset = raw `dtmf` events only, as before.
+   */
+  keypad?: KeypadOptions;
   /**
    * `afterPlayback` (default): tool results wait until current agent audio
    * finishes playing. `immediate`: send as soon as the tool completes.
@@ -535,6 +662,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 +733,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 +764,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;
@@ -660,9 +815,16 @@ interface SessionEventMap {
   'background_audio.stopped': (info: {
     preset?: string;
   }) => void;
+  /** Raw keypress (every Twilio dtmf frame). With `keypad` configured it fires AFTER the collector consumed the key. */
   dtmf: (info: {
     digit: string;
   }) => void;
+  /** A complete keypad entry (`keypad` option): submit key, `maxDigits`, or inter-digit timeout. */
+  'keypad.entry': (entry: KeypadEntry) => void;
+  /** The caller pressed the clear key; `discarded` is what the buffer held. */
+  'keypad.cleared': (info: {
+    discarded: string;
+  }) => void;
   'usage.updated': (usage: UsageInfo, delta: ProviderUsage) => void;
   error: (error: Error) => void;
 }
@@ -683,6 +845,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;
@@ -699,11 +863,17 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   readonly streamSid: string;
   readonly callInfo: ToolCallInfo;
   readonly context: SessionContext;
+  /**
+   * Keypad (DTMF) input handle: digits buffered so far, `clear()`, `submit()`.
+   * Inert (empty, no-ops) unless the `keypad` session option is configured.
+   */
+  readonly keypad: KeypadHandle;
   private stateValue;
   private readonly deps;
   private readonly log;
   private readonly tracker;
   private readonly interruptions;
+  private readonly keypadCollector;
   private readonly usageAccumulator;
   private readonly toolQueue;
   private readonly transcriptEntries;
@@ -713,6 +883,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 +944,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?: {
@@ -822,6 +1003,8 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   /** Immediate teardown (no goodbye). */
   end(reason?: CallEndReason): Promise<void>;
   private buildToolset;
+  /** Agent instructions plus the kit's own notes that must survive handoffs (keypad). */
+  private composeInstructions;
   private buildProviderInit;
   private wireTransport;
   /** Emit 'error'; when the host attached no listener, log instead of losing it. */
@@ -893,6 +1076,9 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
    * starts immediately while the provider session is still being built.
    */
   private playPreGreeting;
+  private handleKeypress;
+  private onKeypadEntry;
+  private onKeypadCleared;
   /** Armed whenever the agent goes quiet and we're waiting on the caller. */
   private armIdleTimer;
   private clearIdleTimer;
@@ -1085,4 +1271,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_KEYPAD_CLEAR_MESSAGE, DEFAULT_KEYPAD_INSTRUCTIONS, DEFAULT_KEYPAD_OPTIONS, 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, KeypadCollector, type KeypadCollectorHooks, type KeypadEntry, type KeypadEntryReason, type KeypadHandle, type KeypadKeyKind, type KeypadOptions, 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, defaultKeypadMessage, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };

package/dist/index.d.mts

@@ -193,6 +193,124 @@ declare function decorateTool(tool: Tool, middlewares: readonly ToolMiddleware[]
 /** Compose wrapExecute chains around an innermost executor. */
 declare function composeExecution(tool: Tool, input: unknown, ctx: ToolContext, middlewares: readonly ToolMiddleware[], innermost: () => Promise<unknown>): Promise<unknown>;
 //#endregion
+//#region src/dtmf/KeypadCollector.d.ts
+/**
+ * KeypadCollector — turns single DTMF keypresses into complete keypad entries.
+ *
+ * Callers type digits with ~1s pauses between them; the model should hear the
+ * whole number once, not ten fragments. The collector buffers digits and
+ * completes an entry on the submit key (`#`), on `maxDigits`, or after
+ * `interDigitTimeoutMs` of no keypresses (the caller stopped without `#` —
+ * flushing lets the agent react, typically "that's only N digits, please
+ * retype"). The clear key (`*`) discards the buffer so the caller can start
+ * over. Letters A–D and anything exotic are ignored.
+ *
+ * Pure state machine: no session, no transport. `CallSession` feeds it from
+ * the Twilio `dtmf` frame (before emitting the raw `dtmf` event), turns the
+ * hooks into `keypad.entry` / `keypad.cleared` events, and injects the default
+ * user-turn message. Field-tested shape (workshop DTMF agents, Aug 2026).
+ */
+type KeypadEntryReason = 'submit' | 'timeout' | 'maxDigits';
+interface KeypadEntry {
+  /** The digits typed, in order (0–9 only). */
+  digits: string;
+  /** What completed the entry: the submit key, the inter-digit timeout, or `maxDigits`. */
+  reason: KeypadEntryReason;
+}
+interface KeypadOptions {
+  /** Key that submits the current entry immediately. Default `'#'`. */
+  submitKey?: string;
+  /** Key that discards the current entry so the caller can start over. Default `'*'`. */
+  clearKey?: string;
+  /**
+   * Silence after the last keypress that completes the entry anyway. Callers
+   * pause ~1s between digits; default 4000.
+   */
+  interDigitTimeoutMs?: number;
+  /**
+   * Auto-submit once this many digits are buffered (an ID or phone number of
+   * known length — the caller never has to press `#`). Default: unlimited.
+   */
+  maxDigits?: number;
+  /**
+   * Stop the agent mid-sentence on every keypress — typing means "I'm
+   * answering". Bypasses the interruption guard like `session.interrupt()`.
+   * Without it a flushed entry queues its readback behind stale speech.
+   * Default true.
+   */
+  interruptOnKeypress?: boolean;
+  /**
+   * How a completed entry reaches the model: a function returning the text of
+   * the user turn injected for it (default `defaultKeypadMessage`), or `false`
+   * to inject nothing and handle `keypad.entry` yourself.
+   */
+  message?: ((entry: KeypadEntry) => string) | false;
+  /**
+   * User turn injected when the caller presses the clear key (default text
+   * tells the model the caller is starting over), or `false` for none.
+   */
+  clearMessage?: string | false;
+  /**
+   * Appended to the agent instructions so the model knows what `[keypad]`
+   * messages are (default `DEFAULT_KEYPAD_INSTRUCTIONS`), or `false` to leave
+   * the instructions untouched — say it in your own prompt instead.
+   */
+  instructions?: string | false;
+}
+/** Host-facing handle: `session.keypad`. */
+interface KeypadHandle {
+  /** Digits buffered so far (empty when keypad input is not configured). */
+  readonly digits: string;
+  /** Discard the buffer silently — no event, no message to the model. */
+  clear(): void;
+  /** Complete the buffered entry now (reason `'submit'`); no-op when empty. */
+  submit(): void;
+}
+declare const DEFAULT_KEYPAD_OPTIONS: {
+  readonly submitKey: "#";
+  readonly clearKey: "*";
+  readonly interDigitTimeoutMs: 4000;
+  readonly 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.
+ */
+declare const DEFAULT_KEYPAD_INSTRUCTIONS: string;
+/** Default text of the user turn injected for a completed entry. */
+declare function defaultKeypadMessage(entry: KeypadEntry): string;
+/** Default text of the user turn injected when the caller presses the clear key. */
+declare const DEFAULT_KEYPAD_CLEAR_MESSAGE = "[keypad] I pressed star — I want to start over and retype from the beginning.";
+/** What a keypress meant to the collector. */
+type KeypadKeyKind = 'digit' | 'submit' | 'clear' | 'ignored';
+interface KeypadCollectorHooks {
+  onEntry: (entry: KeypadEntry) => void;
+  onClear: (info: {
+    discarded: string;
+  }) => void;
+}
+declare class KeypadCollector implements KeypadHandle {
+  private readonly submitKey;
+  private readonly clearKey;
+  private readonly interDigitTimeoutMs;
+  private readonly maxDigits;
+  private readonly hooks;
+  private buffer;
+  private timer;
+  private disposed;
+  constructor(options: KeypadOptions, hooks: KeypadCollectorHooks);
+  get digits(): string;
+  /** Feed one keypress (a Twilio `dtmf` frame). Returns what the key meant. */
+  press(key: string): KeypadKeyKind;
+  clear(): void;
+  submit(): void;
+  /** Release the timer; pending digits are dropped (the call is over). */
+  dispose(): void;
+  private complete;
+  private armTimer;
+  private cancelTimer;
+}
+//#endregion
 //#region src/interruption/InterruptionController.d.ts
 /**
  * InterruptionController — decides whether a barge-in is honored.
@@ -462,6 +580,15 @@ interface SessionOptions {
    * this also serializes ALL mid-call session updates for the session.
    */
   noiseAdaptiveVad?: NoiseAdaptiveVadOptions;
+  /**
+   * Opt-in keypad (DTMF) input: buffer keypresses into complete entries —
+   * `#` submits, `*` clears, `maxDigits` auto-submits, 4s of no keypresses
+   * flushes — stop the agent on every keypress, and inject each entry as a
+   * `[keypad] ...` user turn the model answers. Emits `keypad.entry` /
+   * `keypad.cleared`; the raw `dtmf` event keeps firing per key. Set `{}` to
+   * enable with defaults; unset = raw `dtmf` events only, as before.
+   */
+  keypad?: KeypadOptions;
   /**
    * `afterPlayback` (default): tool results wait until current agent audio
    * finishes playing. `immediate`: send as soon as the tool completes.
@@ -535,6 +662,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 +733,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 +764,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;
@@ -660,9 +815,16 @@ interface SessionEventMap {
   'background_audio.stopped': (info: {
     preset?: string;
   }) => void;
+  /** Raw keypress (every Twilio dtmf frame). With `keypad` configured it fires AFTER the collector consumed the key. */
   dtmf: (info: {
     digit: string;
   }) => void;
+  /** A complete keypad entry (`keypad` option): submit key, `maxDigits`, or inter-digit timeout. */
+  'keypad.entry': (entry: KeypadEntry) => void;
+  /** The caller pressed the clear key; `discarded` is what the buffer held. */
+  'keypad.cleared': (info: {
+    discarded: string;
+  }) => void;
   'usage.updated': (usage: UsageInfo, delta: ProviderUsage) => void;
   error: (error: Error) => void;
 }
@@ -683,6 +845,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;
@@ -699,11 +863,17 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   readonly streamSid: string;
   readonly callInfo: ToolCallInfo;
   readonly context: SessionContext;
+  /**
+   * Keypad (DTMF) input handle: digits buffered so far, `clear()`, `submit()`.
+   * Inert (empty, no-ops) unless the `keypad` session option is configured.
+   */
+  readonly keypad: KeypadHandle;
   private stateValue;
   private readonly deps;
   private readonly log;
   private readonly tracker;
   private readonly interruptions;
+  private readonly keypadCollector;
   private readonly usageAccumulator;
   private readonly toolQueue;
   private readonly transcriptEntries;
@@ -713,6 +883,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 +944,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?: {
@@ -822,6 +1003,8 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   /** Immediate teardown (no goodbye). */
   end(reason?: CallEndReason): Promise<void>;
   private buildToolset;
+  /** Agent instructions plus the kit's own notes that must survive handoffs (keypad). */
+  private composeInstructions;
   private buildProviderInit;
   private wireTransport;
   /** Emit 'error'; when the host attached no listener, log instead of losing it. */
@@ -893,6 +1076,9 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
    * starts immediately while the provider session is still being built.
    */
   private playPreGreeting;
+  private handleKeypress;
+  private onKeypadEntry;
+  private onKeypadCleared;
   /** Armed whenever the agent goes quiet and we're waiting on the caller. */
   private armIdleTimer;
   private clearIdleTimer;
@@ -1085,4 +1271,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_KEYPAD_CLEAR_MESSAGE, DEFAULT_KEYPAD_INSTRUCTIONS, DEFAULT_KEYPAD_OPTIONS, 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, KeypadCollector, type KeypadCollectorHooks, type KeypadEntry, type KeypadEntryReason, type KeypadHandle, type KeypadKeyKind, type KeypadOptions, 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, defaultKeypadMessage, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };