openai 0.114.0 → 0.115.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8905b3e720546308f3334931a036c17e3e990e66ec863039da6c661d6024dec
-  data.tar.gz: 4698d4841fd6becc4266b58c8b863e3fb7b50a16d4b76523808ac291e5c566f3
+  metadata.gz: 5ced72b8e35330a5d4832f6e8a19c4b989c320faea258dcae427e0df5daa5af7
+  data.tar.gz: 346d52cbceace88063f31b32abb7f3e3f0a6c85da9315444335534f5fc3d554c
 SHA512:
-  metadata.gz: e664a8f9ee816f4deb836f3b03b1d82a5178f9d8e85fa42a25530e1b3d514273dbefd17da517837b5ef197e51c0e16abcf85c845491744278339903abc3b1502
-  data.tar.gz: 6398277b839b172914d849d071a4994d8a2c0e90ef74cde85ce76f27c940753b000e0f709f05a1d1e0f9ab8fdb7c44ce3cb77f5f6f8fcde257fbd4cdc466673c
+  metadata.gz: 664188f40a63883c74614050aa814ee2f207135c74856c0e132df3452f9d42a54f01f23133872459ef91fd2d078f11ca01f2bb4e008e59eb53b780e611978435
+  data.tar.gz: cc89bc9ed7879748bba0bc27f3f4ee84c963faed1dc5305016d8d57b590a85eafb48e5c3dc65a9aa24f012a3285df4858e621471687292f3058c886164c3892c

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [0.115.0](https://github.com/openai/openai-ruby/compare/v0.114.0...v0.115.0) (2026-10-31)
+
+
+### Features
+
+* **api:** add agent context compaction settings ([#1003](https://github.com/openai/openai-ruby/issues/1003)) ([6f5b0a3](https://github.com/openai/openai-ruby/commit/6f5b0a3454aed204ccd8baad2ff0fb8bca1c17a5))
+* **api:** add agent session review and tool settings ([#1013](https://github.com/openai/openai-ruby/issues/1013)) ([b604fe7](https://github.com/openai/openai-ruby/commit/b604fe7ad3b252adcc3200314a46a028c9ad9a9b))
+* **api:** add experimental agent time awareness ([#1005](https://github.com/openai/openai-ruby/issues/1005)) ([25ab8e9](https://github.com/openai/openai-ruby/commit/25ab8e922a4f5f1adf74390139d08f8cb9f21db8))
+* **api:** add image edit markup overlays ([#1004](https://github.com/openai/openai-ruby/issues/1004)) ([79e7168](https://github.com/openai/openai-ruby/commit/79e7168b33bccf79d66700b0ac9820cb80d7ef36))
+* **api:** add organization external key management ([#998](https://github.com/openai/openai-ruby/issues/998)) ([e0313fc](https://github.com/openai/openai-ruby/commit/e0313fc261c816fba0628d4fc6e576b674e1d9df))
+* **api:** add SIP DTMF commands and delivery events ([#1002](https://github.com/openai/openai-ruby/issues/1002)) ([0ed1bc6](https://github.com/openai/openai-ruby/commit/0ed1bc69dd8249544631fe7335495f3807a46fd3))
+* **api:** complete request input type definitions ([#999](https://github.com/openai/openai-ruby/issues/999)) ([543fea3](https://github.com/openai/openai-ruby/commit/543fea32e06ee61b2ad5a201fe988120c646b75b))
+* **api:** expose hosted tool usage on responses ([#995](https://github.com/openai/openai-ruby/issues/995)) ([429e9ad](https://github.com/openai/openai-ruby/commit/429e9ad7b436e8c4bc85ea30f5e109f191393f93))
+* **api:** filter agent sessions by metadata ([#992](https://github.com/openai/openai-ruby/issues/992)) ([9dc8a3d](https://github.com/openai/openai-ruby/commit/9dc8a3dd0148cf6e08d18f0b1e0fca8d121311d8))
+* **api:** improve WebSocket encoding and recovery ([#1007](https://github.com/openai/openai-ruby/issues/1007)) ([d1a4b87](https://github.com/openai/openai-ruby/commit/d1a4b87292b52a5a718d7ed40ce6d68750c16ada))
+* **api:** support Responses WebSocket warmup ([#1012](https://github.com/openai/openai-ruby/issues/1012)) ([db09dba](https://github.com/openai/openai-ruby/commit/db09dba45a16e329c436df599e453be74d97b1ad))
+* **api:** support text formats on Responses configuration updates ([#1006](https://github.com/openai/openai-ruby/issues/1006)) ([c8b295c](https://github.com/openai/openai-ruby/commit/c8b295cc209fabc4e52db9bf321176c525f67cc9))
+
+
+### Bug Fixes
+
+* accept omitted nullable text in chat tool responses ([#993](https://github.com/openai/openai-ruby/issues/993)) ([b276766](https://github.com/openai/openai-ruby/commit/b2767663f881b47aae65fb1d9d452d64a2ec0cab))
+* preserve Vertex API root for stored responses ([#984](https://github.com/openai/openai-ruby/issues/984)) ([5bcd40b](https://github.com/openai/openai-ruby/commit/5bcd40b01cecb83a1e0a2bc044f7c7902ec0de7f))
+* **realtime:** allow developer messages in response input ([#978](https://github.com/openai/openai-ruby/issues/978)) ([ced5c63](https://github.com/openai/openai-ruby/commit/ced5c6315a9ad411a0d9704df9405c5a600ba55b))
+* **realtime:** reject overlapping reads on physical WebSockets ([#1011](https://github.com/openai/openai-ruby/issues/1011)) ([5317eb4](https://github.com/openai/openai-ruby/commit/5317eb42a544ddbc6ca3950d828f601edfbd0f4c))
+* reject overlapping Live WebSocket reads ([#1009](https://github.com/openai/openai-ruby/issues/1009)) ([e669431](https://github.com/openai/openai-ruby/commit/e669431961a0f14bc2c20ec83d167d701b2df3a0))
+* require explicit WebSocket transport for custom HTTP clients ([#1008](https://github.com/openai/openai-ruby/issues/1008)) ([54bb670](https://github.com/openai/openai-ruby/commit/54bb67010e46d25921f8ff33731640954f047ece))
+
+
+### Chores
+
+* **api:** document upcoming model shutdowns ([#990](https://github.com/openai/openai-ruby/issues/990)) ([ace1351](https://github.com/openai/openai-ruby/commit/ace13514e2db8f3a0f3d6b5a409d76e08e3b1bc1))
+* **api:** preserve organization external key request contracts ([#1001](https://github.com/openai/openai-ruby/issues/1001)) ([7ea9e1d](https://github.com/openai/openai-ruby/commit/7ea9e1dd9926ae5cbf692aecbedbc4f6c5f6c59a))
+* **api:** update image-model documentation ([#985](https://github.com/openai/openai-ruby/issues/985)) ([02c1d66](https://github.com/openai/openai-ruby/commit/02c1d66449a2ddda2ad64d0edf425795c1ee3f5c))
+* enforce generated-file ownership ([#979](https://github.com/openai/openai-ruby/issues/979)) ([300d5d2](https://github.com/openai/openai-ruby/commit/300d5d2889714a436dd73421f510b7b3b97f8379))
+
 ## [0.114.0](https://github.com/openai/openai-ruby/compare/v0.113.0...v0.114.0) (2026-10-27)
 
 

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "openai", "~> 0.114.0"
+gem "openai", "~> 0.115.0"
 ```
 
 <!-- x-release-please-end -->
@@ -226,7 +226,12 @@ client.responses.connect do |connection|
 
   connection.each do |event|
     print(event.delta) if event.type == :"response.output_text.delta"
-    break if event.type == :"response.completed"
+    case event.type
+    when :"response.completed"
+      break
+    when :"response.failed", :"response.incomplete", :error
+      raise "Responses operation did not complete."
+    end
   end
 end
 ```
@@ -453,6 +458,16 @@ origin, as above, so they cannot be presented elsewhere. Use the
 Server trust remains separate from the client identity and can be customized
 with `Net::HTTP` properties such as `cert_store` or `ca_file`.
 
+An HTTP client's connection settings do not carry over to the default
+WebSocket transport. If you configure `http_client:` with a custom requester
+or customized `OpenAI::NetHTTPClient`, pass a compatible `transport:` when
+opening Responses, Realtime, Translation, or Live WebSockets. The SDK checks
+this before fetching credentials or opening a connection. The supplied
+WebSocket transport must enforce the connection settings your application
+requires; the SDK still validates its supported authentication and provider
+scope. See the [Realtime custom transport contract](realtime.md#custom-transport)
+and [Responses transport options](responses-websocket.md).
+
 Each `OpenAI::NetHTTPClient` owns its connection pool, so separate HTTP client
 instances do not share connections or credentials.
 

data/docs/architecture/security-model.md

@@ -1,5 +1,10 @@
 # OpenAI Ruby SDK Security Model
 
+Generated files are updated through authoritative inputs or the compiler and
+regeneration; handwritten edits to them are forbidden. Code review enforces this
+ownership rule. The customization-budget reporter and publishers are retired
+and are not part of the active CI or security controls.
+
 This is the canonical detailed threat model for this repository. `SECURITY.md`
 remains the authority for disclosure and reportability; this document is the
 authority for architecture, trust boundaries, security invariants, attack
@@ -7,6 +12,11 @@ surface, and severity calibration. Codex Security scans must load this file
 from the scanned revision instead of relying on a duplicated cloud-configured
 model.
 
+Generated-file ownership currently relies on `AGENTS.md`, contributor guidance,
+and ordinary SDK code review. There is no dedicated generated-file edit check or
+required gate. Review generated output and inventory changes together; fix
+violations in the inputs/compiler and regenerate.
+
 ## 1. Overview
 
 The OpenAI Ruby gem is a caller-embedded Ruby 3.3+ library, not a hosted
@@ -23,7 +33,6 @@ requests, then parses remote responses into typed Ruby values
 | Streaming and Realtime helpers | Construct authenticated WebSocket handshakes, enforce transport policy, and parse SSE/WebSocket JSON into typed events | `lib/openai/internal/stream.rb:19-60`, `lib/openai/helpers/realtime/client_extension.rb:167-280`, `lib/openai/helpers/realtime/transports/async_websocket.rb:185-308`, `lib/openai/helpers/realtime/connection.rb:47-100` |
 | Webhook helper | Verify timestamp and HMAC before parsing webhook events | `lib/openai/resources/webhooks.rb:15-119` |
 | Providers and workload identity | Azure, Bedrock, built-in subject-token acquisition, exchange, and X.509 credential paths | `lib/openai/providers/azure.rb:40-58`, `lib/openai/auth/subject_token_providers/gcp_id_token_provider.rb:9-67`, `lib/openai/auth/subject_token_providers/azure_managed_identity_token_provider.rb:9-92`, `lib/openai/auth/subject_token_providers/k8s_service_account_token_provider.rb:9-37`, `lib/openai/auth/workload_identity_auth.rb:280-330` |
-| CI and release workflows | Run repository code, upload CodeQL results, publish trusted Castiron results, live checks/examples, and releases | `.github/workflows/ci.yml:18-32`, `.github/workflows/codeql.yml:3-53`, `.github/workflows/castiron-custom-code-comment.yml:4-38`, `.github/workflows/examples-e2e.yml:1-43`, `.github/workflows/create-releases.yml:14-79` |
 
 ```mermaid
 flowchart LR
@@ -36,9 +45,6 @@ flowchart LR
   PR[Candidate checkout] --> CI[Ordinary read-only CI]
   PR --> CodeQL[CodeQL analysis]
   CodeQL --> SecurityEvents[Code-scanning results]
-  PR --> Castiron[Candidate Castiron workflow]
-  Castiron --> Trusted[Main-sourced workflow_run publisher]
-  Trusted --> GitHub[Statuses and PR comments]
   Main[Main revision] --> Live[Live / release workflows]
   Live --> Secrets[Referenced credentials and publishing authority]
 ```
@@ -57,7 +63,6 @@ flowchart LR
 | Dependency acquisition and installation | Gem source, locked revision, transitive gem, native extension, and install/build-script execution | Contributor/CI `Gemfile` selects `syntax_tree-rbs` from GitHub branch `main` and `Gemfile.lock` pins revision `247832988a850b8df050cf207f652872fda49973`; Bedrock CI selects `aws-sdk-core` through `gemfiles/bedrock.gemfile` and its lock; docs lockfiles and gemspec dependencies select other installed code | Locked RubyGems and Git sources plus package metadata from the reviewed revision | CI runners and consumer Bundler/RubyGems installations | Human/source review of dependency and lockfile changes; CI verifies the reviewed checkout but does not make an unreviewed dependency trustworthy | `AGENTS.md:39-42`, `Gemfile:3-15`, `Gemfile.lock:1-20`, `gemfiles/bedrock.gemfile:1-5`, `gemfiles/bedrock.gemfile.lock:1-58`, `.github/workflows/ci-checks.yml:124-144`, `openai.gemspec:18-48`, `docs/Gemfile:1-8`, `docs/Gemfile.lock:1-21` |
 | Ordinary PR CI | Candidate checkout execution | Checked-out PR revision runs lint, typecheck, build, and tests | Candidate code executes with repository-code authority | Ephemeral CI runner | `permissions: {}`, `contents: read`, `persist-credentials: false` | `.github/workflows/ci.yml:18-32`, `.github/workflows/ci-checks.yml:100-120` |
 | CodeQL PR analysis | Candidate checkout and code-scanning result upload | Pull requests, main pushes, and merge-group checks run action and Ruby analysis | Candidate source produces SARIF under runner temp; `security-events: write` uploads code-scanning results | GitHub code scanning | Top-level `permissions: {}`; job grants only `actions: read`, `contents: read`, and `security-events: write`; pinned checkout/CodeQL actions; `persist-credentials: false`; checked SARIF must exist and contain no findings | `.github/workflows/codeql.yml:3-28`, `.github/workflows/codeql.yml:37-53`, `.github/workflows/codeql.yml:55-96` |
-| Trusted Castiron workflow-run publisher | Commit-status and PR-comment writes | Candidate-associated `workflow_run` metadata -> main-sourced reporter recomputes from current Git objects for statuses and successful report comments; fallback failure comments use event/path, current-head, and monotonic-replacement checks | `statuses: write` and `pull-requests: write` only in publisher jobs | GitHub commit statuses and PR comments | Status path: no candidate artifact, run identity validation, exact head/base checks; successful comment path: trusted report artifact; fallback failure-comment path: main-sourced code, event/path filtering, current-head matching, monotonic replacement | `.github/workflows/castiron-custom-code-comment.yml:4-38`, `.github/workflows/castiron-custom-code-comment.yml:40-98`, `.github/workflows/castiron-custom-code-comment.yml:116-171`, `.github/workflows/castiron-custom-code-comment.yml:174-237` |
 | Live/release workflows | API keys, X.509 material, GitHub App private key, generated GitHub App token, RubyGems OIDC | Main-only conditions plus named environments; release job passes `OPENAI_SDKS_APP_PRIVATE_KEY` to pinned token action, then passes generated token to Release Please | Referenced long-lived private key as action input; generated short-lived release token; publishing OIDC | Main revision, token action, OpenAI API, GitHub, RubyGems | Repository/ref conditions, separate named environments, least privilege, pinned actions, generated token handoff, OIDC only for publishing | `.github/workflows/live-smoke.yml:17-92`, `.github/workflows/create-releases.yml:17-79` |
 | Examples E2E workflow | Live-example API credential and uploaded reports | Manual dispatch; main/repository condition; named `ci` environment; `OPENAI_API_KEY` secret reference | Credential only in the live-example step; allowlisted `report.json` and `summary.md` under runner temp | OpenAI API and GitHub artifact readers | `permissions: {}`, `contents: read`, checkout without persisted credentials, main/repository condition, allowlisted reports, 14-day retention, focused confidentiality/isolation tests | `.github/workflows/examples-e2e.yml:1-43`, `test/scripts/examples_e2e_test.rb:202-234`, `test/scripts/examples_e2e_test.rb:306-327` |
 
@@ -188,16 +193,7 @@ Important boundaries:
   (`.github/workflows/examples-e2e.yml:1-43`,
   `test/scripts/examples_e2e_test.rb:202-234`,
   `test/scripts/examples_e2e_test.rb:306-327`).
-- Candidate-associated `workflow_run` metadata and Git objects crossing into
-  the trusted Castiron publisher are a genuine write-capable boundary. The
-  status path must preserve run-identity and exact-head/base checks; successful
-  report comments must remain bound to the trusted report artifact. The
-  fallback failure-comment path has narrower main-sourced event/path,
-  current-head, and monotonic-replacement checks that scans must assess
-  independently
-  (`.github/workflows/castiron-custom-code-comment.yml:34-98`,
-  `.github/workflows/castiron-custom-code-comment.yml:116-171`,
-  `.github/workflows/castiron-custom-code-comment.yml:174-237`).
+
 - Dependency declarations and locks cross a supply-chain boundary when Bundler
   or RubyGems fetches and executes selected package code in CI or consumer
   applications. A changed source, Git revision, transitive gem, native
@@ -261,7 +257,6 @@ The following are hypotheses and review guidance, not confirmed findings.
 | High | Candidate PR code reaches live/release credentials or publishing authority | Privileged workflow executes candidate code or exposes secrets/write tokens | Credential theft or release compromise | Main-only conditions, named environments, least-privilege permissions, trusted publisher separation | Keep candidate and live/release workflows isolated | `.github/workflows/live-smoke.yml:17-92`, `.github/workflows/create-releases.yml:17-79` |
 | High | Release GitHub App private key reaches an unintended action, log, or artifact | Main/repository release gate or pinned token-action input boundary regresses | Attacker can mint GitHub App tokens beyond one workflow token lifetime | Main/repository condition, named release environment, empty job permissions, pinned token action, generated token passed separately to Release Please | Keep the private key confined to token minting and preserve generated-token handoff | `.github/workflows/create-releases.yml:17-46` |
 | Medium | Candidate source or generated SARIF influences the write-capable CodeQL upload outside its intended code-scanning result path | PR-adjacent CodeQL action or token scoping regresses | Forged or unintended code-scanning results | Top-level empty permissions; scoped `security-events: write`; read-only content/metadata; pinned actions; no persisted checkout credentials; SARIF existence/shape/finding checks | Preserve least privilege and keep upload input limited to CodeQL output | `.github/workflows/codeql.yml:3-28`, `.github/workflows/codeql.yml:37-53`, `.github/workflows/codeql.yml:55-96` |
-| High | Candidate-associated workflow metadata or Git objects influence the write-capable Castiron publisher without the path-specific trusted validation | Attacker controls a PR head or associated workflow metadata and a status, successful-comment, or fallback-comment check regresses | Forged or stale commit statuses and PR comments | Statuses use main-sourced recomputation plus run/head/base checks; successful comments use a trusted report artifact; fallback comments rely on main-sourced event/path, current-head, and monotonic-replacement checks | Preserve each path's distinct recomputation, freshness, artifact-binding, or fallback-isolation checks before its write | `.github/workflows/castiron-custom-code-comment.yml:34-98`, `.github/workflows/castiron-custom-code-comment.yml:116-171`, `.github/workflows/castiron-custom-code-comment.yml:174-237` |
 | High | A dependency declaration or lockfile selects malicious package code, native extension, or install/build script | Lower-trust change alters a source, Git revision, transitive dependency, or executable package hook that CI or a consumer installs; the contributor/CI bundle currently includes Git-sourced `syntax_tree-rbs` locked at `247832988a850b8df050cf207f652872fda49973`; Bedrock CI separately installs its `aws-sdk-core` bundle | Code execution in CI or consumer applications | Reviewed lockfiles and dependency policy; ordinary and Bedrock CI execute selected dependencies with runner authority | Review direct/transitive dependencies, sources, locked revisions, native extensions, and scripts before acceptance | `AGENTS.md:39-42`, `Gemfile:3-15`, `Gemfile.lock:1-20`, `gemfiles/bedrock.gemfile:1-5`, `gemfiles/bedrock.gemfile.lock:1-58`, `.github/workflows/ci-checks.yml:124-144`, `openai.gemspec:18-48`, `docs/Gemfile:1-8`, `docs/Gemfile.lock:1-21` |
 | High | Built-in subject-token acquisition or exchange sends a token to an unintended source, proxy, issuer, or origin | Lower-trust configuration, caller-owned environment proxy, local token path, metadata response, or endpoint handling is bypassed | Credential disclosure or forged authentication | Fixed GCP metadata host/path/header with configurable audience/timeout; fixed Azure IMDS endpoint/header with configurable resource/selectors/API version/timeout and JSON token extraction; inherited Net::HTTP environment-proxy routing remains caller-owned; configured/default Kubernetes path with mapped failures; fixed/default issuer paths, origin checks, X.509 destination restrictions | Preserve strict source, proxy, destination, timeout, redirect, and response-parsing handling | `lib/openai/auth/subject_token_providers/gcp_id_token_provider.rb:9-67`, `lib/openai/auth/subject_token_providers/azure_managed_identity_token_provider.rb:9-92`, `lib/openai/auth/subject_token_providers/k8s_service_account_token_provider.rb:9-37`, `lib/openai/auth/workload_identity_auth.rb:303-330`, `lib/openai/providers/bedrock.rb:398-427` |
 | High | Realtime bearer credentials, proxy credentials, or trace data reach an unintended destination or audience | Lower-trust destination, proxy, TLS, or tracing behavior bypasses handshake controls | Credential disclosure or authenticated connection to the wrong peer | Base-URL/provider restrictions, proxy-header stripping, WSS verification, proxy handling, trace redaction | Preserve destination/TLS/proxy/redaction controls independently from event parsing | `lib/openai/helpers/realtime/client_extension.rb:167-280`, `lib/openai/helpers/realtime/transports/async_websocket.rb:185-224`, `lib/openai/helpers/realtime/transports/async_websocket.rb:294-378` |

data/examples/responses/websocket_workflows.rb

@@ -8,6 +8,11 @@ require_relative "../../lib/openai"
 module OpenAI
   module Examples
     module ResponsesWebSocketWorkflows
+      # Identify only this example's idle timeout. Other cancellation and
+      # transport errors keep their original contracts.
+      class PreviewTimeout < StandardError
+      end
+
       module_function
 
       # One reader drains all requested lanes. This example fails the entire
@@ -80,6 +85,70 @@ module OpenAI
         )
       end
 
+      # max_bytes counts cumulative encoded typed events, not wire bytes or
+      # total process memory. Call separately for each response on each lane.
+      def preview_lane(lane, max_bytes:, seconds:)
+        unless max_bytes.is_a?(Integer) &&
+            max_bytes.positive? &&
+            (seconds.is_a?(Integer) || seconds.is_a?(Float)) &&
+            Float(seconds).finite? &&
+            seconds.positive?
+          raise ArgumentError, "Choose a positive integer byte budget and finite positive lifetime."
+        end
+
+        preview = OpenAI::Responses::IncrementalResponse.new
+        admitted_bytes = 0
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        Async::Task.current.with_timeout(seconds, PreviewTimeout) do
+          loop do
+            return {outcome: :timeout} if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+            event = lane.receive
+            data = event.is_a?(OpenAI::Responses::UnknownServerEvent) ? event.to_h : event.deep_to_h
+            encoded_bytes = JSON.generate(data, max_nesting: false).bytesize
+            # Queued reads and JSON encoding can complete without yielding.
+            if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+              return {outcome: :timeout, last_received_event: event}
+            end
+
+            if encoded_bytes > max_bytes - admitted_bytes
+              return {outcome: :budget_exceeded, last_received_event: event}
+            end
+
+            admitted_bytes += encoded_bytes
+            preview.add(event)
+            if preview.phase == :terminal
+              terminal = preview.terminal_event
+              if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+                return {outcome: :timeout, last_received_event: event}
+              end
+
+              return {outcome: :terminal, terminal_event: terminal}
+            end
+          end
+        end
+
+      rescue PreviewTimeout
+        {outcome: :timeout}
+      ensure
+        preview&.reset
+      end
+
+      def preview(client:, model:)
+        # Limits for this short text example only. Choose larger budgets for
+        # legitimate image, audio, tool, or other large outputs.
+        OpenAI::Responses::Session
+          .open(
+            client: client,
+            limits: session_limits,
+            transport_options: {max_message_bytes: 16 * 1024 * 1024}
+          ) do |session|
+            lane = session.lane("preview")
+            lane.send_event(type: "response.create", model: model, input: "Write one brief sentence.")
+            preview_lane(lane, max_bytes: 4 * 1024 * 1024, seconds: 15)
+          end
+      end
+
       def multiplex(client:, model:)
         OpenAI::Responses::Session.open(client: client, limits: session_limits) do |session|
           lanes = %w[planner critic].to_h { |name| [name, session.lane(name)] }
@@ -181,7 +250,7 @@ module OpenAI
       end
 
       def run(client:, model:, workflow:, timeout: 60, output: $stdout)
-        Sync do |task|
+        result = Sync do |task|
           task.with_timeout(timeout) do
             case workflow
             when "tools"
@@ -192,13 +261,19 @@ module OpenAI
               reconnect(client: client, model: model, store: true)
             when "stateless"
               reconnect(client: client, model: model, store: false)
+            when "preview"
+              preview(client: client, model: model)
             else
-              raise ArgumentError, "Choose tools, multiplex, stored, or stateless."
+              raise ArgumentError, "Choose tools, multiplex, stored, stateless, or preview."
             end
           end
         end
 
-        output.puts("Responses WebSocket workflow completed.")
+        if workflow == "preview"
+          output.puts("Responses WebSocket preview: #{result.fetch(:outcome)}.")
+        else
+          output.puts("Responses WebSocket workflow completed.")
+        end
       end
     end
   end

data/lib/openai/helpers/chat/tool_runner.rb

@@ -101,7 +101,7 @@ module OpenAI
 
           [:content, :refusal].each do |field|
             value = message[field]
-            unless message.to_h.key?(field) && (value.nil? || value.is_a?(String))
+            unless value.nil? || value.is_a?(String)
               raise Error, "Expected assistant content and refusal to be strings or null"
             end
           end

data/lib/openai/helpers/live/websocket.rb

@@ -44,16 +44,46 @@ module OpenAI
 
     # A transport-open primary connection. Startup is owned by the caller:
     # send session.start and observe session.started before further commands.
+    # Only one receive call may read or decode at a time. Iteration releases
+    # the read before yielding an event to the caller.
     class Connection < OpenAI::WebSocket::TypedConnection
       # @api private
       def initialize(socket:, url:)
         super(socket: socket, url: url, client_event: client_event_type, server_event: server_event_type)
         @poisoned = false
         @closed = false
+        @read_mutex = Mutex.new
       end
 
       private :parse_event
 
+      def receive
+        with_read_lease { read_one }
+      end
+
+      # @api private
+      def receive_raw
+        with_read_lease { read_raw_message }
+      end
+
+      private def read_one
+        data = read_raw_message
+        return nil if data.nil?
+
+        parse_event(data)
+      end
+
+      private def with_read_lease
+        acquired = @read_mutex.try_lock
+        unless acquired
+          raise connection_error("Live WebSocket already has an active reader."), cause: nil
+        end
+
+        yield
+      ensure
+        @read_mutex.unlock if acquired
+      end
+
       private def coerce_client_event(payload) = coerce_event(@client_event, payload, outbound: true)
 
       private def coerce(type, payload)
@@ -210,6 +240,7 @@ module OpenAI
 
           OpenAI::WebSocket::ConnectionManager
             .new(
+              client: @client,
               transport: transport,
               transport_options: transport_options,
               default_transport: default_transport,

data/lib/openai/helpers/realtime/connection.rb

@@ -22,6 +22,7 @@ module OpenAI
       def initialize(socket:, url:, recovery: nil)
         super(socket: socket, url: url)
         @recovery = recovery
+        @read_mutex = Mutex.new
         @server_event_names = discriminator_values(OpenAI::Realtime::RealtimeServerEvent)
         @client_event_names = discriminator_values(OpenAI::Realtime::RealtimeClientEvent)
         @session = OpenAI::Realtime::ConnectionResources::Session.new(self)
@@ -63,6 +64,27 @@ module OpenAI
         send_raw(encode_client_event(event))
       end
 
+      # @api private
+      def enable_no_status_recovery
+        @socket.enable_no_status_recovery if @socket.respond_to?(:enable_no_status_recovery)
+        nil
+      end
+
+      private def read_raw_message
+        # Recovery already queues callers behind its one physical reader.
+        return super if @recovery
+
+        unless @read_mutex.try_lock
+          raise connection_error("A Realtime WebSocket read is already in progress."), cause: nil
+        end
+
+        begin
+          super
+        ensure
+          @read_mutex.unlock
+        end
+      end
+
       private def write_text(text)
         return super unless @recovery
 
@@ -114,6 +136,17 @@ module OpenAI
 
         payload = OpenAI::Internal::Type::Converter.dump(OpenAI::Realtime::RealtimeClientEvent, coerced)
         validate_discriminator!(payload, @client_event_names, kind: "client")
+        if payload[:type].to_s == "conversation.item.create"
+          item = payload[:item]
+          if item.is_a?(Hash)
+            item = item.transform_keys(&:to_s)
+            if item["type"].to_s == "item_reference" ||
+                (item["type"].to_s == "message" && item["role"].to_s == "developer")
+              raise ArgumentError, "Realtime item references and developer messages are only valid in response input"
+            end
+          end
+        end
+
         generate_json(payload)
       rescue SystemStackError
         raise ArgumentError, "Invalid Realtime client event.", cause: nil

data/lib/openai/helpers/realtime/connection_manager.rb

@@ -34,6 +34,7 @@ module OpenAI
         end
 
         super(
+          client: client,
           transport: transport,
           transport_options: transport_options,
           default_transport: -> { OpenAI::Realtime::Transports::AsyncWebSocket.new },

data/lib/openai/helpers/realtime/conversation_item_variant_resolver.rb

@@ -30,6 +30,11 @@ module OpenAI
             OpenAI::Realtime::RealtimeConversationItemUserMessage
           when "assistant"
             OpenAI::Realtime::RealtimeConversationItemAssistantMessage
+          when "developer"
+            # Use the registered model when available. Earlier generated schemas
+            # predate this supported role, so preserve just this message as JSON.
+            variants.find { _1.fields.dig(:role, :type) === :developer } ||
+              OpenAI::Internal::Type::Unknown
           else
             raise ArgumentError, "Realtime message item has an unknown role: #{role.inspect}"
           end

data/lib/openai/helpers/realtime/recovery.rb

@@ -99,7 +99,8 @@ module OpenAI
       end
 
       def write(text)
-        return write_once(text) if Fiber.current.equal?(@owner_fiber)
+        # Restore writes bypass the mailbox, but reentrant writes join an active flush.
+        return write_once(text) if Fiber.current.equal?(@owner_fiber) && !@mutex.synchronize { @flushing }
 
         reply = @mutex.synchronize do
           raise write_error(text), cause: nil if @error || [:closed, :ending].include?(@state)
@@ -124,6 +125,8 @@ module OpenAI
 
       def flush_pending
         if Fiber.current.equal?(@owner_fiber)
+          return nil if @mutex.synchronize { @flushing }
+
           raise state_error("Queue flush interrupted; remaining events were not sent."), cause: nil unless flush
           return nil
         end
@@ -246,6 +249,7 @@ module OpenAI
       private def serve(physical)
         @owner_fiber = Fiber.current
         @physical = physical
+        @physical.enable_no_status_recovery
         @mutex.synchronize do
           return if @state == :closed
 

data/lib/openai/helpers/realtime/translation.rb

@@ -138,6 +138,10 @@ module OpenAI
             )
           end
 
+          if @active_reads.positive?
+            raise connection_error("A Realtime Translation WebSocket read is already in progress."), cause: nil
+          end
+
           @active_reads += 1
         end
 
@@ -245,6 +249,7 @@ module OpenAI
 
           OpenAI::WebSocket::ConnectionManager
             .new(
+              client: @client,
               transport: transport,
               transport_options: transport_options,
               default_transport: default_transport,

data/lib/openai/helpers/realtime/transports/async_websocket.rb

@@ -16,6 +16,19 @@ module OpenAI
 
         private_constant :ERROR_FACTORY
 
+        # The optional transport discards an empty close frame's status. Restore
+        # it only on sockets owned by automatic recovery, after native validation.
+        module RecoverNoStatusClose
+          def receive_close(frame)
+            super
+            if frame.payload.empty?
+              raise ::Protocol::WebSocket::ClosedError.new("Peer closed without a status", 1005)
+            end
+          end
+        end
+
+        private_constant :RecoverNoStatusClose
+
         # Compatibility wrapper for the socket class yielded before the shared
         # transport extraction.
         #
@@ -24,6 +37,12 @@ module OpenAI
           def initialize(connection, url:)
             super(connection, url: url, error_factory: ERROR_FACTORY)
           end
+
+          # @api private
+          def enable_no_status_recovery
+            @connection.extend(RecoverNoStatusClose) if @connection.respond_to?(:receive_close)
+            nil
+          end
         end
 
         def initialize(&tls_configurator)

data/lib/openai/helpers/responses_websocket/connection.rb

@@ -48,11 +48,20 @@ module OpenAI
       #
       # @return [nil]
       def send_event(event)
+        send_client_event(event)
+      end
+
+      # @api private
+      def send_response_create(event)
+        send_client_event(event, response_create: true)
+      end
+
+      private def send_client_event(event, response_create: false)
         assert_owner!
         raise connection_error("Cannot send on a closed Responses WebSocket.") if poisoned? || closed?
 
         encoded = begin
-          generate_json(encode_client_event(event))
+          generate_json(encode_client_event(event, response_create: response_create))
         rescue SystemStackError
           raise OpenAI::Errors::ResponsesClientEventError.new, cause: nil
         end
@@ -162,9 +171,12 @@ module OpenAI
       end
 
       # @api private
-      def encode_client_event(event)
-        validate_event_tree!(event)
-        payload = if event.is_a?(Hash)
+      def encode_client_event(event, response_create: false)
+        create_type = OpenAI::Responses::ResponsesClientEvent::ResponseCreate if response_create
+        validate_event_tree!(event, target: create_type)
+        payload = if response_create
+          OpenAI::Internal::Type::Converter.dump(create_type, event)
+        elsif event.is_a?(Hash)
           OpenAI::Internal::Type::Unknown.dump(event, state: {can_retry: true})
         else
           OpenAI::Internal::Type::Converter.dump(OpenAI::Responses::ResponsesClientEvent, event)
@@ -172,7 +184,7 @@ module OpenAI
 
         raise OpenAI::Errors::ResponsesClientEventError.new unless payload.is_a?(Hash)
 
-        normalize_event_keys(payload)
+        OpenAI::Helpers::StructuredOutput.prepare_configuration_updates!(normalize_event_keys(payload))
       rescue OpenAI::Errors::ResponsesClientEventError
         raise
       rescue StandardError
@@ -216,42 +228,68 @@ module OpenAI
         raise connection_error("Responses WebSocket connections are single-owner.")
       end
 
-      private def validate_event_tree!(value)
+      private def validate_event_tree!(value, target: nil)
         active = {}.compare_by_identity
-        pending = [[value, false]]
+        pending = [[value, false, target]]
         until pending.empty?
-          value, exiting = pending.pop
+          value, exiting, target = pending.pop
           if exiting
             active.delete(value)
             next
           end
 
+          # Use the serializer's selected type, so unknown extension hashes keep their
+          # wire keys even when they resemble Ruby aliases in another model.
+          while target.is_a?(OpenAI::Internal::Type::Union)
+            target = target.variant_for_dump(value)
+          end
+
           children = case value
           when OpenAI::Internal::Type::BaseModel
             data = value.to_h
             reject_duplicate_serialized_model_keys!(value.class, data)
-            [data]
+            unless target.is_a?(Class) && target <= OpenAI::Internal::Type::BaseModel
+              target = value.class
+            end
+
+            [[data, target]]
           when Hash
             reject_duplicate_semantic_keys!(value)
-            value.values
+            if target.is_a?(Class) && target <= OpenAI::Internal::Type::BaseModel
+              reject_duplicate_serialized_model_keys!(target, value, skip_coerce: true)
+              value.map do |key, child|
+                name = key.is_a?(String) ? key.to_sym : key
+                field = target.known_fields[name]
+                field = nil if field && field.fetch(:mode) == :coerce
+                [child, field && field.fetch(:type_fn).call]
+              end
+            elsif target.is_a?(OpenAI::Internal::Type::HashOf)
+              item_type = target.item_type
+              value.values.map { [_1, item_type] }
+            else
+              value.values.map { [_1, nil] }
+            end
+
           when Array
-            value
+            item_type = target.is_a?(OpenAI::Internal::Type::ArrayOf) ? target.item_type : nil
+            value.map { [_1, item_type] }
           else
             next
           end
 
           guard_cycle!(value, active)
-          pending << [value, true]
-          children.reverse_each { |child| pending << [child, false] }
+          pending << [value, true, nil]
+          children.reverse_each { |child, child_type| pending << [child, false, child_type] }
         end
 
         nil
       end
 
-      private def reject_duplicate_serialized_model_keys!(model, data)
-        serialized_keys = data.keys.map do |key|
+      private def reject_duplicate_serialized_model_keys!(model, data, skip_coerce: false)
+        serialized_keys = data.keys.filter_map do |key|
           name = key.is_a?(String) ? key.to_sym : key
           field = model.known_fields[name]
+          next if skip_coerce && field && field.fetch(:mode) == :coerce
           field ? field.fetch(:api_name) : name
         end
 

data/lib/openai/helpers/responses_websocket/connection_manager.rb

@@ -18,6 +18,7 @@ module OpenAI
         end
 
         super(
+          client: client,
           transport: transport,
           transport_options: transport_options,
           default_transport: -> { OpenAI::Responses::Transports::AsyncWebSocket.new },