realtime-voice-agents 2.2.0 → 2.4.0

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { n as BackgroundAudioPreset, r as BackgroundAudioSpec, t as BackgroundAu
 import { t as TypedEmitter } from "./events-BUMYdETO.cjs";
 import { _ as Logger, a as ProviderToolSchema, c as SessionUpdateOptions, d as ProviderCloseInfo, f as ProviderEvents, g as VadTuningProfile, h as ProviderCapabilities, i as ProviderSessionInit, l as VadConfig, m as ProviderUsage, n as ProviderFactory, o as SendTextOptions, p as ProviderToolCall, r as ProviderFactoryContext, s as SendToolResultOptions, t as BaseRealtimeProvider, u as ProviderAudioDelta, v as consoleLogger, y as noopLogger } from "./BaseRealtimeProvider-BL75_HHh.cjs";
 import { i as WebSocketLike, m as TwilioStartEvent, r as TwilioMediaTransport } from "./transport-B_PJFIVd.cjs";
-import { a as emptyUsage, i as UsageInfo, n as SessionStore, o as TranscriptEntry, r as CallSnapshot, t as InMemorySessionStore } from "./InMemorySessionStore-B5_rq61L.cjs";
+import { a as emptyUsage, i as UsageInfo, n as SessionStore, o as HandoffRecord, r as CallSnapshot, s as TranscriptEntry, t as InMemorySessionStore } from "./InMemorySessionStore-CRBmmCA6.cjs";
 import { i as TwilioRestClient, n as connectStreamTwiml } from "./twiml-z9LjoF4_.cjs";
 import { IncomingMessage } from "node:http";
 //#region src/tools/tool.d.ts
@@ -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.
@@ -671,6 +798,16 @@ interface SessionEventMap {
     to: Agent;
     reason?: string;
   }) => void;
+  /**
+   * A transfer the model asked for was refused. Fires INSTEAD of
+   * `agent.handoff` — the active agent did not change.
+   */
+  'agent.handoff.blocked': (info: {
+    from: Agent;
+    to: Agent;
+    reason?: string;
+    cause: string;
+  }) => void;
   interruption: (info: {
     responseId: string;
     playedMs: number;
@@ -688,9 +825,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;
 }
@@ -729,11 +873,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;
@@ -780,6 +930,15 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private readonly agents;
   private readonly handoffHistory;
   private handoffInProgress;
+  /**
+   * An agent that just took over cannot transfer again until the caller has
+   * spoken. Without it every incoming agent re-derives intent from the same
+   * replayed transcript, decides the request is not its own, and transfers on
+   * — agents ping-ponging with no caller turn between them (field bug, Aug
+   * 2026). Programmatic `handoffTo()` is host intent and bypasses the lock,
+   * but still arms it for the agent it installs.
+   */
+  private handoffLockedUntilCallerTurn;
   /** Pre-synthesized greeting playout state. */
   private pregreeting;
   /** Noise-adaptive VAD (opt-in); built after connect from the provider's ACKed config. */
@@ -863,6 +1022,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. */
@@ -927,6 +1088,12 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private reconnectProvider;
   /** After a reconnect the provider session is blank — restore conversational context. */
   private reinjectHistory;
+  /**
+   * Refuse a model-initiated transfer from an agent the caller has not spoken
+   * to yet. The refusal must reach the model as the tool result, or it simply
+   * calls the same transfer tool again on its next turn.
+   */
+  private rejectHandoff;
   private performHandoff;
   /**
    * Burst-write a stored μ-law greeting straight onto the Twilio socket —
@@ -934,6 +1101,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;
@@ -1126,4 +1296,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 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 };
+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 HandoffRecord, 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

@@ -2,7 +2,7 @@ import { n as BackgroundAudioPreset, r as BackgroundAudioSpec, t as BackgroundAu
 import { t as TypedEmitter } from "./events-BUMYdETO.mjs";
 import { _ as Logger, a as ProviderToolSchema, c as SessionUpdateOptions, d as ProviderCloseInfo, f as ProviderEvents, g as VadTuningProfile, h as ProviderCapabilities, i as ProviderSessionInit, l as VadConfig, m as ProviderUsage, n as ProviderFactory, o as SendTextOptions, p as ProviderToolCall, r as ProviderFactoryContext, s as SendToolResultOptions, t as BaseRealtimeProvider, u as ProviderAudioDelta, v as consoleLogger, y as noopLogger } from "./BaseRealtimeProvider-CWJ81HIt.mjs";
 import { i as WebSocketLike, m as TwilioStartEvent, r as TwilioMediaTransport } from "./transport-CEaLFV4E.mjs";
-import { a as emptyUsage, i as UsageInfo, n as SessionStore, o as TranscriptEntry, r as CallSnapshot, t as InMemorySessionStore } from "./InMemorySessionStore-B5_rq61L.mjs";
+import { a as emptyUsage, i as UsageInfo, n as SessionStore, o as HandoffRecord, r as CallSnapshot, s as TranscriptEntry, t as InMemorySessionStore } from "./InMemorySessionStore-CRBmmCA6.mjs";
 import { i as TwilioRestClient, n as connectStreamTwiml } from "./twiml-z9LjoF4_.mjs";
 import { IncomingMessage } from "node:http";
 //#region src/tools/tool.d.ts
@@ -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.
@@ -671,6 +798,16 @@ interface SessionEventMap {
     to: Agent;
     reason?: string;
   }) => void;
+  /**
+   * A transfer the model asked for was refused. Fires INSTEAD of
+   * `agent.handoff` — the active agent did not change.
+   */
+  'agent.handoff.blocked': (info: {
+    from: Agent;
+    to: Agent;
+    reason?: string;
+    cause: string;
+  }) => void;
   interruption: (info: {
     responseId: string;
     playedMs: number;
@@ -688,9 +825,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;
 }
@@ -729,11 +873,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;
@@ -780,6 +930,15 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private readonly agents;
   private readonly handoffHistory;
   private handoffInProgress;
+  /**
+   * An agent that just took over cannot transfer again until the caller has
+   * spoken. Without it every incoming agent re-derives intent from the same
+   * replayed transcript, decides the request is not its own, and transfers on
+   * — agents ping-ponging with no caller turn between them (field bug, Aug
+   * 2026). Programmatic `handoffTo()` is host intent and bypasses the lock,
+   * but still arms it for the agent it installs.
+   */
+  private handoffLockedUntilCallerTurn;
   /** Pre-synthesized greeting playout state. */
   private pregreeting;
   /** Noise-adaptive VAD (opt-in); built after connect from the provider's ACKed config. */
@@ -863,6 +1022,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. */
@@ -927,6 +1088,12 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private reconnectProvider;
   /** After a reconnect the provider session is blank — restore conversational context. */
   private reinjectHistory;
+  /**
+   * Refuse a model-initiated transfer from an agent the caller has not spoken
+   * to yet. The refusal must reach the model as the tool result, or it simply
+   * calls the same transfer tool again on its next turn.
+   */
+  private rejectHandoff;
   private performHandoff;
   /**
    * Burst-write a stored μ-law greeting straight onto the Twilio socket —
@@ -934,6 +1101,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;
@@ -1126,4 +1296,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 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 };
+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 HandoffRecord, 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 };