fix(docs): correct the chat streaming helper contract

[HAYDEN-OAI]

Summary

Correct three tokens in the handwritten Chat Streaming guide:

• The optional stream flag accepted by chat.completions.stream() is true, not false.
• The helper returns ChatCompletionStream, not ChatCompletionStreamingRunner (which is used for streaming tool runners).

The current documented stream: false call fails type checking with TS2322. The public helper always enables streaming. No SDK implementation, generated files, public declarations, dependencies, or lockfiles change. docs/helpers.md is absent from the pinned Castiron generated snapshot. I checked open PRs; #2591 edits an unrelated afterCompletion section of the same guide and does not address this issue.

Validation

• Compiler reproduction through the public OpenAI export: stream: false is rejected; omitted stream and stream: true are accepted.
• Public .stream() smoke test with synthetic SSE: exact ChatCompletionStream prototype, not a ChatCompletionStreamingRunner, serialized stream: true, successful completion, no live API calls.
• ./scripts/test tests/lib/ChatCompletionStream.test.ts: 40 passed on Node 22.22.2 and 40 passed on Node 24.19.0.
• Pinned Oxfmt 0.62.0 check and git diff --check passed.
• Local focused tests used available cached Vitest 4.1.10; the repository pins 4.1.11. A fresh frozen install remains blocked by missing publication-time metadata for qs@6.16.0 in the configured registry; no installation safeguards or configuration were changed.

Adversarial self-review

Reviewed public types, actual return identity, optional/explicit stream behavior, compatibility, and security implications. Independent review found no actionable issues. This is a documentation-only correction; compiler/runtime verification and the existing stream suite are proportionate, without adding a Markdown-parsing test harness for three tokens.

[chatgpt-codex-connector]

Codex Review Summary

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

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-04T02:19:50.258542Z	0737b8f	PR opened
🔒 Security Review	✅ Completed 2026-09-04T02:20:36.001075Z	0737b8f	PR opened

ℹ️ 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]

OkTest Summary

✅ 237/237 SDK tests passed in 10.31s for Node SDK PR #2596.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	150ms
tests/chat-completions-create.test.ts	✅ Passed	233ms
tests/chat-completions-stream.test.ts	✅ Passed	124ms
tests/files-content-binary.test.ts	✅ Passed	122ms
tests/files-create-multipart.test.ts	✅ Passed	186ms
tests/files-list-pagination.test.ts	✅ Passed	193ms
tests/initialize-config.test.ts	✅ Passed	204ms
tests/instance-isolation.test.ts	✅ Passed	129ms
tests/models-list.test.ts	✅ Passed	137ms
tests/responses-background-lifecycle.test.ts	✅ Passed	193ms
tests/responses-body-method-errors.test.ts	✅ Passed	343ms
tests/responses-cancel-timeout.test.ts	✅ Passed	194ms
tests/responses-cancel.test.ts	✅ Passed	260ms
tests/responses-compact-retries.test.ts	✅ Passed	258ms
tests/responses-compact.test.ts	✅ Passed	220ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	133ms
tests/responses-create-advanced.test.ts	✅ Passed	177ms
tests/responses-create-disconnect.test.ts	✅ Passed	1.014s
tests/responses-create-errors.test.ts	✅ Passed	216ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	162ms
tests/responses-create-retries.test.ts	✅ Passed	261ms
tests/responses-create-stream-failures.test.ts	✅ Passed	194ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	2.14s
tests/responses-create-stream-wire.test.ts	✅ Passed	2.423s
tests/responses-create-stream.test.ts	✅ Passed	75ms
tests/responses-create-terminal-states.test.ts	✅ Passed	208ms
tests/responses-create-timeout.test.ts	✅ Passed	245ms
tests/responses-create.test.ts	✅ Passed	242ms
tests/responses-delete.test.ts	✅ Passed	207ms
tests/responses-input-items-errors.test.ts	✅ Passed	183ms
tests/responses-input-items-list.test.ts	✅ Passed	178ms
tests/responses-input-items-options.test.ts	✅ Passed	120ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	265ms
tests/responses-input-tokens-count.test.ts	✅ Passed	287ms
tests/responses-malformed-inputs.test.ts	✅ Passed	2.148s
tests/responses-not-found-errors.test.ts	✅ Passed	238ms
tests/responses-parse.test.ts	✅ Passed	167ms
tests/responses-retrieve-retries.test.ts	✅ Passed	221ms
tests/responses-retrieve.test.ts	✅ Passed	224ms
tests/responses-stored-method-errors.test.ts	✅ Passed	523ms
tests/retry-behavior.test.ts	✅ Passed	3.21s
tests/sdk-error-shape.test.ts	✅ Passed	281ms

View OkTest run #33829055689

_{SDK merge (c9dd697e27c4) · head (0737b8f0558b) · base (6153484a88c2) · OkTest (2b1bdfd25e98)}

[github-actions]

Castiron custom code

✅ No new custom-code files detected.

32 mixed files remain; 0 existing customizations changed.

Compared 6153484a88c2 → 0737b8f0558b. Generated baselines verified.

32 existing customizations unchanged

• api.md
• scripts/castiron/README.md
• scripts/castiron/custom_code_report.py
• scripts/castiron/test_custom_code_report.py
• src/client.ts
• src/resources/audio/transcriptions.ts
• src/resources/audio/translations.ts
• src/resources/beta/assistants.ts
• src/resources/beta/beta.ts
• src/resources/beta/index.ts
• src/resources/beta/responses/internal-base.ts
• src/resources/beta/responses/responses.ts
• src/resources/beta/threads/index.ts
• src/resources/beta/threads/runs/index.ts
• src/resources/beta/threads/runs/runs.ts
• src/resources/beta/threads/threads.ts
• src/resources/chat/completions/completions.ts
• src/resources/chat/completions/index.ts
• src/resources/conversations/index.ts
• src/resources/embeddings.ts
• src/resources/files.ts
• src/resources/fine-tuning/checkpoints/permissions.ts
• src/resources/images.ts
• src/resources/responses/internal-base.ts
• src/resources/responses/responses.ts
• src/resources/skills/skills.ts
• src/resources/skills/versions/versions.ts
• src/resources/vector-stores/file-batches.ts
• src/resources/vector-stores/files.ts
• src/resources/webhooks/index.ts
• src/resources/webhooks/webhooks.ts
• tests/lib/data-residency.test.ts

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 33829068742 --repo openai/openai-node \
  --name castiron-custom-code-33829068742-1 --dir /tmp/castiron-custom-code-33829068742-1
git apply --stat /tmp/castiron-custom-code-33829068742-1/custom-code.patch
cat /tmp/castiron-custom-code-33829068742-1/custom-code.patch

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

git fetch --no-tags origin 6153484a88c2ce97bc81fe9c773b7c51b2f11d8f 0737b8f0558b4b4340875f6510125e6de38490d9
python3 scripts/castiron/custom_code_report.py report \
  --base 6153484a88c2ce97bc81fe9c773b7c51b2f11d8f \
  --head 0737b8f0558b4b4340875f6510125e6de38490d9 --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-0737b8f0558b
cat /tmp/castiron-custom-code-0737b8f0558b/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

[jbeckwith-oai]

Validated the exact-head documentation correction. The public chat completions stream helper accepts only omitted or true stream mode and returns ChatCompletionStream, not the tool-runner type. The updated signature and prose now match the public API contract. Review is complete; CI is still running.