feat: add HTTP response observability

[jbeckwith-oai]

Summary

• expose immutable response status, normalized headers, and request IDs through last_response on top-level models, pages, raw streams, and streaming helpers
• add client-scoped request diagnostics with standard Ruby logger compatibility, OPENAI_LOG, credential redaction, bounded body logging, retry timing, and stream-safe lifecycle logging
• add immutable structured OpenAI::RetryEvent callbacks for observing retries before their delay

API

client = OpenAI::Client.new(
  api_key: ENV.fetch("OPENAI_API_KEY"),
  logger: Rails.logger,
  log_level: :info,
  on_retry: ->(event) { Rails.logger.warn("retry #{event.attempt}/#{event.max_attempts}") }
)

response = client.responses.create(model: "gpt-5.2", input: "hello")
response.last_response.status
response.last_response.request_id
response.last_response.headers

Observability configuration belongs to OpenAI::Client, so it behaves consistently with both the default and custom HTTP transports. This deliberately does not add a raw-response wrapper or generated per-resource methods. Response metadata, retries, logging, transports, and stream attachment remain Ruby overlay concerns.

The narrow generated OpenAI::Client constructor counterpart is open in https://github.com/openai/openai/pull/1277393.

The independently generated timeout: nil fix remains in #363. It merges cleanly with this branch, and the composed tree passes the complete Ruby test and lint suites.

Closes #242.
Closes #306.

Consolidates and supersedes the implementation work from #262 and #359. The response metadata work originated with @ktamulonis.

Validation

• Ruby 3.3.12 and 4.0.6: 606 tests and 2,269 assertions per version, no failures
• composed with fix(api): allow nil timeout in client signatures #363: 609 tests and 2,284 assertions, no failures
• full repository lint/type validation: 2,605 RuboCop files and 1,212 RBS files, Sorbet clean
• built gem and isolated installed-artifact load probe
• thermo-nuclear maintainability review

[openai-sdks]

OkTest Summary

✅ 237/237 SDK tests passed in 9.276s for Ruby SDK PR #365.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	183ms
tests/chat-completions-create.test.ts	✅ Passed	201ms
tests/chat-completions-stream.test.ts	✅ Passed	144ms
tests/files-content-binary.test.ts	✅ Passed	258ms
tests/files-create-multipart.test.ts	✅ Passed	303ms
tests/files-list-pagination.test.ts	✅ Passed	308ms
tests/initialize-config.test.ts	✅ Passed	197ms
tests/instance-isolation.test.ts	✅ Passed	214ms
tests/models-list.test.ts	✅ Passed	258ms
tests/responses-background-lifecycle.test.ts	✅ Passed	208ms
tests/responses-body-method-errors.test.ts	✅ Passed	562ms
tests/responses-cancel-timeout.test.ts	✅ Passed	319ms
tests/responses-cancel.test.ts	✅ Passed	256ms
tests/responses-compact-retries.test.ts	✅ Passed	301ms
tests/responses-compact.test.ts	✅ Passed	226ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	180ms
tests/responses-create-advanced.test.ts	✅ Passed	181ms
tests/responses-create-disconnect.test.ts	✅ Passed	150ms
tests/responses-create-errors.test.ts	✅ Passed	334ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	192ms
tests/responses-create-retries.test.ts	✅ Passed	269ms
tests/responses-create-stream-failures.test.ts	✅ Passed	148ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	224ms
tests/responses-create-stream-wire.test.ts	✅ Passed	1.906s
tests/responses-create-stream.test.ts	✅ Passed	188ms
tests/responses-create-terminal-states.test.ts	✅ Passed	332ms
tests/responses-create-timeout.test.ts	✅ Passed	325ms
tests/responses-create.test.ts	✅ Passed	373ms
tests/responses-delete.test.ts	✅ Passed	297ms
tests/responses-input-items-errors.test.ts	✅ Passed	179ms
tests/responses-input-items-list.test.ts	✅ Passed	165ms
tests/responses-input-items-options.test.ts	✅ Passed	230ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	235ms
tests/responses-input-tokens-count.test.ts	✅ Passed	330ms
tests/responses-malformed-inputs.test.ts	✅ Passed	2.143s
tests/responses-not-found-errors.test.ts	✅ Passed	321ms
tests/responses-parse.test.ts	✅ Passed	174ms
tests/responses-retrieve-retries.test.ts	✅ Passed	287ms
tests/responses-retrieve.test.ts	✅ Passed	234ms
tests/responses-stored-method-errors.test.ts	✅ Passed	789ms
tests/retry-behavior.test.ts	✅ Passed	1.911s
tests/sdk-error-shape.test.ts	✅ Passed	541ms

View OkTest run #31542371789

_{SDK merge (8a30cfe516b5) · head (38ee0dd714fd) · base (e52ca61a116f) · OkTest (91635c6a2723)}

[HAYDEN-OAI]

Reviewed the response-metadata propagation, client-scoped logging/retry API, redaction paths, stream lifecycle behavior, and typing surfaces at the current head. The prior redaction/stream concerns are addressed and I found no substantive issues.