realtime-voice-agents 2.2.0 → 2.4.0

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;
@@ -697,9 +796,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
@@ -889,11 +1013,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 = [];
@@ -940,6 +1070,15 @@ var CallSession = class extends 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. */
@@ -967,6 +1106,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 +1359,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 +1391,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"));
@@ -1302,11 +1462,13 @@ var CallSession = class extends 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");
@@ -1602,6 +1764,17 @@ var CallSession = class extends 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
@@ -1985,29 +2158,53 @@ var CallSession = class extends 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
 			});
@@ -2083,6 +2280,30 @@ 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.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;
@@ -2142,6 +2363,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 +2671,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/dist/store.d.cts

@@ -1,2 +1,2 @@
-import { i as UsageInfo, n as SessionStore, o as TranscriptEntry, r as CallSnapshot, t as InMemorySessionStore } from "./InMemorySessionStore-B5_rq61L.cjs";
-export { type CallSnapshot, InMemorySessionStore, type SessionStore, type TranscriptEntry, type UsageInfo };
+import { i as UsageInfo, n as SessionStore, o as HandoffRecord, r as CallSnapshot, s as TranscriptEntry, t as InMemorySessionStore } from "./InMemorySessionStore-CRBmmCA6.cjs";
+export { type CallSnapshot, type HandoffRecord, InMemorySessionStore, type SessionStore, type TranscriptEntry, type UsageInfo };

package/dist/store.d.mts

@@ -1,2 +1,2 @@
-import { i as UsageInfo, n as SessionStore, o as TranscriptEntry, r as CallSnapshot, t as InMemorySessionStore } from "./InMemorySessionStore-B5_rq61L.mjs";
-export { type CallSnapshot, InMemorySessionStore, type SessionStore, type TranscriptEntry, type UsageInfo };
+import { i as UsageInfo, n as SessionStore, o as HandoffRecord, r as CallSnapshot, s as TranscriptEntry, t as InMemorySessionStore } from "./InMemorySessionStore-CRBmmCA6.mjs";
+export { type CallSnapshot, type HandoffRecord, InMemorySessionStore, type SessionStore, type TranscriptEntry, type UsageInfo };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-voice-agents",
-  "version": "2.2.0",
+  "version": "2.4.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",