@cohortapp/agent-sdk 2.3.0

package/lib/voice/index.mjs

@@ -0,0 +1,100 @@
+/**
+ * Maestro — Voice subsystem (provider-agnostic facade)
+ *
+ * Exports the `VoiceProvider` interface and the concrete implementations
+ * we ship. Today: OpenAI Realtime. Tomorrow: Gemini Live, Claude Voice
+ * (when GA). The interface is small on purpose:
+ *
+ *   connect(session)               → opens the upstream session
+ *   appendAudio(pcm16Chunk)        → streams an audio chunk to the model
+ *   commitTurn()                   → tells the model the user's turn is over
+ *   interrupt()                    → barge-in: stop current model output
+ *   sendToolResult(callId, output) → returns a tool-call result + resumes
+ *   sendText(text)                 → optional: send user text directly
+ *   close()                        → tear the session down
+ *   on(event, handler)             → audio.delta, transcript.delta, tool.call, …
+ *
+ * The maestro daemon never imports this directly; instead, the
+ * `voice-handler.mjs` daemon worker creates a provider via createProvider()
+ * and pipes between the channel (Twilio SIP, browser WebRTC, etc.) and the
+ * provider. That keeps the audio plumbing out of the core daemon and makes
+ * the provider swappable per agent.
+ */
+
+import { VoiceProvider, VOICE_EVENTS } from "./provider.mjs";
+import { createOpenAIRealtimeProvider } from "./openai-realtime.mjs";
+
+export { VoiceProvider, VOICE_EVENTS };
+
+/**
+ * Factory for the configured provider. Reads `provider` from the session
+ * config and instantiates the matching implementation. Used by the
+ * daemon's voice worker so we never hard-code OpenAI.
+ *
+ * Supported provider names:
+ *   "openai-realtime" (default) → OpenAI gpt-realtime-2 over WebSocket
+ *   "openai-realtime-webrtc"     → same model, WebRTC transport
+ *   "gemini-live"                → stub (throws not_implemented)
+ *
+ * @param {string} name
+ * @param {object} opts
+ * @returns {VoiceProvider}
+ */
+export function createProvider(name, opts = {}) {
+  switch ((name || "openai-realtime").toLowerCase()) {
+    case "openai-realtime":
+    case "openai-realtime-ws":
+      return createOpenAIRealtimeProvider({ transport: "ws", ...opts });
+    case "openai-realtime-webrtc":
+      return createOpenAIRealtimeProvider({ transport: "webrtc", ...opts });
+    case "gemini-live":
+      throw new Error("provider 'gemini-live' is stubbed — see lib/voice/gemini-live.mjs (planned 1.13.0)");
+    case "claude-voice":
+      throw new Error("provider 'claude-voice' is unavailable — Anthropic has not yet shipped a streaming voice API");
+    default:
+      throw new Error(`unknown voice provider: ${name}`);
+  }
+}
+
+/**
+ * Helper: build a Realtime session config from a partial spec + agent
+ * identity. Centralises the defaults so every caller doesn't reinvent
+ * them.
+ */
+export function buildSessionConfig(partial = {}, identity = {}) {
+  const voice = partial.voice || "cedar"; // GA-only voice from May 2026 launch
+  const instructions = partial.instructions ||
+    `You are ${identity.name || "this agent"}, ${identity.role || "an executive operator"} at ${identity.company || "the company"}. ` +
+    `Reply briefly in ${identity.name || "first-person"} voice. Honour the same action-classification policy as the Slack/Gmail channels — verbally confirm any high-risk action before invoking its tool.`;
+  return {
+    type: "realtime",
+    model: partial.model || "gpt-realtime-2",
+    output_modalities: partial.output_modalities || ["audio"],
+    instructions,
+    voice,
+    input_audio_format: partial.input_audio_format || "pcm16",
+    output_audio_format: partial.output_audio_format || "pcm16",
+    input_audio_transcription: partial.input_audio_transcription ?? {
+      model: "gpt-realtime-whisper",
+    },
+    turn_detection: partial.turn_detection ?? {
+      type: "server_vad",
+      threshold: 0.5,
+      prefix_padding_ms: 300,
+      silence_duration_ms: 500,
+    },
+    tools: partial.tools || [],
+    tool_choice: partial.tool_choice || "auto",
+  };
+}
+
+export { createOpenAIRealtimeProvider } from "./openai-realtime.mjs";
+export { actionsToRealtimeTools, registerToolBridge } from "./tool-bridge.mjs";
+export { rotateSessionIfStale, SESSION_ROTATION_DEFAULTS } from "./session-rotation.mjs";
+
+export default {
+  VoiceProvider,
+  VOICE_EVENTS,
+  createProvider,
+  buildSessionConfig,
+};

