github/codex
4
0 Fork 0
mirror of https://github.com/openai/codex.git synced 2026-11-12 14:41:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Persist realtime events in the thread timeline (#40508)

Browse Source 
## Why

Clients need a bounded view of realtime conversations that preserves the order of speech, agent work, and turn lifecycle events without loading the full thread history.

## What changed

- Persist realtime session boundaries, transcript segments, and promoted agent items in paginated thread rollouts.
- Add the experimental `thread/timeline/list` API to page ordinary items, realtime items, and turn boundaries in canonical rollout order. Include `activeRealtimeSessionAtPageStart` so each page can be rendered independently.
- Emit typed `thread/realtime/item/started`, `thread/realtime/item/transcript/delta`, and `thread/realtime/item/completed` notifications around durable realtime items.
- Keep the existing `thread/items/list` response and legacy thread history behavior unchanged.

## Testing

- Cover mixed timeline pagination, realtime-session state at page boundaries, rollout replay, subagent history prefixes, transcript streaming, steering, and promoted agent artifacts.

GitOrigin-RevId: faa2c420192d63e060e8fb32446e3c797422656e
This commit is contained in:
guinness-oai authored and copyberry committed 2026-08-25 01:03:20 +00:00
1 parent 80e871309a
commit 41ca88e95c
80 files changed
+5140 -47
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json
Generated
+452
View File
@@ -16424,6 +16424,66 @@
"title": "Thread/realtime/itemAddedNotification",
"type": "object"
},
{
"properties": {
"method": {
"enum": [
"thread/realtime/item/started"
],
"title": "Thread/realtime/item/startedNotificationMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/ThreadRealtimeItemStartedNotification"
}
},
"required": [
"method",
"params"
],
"title": "Thread/realtime/item/startedNotification",
"type": "object"
},
{
"properties": {
"method": {
"enum": [
"thread/realtime/item/transcript/delta"
],
"title": "Thread/realtime/item/transcript/deltaNotificationMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/ThreadRealtimeItemTranscriptDeltaNotification"
}
},
"required": [
"method",
"params"
],
"title": "Thread/realtime/item/transcript/deltaNotification",
"type": "object"
},
{
"properties": {
"method": {
"enum": [
"thread/realtime/item/completed"
],
"title": "Thread/realtime/item/completedNotificationMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/ThreadRealtimeItemCompletedNotification"
}
},
"required": [
"method",
"params"
],
"title": "Thread/realtime/item/completedNotification",
"type": "object"
},
{
"properties": {
"method": {
@@ -19270,6 +19330,65 @@
],
"type": "object"
},
"ThreadRealtimeBemItemPresentation": {
"description": "EXPERIMENTAL - how an existing agent item appears in a realtime conversation.",
"oneOf": [
{
"properties": {
"type": {
"enum": [
"wholeItem"
],
"title": "WholeItemThreadRealtimeBemItemPresentationType",
"type": "string"
}
},
"required": [
"type"
],
"title": "WholeItemThreadRealtimeBemItemPresentation",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"inlineMarkdown"
],
"title": "InlineMarkdownThreadRealtimeBemItemPresentationType",
"type": "string"
}
},
"required": [
"type"
],
"title": "InlineMarkdownThreadRealtimeBemItemPresentation",
"type": "object"
},
{
"properties": {
"index": {
"format": "uint32",
"minimum": 0.0,
"type": "integer"
},
"type": {
"enum": [
"inlineVisualization"
],
"title": "InlineVisualizationThreadRealtimeBemItemPresentationType",
"type": "string"
}
},
"required": [
"index",
"type"
],
"title": "InlineVisualizationThreadRealtimeBemItemPresentation",
"type": "object"
}
]
},
"ThreadRealtimeClosedNotification": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "EXPERIMENTAL - emitted when thread realtime transport closes.",
@@ -19324,6 +19443,112 @@
],
"type": "object"
},
"ThreadRealtimeItem": {
"description": "EXPERIMENTAL - a thread-scoped realtime item in the canonical timeline.",
"oneOf": [
{
"properties": {
"type": {
"enum": [
"realtimeSessionStarted"
],
"title": "RealtimeSessionStartedThreadRealtimeItemType",
"type": "string"
}
},
"required": [
"type"
],
"title": "RealtimeSessionStartedThreadRealtimeItem",
"type": "object"
},
{
"properties": {
"role": {
"$ref": "#/definitions/ThreadRealtimeTranscriptRole"
},
"text": {
"type": "string"
},
"type": {
"enum": [
"transcriptSegment"
],
"title": "TranscriptSegmentThreadRealtimeItemType",
"type": "string"
}
},
"required": [
"role",
"text",
"type"
],
"title": "TranscriptSegmentThreadRealtimeItem",
"type": "object"
},
{
"properties": {
"item_id": {
"type": "string"
},
"presentation": {
"$ref": "#/definitions/ThreadRealtimeBemItemPresentation"
},
"turn_id": {
"type": "string"
},
"type": {
"enum": [
"bemItemPromoted"
],
"title": "BemItemPromotedThreadRealtimeItemType",
"type": "string"
}
},
"required": [
"item_id",
"presentation",
"turn_id",
"type"
],
"title": "BemItemPromotedThreadRealtimeItem",
"type": "object"
},
{
"properties": {
"outcome": {
"$ref": "#/definitions/ThreadRealtimeSessionOutcome"
},
"type": {
"enum": [
"realtimeSessionClosed"
],
"title": "RealtimeSessionClosedThreadRealtimeItemType",
"type": "string"
}
},
"required": [
"outcome",
"type"
],
"title": "RealtimeSessionClosedThreadRealtimeItem",
"type": "object"
}
],
"properties": {
"id": {
"type": "string"
},
"realtimeSessionId": {
"type": "string"
}
},
"required": [
"id",
"realtimeSessionId"
],
"type": "object"
},
"ThreadRealtimeItemAddedNotification": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "EXPERIMENTAL - raw non-audio thread realtime item emitted by the backend.",
@@ -19340,6 +19565,64 @@
"title": "ThreadRealtimeItemAddedNotification",
"type": "object"
},
"ThreadRealtimeItemCompletedNotification": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "EXPERIMENTAL - a realtime timeline item published after canonical commit.",
"properties": {
"item": {
"$ref": "#/definitions/ThreadRealtimeItem"
},
"threadId": {
"type": "string"
}
},
"required": [
"item",
"threadId"
],
"title": "ThreadRealtimeItemCompletedNotification",
"type": "object"
},
"ThreadRealtimeItemStartedNotification": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "EXPERIMENTAL - a realtime timeline item started before its content streams.",
"properties": {
"item": {
"$ref": "#/definitions/ThreadRealtimeItem"
},
"threadId": {
"type": "string"
}
},
"required": [
"item",
"threadId"
],
"title": "ThreadRealtimeItemStartedNotification",
"type": "object"
},
"ThreadRealtimeItemTranscriptDeltaNotification": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "EXPERIMENTAL - text appended to an active realtime transcript item.",
"properties": {
"delta": {
"type": "string"
},
"itemId": {
"type": "string"
},
"threadId": {
"type": "string"
}
},
"required": [
"delta",
"itemId",
"threadId"
],
"title": "ThreadRealtimeItemTranscriptDeltaNotification",
"type": "object"
},
"ThreadRealtimeOutputAudioDeltaNotification": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "EXPERIMENTAL - streamed output audio emitted by thread realtime.",
@@ -19376,6 +19659,13 @@
"title": "ThreadRealtimeSdpNotification",
"type": "object"
},
"ThreadRealtimeSessionOutcome": {
"enum": [
"ended",
"failed"
],
"type": "string"
},
"ThreadRealtimeStartTransport": {
"description": "EXPERIMENTAL - transport used by thread realtime.",
"oneOf": [
@@ -19509,6 +19799,13 @@
"title": "ThreadRealtimeTranscriptDoneNotification",
"type": "object"
},
"ThreadRealtimeTranscriptRole": {
"enum": [
"user",
"assistant"
],
"type": "string"
},
"ThreadResumeInitialTurnsPageParams": {
"properties": {
"itemsView": {
@@ -20504,6 +20801,161 @@
"title": "ThreadStatusChangedNotification",
"type": "object"
},
"ThreadTimelineEntry": {
"description": "EXPERIMENTAL - one item or turn boundary in canonical rollout order.",
"oneOf": [
{
"properties": {
"item": {
"$ref": "#/definitions/ThreadItem"
},
"position": {
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"turnId": {
"type": "string"
},
"type": {
"enum": [
"item"
],
"title": "ItemThreadTimelineEntryType",
"type": "string"
}
},
"required": [
"item",
"position",
"turnId",
"type"
],
"title": "ItemThreadTimelineEntry",
"type": "object"
},
{
"properties": {
"item": {
"$ref": "#/definitions/ThreadRealtimeItem"
},
"position": {
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"type": {
"enum": [
"realtime"
],
"title": "RealtimeThreadTimelineEntryType",
"type": "string"
}
},
"required": [
"item",
"position",
"type"
],
"title": "RealtimeThreadTimelineEntry",
"type": "object"
},
{
"properties": {
"position": {
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"started_at": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"turn_id": {
"type": "string"
},
"type": {
"enum": [
"turnStarted"
],
"title": "TurnStartedThreadTimelineEntryType",
"type": "string"
}
},
"required": [
"position",
"turn_id",
"type"
],
"title": "TurnStartedThreadTimelineEntry",
"type": "object"
},
{
"properties": {
"completed_at": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"duration_ms": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"error": {
"anyOf": [
{
"$ref": "#/definitions/TurnError"
},
{
"type": "null"
}
]
},
"position": {
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"started_at": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"status": {
"$ref": "#/definitions/TurnStatus"
},
"turn_id": {
"type": "string"
},
"type": {
"enum": [
"turnCompleted"
],
"title": "TurnCompletedThreadTimelineEntryType",
"type": "string"
}
},
"required": [
"position",
"status",
"turn_id",
"type"
],
"title": "TurnCompletedThreadTimelineEntry",
"type": "object"
}
]
},
"ThreadTokenUsage": {
"properties": {
"last": {