fix: use Annotation type for ResponseOutputTextAnnotationAddedEvent.annotation

[C1-BA-B1-F3]

Description

Fixes #3419

The annotation field on ResponseOutputTextAnnotationAddedEvent was typed as object instead of the proper Annotation union type. This forced consumers to use typing.cast to access typed fields.

Changes

• Changed annotation: object to annotation: Annotation in ResponseOutputTextAnnotationAddedEvent
• Added import for Annotation from response_output_text.py
• Added tests to verify all annotation types are properly parsed

Type Definition

The Annotation type is already defined in response_output_text.py:

Annotation: TypeAlias = Annotated[
    Union[AnnotationFileCitation, AnnotationURLCitation, AnnotationContainerFileCitation, AnnotationFilePath],
    PropertyInfo(discriminator="type"),
]

This is consistent with how ResponseOutputText.annotations: List[Annotation] is already typed.

Testing

Added comprehensive tests covering all annotation variants:

• test_annotation_url_citation - URL citation annotations
• test_annotation_file_citation - File citation annotations
• test_annotation_container_file_citation - Container file citation annotations
• test_annotation_file_path - File path annotations
• test_annotation_type_is_union - Verifies field is not typed as object
• test_construct_type_with_annotation - Tests streaming event parsing

Before/After

Before:

from openai.types.responses import ResponseOutputTextAnnotationAddedEvent
from openai.types.responses.response_output_text import AnnotationURLCitation
import typing

event = ResponseOutputTextAnnotationAddedEvent(...)
annotation = typing.cast(AnnotationURLCitation, event.annotation)  # Required cast
print(annotation.url)

After:

from openai.types.responses import ResponseOutputTextAnnotationAddedEvent

event = ResponseOutputTextAnnotationAddedEvent(...)
# Can now match on type and access fields directly
if event.annotation.type == "url_citation":
    print(event.annotation.url)  # No cast needed

---

Ultraworked with Sisyphus

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4e0b2a1df1

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Always close the response if draining fails

When the added drain loop reads the remaining stream, response.iter_bytes() can still raise (for example a read timeout or protocol error while waiting for the chunked terminator). In that case execution never reaches response.close(), so this new cleanup path can leak the response/connection and can also replace the original streaming exception with the drain failure; the async branch added below has the same ordering. Wrap the drain in its own try/finally so close/aclose always runs.

Useful? React with 👍 / 👎.