realtime-voice-agents 2.2.0 → 2.4.0

package/README.md

@@ -184,6 +184,10 @@ const receptionist = new Agent({ name: 'Receptionist', instructions: '…', hand
 
 Each agent in `handoffs` becomes a `transfer_to_<id>` tool. On handoff the session settles the function call, swaps instructions + tools (`session.update` on OpenAI/xAI; close-and-reopen with context carry on Gemini), and triggers a natural continuation — the caller never hears a seam. Also available programmatically: `session.handoffTo('billing')`. Cycles are fine (billing can hand back).
 
+**An agent that just took over cannot transfer again until the caller speaks.** The transfer tool is refused (`agent.handoff.blocked` fires, the model is told why, the active agent does not change); a caller turn — speech or a keypad entry — unlocks it. This makes transfer loops structurally impossible rather than merely discouraged: given the same replayed transcript, each incoming agent otherwise re-derives intent, decides the request is somebody else's, and passes it on. The trade-off is that a pure router node costs an extra caller turn, so direct arcs between agents beat hub-and-spoke. `session.handoffTo()` is host intent and bypasses the lock (it still arms it for the agent it installs).
+
+The context an incoming agent receives is attributed, not flat: each replayed line names the agent that said it, and completed transfers appear as `[transfer] A -> B (reason: …)` lines — so it can see what was already answered and already routed.
+
 ## Built-in call controls
 
 ```ts
@@ -270,9 +274,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` / `agent.handoff.blocked` · `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 +333,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/{InMemorySessionStore-B5_rq61L.d.cts → InMemorySessionStore-CRBmmCA6.d.cts}

@@ -9,6 +9,14 @@ interface TranscriptEntry {
   /** The caller cut this utterance off mid-playback. */
   interrupted?: boolean;
 }
+/** One completed transfer, as recorded in the session's handoff history. */
+interface HandoffRecord {
+  from: string;
+  to: string;
+  /** Milliseconds since call start. */
+  atMs: number;
+  reason?: string;
+}
 //#endregion
 //#region src/session/usage.d.ts
 /** Accumulated token consumption for a call, normalized across providers. */
@@ -40,11 +48,7 @@ interface CallSnapshot {
   transcript: TranscriptEntry[];
   usage: UsageInfo;
   context: Record<string, unknown>;
-  handoffHistory: Array<{
-    from: string;
-    to: string;
-    atMs: number;
-  }>;
+  handoffHistory: HandoffRecord[];
   /** Gemini session-resumption handle, when the provider supplies one. */
   resumptionHandle?: string;
   startedAtMs: number;
@@ -80,4 +84,4 @@ declare class InMemorySessionStore implements SessionStore {
   list(): CallSnapshot[];
 }
 //#endregion
-export { emptyUsage as a, UsageInfo as i, SessionStore as n, TranscriptEntry as o, CallSnapshot as r, InMemorySessionStore as t };
+export { emptyUsage as a, UsageInfo as i, SessionStore as n, HandoffRecord as o, CallSnapshot as r, TranscriptEntry as s, InMemorySessionStore as t };

package/dist/{InMemorySessionStore-B5_rq61L.d.mts → InMemorySessionStore-CRBmmCA6.d.mts}

@@ -9,6 +9,14 @@ interface TranscriptEntry {
   /** The caller cut this utterance off mid-playback. */
   interrupted?: boolean;
 }
+/** One completed transfer, as recorded in the session's handoff history. */
+interface HandoffRecord {
+  from: string;
+  to: string;
+  /** Milliseconds since call start. */
+  atMs: number;
+  reason?: string;
+}
 //#endregion
 //#region src/session/usage.d.ts
 /** Accumulated token consumption for a call, normalized across providers. */
@@ -40,11 +48,7 @@ interface CallSnapshot {
   transcript: TranscriptEntry[];
   usage: UsageInfo;
   context: Record<string, unknown>;
-  handoffHistory: Array<{
-    from: string;
-    to: string;
-    atMs: number;
-  }>;
+  handoffHistory: HandoffRecord[];
   /** Gemini session-resumption handle, when the provider supplies one. */
   resumptionHandle?: string;
   startedAtMs: number;
@@ -80,4 +84,4 @@ declare class InMemorySessionStore implements SessionStore {
   list(): CallSnapshot[];
 }
 //#endregion
-export { emptyUsage as a, UsageInfo as i, SessionStore as n, TranscriptEntry as o, CallSnapshot as r, InMemorySessionStore as t };
+export { emptyUsage as a, UsageInfo as i, SessionStore as n, HandoffRecord as o, CallSnapshot as r, TranscriptEntry as s, InMemorySessionStore as t };

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;
@@ -701,9 +800,34 @@ function delayForAttempt(policy, attempt, random = Math.random) {
 }
 //#endregion
 //#region src/session/transcript.ts
-/** Render a transcript for history re-injection after reconnect/handoff. */
-function formatTranscriptForInjection(entries, maxTurns = 30) {
-	return entries.slice(-maxTurns).map((entry) => `${entry.role === "user" ? "Caller" : "Agent"}: ${entry.text}`).join("\n");
+/**
+* Render a transcript for history re-injection after reconnect/handoff.
+*
+* Agent lines are attributed to the agent that said them and completed
+* transfers are interleaved as `[transfer]` lines: an incoming agent handed a
+* flat `Agent:` dialogue re-derives intent from scratch, decides the request
+* belongs to somebody else, and transfers on — agents ping-ponging with no
+* caller turn between them (field bug, Aug 2026). Replaying WHO said what and
+* WHAT was already routed is what stops the second lap.
+*/
+function formatTranscriptForInjection(entries, options = {}) {
+	const { maxTurns = 30, agentNames, handoffs = [] } = options;
+	const recent = entries.slice(-maxTurns);
+	if (recent.length === 0) return "";
+	const nameOf = (agentId) => (agentId ? agentNames?.get(agentId) : void 0) ?? agentId ?? "Agent";
+	const windowStartMs = recent[0].timestampMs;
+	const lines = recent.map((entry) => ({
+		atMs: entry.timestampMs,
+		text: entry.role === "user" ? `Caller: ${entry.text}` : `${nameOf(entry.agentId)}: ${entry.text}`
+	}));
+	for (const handoff of handoffs) {
+		if (handoff.atMs < windowStartMs) continue;
+		lines.push({
+			atMs: handoff.atMs,
+			text: `[transfer] ${nameOf(handoff.from)} -> ${nameOf(handoff.to)}` + (handoff.reason ? ` (reason: ${handoff.reason})` : "")
+		});
+	}
+	return lines.sort((a, b) => a.atMs - b.atMs).map((line) => line.text).join("\n");
 }
 //#endregion
 //#region src/session/usage.ts
@@ -893,11 +1017,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 = [];
@@ -944,6 +1074,15 @@ var CallSession = class extends require_events.TypedEmitter {
 	agents;
 	handoffHistory = [];
 	handoffInProgress = false;
+	/**
+	* 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.
+	*/
+	handoffLockedUntilCallerTurn = false;
 	/** Pre-synthesized greeting playout state. */
 	pregreeting = null;
 	/** Noise-adaptive VAD (opt-in); built after connect from the provider's ACKed config. */
@@ -971,6 +1110,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 +1363,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 +1395,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"));
@@ -1306,11 +1466,13 @@ var CallSession = class extends require_events.TypedEmitter {
 			};
 			this.transcriptEntries.push(entry);
 			this.nudgeCount = 0;
+			this.handoffLockedUntilCallerTurn = false;
 			this.emit("transcript.user", entry);
 		});
 		provider.on("userSpeechStarted", () => {
 			this.userSpeechActive = true;
 			this.userSpeechStartedAtMs = Date.now();
+			this.handoffLockedUntilCallerTurn = false;
 			this.clearIdleTimer();
 			this.nudgeCount = 0;
 			this.emit("user.speech.started");
@@ -1606,6 +1768,17 @@ var CallSession = class extends require_events.TypedEmitter {
 					this.deliverToolResult(call.id, { error: `unknown agent "${directive.targetAgentId}"` });
 					return;
 				}
+				if (this.handoffLockedUntilCallerTurn) {
+					this.rejectHandoff(target, directive.reason, call.id);
+					this.emit("tool.completed", {
+						...baseInfo,
+						strategy: tool.strategy,
+						input,
+						result: { handoffBlocked: target.id },
+						durationMs: Date.now() - started
+					});
+					return;
+				}
 				this.deliverToolResult(call.id, {
 					status: "transferring_conversation",
 					to: target.name
@@ -1989,29 +2162,53 @@ var CallSession = class extends require_events.TypedEmitter {
 	/** After a reconnect the provider session is blank — restore conversational context. */
 	reinjectHistory(provider) {
 		if (this.transcriptEntries.length === 0) return;
-		const summary = formatTranscriptForInjection(this.transcriptEntries);
-		provider.sendText(`Context: this phone call reconnected mid-conversation. Transcript so far:\n${summary}\nContinue naturally from where it left off; do not greet again.`, {
+		const summary = formatTranscriptForInjection(this.transcriptEntries, {
+			agentNames: new Map([...this.agents].map(([id, agent]) => [id, agent.name])),
+			handoffs: this.handoffHistory
+		});
+		provider.sendText(`Context: this phone call reconnected mid-conversation. You are ${this.activeAgentValue.name}. Each line below names who said it; \`[transfer]\` lines are routing that ALREADY happened.\n${summary}\nAnything already answered or already routed above must not be routed again. Continue naturally from where it left off; do not greet again.`, {
 			role: "system",
 			triggerResponse: false
 		});
 	}
