realtime-voice-agents 2.5.2 → 2.5.3

package/README.md

@@ -119,7 +119,7 @@ One `SessionOptions` surface configures all four; where a provider can't honor a
 - **Tools never pause the voice.** Results are delivered the moment they are ready regardless of `toolResultDelivery`; an interruption does not cancel a running tool, and its result still reaches the backend. Results are relayed in the model's own words — use exact wording only through the voice prompt.
 - **Greetings, nudges and goodbyes** (`greeting.instructions`, `idle.prompts`, `finish_call`) are delivered as `session.commentary.append` — the append that reliably produces speech on demand. Keypad entries and deferred results are `session.thinking.append`; runtime instructions are `session.instructions.append`. Each append is capped at 500 tokens (long texts are split).
 - **Immutable session.** Instructions, voice and audio format cannot change after start, so handoffs and reconnects open a fresh session and seed the attributed transcript through `session.input` (≤ 128 messages) — the anti-loop replay is preserved. Sessions expire after 120 minutes; an expiry reconnects the same way.
-- **Transfers wait for the sentence.** A handoff here is a close-and-reopen, and the backend's transfer lands while the voice is still announcing it — the bridge holds the handoff until that utterance has played out (plus one sentence gap, capped at 5 s), so nothing is cut mid-word and `session.handoffHold` audio covers the reopen. Prompt the voice to *delegate first, announce after*: a transfer or tool the voice announces without delegating never happens.
+- **Transfers wait for the sentence.** A handoff here is a close-and-reopen, and the backend's transfer lands while the voice is still announcing it — the bridge holds the handoff until that utterance has played out (plus one sentence gap, capped at 8 s), so nothing is cut mid-word and `session.handoffHold` audio covers the reopen. Prompt the voice to *delegate first, announce after*: a transfer or tool the voice announces without delegating never happens.
 - **Deafness feeds silence.** The model's session clock runs on input audio, so `deafness` options replace caller audio with silence instead of dropping frames. `ignoreUserAudioUntilFirstTurnDone` therefore defaults to **off** here — the model handles talk-over itself; set it explicitly to keep the greeting deaf.
 - **Real-time stream, 200 ms of cushion.** The voice arrives at exactly real-time pace, so Twilio's buffer never runs ahead of playout and every delivery hiccup between OpenAI, your server and Twilio would be an audible gap (Realtime generates faster than real time, so it never has this problem). The provider holds the first 200 ms of each utterance — the last idle delta included, so soft onsets are not clipped — then streams through. `gptLive({ playoutLeadMs })` tunes it, `0` disables; the cost is that much latency on each turn's first word.
 - **Billing is per second** of session (plus backend tokens). `session.usage.audioSeconds` carries the running total; backend token usage is summed from `response.completed`. The provider sends `session.close` on teardown and waits for `session.closed`, so a hung-up call never keeps billing.

package/dist/gpt-live.cjs

@@ -689,18 +689,26 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
 		const wasOpen = this.gate.isOpen;
 		const events = this.gate.feed(bytes);
 		let forwardId = wasOpen ? this.currentUtteranceId : null;
-		let close = null;
-		for (const gateEvent of events) if (gateEvent.type === "open") {
+		let pendingClose = false;
+		for (const gateEvent of events) {
+			if (gateEvent.type === "close") {
+				pendingClose = true;
+				continue;
+			}
+			if (pendingClose) {
+				this.endUtterance();
+				pendingClose = false;
+			}
 			this.beginUtterance();
 			forwardId = this.currentUtteranceId;
 			this.armPlayoutLead();
-		} else close = gateEvent;
+		}
 		if (forwardId) this.forwardAudio(delta, bytes.length / MULAW_BYTES_PER_MS, forwardId);
 		else this.preRoll = {
 			delta,
 			ms: bytes.length / MULAW_BYTES_PER_MS
 		};
