openai 0.85.0 → 0.87.0

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.

data/sig/openai/auth/subject_token_providers.rbs

@@ -0,0 +1,42 @@
+module OpenAI
+  module Auth
+    module SubjectTokenProviders
+      class K8sServiceAccountTokenProvider
+        include OpenAI::Auth::SubjectTokenProvider
+
+        def initialize: (?token_path: String) -> void
+
+        def token_type: -> Symbol
+
+        def get_token: -> String
+      end
+
+      class AzureManagedIdentityTokenProvider
+        include OpenAI::Auth::SubjectTokenProvider
+
+        def initialize: (
+          ?resource: String,
+          ?object_id: String?,
+          ?client_id: String?,
+          ?msi_res_id: String?,
+          ?api_version: String,
+          ?timeout: Float
+        ) -> void
+
+        def token_type: -> Symbol
+
+        def get_token: -> String
+      end
+
+      class GCPIDTokenProvider
+        include OpenAI::Auth::SubjectTokenProvider
+
+        def initialize: (?audience: String, ?timeout: Float) -> void
+
+        def token_type: -> Symbol
+
+        def get_token: -> String
+      end
+    end
+  end
+end

data/sig/openai/errors.rbs

@@ -4,6 +4,9 @@ module OpenAI
       attr_reader cause: StandardError?
     end
 
+    class InvalidWebhookSignatureError < OpenAI::Errors::Error
+    end
+
     class PollingError < OpenAI::Errors::Error
     end
 
@@ -59,6 +62,9 @@ module OpenAI
     end
 
     class APIConnectionError < OpenAI::Errors::APIError
+      # @api private
+      def request_may_have_been_sent?: -> bool
+
       def initialize: (
         url: URI::Generic,
         ?status: nil,
@@ -66,7 +72,8 @@ module OpenAI
         ?body: nil,
         ?request: nil,
         ?response: nil,
-        ?message: String?
+        ?message: String?,
+        ?request_may_have_been_sent: bool
       ) -> void
     end
 
@@ -78,7 +85,8 @@ module OpenAI
         ?body: nil,
         ?request: nil,
         ?response: nil,
-        ?message: String?
+        ?message: String?,
+        ?request_may_have_been_sent: bool
       ) -> void
     end
 
@@ -135,5 +143,31 @@ module OpenAI
     class InternalServerError < OpenAI::Errors::APIStatusError
       HTTP_STATUS: Range[Integer]
     end
+
+    class OAuthError < OpenAI::Errors::APIStatusError
+      def status: -> Integer
+
+      def status=: (Integer) -> Integer
+
+      attr_reader error_code: OpenAI::Models::oauth_error_code?
+
+      def initialize: (
+        status: Integer,
+        body: Object?,
+        headers: ::Hash[String, String]?
+      ) -> void
+    end
+
+    class SubjectTokenProviderError < OpenAI::Errors::Error
+      attr_reader provider: String
+
+      attr_accessor cause: StandardError?
+
+      def initialize: (
+        message: String,
+        provider: String,
+        ?cause: StandardError?
+      ) -> void
+    end
   end
 end

data/sig/openai/file_part.rbs

@@ -26,5 +26,8 @@ module OpenAI
       ?filename: (Pathname | String)?,
       ?content_type: String?
     ) -> void
+
+    # @api private
+    private def strip_directories: (Pathname | String filename) -> String
   end
 end

data/sig/openai/helpers/local_audio/interface.rbs

