openai 0.85.0 → 0.86.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37f60ef5c84fcaef53fccd86fa30e1cc0988b4033abdd3e14711247e082de5d4
-  data.tar.gz: 97cd2b216e53d22574e00031f94b0d2975393a9128a9d2528ea735679bb04f8f
+  metadata.gz: 0e2fc3cef6cd029385cb528885096cbf0640df90c238752af2ef76186c578578
+  data.tar.gz: 5ab2eac3ec679b9d43a141ec43ef70b294ed09a5e4f72f9a3c272cd407cbe3dc
 SHA512:
-  metadata.gz: 1493b225ac23056cda189b6af2bdd547aeb3441fef8f85c9454ae2d2d51e87e84743807cd86875f85a1d055eeb1f8c30ab684b7a11f76e46f86fbcd47c3b0995
-  data.tar.gz: 702dc478f26dff8454563e36b2d3ed4113ced5f04f104d34ab399091b290bf34ca3cccbb1ad8f44b2dae132d40053e33b9d0a86dc20f3a66316e0aed9378459d
+  metadata.gz: e80dd1fe954a867a454f08d6349689d71f731f1908add8fc5d48e25605a431202cd6f9366e0c30070ae5273195b37116e33a606f6a26de89957d23bea6dd855b
+  data.tar.gz: b87d683d9a0cbc8b59fcb6ddc31b9b1a1737455d7353bf7466736a375955018946f18ba753c79362f94fec9ef9b52f70dd90405cfd94d600e407aaf0b4d64ad5

