Skip to content

docs(realtime): add standard WebSocket workflows - #500

Open
jbeckwith-oai wants to merge 4 commits into
mainfrom
codex/realtime-standard-workflows
Open

docs(realtime): add standard WebSocket workflows#500
jbeckwith-oai wants to merge 4 commits into
mainfrom
codex/realtime-standard-workflows

Conversation

@jbeckwith-oai

Copy link
Copy Markdown
Contributor

Summary

  • add runnable Realtime WebSocket examples for deterministic local function calling, validated PNG/JPEG input, and MCP approval
  • keep each workflow on the existing generic client.realtime.connect helpers, including generic function_call_output and mcp_approval_response conversation items
  • add explicit lifecycle/correlation checks, bounded executable deadlines, metadata-only diagnostics, focused failure-path tests, documentation, E2E inventory, and gem packaging coverage

Validation

  • focused Realtime example tests: 26 runs, 164 assertions, 0 failures
  • gem packaging test: 1 run, 20 assertions, 0 failures
  • example E2E inventory: passed (24 covered / 33 total; 9 explicit exclusions)
  • bundle exec rake lint: passed
  • bundle exec rake typecheck: passed
  • full bundle exec rake test with the required Steady mock: 1,111 / 1,112 tests passed; the existing RealtimeNetworkInvariantsTest#test_http_proxy_uses_connect_and_isolates_proxy_and_origin_credentials races its localhost accept thread against teardown in this environment and also fails in isolation

Review notes

  • no production runtime, generated model/resource, RBI, or RBS changes
  • no new convenience API; examples use conversation.items.create
  • MCP server URL is caller-supplied and no public endpoint is embedded
  • requesting @openai/sdks-team review because this documents file-path/image and remote MCP endpoint boundaries

@jbeckwith-oai
jbeckwith-oai requested a review from a team as a code owner August 20, 2026 23:35
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Aug 20, 2026

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review Completed 2026-08-21T05:15:26.906449Z 787b12a New commits
🔒 Security Review Completed 2026-08-21T05:13:25.074139Z 787b12a New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@openai-sdks

openai-sdks Bot commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

OkTest Summary

237/237 SDK tests passed in 10.062s for Ruby SDK PR #500.

Test results — 42 files
Test Result Time
tests/chat-completions-complex-body.test.ts ✅ Passed 179ms
tests/chat-completions-create.test.ts ✅ Passed 230ms
tests/chat-completions-stream.test.ts ✅ Passed 138ms
tests/files-content-binary.test.ts ✅ Passed 145ms
tests/files-create-multipart.test.ts ✅ Passed 139ms
tests/files-list-pagination.test.ts ✅ Passed 158ms
tests/initialize-config.test.ts ✅ Passed 181ms
tests/instance-isolation.test.ts ✅ Passed 280ms
tests/models-list.test.ts ✅ Passed 208ms
tests/responses-background-lifecycle.test.ts ✅ Passed 297ms
tests/responses-body-method-errors.test.ts ✅ Passed 485ms
tests/responses-cancel-timeout.test.ts ✅ Passed 212ms
tests/responses-cancel.test.ts ✅ Passed 315ms
tests/responses-compact-retries.test.ts ✅ Passed 253ms
tests/responses-compact.test.ts ✅ Passed 268ms
tests/responses-create-advanced-stream.test.ts ✅ Passed 147ms
tests/responses-create-advanced.test.ts ✅ Passed 220ms
tests/responses-create-disconnect.test.ts ✅ Passed 997ms
tests/responses-create-errors.test.ts ✅ Passed 262ms
tests/responses-create-malformed-api-responses.test.ts ✅ Passed 188ms
tests/responses-create-retries.test.ts ✅ Passed 321ms
tests/responses-create-stream-failures.test.ts ✅ Passed 153ms
tests/responses-create-stream-timeout.test.ts ✅ Passed 217ms
tests/responses-create-stream-wire.test.ts ✅ Passed 2.453s
tests/responses-create-stream.test.ts ✅ Passed 103ms
tests/responses-create-terminal-states.test.ts ✅ Passed 327ms
tests/responses-create-timeout.test.ts ✅ Passed 209ms
tests/responses-create.test.ts ✅ Passed 312ms
tests/responses-delete.test.ts ✅ Passed 253ms
tests/responses-input-items-errors.test.ts ✅ Passed 189ms
tests/responses-input-items-list.test.ts ✅ Passed 191ms
tests/responses-input-items-options.test.ts ✅ Passed 211ms
tests/responses-input-tokens-count-timeout.test.ts ✅ Passed 318ms
tests/responses-input-tokens-count.test.ts ✅ Passed 231ms
tests/responses-malformed-inputs.test.ts ✅ Passed 2.112s
tests/responses-not-found-errors.test.ts ✅ Passed 367ms
tests/responses-parse.test.ts ✅ Passed 213ms
tests/responses-retrieve-retries.test.ts ✅ Passed 277ms
tests/responses-retrieve.test.ts ✅ Passed 256ms
tests/responses-stored-method-errors.test.ts ✅ Passed 702ms
tests/retry-behavior.test.ts ✅ Passed 3.162s
tests/sdk-error-shape.test.ts ✅ Passed 368ms

