realtime-voice-agents 2.5.0 → 2.5.1

package/README.md

@@ -119,7 +119,8 @@ 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.
-- **Deafness feeds silence.** The model's session clock runs on input audio, so `deafness` options replace caller audio with silence instead of dropping frames.
+- **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.
+- **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.
 - **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.
 
 ## Provider fallbacks
@@ -341,7 +342,7 @@ session: {
   greeting: { mode: 'agent-initiates' },        // 'user-initiates' to wait
   interruptions: { enabled: true },
   deafness: {
-    ignoreUserAudioUntilFirstTurnDone: true,    // auto-false with greeting.mode 'user-initiates' (caller must be heard to start)
+    ignoreUserAudioUntilFirstTurnDone: undefined, // auto: true, except false with greeting.mode 'user-initiates' and on full-duplex providers (GPT-Live)
     muteDuringToolExecution: true,
     muteWhileAgentSpeaking: false,              // half-duplex: deaf while agent audio plays (caller speech is lost, not queued)
   },
@@ -355,6 +356,7 @@ session: {
   toolResultDelivery: 'afterPlayback',          // or 'immediate'
   toolBackgroundAudio: undefined,               // default hold audio for tools
   handoffVoicePolicy: 'keep',                   // or 'reconnect' to switch voices
+  handoffHold: undefined,                       // { spec: 'ringing', ... }: hold audio over a reconnect-style handoff (Gemini, GPT-Live)
   context: {},                                  // seed session KV for tools/instructions
 }
 ```

package/dist/index.cjs

@@ -535,6 +535,28 @@ var PlaybackTracker = class {
 		return interrupted;
 	}
 	/**
+	* The provider session behind every open response is gone (closed for a
+	* handoff or reconnect), so their remaining marks may never come home:
+	* finalize them at their current playedMs so `isPlaybackActive()` cannot
+	* stay true for the rest of the call. Late echoes classify as flushed.
+	* Returns the abandoned responses.
+	*/
+	abandonOpen() {
+		const abandoned = [];
+		for (const track of [...this.responses.values()]) {
+			if (track.finished) continue;
+			track.flushed = true;
+			track.finished = true;
+			abandoned.push({
+				responseId: track.responseId,
+				playedMs: track.playedMs,
+				itemId: track.itemId
+			});
+			this.maybeForget(track);
+		}
+		return abandoned;
+	}
+	/**
 	* Best-estimate of what the caller has heard of `responseId` right now:
 	* last confirmed mark plus wall-clock elapsed since, clamped to the total.
 	*/
@@ -1099,6 +1121,8 @@ var CallSession = class extends require_events.TypedEmitter {
 	reconnecting = false;
 	pendingHangup = null;
 	pendingTransfer = null;
+	/** Model-owned turn-taking: a transfer that landed mid-utterance, held until the sentence plays out. */
+	pendingHandoff = null;
 	endedReason = null;
 	hangupReason = "agent-hangup";
 	middlewares;
@@ -1491,6 +1515,11 @@ var CallSession = class extends require_events.TypedEmitter {
 					this.pendingHangup.grace = null;
 				}
 			}
+			if (this.pendingHandoff?.grace) {
+				clearTimeout(this.pendingHandoff.grace);
+				this.timers.delete(this.pendingHandoff.grace);
+				this.pendingHandoff.grace = null;
+			}
 			this.noteHangupProgress();
 			this.clearIdleTimer();
 			this.interruptions.onResponseStarted(responseId);
@@ -1511,6 +1540,7 @@ var CallSession = class extends require_events.TypedEmitter {
 				this.flushToolQueue();
 				this.executePendingTransfer();
 				this.maybeCompleteHangup();
+				this.maybeRunPendingHandoff();
 			}
 		});
 		provider.on("agentTranscript", ({ responseId, text }) => {
@@ -1578,7 +1608,7 @@ var CallSession = class extends require_events.TypedEmitter {
 			const proposal = this.noiseVad.onInboundFrame(payload, excluded);
 			if (proposal) this.handleVadProposal(proposal);
 		}
-		if (this.pregreeting !== null && !this.pregreeting.played || this.deps.options.deafness.ignoreUserAudioUntilFirstTurnDone && !this.firstTurnDone || this.deps.options.deafness.muteDuringToolExecution && this.runningTools.size > 0 || this.deps.options.deafness.muteWhileAgentSpeaking && this.tracker.isPlaybackActive() || this.interruptions.isSuspended) {
+		if (this.pregreeting !== null && !this.pregreeting.played || this.firstTurnDeafness() && !this.firstTurnDone || this.deps.options.deafness.muteDuringToolExecution && this.runningTools.size > 0 || this.deps.options.deafness.muteWhileAgentSpeaking && this.tracker.isPlaybackActive() || this.interruptions.isSuspended) {
 			if (!this.modelOwnsTurnTaking()) return;
 			payload = silenceLike(payload);
 		}
@@ -1673,6 +1703,7 @@ var CallSession = class extends require_events.TypedEmitter {
 		this.flushToolQueue();
 		this.executePendingTransfer();
 		this.maybeCompleteHangup();
+		this.maybeRunPendingHandoff();
 		if (this.blockedUserTurn === "committed") {
 			this.blockedUserTurn = "idle";
 			if (!hadQueuedToolResults && this.runningTools.size === 0) this.provider?.createResponse();
@@ -1862,6 +1893,10 @@ var CallSession = class extends require_events.TypedEmitter {
 					result: { handoffTo: target.id },
 					durationMs: Date.now() - started
 				});
+				if (this.modelOwnsTurnTaking() && (this.generating || this.tracker.isPlaybackActive())) {
+					this.deferHandoff(target, directive.reason);
+					return;
+				}
 				await this.performHandoff(target, directive.reason);
 				return;
 			}
@@ -2162,7 +2197,7 @@ var CallSession = class extends require_events.TypedEmitter {
 				pending.grace = null;
 				if (this.generating || this.tracker.isPlaybackActive()) return;
 				this.completeHangup();
-			}, HANGUP_SENTENCE_GRACE_MS);
+			}, SENTENCE_GRACE_MS);
 			timer.unref?.();
 			this.timers.add(timer);
 			this.pendingHangup.grace = timer;
@@ -2229,6 +2264,7 @@ var CallSession = class extends require_events.TypedEmitter {
 		if (this.stateValue !== "active") return;
 		const provider = this.provider;
 		if (!provider) return;
+		this.abandonOpenPlayback();
 		try {
 			await provider.connect(this.buildProviderInit());
 		} catch (error) {
@@ -2277,6 +2313,89 @@ var CallSession = class extends require_events.TypedEmitter {
 			cause: "no-caller-turn"
 		});
 	}
+	/**
+	* First-turn deafness shields an agent-first greeting from early caller
+	* speech where the bridge owns barge-in. A full-duplex model owns talk-over
+	* itself, and "deaf" there only means fed silence — so the default flips
+	* off on `turnTaking: 'model'`; an explicit setting is honored as written.
+	*/
+	firstTurnDeafness() {
+		return this.deps.options.deafness.ignoreUserAudioUntilFirstTurnDone ?? !this.modelOwnsTurnTaking();
+	}
+	/**
+	* The provider session behind every open response is being closed (handoff
+	* or reconnect): their tail marks may never come. Finalize them now, or
+	* `isPlaybackActive()` stays true for the rest of the call and everything
+	* gated on it — the hangup grace, REST transfers, guard rotation — wedges
+	* (field, Sept 2026). Whatever Twilio still holds plays out; no
+	* `playback.finished` is claimed for audio nobody confirmed.
+	*/
+	abandonOpenPlayback() {
+		if (this.tracker.abandonOpen().length === 0) return;
+		this.interruptions.onPlaybackEnded();
+		this.maybeCompleteHangup();
+		this.maybeRunPendingHandoff();
+	}
+	/**
+	* On a full-duplex provider the backend's transfer lands while the voice is
+	* still speaking the sentence that announces it, and the handoff is a
+	* close-and-reopen: performing it at once cuts that sentence, and the
+	* in-flight deltas kill the handoff hold before it starts (field, Sept
+	* 2026). Hold the transfer until the utterance has played out plus one
+	* sentence gap — a new utterance cancels the grace — capped so a voice that
+	* never stops still hands off.
+	*/
+	deferHandoff(target, reason) {
+		if (this.pendingHandoff) {
+			this.pendingHandoff.target = target;
+			this.pendingHandoff.reason = reason;
+			return;
+		}
+		const cap = setTimeout(() => {
+			this.timers.delete(cap);
+			const pending = this.pendingHandoff;
+			if (!pending) return;
+			this.log.warn("deferred handoff capped — the voice kept talking; handing off now");
+			this.clearPendingHandoff();
+			this.performHandoff(pending.target, pending.reason);
+		}, HANDOFF_DEFER_MAX_MS);
+		cap.unref?.();
+		this.timers.add(cap);
+		this.pendingHandoff = {
+			target,
+			reason,
+			grace: null,
+			cap
+		};
+		this.maybeRunPendingHandoff();
+	}
+	maybeRunPendingHandoff() {
+		const pending = this.pendingHandoff;
+		if (!pending || pending.grace) return;
+		if (this.generating || this.tracker.isPlaybackActive()) return;
+		const grace = setTimeout(() => {
+			this.timers.delete(grace);
+			const current = this.pendingHandoff;
+			if (!current) return;
+			current.grace = null;
+			if (this.generating || this.tracker.isPlaybackActive()) return;
+			this.clearPendingHandoff();
+			this.performHandoff(current.target, current.reason);
+		}, SENTENCE_GRACE_MS);
+		grace.unref?.();
+		this.timers.add(grace);
+		pending.grace = grace;
+	}
+	clearPendingHandoff() {
+		const pending = this.pendingHandoff;
+		if (!pending) return;
+		this.pendingHandoff = null;
+		for (const timer of [pending.grace, pending.cap]) {
+			if (!timer) continue;
+			clearTimeout(timer);
+			this.timers.delete(timer);
+		}
+	}
 	async performHandoff(target, reason) {
 		if (this.stateValue !== "active" || !this.provider) return;
 		if (target.id === this.activeAgentValue.id) return;
@@ -2309,6 +2428,7 @@ var CallSession = class extends require_events.TypedEmitter {
 				startDelayMs: hold.startDelayMs ?? 300
 			});
 			try {
+				this.abandonOpenPlayback();
 				await this.provider.close();
 				await this.provider.connect({
 					...this.buildProviderInit(),
@@ -2509,7 +2629,10 @@ var CallSession = class extends require_events.TypedEmitter {
 };
 const PREGREETING_MARK = "pre:greeting";
 /** Longer than the speech gate's quiet window plus the mark round trip (0.8 s + ~0.3 s). */
-const HANGUP_SENTENCE_GRACE_MS = 1500;
+/** 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;
 /** 400ms per frame — matches production burst-write implementations. */
 const PREGREETING_CHUNK_BYTES = 3200;
 function toError(value) {
@@ -2536,7 +2659,6 @@ const DEFAULT_SESSION_OPTIONS = {
 	greeting: { mode: "agent-initiates" },
 	interruptions: { enabled: true },
 	deafness: {
-		ignoreUserAudioUntilFirstTurnDone: true,
 		muteDuringToolExecution: true,
 		muteWhileAgentSpeaking: false
 	},

package/dist/index.d.cts

@@ -521,11 +521,14 @@ interface GreetingOptions {
 interface DeafnessOptions {
   /**
    * Drop caller audio until the agent's first turn finishes playing.
-   * Protects the greeting from noisy pickups. Default true — except with
-   * `greeting.mode: 'user-initiates'`, where the caller must be heard to
-   * start the call at all, so the default flips to false. An explicit true
-   * is honored even there, but deafens the call until something else
-   * (an idle nudge, a tool) produces the agent's first turn.
+   * Protects the greeting from noisy pickups on providers where the bridge
+   * owns barge-in. Unset = automatic: true there, false with
+   * `greeting.mode: 'user-initiates'` (the caller must be heard to start the
+   * call at all) and on full-duplex providers (`turnTaking: 'model'`), where
+   * the model owns talk-over and "deaf" only means fed silence. An explicit
+   * value is honored as written — an explicit true with user-initiates
+   * deafens the call until something else (an idle nudge, a tool) produces
+   * the agent's first turn.
    */
   ignoreUserAudioUntilFirstTurnDone?: boolean;
   /** Drop caller audio while a foreground tool is running. Default true. */
@@ -914,6 +917,8 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private reconnecting;
   private pendingHangup;
   private pendingTransfer;
+  /** Model-owned turn-taking: a transfer that landed mid-utterance, held until the sentence plays out. */
+  private pendingHandoff;
   private endedReason;
   private hangupReason;
   private readonly middlewares;
@@ -1098,6 +1103,34 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
    * calls the same transfer tool again on its next turn.
    */
   private rejectHandoff;
+  /**
+   * First-turn deafness shields an agent-first greeting from early caller
+   * speech where the bridge owns barge-in. A full-duplex model owns talk-over
+   * itself, and "deaf" there only means fed silence — so the default flips
+   * off on `turnTaking: 'model'`; an explicit setting is honored as written.
+   */
+  private firstTurnDeafness;
+  /**
+   * The provider session behind every open response is being closed (handoff
+   * or reconnect): their tail marks may never come. Finalize them now, or
+   * `isPlaybackActive()` stays true for the rest of the call and everything
+   * gated on it — the hangup grace, REST transfers, guard rotation — wedges
+   * (field, Sept 2026). Whatever Twilio still holds plays out; no
+   * `playback.finished` is claimed for audio nobody confirmed.
+   */
+  private abandonOpenPlayback;
+  /**
+   * On a full-duplex provider the backend's transfer lands while the voice is
+   * still speaking the sentence that announces it, and the handoff is a
+   * close-and-reopen: performing it at once cuts that sentence, and the
+   * in-flight deltas kill the handoff hold before it starts (field, Sept
+   * 2026). Hold the transfer until the utterance has played out plus one
+   * sentence gap — a new utterance cancels the grace — capped so a voice that
+   * never stops still hands off.
+   */
+  private deferHandoff;
+  private maybeRunPendingHandoff;
+  private clearPendingHandoff;
   private performHandoff;
   /**
    * Burst-write a stored μ-law greeting straight onto the Twilio socket —
@@ -1276,6 +1309,18 @@ declare class PlaybackTracker {
     playedMs: number;
     itemId?: string;
   }>;
+  /**
+   * The provider session behind every open response is gone (closed for a
+   * handoff or reconnect), so their remaining marks may never come home:
+   * finalize them at their current playedMs so `isPlaybackActive()` cannot
+   * stay true for the rest of the call. Late echoes classify as flushed.
+   * Returns the abandoned responses.
+   */
+  abandonOpen(): Array<{
+    responseId: string;
+    playedMs: number;
+    itemId?: string;
+  }>;
   /**
    * Best-estimate of what the caller has heard of `responseId` right now:
    * last confirmed mark plus wall-clock elapsed since, clamped to the total.

package/dist/index.d.mts

@@ -521,11 +521,14 @@ interface GreetingOptions {
 interface DeafnessOptions {
   /**
    * Drop caller audio until the agent's first turn finishes playing.
-   * Protects the greeting from noisy pickups. Default true — except with
-   * `greeting.mode: 'user-initiates'`, where the caller must be heard to
-   * start the call at all, so the default flips to false. An explicit true
-   * is honored even there, but deafens the call until something else
-   * (an idle nudge, a tool) produces the agent's first turn.
+   * Protects the greeting from noisy pickups on providers where the bridge
+   * owns barge-in. Unset = automatic: true there, false with
+   * `greeting.mode: 'user-initiates'` (the caller must be heard to start the
+   * call at all) and on full-duplex providers (`turnTaking: 'model'`), where
+   * the model owns talk-over and "deaf" only means fed silence. An explicit
+   * value is honored as written — an explicit true with user-initiates
+   * deafens the call until something else (an idle nudge, a tool) produces
+   * the agent's first turn.
    */
   ignoreUserAudioUntilFirstTurnDone?: boolean;
   /** Drop caller audio while a foreground tool is running. Default true. */
@@ -914,6 +917,8 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private reconnecting;
   private pendingHangup;
   private pendingTransfer;
+  /** Model-owned turn-taking: a transfer that landed mid-utterance, held until the sentence plays out. */
+  private pendingHandoff;
   private endedReason;
   private hangupReason;
   private readonly middlewares;
@@ -1098,6 +1103,34 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
    * calls the same transfer tool again on its next turn.
    */
   private rejectHandoff;
+  /**
+   * First-turn deafness shields an agent-first greeting from early caller
+   * speech where the bridge owns barge-in. A full-duplex model owns talk-over
+   * itself, and "deaf" there only means fed silence — so the default flips
+   * off on `turnTaking: 'model'`; an explicit setting is honored as written.
+   */
+  private firstTurnDeafness;
+  /**
+   * The provider session behind every open response is being closed (handoff
+   * or reconnect): their tail marks may never come. Finalize them now, or
+   * `isPlaybackActive()` stays true for the rest of the call and everything
+   * gated on it — the hangup grace, REST transfers, guard rotation — wedges
+   * (field, Sept 2026). Whatever Twilio still holds plays out; no
+   * `playback.finished` is claimed for audio nobody confirmed.
+   */
+  private abandonOpenPlayback;
+  /**
+   * On a full-duplex provider the backend's transfer lands while the voice is
+   * still speaking the sentence that announces it, and the handoff is a
+   * close-and-reopen: performing it at once cuts that sentence, and the
+   * in-flight deltas kill the handoff hold before it starts (field, Sept
+   * 2026). Hold the transfer until the utterance has played out plus one
+   * sentence gap — a new utterance cancels the grace — capped so a voice that
+   * never stops still hands off.
+   */
+  private deferHandoff;
+  private maybeRunPendingHandoff;
+  private clearPendingHandoff;
   private performHandoff;
   /**
    * Burst-write a stored μ-law greeting straight onto the Twilio socket —
@@ -1276,6 +1309,18 @@ declare class PlaybackTracker {
     playedMs: number;
     itemId?: string;
   }>;
+  /**
+   * The provider session behind every open response is gone (closed for a
+   * handoff or reconnect), so their remaining marks may never come home:
+   * finalize them at their current playedMs so `isPlaybackActive()` cannot
+   * stay true for the rest of the call. Late echoes classify as flushed.
+   * Returns the abandoned responses.
+   */
+  abandonOpen(): Array<{
+    responseId: string;
+    playedMs: number;
+    itemId?: string;
+  }>;
   /**
    * Best-estimate of what the caller has heard of `responseId` right now:
    * last confirmed mark plus wall-clock elapsed since, clamped to the total.

package/dist/index.mjs

@@ -531,6 +531,28 @@ var PlaybackTracker = class {
 		return interrupted;
 	}
 	/**
+	* The provider session behind every open response is gone (closed for a
+	* handoff or reconnect), so their remaining marks may never come home:
+	* finalize them at their current playedMs so `isPlaybackActive()` cannot
+	* stay true for the rest of the call. Late echoes classify as flushed.
+	* Returns the abandoned responses.
+	*/
+	abandonOpen() {
+		const abandoned = [];
+		for (const track of [...this.responses.values()]) {
+			if (track.finished) continue;
+			track.flushed = true;
+			track.finished = true;
+			abandoned.push({
+				responseId: track.responseId,
+				playedMs: track.playedMs,
+				itemId: track.itemId
+			});
+			this.maybeForget(track);
+		}
+		return abandoned;
+	}
+	/**
 	* Best-estimate of what the caller has heard of `responseId` right now:
 	* last confirmed mark plus wall-clock elapsed since, clamped to the total.
 	*/
@@ -1095,6 +1117,8 @@ var CallSession = class extends TypedEmitter {
 	reconnecting = false;
 	pendingHangup = null;
 	pendingTransfer = null;
+	/** Model-owned turn-taking: a transfer that landed mid-utterance, held until the sentence plays out. */
+	pendingHandoff = null;
 	endedReason = null;
 	hangupReason = "agent-hangup";
 	middlewares;
@@ -1487,6 +1511,11 @@ var CallSession = class extends TypedEmitter {
 					this.pendingHangup.grace = null;
 				}
 			}
+			if (this.pendingHandoff?.grace) {
+				clearTimeout(this.pendingHandoff.grace);
+				this.timers.delete(this.pendingHandoff.grace);
+				this.pendingHandoff.grace = null;
+			}
 			this.noteHangupProgress();
 			this.clearIdleTimer();
 			this.interruptions.onResponseStarted(responseId);
@@ -1507,6 +1536,7 @@ var CallSession = class extends TypedEmitter {
 				this.flushToolQueue();
 				this.executePendingTransfer();
 				this.maybeCompleteHangup();
+				this.maybeRunPendingHandoff();
 			}
 		});
 		provider.on("agentTranscript", ({ responseId, text }) => {
@@ -1574,7 +1604,7 @@ var CallSession = class extends TypedEmitter {
 			const proposal = this.noiseVad.onInboundFrame(payload, excluded);
 			if (proposal) this.handleVadProposal(proposal);
 		}
-		if (this.pregreeting !== null && !this.pregreeting.played || this.deps.options.deafness.ignoreUserAudioUntilFirstTurnDone && !this.firstTurnDone || this.deps.options.deafness.muteDuringToolExecution && this.runningTools.size > 0 || this.deps.options.deafness.muteWhileAgentSpeaking && this.tracker.isPlaybackActive() || this.interruptions.isSuspended) {
+		if (this.pregreeting !== null && !this.pregreeting.played || this.firstTurnDeafness() && !this.firstTurnDone || this.deps.options.deafness.muteDuringToolExecution && this.runningTools.size > 0 || this.deps.options.deafness.muteWhileAgentSpeaking && this.tracker.isPlaybackActive() || this.interruptions.isSuspended) {
 			if (!this.modelOwnsTurnTaking()) return;
 			payload = silenceLike(payload);
 		}
@@ -1669,6 +1699,7 @@ var CallSession = class extends TypedEmitter {
 		this.flushToolQueue();
 		this.executePendingTransfer();
 		this.maybeCompleteHangup();
+		this.maybeRunPendingHandoff();
 		if (this.blockedUserTurn === "committed") {
 			this.blockedUserTurn = "idle";
 			if (!hadQueuedToolResults && this.runningTools.size === 0) this.provider?.createResponse();
@@ -1858,6 +1889,10 @@ var CallSession = class extends TypedEmitter {
 					result: { handoffTo: target.id },
 					durationMs: Date.now() - started
 				});
+				if (this.modelOwnsTurnTaking() && (this.generating || this.tracker.isPlaybackActive())) {
+					this.deferHandoff(target, directive.reason);
+					return;
+				}
 				await this.performHandoff(target, directive.reason);
 				return;
 			}
@@ -2158,7 +2193,7 @@ var CallSession = class extends TypedEmitter {
 				pending.grace = null;
 				if (this.generating || this.tracker.isPlaybackActive()) return;
 				this.completeHangup();
-			}, HANGUP_SENTENCE_GRACE_MS);
+			}, SENTENCE_GRACE_MS);
 			timer.unref?.();
 			this.timers.add(timer);
 			this.pendingHangup.grace = timer;
@@ -2225,6 +2260,7 @@ var CallSession = class extends TypedEmitter {
 		if (this.stateValue !== "active") return;
 		const provider = this.provider;
 		if (!provider) return;
+		this.abandonOpenPlayback();
 		try {
 			await provider.connect(this.buildProviderInit());
 		} catch (error) {
@@ -2273,6 +2309,89 @@ var CallSession = class extends TypedEmitter {
 			cause: "no-caller-turn"
 		});
 	}
+	/**
+	* First-turn deafness shields an agent-first greeting from early caller
+	* speech where the bridge owns barge-in. A full-duplex model owns talk-over
+	* itself, and "deaf" there only means fed silence — so the default flips
+	* off on `turnTaking: 'model'`; an explicit setting is honored as written.
+	*/
+	firstTurnDeafness() {
+		return this.deps.options.deafness.ignoreUserAudioUntilFirstTurnDone ?? !this.modelOwnsTurnTaking();
+	}
+	/**
+	* The provider session behind every open response is being closed (handoff
+	* or reconnect): their tail marks may never come. Finalize them now, or
+	* `isPlaybackActive()` stays true for the rest of the call and everything
+	* gated on it — the hangup grace, REST transfers, guard rotation — wedges
+	* (field, Sept 2026). Whatever Twilio still holds plays out; no
+	* `playback.finished` is claimed for audio nobody confirmed.
+	*/
+	abandonOpenPlayback() {
+		if (this.tracker.abandonOpen().length === 0) return;
+		this.interruptions.onPlaybackEnded();
+		this.maybeCompleteHangup();
+		this.maybeRunPendingHandoff();
+	}
+	/**
+	* On a full-duplex provider the backend's transfer lands while the voice is
+	* still speaking the sentence that announces it, and the handoff is a
+	* close-and-reopen: performing it at once cuts that sentence, and the
+	* in-flight deltas kill the handoff hold before it starts (field, Sept
+	* 2026). Hold the transfer until the utterance has played out plus one
+	* sentence gap — a new utterance cancels the grace — capped so a voice that
+	* never stops still hands off.
+	*/
+	deferHandoff(target, reason) {
+		if (this.pendingHandoff) {
+			this.pendingHandoff.target = target;
+			this.pendingHandoff.reason = reason;
+			return;
+		}
+		const cap = setTimeout(() => {
+			this.timers.delete(cap);
+			const pending = this.pendingHandoff;
+			if (!pending) return;
+			this.log.warn("deferred handoff capped — the voice kept talking; handing off now");
+			this.clearPendingHandoff();
+			this.performHandoff(pending.target, pending.reason);
+		}, HANDOFF_DEFER_MAX_MS);
+		cap.unref?.();
+		this.timers.add(cap);
+		this.pendingHandoff = {
+			target,
+			reason,
+			grace: null,
+			cap
+		};
+		this.maybeRunPendingHandoff();
+	}
+	maybeRunPendingHandoff() {
+		const pending = this.pendingHandoff;
+		if (!pending || pending.grace) return;
+		if (this.generating || this.tracker.isPlaybackActive()) return;
+		const grace = setTimeout(() => {
+			this.timers.delete(grace);
+			const current = this.pendingHandoff;
+			if (!current) return;
+			current.grace = null;
+			if (this.generating || this.tracker.isPlaybackActive()) return;
+			this.clearPendingHandoff();
+			this.performHandoff(current.target, current.reason);
+		}, SENTENCE_GRACE_MS);
+		grace.unref?.();
+		this.timers.add(grace);
+		pending.grace = grace;
+	}
+	clearPendingHandoff() {
+		const pending = this.pendingHandoff;
+		if (!pending) return;
+		this.pendingHandoff = null;
+		for (const timer of [pending.grace, pending.cap]) {
+			if (!timer) continue;
+			clearTimeout(timer);
+			this.timers.delete(timer);
+		}
+	}
 	async performHandoff(target, reason) {
 		if (this.stateValue !== "active" || !this.provider) return;
 		if (target.id === this.activeAgentValue.id) return;
@@ -2305,6 +2424,7 @@ var CallSession = class extends TypedEmitter {
 				startDelayMs: hold.startDelayMs ?? 300
 			});
 			try {
+				this.abandonOpenPlayback();
 				await this.provider.close();
 				await this.provider.connect({
 					...this.buildProviderInit(),
@@ -2505,7 +2625,10 @@ var CallSession = class extends TypedEmitter {
 };
 const PREGREETING_MARK = "pre:greeting";
 /** Longer than the speech gate's quiet window plus the mark round trip (0.8 s + ~0.3 s). */
-const HANGUP_SENTENCE_GRACE_MS = 1500;
+/** 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;
 /** 400ms per frame — matches production burst-write implementations. */
 const PREGREETING_CHUNK_BYTES = 3200;
 function toError(value) {
@@ -2532,7 +2655,6 @@ const DEFAULT_SESSION_OPTIONS = {
 	greeting: { mode: "agent-initiates" },
 	interruptions: { enabled: true },
 	deafness: {
-		ignoreUserAudioUntilFirstTurnDone: true,
 		muteDuringToolExecution: true,
 		muteWhileAgentSpeaking: false
 	},

package/package.json

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