realtime-voice-agents 2.5.1 → 2.5.3

package/README.md

@@ -119,8 +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.
-- **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.
 
 ## Provider fallbacks

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);
@@ -681,17 +689,74 @@ 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;
-		} else close = gateEvent;
-		if (forwardId) this.emit("audio", {
+			this.armPlayoutLead();
+		}
+		if (forwardId) this.forwardAudio(delta, bytes.length / MULAW_BYTES_PER_MS, forwardId);
+		else this.preRoll = {
+			delta,
+			ms: bytes.length / MULAW_BYTES_PER_MS
+		};
+		if (pendingClose) 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: forwardId
+			responseId
 		});
-		if (close) this.endUtterance();
-		else if (this.gate.isOpen) this.armGateStall();
+	}
+	playoutLeadMs() {
+		return this.config.playoutLeadMs ?? 200;
 	}
 	handleBackendEvent(inner, delegationId) {
 		const type = inner.type ?? "";
@@ -722,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 });
@@ -729,6 +795,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 +824,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 +992,7 @@ function gptLive(options = {}) {
 		store: options.store,
 		extraSessionOptions: options.sessionOptions,
 		connectTimeoutMs: options.connectTimeoutMs,
+		playoutLeadMs: options.playoutLeadMs,
 		speechGate: options.speechGate,
 		transcriptGapMs: options.transcriptGapMs
 	};
@@ -938,6 +1008,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);
@@ -678,17 +686,74 @@ 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;
-		} else close = gateEvent;
-		if (forwardId) this.emit("audio", {
+			this.armPlayoutLead();
+		}
+		if (forwardId) this.forwardAudio(delta, bytes.length / MULAW_BYTES_PER_MS, forwardId);
+		else this.preRoll = {
+			delta,
+			ms: bytes.length / MULAW_BYTES_PER_MS
+		};
+		if (pendingClose) 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: forwardId
+			responseId
 		});
-		if (close) this.endUtterance();
-		else if (this.gate.isOpen) this.armGateStall();
+	}
+	playoutLeadMs() {
+		return this.config.playoutLeadMs ?? 200;
 	}
 	handleBackendEvent(inner, delegationId) {
 		const type = inner.type ?? "";
@@ -719,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 });
@@ -726,6 +792,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 +821,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 +989,7 @@ function gptLive(options = {}) {
 		store: options.store,
 		extraSessionOptions: options.sessionOptions,
 		connectTimeoutMs: options.connectTimeoutMs,
+		playoutLeadMs: options.playoutLeadMs,
 		speechGate: options.speechGate,
 		transcriptGapMs: options.transcriptGapMs
 	};
@@ -933,4 +1003,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

@@ -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.1",
+  "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",