openai 7.16.0 → 7.18.0

package/src/lib/responses/responses-websocket-lane.ts

@@ -0,0 +1,388 @@
+import type {
+  Response,
+  ResponsesClientEvent,
+  ResponsesServerEvent,
+} from '../../resources/responses/responses';
+import { WebSocketError } from '../../resources/responses/internal-base';
+import { OpenAIError } from '../../core/error';
+import { hasOwn, isObj } from '../../internal/utils/values';
+import {
+  cloneResponse,
+  createCanonicalResponseContext,
+  ensureCanonicalOutputText,
+} from '../../internal/responses/canonical-output-text';
+
+type WireResponse = Omit<Response, 'output' | 'output_text'> &
+  Partial<Pick<Response, 'output' | 'output_text'>>;
+
+type WireEvent<Event> = Event extends { response: Response }
+  ? Omit<Event, 'response'> & {
+      response: WireResponse;
+    }
+  : Event;
+
+/** Raw lane events, including future types with unknown fields. Response output may be omitted. */
+export type ResponsesWebSocketEvent =
+  | WireEvent<ResponsesServerEvent>
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- Future wire event fields have no SDK schema and must remain unknown to callers.
+  | {
+      /** The server's event tag, which may be newer than the SDK. */
+      type: string;
+      [key: string]: unknown;
+    };
+
+function isEventType<Type extends ResponsesServerEvent['type']>(
+  event: ResponsesWebSocketEvent,
+  ...types: Type[]
+): event is Extract<WireEvent<ResponsesServerEvent>, { type: Type }> {
+  return types.some((type) => event.type === type);
+}
+
+/** @internal */
+export function positiveInteger(value: number): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new OpenAIError('Responses WebSocket limits must be positive integers');
+  }
+  return value;
+}
+
+/** A single ordered local consumer. Canceling receive cancels only that wait. */
+export class ResponsesWebSocketLane {
+  declare readonly streamID: string | undefined;
+  readonly #streamID: string | undefined;
+  readonly #send: (event: ResponsesClientEvent) => void;
+  readonly #release: (bytes: number) => void;
+  readonly #maxEvents: number;
+  readonly #maxBytes: number;
+  #bytes = 0;
+  readonly #queue: ({ event: ResponsesWebSocketEvent; bytes: number } | undefined)[] = [];
+  #queueHead = 0;
+  #wake: (() => void) | undefined;
+  #failure: Error | undefined;
+  #reading = false;
+
+  /** Created by ResponsesWebSocketSession.lane().
+   * @internal
+   */
+  constructor(
+    streamID: string | undefined,
+    send: (event: ResponsesClientEvent) => void,
+    release: (bytes: number) => void,
+    maxEvents: number,
+    maxBytes: number,
+  ) {
+    this.#streamID = streamID;
+    Object.defineProperty(this, 'streamID', {
+      value: streamID,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+    this.#send = send;
+    this.#release = release;
+    this.#maxEvents = maxEvents;
+    this.#maxBytes = maxBytes;
+  }
+
+  /** Sends a request on this lane, omitting HTTP-only stream/background fields. previous_response_id remains caller-controlled. */
+  create(
+    request: Omit<
+      Extract<ResponsesClientEvent, { type: 'response.create' }>,
+      'type' | 'stream_id' | 'stream' | 'background'
+    >,
+  ): void {
+    if (this.#failure) {
+      throw this.#failure;
+    }
+    const event: Extract<ResponsesClientEvent, { type: 'response.create' }> = {
+      ...request,
+      type: 'response.create',
+    };
+    // The SDK owns this envelope; a top-level hook must not replace its routing.
+    Object.defineProperty(event, 'toJSON', { value: undefined });
+    delete event.stream;
+    delete event.background;
+    if (this.#streamID === undefined) {
+      delete event.stream_id;
+    } else {
+      Object.defineProperty(event, 'stream_id', { value: this.#streamID, enumerable: true });
+    }
+    this.#send(event);
+  }
+
+  /** Returns the next raw event without filling omitted output or computing output_text. */
+  async receive(options: { signal?: AbortSignal } = {}): Promise<ResponsesWebSocketEvent> {
+    this.#acquireReader();
+    try {
+      const item = await this.#receive(options);
+      return item.event;
+    } finally {
+      this.#reading = false;
+    }
+  }
+
+  #acquireReader(): void {
+    if (this.#reading) {
+      throw new OpenAIError('Responses WebSocket lane already has a reader');
+    }
+    this.#reading = true;
+  }
+
+  async #receive(options: {
+    signal?: AbortSignal | undefined;
+  }): Promise<{ event: ResponsesWebSocketEvent; bytes: number }> {
+    const { signal } = options;
+    for (;;) {
+      if (signal?.aborted) {
+        throw signal.reason;
+      }
+      const item = this.#queue[this.#queueHead];
+      if (item) {
+        this.#queue[this.#queueHead] = undefined;
+        this.#queueHead += 1;
+        if (this.#queueHead >= 64 && this.#queueHead * 2 >= this.#queue.length) {
+          this.#queue.splice(0, this.#queueHead);
+          this.#queueHead = 0;
+        }
+        this.#release(item.bytes);
+        this.#bytes -= item.bytes;
+        return item;
+      }
+      if (this.#failure) {
+        throw this.#failure;
+      }
+      // oxlint-disable-next-line eslint/no-await-in-loop, promise/avoid-new -- A single ordered consumer waits for socket callbacks; canceling a wait must preserve queued events.
+      await new Promise<void>((resolve) => {
+        this.#wake = () => resolve();
+        signal?.addEventListener('abort', this.#wake, { once: true });
+      }).finally(() => {
+        if (this.#wake) {
+          signal?.removeEventListener('abort', this.#wake);
+        }
+        this.#wake = undefined;
+      });
+    }
+  }
+
+  /**
+   * Consumes the next response, returning completed, failed, or incomplete results.
+   * Collects finalized items and uses the existing Responses snapshot normalizer.
+   * Socket error events retain their nested data.
+   * Raw events remain observable on the original connection. maxResponseBytes
+   * optionally bounds the cumulative UTF-8 event bytes consumed for this result.
+   * There is no cumulative limit unless maxResponseBytes is supplied; the lane's
+   * queue budget only limits events waiting to be consumed. Exceeding the limit
+   * before a terminal event fails this lane, so the partial response cannot be
+   * consumed as a new result by a later call. Cancellation after consuming events
+   * also fails the lane; cancellation before consuming anything leaves it reusable.
+   * An invalid completed output item or terminal response fails only this lane.
+   */
+  async finalResponse(options: { signal?: AbortSignal; maxResponseBytes?: number } = {}): Promise<Response> {
+    const { signal } = options;
+    const maxBytes =
+      options.maxResponseBytes === undefined ? Infinity : positiveInteger(options.maxResponseBytes);
+    const completedOutput = new Map<number, Response['output'][number]>();
+    let consumedBytes = 0;
+    this.#acquireReader();
+    try {
+      for (;;) {
+        // oxlint-disable-next-line eslint/no-await-in-loop -- Protocol order is required to accumulate one response.
+        const { event, bytes } = await this.#receive({ signal });
+        consumedBytes += bytes;
+        const terminal = isEventType(
+          event,
+          'error',
+          'response.completed',
+          'response.failed',
+          'response.incomplete',
+        );
+        if (consumedBytes > maxBytes) {
+          const error = new OpenAIError('Responses WebSocket accumulated response limit exceeded');
+          if (!terminal) {
+            this.fail(error);
+          }
+          throw error;
+        }
+        if (isEventType(event, 'error')) {
+          throw new WebSocketError('Responses WebSocket request failed', event);
+        }
+        if (isEventType(event, 'response.created')) {
+          completedOutput.clear();
+        } else if (isEventType(event, 'response.output_item.done')) {
+          this.#validateOutputItem(event);
+          completedOutput.set(event.output_index, structuredClone(event.item));
+        }
+        if (terminal) {
+          this.#validateTerminalResponse(event);
+          return this.#finalizeResponse(event.response, completedOutput);
+        }
+      }
+    } catch (error) {
+      if (consumedBytes > 0 && signal?.aborted) {
+        this.fail(new OpenAIError('Responses WebSocket final response canceled after consuming events'));
+      }
+      throw error;
+    } finally {
+      this.#reading = false;
+    }
+  }
+
+  #finalizeResponse(
+    response: WireResponse,
+    completedOutput: Map<number, Response['output'][number]>,
+  ): Response {
+    const context = createCanonicalResponseContext();
+    try {
+      // Socket deltas need not include the setup events required by SSE.
+      // The terminal response is authoritative; finalized items fill an omitted output.
+      const completedEntries = [...completedOutput];
+      completedEntries.sort(([left], [right]) => left - right);
+      const output = hasOwn(response, 'output') ? response.output : undefined;
+      const outputText = hasOwn(response, 'output_text') ? response.output_text : undefined;
+      if (
+        (output !== undefined &&
+          output !== null &&
+          (!Array.isArray(output) ||
+            !output.every((item) => ResponsesWebSocketLane.#isValidOutputItem(item)))) ||
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate present wire fields before exposing a typed final response.
+        (outputText !== undefined && outputText !== null && typeof outputText !== 'string')
+      ) {
+        throw new OpenAIError('Invalid Responses WebSocket terminal response');
+      }
+      const snapshot = cloneResponse(context, {
+        ...response,
+        output: output ?? completedEntries.map(([, item]) => item),
+        output_text: outputText ?? '',
+      });
+      if (outputText === undefined || outputText === null) {
+        ensureCanonicalOutputText(context, snapshot);
+      }
+      return snapshot;
+    } catch {
+      const error = new OpenAIError('Invalid Responses WebSocket terminal response');
+      this.fail(error);
+      throw error;
+    }
+  }
+
+  #validateOutputItem(event: { output_index: number; item: unknown }): void {
+    if (
+      !hasOwn(event, 'output_index') ||
+      !Number.isSafeInteger(event.output_index) ||
+      event.output_index < 0
+    ) {
+      const error = new OpenAIError('Responses WebSocket output index must be a nonnegative integer');
+      this.fail(error);
+      throw error;
+    }
+    if (!hasOwn(event, 'item')) {
+      const error = new OpenAIError('Responses WebSocket output item must be an own property');
+      this.fail(error);
+      throw error;
+    }
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Completed output items must be wire objects before they enter the typed response.
+    if (event.item === null || typeof event.item !== 'object' || Array.isArray(event.item)) {
+      const error = new OpenAIError('Responses WebSocket output item must be an object');
+      this.fail(error);
+      throw error;
+    }
+    if (!ResponsesWebSocketLane.#isValidOutputItem(event.item)) {
+      const error = new OpenAIError('Invalid Responses WebSocket completed output item');
+      this.fail(error);
+      throw error;
+    }
+  }
+
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- This is the wire boundary that validates untyped output items.
+  static #isValidOutputItem(item: unknown): boolean {
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Wire items require an own string discriminator, including unknown future variants.
+    if (!isObj(item) || !hasOwn(item, 'type') || typeof item['type'] !== 'string') {
+      return false;
+    }
+    if (item['type'] !== 'message') {
+      return true;
+    }
+    return (
+      hasOwn(item, 'content') &&
+      Array.isArray(item['content']) &&
+      // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Validate untyped message parts before exposing the final response.
+      item['content'].every((content: unknown) => {
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Message parts use the same wire discriminator contract.
+        if (!isObj(content) || !hasOwn(content, 'type') || typeof content['type'] !== 'string') {
+          return false;
+        }
+        return (
+          content['type'] !== 'output_text' ||
+          // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Canonical text accumulation consumes this exact wire field.
+          (hasOwn(content, 'text') && typeof content['text'] === 'string')
+        );
+      })
+    );
+  }
+
+  #validateTerminalResponse(event: { response?: unknown }): void {
+    if (
+      !hasOwn(event, 'response') ||
+      event.response === null ||
+      // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate the untrusted terminal envelope before normalizing a typed response snapshot.
+      typeof event.response !== 'object' ||
+      Array.isArray(event.response)
+    ) {
+      const error = new OpenAIError('Responses WebSocket terminal response must be an object');
+      this.fail(error);
+      throw error;
+    }
+  }
+
+  /** Detaches this consumer without canceling remote work. Its ID remains reserved until reconnect. */
+  close(): void {
+    this.fail(new OpenAIError('Responses WebSocket lane is closed'));
+  }
+
+  /** Preserves already accepted events when the transport ends.
+   * @internal
+   */
+  end(error: Error): void {
+    if (this.#failure) {
+      return;
+    }
+    this.#failure = error;
+    // Keep queued events owned by the session until drain, close, or reconnect.
+    this.#wake?.();
+  }
+
+  /** @internal */
+  get ended(): boolean {
+    return this.#failure !== undefined;
+  }
+
+  /** @internal */
+  push(event: ResponsesWebSocketEvent, bytes: number): void {
+    if (this.#failure) {
+      this.#release(bytes);
+      return;
+    }
+    if (this.#queue.length - this.#queueHead >= this.#maxEvents || bytes > this.#maxBytes - this.#bytes) {
+      this.#release(bytes);
+      this.fail(new OpenAIError('Responses WebSocket lane buffer limit exceeded'));
+      return;
+    }
+    this.#bytes += bytes;
+    this.#queue.push({ event, bytes });
+    this.#wake?.();
+  }
+
+  /** @internal */
+  fail(error: Error): void {
+    this.#failure ??= error;
+    for (const item of this.#queue) {
+      if (item) {
+        this.#release(item.bytes);
+      }
+    }
+    this.#queue.length = 0;
+    this.#queueHead = 0;
+    this.#bytes = 0;
+    this.#wake?.();
+  }
+}

package/src/lib/responses/responses-websocket-session.ts

@@ -0,0 +1,317 @@
+import type { ResponsesServerEvent } from '../../resources/responses/responses';
+import type { ResponsesEmitter } from '../../resources/responses/internal-base';
+import { WebSocketError } from '../../resources/responses/internal-base';
+import { OpenAIError } from '../../core/error';
+import { ReadyState } from '../../internal/ws-adapter';
+import type { WebSocketLike } from '../../internal/ws-adapter';
+import { getWebSocketError, rawByteLength } from '../../internal/ws';
+import { hasOwn, isObj } from '../../internal/utils/values';
+import { getWebSocketEventBytes, getWebSocketEventPayload } from '../../resources/responses/ws-base';
+import {
+  getWebSocketEventBytes as getBetaWebSocketEventBytes,
+  getWebSocketEventPayload as getBetaWebSocketEventPayload,
+} from '../../resources/beta/responses/ws-base';
+import { ResponsesWebSocketLane, positiveInteger } from './responses-websocket-lane';
+
+export { ResponsesWebSocketLane } from './responses-websocket-lane';
+export type { ResponsesWebSocketEvent } from './responses-websocket-lane';
+
+interface LaneState {
+  lane: ResponsesWebSocketLane;
+  events: number;
+  bytes: number;
+}
+
+/** Limits for this optional helper. They do not change the underlying socket's limits. */
+export interface ResponsesWebSocketSessionOptions {
+  /** Maximum lane IDs registered until the next reconnect, including detached lanes. */
+  maxLanes: number;
+  /** Maximum queued events across all lanes. */
+  maxBufferedEvents: number;
+  /** Maximum queued UTF-8 JSON bytes across all lanes. */
+  maxBufferedBytes: number;
+}
+
+function parseEvent(serialized: string): ResponsesServerEvent {
+  // SAFETY: Validate the envelope below, as the native transport does for server-defined payloads.
+  const event = JSON.parse(serialized) as ResponsesServerEvent;
+  if (
+    !isObj(event) ||
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Match the native event envelope at this untyped boundary.
+    typeof Object.getOwnPropertyDescriptor(event, 'type')?.value !== 'string'
+  ) {
+    throw new OpenAIError('Invalid WebSocket event shape');
+  }
+  return event;
+}
+
+function serializeCustomEvent(incoming: ResponsesServerEvent): string {
+  const snapshot = structuredClone(incoming);
+  // Mask inherited serialization hooks throughout our copy, not the caller's event.
+  const pending: unknown[] = [snapshot];
+  const visited = new Set<object>();
+  while (pending.length > 0) {
+    const value = pending.pop();
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Traverse only objects in the untyped structured clone.
+    if (value === null || typeof value !== 'object' || visited.has(value)) {
+      continue;
+    }
+    visited.add(value);
+    // Keep Date's standard JSON conversion, which is owned by Date.prototype.
+    if (!(value instanceof Date) && !hasOwn(value, 'toJSON')) {
+      Object.defineProperty(value, 'toJSON', { value: undefined });
+    }
+    for (const child of Object.values(value)) {
+      pending.push(child);
+    }
+  }
+  return JSON.stringify(snapshot);
+}
+
+/**
+ * Routes events from an existing Responses socket without creating another reader.
+ * Register lanes before sending. Unregistered events remain observable on the socket.
+ * Closing this helper releases its listeners and lanes, but leaves the socket open.
+ * Attaching to a closing or closed socket is rejected.
+ * Reconnecting invalidates lanes: register new ones after restoring application state.
+ * No request is replayed by this helper.
+ */
+export class ResponsesWebSocketSession {
+  readonly #connection: ResponsesEmitter & { readonly socket: WebSocketLike };
+  readonly #lanes = new Map<string | undefined, LaneState>();
+  readonly #maxLanes: number;
+  readonly #maxEvents: number;
+  readonly #maxBytes: number;
+  #events = 0;
+  #bytes = 0;
+  #closed = false;
+  #socket: WebSocketLike | undefined;
+  #failedTransport: { socket: WebSocketLike | undefined; error: WebSocketError } | undefined;
+
+  constructor(
+    connection: ResponsesEmitter & { readonly socket: WebSocketLike },
+    options: ResponsesWebSocketSessionOptions,
+  ) {
+    this.#connection = connection;
+    this.#maxLanes = positiveInteger(options.maxLanes);
+    this.#maxEvents = positiveInteger(options.maxBufferedEvents);
+    this.#maxBytes = positiveInteger(options.maxBufferedBytes);
+    if (
+      connection.socket.readyState === ReadyState.CLOSING ||
+      connection.socket.readyState === ReadyState.CLOSED
+    ) {
+      throw new OpenAIError('Cannot attach a Responses WebSocket session to a closing or closed socket');
+    }
+    connection.on('event', this.#onEvent);
+    connection.on('error', this.#onError);
+    connection.on('close', this.#onClose);
+    connection.on('reconnecting', this.#onReconnect);
+    connection.on('reconnected', this.#onReconnected);
+    this.#onReconnected();
+  }
+
+  /** Omit streamID for the protocol's default lane. A lane has one consumer.
+   * IDs remain reserved until reconnect, including after close or failure:
+   * a terminal response can still be followed by an automatic successor.
+   */
+  lane(
+    streamID?: string,
+    limits: { maxBufferedEvents?: number; maxBufferedBytes?: number } = {},
+  ): ResponsesWebSocketLane {
+    if (this.#closed) {
+      throw new OpenAIError('Responses WebSocket session is closed');
+    }
+    this.#assertTransportAvailable(this.#connection.socket);
+    if (
+      streamID !== undefined &&
+      // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Untyped JavaScript callers must not create non-string routing keys through RegExp coercion.
+      (typeof streamID !== 'string' || !/^[A-Za-z0-9_.-]{1,256}$/u.test(streamID))
+    ) {
+      throw new OpenAIError('Invalid Responses WebSocket stream ID');
+    }
+    if (this.#lanes.has(streamID)) {
+      throw new OpenAIError('Responses WebSocket lane is already registered');
+    }
+    if (this.#lanes.size >= this.#maxLanes) {
+      throw new OpenAIError('Responses WebSocket lane limit exceeded');
+    }
+    const entry: LaneState = {
+      events: 0,
+      bytes: 0,
+      lane: new ResponsesWebSocketLane(
+        streamID,
+        (event) => {
+          const { socket } = this.#connection;
+          this.#assertTransportAvailable(socket);
+          if (socket.readyState !== ReadyState.OPEN) {
+            throw new OpenAIError('Wait for an open Responses WebSocket before sending');
+          }
+          // The emitter's reconnect queue may replay an uncertain write. Send
+          // directly to the physical socket, including during its open callback.
+          socket.send(JSON.stringify(event));
+        },
+        (bytes) => {
+          this.#events -= 1;
+          this.#bytes -= bytes;
+          entry.events -= 1;
+          entry.bytes -= bytes;
+        },
+        positiveInteger(limits.maxBufferedEvents ?? this.#maxEvents),
+        positiveInteger(limits.maxBufferedBytes ?? this.#maxBytes),
+      ),
+    };
+    this.#lanes.set(streamID, entry);
+    return entry.lane;
+  }
+
+  close(): void {
+    this.#closed = true;
+    this.#removeListeners();
+    this.#failLanes(new OpenAIError('Responses WebSocket session is closed'));
+    this.#lanes.clear();
+  }
+
+  #removeListeners(): void {
+    this.#connection.off('event', this.#onEvent);
+    this.#connection.off('error', this.#onError);
+    this.#connection.off('close', this.#onClose);
+    this.#connection.off('reconnecting', this.#onReconnect);
+    this.#connection.off('reconnected', this.#onReconnected);
+    this.#socket?.off('error', this.#onSocketError);
+    this.#socket = undefined;
+  }
+
+  #onEvent = (incoming: ResponsesServerEvent): void => {
+    let event: ResponsesServerEvent;
+    let bytes: number;
+    try {
+      const payload = getWebSocketEventPayload(incoming) ?? getBetaWebSocketEventPayload(incoming);
+      // Native events are copied from the wire, before any observer's mutations.
+      // Clone custom inputs once to strip prototypes and evaluate accessors,
+      // then retain only the JSON representation covered by byte accounting.
+      let serialized = payload;
+      if (serialized === undefined) {
+        serialized = serializeCustomEvent(incoming);
+      }
+      event = parseEvent(serialized);
+      bytes =
+        payload === undefined
+          ? rawByteLength(serialized)
+          : (getBetaWebSocketEventBytes(incoming) ?? getWebSocketEventBytes(incoming));
+    } catch {
+      this.#failLanes(new OpenAIError('Cannot snapshot custom WebSocket event'));
+      return;
+    }
+    const routing = Object.getOwnPropertyDescriptor(event, 'stream_id');
+    let streamID: string | undefined;
+    if (routing) {
+      const value: unknown = routing.value;
+      // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Raw event observers may mutate routing; only an own string value can select a lane, without invoking accessors.
+      if (typeof value !== 'string') {
+        return;
+      }
+      streamID = value;
+    }
+    const entry = this.#lanes.get(streamID);
+    if (!entry || entry.lane.ended) {
+      return;
+    }
+    if (bytes > this.#maxBytes) {
+      entry.lane.fail(new OpenAIError('Responses WebSocket helper buffer limit exceeded'));
+      return;
+    }
+    this.#events += 1;
+    this.#bytes += bytes;
+    entry.events += 1;
+    entry.bytes += bytes;
+    // Apply the lane's own limits first, releasing its backlog on overflow.
+    entry.lane.push(event, bytes);
+    while (this.#events > this.#maxEvents || this.#bytes > this.#maxBytes) {
+      const bytePressure = this.#bytes > this.#maxBytes;
+      let largest = entry;
+      let largestSize = 0;
+      for (const candidate of this.#lanes.values()) {
+        // Attribute pressure to existing backlogs, excluding the incoming event.
+        const size = bytePressure
+          ? candidate.bytes - (candidate === entry ? bytes : 0)
+          : candidate.events - (candidate === entry ? 1 : 0);
+        // Strict comparison breaks ties by lane registration order.
+        if (size > largestSize) {
+          largest = candidate;
+          largestSize = size;
+        }
+      }
+      largest.lane.fail(new OpenAIError('Responses WebSocket helper buffer limit exceeded'));
+    }
+  };
+
+  #onClose = (): void => {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    this.#removeListeners();
+    for (const { lane } of this.#lanes.values()) {
+      lane.end(new OpenAIError('Responses WebSocket connection closed'));
+    }
+  };
+  // oxlint-disable-next-line eslint/class-methods-use-this -- Each session owns a distinct listener so detaching one does not unhandle another session's errors.
+  #onError = (): void => {
+    // API errors are routed as events. Other emitter errors may be recoverable
+    // diagnostics; only the physical socket's errors end all lanes.
+  };
+  #onSocketError = (cause: Error): void => {
+    const error = new WebSocketError(cause.message, null);
+    Object.assign(error, { cause });
+    this.#failedTransport = { socket: this.#socket, error };
+    for (const { lane } of this.#lanes.values()) {
+      lane.end(error);
+    }
+  };
+  #onReconnect = (): void => {
+    this.#socket?.off('error', this.#onSocketError);
+    this.#socket = undefined;
+    this.#failLanes(new OpenAIError('Responses WebSocket reconnected state must be restored explicitly'));
+    this.#lanes.clear();
+  };
+  #onReconnected = (): void => {
+    if (this.#closed) {
+      return;
+    }
+    this.#socket?.off('error', this.#onSocketError);
+    this.#socket = this.#connection.socket;
+    this.#clearRecoveredTransportError(this.#socket);
+    this.#socket.on('error', this.#onSocketError);
+  };
+
+  #assertTransportAvailable(socket: WebSocketLike): void {
+    // Native transports record failure before forwarding their public error event.
+    const cause = getWebSocketError(socket);
+    if (cause) {
+      const error = new WebSocketError(cause.message, null);
+      Object.assign(error, { cause });
+      throw error;
+    }
+    this.#clearRecoveredTransportError(socket);
+    if (this.#failedTransport) {
+      throw this.#failedTransport.error;
+    }
+  }
+
+  #clearRecoveredTransportError(socket: WebSocketLike): void {
+    // Application recovery callbacks can run before our reconnected listener.
+    if (
+      this.#failedTransport &&
+      socket !== this.#failedTransport.socket &&
+      socket.readyState === ReadyState.OPEN
+    ) {
+      this.#failedTransport = undefined;
+    }
+  }
+
+  #failLanes(error: Error): void {
+    for (const { lane } of this.#lanes.values()) {
+      lane.fail(error);
+    }
+  }
+}