codex/
items.rs

1use serde::{Deserialize, Serialize};
2use serde_json::Value;
3
4/// Lifecycle status for a command execution item.
5#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
6#[serde(rename_all = "snake_case")]
7pub enum CommandExecutionStatus {
8    /// Command started and is still running.
9    InProgress,
10    /// Command finished successfully or with a captured exit code.
11    Completed,
12    /// Command failed before producing a completed state.
13    Failed,
14}
15
16/// Command execution output item.
17#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
18pub struct CommandExecutionItem {
19    /// Unique item id.
20    pub id: String,
21    /// Shell command text executed by the agent.
22    pub command: String,
23    /// Aggregated stdout/stderr text emitted so far.
24    pub aggregated_output: String,
25    /// Process exit code when available.
26    #[serde(skip_serializing_if = "Option::is_none")]
27    pub exit_code: Option<i32>,
28    /// Current command lifecycle status.
29    pub status: CommandExecutionStatus,
30}
31
32/// File patch change kind.
33#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
34#[serde(rename_all = "snake_case")]
35pub enum PatchChangeKind {
36    /// File was added.
37    Add,
38    /// File was deleted.
39    Delete,
40    /// File was modified in place.
41    Update,
42}
43
44/// One changed file within a patch item.
45#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
46pub struct FileUpdateChange {
47    /// File path relative to the thread working directory.
48    pub path: String,
49    /// Type of change applied to this file.
50    pub kind: PatchChangeKind,
51}
52
53/// Patch application lifecycle status.
54#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
55#[serde(rename_all = "snake_case")]
56pub enum PatchApplyStatus {
57    /// Patch application completed.
58    Completed,
59    /// Patch application failed.
60    Failed,
61}
62
63/// File change item containing patch metadata.
64#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
65pub struct FileChangeItem {
66    /// Unique item id.
67    pub id: String,
68    /// Files affected by the patch.
69    pub changes: Vec<FileUpdateChange>,
70    /// Patch apply status.
71    pub status: PatchApplyStatus,
72}
73
74/// Lifecycle status for MCP tool call items.
75#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
76#[serde(rename_all = "snake_case")]
77pub enum McpToolCallStatus {
78    /// MCP tool call is still running.
79    InProgress,
80    /// MCP tool call completed successfully.
81    Completed,
82    /// MCP tool call failed.
83    Failed,
84}
85
86/// Successful MCP tool call result payload.
87#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
88pub struct McpToolCallResult {
89    /// Content blocks returned by MCP tool execution.
90    pub content: Vec<Value>,
91    /// Structured result payload returned by MCP tool execution.
92    pub structured_content: Value,
93}
94
95/// Failed MCP tool call payload.
96#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
97pub struct McpToolCallError {
98    /// Human-readable error message.
99    pub message: String,
100}
101
102/// MCP tool call item.
103#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
104pub struct McpToolCallItem {
105    /// Unique item id.
106    pub id: String,
107    /// MCP server name.
108    pub server: String,
109    /// MCP tool name.
110    pub tool: String,
111    /// JSON arguments passed to the tool.
112    pub arguments: Value,
113    /// Successful result payload when available.
114    #[serde(skip_serializing_if = "Option::is_none")]
115    pub result: Option<McpToolCallResult>,
116    /// Error payload when the tool call fails.
117    #[serde(skip_serializing_if = "Option::is_none")]
118    pub error: Option<McpToolCallError>,
119    /// Current MCP tool call status.
120    pub status: McpToolCallStatus,
121}
122
123/// Final assistant text response item.
124#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
125pub struct AgentMessageItem {
126    /// Unique item id.
127    pub id: String,
128    /// Assistant message text.
129    pub text: String,
130}
131
132/// Model reasoning item.
133#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
134pub struct ReasoningItem {
135    /// Unique item id.
136    pub id: String,
137    /// Reasoning content text.
138    pub text: String,
139}
140
141/// Web search item.
142#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
143pub struct WebSearchItem {
144    /// Unique item id.
145    pub id: String,
146    /// Search query string.
147    pub query: String,
148}
149
150/// Item representing an error generated inside the turn flow.
151#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
152pub struct ErrorItem {
153    /// Unique item id.
154    pub id: String,
155    /// Error message.
156    pub message: String,
157}
158
159/// One todo entry tracked by the agent.
160#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
161pub struct TodoItem {
162    /// Todo text content.
163    pub text: String,
164    /// Whether this todo has been completed.
165    pub completed: bool,
166}
167
168/// Todo list item.
169#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
170pub struct TodoListItem {
171    /// Unique item id.
172    pub id: String,
173    /// Todo entries tracked in this list.
174    pub items: Vec<TodoItem>,
175}
176
177/// Canonical union of thread items and their type-specific payloads.
178#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
179#[serde(tag = "type", rename_all = "snake_case")]
180pub enum ThreadItem {
181    /// Assistant message payload.
182    AgentMessage(AgentMessageItem),
183    /// Reasoning payload.
184    Reasoning(ReasoningItem),
185    /// Command execution payload.
186    CommandExecution(CommandExecutionItem),
187    /// File change payload.
188    FileChange(FileChangeItem),
189    /// MCP tool call payload.
190    McpToolCall(McpToolCallItem),
191    /// Web search payload.
192    WebSearch(WebSearchItem),
193    /// Todo list payload.
194    TodoList(TodoListItem),
195    /// Error payload.
196    Error(ErrorItem),
197}
codex/items.rs

codex/
items.rs
