feat: add async event iterators

[HAYDEN-OAI]

Summary

• add a typed events(eventName) async iterator to EventStream
• document awaiting repeated imageFileDone assistant helper events
• add coverage for ordering, queued events, and stream failures

Why

Issue #879 needs async/await control for SDK convenience events such as imageFileDone. Existing .on() callbacks are synchronous, so callers cannot naturally process each repeated event sequentially.

Behavior

stream.events(eventName) yields the emitted argument tuple for every occurrence. It queues events while the consumer awaits work, ends with the stream, and surfaces stream errors or aborts after previously queued events have been drained. Existing .on() behavior is unchanged.

Validation

• pnpm exec jest tests/lib/EventStream.test.ts --runInBand
• pnpm exec tsc --noEmit
• pnpm run lint

Resolves #879

[openai-sdks]

OkTest Summary

✅ 237/237 SDK tests passed in 11.166s for Node SDK PR #1977.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	180ms
tests/chat-completions-create.test.ts	✅ Passed	243ms
tests/chat-completions-stream.test.ts	✅ Passed	304ms
tests/files-content-binary.test.ts	✅ Passed	204ms
tests/files-create-multipart.test.ts	✅ Passed	231ms
tests/files-list-pagination.test.ts	✅ Passed	292ms
tests/initialize-config.test.ts	✅ Passed	184ms
tests/instance-isolation.test.ts	✅ Passed	104ms
tests/models-list.test.ts	✅ Passed	195ms
tests/responses-background-lifecycle.test.ts	✅ Passed	235ms
tests/responses-body-method-errors.test.ts	✅ Passed	348ms
tests/responses-cancel-timeout.test.ts	✅ Passed	216ms
tests/responses-cancel.test.ts	✅ Passed	198ms
tests/responses-compact-retries.test.ts	✅ Passed	216ms
tests/responses-compact.test.ts	✅ Passed	227ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	130ms
tests/responses-create-advanced.test.ts	✅ Passed	173ms
tests/responses-create-disconnect.test.ts	✅ Passed	1.207s
tests/responses-create-errors.test.ts	✅ Passed	188ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	290ms
tests/responses-create-retries.test.ts	✅ Passed	348ms
tests/responses-create-stream-failures.test.ts	✅ Passed	269ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	2.237s
tests/responses-create-stream-wire.test.ts	✅ Passed	2.668s
tests/responses-create-stream.test.ts	✅ Passed	70ms
tests/responses-create-terminal-states.test.ts	✅ Passed	233ms
tests/responses-create-timeout.test.ts	✅ Passed	204ms
tests/responses-create.test.ts	✅ Passed	170ms
tests/responses-delete.test.ts	✅ Passed	254ms
tests/responses-input-items-errors.test.ts	✅ Passed	243ms
tests/responses-input-items-list.test.ts	✅ Passed	216ms
tests/responses-input-items-options.test.ts	✅ Passed	213ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	229ms
tests/responses-input-tokens-count.test.ts	✅ Passed	231ms
tests/responses-malformed-inputs.test.ts	✅ Passed	2.372s
tests/responses-not-found-errors.test.ts	✅ Passed	230ms
tests/responses-parse.test.ts	✅ Passed	194ms
tests/responses-retrieve-retries.test.ts	✅ Passed	231ms
tests/responses-retrieve.test.ts	✅ Passed	218ms
tests/responses-stored-method-errors.test.ts	✅ Passed	605ms
tests/retry-behavior.test.ts	✅ Passed	3.298s
tests/sdk-error-shape.test.ts	✅ Passed	259ms

View OkTest run #28824434602

_{SDK merge (e9871d6c9b38) · head (e7cd5be20311) · base (95b54e589491) · OkTest (7fc645091b1a)}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fd75792ee1

ℹ️ 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".

[jbeckwith-oai]

@-

[jbeckwith-oai]

Comprehensive review completed against e7cd5be.

Original issue reproduced on base 95b54e5: a minimal EventStream async imageFileDone listener received two events while the first handler was blocked, producing start:first, start:second, end:second. This confirms #879: synchronous callbacks do not serialize awaited work. The reproduction passed with node_modules/.bin/jest tests/lib/EventStream.issue879-repro.test.ts --runInBand (1/1).

Validation:

• Authored tests plus six review edge cases passed (10/10): queued-before-read delivery, independent subscribers, multiple pending reads on end/failure, direct error/abort iteration, zero-argument tuples, cancellation without stream abort, and creation after end.
• Scoped TypeScript validation passed for the implementation and review cases.
• Prettier and ESLint passed on changed files.
• CI is green for build, lint, Node 20/22/24/26.2 tests, ecosystem tests, breaking-change detection, Agents SDK regressions, CodeQL, and the 237-test SDK integration run.

Compatibility:

• Additive API; existing on, once, emitted, and AssistantStream iteration behavior is unchanged.
• Event-name generics preserve exact argument tuples.
• Events remain ordered during awaited consumer work; terminal failures follow queued events; explicitly iterating error or abort yields those events.
• Iterator return removes only its own listeners and does not abort the stream. The follow-up commit restores normal unhandled-failure behavior after cleanup.
• No in-repository subclass has an events member collision. I found no runtime, type, or API breaking change.

No blocking or nonblocking findings. Approved.

[jbeckwith-oai]

Approved after reproducing issue #879 on base 95b54e5 and validating e7cd5be with 10 targeted tests plus scoped type, lint, formatting, CI, compatibility, and edge-case review. No blocking or nonblocking findings. Full evidence: #1977 (comment)