data/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## [0.86.0](https://github.com/openai/openai-ruby/compare/v0.85.0...v0.86.0) (2026-09-08)
+
+
+### Features
+
+* add Responses WebSocket mode ([#562](https://github.com/openai/openai-ruby/issues/562)) ([7c910a7](https://github.com/openai/openai-ruby/commit/7c910a78ae4418dc59e766edc2467c254b814a89))
+* **api:** add cache diagnostics and fix optional RBS keys ([#604](https://github.com/openai/openai-ruby/issues/604)) ([4e4f7cd](https://github.com/openai/openai-ruby/commit/4e4f7cdda5b5e1c568badded52324af06c77378b))
+* **api:** add service-account API key expiration fields ([#625](https://github.com/openai/openai-ruby/issues/625)) ([8d3f213](https://github.com/openai/openai-ruby/commit/8d3f213da707b11ddbd913a801925b00b3e2bcc9))
+* **api:** correct function argument completion event fields (openapi-545) ([#622](https://github.com/openai/openai-ruby/issues/622)) ([06e2c91](https://github.com/openai/openai-ruby/commit/06e2c91dc349ba36d12ece05bf0b0cbf1ba0e220))
+* **api:** recognize incomplete web search call status ([#590](https://github.com/openai/openai-ruby/issues/590)) ([1560da0](https://github.com/openai/openai-ruby/commit/1560da01073061cc0a0dadc853f7dbc6e688a4d4))
+* **responses:** parse structured outputs on retrieval ([#532](https://github.com/openai/openai-ruby/issues/532)) ([41eb726](https://github.com/openai/openai-ruby/commit/41eb726b66fcb56f149553a9d681d8f1837b9b97))
+
+
+### Bug Fixes
+
+* accept documented RequestOptions extra query values ([#660](https://github.com/openai/openai-ruby/issues/660)) ([e168aa4](https://github.com/openai/openai-ruby/commit/e168aa47ee9ff81150a901c4eba1f236dea0dcf6))
+* accept string Responses structured-output tags ([#617](https://github.com/openai/openai-ruby/issues/617)) ([4322e07](https://github.com/openai/openai-ruby/commit/4322e076e57b769d619175006307763e3c630cfb))
+* **api:** expose metadata on binary responses ([#608](https://github.com/openai/openai-ruby/issues/608)) ([59e0643](https://github.com/openai/openai-ruby/commit/59e0643dbb37e95b4746b24b38c1489dd2867e33))
+* avoid retrying ambiguous non-idempotent requests ([#650](https://github.com/openai/openai-ruby/issues/650)) ([4734cba](https://github.com/openai/openai-ruby/commit/4734cba47984a53e241e224acb7f465372b34598))
+* avoid unused Responses stream snapshot copies ([#677](https://github.com/openai/openai-ruby/issues/677)) ([2996996](https://github.com/openai/openai-ruby/commit/2996996d8c68e96f5c8fb65da869a321988c5dc8))
+* close proxy after WebSocket handshake failure ([#675](https://github.com/openai/openai-ruby/issues/675)) ([aeb4cf2](https://github.com/openai/openai-ruby/commit/aeb4cf2120d6eb7f204206dd5364951ad0495103)), closes [#669](https://github.com/openai/openai-ruby/issues/669)
+* coerce Integer strings as decimal ([#667](https://github.com/openai/openai-ruby/issues/667)) ([82f8c62](https://github.com/openai/openai-ruby/commit/82f8c62f0a68236757d57cfe3fd4a501f41270f5))
+* correct Responses stream RBS contract ([#654](https://github.com/openai/openai-ruby/issues/654)) ([0d32ba4](https://github.com/openai/openai-ruby/commit/0d32ba4c555c3ea2763dade0db6618e86de84f96))
+* correct Responses text enumerator Sorbet type ([#637](https://github.com/openai/openai-ruby/issues/637)) ([49ccb69](https://github.com/openai/openai-ruby/commit/49ccb69cbe4fd0a738bbc03840b7bb117bb183f6))
+* declare built-in workload identity providers ([#659](https://github.com/openai/openai-ruby/issues/659)) ([cfbbb98](https://github.com/openai/openai-ruby/commit/cfbbb98f2a87340442c9b8ccd267cd54dbd31fbc))
+* declare Chat stream finish exception types ([#657](https://github.com/openai/openai-ruby/issues/657)) ([87fc522](https://github.com/openai/openai-ruby/commit/87fc522b00f51b1020f64bdcaa4e56573f43ab6a))
+* declare webhook signature error types ([#642](https://github.com/openai/openai-ruby/issues/642)) ([5211472](https://github.com/openai/openai-ruby/commit/52114726f0bd8780f013e95cade266e3f95677c6))
+* declare workload identity error types ([#658](https://github.com/openai/openai-ruby/issues/658)) ([e6afdeb](https://github.com/openai/openai-ruby/commit/e6afdeb10815f3b3cd5a3224abd5d55a3f2b1377))
+* deserialize diarized transcriptions correctly ([#652](https://github.com/openai/openai-ruby/issues/652)) ([5be26ce](https://github.com/openai/openai-ruby/commit/5be26ce71fa5855e668068075215c454ec7eeab8))
+* handle non-object OAuth error bodies ([#674](https://github.com/openai/openai-ruby/issues/674)) ([13aa3d6](https://github.com/openai/openai-ruby/commit/13aa3d65ee84d242407d8ad912b0f26e4c945fe8))
+* handle quoted response charsets ([#613](https://github.com/openai/openai-ruby/issues/613)) ([91d0e86](https://github.com/openai/openai-ruby/commit/91d0e86ed995f54361b329d7641af9f20163f27d)), closes [#610](https://github.com/openai/openai-ruby/issues/610)
+* honor custom idempotency headers for retries ([#673](https://github.com/openai/openai-ruby/issues/673)) ([5bd703a](https://github.com/openai/openai-ruby/commit/5bd703acb8b270d0ae37ea1a846dfada5f88b9fc)), closes [#671](https://github.com/openai/openai-ruby/issues/671)
+* honor raw StringIO request cursors ([#621](https://github.com/openai/openai-ruby/issues/621)) ([8e6abfd](https://github.com/openai/openai-ruby/commit/8e6abfd57a33ae7c7360f496f8baf15e1cf74db4))
+* isolate base URL queries between requests ([#619](https://github.com/openai/openai-ruby/issues/619)) ([347e659](https://github.com/openai/openai-ruby/commit/347e659404bd7a13de57604e325c4432c875ee60))
+* isolate structured output field metadata ([#655](https://github.com/openai/openai-ruby/issues/655)) ([7f3cec8](https://github.com/openai/openai-ruby/commit/7f3cec8663175c9ac1be12368bcf1c3717ca2466))
+* keep Realtime metadata out of nested payloads ([#653](https://github.com/openai/openai-ruby/issues/653)) ([d1fa0d3](https://github.com/openai/openai-ruby/commit/d1fa0d3026a47cd16c4c2dcd8d68e8d1ecb854db))
+* match response charset parameters case-insensitively ([#629](https://github.com/openai/openai-ruby/issues/629)) ([821d9b3](https://github.com/openai/openai-ruby/commit/821d9b3f018040a3a946f714e120f009541c9743))
+* match the multipart request content type case-insensitively ([#666](https://github.com/openai/openai-ruby/issues/666)) ([55ae013](https://github.com/openai/openai-ruby/commit/55ae0137740f05f30173e3dc73d546a500b29d2a))
+* normalize Bedrock environment bearer tokens ([#601](https://github.com/openai/openai-ruby/issues/601)) ([131e977](https://github.com/openai/openai-ruby/commit/131e97745f0cca1b167a533b852141ceed480c96))
+* normalize workload identity error headers ([#640](https://github.com/openai/openai-ruby/issues/640)) ([1cf3762](https://github.com/openai/openai-ruby/commit/1cf37629ab61b2cc9259dff52c143b08ebe6b70a))
+* parse initial streamed tool arguments ([#593](https://github.com/openai/openai-ruby/issues/593)) ([f4e2ec9](https://github.com/openai/openai-ruby/commit/f4e2ec9069d0781e376447f9f840082f00e07b81))
+* parse SSE field lines that carry no value ([#631](https://github.com/openai/openai-ruby/issues/631)) ([9109f3f](https://github.com/openai/openai-ruby/commit/9109f3f79f6db401e400ca8e4cac8586a9332760))
+* parse SSE retry metadata as decimal ([#624](https://github.com/openai/openai-ruby/issues/624)) ([9135d15](https://github.com/openai/openai-ruby/commit/9135d15c272b9e6102f41dc5d0fa64ac1a5fc2ec))
+* parse strict tools in later chat choices ([#633](https://github.com/openai/openai-ruby/issues/633)) ([b68ce90](https://github.com/openai/openai-ruby/commit/b68ce906106cdaa165cbb6ebdd5ec34b2cc7ba2b))
+* populate nested API error metadata ([#639](https://github.com/openai/openai-ruby/issues/639)) ([8dba07c](https://github.com/openai/openai-ruby/commit/8dba07cda53195755ffbf15634c516e51701ba5a))
+* preserve bare CR SSE line boundaries ([#676](https://github.com/openai/openai-ruby/issues/676)) ([98c5a53](https://github.com/openai/openai-ruby/commit/98c5a5333f5d82f25ec12e7b5a9f65ea78716a12)), closes [#670](https://github.com/openai/openai-ruby/issues/670)
+* preserve chat stream moderation results ([#616](https://github.com/openai/openai-ruby/issues/616)) ([c2c729c](https://github.com/openai/openai-ruby/commit/c2c729ce407a526a91d5f1c0607ee190956e414d))
+* preserve complete interleaved tool arguments ([#638](https://github.com/openai/openai-ruby/issues/638)) ([1f32200](https://github.com/openai/openai-ruby/commit/1f322009ccc529d03048fc1d4bee96401c58ee35))
+* preserve documented file inputs on readback ([#662](https://github.com/openai/openai-ruby/issues/662)) ([0169713](https://github.com/openai/openai-ruby/commit/016971345676ade41c57fcee11b60f3adcefe652))
+* preserve file semantics for pathless multipart IO ([#665](https://github.com/openai/openai-ruby/issues/665)) ([0fefbf6](https://github.com/openai/openai-ruby/commit/0fefbf68a804bdd080dfef9defe0ce45e18eaa6b))
+* preserve hash-form type metadata ([#651](https://github.com/openai/openai-ruby/issues/651)) ([8de6a0f](https://github.com/openai/openai-ruby/commit/8de6a0fc26ba8649d6621689ce5c342799c0a786))
+* preserve text logprobs in response streams ([#595](https://github.com/openai/openai-ruby/issues/595)) ([e8e2f39](https://github.com/openai/openai-ruby/commit/e8e2f392f6bd20d8b9ca84d8141b73be0e6b33d9))
+* preserve unknown discriminated union values ([#645](https://github.com/openai/openai-ruby/issues/645)) ([1384aa0](https://github.com/openai/openai-ruby/commit/1384aa017af5fa98a515753e1d4a9ba0bac82d63))
+* preserve UTF-8 SSE stream boundaries ([#623](https://github.com/openai/openai-ruby/issues/623)) ([6b9ee87](https://github.com/openai/openai-ruby/commit/6b9ee8729c3ac429cc93716e8b51bce603de3405))
+* rank tied union variants by declaration order ([#628](https://github.com/openai/openai-ruby/issues/628)) ([5ae6f43](https://github.com/openai/openai-ruby/commit/5ae6f43f4260a1a68984afc649bdc44e68526324))
+* redact malformed streamed JSON errors ([#643](https://github.com/openai/openai-ruby/issues/643)) ([5ab02f6](https://github.com/openai/openai-ruby/commit/5ab02f65fdcecdd007a48e7bde8679ce240c1a1c))
+* respect StringIO cursor in FilePart serialization ([#592](https://github.com/openai/openai-ruby/issues/592)) ([4115a1e](https://github.com/openai/openai-ruby/commit/4115a1e03a3111cbc80be20eb902df81567b3c76))
+* **responses:** expose stream resumption parameters ([#646](https://github.com/openai/openai-ruby/issues/646)) ([d93852f](https://github.com/openai/openai-ruby/commit/d93852f16db7307e3b0da1396b4d06ad4f74cfc2))
+* restore conflict-free exported RBIs for Tapioca ([#679](https://github.com/openai/openai-ruby/issues/679)) ([c80a253](https://github.com/openai/openai-ruby/commit/c80a25396afbf143e68c4b11a8552ebbbb6bfc3b))
+* retry only proven unsent requests ([#663](https://github.com/openai/openai-ruby/issues/663)) ([a63eda8](https://github.com/openai/openai-ruby/commit/a63eda8203aa023ef3a6917c18a2be80cb66e406))
+* stream container file uploads as multipart ([#648](https://github.com/openai/openai-ruby/issues/648)) ([b3c523b](https://github.com/openai/openai-ruby/commit/b3c523b2566a6b760d0a1a952682bf6ca9a866d0))
+* strip upload filenames without platform path rules ([#627](https://github.com/openai/openai-ruby/issues/627)) ([5f00613](https://github.com/openai/openai-ruby/commit/5f006135268ae38b81024f8c28de939c53598c90))
+* suppress Responses WebSocket exception causes ([#644](https://github.com/openai/openai-ruby/issues/644)) ([1b16a83](https://github.com/openai/openai-ruby/commit/1b16a832d74df6742b256545a24915424deaa7dd))
+* type chat completion streams for Sorbet ([#634](https://github.com/openai/openai-ruby/issues/634)) ([cca6a70](https://github.com/openai/openai-ruby/commit/cca6a7035e680fd85ea40bd728937e9c957bd81a))
+* upload pathless IO streams instead of raising ([#630](https://github.com/openai/openai-ruby/issues/630)) ([950552f](https://github.com/openai/openai-ruby/commit/950552f470951ddf01bd1f55a1569b012b6b4fd0))
+
+
+### Chores
+
+* **api:** document throttling and model overload responses — SDK-235 ([#632](https://github.com/openai/openai-ruby/issues/632)) ([2b0483d](https://github.com/openai/openai-ruby/commit/2b0483d394289aa18b792bd7a5440977d8b7a7a1))
+* **api:** Refresh SDK metadata ([#612](https://github.com/openai/openai-ruby/issues/612)) ([e93a4b5](https://github.com/openai/openai-ruby/commit/e93a4b54f9b64609b96c553ac7864d94dacc6cf1))
+* **deps-dev:** bump the development-dependencies group with 7 updates ([#668](https://github.com/openai/openai-ruby/issues/668)) ([d9a2271](https://github.com/openai/openai-ruby/commit/d9a2271531acea12bc3b46293bb90159d3975d59))
+* migrate to forked steady ([#605](https://github.com/openai/openai-ruby/issues/605)) ([5542f01](https://github.com/openai/openai-ruby/commit/5542f01a8395bc9349eae479396ba5158692385f))
+
+
+### Documentation
+
+* clarify dormant compatibility-check boundary ([#647](https://github.com/openai/openai-ruby/issues/647)) ([d6fa81c](https://github.com/openai/openai-ruby/commit/d6fa81ca012db991be4438f6f1b605a0ce12aa8e))
+* clarify Realtime transcription event boundary ([#649](https://github.com/openai/openai-ruby/issues/649)) ([94a1d77](https://github.com/openai/openai-ruby/commit/94a1d77a23c990308d6262f3ce668af6206361f4))
+
 ## [0.85.0](https://github.com/openai/openai-ruby/compare/v0.84.0...v0.85.0) (2026-09-03)
 
 

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.85.0"
+gem "openai", "~> 0.86.0"
 ```
 
 <!-- x-release-please-end -->
@@ -81,6 +81,37 @@ sideband connection. See the [Realtime WebSocket guide](realtime.md) and the run
 [text, transcription, voice, and sideband examples](examples/realtime/README.md)
 for lifecycle, authentication, proxy, TLS, and custom transport details.
 
+### Responses WebSockets
+
+The Responses API also supports a persistent, block-scoped WebSocket for
+sequential and multiplexed response creation. Add the optional
+`async-websocket` gem, then send `response.create` events through
+`client.responses.connect`:
+
+```ruby
+client.responses.connect do |connection|
+  connection.response.create(
+    model: "gpt-5.2",
+    input: "Say hello.",
+    stream_id: "turn_1"
+  )
+
+  connection.each do |event|
+    print(event.delta) if event.type == :"response.output_text.delta"
+    break if event.type == :"response.completed"
+  end
+end
+```
+
+The connection is intentionally single-owner: callers serialize writes and
+use one reader (`receive` or `each`). The SDK forwards response fields and
+`stream_id` values without imposing additional client-side policy. Known
+server events are decoded into generated models on a best-effort basis, while
+newer event types remain observable as `UnknownServerEvent` values. The SDK
+does not automatically reconnect or replay an ambiguous write. When the server
+closes a connection, open a new connection and continue with
+`previous_response_id` when the response was stored.
+
 ### Pagination
 
 List methods in the OpenAI API are paginated.
@@ -213,7 +244,11 @@ The custom HTTP client owns connection pooling and lifecycle, must enforce
 `request.timeout`, and should raise `OpenAI::Errors::APIConnectionError` or
 `OpenAI::Errors::APITimeoutError` for retryable transport failures. Other
 exceptions propagate without an SDK retry. The SDK does not close an injected
-HTTP client.
+HTTP client. Connection failures are treated as potentially post-send by
+default, so non-idempotent requests are not retried automatically. When a
+transport can prove that no request bytes were sent, it may raise either error
+with `request_may_have_been_sent: false` to allow the SDK retry policy to
+retry a replayable request safely.
 
 The default `OpenAI::NetHTTPClient` implements this contract with pooled
 `Net::HTTP` connections. It accepts an optional block for native connection
@@ -395,6 +430,10 @@ For secure, automated environments like cloud-managed Kubernetes, Azure, and GCP
 
 `client_id` remains available as an optional parameter for token exchange setups that require an explicit OAuth client ID.
 
+If `OPENAI_API_KEY` is already set in your environment, pass `api_key: nil`
+to explicitly opt out of that ambient API key when constructing a workload
+identity client.
+
 ### X.509 Workload Identity (Preview)
 
 Organizations enrolled in the X.509 workload identity preview can exchange a
@@ -503,6 +542,7 @@ workload_identity = OpenAI::Auth::WorkloadIdentity.new(
 )
 
 client = OpenAI::Client.new(
+  api_key: nil,
   workload_identity: workload_identity,
 )
 
@@ -524,6 +564,7 @@ workload_identity = OpenAI::Auth::WorkloadIdentity.new(
 )
 
 client = OpenAI::Client.new(
+  api_key: nil,
   workload_identity: workload_identity,
 )
 ```
@@ -540,6 +581,7 @@ workload_identity = OpenAI::Auth::WorkloadIdentity.new(
 )
 
 client = OpenAI::Client.new(
+  api_key: nil,
   workload_identity: workload_identity,
 )
 ```
@@ -570,6 +612,7 @@ workload_identity = OpenAI::Auth::WorkloadIdentity.new(
 )
 
 client = OpenAI::Client.new(
+  api_key: nil,
   workload_identity: workload_identity,
   organization: ENV["OPENAI_ORG_ID"],
   project: ENV["OPENAI_PROJECT_ID"]
@@ -605,9 +648,9 @@ post '/webhook' do
     event = client.webhooks.unwrap(request_body, request.env)
     
     case event.type
-    when 'response.completed'
+    when :'response.completed'
       puts "Response completed: #{event.data}"
-    when 'response.failed'
+    when :'response.failed'
       puts "Response failed: #{event.data}"
     else
       puts "Unhandled event type: #{event.type}"
@@ -711,6 +754,27 @@ response
   end
 ```
 
+For a stored or background response, pass the same structured-output model again
+when retrieving it. The model is used locally to populate `content.parsed`; it is
+not sent as a retrieval query parameter. A response that is still queued or in
+progress can be retrieved the same way, but structured output is parsed only after
+a later retrieval reports it completed when status is present. Compatible
+statusless responses parse once their hinted output is syntactically complete JSON.
+For structured function tools, pass the same model again with
+`tools: [ToolArguments]`; matching retrieved function calls expose typed arguments
+through `output.parsed`.
+
+```ruby
+pending = client.responses.create(
+  model: "gpt-5.2",
+  input: "Extract the event information.",
+  text: CalendarEvent,
+  background: true
+)
+
+response = client.responses.retrieve(pending.id, text: CalendarEvent)
+```
+
 </details>
 
 See the [examples](https://github.com/openai/openai-ruby/tree/main/examples) directory for more usage examples for helper usage.
@@ -915,8 +979,9 @@ a supplied logger are isolated and never replace an API result or API error.
 ### Response metadata and request IDs
 
 OpenAI recommends logging request IDs in production so requests can be traced
-during troubleshooting. Top-level models and pages returned by the client expose
-immutable HTTP response metadata through `last_response`:
+during troubleshooting. Top-level models, pages, streams, and binary StringIO
+values returned by the client expose immutable HTTP response metadata through
+`last_response`:
 
 ```ruby
 response = openai.responses.create(model: "gpt-5.2", input: "Say 'this is a test'.")
@@ -924,6 +989,10 @@ puts(response.last_response.status)                 # 200
 puts(response.last_response.headers["x-request-id"]) # req_123
 puts(response.last_response.request_id)             # req_123
 puts(response._request_id)                           # req_123
+
+audio = openai.audio.speech.create(input: "Hello!", model: "tts-1", voice: "alloy")
+puts(audio.last_response.headers["x-request-id"])    # req_456
+puts(audio._request_id)                               # req_456
 ```
 
 Header names and values are normalized to strings, header names are lowercase,
@@ -932,11 +1001,12 @@ HTTP response that opened the stream. Higher-level streaming helpers expose the
 same metadata as their underlying stream; models assembled from stream events
 do not.
 
-`last_response` and `_request_id` are only populated on top-level typed models
-and pages returned by the client. They are `nil` on constructed or nested models
-and are not included in `to_h`, JSON, or YAML output. Endpoints returning raw
-primitives, binary data, or `nil` do not expose this metadata. Unlike other
-properties that begin with an underscore, `_request_id` is public.
+`last_response` and `_request_id` are only populated on top-level models,
+pages, streams, and direct binary `StringIO` responses returned by the client.
+They are `nil` on constructed or nested models, unavailable on primitive or
+union-backed plain-text fallbacks, and are not included in `to_h`, JSON, or
+YAML output. Endpoints returning `nil` have no object that can carry metadata.
+Unlike other properties that begin with an underscore, `_request_id` is public.
 
 For failed HTTP requests, catch `OpenAI::Errors::APIStatusError` and use
 `request_id`:
@@ -957,7 +1027,15 @@ for more information.
 
 Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
 
-Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
+Requests are automatically retried only when their bodies are replayable. For
+those requests, after transport execution begins, connection errors (for
+example, due to a network connectivity problem) and timeouts are retried by
+default only when the transport proves that no request bytes were sent, for
+idempotent HTTP methods, or for requests carrying a non-empty
+`Idempotency-Key` header. Failures before transport execution retain the
+configured retry behavior because no request has been dispatched.
+408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors
+are retried by default regardless of the HTTP method.
 
 You can use the `max_retries` option to configure or disable this:
 
@@ -1016,7 +1094,11 @@ openai.chat.completions.create(
 
 On timeout, `OpenAI::Errors::APITimeoutError` is raised.
 
-Note that requests that time out are retried by default.
+After transport execution begins, requests with replayable bodies that time out
+are retried by default only when the transport proves that no request bytes
+were sent, for idempotent HTTP methods, or for requests carrying a non-empty
+`Idempotency-Key` header. Timeouts before transport execution retain the
+configured retry behavior.
 
 ## Advanced concepts
 

data/docs/architecture/security-model.md

@@ -126,8 +126,21 @@ Important boundaries:
 - Authenticated Realtime handshakes are a transport boundary distinct from
   event parsing. Bearer credentials, caller-selected WebSocket destinations,
   TLS, proxy credentials, and traces must remain bound to their intended
-  origin and diagnostic audience
-  (`lib/openai/helpers/realtime/client_extension.rb:167-280`,
+  origin and diagnostic audience. Bearer credentials, including ephemeral
+  client secrets passed to client apps, authenticate the handshake before any
+  typed event is sent; post-handshake transcription `session.update` events
+  carry configuration rather than a client secret. The legacy generated
+  `TranscriptionSessionUpdatedEvent` model requires a `client_secret` even
+  though its own documentation says WebSocket updates omit it, but that model
+  is not in the helper's active server-event union: the parser treats its
+  `transcription_session.updated` discriminator as unknown, while current
+  transcription updates use `session.updated`
+  (`lib/openai/helpers/websocket/client_request.rb:89-113`,
+  `lib/openai/helpers/realtime/connection_resources.rb:25-31`,
+  `lib/openai/resources/realtime/client_secrets.rb:10-45`,
+  `lib/openai/models/realtime/transcription_session_updated_event.rb:13-49`,
+  `lib/openai/models/realtime/realtime_server_event.rb:192-199`,
+  `lib/openai/helpers/realtime/connection.rb:32-49`,
   `lib/openai/helpers/realtime/transports/async_websocket.rb:185-224`,
   `lib/openai/helpers/realtime/transports/async_websocket.rb:294-378`).
 - Multipart upload serialization is a file-path and header-integrity boundary.
@@ -206,6 +219,19 @@ PR CI. A contributor who can modify those tracked files does not gain a new
 privilege merely because CI executes them. Do not report that execution alone
 as a security finding.
 
+Dormant developer helpers are not security controls merely because their names
+suggest compatibility or safety verification. At this revision,
+`scripts/detect-breaking-changes` is not invoked by any tracked workflow or
+tracked required job; when a contributor explicitly runs it, it replaces
+selected tests with historical versions and invokes lint rather than runtime
+assertions.
+That can affect contributor confidence or release-quality review, but without a
+privileged workflow invocation or an independent lower-trust path to a sensitive
+sink, it is not a repository security boundary. Reassess this classification if
+the helper becomes a required or privileged workflow control; otherwise treat
+ordinary compatibility regressions as product/release-quality issues unless they
+independently violate a runtime security invariant.
+
 That rule does not suppress a real finding when independently mutable
 lower-trust input crosses a parser/evaluator boundary, untrusted runtime/API/
 network data reaches a sensitive sink, candidate code can reach sensitive

data/lib/openai/auth/workload_identity_auth.rb

@@ -355,7 +355,7 @@ module OpenAI
             OpenAI::Errors::OAuthError.new(
               status: response.code.to_i,
               body: body,
-              headers: response.to_hash
+              headers: response.each_header.to_h
             )
           )
         in Net::HTTPSuccess
@@ -368,7 +368,7 @@ module OpenAI
             OpenAI::Errors::APIError.new(
               url: @token_exchange_url,
               status: response.code.to_i,
-              headers: response.to_hash,
+              headers: response.each_header.to_h,
               body: body,
               message: "Token exchange failed with status #{response.code}"
             )

data/lib/openai/auth/x509_token_exchange.rb

@@ -74,7 +74,13 @@ module OpenAI
 
         raise_error(response, body)
       rescue OpenAI::Errors::APIConnectionError => error
-        raise error.class.new(url: URI(TOKEN_URL)), cause: nil
+        raise(
+          error.class.new(
+            url: URI(TOKEN_URL),
+            request_may_have_been_sent: error.request_may_have_been_sent?
+          ),
+          cause: nil
+        )
       end
 
       private def remaining_timeout(deadline)

data/lib/openai/auth/x509_transport.rb

@@ -116,21 +116,39 @@ module OpenAI
           native_response
 
         rescue OpenAI::Errors::APIConnectionError => error
-          raise error.class.new(url: sanitized_url(url)), cause: nil
+          raise(
+            error.class.new(
+              url: sanitized_url(url),
+              request_may_have_been_sent: error.request_may_have_been_sent?
+            ),
+            cause: nil
+          )
         end
 
         stream = Enumerator.new do |chunks|
           response.body.each { |chunk| chunks << chunk }
 
         rescue OpenAI::Errors::APIConnectionError => error
-          raise error.class.new(url: sanitized_url(url)), cause: nil
+          raise(
+            error.class.new(
+              url: sanitized_url(url),
+              request_may_have_been_sent: error.request_may_have_been_sent?
+            ),
+            cause: nil
+          )
         end
 
         body = OpenAI::Internal::Util.fused_enum(stream) do
           OpenAI::Internal::Util.close_fused!(response.body)
 
         rescue OpenAI::Errors::APIConnectionError => error
-          raise error.class.new(url: sanitized_url(url)), cause: nil
+          raise(
+            error.class.new(
+              url: sanitized_url(url),
+              request_may_have_been_sent: error.request_may_have_been_sent?
+            ),
+            cause: nil
+          )
         end
 
         OpenAI::HTTPClient::Response.new(status: response.status, headers: response.headers, body: body)

data/lib/openai/client.rb

@@ -399,14 +399,16 @@ module OpenAI
       rescue OpenAI::Errors::APIError => error
         status = error.status
         connection_failure = error.is_a?(OpenAI::Errors::APIConnectionError)
-        retryable_status = connection_failure ||
+        retryable_connection_failure = connection_failure &&
+          false.equal?(error.request_may_have_been_sent?)
+        retryable_status = retryable_connection_failure ||
           [408, 409, 429].include?(status) ||
           (status.is_a?(Integer) && (500..599).cover?(status))
         consumed_retries = attempts + previous_issuer_retries + retry_count
         unless x509_transport?(@requester) &&
             retryable_status &&
             consumed_retries < request.fetch(:x509_request_context).fetch(:auth_max_retries) &&
-            (connection_failure || self.class.should_retry?(status, headers: error.headers || {}))
+            (retryable_connection_failure || self.class.should_retry?(status, headers: error.headers || {}))
           raise
         end
 

data/lib/openai/errors.rb

@@ -141,6 +141,15 @@ module OpenAI
       #
       #   @return [nil]
 
+      # Whether request bytes might have reached the peer before the transport
+      # failed. HTTP clients should only set this to `false` when they can
+      # prove that no request bytes were sent.
+      #
+      # @api private
+      #
+      # @return [Boolean]
+      def request_may_have_been_sent? = @request_may_have_been_sent
+
       # @api private
       #
       # @param url [URI::Generic]
@@ -150,6 +159,7 @@ module OpenAI
       # @param request [nil]
       # @param response [nil]
       # @param message [String, nil]
+      # @param request_may_have_been_sent [Boolean]
       def initialize(
         url:,
         status: nil,
@@ -157,9 +167,11 @@ module OpenAI
         body: nil,
         request: nil,
         response: nil,
-        message: "Connection error."
+        message: "Connection error.",
+        request_may_have_been_sent: true
       )
-        super
+        @request_may_have_been_sent = request_may_have_been_sent
+        super(url:, status:, headers:, body:, request:, response:, message:)
       end
     end
 
@@ -173,6 +185,7 @@ module OpenAI
       # @param request [nil]
       # @param response [nil]
       # @param message [String, nil]
+      # @param request_may_have_been_sent [Boolean]
       def initialize(
         url:,
         status: nil,
@@ -180,7 +193,8 @@ module OpenAI
         body: nil,
         request: nil,
         response: nil,
-        message: "Request timed out."
+        message: "Request timed out.",
+        request_may_have_been_sent: true
       )
         super
       end
@@ -264,9 +278,9 @@ module OpenAI
           safe_status_message(url: url, status: status, body: body)
         end
 
-        @code = OpenAI::Internal::Type::Converter.coerce(String, OpenAI::Internal::Util.dig(body, :code))
-        @param = OpenAI::Internal::Type::Converter.coerce(String, OpenAI::Internal::Util.dig(body, :param))
-        @type = OpenAI::Internal::Type::Converter.coerce(String, OpenAI::Internal::Util.dig(body, :type))
+        @code = OpenAI::Internal::Type::Converter.coerce(String, error_metadata(body, :code))
+        @param = OpenAI::Internal::Type::Converter.coerce(String, error_metadata(body, :param))
+        @type = OpenAI::Internal::Type::Converter.coerce(String, error_metadata(body, :type))
         super(
           url: url,
           status: status,
@@ -278,6 +292,10 @@ module OpenAI
         )
       end
 
+      private def error_metadata(body, key)
+        OpenAI::Internal::Util.dig(body, key) { OpenAI::Internal::Util.dig(body, [:error, key]) }
+      end
+
       private def safe_status_message(url:, status:, body:)
         sensitive_description = %r{
           https?:// |
@@ -536,10 +554,11 @@ module OpenAI
       attr_reader :error_code
 
       def initialize(status:, body:, headers:)
-        @error_code = OpenAI::Internal::Type::Converter.coerce(OpenAI::Models::OAuthErrorCode, body&.dig(:error))
+        error = OpenAI::Internal::Util.dig(body, :error)
+        @error_code = OpenAI::Internal::Type::Converter.coerce(OpenAI::Models::OAuthErrorCode, error)
 
-        message = if body&.dig(:error_description)
-          body[:error_description]
+        message = if (error_description = OpenAI::Internal::Util.dig(body, :error_description))
+          error_description
         elsif @error_code
           @error_code
         else

data/lib/openai/file_part.rb

@@ -30,6 +30,14 @@ module OpenAI
     }nx
     private_constant :MEDIA_TYPE
 
+    # Directory separators recognized on any host, so an upload name is stripped
+    # the same way everywhere.
+    #
+    # @api private
+    # @type [Regexp]
+    SEPARATORS = %r{[/\\]}
+    private_constant :SEPARATORS
+
     # Validate an effective media type before it is written to multipart headers.
     #
     # @api private
@@ -85,7 +93,7 @@ module OpenAI
       in Pathname
         content.read(binmode: true)
       in StringIO
-        content.string
+        content.string.byteslice(content.pos..) || ""
       in IO
         content.read
       in String
@@ -112,7 +120,7 @@ module OpenAI
       @content_type = content_type
       @filename = case [filename, (@content = content)]
       in [String | Pathname, _]
-        ::File.basename(filename)
+        strip_directories(filename)
       in [nil, Pathname]
         content.basename.to_path
       in [nil, IO]
@@ -121,5 +129,30 @@ module OpenAI
         filename
       end
     end
+
+    # Strip directory components from a caller-supplied upload name.
+    #
+    # `::File.basename` applies the host platform's path rules, so on Windows it
+    # also truncates at a drive separator: the remote name `"report: final.md"`
+    # becomes `"report"`. This name is sent to the API rather than resolved
+    # locally, so drop separators directly and keep every other character, no
+    # matter which platform the SDK runs on.
+    #
+    # @api private
+    #
+    # @param filename [Pathname, String]
+    #
+    # @return [String]
+    private def strip_directories(filename)
+      name = filename.to_s
+      binary_name = name.b
+      raise ArgumentError, "path name contains null byte" if binary_name.include?("\0")
+
+      searchable_name = name.scrub { |bytes| "?" * bytes.bytesize }
+      basename = searchable_name.split(SEPARATORS).last
+      return name.byteslice(0, name.empty? ? 0 : 1) if basename.nil?
+
+      name.byteslice(searchable_name.byterindex(basename), basename.bytesize)
+    end
   end
 end