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