View OkTest run #32449621071

SDK merge (2245f2cd7d03) · head (787b12a037a7) · base (7ab65d8b6583) · OkTest (2b1bdfd25e98)

@github-actions

github-actions Bot commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

Castiron custom code

✅ No new custom-code files detected.

50 mixed files remain; 0 existing customizations changed.

Compared 7ab65d8b6583787b12a037a7. Generated baselines verified.

50 existing customizations unchanged
  • lib/openai.rb
  • lib/openai/client.rb
  • lib/openai/models/chat/chat_completion_message.rb
  • lib/openai/models/chat/chat_completion_message_function_tool_call.rb
  • lib/openai/models/chat/completion_create_params.rb
  • lib/openai/models/response_format_json_schema.rb
  • lib/openai/models/responses/function_tool.rb
  • lib/openai/models/responses/response.rb
  • lib/openai/models/responses/response_create_params.rb
  • lib/openai/models/responses/response_format_text_config.rb
  • lib/openai/models/responses/response_format_text_json_schema_config.rb
  • lib/openai/models/responses/response_function_tool_call.rb
  • lib/openai/models/responses/response_function_web_search.rb
  • lib/openai/models/responses/response_output_text.rb
  • lib/openai/models/responses/tool.rb
  • lib/openai/resources/beta/responses.rb
  • lib/openai/resources/beta/threads.rb
  • lib/openai/resources/chat/completions.rb
  • lib/openai/resources/files.rb
  • lib/openai/resources/responses.rb
  • lib/openai/resources/vector_stores/file_batches.rb
  • lib/openai/resources/vector_stores/files.rb
  • lib/openai/resources/webhooks.rb
  • rbi/openai/client.rbi
  • rbi/openai/models/chat/chat_completion_message.rbi
  • rbi/openai/models/chat/chat_completion_message_function_tool_call.rbi
  • rbi/openai/models/chat/completion_create_params.rbi
  • rbi/openai/models/response_format_json_schema.rbi
  • rbi/openai/models/responses/response.rbi
  • rbi/openai/models/responses/response_create_params.rbi
  • rbi/openai/models/responses/response_function_tool_call.rbi
  • rbi/openai/models/responses/response_function_web_search.rbi
  • rbi/openai/models/responses/response_output_text.rbi
  • rbi/openai/resources/chat/completions.rbi
  • rbi/openai/resources/files.rbi
  • rbi/openai/resources/responses.rbi
  • rbi/openai/resources/vector_stores/file_batches.rbi
  • rbi/openai/resources/vector_stores/files.rbi
  • rbi/openai/resources/webhooks.rbi
  • scripts/castiron/README.md

10 more in the full report.

A changed generated baseline means this report cannot reliably identify which handwritten lines changed.

