[Question] Clarify TurnStartedEvent.model_context_window optionality

[hobostay]

Summary

There's a TODO comment in protocol.rs indicating that model_context_window should not be optional, but it's currently marked as Option<i64>. I'd like to understand the design intent and whether this should be addressed.

Location

File: codex-rs/protocol/src/protocol.rs
Line: 1157-1158

#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
pub struct TurnStartedEvent {
    // TODO(aibrahim): make this not optional
    pub model_context_window: Option<i64>,
    #[serde(default)]
    pub collaboration_mode_kind: ModeKind,
}

Questions for the Team

1. What is the current behavior when model_context_window is None?

   • Does the code have a fallback/default value?
   • Does it cause issues for clients that expect this value?

2. What prevents making this field required?

   • Are there legacy clients that don't provide this value?
   • Are there certain models where this value is unknown/unavailable?

3. What is the timeline for addressing this TODO?

   • Is this planned for a specific version?
   • Would a migration path be needed (e.g., default value + deprecation period)?

Potential Approaches

Option 1: Make it required (Breaking Change)

pub model_context_window: i64,  // Always present

• Pros: Clear API contract, no handling of None case needed
• Cons: Breaking change, requires all clients to provide this value

Option 2: Provide sensible default

#[serde(default = "default_context_window")]
pub model_context_window: i64,

• Pros: Backward compatible, always has a value
• Cons: May hide cases where the value should be explicitly set

Option 3: Keep optional with clear documentation

/// The model's context window size in tokens.
/// Will be None for older sessions or models where this information is not available.
pub model_context_window: Option<i64>,

• Pros: Backward compatible, explicit about uncertainty
• Cons: Requires clients to handle None case

Impact

• Priority: Medium (affects API clarity and client implementation)
• Type: API Design / Technical Debt

Related Code

This TODO appears in multiple locations in the codebase, suggesting this may be a known architectural decision point:

• codex-rs/protocol/src/protocol.rs
• codex-rs/app-server-protocol/src/protocol/v2.rs

---

Note: I'm aware that external PRs are by invitation only. I'm submitting this issue to seek clarification and contribute analysis as outlined in the contributing guidelines.