docs: Improve streaming documentation with event diagrams and correct types#1780
docs: Improve streaming documentation with event diagrams and correct types#1780darshjme wants to merge 1 commit intoopenai:masterfrom
Conversation
Addresses openai#860 by clarifying the relationship between raw SSE events and the SDK's convenience event listeners. Changes: - Add Responses API streaming section to helpers.md with Mermaid sequence diagrams showing the event lifecycle - Add event type reference table for Responses streaming - Add mapping table showing how Assistant convenience events (textDelta, toolCallCreated, etc.) relate to raw SSE events (thread.message.delta, thread.run.step.delta, etc.) - Add Mermaid diagram for Assistant streaming lifecycle - Add raw event listener example for Assistants (thread.run.completed, thread.run.requires_action) that were previously undocumented - Update README streaming section with Mermaid diagram and typed event examples
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4720553dd3
ℹ️ 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".
| | `event` | _all events_ | `(event: AssistantStreamEvent) => void` | | ||
| | `runStepCreated` | `thread.run.step.created` | `(runStep: RunStep) => void` | | ||
| | `runStepDelta` | `thread.run.step.delta` | `(delta: RunStepDelta, snapshot: RunStep) => void` | | ||
| | `runStepDone` | `thread.run.step.completed` | `(runStep: RunStep) => void` | |
There was a problem hiding this comment.
The new mapping row documents runStepDone as if it only comes from thread.run.step.completed, but AssistantStream.#handleRunStep emits runStepDone for thread.run.step.failed, thread.run.step.cancelled, and thread.run.step.expired as well (src/lib/AssistantStream.ts, switch cases around lines 537-550). Users following this table may skip failure/cancellation handling and incorrectly assume no runStepDone callback will fire in those paths.
Useful? React with 👍 / 👎.
| | `textDone` | `thread.message.completed` | `(content: Text, snapshot: Message) => void` | | ||
| | `toolCallCreated` | `thread.run.step.delta` (first tool call) | `(toolCall: ToolCall) => void` | | ||
| | `toolCallDelta` | `thread.run.step.delta` (subsequent) | `(delta: ToolCallDelta, snapshot: ToolCall) => void` | | ||
| | `toolCallDone` | `thread.run.step.completed` | `(toolCall: ToolCall) => void` | |
There was a problem hiding this comment.
This row says toolCallDone is triggered by thread.run.step.completed, but the stream implementation also emits toolCallDone when switching tool-call indices during thread.run.step.delta and on other terminal step states (failed, cancelled, expired) in src/lib/AssistantStream.ts (around lines 524-546). Documenting only thread.run.step.completed can lead integrators to miss legitimate toolCallDone callbacks and mishandle tool-call lifecycle state.
Useful? React with 👍 / 👎.
1 participant
Summary
Addresses #860 -- the streaming documentation uses convenience event names (
textCreated,textDelta,toolCallCreated) without explaining how they relate to the raw SSE events (thread.message.delta,thread.run.step.delta, etc.) from the API reference. This makes it hard to discover events likethread.run.completedorthread.run.requires_actionthat don't have convenience wrappers.Changes:
.on('event', ...)for events likethread.run.completedandthread.run.requires_action.on()typed event listeners andfor await...ofiterationTest plan
src/resources/responses/responses.ts,src/lib/AssistantStream.ts)