@@ -0,0 +1,62 @@
+module OpenAI
+  module LocalAudio
+    def self.record: (
+      duration: Numeric,
+      ?device: (String | Integer)?,
+      ?timeout: Numeric?
+    ) -> OpenAI::FilePart
+    def self.play: (
+      IO | StringIO | OpenAI::FilePart source,
+      ?format: :auto | :pcm,
+      ?timeout: Numeric?
+    ) -> nil
+
+    # @api private
+    def self.playback_source: (
+      IO | StringIO | OpenAI::FilePart source
+    ) -> (IO | StringIO)
+
+    # @api private
+    def self.capture_device: (
+      (String | Integer)? device,
+      ?platform: String
+    ) -> [String, String]
+
+    # @api private
+    def self.wav_header: (Integer bytes) -> String
+
+    # @api private
+    class MediaProcess
+      def self.environment: -> Hash[String, String]
+      def self.clock: -> Float
+      def self.duration: (Numeric value, name: String | Symbol) -> Float
+      def initialize: (
+        Array[String] argv,
+        input: IO | String,
+        output: IO | String,
+        timeout: Numeric?,
+        ?capture_errors: bool
+      ) -> void
+      def check_deadline: -> void
+      def errors?: -> bool
+      def read: (IO | StringIO io, ?stop_on_exit: bool) -> String?
+      def write: (IO io, String bytes) -> void
+      def wait: -> Process::Status
+      def close: -> void
+    end
+    class Error < OpenAI::Errors::Error
+    end
+    class DependencyError < OpenAI::LocalAudio::Error
+    end
+    class UnsupportedPlatformError < OpenAI::LocalAudio::Error
+    end
+    class DeviceError < OpenAI::LocalAudio::Error
+    end
+    class PlaybackError < OpenAI::LocalAudio::Error
+    end
+    class TimeoutError < OpenAI::LocalAudio::Error
+    end
+    class FormatError < OpenAI::LocalAudio::Error
+    end
+  end
+end

data/sig/openai/helpers/realtime/connection.rbs

@@ -19,7 +19,11 @@ module OpenAI
         attr_reader input_audio_buffer: OpenAI::Realtime::ConnectionResources::InputAudioBuffer
 
         # @api private
-        def initialize: (socket: untyped, url: URI::Generic) -> void
+        def initialize: (
+          socket: untyped,
+          url: URI::Generic,
+          ?recovery: untyped
+        ) -> void
         def each:
           -> Enumerator[OpenAI::Models::Realtime::connection_server_event, self]
           | {
@@ -39,6 +43,10 @@ module OpenAI
         # @api private
         def abort: -> nil
         def closed?: -> bool
+        def reconnecting?: -> bool
+        def pending_messages: -> Array[String]
+        def take_pending_messages: -> Array[String]
+        def flush_pending: -> nil
       end
     end
   end

data/sig/openai/helpers/realtime/extensions.rbs

@@ -23,7 +23,7 @@ module OpenAI
   end
 
   module Errors
-    class RealtimeConnectionError < OpenAI::Errors::Error
+    class RealtimeConnectionError < OpenAI::Errors::WebSocketConnectionError
       attr_reader url: URI::Generic
 
       # @api private
@@ -39,7 +39,7 @@ module OpenAI
       ) -> void
     end
 
-    class RealtimeProtocolError < OpenAI::Errors::Error
+    class RealtimeProtocolError < OpenAI::Errors::WebSocketProtocolError
       attr_reader data: String
       def cause: -> StandardError?
 
