codex/
events.rs

1use serde::{Deserialize, Serialize};
2
3use crate::items::ThreadItem;
4
5/// Token usage for a completed turn.
6#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
7pub struct Usage {
8    /// Input tokens consumed by the turn.
9    pub input_tokens: u64,
10    /// Input tokens served from cache.
11    pub cached_input_tokens: u64,
12    /// Output tokens generated by the model.
13    pub output_tokens: u64,
14}
15
16/// Turn failure payload.
17#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
18pub struct ThreadError {
19    /// Human-readable error message emitted for a failed turn.
20    pub message: String,
21}
22
23/// Payload for a `thread.started` event.
24#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
25pub struct ThreadStartedEvent {
26    /// Stable thread identifier used for subsequent `resume` turns.
27    pub thread_id: String,
28}
29
30/// Payload for a `turn.started` event.
31#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
32pub struct TurnStartedEvent;
33
34/// Payload for a `turn.completed` event.
35#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
36pub struct TurnCompletedEvent {
37    /// Final token usage reported for the turn.
38    pub usage: Usage,
39}
40
41/// Payload for a `turn.failed` event.
42#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
43pub struct TurnFailedEvent {
44    /// Error details for the failed turn.
45    pub error: ThreadError,
46}
47
48/// Payload for an `item.started` event.
49#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
50pub struct ItemStartedEvent {
51    /// Item state snapshot when processing begins.
52    pub item: ThreadItem,
53}
54
55/// Payload for an `item.updated` event.
56#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
57pub struct ItemUpdatedEvent {
58    /// Item state snapshot after an incremental update.
59    pub item: ThreadItem,
60}
61
62/// Payload for an `item.completed` event.
63#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
64pub struct ItemCompletedEvent {
65    /// Final item payload.
66    pub item: ThreadItem,
67}
68
69/// Payload for a top-level `error` event.
70#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
71pub struct ThreadErrorEvent {
72    /// Human-readable stream-level error message.
73    pub message: String,
74}
75
76/// Top-level JSONL events emitted by `codex exec --experimental-json`.
77#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
78#[serde(tag = "type")]
79pub enum ThreadEvent {
80    /// Emitted once when a thread is created and assigned an id.
81    #[serde(rename = "thread.started")]
82    ThreadStarted {
83        /// Stable thread identifier used for subsequent turns.
84        thread_id: String,
85    },
86    /// Emitted when a new turn starts execution.
87    #[serde(rename = "turn.started")]
88    TurnStarted,
89    /// Emitted after a successful turn with token usage information.
90    #[serde(rename = "turn.completed")]
91    TurnCompleted {
92        /// Final token usage for the completed turn.
93        usage: Usage,
94    },
95    /// Emitted when a turn fails.
96    #[serde(rename = "turn.failed")]
97    TurnFailed {
98        /// Failure payload describing why the turn failed.
99        error: ThreadError,
100    },
101    /// Emitted when an item starts.
102    #[serde(rename = "item.started")]
103    ItemStarted {
104        /// Item snapshot at start time.
105        item: ThreadItem,
106    },
107    /// Emitted when an in-progress item receives an update.
108    #[serde(rename = "item.updated")]
109    ItemUpdated {
110        /// Item snapshot after an intermediate update.
111        item: ThreadItem,
112    },
113    /// Emitted when an item is completed.
114    #[serde(rename = "item.completed")]
115    ItemCompleted {
116        /// Final item snapshot.
117        item: ThreadItem,
118    },
119    /// Emitted for stream-level errors not tied to a specific turn item.
120    #[serde(rename = "error")]
121    Error {
122        /// Human-readable stream-level error message.
123        message: String,
124    },
125}
codex/events.rs

codex/
events.rs
