openai 0.86.0 → 0.87.0

data/rbi/openai/resources/images.rbi

@@ -50,8 +50,7 @@ module OpenAI
       # See {OpenAI::Resources::Images#edit_stream_raw} for streaming counterpart.
       #
       # Creates an edited or extended image given one or more source images and a
-      # prompt. This endpoint supports GPT Image models (`gpt-image-1.5`, `gpt-image-1`,
-      # `gpt-image-1-mini`, and `chatgpt-image-latest`) and `dall-e-2`.
+      # prompt. This endpoint supports GPT Image models and `dall-e-2`.
       sig {
         params(
           image: OpenAI::ImageEditParams::Image::Variants,
@@ -77,9 +76,11 @@ module OpenAI
         # The image(s) to edit. Must be a supported image file or an array of images.
         #
         # For the GPT image models (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`,
-        # `gpt-image-2`, `gpt-image-2-2026-04-21`, and `chatgpt-image-latest`), each image
-        # should be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to
-        # 16 images.
+        # `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,
+        # `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`,
+        # `gpt-image-2.5-flare-2026-09-08`, and `chatgpt-image-latest`), each image should
+        # be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16
+        # images.
         #
         # For `dall-e-2`, you can only provide one image, and it should be a square `png`
         # file less than 4MB.
@@ -95,9 +96,11 @@ module OpenAI
         # one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used,
         # the model will automatically determine the best background for the image.
         #
-        # Transparent backgrounds are available for supported GPT Image models. For
-        # `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When
-        # using `transparent`, set the output format to `png` or `webp`.
+        # `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08`
+        # snapshots, support `opaque` and `transparent` backgrounds. Transparent
+        # backgrounds are available for supported GPT Image models. For `gpt-image-2` and
+        # `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`,
+        # set the output format to `png` or `webp`.
         background: nil,
         # Control how much effort the model will exert to match the style and features,
         # especially facial features, of input images. This parameter is only supported
@@ -115,7 +118,9 @@ module OpenAI
         mask: nil,
         # The model to use for image generation. One of `dall-e-2` or a GPT image model
         # (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`,
-        # `gpt-image-2-2026-04-21`, or `chatgpt-image-latest`). Defaults to
+        # `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,
+        # `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`,
+        # `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`). Defaults to
         # `gpt-image-1.5`.
         model: nil,
         # The number of images to generate. Must be between 1 and 10.
@@ -135,25 +140,28 @@ module OpenAI
         # Note that the final image may be sent before the full number of partial images
         # are generated if the full image is generated more quickly.
         partial_images: nil,
-        # The quality of the image that will be generated for GPT image models. Defaults
-        # to `auto`.
+        # The quality of the image that will be generated for GPT image models. The GPT
+        # image models support `low`, `medium`, and `high`. `gpt-image-2.5-sunburst` and
+        # `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support
+        # `xhigh` and `max`. Defaults to `auto`.
         quality: nil,
         # The format in which the generated images are returned. Must be one of `url` or
         # `b64_json`. URLs are only valid for 60 minutes after the image has been
         # generated. This parameter is only supported for `dall-e-2` (default is `url` for
         # `dall-e-2`), as GPT image models always return base64-encoded images.
         response_format: nil,
-        # The size of the generated images. For `gpt-image-2` and
-        # `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT`
-        # strings, for example `1536x864`. Width and height must both be divisible by 16
-        # and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above
-        # `2560x1440` are experimental, and the maximum supported resolution is
-        # `3840x2160`. The requested size must also satisfy the model's current pixel and
-        # edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are
-        # supported by the GPT image models; `auto` is supported for models that allow
-        # automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or
-        # `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or
-        # `1024x1792`.
+        # The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`,
+        # `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`,
+        # `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary
+        # resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`.
+        # Width and height must both be divisible by 16 and the requested aspect ratio
+        # must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and
+        # the maximum supported resolution is `3840x2160`. The requested size must also
+        # satisfy the model's current pixel and edge limits. The standard sizes
+        # `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models;
+        # `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use
+        # one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of
+        # `1024x1024`, `1792x1024`, or `1024x1792`.
         size: nil,
         # A unique identifier representing your end-user, which can help OpenAI to monitor
         # and detect abuse.
@@ -169,8 +177,7 @@ module OpenAI
       # See {OpenAI::Resources::Images#edit} for non-streaming counterpart.
       #
       # Creates an edited or extended image given one or more source images and a
-      # prompt. This endpoint supports GPT Image models (`gpt-image-1.5`, `gpt-image-1`,
-      # `gpt-image-1-mini`, and `chatgpt-image-latest`) and `dall-e-2`.
+      # prompt. This endpoint supports GPT Image models and `dall-e-2`.
       sig {
         params(
           image: OpenAI::ImageEditParams::Image::Variants,
@@ -196,9 +203,11 @@ module OpenAI
         # The image(s) to edit. Must be a supported image file or an array of images.
         #
         # For the GPT image models (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`,
-        # `gpt-image-2`, `gpt-image-2-2026-04-21`, and `chatgpt-image-latest`), each image
-        # should be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to
-        # 16 images.
+        # `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,
+        # `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`,
+        # `gpt-image-2.5-flare-2026-09-08`, and `chatgpt-image-latest`), each image should
+        # be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16
+        # images.
         #
         # For `dall-e-2`, you can only provide one image, and it should be a square `png`
         # file less than 4MB.
@@ -214,9 +223,11 @@ module OpenAI
         # one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used,
         # the model will automatically determine the best background for the image.
         #
-        # Transparent backgrounds are available for supported GPT Image models. For
-        # `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When
-        # using `transparent`, set the output format to `png` or `webp`.
+        # `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08`
+        # snapshots, support `opaque` and `transparent` backgrounds. Transparent
+        # backgrounds are available for supported GPT Image models. For `gpt-image-2` and
+        # `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`,
+        # set the output format to `png` or `webp`.
         background: nil,
         # Control how much effort the model will exert to match the style and features,
         # especially facial features, of input images. This parameter is only supported
@@ -234,7 +245,9 @@ module OpenAI
         mask: nil,
         # The model to use for image generation. One of `dall-e-2` or a GPT image model
         # (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`,
-        # `gpt-image-2-2026-04-21`, or `chatgpt-image-latest`). Defaults to
+        # `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,
+        # `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`,
+        # `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`). Defaults to
         # `gpt-image-1.5`.
         model: nil,
         # The number of images to generate. Must be between 1 and 10.
@@ -254,25 +267,28 @@ module OpenAI
         # Note that the final image may be sent before the full number of partial images
         # are generated if the full image is generated more quickly.
         partial_images: nil,
-        # The quality of the image that will be generated for GPT image models. Defaults
-        # to `auto`.
+        # The quality of the image that will be generated for GPT image models. The GPT
+        # image models support `low`, `medium`, and `high`. `gpt-image-2.5-sunburst` and
+        # `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support
+        # `xhigh` and `max`. Defaults to `auto`.
         quality: nil,
         # The format in which the generated images are returned. Must be one of `url` or
         # `b64_json`. URLs are only valid for 60 minutes after the image has been
         # generated. This parameter is only supported for `dall-e-2` (default is `url` for
         # `dall-e-2`), as GPT image models always return base64-encoded images.
         response_format: nil,
-        # The size of the generated images. For `gpt-image-2` and
-        # `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT`
-        # strings, for example `1536x864`. Width and height must both be divisible by 16
-        # and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above
-        # `2560x1440` are experimental, and the maximum supported resolution is
-        # `3840x2160`. The requested size must also satisfy the model's current pixel and
-        # edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are
-        # supported by the GPT image models; `auto` is supported for models that allow
-        # automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or
-        # `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or
-        # `1024x1792`.
+        # The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`,
+        # `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`,
+        # `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary
+        # resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`.
+        # Width and height must both be divisible by 16 and the requested aspect ratio
+        # must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and
+        # the maximum supported resolution is `3840x2160`. The requested size must also
+        # satisfy the model's current pixel and edge limits. The standard sizes
+        # `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models;
+        # `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use
+        # one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of
+        # `1024x1024`, `1792x1024`, or `1024x1792`.
         size: nil,
         # A unique identifier representing your end-user, which can help OpenAI to monitor
         # and detect abuse.
@@ -318,14 +334,18 @@ module OpenAI
         # one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used,
         # the model will automatically determine the best background for the image.
         #
-        # Transparent backgrounds are available for supported GPT Image models. For
-        # `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When
-        # using `transparent`, set the output format to `png` or `webp`.
+        # `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08`
+        # snapshots, support `opaque` and `transparent` backgrounds. Transparent
+        # backgrounds are available for supported GPT Image models. For `gpt-image-2` and
+        # `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`,
+        # set the output format to `png` or `webp`.
         background: nil,
         # The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT
         # image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`,
-        # or `gpt-image-2-2026-04-21`). Defaults to `dall-e-2` unless a parameter specific
-        # to the GPT image models is used.
+        # `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,
+        # `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`,
+        # `gpt-image-2.5-flare-2026-09-08`). Defaults to `dall-e-2` unless a parameter
+        # specific to the GPT image models is used.
         model: nil,
         # Control the content-moderation level for images generated by the GPT image
         # models. Must be either `low` for less restrictive filtering or `auto` (default
@@ -353,6 +373,8 @@ module OpenAI
         # - `auto` (default value) will automatically select the best quality for the
         #   given model.
         # - `high`, `medium` and `low` are supported for the GPT image models.
+        # - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their
+        #   `2026-09-08` snapshots, also support `xhigh` and `max`.
         # - `hd` and `standard` are supported for `dall-e-3`.
         # - `standard` is the only option for `dall-e-2`.
         quality: nil,
@@ -361,17 +383,18 @@ module OpenAI
         # after the image has been generated. This parameter isn't supported for the GPT
         # image models, which always return base64-encoded images.
         response_format: nil,
-        # The size of the generated images. For `gpt-image-2` and
-        # `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT`
-        # strings, for example `1536x864`. Width and height must both be divisible by 16
-        # and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above
-        # `2560x1440` are experimental, and the maximum supported resolution is
-        # `3840x2160`. The requested size must also satisfy the model's current pixel and
-        # edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are
-        # supported by the GPT image models; `auto` is supported for models that allow
-        # automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or
-        # `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or
-        # `1024x1792`.
+        # The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`,
+        # `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`,
+        # `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary
+        # resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`.
+        # Width and height must both be divisible by 16 and the requested aspect ratio
+        # must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and
+        # the maximum supported resolution is `3840x2160`. The requested size must also
+        # satisfy the model's current pixel and edge limits. The standard sizes
+        # `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models;
+        # `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use
+        # one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of
+        # `1024x1024`, `1792x1024`, or `1024x1792`.
         size: nil,
         # The style of the generated images. This parameter is only supported for
         # `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean
@@ -422,14 +445,18 @@ module OpenAI
         # one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used,
         # the model will automatically determine the best background for the image.
         #
-        # Transparent backgrounds are available for supported GPT Image models. For
-        # `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When
-        # using `transparent`, set the output format to `png` or `webp`.
+        # `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08`
+        # snapshots, support `opaque` and `transparent` backgrounds. Transparent
+        # backgrounds are available for supported GPT Image models. For `gpt-image-2` and
+        # `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`,
+        # set the output format to `png` or `webp`.
         background: nil,
         # The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT
         # image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`,
-        # or `gpt-image-2-2026-04-21`). Defaults to `dall-e-2` unless a parameter specific
-        # to the GPT image models is used.
+        # `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,
+        # `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`,
+        # `gpt-image-2.5-flare-2026-09-08`). Defaults to `dall-e-2` unless a parameter
+        # specific to the GPT image models is used.
         model: nil,
         # Control the content-moderation level for images generated by the GPT image
         # models. Must be either `low` for less restrictive filtering or `auto` (default
@@ -457,6 +484,8 @@ module OpenAI
         # - `auto` (default value) will automatically select the best quality for the
         #   given model.
         # - `high`, `medium` and `low` are supported for the GPT image models.
+        # - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their
+        #   `2026-09-08` snapshots, also support `xhigh` and `max`.
         # - `hd` and `standard` are supported for `dall-e-3`.
         # - `standard` is the only option for `dall-e-2`.
         quality: nil,
@@ -465,17 +494,18 @@ module OpenAI
         # after the image has been generated. This parameter isn't supported for the GPT
         # image models, which always return base64-encoded images.
         response_format: nil,
-        # The size of the generated images. For `gpt-image-2` and
-        # `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT`
-        # strings, for example `1536x864`. Width and height must both be divisible by 16
-        # and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above
-        # `2560x1440` are experimental, and the maximum supported resolution is
-        # `3840x2160`. The requested size must also satisfy the model's current pixel and
-        # edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are
-        # supported by the GPT image models; `auto` is supported for models that allow
-        # automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or
-        # `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or
-        # `1024x1792`.
+        # The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`,
+        # `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`,
+        # `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary
+        # resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`.
+        # Width and height must both be divisible by 16 and the requested aspect ratio
+        # must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and
+        # the maximum supported resolution is `3840x2160`. The requested size must also
+        # satisfy the model's current pixel and edge limits. The standard sizes
+        # `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models;
+        # `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use
+        # one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of
+        # `1024x1024`, `1792x1024`, or `1024x1792`.
         size: nil,
         # The style of the generated images. This parameter is only supported for
         # `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean

data/rbi/openai/resources/responses.rbi

@@ -241,6 +241,9 @@ module OpenAI
         # parameter.
         service_tier: nil,
         # Whether to store the generated model response for later retrieval via API.
+        # Defaults to true when omitted. If set to true, response data will be stored for
+        # at least 30 days, subject to the
+        # [data retention exceptions](/api/docs/guides/your-data#v1responses).
         store: nil,
         # Options for streaming responses. Only set this when you set `stream: true`.
         stream_options: nil,
@@ -546,6 +549,9 @@ module OpenAI
         # parameter.
         service_tier: nil,
         # Whether to store the generated model response for later retrieval via API.
+        # Defaults to true when omitted. If set to true, response data will be stored for
+        # at least 30 days, subject to the
+        # [data retention exceptions](/api/docs/guides/your-data#v1responses).
         store: nil,
         # Options for streaming responses. Only set this when you set `stream: true`.
         stream_options: nil,

data/realtime.md

@@ -76,6 +76,107 @@ types. Invalid client events raise `ArgumentError` with a generic public
 message; the converter error remains available through `cause` for explicit
 inspection. `send_raw` and `receive_raw` are text-frame escape hatches.
 
+## Reconnect and retained sends
+
+Automatic reconnect is disabled by default. Enable it on the existing `connect`
+method for ordinary model sessions:
+
+```ruby
+client.realtime.connect(model: "gpt-realtime-2.1", reconnect: true) do |connection|
+  connection.each { |event| handle_event(event) }
+end
+```
+
+Both `receive` and `each` drive recovery. The application block runs once, with
+the same connection object. Recovery opens a **new session**; it does not restore
+conversation history, buffered audio, outstanding tool calls, or an interrupted
+response. The normal server session events remain observable. Sends alone do
+not drive recovery: keep a receiver running to observe disconnects.
+
+`max_reconnect_attempts` defaults to 5 and bounds the total additional connection
+attempts over the block's lifetime, including retryable initial handshake
+failures. Backoff starts at 0.5 seconds, doubles to an 8-second cap, and applies
+jitter. Normal close, explicit close, permanent authentication/TLS/protocol
+failures, and exhausted retries stop recovery. Each attempt uses the client's
+existing endpoint and authentication preparation, including workload-identity
+token refresh. `request_options[:max_retries]` remains an HTTP option and must
+not be used to configure WebSocket reconnect.
+
+An optional `on_reconnected:` callback receives the same connection before the
+replacement is made available to waiting readers. It can restore application
+state using the usual typed helpers; its exceptions stop recovery. A callback
+may receive events itself, consuming them before the application receiver.
+
+### Optional outbound queue
+
+`max_queue_bytes` defaults to **0** (queueing disabled). Set a positive byte
+budget to retain validated, serialized events sent while reconnecting or while
+an explicit queue flush is in progress. Queue-full errors reject the new event
+without evicting accepted events. The budget includes a queued write until it
+settles; empty raw text costs one byte for accounting. Connected sends and
+incoming events have no new payload-size limit.
+
+Retained events are **never automatically flushed** into a replacement session.
+Restore any needed state, decide whether the queued work still belongs in that
+session, then call `flush_pending`. Normal connected sends bypass the held queue,
+allowing setup messages to precede it. Only the retained messages have FIFO
+ordering relative to each other. For example:
+
+```ruby
+restore = lambda do |connection|
+  connection.session.update(type: :realtime, instructions: "Be concise.")
+  # Use this only when the application knows its retained events are valid
+  # in the replacement session. Rebuilding earlier conversation state may
+  # require additional events and acknowledgements first.
+  connection.flush_pending
+end
+
+client.realtime.connect(
+  model: "gpt-realtime-2.1",
+  reconnect: true,
+  max_queue_bytes: 1_048_576,
+  on_reconnected: restore
+) do |connection|
+  connection.each { |event| handle_event(event) }
+end
+```
+
+The callback is optional even with queueing enabled. After receiving a new
+session's events, application code can restore state and flush the queue itself.
+`pending_messages` returns a snapshot of encoded unsent events;
+`take_pending_messages` removes and returns them without sending. The latter
+raises if a flush is in progress. These accessors return empty arrays on ordinary
+connections without recovery; `flush_pending` on such a connection is a no-op.
+
+`OpenAI::Errors::RealtimeQueueFullError` means the event was not accepted.
+`OpenAI::Errors::RealtimeReconnectError` reports a terminal recovery failure or
+an interrupted operation. Its `unsent_messages` contains retained events never
+attempted on the socket. A failed write stops the connection and exposes the
+attempted event as `uncertain_message`; the SDK never retries it. A local write
+completion is not a server acknowledgement, and `event_id` does not establish
+exactly-once delivery. These explicit payload accessors can contain sensitive
+application data; do not log them. Error messages omit their contents.
+
+Each waiting sender receives an error describing only its own event. If its write
+was never attempted, that event appears in `unsent_messages` and `uncertain_message`
+is nil, even when another concurrent sender's write caused the connection to fail.
+
+When an explicit flush is interrupted by another disconnect, unattempted events
+stay queued and require another explicit flush after recovery. Intentional close
+keeps retained data available through the connection's queue accessors. With
+reconnect enabled, close makes a best-effort attempt (up to one second) to send its
+`code` and `reason`, then releases the socket. A close during a write aborts
+immediately and reports uncertain delivery. Leaving the block cancels and joins recovery
+work. Concurrent producers submit through the connection's mailbox; socket I/O
+stays on its owning Async reactor. Cancelling a waiting operation closes the
+logical connection so an abandoned receive cannot consume a later event.
+
+Reconnect uses the optional Async runtime even with a custom transport. Custom
+transports must allow Async cancellation and preserve the cause/status of
+`RealtimeConnectionError` for retry classification. `connect_transcription` and
+`connect_to_call` retain their existing behavior; their session recovery
+semantics are not enabled by this option.
+
 ## Standard text workflows
 
 The same generic helpers cover local function results, image content, and MCP

data/responses-websocket.md

@@ -0,0 +1,182 @@
+# Responses WebSocket workflows
+
+Requires `openai` 0.86.0 or later and the optional `async-websocket` gem:
+
+```ruby
+gem "openai", ">= 0.86.0"
+gem "async-websocket"
+```
+
+Responses WebSocket mode connects to `/v1/responses`. It uses Responses events;
+it is distinct from [Realtime sessions](realtime.md). See the
+[platform guide](https://developers.openai.com/api/docs/guides/websocket-mode)
+for the service contract.
+
+## Run the examples
+
+The [workflow example](examples/responses/websocket_workflows.rb) demonstrates
+four patterns with one reader and no background worker threads. Keep
+`OPENAI_API_KEY` in your environment. These commands make real API calls:
+
+```sh
+bundle exec ruby examples/responses/websocket_workflows.rb tools
+bundle exec ruby examples/responses/websocket_workflows.rb multiplex
+bundle exec ruby examples/responses/websocket_workflows.rb stored
+bundle exec ruby examples/responses/websocket_workflows.rb stateless
+```
+
+Set `OPENAI_RESPONSES_MODEL` to override `gpt-5.2` and
+`OPENAI_RESPONSES_TIMEOUT` to change the 60-second overall deadline. The example
+prints only a completion marker, not prompts, model output, or server errors.
+The default workflow is `multiplex`. The `stored` workflow requires an account
+that allows response storage; use `stateless` with `store=false`/ZDR.
+
+## Connect, send, and receive
+
+```ruby
+client.responses.connect do |connection|
+  connection.response.create(model: "gpt-5.2", input: "Say hello.")
+  connection.each do |event|
+    case event.type.to_s
+    when "response.completed"
+      # Save event.response.id and handle event.response.output here.
+      break
+    when "response.failed", "response.incomplete", "error"
+      raise "Responses operation did not complete."
+    end
+  end
+end
+```
+
+Use the complete example for EOF detection: a connection ending before every
+expected terminal event is not success. `connect` requires a block and closes
+on block exit. Connection options belong in `connect`; model/input fields belong
+in `connection.response.create`.
+
+Known events are decoded into generated models on a best-effort basis. New
+event types arrive as `OpenAI::Responses::UnknownServerEvent`. Preserve or handle
+them explicitly where your application needs them. Do not assume every event
+has a response, text delta, or lane ID.
+
+## Sequential tool turns
+
+The `tools` workflow forces a call to one known, harmless application function.
+After the response completes, it checks the function name and sends its output
+using the original `call_id`. The next create uses `previous_response_id` and
+only the new `function_call_output` item. It does not resend the previous input
+on the same connection.
+
+Tool execution belongs to your application. Validate arguments against your
+tool's contract and authorize effects before execution. Never execute generated
+code or dispatch arbitrary method names from a tool event. The example uses a
+fixed result and does not execute model-provided code.
+
+## Multiplexing and continuation
+
+`stream_id` routes events to a lane; `previous_response_id` selects conversation
+history. They are independent. Reusing a lane without a previous response ID
+starts a new response rather than continuing that lane's conversation.
+
+The `multiplex` workflow writes two creates, then drains both lanes with one
+reader. Events may interleave and the first terminal event does not finish the
+whole operation. Keep a pending-lane set and retain each completed response ID.
+Omitting `stream_id` uses the default lane; its events omit the field as well.
+
+The example fails the whole operation on any error. Production applications can
+route a lane-scoped error to just that lane, while treating a connection-scoped
+error as affecting the connection. Track separate response IDs when multiple
+requests are outstanding within a lane; a lane alone is not a request ID.
+
+The server executes same-lane requests in FIFO order. The SDK does not enforce
+lane grammar, schedule lanes, or manage a per-lane queue. Consult the platform
+guide for the current concurrent-response and named-lane limits.
+
+To fork, send an existing response ID on a different lane. With `store=false`,
+wait for the fork's `response.in_progress` before advancing the source lane so
+its parent remains available in the connection-local cache.
+
+## Reconnect without replaying uncertain work
+
+Both reconnect examples intentionally close a healthy connection **after** a
+completed turn, then open another connection. They do not catch a failed write
+and retry it.
+
+- **Stored:** send only the new input plus the stored `previous_response_id`.
+  If the service cannot retrieve that response, the application must decide
+  whether to reconstruct context and start a new chain.
+- **Stateless:** connection-local state is lost on reconnect. Retain the original
+  inputs and every output item, including reasoning and tool items. Request
+  `include: ["reasoning.encrypted_content"]` for reasoning-model replay. Send the
+  retained history plus new input, omitting `previous_response_id` on the new
+  connection. Do not reduce history to displayed assistant text.
+
+Retained history can contain sensitive data. Apply your application's retention
+policy; neither the SDK nor this example writes a recovery log. A full-context
+replay starts a new chain and is not an exactly-once retry of a failed turn.
+
+Connections have a finite service lifetime (currently up to 60 minutes). Plan
+rotation and persistence at completed-turn boundaries. There is no automatic
+reconnect, rollover, or replay in this SDK connection.
+
+## Deadlines and shutdown
+
+An SDK request timeout bounds connection negotiation, not an established
+session's idle lifetime. The example wraps the complete workflow in an Async
+deadline on the owning thread:
+
+```ruby
+require "async"
+
+Sync do |task|
+  task.with_timeout(60) do
+    client.responses.connect do |connection|
+      # Send and read on this thread, inside the deadline.
+    end
+  end
+end
+```
+
+Connections enforce one owning thread and one active reader. Do not call close
+from another thread or nest `receive` inside an active `each`. The Async deadline
+can interrupt an idle network read on the owning thread; the SDK then aborts and
+cleans up the connection. A timeout inside a transport operation can surface as
+`ResponsesConnectionError`, rather than `Async::TimeoutError`. Application code
+that does CPU-bound work without yielding needs its own cancellation strategy.
+
+Exiting the block normally performs a close. An exception or poisoned connection
+causes an abort, avoiding a flush of uncertain buffered output. The peer may see
+an abrupt disconnect. This is local shutdown, not a server-side cancellation
+acknowledgment, and it does not guarantee that a response stopped executing.
+
+## Error and compatibility boundaries
+
+- `ResponsesSendError#outcome` is `:unknown`: the server may have accepted the
+  event. Stop using that connection; do not automatically resend it.
+- A transport read failure poisons the connection. A server `error` event is
+  delivered as an event and does not by itself poison it.
+- Malformed JSON raises `ResponsesProtocolError` without exposing the payload;
+  the connection permits later reads. Decide whether continuing is appropriate
+  for your application.
+- Raw `send_event` supports generated client models or hashes, including
+  `response.steer`. There is no `connection.response.steer` convenience method.
+- The platform documents `generate: false` warmup. It can be forwarded through
+  create's keyword rest even though 0.86.0 has no named generated `generate`
+  keyword. Follow the platform contract; do not send HTTP-only `stream` or
+  `background` flags just because generated models expose them.
+- X.509 workload identity and provider runtimes are not supported by this
+  entry point. A nonempty `request_options.extra_query` or nonzero
+  `request_options.max_retries` is rejected. Supported workload identity has a
+  narrow pre-handshake 401 refresh; that is not live-session recovery.
+- Large events are valid. Plan memory and application backpressure for your
+  workload without treating a fixed payload size as a protocol maximum.
+
+## Offline verification
+
+```sh
+bundle exec ruby -Itest test/openai/responses_websocket/workflows_test.rb
+```
+
+The tests use real loopback WebSockets and synthetic data, exercise the default
+Responses transport, and make no live API requests. They cover the four example
+patterns, interleaved terminal events, fragmented text, premature EOF, failures,
+idle-read deadlines, and a large event exceeding 32 MiB.