Add missing "nullable" macro to protocol structs that contain optional fields (#5901)

This PR addresses a current hole in the TypeScript code generation for
the API server protocol. Fields that are marked as "Optional<>" in the
Rust code are serialized such that the value is omitted when it is
deserialized — appearing as `undefined`, but the TS type indicates
(incorrectly) that it is always defined but possibly `null`. This can
lead to subtle errors that the TypeScript compiler doesn't catch. The
fix is to include the `#[ts(optional_fields = nullable)]` macro for all
protocol structs that contain one or more `Optional<>` fields.

This PR also includes a new test that validates that all TS protocol
code containing "| null" in its type is marked optional ("?") to catch
cases where `#[ts(optional_fields = nullable)]` is omitted.

codex-rs/protocol/src/approvals.rs

@@ -61,6 +61,7 @@ impl SandboxRiskCategory {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct ExecApprovalRequestEvent {
     /// Identifier for the associated exec call, if available.
     pub call_id: String,
@@ -78,6 +79,7 @@ pub struct ExecApprovalRequestEvent {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct ApplyPatchApprovalRequestEvent {
     /// Responses API call id for the associated patch apply call, if available.
     pub call_id: String,

codex-rs/protocol/src/custom_prompts.rs

@@ -11,6 +11,7 @@ use ts_rs::TS;
 pub const PROMPTS_CMD_PREFIX: &str = "prompts";
 
 #[derive(Serialize, Deserialize, Debug, Clone, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct CustomPrompt {
     pub name: String,
     pub path: PathBuf,

codex-rs/protocol/src/models.rs

@@ -49,6 +49,7 @@ pub enum ContentItem {
 pub enum ResponseItem {
     Message {
         #[serde(skip_serializing)]
+        #[ts(optional = nullable)]
         id: Option<String>,
         role: String,
         content: Vec<ContentItem>,
@@ -58,20 +59,25 @@ pub enum ResponseItem {
         id: String,
         summary: Vec<ReasoningItemReasoningSummary>,
         #[serde(default, skip_serializing_if = "should_serialize_reasoning_content")]
+        #[ts(optional = nullable)]
         content: Option<Vec<ReasoningItemContent>>,
+        #[ts(optional = nullable)]
         encrypted_content: Option<String>,
     },
     LocalShellCall {
         /// Set when using the chat completions API.
         #[serde(skip_serializing)]
+        #[ts(optional = nullable)]
         id: Option<String>,
         /// Set when using the Responses API.
+        #[ts(optional = nullable)]
         call_id: Option<String>,
         status: LocalShellStatus,
         action: LocalShellAction,
     },
     FunctionCall {
         #[serde(skip_serializing)]
+        #[ts(optional = nullable)]
         id: Option<String>,
         name: String,
         // The Responses API returns the function call arguments as a *string* that contains
@@ -92,8 +98,10 @@ pub enum ResponseItem {
     },
     CustomToolCall {
         #[serde(skip_serializing)]
+        #[ts(optional = nullable)]
         id: Option<String>,
         #[serde(default, skip_serializing_if = "Option::is_none")]
+        #[ts(optional = nullable)]
         status: Option<String>,
 
         call_id: String,
@@ -114,8 +122,10 @@ pub enum ResponseItem {
     // }
     WebSearchCall {
         #[serde(skip_serializing)]
+        #[ts(optional = nullable)]
         id: Option<String>,
         #[serde(default, skip_serializing_if = "Option::is_none")]
+        #[ts(optional = nullable)]
         status: Option<String>,
         action: WebSearchAction,
     },
@@ -193,6 +203,7 @@ pub enum LocalShellAction {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct LocalShellExecAction {
     pub command: Vec<String>,
     pub timeout_ms: Option<u64>,
@@ -285,6 +296,7 @@ impl From<Vec<UserInput>> for ResponseInputItem {
 /// If the `name` of a `ResponseItem::FunctionCall` is either `container.exec`
 /// or shell`, the `arguments` field should deserialize to this struct.
 #[derive(Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct ShellToolCallParams {
     pub command: Vec<String>,
     pub workdir: Option<String>,
@@ -317,6 +329,7 @@ pub enum FunctionCallOutputContentItem {
 /// `content_items` with the structured form that the Responses/Chat
 /// Completions APIs understand.
 #[derive(Debug, Default, Clone, PartialEq, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct FunctionCallOutputPayload {
     pub content: String,
     #[serde(skip_serializing_if = "Option::is_none")]

codex-rs/protocol/src/parse_command.rs

@@ -18,11 +18,14 @@ pub enum ParsedCommand {
     },
     ListFiles {
         cmd: String,
+        #[ts(optional = nullable)]
         path: Option<String>,
     },
     Search {
         cmd: String,
+        #[ts(optional = nullable)]
         query: Option<String>,
+        #[ts(optional = nullable)]
         path: Option<String>,
     },
     Unknown {

codex-rs/protocol/src/plan_tool.rs

@@ -21,6 +21,7 @@ pub struct PlanItemArg {
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, TS)]
 #[serde(deny_unknown_fields)]
+#[ts(optional_fields = nullable)]
 pub struct UpdatePlanArgs {
     #[serde(default)]
     pub explanation: Option<String>,

codex-rs/protocol/src/protocol.rs

@@ -563,6 +563,7 @@ pub struct ItemCompletedEvent {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct ExitedReviewModeEvent {
     pub review_output: Option<ReviewOutputEvent>,
 }
@@ -575,11 +576,13 @@ pub struct ErrorEvent {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct TaskCompleteEvent {
     pub last_agent_message: Option<String>,
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct TaskStartedEvent {
     pub model_context_window: Option<i64>,
 }
@@ -599,9 +602,11 @@ pub struct TokenUsage {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct TokenUsageInfo {
     pub total_token_usage: TokenUsage,
     pub last_token_usage: TokenUsage,
+    #[ts(optional = nullable)]
     #[ts(type = "number | null")]
     pub model_context_window: Option<i64>,
 }
@@ -662,25 +667,30 @@ impl TokenUsageInfo {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct TokenCountEvent {
     pub info: Option<TokenUsageInfo>,
     pub rate_limits: Option<RateLimitSnapshot>,
 }
 
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct RateLimitSnapshot {
     pub primary: Option<RateLimitWindow>,
     pub secondary: Option<RateLimitWindow>,
 }
 
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct RateLimitWindow {
     /// Percentage (0-100) of the window that has been consumed.
     pub used_percent: f64,
     /// Rolling window duration, in minutes.
+    #[ts(optional = nullable)]
     #[ts(type = "number | null")]
     pub window_minutes: Option<i64>,
     /// Unix timestamp (seconds since epoch) when the window resets.
+    #[ts(optional = nullable)]
     #[ts(type = "number | null")]
     pub resets_at: Option<i64>,
 }
@@ -794,6 +804,7 @@ pub struct AgentMessageEvent {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct UserMessageEvent {
     pub message: String,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -829,6 +840,7 @@ pub struct AgentReasoningDeltaEvent {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS, PartialEq)]
+#[ts(optional_fields = nullable)]
 pub struct McpInvocation {
     /// Name of the MCP server as defined in the config.
     pub server: String,
@@ -947,6 +959,7 @@ pub enum SessionSource {
 }
 
 #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct SessionMeta {
     pub id: ConversationId,
     pub timestamp: String,
@@ -975,6 +988,7 @@ impl Default for SessionMeta {
 }
 
 #[derive(Serialize, Deserialize, Debug, Clone, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct SessionMetaLine {
     #[serde(flatten)]
     pub meta: SessionMeta,
@@ -1010,6 +1024,7 @@ impl From<CompactedItem> for ResponseItem {
 }
 
 #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct TurnContextItem {
     pub cwd: PathBuf,
     pub approval_policy: AskForApproval,
@@ -1028,6 +1043,7 @@ pub struct RolloutLine {
 }
 
 #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct GitInfo {
     /// Current commit hash (SHA)
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -1161,6 +1177,7 @@ pub struct BackgroundEventEvent {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct DeprecationNoticeEvent {
     /// Concise summary of what is deprecated.
     pub summary: String,
@@ -1170,12 +1187,14 @@ pub struct DeprecationNoticeEvent {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct UndoStartedEvent {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub message: Option<String>,
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct UndoCompletedEvent {
     pub success: bool,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -1220,6 +1239,7 @@ pub struct TurnDiffEvent {
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct GetHistoryEntryResponseEvent {
     pub offset: usize,
     pub log_id: u64,
@@ -1269,6 +1289,7 @@ pub struct ListCustomPromptsResponseEvent {
 }
 
 #[derive(Debug, Default, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[ts(optional_fields = nullable)]
 pub struct SessionConfiguredEvent {
     /// Name left as session_id instead of conversation_id for backwards compatibility.
     pub session_id: ConversationId,
@@ -1329,6 +1350,7 @@ pub enum FileChange {
     },
     Update {
         unified_diff: String,
+        #[ts(optional = nullable)]
         move_path: Option<PathBuf>,
     },
 }