realtime-voice-agents 2.3.0 → 2.5.0

package/dist/gpt-live.cjs

@@ -0,0 +1,954 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rolldown_runtime = require("./rolldown-runtime-VH7oDXx4.cjs");
+const require_BaseRealtimeProvider = require("./BaseRealtimeProvider-ZfFzijdr.cjs");
+const require_mulaw = require("./mulaw-DLUObjdP.cjs");
+const require_env = require("./env-DSnGaERV.cjs");
+const require_OpenAICompatibleProvider = require("./OpenAICompatibleProvider-j2Nza2q2.cjs");
+let ws = require("ws");
+ws = require_rolldown_runtime.__toESM(ws, 1);
+//#region src/providers/gpt-live/session-config.ts
+/**
+* `session.start` construction for GPT-Live (`/v1/live/sessions`).
+*
+* The session object is a STRICT schema: an unknown field rejects the whole
+* start with `unknown_parameter` (field-verified Sept 2026), so every key
+* here is a documented one and `providerOptions` / `extraSessionOptions`
+* are deep-merged last as a deliberate escape hatch. Wire facts baked in:
+* - one audio format for both directions, `{ type: 'audio/pcmu', rate: 8000 }`
+*   (Twilio's wire format — no transcoding)
+* - instructions, voice, format and history are immutable after start
+* - tools do not live on the voice model: they are `delegation.responses.tools`
+*   for the backend Responses model that reasons and calls them
+* - history is `input`: ≤ 128 text messages / ≤ 8,192 rendered tokens
+*/
+const GPT_LIVE_DEFAULT_BACKEND_MODEL = "gpt-5.6-terra";
+const GPT_LIVE_AUDIO_FORMAT = {
+	type: "audio/pcmu",
+	rate: 8e3
+};
+const HISTORY_MAX_MESSAGES = 128;
+/** ≈ 8,192 tokens at a conservative 2.5 chars/token (Hebrew and other dense scripts). */
+const HISTORY_MAX_CHARS = 2e4;
+function toBackendTool(tool) {
+	return {
+		type: "function",
+		name: tool.name,
+		description: tool.description ?? "",
+		parameters: tool.parameters
+	};
+}
+function buildDelegation(tools, options = {}) {
+	const responses = {
+		model: options.model ?? "gpt-5.6-terra",
+		tools: [...(tools ?? []).map(toBackendTool), ...options.extraTools ?? []],
+		tool_choice: options.toolChoice ?? "auto"
+	};
+	if (options.instructions !== void 0) responses.instructions = options.instructions;
+	if (options.parallelToolCalls !== void 0) responses.parallel_tool_calls = options.parallelToolCalls;
+	if (options.maxOutputTokens !== void 0) responses.max_output_tokens = options.maxOutputTokens;
+	if (options.reasoning !== void 0) responses.reasoning = options.reasoning;
+	if (options.serviceTier !== void 0) responses.service_tier = options.serviceTier;
+	if (options.text !== void 0) responses.text = options.text;
+	return {
+		type: "responses",
+		responses
+	};
+}
+/**
+* History → `input` items, newest-first trimming to the API bounds. A leading
+* `developer` entry (the engine's continuation note) is pinned so trimming
+* never drops the context that explains the rest.
+*/
+function buildHistoryItems(history, limits = {}) {
+	if (!history || history.length === 0) return {
+		items: [],
+		dropped: 0
+	};
+	const maxMessages = limits.maxMessages ?? HISTORY_MAX_MESSAGES;
+	const maxChars = limits.maxChars ?? HISTORY_MAX_CHARS;
+	const pinned = history[0].role === "developer" ? [history[0]] : [];
+	const rest = history.slice(pinned.length);
+	let chars = pinned.reduce((n, e) => n + e.text.length, 0);
+	const kept = [];
+	for (let i = rest.length - 1; i >= 0; i--) {
+		const entry = rest[i];
+		if (kept.length + pinned.length >= maxMessages) break;
+		if (chars + entry.text.length > maxChars) break;
+		chars += entry.text.length;
+		kept.unshift(entry);
+	}
+	return {
+		items: [...pinned, ...kept].map((entry) => ({
+			type: "message",
+			role: entry.role,
+			content: [{
+				type: entry.role === "assistant" ? "output_text" : "input_text",
+				text: entry.text
+			}]
+		})),
+		dropped: rest.length - kept.length
+	};
+}
+function buildSessionStart(init, config, eventId, model) {
+	const { items, dropped } = buildHistoryItems(init.history, {
+		maxMessages: config.historyMaxMessages,
+		maxChars: config.historyMaxChars
+	});
+	const voice = init.voice ?? config.defaultVoice;
+	let session = {
+		model,
+		instructions: init.instructions,
+		audio: {
+			format: { ...GPT_LIVE_AUDIO_FORMAT },
+			...voice ? { output: { voice } } : {}
+		},
+		delegation: buildDelegation(init.tools, config.delegation),
+		...items.length ? { input: items } : {},
+		...config.store ? { store: true } : {}
+	};
+	session = require_BaseRealtimeProvider.deepMerge(session, init.providerOptions);
+	session = require_BaseRealtimeProvider.deepMerge(session, config.extraSessionOptions);
+	return {
+		frame: {
+			type: "session.start",
+			event_id: eventId,
+			session
+		},
+		droppedHistory: dropped
+	};
+}
+//#endregion
+//#region src/providers/gpt-live/speech-gate.ts
+/**
+* Speech gate for full-duplex output streams.
+*
+* GPT-Live streams assistant audio continuously and in real time — silence
+* included (≈100 ms μ-law deltas, digital 0xFF while the model is quiet) —
+* and the wire has no response boundaries: no response.created, no
+* output_audio.done. The engine's playback tracking, tool timing and hangup
+* watchdog all key off `responseStarted` / `responseDone`, so this gate
+* synthesizes utterances from the audio itself: one opens on the first loud
+* 20 ms sub-frame and closes after `quietMs` of quiet AUDIO. Quiet is
+* measured on the stream's own clock (bytes received), never wall-clock, so
+* a stalled socket cannot fake a finished utterance and tests can script
+* silence instantly. Field numbers (Sept 2026, 8 kHz μ-law): quiet frames
+* p99 ≈ −50 dBFS, speech p05 ≈ −44 dBFS; LiveKit and Pipecat both close at
+* 0.8 s.
+*/
+const DEFAULT_GATE_THRESHOLD_RMS = .004;
+const DEFAULT_GATE_QUIET_MS = 800;
+const SUBFRAME_BYTES = 160;
+const BYTES_PER_MS = 8;
+var SpeechGate = class {
+	threshold;
+	quietLimitMs;
+	open = false;
+	quietMs = 0;
+	utteranceMs = 0;
+	constructor(options = {}) {
+		this.threshold = options.thresholdRms ?? .004;
+		this.quietLimitMs = options.quietMs ?? 800;
+	}
+	get isOpen() {
+		return this.open;
+	}
+	/** Feed one output delta; returns the transitions it caused, in order. */
+	feed(bytes) {
+		const events = [];
+		for (let offset = 0; offset < bytes.length; offset += SUBFRAME_BYTES) {
+			const frame = bytes.subarray(offset, Math.min(offset + SUBFRAME_BYTES, bytes.length));
+			const frameMs = frame.length / BYTES_PER_MS;
+			if (isSpeech(frame, this.threshold)) {
+				if (!this.open) {
+					this.open = true;
+					this.utteranceMs = 0;
+					events.push({ type: "open" });
+				}
+				this.quietMs = 0;
+				this.utteranceMs += frameMs;
+			} else if (this.open) {
+				this.quietMs += frameMs;
+				this.utteranceMs += frameMs;
+				if (this.quietMs >= this.quietLimitMs) {
+					events.push({
+						type: "close",
+						utteranceMs: this.utteranceMs - this.quietMs
+					});
+					this.open = false;
+					this.quietMs = 0;
+					this.utteranceMs = 0;
+				}
+			}
+		}
+		return events;
+	}
+	/** Force-close an open utterance (stream stalled, session closing). */
+	close() {
+		if (!this.open) return null;
+		const event = {
+			type: "close",
+			utteranceMs: this.utteranceMs - this.quietMs
+		};
+		this.open = false;
+		this.quietMs = 0;
+		this.utteranceMs = 0;
+		return event;
+	}
+};
+/** μ-law digital zero is 0xFF (some encoders emit 0x7F for negative zero). */
+function isDigitalSilence(bytes) {
+	for (let i = 0; i < bytes.length; i++) {
+		const b = bytes[i];
+		if (b !== 255 && b !== 127) return false;
+	}
+	return true;
+}
+function isSpeech(frame, threshold) {
+	if (frame.length === 0 || isDigitalSilence(frame)) return false;
+	const pcm = require_mulaw.mulawToPcm16(frame);
+	let acc = 0;
+	for (let i = 0; i < pcm.length; i++) {
+		const v = pcm[i] / 32768;
+		acc += v * v;
+	}
+	return Math.sqrt(acc / pcm.length) >= threshold;
+}
+//#endregion
+//#region src/providers/gpt-live/transcript-grouper.ts
+var TranscriptGrouper = class {
+	options;
+	current = null;
+	idleTimer = null;
+	constructor(options) {
+		this.options = options;
+	}
+	push(delta, startMs, endMs) {
+		if (this.current && startMs - this.current.endMs > this.options.gapMs) this.flush();
+		if (!this.current) this.current = {
+			text: "",
+			startMs,
+			endMs,
+			tag: this.options.tagFor?.()
+		};
+		this.current.text += delta;
+		this.current.endMs = Math.max(this.current.endMs, endMs);
+		this.armIdle();
+	}
+	/** Close the open turn now (session ending, utterance boundary reached). */
+	flush() {
+		this.clearIdle();
+		const turn = this.current;
+		this.current = null;
+		if (!turn) return;
+		const text = turn.text.trim();
+		if (text.length === 0) return;
+		this.options.onTurn({
+			...turn,
+			text
+		});
+	}
+	dispose() {
+		this.clearIdle();
+		this.current = null;
+	}
+	armIdle() {
+		this.clearIdle();
+		this.idleTimer = setTimeout(() => {
+			this.idleTimer = null;
+			this.flush();
+		}, this.options.idleMs);
+		this.idleTimer.unref?.();
+	}
+	clearIdle() {
+		if (this.idleTimer) {
+			clearTimeout(this.idleTimer);
+			this.idleTimer = null;
+		}
+	}
+};
+//#endregion
+//#region src/providers/gpt-live/GptLiveProvider.ts
+/**
+* GPT-Live provider (`/v1/live/sessions`, raw WebSocket) — OpenAI's
+* full-duplex speech-to-speech model. A different API from Realtime, not a
+* new Realtime model: its own handshake (`session.start` → `session.started`),
+* its own events, and a different division of labour that this provider
+* translates into the engine's normalized contract:
+*
+* - **Turn-taking is the model's.** It listens while it speaks and stops on
+*   its own when the caller talks. There is no VAD config, no cancel, no
+*   truncate, no speech_started/stopped; `capabilities.turnTaking: 'model'`
+*   tells the engine to keep its hands off (see parity tests).
+* - **Output is a continuous real-time stream, silence included** (100 ms
+*   μ-law deltas, digital 0xFF when quiet). Response boundaries are
+*   synthesized by a speech gate on the audio itself (`speech-gate.ts`);
+*   silence between utterances is not forwarded.
+* - **The backend does the thinking.** Tools are declared on a Responses
+*   model (`delegation.responses`), calls arrive wrapped in `response.event`
+*   envelopes, results go back as `response.item.create` + one
+*   `response.create`. The voice keeps talking meanwhile
+*   (`capabilities.decoupledBackend`).
+* - **Text reaches the model only through appends** (≤ 500 tokens each):
+*   instructions (policy), thinking (quiet context), commentary (say this).
+*   `createResponse({ instructions })` maps to commentary — field-tested as
+*   the only append that reliably produces speech on demand (Sept 2026).
+* - **Instructions, voice and history are immutable after start** — handoffs
+*   reconnect and seed the attributed transcript via `session.input`
+*   (`capabilities.startupHistory`).
+* - **Billing is per second of session**, reported as cumulative
+*   `session.usage.updated` ticks; `close()` sends `session.close` and waits
+*   for `session.closed` so the final usage is confirmed.
+*/
+const GPT_LIVE_DEFAULT_BASE_URL = "wss://api.openai.com/v1/live/sessions";
+const NON_RETRIABLE_CLOSE_CODES = /* @__PURE__ */ new Set([
+	1002,
+	1003,
+	1007,
+	1008
+]);
+/** Appends are capped at 500 tokens; split conservatively (dense scripts run ~2.5 chars/token). */
+const APPEND_MAX_CHARS = 1200;
+const TRANSCRIPT_IDLE_EXTRA_MS = 300;
+const GATE_STALL_EXTRA_MS = 500;
+const ACK_TYPES = {
+	"session.instructions.append": "session.instructions.appended",
+	"session.thinking.append": "session.thinking.appended",
+	"session.commentary.append": "session.commentary.appended",
+	"session.update": "session.updated",
+	"session.input_audio.mute": "session.input_audio.muted",
+	"session.input_audio.unmute": "session.input_audio.unmuted"
+};
+let eventSeq = 0;
+const nextEventId = (prefix) => `${prefix}_${++eventSeq}`;
+var GptLiveProvider = class extends require_BaseRealtimeProvider.BaseRealtimeProvider {
+	name;
+	capabilities = {
+		truncate: false,
+		sessionUpdate: false,
+		voiceChangeMidSession: false,
+		transcodeRequired: false,
+		resumption: false,
+		agentTranscriptDeltas: true,
+		vadInterruptControl: false,
+		turnTaking: "model",
+		startupHistory: true,
+		decoupledBackend: true
+	};
+	config;
+	logger;
+	ws = null;
+	ready = false;
+	intentionalClose = false;
+	sessionInit = null;
+	/** Server-assigned session id (sideband attach, forking, recording download). */
+	sessionId = null;
+	/** Unix seconds at which the server expires the session (120 min at launch). */
+	expiresAt = null;
+	gate;
+	gateStallTimer = null;
+	utteranceCounter = 0;
+	currentUtteranceId = null;
+	lastUtteranceId = null;
+	inputTranscript;
+	outputTranscript;
+	acks = /* @__PURE__ */ new Map();
+	seenCalls = /* @__PURE__ */ new Set();
+	sessionClosed = null;
+	closeListeners = [];
+	constructor(config, logger = require_BaseRealtimeProvider.noopLogger) {
+		super();
+		this.config = config;
+		this.logger = logger;
+		this.name = config.providerName ?? "gpt-live";
+		this.gate = new SpeechGate(config.speechGate);
+		const gapMs = config.transcriptGapMs ?? 800;
+		this.inputTranscript = new TranscriptGrouper({
+			gapMs,
+			idleMs: gapMs + TRANSCRIPT_IDLE_EXTRA_MS,
+			onTurn: (turn) => this.emit("userTranscript", { text: turn.text })
+		});
+		this.outputTranscript = new TranscriptGrouper({
+			gapMs,
+			idleMs: gapMs + TRANSCRIPT_IDLE_EXTRA_MS,
+			tagFor: () => this.currentUtteranceId ?? this.lastUtteranceId ?? void 0,
+			onTurn: (turn) => this.emit("agentTranscript", {
+				responseId: turn.tag ?? "",
+				text: turn.text
+			})
+		});
+	}
+	get isConnected() {
+		return this.ready && this.ws?.readyState === ws.default.OPEN;
+	}
+	async connect(init) {
+		if (this.ws) await this.close();
+		this.sessionInit = init;
+		this.intentionalClose = false;
+		this.ready = false;
+		this.sessionClosed = null;
+		this.sessionId = null;
+		this.expiresAt = null;
+		this.resetUtteranceState();
+		if (init.vad !== void 0 || init.transcription !== void 0 || init.temperature !== void 0) this.logger.debug("gpt-live: vad/transcription/temperature are model-owned and ignored");
+		const startId = nextEventId("start");
+		const { frame, droppedHistory } = buildSessionStart(init, this.sessionConfig(), startId, this.config.model);
+		if (droppedHistory > 0) this.logger.warn("gpt-live: startup history trimmed to the API bounds", { dropped: droppedHistory });
+		const ws$1 = new ws.default(this.config.baseUrl ?? "wss://api.openai.com/v1/live/sessions", {
+			headers: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				...this.config.headers
+			},
+			perMessageDeflate: false
+		});
+		this.ws = ws$1;
+		await new Promise((resolve, reject) => {
+			const timeoutMs = this.config.connectTimeoutMs ?? 15e3;
+			const timer = setTimeout(() => fail(/* @__PURE__ */ new Error(`${this.name} session not started within ${timeoutMs}ms`)), timeoutMs);
+			timer.unref?.();
+			let settled = false;
+			const fail = (error) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				try {
+					ws$1.close();
+				} catch {}
+				reject(error);
+			};
+			ws$1.on("unexpected-response", (_request, response) => {
+				let body = "";
+				response.setEncoding("utf8");
+				response.on("data", (chunk) => {
+					if (body.length < 512) body += chunk;
+				});
+				response.on("end", () => {
+					const detail = body.trim().slice(0, 500);
+					this.logger.error("provider rejected the WebSocket upgrade", {
+						status: response.statusCode,
+						body: detail
+					});
+					fail(/* @__PURE__ */ new Error(`${this.name} rejected the WebSocket upgrade: HTTP ${response.statusCode}${detail ? ` — ${detail}` : ""}`));
+				});
+			});
+			ws$1.on("open", () => {
+				this.emit("open");
+				this.send(frame);
+			});
+			ws$1.on("message", (raw) => {
+				const event = this.parseEvent(raw);
+				if (!event) return;
+				if (!settled) {
+					if (event.type === "session.started") {
+						settled = true;
+						clearTimeout(timer);
+						this.sessionId = event.session?.id ?? null;
+						this.expiresAt = typeof event.session?.expires_at === "number" ? event.session.expires_at : null;
+						this.ready = true;
+						this.logger.info("gpt-live session started", {
+							sessionId: this.sessionId,
+							expiresAt: this.expiresAt ? (/* @__PURE__ */ new Date(this.expiresAt * 1e3)).toISOString() : void 0
+						});
+						resolve();
+						return;
+					}
+					if (event.type === "error") {
+						fail(/* @__PURE__ */ new Error(`${this.name} session.start rejected: ${JSON.stringify(event.error ?? event)}`));
+						return;
+					}
+					return;
+				}
+				this.handleEvent(event);
+			});
+			ws$1.on("error", (error) => {
+				const err = error instanceof Error ? error : new Error(String(error));
+				if (!settled) fail(err);
+				else this.emit("error", err);
+			});
+			ws$1.on("close", (code, reasonBuf) => {
+				const reason = reasonBuf?.toString();
+				this.ready = false;
+				this.failPendingAcks();
+				this.finishUtteranceOnClose();
+				const listeners = this.closeListeners;
+				this.closeListeners = [];
+				for (const listener of listeners) listener();
+				if (!settled) {
+					fail(/* @__PURE__ */ new Error(`${this.name} socket closed during setup (${code} ${reason ?? ""})`));
+					return;
+				}
+				this.emit("close", {
+					code,
+					reason,
+					retriable: this.isRetriableClose(code)
+				});
+			});
+		});
+	}
+	async close() {
+		this.intentionalClose = true;
+		this.ready = false;
+		const ws$2 = this.ws;
+		this.ws = null;
+		this.inputTranscript.dispose();
+		this.outputTranscript.dispose();
+		this.clearGateStall();
+		if (!ws$2 || ws$2.readyState === ws.default.CLOSED) return;
+		await new Promise((resolve) => {
+			const timer = setTimeout(() => finish(), this.config.closeTimeoutMs ?? 3e3);
+			timer.unref?.();
+			let done = false;
+			const finish = () => {
+				if (done) return;
+				done = true;
+				clearTimeout(timer);
+				try {
+					if (ws$2.readyState === ws.default.OPEN || ws$2.readyState === ws.default.CONNECTING) ws$2.close(1e3);
+				} catch {}
+				setTimeout(() => {
+					try {
+						ws$2.terminate();
+					} catch {}
+				}, 1e3).unref?.();
+				resolve();
+			};
+			this.closeListeners.push(finish);
+			if (ws$2.readyState === ws.default.OPEN) try {
+				ws$2.send(JSON.stringify({
+					type: "session.close",
+					event_id: nextEventId("close")
+				}));
+			} catch {
+				finish();
+			}
+			else finish();
+		});
+	}
+	sendAudio(base64Mulaw) {
+		if (!this.isConnected) return;
+		this.send({
+			type: "session.input_audio.append",
+			audio: base64Mulaw
+		});
+	}
+	/**
+	* Text has three doors into a GPT-Live session, by intent rather than by
+	* conversation role: `system` → instructions (behaviour), `user` → thinking
+	* (quiet context: keypad entries, deferred results — the model decides how
+	* to react), `assistant` → thinking as well, worded as something already
+	* said (commentary would make the model say it again).
+	*/
+	sendText(text, options = {}) {
+		const role = options.role ?? "user";
+		if (role === "system") this.append("session.instructions.append", text);
+		else if (role === "assistant") this.append("session.thinking.append", `You already said this to the caller earlier: "${text}"`);
+		else this.append("session.thinking.append", text);
+	}
+	sendToolResult(callId, output, options = {}) {
+		this.send({
+			type: "response.item.create",
+			event_id: nextEventId("tool"),
+			item: {
+				type: "function_call_output",
+				call_id: callId,
+				output: typeof output === "string" ? output : JSON.stringify(output ?? null)
+			}
+		});
+		if (options.triggerResponse !== false) this.send({
+			type: "response.create",
+			event_id: nextEventId("continue")
+		});
+	}
+	/**
+	* "Speak now" has no direct verb on this API. Commentary — information the
+	* model should say aloud, paraphrasing allowed — is the append that
+	* produced speech on demand in every field test, greeting and goodbye
+	* alike; an instruction-shaped text is followed rather than read out.
+	*/
+	createResponse(options = {}) {
+		if (options.instructions) this.append("session.commentary.append", options.instructions);
+		else this.append("session.instructions.append", "Respond to the caller now, without waiting for them to speak.");
+	}
+	/**
+	* Only the backend delegation can change mid-session (`session.update` is
+	* sparse and limited to `delegation.responses`): tool lists land there;
+	* instructions / voice / vad are immutable and are reported, not applied.
+	*/
+	async updateSession(patch, options = {}) {
+		if (!this.sessionInit) throw new Error("updateSession before connect");
+		const ignored = Object.keys(patch).filter((key) => key !== "tools" && key !== "providerOptions");
+		if (ignored.length > 0) this.logger.warn("gpt-live: session fields are immutable after start — ignored", { fields: ignored });
+		this.sessionInit = {
+			...this.sessionInit,
+			...patch
+		};
+		let responses = {};
+		if (patch.tools) responses.tools = [...patch.tools.map(toBackendTool), ...this.config.delegation?.extraTools ?? []];
+		const nativeResponses = patch.providerOptions?.delegation?.responses;
+		if (nativeResponses && typeof nativeResponses === "object") responses = require_BaseRealtimeProvider.deepMerge(responses, nativeResponses);
+		if (Object.keys(responses).length === 0) return false;
+		if (!this.isConnected) return false;
+		const eventId = nextEventId("update");
+		const acked = this.awaitAck(eventId, ACK_TYPES["session.update"]);
+		this.send({
+			type: "session.update",
+			event_id: eventId,
+			session: { delegation: {
+				type: "responses",
+				responses
+			} }
+		});
+		return options.awaitAck ? acked : true;
+	}
+	handleEvent(event) {
+		switch (event.type) {
+			case "session.output_audio.delta":
+				if (typeof event.delta !== "string" || event.delta.length === 0) break;
+				this.handleOutputAudio(event.delta);
+				break;
+			case "session.input_transcript.delta":
+				if (typeof event.delta === "string") this.inputTranscript.push(event.delta, numberOr(event.start_ms, 0), numberOr(event.end_ms, 0));
+				break;
+			case "session.output_transcript.delta":
+				if (typeof event.delta === "string") {
+					this.emit("agentTranscriptDelta", {
+						responseId: this.currentUtteranceId ?? this.lastUtteranceId ?? "",
+						delta: event.delta
+					});
+					this.outputTranscript.push(event.delta, numberOr(event.start_ms, 0), numberOr(event.end_ms, 0));
+				}
+				break;
+			case "session.delegation.created":
+				this.logger.debug("gpt-live delegation created", {
+					id: event.delegation?.id,
+					target: event.delegation?.target,
+					responseId: event.delegation?.response_id
+				});
+				break;
+			case "response.event":
+				this.handleBackendEvent(event.event ?? {}, event.delegation_id);
+				break;
+			case "session.usage.updated": {
+				const seconds = event.usage?.seconds;
+				if (typeof seconds === "number") this.emit("usage", {
+					inputTokens: 0,
+					outputTokens: 0,
+					totalTokens: 0,
+					audioSeconds: seconds,
+					raw: event
+				});
+				break;
+			}
+			case "session.instructions.appended":
+			case "session.thinking.appended":
+			case "session.commentary.appended":
+			case "session.updated":
+			case "session.input_audio.muted":
+			case "session.input_audio.unmuted":
+				this.resolveAck(event.client_event_id, true);
+				break;
+			case "session.closed": {
+				const seconds = event.usage?.seconds;
+				this.sessionClosed = {
+					reason: event.reason,
+					usageSeconds: typeof seconds === "number" ? seconds : void 0
+				};
+				this.logger.info("gpt-live session closed", {
+					reason: event.reason,
+					usageSeconds: seconds
+				});
+				if (typeof seconds === "number") this.emit("usage", {
+					inputTokens: 0,
+					outputTokens: 0,
+					totalTokens: 0,
+					audioSeconds: seconds,
+					raw: event
+				});
+				break;
+			}
+			case "error":
+				if (event.error?.client_event_id) this.resolveAck(event.error.client_event_id, false);
+				this.logger.warn("provider error event", { error: event.error });
+				this.emit("error", /* @__PURE__ */ new Error(`${this.name} error: ${JSON.stringify(event.error ?? event)}`));
+				break;
+			case "info": this.logger.debug("gpt-live info", {
+				code: event.code,
+				message: event.message
+			});
+		}
+	}
+	handleOutputAudio(delta) {
+		const bytes = Buffer.from(delta, "base64");
+		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") {
+			this.beginUtterance();
+			forwardId = this.currentUtteranceId;
+		} else close = gateEvent;
+		if (forwardId) this.emit("audio", {
+			base64Mulaw: delta,
+			responseId: forwardId
+		});
+		if (close) this.endUtterance();
+		else if (this.gate.isOpen) this.armGateStall();
+	}
+	handleBackendEvent(inner, delegationId) {
+		const type = inner.type ?? "";
+		if (type === "response.output_item.done" && inner.item?.type === "function_call") {
+			const item = inner.item;
+			const callId = item.call_id ?? item.id ?? `call_${Date.now()}`;
+			if (this.seenCalls.has(callId)) return;
+			this.seenCalls.add(callId);
+			if (this.seenCalls.size > 1e3) this.seenCalls.delete(this.seenCalls.values().next().value);
+			this.emit("toolCall", {
+				id: callId,
+				name: item.name,
+				argumentsJson: typeof item.arguments === "string" ? item.arguments : "{}",
+				responseId: delegationId,
+				itemId: item.id
+			});
+			return;
+		}
+		if (type === "response.completed" || type === "response.done") {
+			const usage = require_OpenAICompatibleProvider.normalizeUsage(inner.response?.usage);
+			if (usage) this.emit("usage", usage);
+			return;
+		}
+		if (type === "response.failed" || type === "response.incomplete") this.logger.warn("gpt-live backend response did not complete", {
+			type,
+			delegationId,
+			error: inner.response?.error
+		});
+	}
+	beginUtterance() {
+		this.currentUtteranceId = `live_utt_${++this.utteranceCounter}`;
+		this.lastUtteranceId = this.currentUtteranceId;
+		this.emit("responseStarted", { responseId: this.currentUtteranceId });
+	}
+	endUtterance() {
+		this.clearGateStall();
+		const id = this.currentUtteranceId;
+		this.currentUtteranceId = null;
+		if (id) this.emit("responseDone", { responseId: id });
+	}
+	/** The stream is real-time: no delta for a quiet window means it stalled — close the utterance. */
+	armGateStall() {
+		this.clearGateStall();
+		const quietMs = this.config.speechGate?.quietMs ?? 800;
+		this.gateStallTimer = setTimeout(() => {
+			this.gateStallTimer = null;
+			if (this.gate.close()) this.endUtterance();
+		}, quietMs + GATE_STALL_EXTRA_MS);
+		this.gateStallTimer.unref?.();
+	}
+	clearGateStall() {
+		if (this.gateStallTimer) {
+			clearTimeout(this.gateStallTimer);
+			this.gateStallTimer = null;
+		}
+	}
+	finishUtteranceOnClose() {
+		this.clearGateStall();
+		if (this.gate.close()) this.endUtterance();
+		this.inputTranscript.flush();
+		this.outputTranscript.flush();
+	}
+	resetUtteranceState() {
+		this.clearGateStall();
+		this.gate.close();
+		this.currentUtteranceId = null;
+		this.lastUtteranceId = null;
+		this.seenCalls.clear();
+	}
+	/** Send `content` as one or more appends (500-token cap); resolves with the last chunk's ack. */
+	async append(type, content, delegationId = null) {
+		if (!this.isConnected) return false;
+		const chunks = splitForAppend(content);
+		if (chunks.length > 1) this.logger.warn("gpt-live: append split to respect the 500-token cap", {
+			type,
+			chunks: chunks.length
+		});
+		let acked = false;
+		for (const chunk of chunks) {
+			const eventId = nextEventId("append");
+			const ack = this.awaitAck(eventId, ACK_TYPES[type]);
+			this.send({
+				type,
+				event_id: eventId,
+				delegation_id: delegationId,
+				content: chunk
+			});
+			acked = await ack;
+			if (!acked) break;
+		}
+		return acked;
+	}
+	awaitAck(eventId, ackType) {
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				if (this.acks.delete(eventId)) {
+					this.logger.warn("gpt-live: no acknowledgement for client event", {
+						eventId,
+						ackType
+					});
+					resolve(false);
+				}
+			}, this.config.ackTimeoutMs ?? 5e3);
+			timer.unref?.();
+			this.acks.set(eventId, {
+				ackType,
+				resolve,
+				timer
+			});
+		});
+	}
+	resolveAck(clientEventId, acked) {
+		if (typeof clientEventId !== "string") return;
+		const waiter = this.acks.get(clientEventId);
+		if (!waiter) return;
+		this.acks.delete(clientEventId);
+		clearTimeout(waiter.timer);
+		waiter.resolve(acked);
+	}
+	failPendingAcks() {
+		for (const [id, waiter] of this.acks) {
+			clearTimeout(waiter.timer);
+			waiter.resolve(false);
+			this.acks.delete(id);
+		}
+	}
+	sessionConfig() {
+		return {
+			defaultVoice: this.config.voice,
+			delegation: this.config.delegation,
+			store: this.config.store,
+			extraSessionOptions: this.config.extraSessionOptions,
+			historyMaxMessages: this.config.historyMaxMessages,
+			historyMaxChars: this.config.historyMaxChars
+		};
+	}
+	isRetriableClose(code) {
+		if (this.intentionalClose) return false;
+		if (NON_RETRIABLE_CLOSE_CODES.has(code)) return false;
+		const reason = this.sessionClosed?.reason;
+		if (reason && reason !== "expired" && reason !== "connection_lost") return false;
+		return true;
+	}
+	parseEvent(raw) {
+		try {
+			return JSON.parse(raw.toString());
+		} catch {
+			this.logger.warn("unparseable provider frame");
+			return null;
+		}
+	}
+	send(payload) {
+		if (this.ws?.readyState !== ws.default.OPEN) return;
+		try {
+			this.ws.send(JSON.stringify(payload));
+		} catch (error) {
+			this.emit("error", error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+};
+function numberOr(value, fallback) {
+	return typeof value === "number" ? value : fallback;
+}
+/** Split on whitespace so no chunk exceeds the per-append cap. */
+function splitForAppend(content, maxChars = APPEND_MAX_CHARS) {
+	const text = content.trim();
+	if (text.length <= maxChars) return [text];
+	const chunks = [];
+	let rest = text;
+	while (rest.length > maxChars) {
+		let cut = rest.lastIndexOf(" ", maxChars);
+		if (cut < maxChars / 2) cut = maxChars;
+		chunks.push(rest.slice(0, cut).trim());
+		rest = rest.slice(cut).trim();
+	}
+	if (rest.length) chunks.push(rest);
+	return chunks;
+}
+//#endregion
+//#region src/gpt-live.ts
+/** OpenAI GPT-Live provider (full-duplex Live API) — `realtime-voice-agents/gpt-live`. */
+/** Env vars checked (in order) when no explicit apiKey is passed — the same project key as Realtime. */
+const GPT_LIVE_KEY_ENV_VARS = [
+	"OPENAI_API_KEY",
+	"OPENAI_KEY",
+	"OPEN_AI_API_KEY"
+];
+const GPT_LIVE_DEFAULT_MODEL = "gpt-live-1";
+const GPT_LIVE_DEFAULT_VOICE = "marin";
+/** Built-in voices accepted by the Live API (the SDK's enum, Sept 2026). */
+const GPT_LIVE_VOICES = [
+	"marin",
+	"cedar",
+	"alloy",
+	"ash",
+	"ballad",
+	"beacon",
+	"bossa",
+	"cinder",
+	"coral",
+	"delta",
+	"echo",
+	"gleam",
+	"meridian",
+	"quartz",
+	"ripple",
+	"sage",
+	"shimmer",
+	"stone",
+	"tempo",
+	"verse",
+	"vesper",
+	"willow"
+];
+/**
+* Create a GPT-Live provider factory for the bridge (`provider: gptLive({...})`).
+*
+* Credentials are resolved per call, when the factory runs (see
+* `openaiRealtime` — a missing key fails that call's connect so a fallback
+* chain can absorb it instead of crashing config construction).
+*/
+function gptLive(options = {}) {
+	const config = {
+		model: options.model ?? "gpt-live-1",
+		voice: options.voice ?? "marin",
+		delegation: options.delegation,
+		baseUrl: options.baseUrl,
+		headers: options.headers,
+		store: options.store,
+		extraSessionOptions: options.sessionOptions,
+		connectTimeoutMs: options.connectTimeoutMs,
+		speechGate: options.speechGate,
+		transcriptGapMs: options.transcriptGapMs
+	};
+	return ({ logger }) => {
+		const apiKey = require_env.resolveApiKey(options.apiKey, GPT_LIVE_KEY_ENV_VARS);
+		if (!apiKey) throw new Error(`gptLive: apiKey missing (pass apiKey or set one of ${GPT_LIVE_KEY_ENV_VARS.join("/")})`);
+		return new GptLiveProvider({
+			...config,
+			apiKey
+		}, logger);
+	};
+}
+//#endregion
+exports.DEFAULT_GATE_QUIET_MS = DEFAULT_GATE_QUIET_MS;
+exports.DEFAULT_GATE_THRESHOLD_RMS = DEFAULT_GATE_THRESHOLD_RMS;
+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;
+exports.GPT_LIVE_DEFAULT_MODEL = GPT_LIVE_DEFAULT_MODEL;
+exports.GPT_LIVE_DEFAULT_VOICE = GPT_LIVE_DEFAULT_VOICE;
+exports.GPT_LIVE_KEY_ENV_VARS = GPT_LIVE_KEY_ENV_VARS;
+exports.GPT_LIVE_VOICES = GPT_LIVE_VOICES;
+exports.GptLiveProvider = GptLiveProvider;
+exports.SpeechGate = SpeechGate;
+exports.buildDelegation = buildDelegation;
+exports.buildHistoryItems = buildHistoryItems;
+exports.buildSessionStart = buildSessionStart;
+exports.gptLive = gptLive;
+exports.splitForAppend = splitForAppend;