@crewhaus/voice-runtime 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/dist/index.js +58 -9
  2. package/package.json +2 -2
package/dist/index.js CHANGED
@@ -35,10 +35,38 @@ export class VoiceRuntimeError extends CrewhausError {
35
35
  }
36
36
  }
37
37
  // ---------------------------------------------------------------------------
38
- // OpenAI Realtime adapter — speaks the v1 WebSocket protocol.
38
+ // OpenAI Realtime adapter — speaks the GA `/v1/realtime` WebSocket protocol.
39
+ //
40
+ // The beta interface (`OpenAI-Beta: realtime=v1` upgrade header + the flat
41
+ // `session.update` shape) is RETIRED server-side: connecting with it closes
42
+ // the socket with code 4000 / `invalid_request_error.beta_api_shape_disabled`
43
+ // and the error event "The Realtime Beta API is no longer supported. Please
44
+ // use /v1/realtime for the GA API." The GA differences this adapter honours:
45
+ //
46
+ // - no `OpenAI-Beta` header (sending it is what triggers the beta shape)
47
+ // - `session.type: "realtime"` is required
48
+ // - `modalities` → `output_modalities`, and text+audio may NOT be combined
49
+ // (audio output still emits transcript events, so `["audio"]` gives us
50
+ // both halves of this adapter's event surface)
51
+ // - `input_audio_format`/`output_audio_format` string enums → nested
52
+ // `audio.input.format` / `audio.output.format` objects
53
+ // - `voice` → `audio.output.voice`; `turn_detection` → `audio.input.turn_detection`
54
+ // - server events renamed: `response.audio.delta` →
55
+ // `response.output_audio.delta`, `response.audio_transcript.{delta,done}`
56
+ // → `response.output_audio_transcript.{delta,done}`
57
+ //
58
+ // The READ path still accepts the legacy event names as aliases — they cost
59
+ // three case labels and keep the adapter usable against a gateway or proxy
60
+ // (`opts.url`) that has not finished its own migration. The WRITE path is GA
61
+ // only: there is no live endpoint left that accepts the beta payload, so a
62
+ // "speak beta" toggle would be dead configuration.
39
63
  // ---------------------------------------------------------------------------
40
64
  const OPENAI_REALTIME_SAMPLE_RATE = 24_000;
41
- const DEFAULT_OPENAI_REALTIME_MODEL = "gpt-4o-realtime-preview";
65
+ /**
66
+ * GA model alias. The beta-era `gpt-4o-realtime-preview` was removed from
67
+ * the API in March 2026 — it is not a valid fallback any more.
68
+ */
69
+ const DEFAULT_OPENAI_REALTIME_MODEL = "gpt-realtime";
42
70
  const DEFAULT_OPENAI_REALTIME_URL = "wss://api.openai.com/v1/realtime";
43
71
  export function createOpenAIRealtimeAdapter(opts = {}) {
44
72
  let ws;
@@ -76,6 +104,8 @@ export function createOpenAIRealtimeAdapter(opts = {}) {
76
104
  // response.cancel needs the most recent response_id.
77
105
  break;
78
106
  }
107
+ // GA name first; the beta name is kept as a read-path alias.
108
+ case "response.output_audio_transcript.delta":
79
109
  case "response.audio_transcript.delta": {
80
110
  const delta = ev["delta"];
81
111
  const itemId = ev["item_id"];
@@ -88,6 +118,7 @@ export function createOpenAIRealtimeAdapter(opts = {}) {
88
118
  }
89
119
  break;
90
120
  }
121
+ case "response.output_audio_transcript.done":
91
122
  case "response.audio_transcript.done": {
92
123
  const transcript = ev["transcript"];
93
124
  const itemId = ev["item_id"];
@@ -100,6 +131,7 @@ export function createOpenAIRealtimeAdapter(opts = {}) {
100
131
  }
101
132
  break;
102
133
  }
134
+ case "response.output_audio.delta":
103
135
  case "response.audio.delta": {
104
136
  const b64 = ev["delta"];
105
137
  if (typeof b64 === "string") {
@@ -161,10 +193,11 @@ export function createOpenAIRealtimeAdapter(opts = {}) {
161
193
  const url = `${baseUrl}?model=${encodeURIComponent(connectOpts.model || DEFAULT_OPENAI_REALTIME_MODEL)}`;
162
194
  const factory = opts._ws ??
163
195
  ((u, init) => new globalThis.WebSocket(u, init));
196
+ // GA takes Authorization only. Sending `OpenAI-Beta: realtime=v1` here
197
+ // is what selects the retired beta wire shape and kills the socket.
164
198
  ws = factory(url, {
165
199
  headers: {
166
200
  Authorization: `Bearer ${apiKey}`,
167
- "OpenAI-Beta": "realtime=v1",
168
201
  },
169
202
  });
170
203
  const socket = ws;
@@ -206,18 +239,34 @@ export function createOpenAIRealtimeAdapter(opts = {}) {
206
239
  socket.addEventListener("close", onClose);
207
240
  socket.addEventListener("message", onMessage);
208
241
  });
209
- // Configure session.
242
+ // Configure session — GA shape. `output_modalities` is audio-only
243
+ // because GA rejects a combined ["text","audio"] request; the audio
244
+ // response still streams transcript deltas, which is where this
245
+ // adapter's transcript_partial/transcript_final events come from.
210
246
  send({
211
247
  type: "session.update",
212
248
  session: {
213
- modalities: ["audio", "text"],
249
+ type: "realtime",
250
+ model: connectOpts.model || DEFAULT_OPENAI_REALTIME_MODEL,
251
+ output_modalities: ["audio"],
214
252
  ...(connectOpts.instructions !== undefined
215
253
  ? { instructions: connectOpts.instructions }
216
254
  : {}),
217
- ...(connectOpts.voice !== undefined ? { voice: connectOpts.voice } : {}),
218
- input_audio_format: "pcm16",
219
- output_audio_format: "pcm16",
220
- turn_detection: connectOpts.vad === "none" ? null : { type: "server_vad" },
255
+ audio: {
256
+ input: {
257
+ format: { type: "audio/pcm", rate: OPENAI_REALTIME_SAMPLE_RATE },
258
+ turn_detection: connectOpts.vad === "none" ? null : { type: "server_vad" },
259
+ },
260
+ output: {
261
+ // `rate` is REQUIRED on an audio/pcm output format — the server
262
+ // rejects the session with "Missing required parameter:
263
+ // 'session.audio.output.format.rate'" if it is omitted (the
264
+ // published docs example omits it, but that example uses
265
+ // audio/pcmu, which is 8kHz-only).
266
+ format: { type: "audio/pcm", rate: OPENAI_REALTIME_SAMPLE_RATE },
267
+ ...(connectOpts.voice !== undefined ? { voice: connectOpts.voice } : {}),
268
+ },
269
+ },
221
270
  ...(connectOpts.tools !== undefined && connectOpts.tools.length > 0
222
271
  ? {
223
272
  tools: connectOpts.tools.map((t) => ({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crewhaus/voice-runtime",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "description": "Realtime voice loop — provider-agnostic RealtimeAdapter + OpenAI Realtime WebSocket adapter (Section 24 VOICE)",
6
6
  "main": "dist/index.js",
@@ -15,7 +15,7 @@
15
15
  "test": "bun test src"
16
16
  },
17
17
  "dependencies": {
18
- "@crewhaus/errors": "0.4.0"
18
+ "@crewhaus/errors": "0.5.0"
19
19
  },
20
20
  "license": "Apache-2.0",
21
21
  "author": {