openai 0.84.0 → 0.86.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03f5297b1df9de7c2e182a5f76a72a5a15f2e9a34468b554eb92eb7e8022182b
-  data.tar.gz: 414ac43f94cee9591533b94c02d1d904cdd6a6ba0beb8694e88745b1b30dfad6
+  metadata.gz: 0e2fc3cef6cd029385cb528885096cbf0640df90c238752af2ef76186c578578
+  data.tar.gz: 5ab2eac3ec679b9d43a141ec43ef70b294ed09a5e4f72f9a3c272cd407cbe3dc
 SHA512:
-  metadata.gz: a2dda8c58eb47a26113b553b1428d23502d0c6740808954b740c0a5cf5dac361a798f6a14f963cff9d1230256cd800295017dc07489f7c6798f50a59c4066b1c
-  data.tar.gz: 72d931bd9cc9fa963b2f9d0d6f6e66078eb778456097d041850013b814ec20c3b5c9661a4b68c9fa2ea56a829aaaccc657e544a8cb68863f6c9ae4dd653aeb01
+  metadata.gz: e80dd1fe954a867a454f08d6349689d71f731f1908add8fc5d48e25605a431202cd6f9366e0c30070ae5273195b37116e33a606f6a26de89957d23bea6dd855b
+  data.tar.gz: b87d683d9a0cbc8b59fcb6ddc31b9b1a1737455d7353bf7466736a375955018946f18ba753c79362f94fec9ef9b52f70dd90405cfd94d600e407aaf0b4d64ad5

data/CHANGELOG.md

@@ -1,5 +1,115 @@
 # 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)
+
+
+### Features
+
+* **api:** add gpt-6-astra and related features ([#596](https://github.com/openai/openai-ruby/issues/596)) ([a08d882](https://github.com/openai/openai-ruby/commit/a08d882c2575e0743a18eb5a4eae7ef3f94b0314))
+
+
+### Bug Fixes
+
+* **ci:** restore Castiron statuses for fork PRs ([#572](https://github.com/openai/openai-ruby/issues/572)) ([b78af5a](https://github.com/openai/openai-ruby/commit/b78af5acf775627c8eddf42da41bef7ea7325235))
+* correct StringIO request content length ([#583](https://github.com/openai/openai-ruby/issues/583)) ([5baeac8](https://github.com/openai/openai-ruby/commit/5baeac8131511141491fc41abdb2e4e4c596f3de))
+* emit done events for terminal chat tool calls ([#573](https://github.com/openai/openai-ruby/issues/573)) ([891936c](https://github.com/openai/openai-ruby/commit/891936ce58db613a61d270792f40da400ea44b97))
+* handle nullable structured-output literals ([#568](https://github.com/openai/openai-ruby/issues/568)) ([c4fee85](https://github.com/openai/openai-ruby/commit/c4fee85338aa283d6cec80538e4524a406fa8b7d))
+* isolate chat stream logprob chunks ([#585](https://github.com/openai/openai-ruby/issues/585)) ([0daedb2](https://github.com/openai/openai-ruby/commit/0daedb2878373da899dac8b029fdb0523a26c6ef))
+* preserve initial chat stream system fingerprint ([#580](https://github.com/openai/openai-ruby/issues/580)) ([a31c1ce](https://github.com/openai/openai-ruby/commit/a31c1cef9ee8e1fc5ed7a9b29f23171260a101e4))
+* preserve late chat completion service tier ([#567](https://github.com/openai/openai-ruby/issues/567)) ([52a0c64](https://github.com/openai/openai-ruby/commit/52a0c64fbb04535d4c1250986a5116298048764e))
+* preserve nested array schema definitions ([#581](https://github.com/openai/openai-ruby/issues/581)) ([bbfbe29](https://github.com/openai/openai-ruby/commit/bbfbe29f53018b4a3a1c61edab355ad901bb0239))
+* preserve recursive structured output refs ([#584](https://github.com/openai/openai-ruby/issues/584)) ([b23fc75](https://github.com/openai/openai-ruby/commit/b23fc752952314de279a32175d98b7ca7fd33f8c))
+* preserve retained Responses stream events ([#577](https://github.com/openai/openai-ruby/issues/577)) ([149e685](https://github.com/openai/openai-ruby/commit/149e685c64f72052d19d9389ba07d40a14c4c070))
+* preserve string-tagged structured output models ([#582](https://github.com/openai/openai-ruby/issues/582)) ([983eaf9](https://github.com/openai/openai-ruby/commit/983eaf9c240f6888d2872abddd555fa3cdd5af95))
+* raise finish errors for initial chat stream chunks ([#579](https://github.com/openai/openai-ruby/issues/579)) ([c923659](https://github.com/openai/openai-ruby/commit/c923659aeddd2ed5e928830babd2f75ea6cbae3d))
+* short-circuit Bedrock profile credentials ([#588](https://github.com/openai/openai-ruby/issues/588)) ([1c7ed46](https://github.com/openai/openai-ruby/commit/1c7ed46782288a882aed9ccedcf69ecc53fd9c6d))
+
+
+### Documentation
+
+* clarify commit prefix user impact ([#575](https://github.com/openai/openai-ruby/issues/575)) ([73752ad](https://github.com/openai/openai-ruby/commit/73752ad281e7d3fde9c4b63bd1efa17b151ff5a6))
+* establish canonical security model ([#565](https://github.com/openai/openai-ruby/issues/565)) ([2ded215](https://github.com/openai/openai-ruby/commit/2ded21565f969d026c93027d1d7264a8081d6242))
+
 ## [0.84.0](https://github.com/openai/openai-ruby/compare/v0.83.0...v0.84.0) (2026-09-02)
 
 

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.84.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/SECURITY.md

@@ -1,5 +1,15 @@
 # Security Policy
 
+## Threat model authority
+
+This file governs vulnerability disclosure and reportability. The repository's
+canonical detailed threat model, trust boundaries, security invariants, and
+severity calibration are defined in
+[docs/architecture/security-model.md](docs/architecture/security-model.md).
+Codex Security scans and reviewers should use that document from the scanned
+revision rather than maintaining a second pasted threat model here or in scan
+configuration.
+
 ## Reporting a vulnerability
 
 Please report potential security vulnerabilities through OpenAI's