Inspect the custom-code diff

Download the exact patch produced by this run (requires repository access):

gh run download 32449620513 --repo openai/openai-ruby \
  --name castiron-custom-code-32449620513-1 --dir /tmp/castiron-custom-code-32449620513-1
git apply --stat /tmp/castiron-custom-code-32449620513-1/custom-code.patch
cat /tmp/castiron-custom-code-32449620513-1/custom-code.patch

Or reproduce it from an SDK checkout containing the vendored reporter:

git fetch --no-tags origin 7ab65d8b6583aff4163dd527b4919368cacaf028 787b12a037a7116c2ca4a7c105c5875eb540ea72
python3 scripts/castiron/custom_code_report.py report \
  --base 7ab65d8b6583aff4163dd527b4919368cacaf028 \
  --head 787b12a037a7116c2ca4a7c105c5875eb540ea72 --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-787b12a037a7
cat /tmp/castiron-custom-code-787b12a037a7/custom-code.patch

This is the current full custom patch for mixed files, not an attribution of only the handwritten lines changed by this PR.

Full report and patch

Comment thread examples/realtime/function_calling.rb Fixed

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bee201d890

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread examples/realtime/image_input.rb

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 66da2b0480

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread examples/realtime/image_input.rb Outdated
Comment thread examples/realtime/image_input.rb Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 89dc1953ad

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread examples/realtime/image_input.rb
Comment thread examples/realtime/image_input.rb Outdated
Comment thread realtime.md
Comment thread examples/realtime/mcp_approval.rb

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 787b12a037

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +126 to +127
length = bytes.byteslice(offset, 4).unpack1("N")
type = bytes.byteslice(offset + 4, 4)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reject unsupported critical PNG chunks

When a CRC-valid unknown critical chunk such as ABCD appears between IHDR and IDAT, this parser silently skips it and returns true, even though a PNG decoder must stop when it cannot interpret a critical chunk. The example consequently opens the authenticated connection and uploads an image that its preflight validation claims is valid; validate chunk-type bits and reject unsupported critical chunks, with a focused regression case.

AGENTS.md reference: AGENTS.md:L25-L29

Useful? React with 👍 / 👎.

Comment on lines +144 to +146
if type == "IDAT"
saw_idat = true
idat << data

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reject nonconsecutive IDAT chunks

When an ancillary chunk such as tEXt separates two IDAT chunks, this loop concatenates the compressed bytes and accepts the file, although PNG requires the IDAT sequence to be consecutive and standard decoders reject such input. Track whether the IDAT run has ended and reject any later IDAT before connecting and uploading, with a focused malformed-image test.

AGENTS.md reference: AGENTS.md:L25-L29

Useful? React with 👍 / 👎.

return valid_jpeg_scans?(frame, scans)
end

next if marker == 0x01 || (0xD0..0xD7).cover?(marker)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reject restart markers outside JPEG scan data

When an RST marker such as FF D0 is inserted after SOI or between ordinary metadata segments, this branch skips it and the otherwise valid file still passes preflight. Restart markers are only valid inside entropy-coded scan data, where jpeg_scan_data already validates their sequence and restart interval; reject them in the outer marker loop so malformed files are not connected and uploaded, with a focused regression case.

AGENTS.md reference: AGENTS.md:L25-L29

Useful? React with 👍 / 👎.

Comment on lines +130 to +135
connection.conversation.items.create(
type: :mcp_approval_response,
id: "approval_response_1",
approval_request_id: item.id,
approve: true,
reason: "Approved by the example application policy."

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Require an application policy before approving MCP calls

When the configured MCP server advertises any tool under the expected label, the example selects its first tool and unconditionally approves whatever arguments the model supplies; the checks above only compare values that originated from that same server and therefore do not constitute an independent approval policy. A compromised or unexpectedly changed server can consequently cause a destructive call without operator consent, so require a caller-provided tool/argument allowlist or an explicit interactive decision before sending approve: true.

AGENTS.md reference: AGENTS.md:L25-L29

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant