fix(openai): handle top-level code/param on Responses WS error frames (#2024)

Co-authored-by: rosetta-livekit-bot[bot] <282703043+rosetta-livekit-bot[bot]@users.noreply.github.com>
Co-authored-by: David Zhao <dz@livekit.io>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

.changeset/quiet-ws-fields.md

@@ -0,0 +1,5 @@
+---
+'@livekit/agents-plugin-openai': patch
+---
+
+Handle top-level `code` and `param` fields on OpenAI Responses WebSocket error frames so request-validation errors surface cleanly and error-code routing (e.g. retry on `previous_response_not_found`) works for top-level codes.

plugins/openai/src/responses/llm.test.ts

@@ -2,11 +2,32 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import { llm, llmStrict } from '@livekit/agents-plugins-test';
-import { describe, it } from 'vitest';
+import { describe, expect, it } from 'vitest';
+import { wsServerEventSchema } from '../ws/types.js';
 import { LLM } from './llm.js';
 
 const hasOpenAIApiKey = Boolean(process.env.OPENAI_API_KEY);
 
+describe('OpenAI Responses WebSocket', () => {
+  it('preserves top-level code and param on error frames', () => {
+    const frame = {
+      type: 'error',
+      message:
+        "Invalid type for 'reasoning.mode': expected one of 'standard' or 'pro', but got null instead.",
+      code: 'invalid_type',
+      param: 'reasoning.mode',
+      status: 400,
+    };
+
+    const parsed = wsServerEventSchema.parse(frame);
+
+    expect(parsed.type).toBe('error');
+    if (parsed.type !== 'error') throw new Error('expected error event');
+    expect(parsed.message).toBe(frame.message);
+    expect(parsed.param).toBe('reasoning.mode');
+  });
+});
+
 if (hasOpenAIApiKey) {
   describe('OpenAI Responses', async () => {
     await llm(

plugins/openai/src/ws/llm.ts

@@ -544,7 +544,7 @@ export class WSLLMStream extends llm.LLMStream {
    * (`previous_response_not_found`), throws for all other errors.
    */
   #handleError(event: WsServerEvent & { type: 'error' }, conn: ResponsesWebSocket): boolean {
-    const code = event.error?.code;
+    const code = event.error?.code ?? event.code;
 
     if (code === 'previous_response_not_found') {
       // The server-side in-memory cache was evicted (e.g. after a failed turn

plugins/openai/src/ws/types.ts

@@ -101,6 +101,8 @@ export const wsResponseFailedEventSchema = z.object({
 export const wsErrorEventSchema = z.object({
   type: z.literal('error'),
   status: z.number().optional(),
+  code: z.string().optional(),
+  param: z.string().optional(),
   error: z
     .object({
       type: z.string().optional(),