+	/**
+	* 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.
+	*/
+	rejectHandoff(target, reason, callId) {
+		const from = this.activeAgentValue;
+		this.log.warn(`blocked transfer ${from.id} -> ${target.id}: the caller has not spoken since the last one`);
+		this.deliverToolResult(callId, {
+			error: "transfer_rejected",
+			message: "You just took over this call and the caller has not spoken since. Do not transfer again yet — handle their request yourself, or ask them what they need. You may transfer once they reply."
+		});
+		this.emit("agent.handoff.blocked", {
+			from,
+			to: target,
+			reason,
+			cause: "no-caller-turn"
+		});
+	}
 	async performHandoff(target, reason) {
 		if (this.stateValue !== "active" || !this.provider) return;
 		if (target.id === this.activeAgentValue.id) return;
 		const from = this.activeAgentValue;
 		this.activeAgentValue = target;
+		this.handoffLockedUntilCallerTurn = true;
 		this.toolset = this.buildToolset();
 		this.handoffHistory.push({
 			from: from.id,
 			to: target.id,
-			atMs: Date.now() - this.startedAtMs
+			atMs: Date.now() - this.startedAtMs,
+			...reason ? { reason } : {}
 		});
 		const continueInstruction = `You are now ${target.name}. Continue the SAME phone conversation naturally — acknowledge the caller and take over; do not restart with a cold greeting.` + (reason ? ` Transfer context: ${reason}.` : "");
 		const voiceChanges = target.voice !== void 0 && target.voice !== from.voice;
 		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 +2284,30 @@ 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.handoffLockedUntilCallerTurn = false;
+		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 +2367,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 +2678,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 +2699,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;