Lightweight coding agent that runs in your terminal
Rust
Gate new turn submissions on host shutdown admission (#43943)
Eric Traut7c098d87418a
diff --git a/codex-rs/app-server/src/error_code.rs b/codex-rs/app-server/src/error_code.rsindex 48e401f7bc..b5b44c0274 100644--- a/codex-rs/app-server/src/error_code.rs+++ b/codex-rs/app-server/src/error_code.rs@@ -7,6 +7,10 @@ pub(crate) const INTERNAL_ERROR_CODE: i64 = -32603;pub(crate) const OVERLOADED_ERROR_CODE: i64 = -32001;pub const INPUT_TOO_LARGE_ERROR_CODE: &str = "input_too_large";+pub(crate) fn server_draining_error() -> JSONRPCErrorError {+ invalid_request("Server is draining; retry after reconnecting")+}+pub(crate) fn invalid_request(message: impl Into<String>) -> JSONRPCErrorError {error(INVALID_REQUEST_ERROR_CODE, message)}diff --git a/codex-rs/app-server/src/request_processors/thread_queue_processor.rs b/codex-rs/app-server/src/request_processors/thread_queue_processor.rsindex 6fe5336dc8..a561272e3f 100644--- a/codex-rs/app-server/src/request_processors/thread_queue_processor.rs+++ b/codex-rs/app-server/src/request_processors/thread_queue_processor.rs@@ -198,6 +198,9 @@ impl ThreadQueueRequestProcessor {.map_err(queue_error)?;let turn_id = match submission {StartIfIdleSubmission::Started { turn_id } => turn_id,+ StartIfIdleSubmission::NotSubmitted {+ reason: NotSubmittedReason::ServerDraining,+ } => return Err(crate::error_code::server_draining_error()),StartIfIdleSubmission::NotSubmitted {reason: NotSubmittedReason::NotIdle | NotSubmittedReason::PendingTriggerTurn,} => {diff --git a/codex-rs/app-server/src/request_processors/turn_processor.rs b/codex-rs/app-server/src/request_processors/turn_processor.rsindex 2beaa87033..b939a0f3f4 100644--- a/codex-rs/app-server/src/request_processors/turn_processor.rs+++ b/codex-rs/app-server/src/request_processors/turn_processor.rs@@ -667,7 +667,11 @@ impl TurnRequestProcessor {TurnInputSubmission::Started { turn_id } => (turn_id, true),TurnInputSubmission::Steered { turn_id } => (turn_id, false),TurnInputSubmission::NotSubmitted { reason } => {- let error = internal_error(format!("failed to submit turn input: {reason:?}"));+ let error = if reason == NotSubmittedReason::ServerDraining {+ crate::error_code::server_draining_error()+ } else {+ internal_error(format!("failed to submit turn input: {reason:?}"))+ };self.track_error_response(&request_id, &error, /*error_type*/ None);return Err(error);}@@ -1067,6 +1071,9 @@ impl TurnRequestProcessor {SteerSubmission::Steered { turn_id } => turn_id,SteerSubmission::NotSubmitted { reason } => {let (message, data, error_type) = match reason {+ NotSubmittedReason::ServerDraining => {+ return Err(crate::error_code::server_draining_error());+ }NotSubmittedReason::NoActiveTurn | NotSubmittedReason::NotIdle => ("no active turn to steer".to_string(),None,diff --git a/codex-rs/core/src/realtime_conversation.rs b/codex-rs/core/src/realtime_conversation.rsindex 63f59d5408..5ef019d75e 100644--- a/codex-rs/core/src/realtime_conversation.rs+++ b/codex-rs/core/src/realtime_conversation.rs@@ -144,13 +144,14 @@ impl RealtimeHandoffAdmission {}}- async fn route(&self, session: &Arc<Session>, text: String) {+ async fn route(&self, session: &Arc<Session>, text: String) -> Result<(), &'static str> {let Ok(_permit) = self.gate.acquire().await else {- return;+ return Ok(());};if !self.retired.load(Ordering::Acquire) {- session.route_realtime_text_input(text).await;+ session.route_realtime_text_input(text).await?;}+ Ok(())}async fn retire(&self) {@@ -1645,6 +1646,7 @@ async fn handle_start_inner(msg,};let mut end = RealtimeConversationEnd::TransportClosed;+ let mut handoff_error = None;// Drain already-parsed events so a queued handoff is routed before the final tail.while let Ok(event) = events_rx.recv().await {match &event {@@ -1667,7 +1669,7 @@ async fn handle_start_inner(if let Some(text) = maybe_routed_text {// The routed text can contain spoken prompts or workspace secrets.debug!("[realtime-text] realtime conversation text output");- route_handoffs.route(&sess_clone, text).await;+ handoff_error = route_handoffs.route(&sess_clone, text).await.err();}sess_clone.send_event_raw(ev(EventMsg::RealtimeConversationRealtime(@@ -1676,9 +1678,24 @@ async fn handle_start_inner(},))).await;+ if handoff_error.is_some() {+ break;+ }+ }+ if handoff_error.is_none()+ && let Ok(text) = transcript_tail_rx.recv().await+ {+ handoff_error = route_handoffs.route(&sess_clone, text).await.err();}- if let Ok(text) = transcript_tail_rx.recv().await {- route_handoffs.route(&sess_clone, text).await;+ if let Some(error) = handoff_error {+ end = RealtimeConversationEnd::Error;+ sess_clone+ .send_event_raw(ev(EventMsg::RealtimeConversationRealtime(+ RealtimeConversationRealtimeEvent {+ payload: RealtimeEvent::Error(error.to_string()),+ },+ )))+ .await;}if fanout_realtime_active.swap(false, Ordering::Relaxed) {match end {diff --git a/codex-rs/core/src/session/turn_input.rs b/codex-rs/core/src/session/turn_input.rsindex b064e24566..d08dcd62a9 100644--- a/codex-rs/core/src/session/turn_input.rs+++ b/codex-rs/core/src/session/turn_input.rs@@ -7,6 +7,9 @@//!//! Persistent thread settings apply on Started and Steered. Turn start//! options only apply on Started.+//! Host shutdown admission is checked before reserving or starting a new turn.+//! Parent-delegated subagent input bypasses drain; automatic starts remain gated.+//! Realtime drain refusals are returned to the fanout for ordered session teardown.use super::TurnInput;use super::session::Session;@@ -28,6 +31,8 @@ use codex_protocol::protocol::ErrorEvent;use codex_protocol::protocol::Event;use codex_protocol::protocol::EventMsg;use codex_protocol::protocol::NonSteerableTurnKind;+use codex_protocol::protocol::SessionSource;+use codex_protocol::protocol::SubAgentSource;use codex_protocol::protocol::ThreadSettingsOverrides;use codex_protocol::turn_input::NotSubmittedReason;use codex_protocol::turn_input::TurnInput as SubmittedTurnInput;@@ -276,6 +281,28 @@ async fn start_or_steer(Ok(TurnInputSubmission::Steered { turn_id })}Err(NotSubmittedReason::NoActiveTurn) => {+ // MAv1 sends explicit input to spawned agents as part of an existing+ // parent's work. Client RPCs are gated separately by the host.+ let is_delegated_input = settings.start_options.parent_turn_id.is_some()+ && matches!(+ session+ .state+ .lock()+ .await+ .session_configuration+ .session_source,+ SessionSource::SubAgent(SubAgentSource::ThreadSpawn { .. })+ );+ let _admission = if is_delegated_input {+ None+ } else {+ let Some(admission) = session.services.extensions.admit_turn_start() else {+ return Ok(TurnInputSubmission::NotSubmitted {+ reason: NotSubmittedReason::ServerDraining,+ });+ };+ Some(admission)+ };let Some(turn_context) = settings.apply_started(session, submission_id.clone(), TurnStartKind::User).await?@@ -337,6 +364,27 @@ async fn start_if_idle(});}+ let _admission = session.services.extensions.admit_turn_start();+ // A one-shot review delegate completes its already-running parent's work.+ // Its explicit input carries parent lineage; automatic starts do not qualify.+ if _admission.is_none()+ && !(kind == TurnStartKind::User+ && start.parent_turn_id.is_some()+ && matches!(+ session+ .state+ .lock()+ .await+ .session_configuration+ .session_source,+ SessionSource::SubAgent(SubAgentSource::Review)+ ))+ {+ return Ok(TurnInputSubmission::NotSubmitted {+ reason: NotSubmittedReason::ServerDraining,+ });+ }+let turn_state = {let mut active_turn = session.active_turn.lock().await;if active_turn.is_some() {@@ -460,7 +508,10 @@ async fn steer(}impl Session {- pub(crate) async fn route_realtime_text_input(self: &Arc<Self>, text: String) {+ pub(crate) async fn route_realtime_text_input(+ self: &Arc<Self>,+ text: String,+ ) -> Result<(), &'static str> {let submission_id = Uuid::now_v7().to_string();let submission = handle(self,@@ -478,6 +529,11 @@ impl Session {.await;match submission {Ok(TurnInputSubmission::Started { .. } | TurnInputSubmission::Steered { .. }) => {}+ Ok(TurnInputSubmission::NotSubmitted {+ reason: NotSubmittedReason::ServerDraining,+ }) => {+ return Err("Server is draining; retry the turn after reconnecting");+ }Ok(TurnInputSubmission::NotSubmitted { reason }) => {self.send_event_raw(Event {id: submission_id,@@ -497,6 +553,7 @@ impl Session {.await;}}+ Ok(())}async fn clear_reserved_idle_turn(&self, turn_state: &Arc<tokio::sync::Mutex<TurnState>>) {diff --git a/codex-rs/core/tests/suite/turn_input_submission.rs b/codex-rs/core/tests/suite/turn_input_submission.rsindex 837d7b2add..5a4c2ce586 100644--- a/codex-rs/core/tests/suite/turn_input_submission.rs+++ b/codex-rs/core/tests/suite/turn_input_submission.rs@@ -1,17 +1,25 @@use codex_core::NotSubmittedReason;use codex_core::RecoverTurnRequest;use codex_core::StartIfIdleSubmission;+use codex_core::StartThreadOptions;use codex_core::SteerSubmission;use codex_core::TurnInput;use codex_core::TurnInputRequest;use codex_core::TurnInputSubmission;use codex_core::TurnStartOptions;use codex_core::config::Constrained;+use codex_extension_api::ExtensionRegistryBuilder;+use codex_extension_api::TurnStartAdmission;+use codex_protocol::AgentPath;use codex_protocol::config_types::CollaborationMode;use codex_protocol::config_types::ModeKind;use codex_protocol::config_types::Settings;use codex_protocol::protocol::AskForApproval;use codex_protocol::protocol::EventMsg;+use codex_protocol::protocol::InterAgentCommunication;+use codex_protocol::protocol::Op;+use codex_protocol::protocol::SessionSource;+use codex_protocol::protocol::SubAgentSource;use codex_protocol::protocol::ThreadSettingsOverrides;use codex_protocol::protocol::TurnEnvironmentSelections;use codex_protocol::user_input::UserInput;@@ -27,12 +35,325 @@ use core_test_support::wait_for_event;use pretty_assertions::assert_eq;use serde_json::Value;use std::sync::Arc;+use std::sync::atomic::AtomicBool;+use std::sync::atomic::Ordering;use std::time::Duration;use test_case::test_case;use tokio::sync::Barrier;use tokio::sync::oneshot;use tokio::time::timeout;+#[derive(Debug)]+struct TestAdmission(AtomicBool);++impl TurnStartAdmission for TestAdmission {+ fn admit_turn_start(&self) -> Option<Box<dyn Send>> {+ if self.0.load(Ordering::SeqCst) {+ None+ } else {+ Some(Box::new(()))+ }+ }+}++#[tokio::test]+async fn host_drain_rejects_turn_start_paths_without_recording_input() -> anyhow::Result<()> {+ let server = responses::start_mock_server().await;+ let response = responses::mount_sse_once(&server, responses::sse_completed("allowed")).await;+ let admission = Arc::new(TestAdmission(AtomicBool::new(true)));+ let mut extensions = ExtensionRegistryBuilder::new();+ extensions.turn_start_admission(admission.clone());+ let test = test_codex()+ .with_extensions(Arc::new(extensions.build()))+ .build_with_auto_env(&server)+ .await?;+ assert_eq!(+ test.codex+ .start_or_steer_turn(user_message_request("rejected direct input"))+ .await?,+ TurnInputSubmission::NotSubmitted {+ reason: NotSubmittedReason::ServerDraining+ },+ );+ for request in [+ user_message_request("rejected queued input"),+ TurnInputRequest::user_input(Vec::new()),+ TurnInputRequest::new(TurnInput::ResponseItem(responses::user_message_item(+ "rejected continuation",+ ))),+ ] {+ assert_eq!(+ test.codex.start_turn_if_idle(request).await?,+ StartIfIdleSubmission::NotSubmitted {+ reason: NotSubmittedReason::ServerDraining+ },+ );+ }+ assert!(response.requests().is_empty());+ admission.0.store(false, Ordering::SeqCst);+ test.codex+ .start_turn_if_idle(user_message_request("allowed input"))+ .await?;+ wait_for_event(&test.codex, |event| {+ matches!(event, EventMsg::TurnComplete(_))+ })+ .await;+ let request = response.single_request();+ assert!(request.body_contains_text("allowed input"));+ assert!(!request.body_contains_text("rejected direct input"));+ assert!(!request.body_contains_text("rejected queued input"));+ assert!(!request.body_contains_text("rejected continuation"));+ Ok(())+}++#[tokio::test]+async fn host_drain_allows_spawned_agent_input_but_not_automatic_work() -> anyhow::Result<()> {+ let server = responses::start_mock_server().await;+ let response = responses::mount_sse_once(&server, responses::sse_completed("child")).await;+ let mut extensions = ExtensionRegistryBuilder::new();+ extensions.turn_start_admission(Arc::new(TestAdmission(AtomicBool::new(true))));+ let test = test_codex()+ .with_extensions(Arc::new(extensions.build()))+ .build_with_auto_env(&server)+ .await?;+ let child = test+ .thread_manager+ .start_thread(StartThreadOptions {+ session_source: Some(SessionSource::SubAgent(SubAgentSource::ThreadSpawn {+ parent_thread_id: test.session_configured.thread_id,+ depth: 1,+ agent_path: None,+ agent_nickname: None,+ agent_role: None,+ })),+ environments: Some(test.codex.environment_selections().await),+ ..StartThreadOptions::new(test.config.clone())+ })+ .await?+ .thread;+ for request in [+ user_message_request("queued child input"),+ TurnInputRequest::user_input(Vec::new()),+ ] {+ assert_eq!(+ child.start_turn_if_idle(request).await?,+ StartIfIdleSubmission::NotSubmitted {+ reason: NotSubmittedReason::ServerDraining+ },+ );+ }+ assert_eq!(+ child+ .start_or_steer_turn(user_message_request("external child input"))+ .await?,+ TurnInputSubmission::NotSubmitted {+ reason: NotSubmittedReason::ServerDraining+ },+ );+ assert!(matches!(+ child+ .start_or_steer_turn(user_message_request("delegated input").on_start(+ TurnStartOptions {+ parent_turn_id: Some("parent-turn".to_string()),+ ..Default::default()+ }+ ))+ .await?,+ TurnInputSubmission::Started { .. }+ ));+ wait_for_event(&child, |event| matches!(event, EventMsg::TurnComplete(_))).await;+ assert!(+ response+ .single_request()+ .body_contains_text("delegated input")+ );+ Ok(())+}++#[tokio::test]+async fn host_drain_allows_running_review_to_finish_its_delegate() -> anyhow::Result<()> {+ use codex_protocol::protocol::ReviewOutputEvent;+ use codex_protocol::protocol::ReviewRequest;+ use codex_protocol::protocol::ReviewTarget;++ let server = responses::start_mock_server().await;+ let expected = ReviewOutputEvent {+ overall_explanation: "review completed during drain".to_string(),+ ..Default::default()+ };+ let response = responses::mount_sse_once(+ &server,+ responses::sse(vec![+ ev_response_created("review"),+ responses::ev_assistant_message("result", &serde_json::to_string(&expected)?),+ ev_completed("review"),+ ]),+ )+ .await;+ let mut extensions = ExtensionRegistryBuilder::new();+ extensions.turn_start_admission(Arc::new(TestAdmission(AtomicBool::new(true))));+ let test = test_codex()+ .with_extensions(Arc::new(extensions.build()))+ .build_with_auto_env(&server)+ .await?;+ // The host already admitted the parent review; only its child start hits Core admission.+ test.codex+ .submit(Op::Review {+ review_request: ReviewRequest {+ target: ReviewTarget::Custom {+ instructions: "review these changes".to_string(),+ },+ user_facing_hint: None,+ },+ })+ .await?;+ let event = wait_for_event(&test.codex, |event| {+ matches!(event, EventMsg::ExitedReviewMode(_))+ })+ .await;+ let EventMsg::ExitedReviewMode(event) = event else {+ unreachable!()+ };+ assert_eq!(event.review_output, Some(expected));+ response.single_request();+ Ok(())+}++#[tokio::test]+async fn host_drain_closes_realtime_after_handoff_error() -> anyhow::Result<()> {+ use codex_protocol::protocol::ConversationStartParams;+ use codex_protocol::protocol::RealtimeConversationClosedEvent;+ use codex_protocol::protocol::RealtimeConversationRealtimeEvent;+ use codex_protocol::protocol::RealtimeEvent;+ use codex_protocol::protocol::RealtimeHandoffRequested;+ use codex_protocol::protocol::RealtimeTranscriptEntry;++ let server = responses::start_mock_server().await;+ let response = responses::mount_sse_once(&server, responses::sse_completed("unexpected")).await;+ let realtime = responses::start_websocket_server(vec![vec![vec![+ serde_json::json!({+ "type": "session.updated",+ "session": { "id": "draining", "instructions": "backend prompt" }+ }),+ serde_json::json!({+ "type": "conversation.handoff.requested",+ "handoff_id": "rejected",+ "item_id": "rejected",+ "input_transcript": "must not start"+ }),+ ]]])+ .await;+ let mut extensions = ExtensionRegistryBuilder::new();+ extensions.turn_start_admission(Arc::new(TestAdmission(AtomicBool::new(true))));+ let test = test_codex()+ .with_extensions(Arc::new(extensions.build()))+ .with_config({+ let realtime_url = realtime.uri().to_string();+ move |config| {+ config.experimental_realtime_ws_base_url = Some(realtime_url);+ config.realtime.version = codex_config::config_toml::RealtimeWsVersion::V1;+ }+ })+ .build_with_auto_env(&server)+ .await?;+ test.codex+ .submit(Op::RealtimeConversationStart(ConversationStartParams {+ client_managed_handoffs: false,+ delegation_ack_filler: None,+ flush_transcript_tail_on_session_end: false,+ codex_responses_as_items: false,+ codex_response_item_prefix: None,+ codex_response_handoff_mode:+ codex_protocol::protocol::CodexResponseHandoffMode::Thinking,+ codex_response_handoff_channel_prefixes: None,+ model: None,+ output_modality: codex_protocol::protocol::RealtimeOutputModality::Audio,+ include_startup_context: false,+ initial_items: Vec::new(),+ realtime_start_instructions: None,+ realtime_end_instructions: None,+ prompt: Some(Some("backend prompt".to_string())),+ realtime_session_id: None,+ transport: None,+ version: None,+ voice: None,+ }))+ .await?;+ for expected in [+ EventMsg::RealtimeConversationRealtime(RealtimeConversationRealtimeEvent {+ payload: RealtimeEvent::HandoffRequested(RealtimeHandoffRequested {+ handoff_id: "rejected".to_string(),+ item_id: "rejected".to_string(),+ input_transcript: "must not start".to_string(),+ active_transcript: vec![RealtimeTranscriptEntry {+ role: "user".to_string(),+ text: "must not start".to_string(),+ }],+ }),+ }),+ EventMsg::RealtimeConversationRealtime(RealtimeConversationRealtimeEvent {+ payload: RealtimeEvent::Error(+ "Server is draining; retry the turn after reconnecting".to_string(),+ ),+ }),+ EventMsg::RealtimeConversationClosed(RealtimeConversationClosedEvent {+ reason: Some("error".to_string()),+ }),+ ] {+ let event = wait_for_event(&test.codex, |event| match event {+ EventMsg::RealtimeConversationRealtime(RealtimeConversationRealtimeEvent {+ payload: RealtimeEvent::HandoffRequested(_) | RealtimeEvent::Error(_),+ })+ | EventMsg::RealtimeConversationClosed(_) => true,+ EventMsg::TurnStarted(_) | EventMsg::Error(_) => panic!("unexpected event: {event:?}"),+ _ => false,+ })+ .await;+ assert_eq!(+ serde_json::to_value(event)?,+ serde_json::to_value(expected)?+ );+ }+ assert!(response.requests().is_empty());+ realtime.shutdown().await;+ Ok(())+}++#[tokio::test]+async fn host_drain_allows_mailbox_work_to_start_a_turn() -> anyhow::Result<()> {+ let server = responses::start_mock_server().await;+ let response = responses::mount_sse_once(&server, responses::sse_completed("mailbox")).await;+ let mut extensions = ExtensionRegistryBuilder::new();+ extensions.turn_start_admission(Arc::new(TestAdmission(AtomicBool::new(true))));+ let test = test_codex()+ .with_extensions(Arc::new(extensions.build()))+ .build_with_auto_env(&server)+ .await?;+ // Mailbox input is memory-only and must be processed before the host exits.+ test.codex+ .submit(Op::InterAgentCommunication {+ communication: InterAgentCommunication::new(+ AgentPath::try_from("/root/worker").expect("valid agent path"),+ AgentPath::root(),+ Vec::new(),+ "mail while draining".to_string(),+ /*trigger_turn*/ true,+ ),+ start_options: Default::default(),+ })+ .await?;+ wait_for_event(&test.codex, |event| {+ matches!(event, EventMsg::TurnComplete(_))+ })+ .await;+ assert!(+ response+ .single_request()+ .body_contains_text("mail while draining")+ );+ Ok(())+}+fn user_message_request(text: &str) -> TurnInputRequest {TurnInputRequest::user_input(vec![UserInput::Text {text: text.to_string(),diff --git a/codex-rs/ext/extension-api/src/lib.rs b/codex-rs/ext/extension-api/src/lib.rsindex 84f2ac0b8e..f92d36bc00 100644--- a/codex-rs/ext/extension-api/src/lib.rs+++ b/codex-rs/ext/extension-api/src/lib.rs@@ -2,6 +2,7 @@ mod capabilities;mod contributors;mod registry;mod state;+mod turn_admission;mod user_instructions;pub use capabilities::AgentSpawnFuture;@@ -97,6 +98,7 @@ pub use registry::ExtensionRegistryBuilder;pub use registry::empty_extension_registry;pub use state::ExtensionData;pub use state::ExtensionDataInit;+pub use turn_admission::TurnStartAdmission;pub use user_instructions::Instructions;pub use user_instructions::LoadUserInstructionsFuture;pub use user_instructions::LoadedUserInstructions;diff --git a/codex-rs/ext/extension-api/src/registry.rs b/codex-rs/ext/extension-api/src/registry.rsindex e4aeba9b5e..dddd8b8ab0 100644--- a/codex-rs/ext/extension-api/src/registry.rs+++ b/codex-rs/ext/extension-api/src/registry.rs@@ -14,6 +14,7 @@ use crate::ToolLifecycleContributor;use crate::TurnInputContributor;use crate::TurnItemContributor;use crate::TurnLifecycleContributor;+use crate::TurnStartAdmission;/// Mutable registry used while hosts register typed runtime contributions.pub struct ExtensionRegistryBuilder<C: Sync> {@@ -25,6 +26,7 @@ impl<C: Sync> Default for ExtensionRegistryBuilder<C> {Self {registry: ExtensionRegistry {event_sink: Arc::new(NoopExtensionEventSink),+ turn_start_admission: None,thread_lifecycle_contributors: Vec::new(),turn_lifecycle_contributors: Vec::new(),config_contributors: Vec::new(),@@ -60,6 +62,11 @@ impl<C: Sync> ExtensionRegistryBuilder<C> {Arc::clone(&self.registry.event_sink)}+ /// Installs the host gate for turn-input submissions that start a new turn.+ pub fn turn_start_admission(&mut self, admission: Arc<dyn TurnStartAdmission>) {+ self.registry.turn_start_admission = Some(admission);+ }+/// Registers one approval-review contributor.pub fn approval_review_contributor(&mut self, contributor: Arc<dyn ApprovalReviewContributor>) {self.registry.approval_review_contributors.push(contributor);@@ -139,6 +146,7 @@ impl<C: Sync> ExtensionRegistryBuilder<C> {/// Immutable typed registry produced after extensions are installed.pub struct ExtensionRegistry<C: Sync> {event_sink: Arc<dyn ExtensionEventSink>,+ turn_start_admission: Option<Arc<dyn TurnStartAdmission>>,thread_lifecycle_contributors: Vec<Arc<dyn ThreadLifecycleContributor<C>>>,turn_lifecycle_contributors: Vec<Arc<dyn TurnLifecycleContributor>>,config_contributors: Vec<Arc<dyn ConfigContributor<C>>>,@@ -154,6 +162,15 @@ pub struct ExtensionRegistry<C: Sync> {}impl<C: Sync> ExtensionRegistry<C> {+ /// Acquires the host's turn-start permit, or an empty permit for ungated hosts.+ /// A missing permit rejects the start before Core consumes pending input.+ pub fn admit_turn_start(&self) -> Option<Box<dyn Send>> {+ match &self.turn_start_admission {+ Some(admission) => admission.admit_turn_start(),+ None => Some(Box::new(())),+ }+ }+/// Returns the host event sink retained by this registry.pub fn event_sink(&self) -> Arc<dyn ExtensionEventSink> {Arc::clone(&self.event_sink)diff --git a/codex-rs/ext/extension-api/src/turn_admission.rs b/codex-rs/ext/extension-api/src/turn_admission.rsnew file mode 100644index 0000000000..9d5de89fc7--- /dev/null+++ b/codex-rs/ext/extension-api/src/turn_admission.rs@@ -0,0 +1,12 @@+//! Lets Core turn-input submissions participate in a host's shutdown drain.++/// A host-provided gate checked before Core starts a turn-input submission.+///+/// Implementations return a permit for work admitted before shutdown and+/// Core retains it through submission. `None` skips the start without consuming+/// pending input. Steering an existing turn does not acquire a new permit.+/// Memory-only mailbox wakeups and parent-delegated subagent input bypass this+/// gate so delegated work can finish before exit. Automatic starts remain gated.+pub trait TurnStartAdmission: std::fmt::Debug + Send + Sync {+ fn admit_turn_start(&self) -> Option<Box<dyn Send>>;+}diff --git a/codex-rs/ext/queue/tests/queue_service.rs b/codex-rs/ext/queue/tests/queue_service.rsindex 875dae3292..a597583d39 100644--- a/codex-rs/ext/queue/tests/queue_service.rs+++ b/codex-rs/ext/queue/tests/queue_service.rs@@ -3,6 +3,8 @@ use std::sync::Arc;use std::sync::Mutex;use std::sync::OnceLock;use std::sync::Weak;+use std::sync::atomic::AtomicBool;+use std::sync::atomic::Ordering;use std::time::Duration;use anyhow::Context;@@ -23,6 +25,7 @@ use codex_extension_api::ThreadIdleCause;use codex_extension_api::ThreadIdleInput;use codex_extension_api::ThreadLifecycleContributor;use codex_extension_api::ThreadResumeInput;+use codex_extension_api::TurnStartAdmission;use codex_protocol::ThreadId;use codex_protocol::items::TurnItem;use codex_protocol::models::ImageDetail;@@ -59,6 +62,19 @@ const TINY_PNG_BYTES: &[u8] = &[];const TINY_PNG_DATA_URL: &str = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR4nGNgAAIAAAUAAXpeqz8AAAAASUVORK5CYII=";+#[derive(Debug)]+struct TestAdmission(AtomicBool);++impl TurnStartAdmission for TestAdmission {+ fn admit_turn_start(&self) -> Option<Box<dyn Send>> {+ if self.0.load(Ordering::SeqCst) {+ None+ } else {+ Some(Box::new(()))+ }+ }+}+#[derive(Default)]struct RecordingEventSink {events: Mutex<Vec<Event>>,@@ -228,6 +244,49 @@ async fn emit_idle_with_cause(.await;}+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn drain_leaves_persisted_queued_message_for_a_later_start() -> anyhow::Result<()> {+ let server = start_mock_server().await;+ let response =+ responses::mount_sse_once(&server, responses::sse_completed("queued-turn")).await;+ let admission = Arc::new(TestAdmission(AtomicBool::new(true)));+ let mut extensions = ExtensionRegistryBuilder::new();+ extensions.turn_start_admission(admission.clone());+ let test = test_codex()+ .with_extensions(Arc::new(extensions.build()))+ .build_with_auto_env(&server)+ .await?;+ let thread_id = test.session_configured.thread_id;+ let queue = loaded_thread_queue(&test)?;+ let staged = QueuedItemService::new(+ Arc::clone(&queue),+ Weak::new(),+ Arc::new(NoopExtensionEventSink),+ );+ let item = staged+ .enqueue(thread_id, user_input("queued after drain"))+ .await?;+ let service = QueuedItemService::new(+ Arc::clone(&queue),+ Arc::downgrade(&test.thread_manager),+ Arc::new(NoopExtensionEventSink),+ );++ emit_idle(&service, thread_id).await;+ assert_eq!(vec![item.clone()], service.list(thread_id).await?);+ assert!(response.requests().is_empty());++ admission.0.store(false, Ordering::SeqCst);+ emit_idle(&service, thread_id).await;+ wait_for_event_match(test.codex.as_ref(), |event| {+ matches!(event, EventMsg::TurnComplete(_)).then_some(())+ })+ .await;+ assert!(service.list(thread_id).await?.is_empty());+ assert_eq!(1, response.requests().len());+ Ok(())+}+#[tokio::test]async fn queued_input_and_unique_event_ids_round_trip() -> anyhow::Result<()> {let (queue, _home) = test_queue().await?;diff --git a/codex-rs/protocol/src/turn_input.rs b/codex-rs/protocol/src/turn_input.rsindex 4819d0fb9b..61b1ffe893 100644--- a/codex-rs/protocol/src/turn_input.rs+++ b/codex-rs/protocol/src/turn_input.rs@@ -215,6 +215,9 @@ pub enum SteerSubmission {/// Why Core did not accept submitted turn input for turn processing.#[derive(Clone, Debug, Eq, PartialEq)]pub enum NotSubmittedReason {+ /// The host is draining and no longer permits new regular turns.+ ServerDraining,+/// `start_turn_if_idle` found an active turn.NotIdle,