package/lib/voice/openai-realtime.mjs

@@ -0,0 +1,510 @@
+/**
+ * Maestro — OpenAI Realtime voice provider (May 2026 GA)
+ *
+ * Thin, typed-by-convention wrapper around OpenAI's Realtime API. Emits
+ * the events declared in `lib/voice/index.mjs:VOICE_EVENTS` so the daemon's
+ * voice worker can stay provider-agnostic.
+ *
+ * Two transports:
+ *   - WebSocket  (server-side agents)   — wss://api.openai.com/v1/realtime
+ *   - WebRTC     (browser/low-latency)  — POST /v1/realtime/calls
+ *
+ * Audio is PCM16 mono @ 24 kHz on the WebSocket path; WebRTC negotiates
+ * Opus automatically. For µ-law (Twilio Voice / SIP bridges), set the
+ * session input/output audio_format to "g711_ulaw" and route µ-law
+ * frames through directly — no resampling on our side.
+ *
+ * Implementation notes:
+ *   - We don't take a hard dependency on the `openai` npm package. If it
+ *     is installed, we use its typed OpenAIRealtimeWS helper. Otherwise we
+ *     fall back to a thin `ws` client. Either way, the public interface
+ *     here is identical.
+ *   - For barge-in (user interrupts the agent), the caller MUST emit
+ *     `interrupt()` from a USER_SPEECH_STARTED handler, AND must track how
+ *     many ms of agent audio actually played before the interruption so
+ *     `conversation.item.truncate` can keep the model's internal
+ *     transcript in sync with what the human heard. Skipping the truncate
+ *     is the #1 production bug per the OpenAI docs.
+ *
+ * Auth:
+ *   - OPENAI_API_KEY (required)
+ *   - OPENAI_SAFETY_IDENTIFIER (optional; hashed user ID for safety telemetry)
+ *
+ * Refs:
+ *   https://developers.openai.com/api/docs/guides/realtime-conversations
+ *   https://developers.openai.com/api/docs/guides/realtime-vad
+ */
+
+import { VoiceProvider, VOICE_EVENTS } from "./provider.mjs";
+
+export const OPENAI_REALTIME_WS_URL = "wss://api.openai.com/v1/realtime";
+export const OPENAI_REALTIME_DEFAULT_MODEL = "gpt-realtime-2";
+
+// WebSocket.readyState OPEN value (same for browser WebSocket and the `ws`
+// package). We compare numerically rather than importing a constructor so the
+// SDK / `ws` / injected-fake socket paths all work uniformly.
+const WS_OPEN = 1;
+
+// Default backpressure ceiling (bytes). When socket.bufferedAmount climbs above
+// this, the kernel/ws send buffer is backing up faster than the wire can drain
+// — typically because the upstream stalled. Rather than queueing unbounded
+// audio (which adds latency the user hears as lag and can OOM a long call), we
+// drop new *audio append* frames until the buffer drains (drop-oldest-style for
+// a live stream). Control frames are never dropped. Tunable via
+// opts.maxBufferedBytes. 0 disables the check.
+const DEFAULT_MAX_BUFFERED_BYTES = 1 << 20; // 1 MiB
+
+// Lazy-load WebSocket. We prefer the official `openai` SDK helper if
+// available, but fall back to plain `ws` so the framework doesn't force
+// the user to install a new dependency until they actually opt in.
+async function loadWsCtor() {
+  try {
+    const sdk = await import("openai/realtime/ws");
+    return { type: "sdk", ctor: sdk.OpenAIRealtimeWS };
+  } catch { /* fall through */ }
+  try {
+    const wsMod = await import("ws");
+    const WebSocket = wsMod.default || wsMod.WebSocket;
+    return { type: "ws", ctor: WebSocket };
+  } catch (err) {
+    throw new Error(
+      "Neither `openai/realtime/ws` nor `ws` is installed. " +
+        "Install one: `npm i openai` (recommended) or `npm i ws`."
+    );
+  }
+}
+
+class OpenAIRealtimeProvider extends VoiceProvider {
+  constructor(opts = {}) {
+    super(opts);
+    this.transport = opts.transport || "ws";
+    this.model = opts.model || OPENAI_REALTIME_DEFAULT_MODEL;
+    this.apiKey = opts.apiKey || process.env.OPENAI_API_KEY;
+    this.safetyIdentifier = opts.safetyIdentifier || process.env.OPENAI_SAFETY_IDENTIFIER;
+    this.socket = null;       // underlying WS instance
+    this.sessionConfig = null;
+    this.sessionId = null;    // server-assigned session id
+    this.responseId = null;   // current in-flight response (if any)
+    this.lastAgentAudioStartedAt = null; // ms since-connect when agent started speaking
+    this.lastAgentAudioPlayedMs = 0;     // ms of agent audio the user has heard
+    this._connectedAt = null;
+    this._turnAudioStartedAt = null;
+
+    // ── Reconnect / upstream-drop handling (H4) ──────────────────────────
+    // close() flips this so _onClose can tell a deliberate client close
+    // apart from an unexpected upstream socket drop. Only the latter
+    // triggers a bounded reconnect.
+    this._clientClosed = false;
+    this._reconnecting = false;
+    this._reconnectAttempts = 0;
+    this.maxReconnectAttempts = opts.maxReconnectAttempts ?? 3;
+    this.reconnectBaseDelayMs = opts.reconnectBaseDelayMs ?? 250;
+    // Seams so tests can drive reconnect without real sockets/timers.
+    this._setTimeout = opts.setTimeout || setTimeout;
+    this._clearTimeout = opts.clearTimeout || clearTimeout;
+    this._reconnectTimer = null;
+    // Optional injected WebSocket constructor — when provided, _connectWebSocket
+    // uses it instead of dynamically loading `openai`/`ws`. Lets tests drive a
+    // fake socket with no real network. Shape: (url, { headers }) => socketLike.
+    this._wsCtorOverride = opts.wsCtor || null;
+
+    // ── Backpressure (L12) ───────────────────────────────────────────────
+    // Ceiling on socket.bufferedAmount before we start dropping *audio* frames.
+    // Control frames (session.update, response.*, tool results) always go out.
+    this.maxBufferedBytes = opts.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+    // Count of audio frames dropped due to backpressure / non-open socket, for
+    // observability. Not part of any wire protocol.
+    this.droppedAudioFrames = 0;
+  }
+
+  /** Open the upstream session. Awaits the server's session.created event. */
+  async connect(sessionConfig) {
+    if (this.state !== "idle" && this.state !== "closed") {
+      throw new Error(`connect() called from invalid state: ${this.state}`);
+    }
+    if (!this.apiKey) {
+      throw new Error("OPENAI_API_KEY not set");
+    }
+    this.sessionConfig = sessionConfig;
+
+    if (this.transport === "ws") {
+      await this._connectWebSocket();
+    } else if (this.transport === "webrtc") {
+      throw new Error("WebRTC transport in this provider is not wired in yet — use 'ws' for server-side agents");
+    } else {
+      throw new Error(`unknown transport: ${this.transport}`);
+    }
+
+    // Send the initial session.update so the model knows our voice / tools / VAD.
+    this._send({
+      type: "session.update",
+      session: sessionConfig,
+    });
+    this.state = "connected";
+    this.emit(VOICE_EVENTS.CONNECTED, { transport: this.transport, model: this.model });
+  }
+
+  _connectWebSocket() {
+    const loader = this._wsCtorOverride
+      ? Promise.resolve({ type: "factory", ctor: this._wsCtorOverride })
+      : loadWsCtor();
+    return loader.then(({ type, ctor }) => {
+      return new Promise((resolve, reject) => {
+        const url = `${OPENAI_REALTIME_WS_URL}?model=${encodeURIComponent(this.model)}`;
+        const headers = {
+          Authorization: `Bearer ${this.apiKey}`,
+          "OpenAI-Beta": "realtime=v1",
+        };
+        if (this.safetyIdentifier) {
+          headers["OpenAI-Safety-Identifier"] = this.safetyIdentifier;
+        }
+
+        let socket;
+        if (type === "sdk") {
+          // The official OpenAIRealtimeWS instance manages its own WebSocket;
+          // its .socket property is the raw WS. We wire to the underlying.
+          const rt = new ctor({ model: this.model, apiKey: this.apiKey });
+          socket = rt.socket;
+          this._sdkRt = rt;
+        } else if (type === "factory") {
+          // Injected socket factory (tests): called as a plain function,
+          // NOT with `new`, so a fake socket can be returned directly.
+          socket = ctor(url, { headers });
+        } else {
+          socket = new ctor(url, { headers });
+        }
+
+        this.socket = socket;
+        this._connectedAt = Date.now();
+
+        const onOpen = () => resolve();
+        const onError = (err) => reject(err instanceof Error ? err : new Error(String(err?.message || err)));
+        if (typeof socket.addEventListener === "function") {
+          socket.addEventListener("open", onOpen, { once: true });
+          socket.addEventListener("error", onError, { once: true });
+        } else {
+          socket.once?.("open", onOpen);
+          socket.once?.("error", onError);
+        }
+
+        const handleMessage = (raw) => this._onServerEvent(raw);
+        if (typeof socket.addEventListener === "function") {
+          socket.addEventListener("message", (evt) => handleMessage(evt.data));
+          socket.addEventListener("close", (evt) => this._onClose(evt.reason || "closed"));
+          socket.addEventListener("error", (evt) => this.emit(VOICE_EVENTS.ERROR, evt));
+        } else {
+          socket.on?.("message", handleMessage);
+          socket.on?.("close", (code, reason) => this._onClose(reason || `code ${code}`));
+          socket.on?.("error", (err) => this.emit(VOICE_EVENTS.ERROR, err));
+        }
+      });
+    });
+  }
+
+  /** Stream PCM16 audio (base64-encoded chunk OR raw Buffer/Uint8Array). */
+  appendAudio(pcm16) {
+    if (this.state !== "connected" && this.state !== "speaking" && this.state !== "listening") return;
+    // Backpressure: if the socket's send buffer is already backed up, drop this
+    // audio frame instead of queueing it. Audio is a live stream — a stale
+    // chunk delivered late is worse than a dropped one, and unbounded queueing
+    // adds audible latency and can exhaust memory on a long stalled call. Only
+    // audio is shed; control frames in _send() are never dropped.
+    if (this._isBackpressured()) {
+      this.droppedAudioFrames += 1;
+      return;
+    }
+    const b64 = typeof pcm16 === "string" ? pcm16 : Buffer.from(pcm16).toString("base64");
+    this._send({ type: "input_audio_buffer.append", audio: b64 });
+  }
+
+  /**
+   * True when the underlying socket is not OPEN, or its send buffer has grown
+   * past maxBufferedBytes (i.e. we're writing faster than the wire drains).
+   * Robust to fake/SDK sockets that don't expose readyState/bufferedAmount.
+   * @returns {boolean}
+   */
+  _isBackpressured() {
+    const s = this.socket;
+    if (!s) return true;
+    if (typeof s.readyState === "number" && s.readyState !== WS_OPEN) return true;
+    if (
+      this.maxBufferedBytes > 0 &&
+      typeof s.bufferedAmount === "number" &&
+      s.bufferedAmount > this.maxBufferedBytes
+    ) {
+      return true;
+    }
+    return false;
+  }
+
+  /** Commit the current audio buffer as one user turn. */
+  commitTurn() {
+    this._send({ type: "input_audio_buffer.commit" });
+    this._send({ type: "response.create" }); // ask the model to respond
+  }
+
+  /** Send a text-only user message (no audio). */
+  sendText(text) {
+    this._send({
+      type: "conversation.item.create",
+      item: {
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text }],
+      },
+    });
+    this._send({ type: "response.create" });
+  }
+
+  /**
+   * Barge-in. The caller passes the number of milliseconds of agent audio
+   * the user actually heard before interrupting; we truncate the model's
+   * server-side conversation item to match so subsequent turns don't
+   * "remember" content the human never heard.
+   */
+  interrupt(opts = {}) {
+    const playedMs = Number(opts.playedMs ?? this.lastAgentAudioPlayedMs ?? 0);
+    if (this.responseId) {
+      this._send({ type: "response.cancel" });
+    }
+    if (opts.itemId && playedMs > 0) {
+      this._send({
+        type: "conversation.item.truncate",
+        item_id: opts.itemId,
+        content_index: 0,
+        audio_end_ms: playedMs,
+      });
+    }
+    this.responseId = null;
+  }
+
+  /**
+   * Return a tool-call result and resume the model. Output must be a
+   * JSON-serialisable value (object or scalar) — we stringify it for you.
+   */
+  sendToolResult(callId, output) {
+    if (!callId) throw new Error("sendToolResult requires a call_id");
+    this._send({
+      type: "conversation.item.create",
+      item: {
+        type: "function_call_output",
+        call_id: callId,
+        output: typeof output === "string" ? output : JSON.stringify(output),
+      },
+    });
+    this._send({ type: "response.create" });
+  }
+
+  /** Close the upstream session cleanly. */
+  close(reason) {
+    // Mark this as a deliberate, client-initiated close so an ensuing
+    // socket 'close' event is NOT treated as an upstream drop (H4).
+    this._clientClosed = true;
+    if (this._reconnectTimer) {
+      try { this._clearTimeout(this._reconnectTimer); } catch { /* */ }
+      this._reconnectTimer = null;
+    }
+    this._reconnecting = false;
+    if (this.state === "closed") return;
+    try { this.socket?.close?.(); } catch { /* ignore */ }
+    this.state = "closed";
+    this.emit(VOICE_EVENTS.CLOSED, { reason: reason || "client_close" });
+  }
+
+  // ── Internals ────────────────────────────────────────────────────────────
+
+  _send(payload) {
+    const s = this.socket;
+    if (!s || this.state === "closed") return;
+    // Don't write to a socket that isn't OPEN (CONNECTING / CLOSING / CLOSED):
+    // socket.send() would otherwise throw on the `ws` package. We still allow
+    // sends in the "reconnecting" state because _attemptReconnect re-seeds
+    // session.update on a freshly-opened socket (readyState OPEN) before
+    // flipping state back to "connected". Fake/SDK sockets without a numeric
+    // readyState fall through to the send (preserving existing behaviour).
+    if (typeof s.readyState === "number" && s.readyState !== WS_OPEN) return;
+    try {
+      s.send(JSON.stringify(payload));
+    } catch (err) {
+      this.emit(VOICE_EVENTS.ERROR, err);
+    }
+  }
+
+  _onClose(reason) {
+    // A deliberate client close() — keep the existing behaviour: tear down
+    // and emit CLOSED exactly once. close() already set state=closed and
+    // emitted CLOSED, so don't double-emit.
+    if (this._clientClosed) {
+      this.state = "closed";
+      return;
+    }
+    // Unexpected upstream drop. Don't silently flip to "closed" (which would
+    // make appendAudio/_send early-return → dead air). Attempt a bounded
+    // reconnect; only on exhaustion do we tear down deterministically (H4).
+    this._scheduleReconnect(reason);
+  }
+
+  /**
+   * Schedule a bounded reconnect after an upstream drop. Backs off
+   * exponentially from reconnectBaseDelayMs. On exhaustion, tears down
+   * deterministically with a clear error + CLOSED event rather than going
+   * silent. No-ops if a client close() already happened.
+   */
+  _scheduleReconnect(reason) {
+    if (this._clientClosed) return;
+    if (this._reconnecting) return; // a reconnect cycle is already in flight
+    if (this._reconnectAttempts >= this.maxReconnectAttempts) {
+      this._failReconnect(reason);
+      return;
+    }
+    this._reconnecting = true;
+    this.state = "reconnecting";
+    const attempt = this._reconnectAttempts + 1;
+    const delay = this.reconnectBaseDelayMs * Math.pow(2, this._reconnectAttempts);
+    this.emit(VOICE_EVENTS.ERROR, new Error(
+      `upstream session dropped (${reason}); reconnect attempt ${attempt}/${this.maxReconnectAttempts} in ${delay}ms`,
+    ));
+    this._reconnectTimer = this._setTimeout(() => {
+      this._reconnectTimer = null;
+      this._attemptReconnect(reason);
+    }, delay);
+    if (this._reconnectTimer && typeof this._reconnectTimer.unref === "function") {
+      this._reconnectTimer.unref();
+    }
+  }
+
+  /** Perform one reconnect attempt: reopen WS + re-send the stored config. */
+  async _attemptReconnect(reason) {
+    if (this._clientClosed) { this._reconnecting = false; return; }
+    this._reconnectAttempts += 1;
+    try {
+      this.socket = null;
+      await this._connectWebSocket();
+      // Re-seed the new socket with the session config the model needs.
+      if (this.sessionConfig) {
+        this._send({ type: "session.update", session: this.sessionConfig });
+      }
+      // Back to a live state — clear the reconnect bookkeeping.
+      this.state = "connected";
+      this._reconnecting = false;
+      this._reconnectAttempts = 0;
+      this.emit(VOICE_EVENTS.CONNECTED, {
+        transport: this.transport,
+        model: this.model,
+        reconnected: true,
+      });
+    } catch (err) {
+      // This attempt failed — schedule the next one (or fail if exhausted).
+      this._reconnecting = false;
+      if (this._reconnectAttempts >= this.maxReconnectAttempts) {
+        this._failReconnect(err?.message || reason);
+      } else {
+        this._scheduleReconnect(err?.message || reason);
+      }
+    }
+  }
+
+  /** Give up after exhausting reconnects: deterministic teardown + error. */
+  _failReconnect(reason) {
+    this._reconnecting = false;
+    if (this._reconnectTimer) {
+      try { this._clearTimeout(this._reconnectTimer); } catch { /* */ }
+      this._reconnectTimer = null;
+    }
+    this.state = "closed";
+    this.emit(VOICE_EVENTS.ERROR, new Error(
+      `upstream session lost and reconnect exhausted after ${this.maxReconnectAttempts} attempts (${reason})`,
+    ));
+    this.emit(VOICE_EVENTS.CLOSED, { reason: `upstream_drop_reconnect_exhausted: ${reason}` });
+  }
+
+  _onServerEvent(raw) {
+    let evt;
+    try {
+      evt = typeof raw === "string" ? JSON.parse(raw) : JSON.parse(Buffer.from(raw).toString("utf-8"));
+    } catch (err) {
+      this.emit(VOICE_EVENTS.ERROR, new Error(`bad server frame: ${err.message}`));
+      return;
+    }
+    // Re-emit using our normalised event names. We pass through anything
+    // unrecognised under its native `type` so downstream consumers can
+    // still observe vendor-specific events.
+    switch (evt.type) {
+      case "session.created":
+        this.sessionId = evt.session?.id || null;
+        this.emit(VOICE_EVENTS.SESSION_CREATED, evt.session || {});
+        break;
+      case "input_audio_buffer.speech_started":
+        this.emit(VOICE_EVENTS.USER_SPEECH_STARTED, evt);
+        break;
+      case "input_audio_buffer.speech_stopped":
+        this.emit(VOICE_EVENTS.USER_SPEECH_STOPPED, evt);
+        break;
+      case "response.created":
+        this.responseId = evt.response?.id || null;
+        break;
+      case "response.audio.delta":
+        if (!this._turnAudioStartedAt) this._turnAudioStartedAt = Date.now();
+        this.emit(VOICE_EVENTS.AUDIO_DELTA, {
+          delta: evt.delta,
+          item_id: evt.item_id,
+          response_id: evt.response_id,
+        });
+        break;
+      case "response.audio.done":
+        this._turnAudioStartedAt = null;
+        this.emit(VOICE_EVENTS.AUDIO_DONE, evt);
+        break;
+      case "response.audio_transcript.delta":
+      case "response.output_text.delta":
+        this.emit(VOICE_EVENTS.TRANSCRIPT_DELTA, {
+          delta: evt.delta,
+          role: evt.type.includes("audio_transcript") ? "assistant_voice" : "assistant_text",
+          item_id: evt.item_id,
+          response_id: evt.response_id,
+        });
+        break;
+      case "response.audio_transcript.done":
+      case "response.output_text.done":
+        this.emit(VOICE_EVENTS.TRANSCRIPT_DONE, evt);
+        break;
+      case "response.function_call_arguments.delta":
+        this.emit(VOICE_EVENTS.TOOL_CALL_DELTA, {
+          call_id: evt.call_id,
+          name: evt.name,
+          delta: evt.delta,
+        });
+        break;
+      case "response.function_call_arguments.done":
+        this.emit(VOICE_EVENTS.TOOL_CALL, {
+          call_id: evt.call_id,
+          name: evt.name,
+          arguments: safeParseJson(evt.arguments),
+          response_id: evt.response_id,
+        });
+        break;
+      case "response.done":
+        this.responseId = null;
+        this.emit(VOICE_EVENTS.TURN_DONE, evt.response || {});
+        break;
+      case "error":
+        this.emit(VOICE_EVENTS.ERROR, new Error(evt.error?.message || "unknown"));
+        break;
+      default:
+        // Surface as a generic event so callers wanting raw access can subscribe.
+        this.emit(evt.type, evt);
+    }
+  }
+}
+
+function safeParseJson(s) {
+  if (typeof s !== "string") return s;
+  try { return JSON.parse(s); } catch { return { _raw: s }; }
+}
+
+export function createOpenAIRealtimeProvider(opts = {}) {
+  return new OpenAIRealtimeProvider(opts);
+}
+
+export { OpenAIRealtimeProvider };
+export default createOpenAIRealtimeProvider;