-		if (close) this.endUtterance();
+		if (pendingClose) this.endUtterance();
 		else if (this.gate.isOpen) this.armGateStall();
 	}
 	/**
@@ -779,6 +787,7 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
 		});
 	}
 	beginUtterance() {
+		if (this.currentUtteranceId) this.endUtterance();
 		this.currentUtteranceId = `live_utt_${++this.utteranceCounter}`;
 		this.lastUtteranceId = this.currentUtteranceId;
 		this.emit("responseStarted", { responseId: this.currentUtteranceId });

package/dist/gpt-live.mjs

@@ -686,18 +686,26 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
 		const wasOpen = this.gate.isOpen;
 		const events = this.gate.feed(bytes);
 		let forwardId = wasOpen ? this.currentUtteranceId : null;
-		let close = null;
-		for (const gateEvent of events) if (gateEvent.type === "open") {
+		let pendingClose = false;
+		for (const gateEvent of events) {
+			if (gateEvent.type === "close") {
+				pendingClose = true;
+				continue;
+			}
+			if (pendingClose) {
+				this.endUtterance();
+				pendingClose = false;
+			}
 			this.beginUtterance();
 			forwardId = this.currentUtteranceId;
 			this.armPlayoutLead();
-		} else close = gateEvent;
+		}
 		if (forwardId) this.forwardAudio(delta, bytes.length / MULAW_BYTES_PER_MS, forwardId);
 		else this.preRoll = {
 			delta,
 			ms: bytes.length / MULAW_BYTES_PER_MS
 		};
-		if (close) this.endUtterance();
+		if (pendingClose) this.endUtterance();
 		else if (this.gate.isOpen) this.armGateStall();
 	}
 	/**
@@ -776,6 +784,7 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
 		});
 	}
 	beginUtterance() {
+		if (this.currentUtteranceId) this.endUtterance();
 		this.currentUtteranceId = `live_utt_${++this.utteranceCounter}`;
 		this.lastUtteranceId = this.currentUtteranceId;
 		this.emit("responseStarted", { responseId: this.currentUtteranceId });

package/dist/index.cjs

@@ -2631,8 +2631,13 @@ const PREGREETING_MARK = "pre:greeting";
 /** Longer than the speech gate's quiet window plus the mark round trip (0.8 s + ~0.3 s). */
 /** Model-owned turn-taking: the gate can split one sentence at a pause — wait one gap for the next. */
 const SENTENCE_GRACE_MS = 1500;
-/** A deferred handoff runs no later than this after the transfer landed, even mid-utterance. */
-const HANDOFF_DEFER_MAX_MS = 5e3;
+/**
+* A deferred handoff runs no later than this after the transfer landed, even
+* mid-utterance. One announce + a stray utterance + the sentence grace lands
+* right at 5 s in the field (Sept 2026); the cap is for a voice that never
+* stops, and the caller hears the agent meanwhile, so it errs long.
+*/
+const HANDOFF_DEFER_MAX_MS = 8e3;
 /** 400ms per frame — matches production burst-write implementations. */
 const PREGREETING_CHUNK_BYTES = 3200;
 function toError(value) {

package/dist/index.mjs

@@ -2627,8 +2627,13 @@ const PREGREETING_MARK = "pre:greeting";
 /** Longer than the speech gate's quiet window plus the mark round trip (0.8 s + ~0.3 s). */
 /** Model-owned turn-taking: the gate can split one sentence at a pause — wait one gap for the next. */
 const SENTENCE_GRACE_MS = 1500;
-/** A deferred handoff runs no later than this after the transfer landed, even mid-utterance. */
-const HANDOFF_DEFER_MAX_MS = 5e3;
+/**
+* A deferred handoff runs no later than this after the transfer landed, even
+* mid-utterance. One announce + a stray utterance + the sentence grace lands
+* right at 5 s in the field (Sept 2026); the cap is for a voice that never
+* stops, and the caller hears the agent meanwhile, so it errs long.
+*/
+const HANDOFF_DEFER_MAX_MS = 8e3;
 /** 400ms per frame — matches production burst-write implementations. */
 const PREGREETING_CHUNK_BYTES = 3200;
 function toError(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-voice-agents",
-  "version": "2.5.2",
+  "version": "2.5.3",
   "description": "Provider-agnostic bridge between Twilio Media Streams and realtime speech-to-speech AI APIs (OpenAI Realtime, OpenAI GPT-Live full-duplex, 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",