Rename plan step types and drop todo alias

codex-rs/app-server-protocol/src/protocol/common.rs

@@ -429,6 +429,9 @@ macro_rules! server_notification_definitions {
     (
         $(
             $(#[$variant_meta:meta])*
+            // Optional wire name and aliases:
+            // `Variant => "wire/name", aliases(["old/name"]) (Payload)`
+            // expands to serde rename + alias attributes on the enum variant.
             $variant:ident $(=> $wire:literal $(, aliases([$($alias:literal),* $(,)?]))? )? ( $payload:ty )
         ),* $(,)?
     ) => {
@@ -440,6 +443,8 @@ macro_rules! server_notification_definitions {
             $(
                 $(#[$variant_meta])*
                 $(
+                    // If a wire name is provided, emit serde/TS/strum renames
+                    // plus any legacy serde aliases for compatibility.
                     #[serde(rename = $wire)]
                     #[ts(rename = $wire)]
                     #[strum(serialize = $wire)]
@@ -589,7 +594,7 @@ server_notification_definitions! {
     TurnStarted => "turn/started" (v2::TurnStartedNotification),
     TurnCompleted => "turn/completed" (v2::TurnCompletedNotification),
     TurnDiffUpdated => "turn/diff/updated" (v2::TurnDiffUpdatedNotification),
-    TurnPlanUpdated => "turn/plan/updated", aliases(["turn/todo/updated", "turn/todos/updated"]) (v2::TurnPlanUpdatedNotification),
+    TurnPlanUpdated => "turn/plan/updated", aliases(["turn/todos/updated"]) (v2::TurnPlanUpdatedNotification),
     ItemStarted => "item/started" (v2::ItemStartedNotification),
     ItemCompleted => "item/completed" (v2::ItemCompletedNotification),
     /// This event is internal-only. Used by Codex Cloud.

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

@@ -2262,31 +2262,36 @@ pub struct TurnPlanUpdatedNotification {
     pub turn_id: String,
     pub explanation: Option<String>,
     #[serde(default)]
-    pub todo: Vec<TurnPlanStep>,
+    pub todo: Vec<TurnTodoStep>,
     #[serde(default)]
-    pub plan: Vec<TurnPlanStep>,
+    pub plan: Vec<TurnTodoStep>,
 }
 
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]
-/// Legacy plan-named todo step used by the todo list update notification.
-pub struct TurnPlanStep {
+/// Todo step used by the todo list update notification.
+pub struct TurnTodoStep {
     pub step: String,
-    pub status: TurnPlanStepStatus,
+    pub status: TurnTodoStepStatus,
 }
 
 #[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]
-/// Legacy plan-named todo status used by the todo list update notification.
-pub enum TurnPlanStepStatus {
+/// Todo status used by the todo list update notification.
+pub enum TurnTodoStepStatus {
     Pending,
     InProgress,
     Completed,
 }
 
-impl From<CoreTodoItemArg> for TurnPlanStep {
+#[deprecated(note = "use TurnTodoStep")]
+pub type TurnPlanStep = TurnTodoStep;
+#[deprecated(note = "use TurnTodoStepStatus")]
+pub type TurnPlanStepStatus = TurnTodoStepStatus;
+
+impl From<CoreTodoItemArg> for TurnTodoStep {
     fn from(value: CoreTodoItemArg) -> Self {
         Self {
             step: value.step,
@@ -2295,7 +2300,7 @@ impl From<CoreTodoItemArg> for TurnPlanStep {
     }
 }
 
-impl From<CoreTodoStatus> for TurnPlanStepStatus {
+impl From<CoreTodoStatus> for TurnTodoStepStatus {
     fn from(value: CoreTodoStatus) -> Self {
         match value {
             CoreTodoStatus::Pending => Self::Pending,

codex-rs/app-server/README.md

@@ -433,7 +433,7 @@ The app-server streams JSON-RPC notifications while a turn is running. Each turn
 - `turn/started` — `{ turn }` with the turn id, empty `items`, and `status: "inProgress"`.
 - `turn/completed` — `{ turn }` where `turn.status` is `completed`, `interrupted`, or `failed`; failures carry `{ error: { message, codexErrorInfo?, additionalDetails? } }`.
 - `turn/diff/updated` — `{ threadId, turnId, diff }` represents the up-to-date snapshot of the turn-level unified diff, emitted after every FileChange item. `diff` is the latest aggregated unified diff across every file change in the turn. UIs can render this to show the full "what changed" view without stitching individual `fileChange` items.
-- `turn/todos/updated` — `{ turnId, explanation?, todo, plan }` whenever the agent shares or changes its todo list; each entry is `{ step, status }` with `status` in `pending`, `inProgress`, or `completed`. `todo` is preferred and `plan` is a deprecated legacy alias; both are emitted for compatibility. Clients may also send/accept the legacy aliases `turn/plan/updated` and `turn/todo/updated`. (The plan-named event and field are legacy and are unrelated to Plan mode.)
+- `turn/todos/updated` — `{ turnId, explanation?, todo, plan }` whenever the agent shares or changes its todo list; each entry is `{ step, status }` with `status` in `pending`, `inProgress`, or `completed`. `todo` is preferred and `plan` is a deprecated legacy alias; both are emitted for compatibility. Clients may also send/accept the legacy alias `turn/plan/updated`. (The plan-named event and field are legacy and are unrelated to Plan mode.)
 
 Today both notifications carry an empty `items` array even when item events were streamed; rely on `item/*` notifications for the canonical item list until this is fixed.
 

codex-rs/app-server/src/bespoke_event_handling.rs

@@ -64,9 +64,9 @@ use codex_app_server_protocol::TurnCompletedNotification;
 use codex_app_server_protocol::TurnDiffUpdatedNotification;
 use codex_app_server_protocol::TurnError;
 use codex_app_server_protocol::TurnInterruptResponse;
-use codex_app_server_protocol::TurnPlanStep as TurnTodoStep;
 use codex_app_server_protocol::TurnPlanUpdatedNotification as TurnTodoUpdatedNotification;
 use codex_app_server_protocol::TurnStatus;
+use codex_app_server_protocol::TurnTodoStep;
 use codex_app_server_protocol::build_turns_from_event_msgs;
 use codex_core::CodexThread;
 use codex_core::parse_command::shlex_join;
@@ -1805,7 +1805,7 @@ mod tests {
     use anyhow::Result;
     use anyhow::anyhow;
     use anyhow::bail;
-    use codex_app_server_protocol::TurnPlanStepStatus as TurnTodoStepStatus;
+    use codex_app_server_protocol::TurnTodoStepStatus;
     use codex_core::protocol::CreditsSnapshot;
     use codex_core::protocol::McpInvocation;
     use codex_core::protocol::RateLimitSnapshot;