@@ -52,6 +52,10 @@ module OpenAI
     class Realtime
       def connect: (
         model: String,
+        ?reconnect: bool,
+        ?max_reconnect_attempts: Integer,
+        ?max_queue_bytes: Integer,
+        ?on_reconnected: (^(OpenAI::Realtime::Connection) -> void)?,
         ?websocket_base_url: String?,
         ?request_options: OpenAI::request_opts?,
         ?transport: untyped?,

data/sig/openai/helpers/realtime/recovery.rbs

@@ -0,0 +1,19 @@
+module OpenAI
+  module Errors
+    class RealtimeQueueFullError < OpenAI::Errors::Error
+      def initialize: -> void
+    end
+
+    class RealtimeReconnectError < OpenAI::Errors::Error
+      attr_reader unsent_messages: Array[String]
+      attr_reader uncertain_message: String?
+
+      # @api private
+      def initialize: (
+        message: String,
+        ?unsent_messages: Array[String],
+        ?uncertain_message: String?
+      ) -> void
+    end
+  end
+end

data/sig/openai/helpers/responses_websocket/connection.rbs

@@ -0,0 +1,48 @@
+module OpenAI
+  module Models
+    module Responses
+      type connection_server_event =
+        OpenAI::Models::Responses::responses_server_event
+        | OpenAI::Responses::UnknownServerEvent
+
+      type connection_client_event =
+        OpenAI::Models::Responses::responses_client_event
+        | ::Hash[Symbol | String, untyped]
+
+      class Connection
+        include Enumerable[OpenAI::Models::Responses::connection_server_event]
+
+        attr_reader url: URI::Generic
+        attr_reader response: OpenAI::Responses::ConnectionResources::Response
+
+        # @api private
+        def initialize: (socket: top, url: URI::Generic) -> void
+        def each:
+          -> Enumerator[OpenAI::Models::Responses::connection_server_event, self]
+          | {
+            (OpenAI::Models::Responses::connection_server_event event) -> void
+          } -> self
+        def receive: -> OpenAI::Models::Responses::connection_server_event?
+
+        # @api private
+        def receive_raw: -> String?
+
+        def send_event: (
+          OpenAI::Models::Responses::connection_client_event event
+        ) -> nil
+
+        # @api private
+        def send_raw: (String data) -> nil
+
+        def close: (?code: Integer, ?reason: String) -> nil
+
+        # @api private
+        def abort: -> nil
+        def closed?: -> bool
+
+        # @api private
+        def poisoned?: -> bool
+      end
+    end
+  end
+end

data/sig/openai/helpers/responses_websocket/connection_manager.rbs

@@ -0,0 +1,19 @@
+module OpenAI
+  module Models
+    module Responses
+      class ConnectionManager
+        # @api private
+        def initialize: (
+          client: OpenAI::Client,
+          websocket_base_url: String?,
+          transport: top,
+          request_options: OpenAI::request_opts?,
+          transport_options: ::Hash[Symbol, top]
+        ) -> void
+
+        # @api private
+        def open: { (OpenAI::Responses::Connection connection) -> top } -> top
+      end
+    end
+  end
+end

data/sig/openai/helpers/responses_websocket/connection_resources.rbs

@@ -0,0 +1,12 @@
+module OpenAI
+  module Models
+    module Responses
+      module ConnectionResources
+        class Response
+          # @api private
+          def initialize: (OpenAI::Responses::Connection connection) -> void
+        end
+      end
+    end
+  end
+end

data/sig/openai/helpers/responses_websocket/extensions.rbs

@@ -0,0 +1,55 @@
+module OpenAI
+  class Client
+    # @api private
+    def with_responses_websocket_connection_request: (
+      ?websocket_base_url: String?,
+      ?options: OpenAI::request_opts?
+    ) {
+      (
+        OpenAI::Internal::Transport::BaseClient::request_input request,
+        ^-> void mark_handshake_completed
+      ) -> top
+    } -> top
+  end
+
+  module Errors
+    class ResponsesConnectionError < OpenAI::Errors::WebSocketConnectionError
+      attr_reader url: URI::Generic
+      attr_reader http_status: Integer?
+      def cause: -> Exception?
+      def initialize: (
+        url: URI::Generic,
+        ?message: String?,
+        ?http_status: Integer?
+      ) -> void
+    end
+
+    class ResponsesProtocolError < OpenAI::Errors::WebSocketProtocolError
+      def cause: -> Exception?
+      def initialize: -> void
+    end
+
+    class ResponsesClientEventError < OpenAI::Errors::Error
+      def cause: -> Exception?
+      def initialize: -> void
+    end
+
+    class ResponsesSendError < ResponsesConnectionError
+      attr_reader outcome: Symbol
+      def initialize: (url: URI::Generic) -> void
+    end
+  end
+
+  module Resources
+    class Responses
+      def connect: (
+        ?websocket_base_url: String?,
+        ?request_options: OpenAI::request_opts?,
+        ?transport: top?,
+        ?transport_options: ::Hash[Symbol, top]
+      ) {
+        (OpenAI::Responses::Connection connection) -> top
+      } -> top
+    end
+  end
+end