realtime-voice-agents 2.5.0 → 2.5.2

package/README.md

@@ -119,7 +119,9 @@ 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.
+- **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.
 
 ## Provider fallbacks
@@ -341,7 +343,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 +357,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/gpt-live.cjs

@@ -310,6 +310,8 @@ const NON_RETRIABLE_CLOSE_CODES = /* @__PURE__ */ new Set([
 const APPEND_MAX_CHARS = 1200;
 const TRANSCRIPT_IDLE_EXTRA_MS = 300;
 const GATE_STALL_EXTRA_MS = 500;
+const DEFAULT_PLAYOUT_LEAD_MS = 200;
+const MULAW_BYTES_PER_MS = 8;
 const ACK_TYPES = {
 	"session.instructions.append": "session.instructions.appended",
 	"session.thinking.append": "session.thinking.appended",
@@ -346,6 +348,10 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
 	expiresAt = null;
 	gate;
 	gateStallTimer = null;
+	/** Deltas of the current utterance held until the playout lead has accumulated. */
+	lead = null;
+	/** The last idle delta: becomes the utterance's pre-roll when the gate opens. */
+	preRoll = null;
 	utteranceCounter = 0;
 	currentUtteranceId = null;
 	lastUtteranceId = null;
@@ -492,6 +498,8 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
 		this.inputTranscript.dispose();
 		this.outputTranscript.dispose();
 		this.clearGateStall();
+		this.lead = null;
+		this.preRoll = null;
 		if (!ws$2 || ws$2.readyState === ws.default.CLOSED) return;
 		await new Promise((resolve) => {
 			const timer = setTimeout(() => finish(), this.config.closeTimeoutMs ?? 3e3);
@@ -685,14 +693,63 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
 		for (const gateEvent of events) if (gateEvent.type === "open") {
 			this.beginUtterance();
 			forwardId = this.currentUtteranceId;
+			this.armPlayoutLead();
 		} else close = gateEvent;
-		if (forwardId) this.emit("audio", {
-			base64Mulaw: delta,
-			responseId: forwardId
-		});
+		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();
 		else if (this.gate.isOpen) this.armGateStall();
 	}
+	/**
+	* The stream is real-time paced, so Twilio's buffer never runs ahead of
+	* playout and every delivery hiccup between the model, this server and
+	* Twilio is an audible gap (field, Sept 2026: "slightly choppy"). Hold the
+	* first `playoutLeadMs` of each utterance — the last idle delta included —
+	* then flush and stream through: Twilio keeps that much cushion for the
+	* rest of the utterance, at the cost of that much latency on its first word.
+	*/
+	armPlayoutLead() {
+		if (this.playoutLeadMs() <= 0) {
+			this.preRoll = null;
+			return;
+		}
+		this.lead = {
+			pending: [],
+			pendingMs: 0
+		};
+		if (this.preRoll) {
+			this.lead.pending.push(this.preRoll.delta);
+			this.lead.pendingMs += this.preRoll.ms;
+			this.preRoll = null;
+		}
+	}
+	forwardAudio(delta, ms, responseId) {
+		if (!this.lead) {
+			this.emit("audio", {
+				base64Mulaw: delta,
+				responseId
+			});
+			return;
+		}
+		this.lead.pending.push(delta);
+		this.lead.pendingMs += ms;
+		if (this.lead.pendingMs >= this.playoutLeadMs()) this.flushPlayoutLead(responseId);
+	}
+	flushPlayoutLead(responseId) {
+		const lead = this.lead;
+		if (!lead) return;
+		this.lead = null;
+		for (const delta of lead.pending) this.emit("audio", {
+			base64Mulaw: delta,
+			responseId
+		});
+	}
+	playoutLeadMs() {
+		return this.config.playoutLeadMs ?? 200;
+	}
 	handleBackendEvent(inner, delegationId) {
 		const type = inner.type ?? "";
 		if (type === "response.output_item.done" && inner.item?.type === "function_call") {
@@ -729,6 +786,7 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
 	endUtterance() {
 		this.clearGateStall();
 		const id = this.currentUtteranceId;
+		if (id) this.flushPlayoutLead(id);
 		this.currentUtteranceId = null;
 		if (id) this.emit("responseDone", { responseId: id });
 	}
@@ -757,6 +815,8 @@ var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimePro
 	resetUtteranceState() {
 		this.clearGateStall();
 		this.gate.close();
+		this.lead = null;
+		this.preRoll = null;
 		this.currentUtteranceId = null;
 		this.lastUtteranceId = null;
 		this.seenCalls.clear();
@@ -923,6 +983,7 @@ function gptLive(options = {}) {
 		store: options.store,
 		extraSessionOptions: options.sessionOptions,
 		connectTimeoutMs: options.connectTimeoutMs,
+		playoutLeadMs: options.playoutLeadMs,
 		speechGate: options.speechGate,
 		transcriptGapMs: options.transcriptGapMs
 	};
@@ -938,6 +999,7 @@ function gptLive(options = {}) {
 //#endregion
 exports.DEFAULT_GATE_QUIET_MS = DEFAULT_GATE_QUIET_MS;
 exports.DEFAULT_GATE_THRESHOLD_RMS = DEFAULT_GATE_THRESHOLD_RMS;
+exports.DEFAULT_PLAYOUT_LEAD_MS = DEFAULT_PLAYOUT_LEAD_MS;
 exports.GPT_LIVE_AUDIO_FORMAT = GPT_LIVE_AUDIO_FORMAT;
 exports.GPT_LIVE_DEFAULT_BACKEND_MODEL = GPT_LIVE_DEFAULT_BACKEND_MODEL;
 exports.GPT_LIVE_DEFAULT_BASE_URL = GPT_LIVE_DEFAULT_BASE_URL;

package/dist/gpt-live.d.cts

@@ -126,6 +126,14 @@ interface GptLiveProviderConfig {
   connectTimeoutMs?: number;
   /** How long `close()` waits for `session.closed` (final usage) before dropping the socket. Default 3000. */
   closeTimeoutMs?: number;
+  /**
+   * Audio held back at the start of each utterance before forwarding begins,
+   * so Twilio keeps that much cushion against delivery jitter (the stream is
+   * real-time paced — without it any hiccup is an audible gap). The last idle
+   * delta before the onset is included, so soft onsets are not clipped.
+   * Default 200; 0 forwards every delta as it arrives.
+   */
+  playoutLeadMs?: number;
   /** Speech gate tuning (utterance boundaries synthesized from the audio). */
   speechGate?: SpeechGateOptions;
   /** Session-timeline gap that splits transcript fragments into turns. Default 800. */
@@ -137,6 +145,7 @@ interface GptLiveProviderConfig {
   ackTimeoutMs?: number;
   providerName?: string;
 }
+declare const DEFAULT_PLAYOUT_LEAD_MS = 200;
 declare class GptLiveProvider extends BaseRealtimeProvider {
   readonly name: string;
   readonly capabilities: ProviderCapabilities;
@@ -152,6 +161,10 @@ declare class GptLiveProvider extends BaseRealtimeProvider {
   expiresAt: number | null;
   private readonly gate;
   private gateStallTimer;
+  /** Deltas of the current utterance held until the playout lead has accumulated. */
+  private lead;
+  /** The last idle delta: becomes the utterance's pre-roll when the gate opens. */
+  private preRoll;
   private utteranceCounter;
   private currentUtteranceId;
   private lastUtteranceId;
@@ -192,6 +205,18 @@ declare class GptLiveProvider extends BaseRealtimeProvider {
   updateSession(patch: Partial<ProviderSessionInit>, options?: SessionUpdateOptions): Promise<boolean>;
   private handleEvent;
   private handleOutputAudio;
+  /**
+   * The stream is real-time paced, so Twilio's buffer never runs ahead of
+   * playout and every delivery hiccup between the model, this server and
+   * Twilio is an audible gap (field, Sept 2026: "slightly choppy"). Hold the
+   * first `playoutLeadMs` of each utterance — the last idle delta included —
+   * then flush and stream through: Twilio keeps that much cushion for the
+   * rest of the utterance, at the cost of that much latency on its first word.
+   */
+  private armPlayoutLead;
+  private forwardAudio;
+  private flushPlayoutLead;
+  private playoutLeadMs;
   private handleBackendEvent;
   private beginUtterance;
   private endUtterance;
@@ -244,6 +269,14 @@ interface GptLiveOptions {
   /** Provider-native `session.start` fields, deep-merged last. The schema is strict: an unknown field rejects the session. */
   sessionOptions?: Record<string, unknown>;
   connectTimeoutMs?: number;
+  /**
+   * Cushion held at the start of each utterance before audio is forwarded to
+   * Twilio. The model streams at exactly real-time pace, so without it any
+   * delivery hiccup is an audible gap; with it Twilio stays that far ahead of
+   * playout. Costs the same amount of latency on each turn's first word.
+   * Default 200; 0 forwards every delta as it arrives.
+   */
+  playoutLeadMs?: number;
   /** Speech gate tuning — utterance boundaries synthesized from the continuous output stream. */
   speechGate?: SpeechGateOptions;
   /** Session-timeline gap that splits transcript fragments into turns. Default 800. */
@@ -258,4 +291,4 @@ interface GptLiveOptions {
  */
 declare function gptLive(options?: GptLiveOptions): ProviderFactory;
 //#endregion
-export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, type GptLiveDelegationOptions, GptLiveOptions, GptLiveProvider, type GptLiveProviderConfig, type GptLiveSessionConfig, GptLiveVoice, SpeechGate, type SpeechGateOptions, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };
+export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, DEFAULT_PLAYOUT_LEAD_MS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, type GptLiveDelegationOptions, GptLiveOptions, GptLiveProvider, type GptLiveProviderConfig, type GptLiveSessionConfig, GptLiveVoice, SpeechGate, type SpeechGateOptions, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };

package/dist/gpt-live.d.mts

@@ -126,6 +126,14 @@ interface GptLiveProviderConfig {
   connectTimeoutMs?: number;
   /** How long `close()` waits for `session.closed` (final usage) before dropping the socket. Default 3000. */
   closeTimeoutMs?: number;
+  /**
+   * Audio held back at the start of each utterance before forwarding begins,
+   * so Twilio keeps that much cushion against delivery jitter (the stream is
+   * real-time paced — without it any hiccup is an audible gap). The last idle
+   * delta before the onset is included, so soft onsets are not clipped.
+   * Default 200; 0 forwards every delta as it arrives.
+   */
+  playoutLeadMs?: number;
   /** Speech gate tuning (utterance boundaries synthesized from the audio). */
   speechGate?: SpeechGateOptions;
   /** Session-timeline gap that splits transcript fragments into turns. Default 800. */
@@ -137,6 +145,7 @@ interface GptLiveProviderConfig {
   ackTimeoutMs?: number;
   providerName?: string;
 }
+declare const DEFAULT_PLAYOUT_LEAD_MS = 200;
 declare class GptLiveProvider extends BaseRealtimeProvider {
   readonly name: string;
   readonly capabilities: ProviderCapabilities;
@@ -152,6 +161,10 @@ declare class GptLiveProvider extends BaseRealtimeProvider {
   expiresAt: number | null;
   private readonly gate;
   private gateStallTimer;
+  /** Deltas of the current utterance held until the playout lead has accumulated. */
+  private lead;
+  /** The last idle delta: becomes the utterance's pre-roll when the gate opens. */
+  private preRoll;
   private utteranceCounter;
   private currentUtteranceId;
   private lastUtteranceId;
@@ -192,6 +205,18 @@ declare class GptLiveProvider extends BaseRealtimeProvider {
   updateSession(patch: Partial<ProviderSessionInit>, options?: SessionUpdateOptions): Promise<boolean>;
   private handleEvent;
   private handleOutputAudio;
+  /**
+   * The stream is real-time paced, so Twilio's buffer never runs ahead of
+   * playout and every delivery hiccup between the model, this server and
+   * Twilio is an audible gap (field, Sept 2026: "slightly choppy"). Hold the
+   * first `playoutLeadMs` of each utterance — the last idle delta included —
+   * then flush and stream through: Twilio keeps that much cushion for the
+   * rest of the utterance, at the cost of that much latency on its first word.
+   */
+  private armPlayoutLead;
+  private forwardAudio;
+  private flushPlayoutLead;
+  private playoutLeadMs;
   private handleBackendEvent;
   private beginUtterance;
   private endUtterance;
@@ -244,6 +269,14 @@ interface GptLiveOptions {
   /** Provider-native `session.start` fields, deep-merged last. The schema is strict: an unknown field rejects the session. */
   sessionOptions?: Record<string, unknown>;
   connectTimeoutMs?: number;
+  /**
+   * Cushion held at the start of each utterance before audio is forwarded to
+   * Twilio. The model streams at exactly real-time pace, so without it any
+   * delivery hiccup is an audible gap; with it Twilio stays that far ahead of
+   * playout. Costs the same amount of latency on each turn's first word.
+   * Default 200; 0 forwards every delta as it arrives.
+   */
+  playoutLeadMs?: number;
   /** Speech gate tuning — utterance boundaries synthesized from the continuous output stream. */
   speechGate?: SpeechGateOptions;
   /** Session-timeline gap that splits transcript fragments into turns. Default 800. */
@@ -258,4 +291,4 @@ interface GptLiveOptions {
  */
 declare function gptLive(options?: GptLiveOptions): ProviderFactory;
 //#endregion
-export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, type GptLiveDelegationOptions, GptLiveOptions, GptLiveProvider, type GptLiveProviderConfig, type GptLiveSessionConfig, GptLiveVoice, SpeechGate, type SpeechGateOptions, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };
+export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, DEFAULT_PLAYOUT_LEAD_MS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, type GptLiveDelegationOptions, GptLiveOptions, GptLiveProvider, type GptLiveProviderConfig, type GptLiveSessionConfig, GptLiveVoice, SpeechGate, type SpeechGateOptions, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };

package/dist/gpt-live.mjs

@@ -307,6 +307,8 @@ const NON_RETRIABLE_CLOSE_CODES = /* @__PURE__ */ new Set([
 const APPEND_MAX_CHARS = 1200;
 const TRANSCRIPT_IDLE_EXTRA_MS = 300;
 const GATE_STALL_EXTRA_MS = 500;
+const DEFAULT_PLAYOUT_LEAD_MS = 200;
+const MULAW_BYTES_PER_MS = 8;
 const ACK_TYPES = {
 	"session.instructions.append": "session.instructions.appended",
 	"session.thinking.append": "session.thinking.appended",
@@ -343,6 +345,10 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
 	expiresAt = null;
 	gate;
 	gateStallTimer = null;
+	/** Deltas of the current utterance held until the playout lead has accumulated. */
+	lead = null;
+	/** The last idle delta: becomes the utterance's pre-roll when the gate opens. */
+	preRoll = null;
 	utteranceCounter = 0;
 	currentUtteranceId = null;
 	lastUtteranceId = null;
@@ -489,6 +495,8 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
 		this.inputTranscript.dispose();
 		this.outputTranscript.dispose();
 		this.clearGateStall();
+		this.lead = null;
+		this.preRoll = null;
 		if (!ws || ws.readyState === WebSocket$1.CLOSED) return;
 		await new Promise((resolve) => {
 			const timer = setTimeout(() => finish(), this.config.closeTimeoutMs ?? 3e3);
@@ -682,14 +690,63 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
 		for (const gateEvent of events) if (gateEvent.type === "open") {
 			this.beginUtterance();
 			forwardId = this.currentUtteranceId;
+			this.armPlayoutLead();
 		} else close = gateEvent;
-		if (forwardId) this.emit("audio", {
-			base64Mulaw: delta,
-			responseId: forwardId
-		});
+		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();
 		else if (this.gate.isOpen) this.armGateStall();
 	}
+	/**
+	* The stream is real-time paced, so Twilio's buffer never runs ahead of
+	* playout and every delivery hiccup between the model, this server and
+	* Twilio is an audible gap (field, Sept 2026: "slightly choppy"). Hold the
+	* first `playoutLeadMs` of each utterance — the last idle delta included —
+	* then flush and stream through: Twilio keeps that much cushion for the
+	* rest of the utterance, at the cost of that much latency on its first word.
+	*/
+	armPlayoutLead() {
+		if (this.playoutLeadMs() <= 0) {
+			this.preRoll = null;
+			return;
+		}
+		this.lead = {
+			pending: [],
+			pendingMs: 0
+		};
+		if (this.preRoll) {
+			this.lead.pending.push(this.preRoll.delta);
+			this.lead.pendingMs += this.preRoll.ms;
+			this.preRoll = null;
+		}
+	}
+	forwardAudio(delta, ms, responseId) {
+		if (!this.lead) {
+			this.emit("audio", {
+				base64Mulaw: delta,
+				responseId
+			});
+			return;
+		}
+		this.lead.pending.push(delta);
+		this.lead.pendingMs += ms;
+		if (this.lead.pendingMs >= this.playoutLeadMs()) this.flushPlayoutLead(responseId);
+	}
+	flushPlayoutLead(responseId) {
+		const lead = this.lead;
+		if (!lead) return;
+		this.lead = null;
+		for (const delta of lead.pending) this.emit("audio", {
+			base64Mulaw: delta,
+			responseId
+		});
+	}
+	playoutLeadMs() {
+		return this.config.playoutLeadMs ?? 200;
+	}
 	handleBackendEvent(inner, delegationId) {
 		const type = inner.type ?? "";
 		if (type === "response.output_item.done" && inner.item?.type === "function_call") {
@@ -726,6 +783,7 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
 	endUtterance() {
 		this.clearGateStall();
 		const id = this.currentUtteranceId;
+		if (id) this.flushPlayoutLead(id);
 		this.currentUtteranceId = null;
 		if (id) this.emit("responseDone", { responseId: id });
 	}
@@ -754,6 +812,8 @@ var GptLiveProvider = class extends BaseRealtimeProvider {
 	resetUtteranceState() {
 		this.clearGateStall();
 		this.gate.close();
+		this.lead = null;
+		this.preRoll = null;
 		this.currentUtteranceId = null;
 		this.lastUtteranceId = null;
 		this.seenCalls.clear();
@@ -920,6 +980,7 @@ function gptLive(options = {}) {
 		store: options.store,
 		extraSessionOptions: options.sessionOptions,
 		connectTimeoutMs: options.connectTimeoutMs,
+		playoutLeadMs: options.playoutLeadMs,
 		speechGate: options.speechGate,
 		transcriptGapMs: options.transcriptGapMs
 	};
@@ -933,4 +994,4 @@ function gptLive(options = {}) {
 	};
 }
 //#endregion
-export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, GptLiveProvider, SpeechGate, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };
+export { DEFAULT_GATE_QUIET_MS, DEFAULT_GATE_THRESHOLD_RMS, DEFAULT_PLAYOUT_LEAD_MS, GPT_LIVE_AUDIO_FORMAT, GPT_LIVE_DEFAULT_BACKEND_MODEL, GPT_LIVE_DEFAULT_BASE_URL, GPT_LIVE_DEFAULT_MODEL, GPT_LIVE_DEFAULT_VOICE, GPT_LIVE_KEY_ENV_VARS, GPT_LIVE_VOICES, GptLiveProvider, SpeechGate, buildDelegation, buildHistoryItems, buildSessionStart, gptLive, splitForAppend };

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.2",
   "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",