diff --git a/codex-rs/app-server-protocol/src/protocol/v2/thread_data.rs b/codex-rs/app-server-protocol/src/protocol/v2/thread_data.rs index f0c518adf8..cfb52c7d1d 100644 --- a/codex-rs/app-server-protocol/src/protocol/v2/thread_data.rs +++ b/codex-rs/app-server-protocol/src/protocol/v2/thread_data.rs @@ -152,7 +152,9 @@ pub struct Thread { #[ts(export_to = "v2/")] pub struct Turn { pub id: String, - /// Thread items currently included in this turn payload. + /// Thread items currently included in this turn payload. `turn/completed` + /// includes terminal turn items when they are still available from the live + /// thread listener; other lightweight responses may leave this empty. pub items: Vec, /// Describes how much of `items` has been loaded for this turn. #[serde(default)] diff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.md index 2ceffc86fe..463f7aa520 100644 --- a/codex-rs/app-server/README.md +++ b/codex-rs/app-server/README.md @@ -1213,13 +1213,13 @@ Because audio is intentionally separate from `ThreadItem`, clients can opt out o The app-server streams JSON-RPC notifications while a turn is running. Each turn emits `turn/started` when it begins running and ends with `turn/completed` (final `turn` status). Token usage events stream separately via `thread/tokenUsage/updated`. Clients subscribe to the events they care about, rendering each item incrementally as updates arrive. The per-item lifecycle is always: `item/started` → zero or more item-specific deltas → `item/completed`. - `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/completed` — `{ turn }` where `turn.status` is `completed`, `interrupted`, or `failed`; failures carry `{ error: { message, codexErrorInfo?, additionalDetails? } }`. When the live listener still has the terminal turn snapshot, `turn.items` includes the completed turn items. - `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/plan/updated` — `{ turnId, explanation?, plan }` whenever the agent shares or changes its plan; each `plan` entry is `{ step, status }` with `status` in `pending`, `inProgress`, or `completed`. - `model/rerouted` — `{ threadId, turnId, fromModel, toModel, reason }` when the backend reroutes a request to a different model (for example, due to high-risk cyber safety checks). - `model/verification` — `{ threadId, turnId, verifications }` when the backend flags additional account verification, such as `trustedAccessForCyber`. -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. +`turn/started` still carries an empty `items` array. `turn/completed` includes the terminal turn items when app-server can recover them from the live thread listener, but clients should still treat `item/*` notifications as the canonical incremental stream. #### Items diff --git a/codex-rs/app-server/src/bespoke_event_handling.rs b/codex-rs/app-server/src/bespoke_event_handling.rs index efe6c69a32..901eb3df11 100644 --- a/codex-rs/app-server/src/bespoke_event_handling.rs +++ b/codex-rs/app-server/src/bespoke_event_handling.rs @@ -1291,20 +1291,31 @@ struct TurnCompletionMetadata { async fn emit_turn_completed_with_status( conversation_id: ThreadId, event_turn_id: String, + turn_snapshot: Option, turn_completion_metadata: TurnCompletionMetadata, outgoing: &ThreadScopedOutgoingMessageSender, ) { + let turn = turn_snapshot.unwrap_or_else(|| Turn { + id: event_turn_id.clone(), + items: vec![], + items_view: TurnItemsView::NotLoaded, + error: None, + status: turn_completion_metadata.status.clone(), + started_at: None, + completed_at: None, + duration_ms: None, + }); let notification = TurnCompletedNotification { thread_id: conversation_id.to_string(), turn: Turn { id: event_turn_id, - items: vec![], - items_view: TurnItemsView::NotLoaded, - error: turn_completion_metadata.error, + items: turn.items, + items_view: turn.items_view, + error: turn_completion_metadata.error.or(turn.error), status: turn_completion_metadata.status, - started_at: turn_completion_metadata.started_at, - completed_at: turn_completion_metadata.completed_at, - duration_ms: turn_completion_metadata.duration_ms, + started_at: turn_completion_metadata.started_at.or(turn.started_at), + completed_at: turn_completion_metadata.completed_at.or(turn.completed_at), + duration_ms: turn_completion_metadata.duration_ms.or(turn.duration_ms), }, }; outgoing @@ -1458,6 +1469,7 @@ pub(crate) async fn maybe_emit_hook_prompt_item_completed( .await; } +#[cfg(test)] async fn find_and_remove_turn_summary( _conversation_id: ThreadId, thread_state: &Arc>, @@ -1466,6 +1478,16 @@ async fn find_and_remove_turn_summary( std::mem::take(&mut state.turn_summary) } +async fn find_turn_completion_state( + event_turn_id: &str, + thread_state: &Arc>, +) -> (TurnSummary, Option) { + let mut state = thread_state.lock().await; + let turn_summary = std::mem::take(&mut state.turn_summary); + let turn_snapshot = state.completion_turn_snapshot(event_turn_id); + (turn_summary, turn_snapshot) +} + async fn handle_turn_complete( conversation_id: ThreadId, event_turn_id: String, @@ -1473,7 +1495,8 @@ async fn handle_turn_complete( outgoing: &ThreadScopedOutgoingMessageSender, thread_state: &Arc>, ) { - let turn_summary = find_and_remove_turn_summary(conversation_id, thread_state).await; + let (turn_summary, turn_snapshot) = + find_turn_completion_state(&event_turn_id, thread_state).await; let (status, error) = match turn_summary.last_error { Some(error) => (TurnStatus::Failed, Some(error)), @@ -1483,6 +1506,7 @@ async fn handle_turn_complete( emit_turn_completed_with_status( conversation_id, event_turn_id, + turn_snapshot, TurnCompletionMetadata { status, error, @@ -1502,11 +1526,13 @@ async fn handle_turn_interrupted( outgoing: &ThreadScopedOutgoingMessageSender, thread_state: &Arc>, ) { - let turn_summary = find_and_remove_turn_summary(conversation_id, thread_state).await; + let (turn_summary, turn_snapshot) = + find_turn_completion_state(&event_turn_id, thread_state).await; emit_turn_completed_with_status( conversation_id, event_turn_id, + turn_snapshot, TurnCompletionMetadata { status: TurnStatus::Interrupted, error: None, @@ -2094,6 +2120,7 @@ mod tests { use codex_protocol::items::HookPromptFragment; use codex_protocol::items::build_hook_prompt_message; use codex_protocol::models::FileSystemPermissions as CoreFileSystemPermissions; + use codex_protocol::models::MessagePhase; use codex_protocol::models::NetworkPermissions as CoreNetworkPermissions; use codex_protocol::permissions::FileSystemAccessMode; use codex_protocol::permissions::FileSystemPath; @@ -3306,6 +3333,14 @@ mod tests { collaboration_mode_kind: Default::default(), }), ); + state.track_current_turn_event( + &event_turn_id, + &EventMsg::AgentMessage(AgentMessageEvent { + message: "done".to_string(), + phase: Some(MessagePhase::FinalAnswer), + memory_citation: None, + }), + ); state.track_current_turn_event( &event_turn_id, &EventMsg::TurnComplete(turn_complete_event(&event_turn_id)), @@ -3324,14 +3359,24 @@ mod tests { let msg = recv_broadcast_message(&mut rx).await?; match msg { OutgoingMessage::AppServerNotification(ServerNotification::TurnCompleted(n)) => { - assert_eq!(n.turn.id, event_turn_id); - assert_eq!(n.turn.status, TurnStatus::Completed); - assert_eq!(n.turn.items_view, TurnItemsView::NotLoaded); - assert!(n.turn.items.is_empty()); - assert_eq!(n.turn.error, None); - assert_eq!(n.turn.started_at, Some(42)); - assert_eq!(n.turn.completed_at, Some(TEST_TURN_COMPLETED_AT)); - assert_eq!(n.turn.duration_ms, Some(TEST_TURN_DURATION_MS)); + assert_eq!( + n.turn, + Turn { + id: event_turn_id, + items: vec![ThreadItem::AgentMessage { + id: "item-1".to_string(), + text: "done".to_string(), + phase: Some(MessagePhase::FinalAnswer), + memory_citation: None, + }], + items_view: TurnItemsView::Full, + status: TurnStatus::Completed, + error: None, + started_at: Some(42), + completed_at: Some(TEST_TURN_COMPLETED_AT), + duration_ms: Some(TEST_TURN_DURATION_MS), + } + ); } other => bail!("unexpected message: {other:?}"), } diff --git a/codex-rs/app-server/src/thread_state.rs b/codex-rs/app-server/src/thread_state.rs index 7f864265b2..f4c17660d0 100644 --- a/codex-rs/app-server/src/thread_state.rs +++ b/codex-rs/app-server/src/thread_state.rs @@ -6,6 +6,7 @@ use codex_app_server_protocol::ThreadHistoryBuilder; use codex_app_server_protocol::ThreadSettings; use codex_app_server_protocol::Turn; use codex_app_server_protocol::TurnError; +use codex_app_server_protocol::TurnStatus; use codex_core::CodexThread; use codex_core::ThreadConfigSnapshot; use codex_file_watcher::WatchRegistration; @@ -80,6 +81,7 @@ pub(crate) struct ThreadState { last_thread_settings: Option, listener_command_tx: Option>, current_turn_history: ThreadHistoryBuilder, + last_terminal_turn: Option, listener_thread: Option>, watch_registration: WatchRegistration, } @@ -117,6 +119,7 @@ impl ThreadState { } self.listener_command_tx = None; self.current_turn_history.reset(); + self.last_terminal_turn = None; self.listener_thread = None; self.watch_registration = WatchRegistration::default(); } @@ -135,15 +138,27 @@ impl ThreadState { self.current_turn_history.active_turn_snapshot() } + pub(crate) fn completion_turn_snapshot(&self, turn_id: &str) -> Option { + self.active_turn_snapshot() + .filter(|turn| turn.id == turn_id && !matches!(turn.status, TurnStatus::InProgress)) + .or_else(|| { + self.last_terminal_turn + .clone() + .filter(|turn| turn.id == turn_id) + }) + } + pub(crate) fn track_current_turn_event(&mut self, event_turn_id: &str, event: &EventMsg) { if let EventMsg::TurnStarted(payload) = event { self.turn_summary.started_at = payload.started_at; + self.last_terminal_turn = None; } self.current_turn_history.handle_event(event); if matches!(event, EventMsg::TurnAborted(_) | EventMsg::TurnComplete(_)) && !self.current_turn_history.has_active_turn() { self.last_terminal_turn_id = Some(event_turn_id.to_string()); + self.last_terminal_turn = self.current_turn_history.active_turn_snapshot(); self.current_turn_history.reset(); } } diff --git a/codex-rs/exec/src/lib.rs b/codex-rs/exec/src/lib.rs index 84d7fb6ead..3dd8f01273 100644 --- a/codex-rs/exec/src/lib.rs +++ b/codex-rs/exec/src/lib.rs @@ -1245,9 +1245,9 @@ async fn maybe_backfill_turn_completed_items( notification: &mut ServerNotification, ) { // In-process delivery may drop non-terminal item notifications under backpressure while still - // guaranteeing `turn/completed`. Because app-server currently emits that completion with an - // empty `turn.items`, exec does one last `thread/read` here so human/json output can recover - // the final message and reconcile any still-running items before shutdown. + // guaranteeing `turn/completed`. App-server now tries to include terminal turn items directly + // on that notification, but exec keeps this bounded `thread/read` fallback for older or + // degraded paths that still arrive with an empty `turn.items`. if !should_backfill_turn_completed_items(thread_ephemeral, notification) { return; } diff --git a/codex-rs/exec/src/lib_tests.rs b/codex-rs/exec/src/lib_tests.rs index 66ceac127a..a40af17c93 100644 --- a/codex-rs/exec/src/lib_tests.rs +++ b/codex-rs/exec/src/lib_tests.rs @@ -390,6 +390,33 @@ fn should_backfill_turn_completed_items_skips_ephemeral_threads() { )); } +#[test] +fn should_backfill_turn_completed_items_skips_notifications_with_items() { + let notification = + ServerNotification::TurnCompleted(codex_app_server_protocol::TurnCompletedNotification { + thread_id: "thread-1".to_string(), + turn: codex_app_server_protocol::Turn { + id: "turn-1".to_string(), + items: vec![AppServerThreadItem::AgentMessage { + id: "msg-1".to_string(), + text: "finished".to_string(), + phase: None, + memory_citation: None, + }], + status: codex_app_server_protocol::TurnStatus::Completed, + error: None, + started_at: None, + completed_at: None, + duration_ms: None, + }, + }); + + assert!(!should_backfill_turn_completed_items( + /*thread_ephemeral*/ false, + ¬ification + )); +} + #[test] fn canceled_mcp_server_elicitation_response_uses_cancel_action() { let value = canceled_mcp_server_elicitation_response()