realtime-voice-agents 2.2.0 → 2.3.0

package/README.md

@@ -270,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/fallback/reconnecting/reconnected/closed` · `agent.speech.started/ended` (generation) · **`playback.started/finished/interrupted`** (what the caller heard, mark-confirmed) · `user.speech.started/ended` · `transcript.user/agent` · `tool.started/completed/failed` · `tool.approval.required` · `agent.handoff` · `interruption` / `interruption.blocked` · `vad.suggestion` / `vad.adjusted` (noise-adaptive VAD) · `background_audio.started/stopped` · `dtmf` · `usage.updated` · `error`.
+`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) => {
@@ -300,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

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 = [];
@@ -971,6 +1076,18 @@ var CallSession = class extends require_events.TypedEmitter {
 		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",
@@ -1212,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,
@@ -1237,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"));
@@ -2011,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
 			});
@@ -2087,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;
@@ -2146,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();
@@ -2456,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;
@@ -2473,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;

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.
@@ -688,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;
 }
@@ -729,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;
@@ -863,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. */
@@ -934,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;
@@ -1126,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 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 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.
@@ -688,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;
 }
@@ -729,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;
@@ -863,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. */
@@ -934,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;
@@ -1126,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 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 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.mjs

@@ -189,6 +189,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;
@@ -889,11 +988,17 @@ var CallSession = class extends 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 = [];
@@ -967,6 +1072,18 @@ var CallSession = class extends TypedEmitter {
 		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",
@@ -1208,9 +1325,16 @@ var CallSession = class extends 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,
@@ -1233,7 +1357,9 @@ var CallSession = class extends 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"));
@@ -2007,7 +2133,7 @@ var CallSession = class extends 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
 			});
@@ -2083,6 +2209,29 @@ var CallSession = class extends 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;
@@ -2142,6 +2291,7 @@ var CallSession = class extends 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();
@@ -2449,4 +2599,4 @@ async function captureGreetingAudio(options) {
 	});
 }
 //#endregion
-export { Agent, BaseRealtimeProvider, CallSession, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, InMemorySessionStore, InterruptionController, NoiseAdaptiveVadController, PlaybackTracker, SessionContext, TwilioRealtimeBridge, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };
+export { Agent, BaseRealtimeProvider, CallSession, DEFAULT_KEYPAD_CLEAR_MESSAGE, DEFAULT_KEYPAD_INSTRUCTIONS, DEFAULT_KEYPAD_OPTIONS, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, InMemorySessionStore, InterruptionController, KeypadCollector, NoiseAdaptiveVadController, PlaybackTracker, SessionContext, TwilioRealtimeBridge, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, defaultKeypadMessage, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };

package/package.json

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