getpatter 0.6.1 → 0.6.2

package/dist/chunk-CL2U3YET.mjs

@@ -0,0 +1,1429 @@
+import {
+  getLogger
+} from "./chunk-MVOQFAEO.mjs";
+import {
+  init_esm_shims
+} from "./chunk-N565J3CF.mjs";
+
+// src/providers/openai-realtime-2.ts
+init_esm_shims();
+import WebSocket2 from "ws";
+
+// src/providers/openai-realtime.ts
+init_esm_shims();
+import WebSocket from "ws";
+var OpenAIRealtimeAudioFormat = {
+  G711_ULAW: "g711_ulaw",
+  G711_ALAW: "g711_alaw",
+  PCM16: "pcm16"
+};
+var OpenAIRealtimeModel = {
+  GPT_REALTIME: "gpt-realtime",
+  GPT_REALTIME_2: "gpt-realtime-2",
+  GPT_REALTIME_MINI: "gpt-realtime-mini",
+  GPT_4O_REALTIME_PREVIEW: "gpt-4o-realtime-preview",
+  GPT_4O_MINI_REALTIME_PREVIEW: "gpt-4o-mini-realtime-preview"
+};
+var OpenAIVoice = {
+  ALLOY: "alloy",
+  ASH: "ash",
+  BALLAD: "ballad",
+  CORAL: "coral",
+  ECHO: "echo",
+  FABLE: "fable",
+  NOVA: "nova",
+  ONYX: "onyx",
+  SAGE: "sage",
+  SHIMMER: "shimmer",
+  VERSE: "verse"
+};
+var OpenAITranscriptionModel = {
+  WHISPER_1: "whisper-1",
+  GPT_4O_TRANSCRIBE: "gpt-4o-transcribe",
+  GPT_4O_MINI_TRANSCRIBE: "gpt-4o-mini-transcribe",
+  GPT_REALTIME_WHISPER: "gpt-realtime-whisper"
+};
+var OpenAIRealtimeVADType = {
+  SERVER_VAD: "server_vad",
+  SEMANTIC_VAD: "semantic_vad"
+};
+var OpenAIRealtimeAdapter = class {
+  constructor(apiKey, model = OpenAIRealtimeModel.GPT_REALTIME_MINI, voice = OpenAIVoice.ALLOY, instructions = "", tools, audioFormat = OpenAIRealtimeAudioFormat.G711_ULAW, options = {}) {
+    this.apiKey = apiKey;
+    this.model = model;
+    this.voice = voice;
+    this.instructions = instructions;
+    this.tools = tools;
+    this.audioFormat = audioFormat;
+    this.options = options;
+  }
+  apiKey;
+  model;
+  voice;
+  instructions;
+  tools;
+  audioFormat;
+  // Fields exposed `protected` (not `private`) so a subclass can implement
+  // alternate transports — e.g. `OpenAIRealtime2Adapter` overrides
+  // `connect()` to speak the GA Realtime API while reusing the rest of
+  // the runtime (audio dispatch, barge-in, heartbeat).
+  ws = null;
+  eventCallbacks = /* @__PURE__ */ new Set();
+  messageListenerAttached = false;
+  heartbeat = null;
+  // Track the in-flight assistant item id so we can truncate cleanly on
+  // barge-in (see ``cancelResponse``) — matches the Python adapter.
+  currentResponseItemId = null;
+  currentResponseAudioMs = 0;
+  // Wall-clock timestamp (Date.now()) of the first ``response.audio.delta``
+  // received since the current response item started. ``cancelResponse``
+  // uses this to bound ``audio_end_ms`` to what the caller could plausibly
+  // have heard — generated audio frequently arrives 5-10x real-time, so
+  // ``audio_end_ms`` driven purely by the per-chunk byte counter overshoots
+  // reality and leaves phantom assistant text on the conversation. The
+  // wall-clock cap corresponds to the maximum playback that real-time TTS
+  // could have produced, which is what the user actually heard.
+  currentResponseFirstAudioAt = null;
+  options;
+  /**
+   * Build the production session.update body. Mirrors the body sent
+   * inside `connect()` so warmup can apply identical configuration to
+   * the upstream session and prime it without billing.
+   */
+  buildSessionConfig() {
+    const config = {
+      input_audio_format: this.audioFormat,
+      output_audio_format: this.audioFormat,
+      voice: this.voice,
+      instructions: this.instructions || "You are a helpful voice assistant. Be concise.",
+      turn_detection: {
+        type: this.options.vadType ?? OpenAIRealtimeVADType.SERVER_VAD,
+        threshold: 0.5,
+        prefix_padding_ms: 300,
+        silence_duration_ms: this.options.silenceDurationMs ?? 300
+      },
+      input_audio_transcription: {
+        model: this.options.inputAudioTranscriptionModel ?? OpenAITranscriptionModel.WHISPER_1
+      }
+    };
+    if (this.options.temperature !== void 0) config.temperature = this.options.temperature;
+    if (this.options.maxResponseOutputTokens !== void 0) {
+      config.max_response_output_tokens = this.options.maxResponseOutputTokens;
+    }
+    if (this.options.modalities !== void 0) config.modalities = this.options.modalities;
+    if (this.options.toolChoice !== void 0) config.tool_choice = this.options.toolChoice;
+    if (this.options.reasoningEffort !== void 0) {
+      config.reasoning = { effort: this.options.reasoningEffort };
+    }
+    if (this.tools?.length) {
+      config.tools = this.tools.map((t) => {
+        const def = {
+          type: "function",
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters
+        };
+        if (t.strict === true) {
+          def.strict = true;
+        }
+        return def;
+      });
+    }
+    return config;
+  }
+  /**
+   * Pre-call WebSocket warmup for the OpenAI Realtime endpoint.
+   *
+   * The canonical session-only warm step on the Realtime API: open the
+   * WS, wait for `session.created`, send a single `session.update`
+   * containing the same fields that the production `connect()` path
+   * applies (`input_audio_format`, `output_audio_format`, `voice`,
+   * `instructions`, `turn_detection`, `input_audio_transcription`,
+   * plus any opt-in fields populated on the adapter), wait for the
+   * matching `session.updated` ack, then close cleanly. This primes
+   * the per-session state on the OpenAI side — DNS + TLS + auth
+   * handshake + initial config exchange — without ever invoking the
+   * model.
+   *
+   * Earlier revisions sent `response.create` with
+   * `{"response": {"generate": false}}` to prime the inference path.
+   * That field is NOT in the OpenAI Realtime API schema; the server
+   * either ignores it (and bills tokens for a real model response) or
+   * rejects the request with `invalid_request_error`. Both behaviours
+   * are billing-unsafe or a no-op beyond TLS warm. The
+   * `session.update` flow is documented and side-effect-free.
+   *
+   * Billing safety: `session.update` only mutates session
+   * configuration. It does NOT invoke the model, does NOT consume any
+   * audio buffer, and does NOT trigger token generation, so no
+   * per-token cost is accrued. Best-effort: failures are logged at
+   * debug level and never raised.
+   */
+  async warmup() {
+    const url = `wss://api.openai.com/v1/realtime?model=${encodeURIComponent(this.model)}`;
+    let ws = null;
+    try {
+      ws = await new Promise((resolve, reject) => {
+        const sock = new WebSocket(url, {
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`
+          }
+        });
+        const timer = setTimeout(() => {
+          try {
+            sock.close();
+          } catch {
+          }
+          reject(new Error("OpenAI Realtime warmup connect timeout"));
+        }, 5e3);
+        sock.once("open", () => {
+          clearTimeout(timer);
+          resolve(sock);
+        });
+        sock.once("error", (err) => {
+          clearTimeout(timer);
+          reject(err);
+        });
+      });
+      const sessionCreated = await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), 2e3);
+        const onMsg = (raw) => {
+          try {
+            const data = JSON.parse(raw.toString());
+            if (data.type === "session.created") {
+              clearTimeout(timer);
+              ws.off("message", onMsg);
+              resolve(true);
+            }
+          } catch {
+          }
+        };
+        ws.on("message", onMsg);
+      });
+      if (!sessionCreated) return;
+      try {
+        ws.send(JSON.stringify({ type: "session.update", session: this.buildSessionConfig() }));
+      } catch {
+        return;
+      }
+      await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(), 1500);
+        const onMsg = (raw) => {
+          try {
+            const data = JSON.parse(raw.toString());
+            if (data.type === "session.updated") {
+              clearTimeout(timer);
+              ws.off("message", onMsg);
+              resolve();
+            }
+          } catch {
+          }
+        };
+        ws.on("message", onMsg);
+      });
+    } catch (err) {
+      getLogger().debug(`OpenAI Realtime warmup failed (best-effort): ${String(err)}`);
+    } finally {
+      if (ws) {
+        try {
+          ws.close();
+        } catch {
+        }
+      }
+    }
+  }
+  /** Open the Realtime WebSocket and apply the session configuration. */
+  async connect() {
+    const url = `wss://api.openai.com/v1/realtime?model=${encodeURIComponent(this.model)}`;
+    this.ws = new WebSocket(url, {
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`
+      }
+    });
+    await new Promise((resolve, reject) => {
+      let sessionCreated = false;
+      let settled = false;
+      const ws = this.ws;
+      const onSetupMessage = (raw) => {
+        let msg;
+        try {
+          msg = JSON.parse(raw.toString());
+        } catch (e) {
+          getLogger().warn(`OpenAI Realtime: failed to parse message: ${String(e)}`);
+          return;
+        }
+        if (msg.type === "session.created" && !sessionCreated) {
+          sessionCreated = true;
+          ws.send(JSON.stringify({ type: "session.update", session: this.buildSessionConfig() }));
+        } else if (msg.type === "session.updated") {
+          cleanup();
+          resolve();
+        }
+      };
+      const onSetupError = (err) => {
+        cleanup();
+        try {
+          ws.close();
+        } catch {
+        }
+        reject(err);
+      };
+      const cleanup = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.off("message", onSetupMessage);
+        ws.off("error", onSetupError);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        try {
+          ws.close();
+        } catch {
+        }
+        reject(new Error("OpenAI Realtime connect timeout"));
+      }, 15e3);
+      ws.on("message", onSetupMessage);
+      ws.on("error", onSetupError);
+    });
+    this.armHeartbeatAndListener();
+  }
+  /**
+   * Adopt a pre-opened, already-`session.updated` Realtime WebSocket
+   * produced by the prewarm pipeline (see `Patter.parkProviderConnections`).
+   * Skips the fresh `new WebSocket()` + `session.created` /
+   * `session.update` round-trip — saves ~250-450 ms on first turn.
+   *
+   * Caller MUST verify `ws.readyState === OPEN` before calling and MUST
+   * have already received `session.updated` on the parked socket. If
+   * the parked WS died between park and adopt, fall back to `connect()`.
+   */
+  adoptWebSocket(ws) {
+    this.ws = ws;
+    this.armHeartbeatAndListener();
+  }
+  armHeartbeatAndListener() {
+    this.heartbeat = setInterval(() => {
+      try {
+        this.ws?.ping();
+      } catch {
+      }
+    }, 2e4);
+    this.ensureMessageListener();
+  }
+  /**
+   * Open a fresh Realtime WS, exchange `session.created` /
+   * `session.update` / `session.updated` (so the upstream session is
+   * fully primed), and return the OPEN socket WITHOUT arming the
+   * heartbeat / message listener. Used by the prewarm pipeline to park
+   * a Realtime connection during ringing; the live consumer adopts it
+   * via {@link adoptWebSocket}.
+   *
+   * Bounded by 8 s. Throws on timeout / handshake failure — callers
+   * (the prewarm pipeline) treat any error as a cache miss and the
+   * call falls through to the cold `connect()` path.
+   *
+   * Billing safety: `session.update` does not invoke the model. No
+   * tokens are billed.
+   */
+  async openParkedConnection() {
+    const url = `wss://api.openai.com/v1/realtime?model=${encodeURIComponent(this.model)}`;
+    const ws = new WebSocket(url, {
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`
+      }
+    });
+    await new Promise((resolve, reject) => {
+      let sessionCreated = false;
+      let settled = false;
+      const onMessage = (raw) => {
+        let msg;
+        try {
+          msg = JSON.parse(raw.toString());
+        } catch {
+          return;
+        }
+        if (msg.type === "session.created" && !sessionCreated) {
+          sessionCreated = true;
+          try {
+            ws.send(JSON.stringify({ type: "session.update", session: this.buildSessionConfig() }));
+          } catch (err) {
+            cleanup();
+            reject(err instanceof Error ? err : new Error(String(err)));
+          }
+        } else if (msg.type === "session.updated") {
+          cleanup();
+          resolve();
+        }
+      };
+      const onError = (err) => {
+        cleanup();
+        reject(err);
+      };
+      const cleanup = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.off("message", onMessage);
+        ws.off("error", onError);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error("OpenAI Realtime park connect timeout"));
+      }, 8e3);
+      ws.on("message", onMessage);
+      ws.on("error", onError);
+    });
+    return ws;
+  }
+  /** Append a base64-encoded audio chunk to the realtime input buffer. */
+  sendAudio(mulawAudio) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    this.ws.send(JSON.stringify({ type: "input_audio_buffer.append", audio: mulawAudio.toString("base64") }));
+  }
+  /**
+   * Register a listener for parsed realtime events.
+   *
+   * Previously every call attached a new ``ws.on('message')`` handler,
+   * which leaked listeners across retries and multi-consumer hooks. We now
+   * route all traffic through a single persistent handler that fans out to
+   * a Set of callbacks. Use {@link offEvent} to remove one.
+   */
+  onEvent(callback) {
+    this.eventCallbacks.add(callback);
+    this.ensureMessageListener();
+  }
+  /** Remove a previously registered {@link onEvent} callback. */
+  offEvent(callback) {
+    this.eventCallbacks.delete(callback);
+  }
+  ensureMessageListener() {
+    if (this.messageListenerAttached || !this.ws) return;
+    this.messageListenerAttached = true;
+    const ws = this.ws;
+    const dispatch = (type, payload) => {
+      for (const cb of this.eventCallbacks) {
+        void Promise.resolve(cb(type, payload)).catch(
+          (err) => getLogger().error("onEvent callback error:", err)
+        );
+      }
+    };
+    ws.on("message", (raw) => {
+      let data;
+      try {
+        data = JSON.parse(raw.toString());
+      } catch (e) {
+        getLogger().warn(`OpenAI Realtime: failed to parse event message: ${String(e)}`);
+        return;
+      }
+      const t = data.type;
+      if (t === "response.audio.delta") {
+        const buf = Buffer.from(data.delta ?? "", "base64");
+        this.currentResponseAudioMs += estimateAudioMs(buf, this.audioFormat);
+        if (this.currentResponseFirstAudioAt === null) {
+          this.currentResponseFirstAudioAt = Date.now();
+        }
+        dispatch("audio", buf);
+      } else if (t === "response.audio_transcript.delta") {
+        dispatch("transcript_output", data.delta);
+      } else if (t === "response.content_part.added" || t === "response.output_item.added") {
+        const itemId = data.item?.id ?? data.item_id ?? null;
+        if (itemId) {
+          this.currentResponseItemId = itemId;
+          this.currentResponseAudioMs = 0;
+          this.currentResponseFirstAudioAt = null;
+        }
+      } else if (t === "input_audio_buffer.speech_started") {
+        dispatch("speech_started", null);
+      } else if (t === "input_audio_buffer.speech_stopped") {
+        dispatch("speech_stopped", null);
+      } else if (t === "conversation.item.input_audio_transcription.completed") {
+        dispatch("transcript_input", data.transcript);
+      } else if (t === "response.function_call_arguments.done") {
+        dispatch("function_call", { call_id: data.call_id, name: data.name, arguments: data.arguments });
+      } else if (t === "response.done") {
+        this.currentResponseItemId = null;
+        this.currentResponseAudioMs = 0;
+        this.currentResponseFirstAudioAt = null;
+        dispatch("response_done", data.response ?? null);
+      } else if (t === "error") {
+        dispatch("error", data.error);
+      }
+    });
+    ws.on("close", (code, reason) => {
+      if (code !== 1e3) {
+        dispatch("error", {
+          type: "connection_closed",
+          code,
+          reason: reason?.toString() ?? ""
+        });
+      }
+    });
+    ws.on("error", (err) => {
+      dispatch("error", { type: "socket_error", message: err?.message ?? String(err) });
+    });
+  }
+  /** Truncate the in-flight assistant turn and cancel the active response.
+   *
+   * ``audio_end_ms`` MUST reflect what the caller actually heard, not what
+   * the server generated. OpenAI streams audio at 5-10x real-time, so the
+   * byte-derived counter overstates playback whenever the consumer cleared
+   * its playout buffer (e.g. ``send_clear``) before the audio reached the
+   * speaker. We bound the truncate point by wall-clock time since the first
+   * chunk of this response — that's the physical maximum a 1x real-time
+   * playback could have produced. Without this cap, OpenAI keeps the full
+   * generated assistant text on the transcript, and the model replays /
+   * resumes from it on the next turn — manifesting as re-greetings and
+   * mid-sentence fragments after a barge-in storm.
+   */
+  cancelResponse() {
+    if (!this.ws) return;
+    if (!this.currentResponseItemId) {
+      return;
+    }
+    let audioEndMs = this.currentResponseAudioMs;
+    if (this.currentResponseFirstAudioAt !== null) {
+      const elapsedMs = Date.now() - this.currentResponseFirstAudioAt;
+      audioEndMs = Math.min(audioEndMs, Math.max(elapsedMs, 0));
+    }
+    try {
+      this.ws.send(JSON.stringify({
+        type: "conversation.item.truncate",
+        item_id: this.currentResponseItemId,
+        content_index: 0,
+        audio_end_ms: audioEndMs
+      }));
+    } catch (err) {
+      getLogger().debug?.(`conversation.item.truncate failed: ${String(err)}`);
+    }
+    this.ws.send(JSON.stringify({ type: "response.cancel" }));
+    this.currentResponseItemId = null;
+    this.currentResponseAudioMs = 0;
+    this.currentResponseFirstAudioAt = null;
+  }
+  /** Inject a user text turn and request a new response. */
+  async sendText(text) {
+    this.ws?.send(JSON.stringify({
+      type: "conversation.item.create",
+      item: { type: "message", role: "user", content: [{ type: "input_text", text }] }
+    }));
+    this.ws?.send(JSON.stringify({ type: "response.create" }));
+  }
+  /**
+   * Trigger `response.create` with no new user item.
+   *
+   * Used by the Realtime stream-handler to drive a response after the
+   * client-side hallucination filter accepts an
+   * `input_audio_transcription.completed` event. The server VAD config
+   * sets `create_response: false` so OpenAI no longer auto-creates a
+   * response on every `input_audio_buffer.committed`; Patter is now
+   * responsible for triggering it explicitly when a real user turn lands.
+   */
+  async requestResponse() {
+    this.ws?.send(JSON.stringify({ type: "response.create" }));
+  }
+  /**
+   * Make the AI speak ``text`` as its opening line.
+   *
+   * Triggers ``response.create`` with explicit ``instructions`` that force
+   * the model to render ``text`` verbatim as its first audio utterance.
+   * This is the correct semantics for ``Agent.firstMessage`` per its
+   * docstring ("What the AI says when the callee answers").
+   *
+   * Without this, ``sendText(firstMessage)`` would inject ``text`` as
+   * ``role: user`` and the AI would *reply* to its own greeting, producing
+   * role-confused openings (e.g. a receptionist agent responding "I'd like
+   * to schedule a haircut" because it took its own first_message as a
+   * customer cue).
+   */
+  async sendFirstMessage(text) {
+    this.ws?.send(JSON.stringify({
+      type: "response.create",
+      response: {
+        modalities: ["audio", "text"],
+        instructions: `Say exactly the following sentence as your first turn and nothing else: "${text}"`
+      }
+    }));
+  }
+  /** Submit a tool/function-call result and request the next response. */
+  async sendFunctionResult(callId, result) {
+    this.ws?.send(JSON.stringify({
+      type: "conversation.item.create",
+      item: { type: "function_call_output", call_id: callId, output: result }
+    }));
+    this.ws?.send(JSON.stringify({ type: "response.create" }));
+  }
+  /** Stop the heartbeat, drop listeners, and close the Realtime WebSocket. */
+  close() {
+    if (this.heartbeat) {
+      clearInterval(this.heartbeat);
+      this.heartbeat = null;
+    }
+    this.eventCallbacks.clear();
+    this.messageListenerAttached = false;
+    this.ws?.close();
+    this.ws = null;
+  }
+};
+function estimateAudioMs(chunk, format) {
+  if (chunk.length === 0) return 0;
+  if (format === OpenAIRealtimeAudioFormat.G711_ULAW || format === OpenAIRealtimeAudioFormat.G711_ALAW)
+    return Math.floor(chunk.length / 8);
+  if (format === OpenAIRealtimeAudioFormat.PCM16) {
+    return Math.floor(chunk.length / 48);
+  }
+  return 0;
+}
+
+// src/audio/transcoding.ts
+init_esm_shims();
+var MULAW_TO_PCM16_TABLE = (() => {
+  const table = new Int16Array(256);
+  for (let i = 0; i < 256; i++) {
+    const mu = ~i & 255;
+    const sign = mu & 128 ? -1 : 1;
+    const exponent = mu >> 4 & 7;
+    const mantissa = mu & 15;
+    const magnitude = (mantissa << 1 | 33) << exponent + 2;
+    table[i] = sign * (magnitude - 132);
+  }
+  return table;
+})();
+var PCM16_TO_MULAW_TABLE = (() => {
+  const BIAS = 132;
+  const CLIP = 32635;
+  const table = new Uint8Array(65536);
+  for (let i = 0; i < 65536; i++) {
+    let sample = i >= 32768 ? i - 65536 : i;
+    const sign = sample < 0 ? 128 : 0;
+    if (sample < 0) sample = -sample;
+    if (sample > CLIP) sample = CLIP;
+    sample += BIAS;
+    let exponent = 7;
+    const exponentMask = 16384;
+    for (let shift = exponentMask; shift > 0 && (sample & shift) === 0; shift >>= 1) {
+      exponent--;
+    }
+    const mantissa = sample >> exponent + 3 & 15;
+    const mulaw = ~(sign | exponent << 4 | mantissa) & 255;
+    table[i] = mulaw;
+  }
+  return table;
+})();
+function mulawToPcm16(mulawData) {
+  const out = Buffer.alloc(mulawData.length * 2);
+  for (let i = 0; i < mulawData.length; i++) {
+    out.writeInt16LE(MULAW_TO_PCM16_TABLE[mulawData[i]], i * 2);
+  }
+  return out;
+}
+function pcm16ToMulaw(pcmData) {
+  const sampleCount = Math.floor(pcmData.length / 2);
+  const out = Buffer.alloc(sampleCount);
+  for (let i = 0; i < sampleCount; i++) {
+    const sample = pcmData.readInt16LE(i * 2);
+    out[i] = PCM16_TO_MULAW_TABLE[sample + 65536 & 65535];
+  }
+  return out;
+}
+var PcmCarry = class {
+  pending = null;
+  /**
+   * Prepend any carried odd byte, return the even-length prefix, and stash
+   * any new trailing odd byte for the next call.
+   *
+   * Returns a zero-length buffer when no complete sample is yet available.
+   */
+  push(chunk) {
+    const combined = this.pending !== null ? Buffer.concat([this.pending, chunk]) : chunk;
+    this.pending = null;
+    const alignedLen = combined.length & ~1;
+    if (alignedLen < combined.length) {
+      this.pending = combined.subarray(alignedLen);
+    }
+    return combined.subarray(0, alignedLen);
+  }
+  /**
+   * Return any pending byte as a 1-byte buffer (rare in practice — only if
+   * the entire stream had an odd byte count), then reset internal state.
+   */
+  flush() {
+    if (this.pending === null) return Buffer.alloc(0);
+    const out = this.pending;
+    this.pending = null;
+    return out;
+  }
+  /** Reset carry state without flushing. */
+  reset() {
+    this.pending = null;
+  }
+};
+var StatefulResampler = class {
+  srcRate;
+  dstRate;
+  // 16k→8k: 5-tap FIR state.
+  // Extended sample buffer carries the 2 history samples that precede the
+  // current chunk AND any "pending" input sample that did not yet generate
+  // output (i.e. the odd sample when the chunk had an odd sample count).
+  // `firPhase` = 0 means the next output is at input position 0 of the
+  // current chunk; 1 means it starts at input position 1 (because the
+  // previous chunk ended on an even-output boundary).
+  firHistory = new Int16Array(2);
+  // [s_{-2}, s_{-1}]
+  firHistoryValid = false;
+  // Pending sample carried from odd-count chunks (not the byte carry —
+  // this is a complete Int16 sample that becomes the first input for the
+  // next call).
+  firPendingSample = null;
+  // 8k→16k: last input sample deferred across chunk boundaries.
+  upsampleLast = 0;
+  upsampleHasHistory = false;
+  // 24k→16k: fractional phase and last input sample across chunks.
+  resample24Last = 0;
+  resample24Phase = 0;
+  resample24HasHistory = false;
+  // Odd-byte alignment carry.
+  carry = new PcmCarry();
+  constructor(opts) {
+    this.srcRate = opts.srcRate;
+    this.dstRate = opts.dstRate;
+    if (opts.channels !== void 0 && opts.channels !== 1) {
+      throw new Error("StatefulResampler: only mono (channels=1) is supported");
+    }
+    const key = `${this.srcRate}->${this.dstRate}`;
+    if (key !== "16000->8000" && key !== "8000->16000" && key !== "24000->16000" && key !== "24000->8000") {
+      throw new Error(
+        `StatefulResampler: unsupported conversion ${key}. Supported: 16000->8000, 8000->16000, 24000->16000, 24000->8000`
+      );
+    }
+  }
+  /**
+   * Process a chunk of PCM16-LE samples.
+   *
+   * Handles odd-byte inputs via an internal carry buffer. Returns an even-byte-
+   * aligned output buffer; may return a zero-length buffer if not enough
+   * aligned input is available yet.
+   */
+  process(pcm) {
+    const aligned = this.carry.push(pcm);
+    if (aligned.length === 0) return Buffer.alloc(0);
+    if (this.srcRate === 16e3 && this.dstRate === 8e3) {
+      return this._downsample16kTo8k(aligned);
+    }
+    if (this.srcRate === 8e3 && this.dstRate === 16e3) {
+      return this._upsample8kTo16k(aligned);
+    }
+    if (this.srcRate === 24e3 && this.dstRate === 8e3) {
+      return this._resample24kTo8k(aligned);
+    }
+    return this._resample24kTo16k(aligned);
+  }
+  /**
+   * Flush internal state and return any remaining output samples.
+   *
+   * For 8k→16k: the deferred last sample is emitted duplicated (matching
+   * the stateless helper's end-of-stream behaviour).
+   * For 16k→8k: any pending odd sample is processed with edge-replication.
+   * Resets all state after flushing.
+   */
+  flush() {
+    this.carry.flush();
+    if (this.srcRate === 16e3 && this.dstRate === 8e3 && this.firPendingSample !== null) {
+      const s = this.firPendingSample;
+      const tmp = Buffer.alloc(4);
+      tmp.writeInt16LE(s, 0);
+      tmp.writeInt16LE(s, 2);
+      const out = this._downsample16kTo8k(tmp);
+      this.firPendingSample = null;
+      return out;
+    }
+    if (this.srcRate === 8e3 && this.dstRate === 16e3 && this.upsampleHasHistory) {
+      const out = Buffer.alloc(4);
+      out.writeInt16LE(this.upsampleLast, 0);
+      out.writeInt16LE(this.upsampleLast, 2);
+      this.upsampleHasHistory = false;
+      this.upsampleLast = 0;
+      return out;
+    }
+    return Buffer.alloc(0);
+  }
+  /** Reset all carried state (e.g. at call boundaries). */
+  reset() {
+    this.firHistory = new Int16Array(2);
+    this.firHistoryValid = false;
+    this.firPendingSample = null;
+    this.upsampleLast = 0;
+    this.upsampleHasHistory = false;
+    this.resample24Last = 0;
+    this.resample24Phase = 0;
+    this.resample24HasHistory = false;
+    this.carry.reset();
+  }
+  // ---------------------------------------------------------------------------
+  // Private: 16 kHz → 8 kHz
+  // ---------------------------------------------------------------------------
+  /**
+   * 2:1 decimation with a 5-tap binomial FIR anti-alias filter.
+   *
+   * FIR coefficients: [1, 4, 6, 4, 1] / 16 (cutoff ~Fs/4 = 4 kHz).
+   *
+   * Cross-chunk state:
+   * - `firHistory[0]` = s_{-2}, `firHistory[1]` = s_{-1} relative to the
+   *   virtual stream (seeded to first-sample on the very first call).
+   * - `firPendingSample` = a lone input sample carried from a chunk whose
+   *   sample count was odd; it will become the first input of the next chunk.
+   *
+   * Decimation: outputs are at even positions (0, 2, 4 …) in the virtual
+   * extended stream, so every 2 input samples yield 1 output. An odd-sample-
+   * count chunk leaves 1 sample in `firPendingSample`; the next chunk
+   * prepends it so the output cadence is unbroken.
+   */
+  _downsample16kTo8k(buf) {
+    const newSampleCount = buf.length >> 1;
+    const hasPending = this.firPendingSample !== null;
+    const totalInput = newSampleCount + (hasPending ? 1 : 0);
+    const input = new Int16Array(totalInput);
+    if (hasPending) {
+      input[0] = this.firPendingSample;
+      for (let j = 0; j < newSampleCount; j++) input[j + 1] = buf.readInt16LE(j * 2);
+    } else {
+      for (let j = 0; j < newSampleCount; j++) input[j] = buf.readInt16LE(j * 2);
+    }
+    this.firPendingSample = null;
+    if (totalInput === 0) return Buffer.alloc(0);
+    if (!this.firHistoryValid) {
+      this.firHistory[0] = 0;
+      this.firHistory[1] = 0;
+      this.firHistoryValid = true;
+    }
+    const extended = new Int16Array(totalInput + 2);
+    extended[0] = this.firHistory[0];
+    extended[1] = this.firHistory[1];
+    for (let j = 0; j < totalInput; j++) extended[j + 2] = input[j];
+    const outSamples = totalInput >> 1;
+    const out = Buffer.alloc(outSamples * 2);
+    for (let i = 0; i < outSamples; i++) {
+      const c = 2 + i * 2;
+      const sM2 = extended[c - 2];
+      const sM1 = extended[c - 1];
+      const s0 = extended[c];
+      const sP1 = c + 1 < extended.length ? extended[c + 1] : extended[extended.length - 1];
+      const sP2 = c + 2 < extended.length ? extended[c + 2] : extended[extended.length - 1];
+      const filtered = sM2 + 4 * sM1 + 6 * s0 + 4 * sP1 + sP2 + 8 >> 4;
+      out.writeInt16LE(Math.max(-32768, Math.min(32767, filtered)), i * 2);
+    }
+    if (totalInput % 2 === 1) {
+      this.firPendingSample = input[totalInput - 1];
+    }
+    if (totalInput >= 2) {
+      this.firHistory[0] = input[totalInput - 2];
+      this.firHistory[1] = input[totalInput - 1];
+    } else {
+      this.firHistory[0] = this.firHistory[1];
+      this.firHistory[1] = input[0];
+    }
+    return out;
+  }
+  // ---------------------------------------------------------------------------
+  // Private: 8 kHz → 16 kHz
+  // ---------------------------------------------------------------------------
+  /**
+   * 1:2 linear-interpolation upsampler.
+   *
+   * For the first chunk (no history): emits 2*(N-1) samples and defers the
+   * last sample. For subsequent chunks (with history): emits the deferred
+   * sample + its interpolated midpoint THEN 2*(N-1) samples from the new
+   * chunk, deferring the new last sample. Total across K chunks + flush =
+   * 2*total_input_samples (correct output length).
+   *
+   * Call flush() after the final chunk to emit the last deferred sample
+   * pair (self-duplicate at end of stream).
+   */
+  _upsample8kTo16k(buf) {
+    const sampleCount = buf.length >> 1;
+    if (sampleCount === 0) return Buffer.alloc(0);
+    const outArr = [];
+    if (this.upsampleHasHistory) {
+      const next = buf.readInt16LE(0);
+      outArr.push(this.upsampleLast);
+      outArr.push(Math.round((this.upsampleLast + next) / 2));
+    }
+    for (let i = 0; i < sampleCount - 1; i++) {
+      const s0 = buf.readInt16LE(i * 2);
+      const s1 = buf.readInt16LE((i + 1) * 2);
+      outArr.push(s0);
+      outArr.push(Math.round((s0 + s1) / 2));
+    }
+    this.upsampleLast = buf.readInt16LE((sampleCount - 1) * 2);
+    this.upsampleHasHistory = true;
+    const outBuf = Buffer.alloc(outArr.length * 2);
+    for (let j = 0; j < outArr.length; j++) outBuf.writeInt16LE(outArr[j], j * 2);
+    return outBuf;
+  }
+  // ---------------------------------------------------------------------------
+  // Private: 24 kHz → 16 kHz / 8 kHz
+  // ---------------------------------------------------------------------------
+  /**
+   * 3:2 linear-interpolation decimator (ratio srcRate/dstRate = 1.5).
+   *
+   * `resample24Phase` tracks the fractional input position of the next output
+   * sample relative to the START of the next chunk. Negative phase means the
+   * next output straddles the previous/current chunk boundary; those are
+   * handled using `resample24Last`.
+   */
+  _resample24kTo16k(buf) {
+    return this._resample24kStep(buf, 24e3 / 16e3);
+  }
+  /** 3:1 decimation — collapses the 24k→16k→8k chain into a single step. */
+  _resample24kTo8k(buf) {
+    return this._resample24kStep(buf, 24e3 / 8e3);
+  }
+  /** Shared phase-stepping resampler used by 24→16 (step 1.5) and 24→8 (step 3). */
+  _resample24kStep(buf, step) {
+    const sampleCount = buf.length >> 1;
+    if (sampleCount === 0) return Buffer.alloc(0);
+    const outArr = [];
+    let phase = this.resample24Phase;
+    while (true) {
+      const idx = Math.floor(phase);
+      if (idx >= sampleCount) break;
+      const frac = phase - idx;
+      let s0;
+      let s1;
+      if (idx < 0) {
+        s0 = this.resample24HasHistory ? this.resample24Last : 0;
+        s1 = buf.readInt16LE(0);
+      } else {
+        s0 = buf.readInt16LE(idx * 2);
+        s1 = idx + 1 < sampleCount ? buf.readInt16LE((idx + 1) * 2) : s0;
+      }
+      const interp = Math.round(s0 + (s1 - s0) * frac);
+      outArr.push(Math.max(-32768, Math.min(32767, interp)));
+      phase += step;
+    }
+    this.resample24Last = buf.readInt16LE((sampleCount - 1) * 2);
+    this.resample24HasHistory = true;
+    this.resample24Phase = phase - sampleCount;
+    const outBuf = Buffer.alloc(outArr.length * 2);
+    for (let j = 0; j < outArr.length; j++) outBuf.writeInt16LE(outArr[j], j * 2);
+    return outBuf;
+  }
+};
+function createResampler16kTo8k() {
+  return new StatefulResampler({ srcRate: 16e3, dstRate: 8e3 });
+}
+function createResampler8kTo16k() {
+  return new StatefulResampler({ srcRate: 8e3, dstRate: 16e3 });
+}
+function createResampler24kTo16k() {
+  return new StatefulResampler({ srcRate: 24e3, dstRate: 16e3 });
+}
+function createResampler24kTo8k() {
+  return new StatefulResampler({ srcRate: 24e3, dstRate: 8e3 });
+}
+var _warnedResample8kTo16k = false;
+var _warnedResample16kTo8k = false;
+var _warnedResample24kTo16k = false;
+function resample8kTo16k(pcm8k) {
+  if (!_warnedResample8kTo16k) {
+    _warnedResample8kTo16k = true;
+    getLogger().warn(
+      "[patter] resample8kTo16k() is deprecated. Use createResampler8kTo16k() (StatefulResampler) to eliminate chunk-boundary discontinuities."
+    );
+  }
+  if (pcm8k.length === 0) return Buffer.alloc(0);
+  const r = createResampler8kTo16k();
+  const main = r.process(pcm8k);
+  const tail = r.flush();
+  return tail.length > 0 ? Buffer.concat([main, tail]) : main;
+}
+function resample16kTo8k(pcm16k) {
+  if (!_warnedResample16kTo8k) {
+    _warnedResample16kTo8k = true;
+    getLogger().warn(
+      "[patter] resample16kTo8k() is deprecated. Use createResampler16kTo8k() (StatefulResampler) to eliminate chunk-boundary discontinuities."
+    );
+  }
+  if (pcm16k.length === 0) return Buffer.alloc(0);
+  const r = createResampler16kTo8k();
+  const out = r.process(pcm16k);
+  const tail = r.flush();
+  return tail.length > 0 ? Buffer.concat([out, tail]) : out;
+}
+function resample24kTo16k(pcm24k) {
+  if (!_warnedResample24kTo16k) {
+    _warnedResample24kTo16k = true;
+    getLogger().warn(
+      "[patter] resample24kTo16k() is deprecated. Use createResampler24kTo16k() (StatefulResampler) or OpenAITTS.resampleStreaming for anti-aliased resampling."
+    );
+  }
+  if (pcm24k.length === 0) return Buffer.alloc(0);
+  const sampleCount = Math.floor(pcm24k.length / 2);
+  const outSamples = Math.floor(sampleCount * 2 / 3);
+  const out = Buffer.alloc(outSamples * 2);
+  for (let i = 0; i < outSamples; i++) {
+    const pos = i * 1.5;
+    const idx = Math.floor(pos);
+    const frac = pos - idx;
+    const s0 = pcm24k.readInt16LE(idx * 2);
+    const s1 = idx + 1 < sampleCount ? pcm24k.readInt16LE((idx + 1) * 2) : s0;
+    const interp = Math.round(s0 + (s1 - s0) * frac);
+    out.writeInt16LE(Math.max(-32768, Math.min(32767, interp)), i * 2);
+  }
+  return out;
+}
+
+// src/providers/openai-realtime-2.ts
+var GA_TO_V1_EVENT_NAMES = {
+  "response.output_audio.delta": "response.audio.delta",
+  "response.output_audio.done": "response.audio.done",
+  "response.output_audio_transcript.delta": "response.audio_transcript.delta",
+  "response.output_audio_transcript.done": "response.audio_transcript.done"
+};
+var OpenAIRealtime2Adapter = class extends OpenAIRealtimeAdapter {
+  /** Two-stage outbound resampler for 24 kHz → 8 kHz. Created lazily on
+   *  the first audio frame so each Realtime session has its own state.
+   *
+   *  We chain `24k → 16k → 8k` instead of using the direct `24k → 8k`
+   *  variant of {@link StatefulResampler}: the direct path is a 3:1
+   *  decimation with linear interpolation only — no anti-alias filter
+   *  — so any energy above 4 kHz in the source aliases down into the
+   *  audible band and is heard as raspy/scratchy artefacts on speech.
+   *  `gpt-realtime-2` outputs voice with significant content above
+   *  4 kHz. The second stage (16k → 8k) uses a 5-tap FIR anti-alias
+   *  filter which removes the offending band before decimation, and
+   *  empirically (see commit message) the chain produces audibly
+   *  cleaner output. The 24k → 16k step is still pure linear-interp
+   *  but the inputs to it stay below the Nyquist of the 16 kHz stage,
+   *  so it doesn't introduce new artefacts.
+   */
+  outboundResampler24To16 = null;
+  outboundResampler16To8 = null;
+  /** Last 8 kHz input sample carried across chunk boundaries for the
+   *  direct 3× linear upsample (see `transcodeInboundMulaw8ToPcm24`).
+   *  The carry guarantees the very first output of each chunk
+   *  interpolates from the *real* preceding sample, not from the chunk's
+   *  own first sample replicated — without it every 20 ms Twilio frame
+   *  boundary becomes a small DC step that the GA server VAD interprets
+   *  as constant low-energy noise, which never crosses the speech
+   *  threshold. */
+  inbound8kCarry = null;
+  /** GA-shape `session.update` payload. See module-level docstring. */
+  buildGASessionConfig() {
+    const opts = this.options;
+    const fmt = { type: "audio/pcm", rate: 24e3 };
+    const config = {
+      type: "realtime",
+      output_modalities: opts.modalities ?? ["audio"],
+      audio: {
+        input: {
+          format: fmt,
+          transcription: {
+            model: opts.inputAudioTranscriptionModel ?? OpenAITranscriptionModel.WHISPER_1
+          },
+          // VAD threshold raised back to the OpenAI default (0.5) on
+          // 2026-05-22. The earlier 0.1 tuning (motivated by the
+          // upsampled telephony-band loss in high frequencies) made the
+          // server VAD trigger on the carrier-loopback echo of the
+          // agent's OWN outbound audio in PSTN no-AEC scenarios.
+          // Combined with the default ``turn_detection.create_response:
+          // true``, every phantom ``speech_started`` ended a turn early
+          // and auto-created a new response that the agent immediately
+          // spoke over, leading to a runaway loop where the first
+          // message was repeatedly cut and re-generated.
+          turn_detection: {
+            type: opts.vadType ?? OpenAIRealtimeVADType.SERVER_VAD,
+            threshold: 0.5,
+            prefix_padding_ms: 300,
+            silence_duration_ms: opts.silenceDurationMs ?? 500,
+            // Defer ``response.create`` to the application: when OpenAI's
+            // server VAD commits an ``input_audio_buffer.committed`` segment
+            // that turns out to be a Whisper hallucination on silence/echo,
+            // auto-creating a response would generate a phantom turn (the
+            // model reads the hallucinated text as user input). Patter
+            // triggers ``response.create`` explicitly in the Realtime
+            // stream-handler AFTER validating ``transcript_input`` against
+            // the hallucination filter. Pair with ``interrupt_response:
+            // false`` so server VAD also leaves in-flight responses alone —
+            // barge-in is gated client-side.
+            create_response: false,
+            interrupt_response: false
+          }
+        },
+        output: {
+          format: fmt,
+          voice: this.voice
+        }
+      },
+      instructions: this.instructions || "You are a helpful voice assistant. Be concise."
+    };
+    if (opts.temperature !== void 0) config.temperature = opts.temperature;
+    if (opts.maxResponseOutputTokens !== void 0) {
+      config.max_output_tokens = opts.maxResponseOutputTokens;
+    }
+    if (opts.toolChoice !== void 0) config.tool_choice = opts.toolChoice;
+    if (opts.reasoningEffort !== void 0) {
+      config.reasoning = { effort: opts.reasoningEffort };
+    }
+    if (this.tools?.length) {
+      config.tools = this.tools.map((t) => {
+        const def = {
+          type: "function",
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters
+        };
+        if (t.strict === true) def.strict = true;
+        return def;
+      });
+    }
+    return config;
+  }
+  /**
+   * Open the Realtime WebSocket against the GA endpoint and apply the GA
+   * session configuration. Header `OpenAI-Beta: realtime=v1` is OMITTED
+   * (the GA endpoint rejects it). Wire shape uses nested `audio.{input,
+   * output}` + `output_modalities` + `session.type === "realtime"`.
+   */
+  async connect() {
+    const url = `wss://api.openai.com/v1/realtime?model=${encodeURIComponent(this.model)}`;
+    this.ws = new WebSocket2(url, {
+      headers: { Authorization: `Bearer ${this.apiKey}` }
+    });
+    const wsRef = this.ws;
+    const originalOn = wsRef.on.bind(this.ws);
+    wsRef.on = (event, handler) => {
+      if (event !== "message") return originalOn(event, handler);
+      const wrapped = (raw, ...rest) => {
+        try {
+          const text = typeof raw === "string" ? raw : raw.toString();
+          const parsed = JSON.parse(text);
+          const t = parsed.type;
+          if (t && t in GA_TO_V1_EVENT_NAMES) {
+            const newType = GA_TO_V1_EVENT_NAMES[t];
+            if (t === "response.output_audio.delta" && typeof parsed.delta === "string") {
+              const mulaw = this.transcodeOutboundPcm24ToMulaw8Buffer(parsed.delta);
+              const FRAME_BYTES = 160;
+              if (mulaw.length === 0) return;
+              for (let off = 0; off < mulaw.length; off += FRAME_BYTES) {
+                const slice = mulaw.subarray(off, Math.min(off + FRAME_BYTES, mulaw.length));
+                const frame = { ...parsed, type: newType, delta: slice.toString("base64") };
+                handler(Buffer.from(JSON.stringify(frame)), ...rest);
+              }
+              return;
+            }
+            parsed.type = newType;
+            handler(Buffer.from(JSON.stringify(parsed)), ...rest);
+            return;
+          }
+        } catch {
+        }
+        handler(raw, ...rest);
+      };
+      return originalOn(event, wrapped);
+    };
+    await new Promise((resolve, reject) => {
+      let sessionCreated = false;
+      let settled = false;
+      const ws = this.ws;
+      const onSetupMessage = (raw) => {
+        let msg;
+        try {
+          msg = JSON.parse(raw.toString());
+        } catch (e) {
+          getLogger().warn(`OpenAI Realtime 2: failed to parse message: ${String(e)}`);
+          return;
+        }
+        if (msg.type === "session.created" && !sessionCreated) {
+          sessionCreated = true;
+          ws.send(JSON.stringify({ type: "session.update", session: this.buildGASessionConfig() }));
+        } else if (msg.type === "session.updated") {
+          cleanup();
+          resolve();
+        } else if (msg.type === "error") {
+          cleanup();
+          try {
+            ws.close();
+          } catch {
+          }
+          reject(new Error(`OpenAI Realtime 2 setup error: ${msg.error?.message ?? JSON.stringify(msg)}`));
+        }
+      };
+      const onSetupError = (err) => {
+        cleanup();
+        try {
+          ws.close();
+        } catch {
+        }
+        reject(err);
+      };
+      const cleanup = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.off("message", onSetupMessage);
+        ws.off("error", onSetupError);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        try {
+          ws.close();
+        } catch {
+        }
+        reject(new Error("OpenAI Realtime 2 connect timeout"));
+      }, 15e3);
+      ws.on("message", onSetupMessage);
+      ws.on("error", onSetupError);
+    });
+    this.armHeartbeatAndListener();
+  }
+  /**
+   * GA-API variant of {@link OpenAIRealtimeAdapter.openParkedConnection}.
+   * Opens a fresh Realtime WS against the GA endpoint, exchanges
+   * `session.created` → GA-shape `session.update` → `session.updated`
+   * so the upstream session is fully primed, and returns the OPEN
+   * socket WITHOUT taking it on `this.ws` or arming the heartbeat /
+   * message listener.
+   *
+   * Used by `Patter.parkProviderConnections` during the carrier
+   * ringing window so the per-call `StreamHandler` can adopt the
+   * primed socket at carrier `start` — eliminating the TCP + TLS +
+   * HTTP-101 + `session.update` ack round-trip from the critical path.
+   * Saves ~300-600 ms of first-audible-word latency.
+   *
+   * Bounded by 8 s. Throws on timeout / handshake failure / GA-side
+   * rejection. Callers treat any error as a cache miss and fall
+   * through to the cold {@link connect} path.
+   *
+   * Billing safety: confirmed by OpenAI's Managing Realtime Costs
+   * guide — `session.update` does NOT invoke the model and bills no
+   * tokens. An idle parked socket costs $0.
+   */
+  async openParkedConnection() {
+    const url = `wss://api.openai.com/v1/realtime?model=${encodeURIComponent(this.model)}`;
+    const ws = new WebSocket2(url, {
+      headers: { Authorization: `Bearer ${this.apiKey}` }
+    });
+    await new Promise((resolve, reject) => {
+      let sessionCreated = false;
+      let settled = false;
+      const onMessage = (raw) => {
+        let msg;
+        try {
+          msg = JSON.parse(raw.toString());
+        } catch {
+          return;
+        }
+        if (msg.type === "session.created" && !sessionCreated) {
+          sessionCreated = true;
+          try {
+            ws.send(JSON.stringify({ type: "session.update", session: this.buildGASessionConfig() }));
+          } catch (err) {
+            cleanup();
+            reject(err instanceof Error ? err : new Error(String(err)));
+          }
+        } else if (msg.type === "session.updated") {
+          cleanup();
+          resolve();
+        } else if (msg.type === "error") {
+          cleanup();
+          reject(new Error(`OpenAI Realtime 2 parked-setup error: ${msg.error?.message ?? JSON.stringify(msg)}`));
+        }
+      };
+      const onError = (err) => {
+        cleanup();
+        reject(err);
+      };
+      const cleanup = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.off("message", onMessage);
+        ws.off("error", onError);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error("OpenAI Realtime 2 park connect timeout"));
+      }, 8e3);
+      ws.on("message", onMessage);
+      ws.on("error", onError);
+    });
+    const keepalive = setInterval(() => {
+      if (ws.readyState !== ws.OPEN) {
+        clearInterval(keepalive);
+        return;
+      }
+      try {
+        ws.send(JSON.stringify({ type: "session.update", session: this.buildGASessionConfig() }));
+      } catch {
+        clearInterval(keepalive);
+      }
+    }, 3e3);
+    ws._parkedKeepalive = keepalive;
+    return ws;
+  }
+  /**
+   * GA-API variant of {@link OpenAIRealtimeAdapter.adoptWebSocket}. Takes
+   * over a WS that {@link openParkedConnection} produced (already through
+   * `session.created` + `session.update` + `session.updated`) and arms
+   * the heartbeat + message listener so the GA event-translation shim
+   * is wired up. Skips the cold-connect path — saves ~300-600 ms on
+   * first audible word.
+   *
+   * Caller MUST verify `ws.readyState === OPEN` before calling. If the
+   * parked WS died between park and adopt, fall back to {@link connect}.
+   */
+  adoptWebSocket(ws) {
+    const wsAny = ws;
+    if (wsAny._parkedKeepalive) {
+      clearInterval(wsAny._parkedKeepalive);
+      delete wsAny._parkedKeepalive;
+    }
+    this.ws = ws;
+    const wsRef = ws;
+    const originalOn = wsRef.on.bind(ws);
+    wsRef.on = (event, handler) => {
+      if (event !== "message") return originalOn(event, handler);
+      const wrapped = (raw, ...rest) => {
+        try {
+          const text = typeof raw === "string" ? raw : raw.toString();
+          const parsed = JSON.parse(text);
+          const t = parsed.type;
+          if (t && Object.prototype.hasOwnProperty.call(GA_TO_V1_EVENT_NAMES, t)) {
+            parsed.type = GA_TO_V1_EVENT_NAMES[t];
+            handler(JSON.stringify(parsed), ...rest);
+            return;
+          }
+        } catch {
+        }
+        handler(raw, ...rest);
+      };
+      return originalOn(event, wrapped);
+    };
+    this.armHeartbeatAndListener();
+  }
+  /**
+   * GA-API variant of {@link OpenAIRealtimeAdapter.sendFirstMessage}. Two
+   * differences from the v1 path:
+   *
+   * 1. The v1 implementation sends `response.modalities` which the GA
+   *    endpoint rejects with `Unknown parameter: 'response.modalities'`.
+   *    Use `output_modalities` to match the GA `session.update` shape.
+   *
+   * 2. The GA `response.create` does NOT inherit `audio.output.voice`
+   *    from the session — it falls back to the server-side default
+   *    (`marin`, female) when the field is omitted on the response
+   *    itself. Session-level `voice: "alloy"` only affects subsequent
+   *    server-VAD-triggered responses, NOT this explicit
+   *    `response.create`. We re-inject the configured voice here so the
+   *    first-message voice matches the rest of the call.
+   */
+  /**
+   * Override the parent `sendAudio` to transcode inbound carrier audio
+   * (mulaw 8 kHz from Twilio/Telnyx) into PCM-16 24 kHz before sending
+   * `input_audio_buffer.append`. The GA server's audio engine ignores
+   * mulaw frames (commit returns "buffer only has 0.00ms of audio") even
+   * though it accepts `audio/pcmu` at the protocol level.
+   */
+  sendAudio(mulawAudio) {
+    if (!this.ws || this.ws.readyState !== this.ws.OPEN) return;
+    const pcm24k = this.transcodeInboundMulaw8ToPcm24(mulawAudio);
+    this.ws.send(JSON.stringify({
+      type: "input_audio_buffer.append",
+      audio: pcm24k.toString("base64")
+    }));
+  }
+  /**
+   * mulaw 8 kHz Buffer → PCM-16-LE 24 kHz Buffer.
+   *
+   * Direct 3× linear-interpolation upsample with a one-sample carry
+   * across chunk boundaries. For every consecutive pair of 8 kHz
+   * samples `(s_a, s_b)` we emit three 24 kHz samples:
+   *
+   *     out_0 = s_a
+   *     out_1 = 2/3·s_a + 1/3·s_b
+   *     out_2 = 1/3·s_a + 2/3·s_b
+   *
+   * The carry stores the last 8 kHz sample of the chunk so the next
+   * chunk can start by pairing `(carry, firstNewSample)` — that's what
+   * keeps the output rate exact (each input sample → 3 output samples)
+   * and eliminates the chunk-boundary DC step that confused the GA
+   * server VAD. The first chunk has no carry and loses 3 samples at
+   * the leading edge (375 µs of audio); that's well below any audible
+   * artefact and well below the GA VAD's 300 ms prefix-padding window.
+   */
+  transcodeInboundMulaw8ToPcm24(mulaw) {
+    const pcm8 = mulawToPcm16(mulaw);
+    const samples8 = pcm8.length / 2;
+    if (samples8 === 0) return Buffer.alloc(0);
+    const GAIN = 2;
+    const inputs = [];
+    if (this.inbound8kCarry !== null) inputs.push(this.inbound8kCarry);
+    for (let i = 0; i < samples8; i++) {
+      const raw = pcm8.readInt16LE(i * 2) * GAIN;
+      inputs.push(Math.max(-32768, Math.min(32767, raw)));
+    }
+    this.inbound8kCarry = inputs[inputs.length - 1];
+    const numPairs = inputs.length - 1;
+    if (numPairs <= 0) return Buffer.alloc(0);
+    const out = Buffer.allocUnsafe(numPairs * 3 * 2);
+    for (let i = 0; i < numPairs; i++) {
+      const s0 = inputs[i];
+      const s1 = inputs[i + 1];
+      out.writeInt16LE(s0, i * 6);
+      out.writeInt16LE(Math.round((s0 * 2 + s1) / 3), i * 6 + 2);
+      out.writeInt16LE(Math.round((s0 + s1 * 2) / 3), i * 6 + 4);
+    }
+    return out;
+  }
+  /**
+   * Base64 PCM-16-LE 24 kHz → Base64 mulaw 8 kHz. Used by the WS
+   * translation shim on each `response.output_audio.delta`. The stateful
+   * resampler is created lazily and reused across all deltas in this
+   * session so the 3:1 decimator's phase carries across chunk
+   * boundaries — without that, every chunk boundary produces a click.
+   */
+  transcodeOutboundPcm24ToMulaw8Buffer(deltaB64) {
+    if (!this.outboundResampler24To16) {
+      this.outboundResampler24To16 = new StatefulResampler({ srcRate: 24e3, dstRate: 16e3 });
+      this.outboundResampler16To8 = new StatefulResampler({ srcRate: 16e3, dstRate: 8e3 });
+    }
+    const pcm24 = Buffer.from(deltaB64, "base64");
+    const pcm16 = this.outboundResampler24To16.process(pcm24);
+    const pcm8 = this.outboundResampler16To8.process(pcm16);
+    if (pcm8.length === 0) return Buffer.alloc(0);
+    return pcm16ToMulaw(pcm8);
+  }
+  async sendFirstMessage(text) {
+    const responseBody = {
+      output_modalities: ["audio"],
+      audio: { output: { voice: this.voice } },
+      instructions: `Say exactly the following sentence as your first turn and nothing else: "${text}"`
+    };
+    if (this.options.reasoningEffort !== void 0) {
+      responseBody.reasoning = { effort: this.options.reasoningEffort };
+    }
+    this.ws?.send(JSON.stringify({ type: "response.create", response: responseBody }));
+  }
+};
+
+export {
+  OpenAIRealtimeAudioFormat,
+  OpenAIRealtimeModel,
+  OpenAIVoice,
+  OpenAITranscriptionModel,
+  OpenAIRealtimeVADType,
+  OpenAIRealtimeAdapter,
+  mulawToPcm16,
+  pcm16ToMulaw,
+  PcmCarry,
+  StatefulResampler,
+  createResampler16kTo8k,
+  createResampler8kTo16k,
+  createResampler24kTo16k,
+  createResampler24kTo8k,
+  resample8kTo16k,
+  resample16kTo8k,
+  resample24kTo16k,
+  OpenAIRealtime2Adapter
+};