Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Support store-owned preparation when resuming threads (#54059)

Owen Linb7ba02f88095
diff --git a/codex-rs/core/src/codex_delegate.rs b/codex-rs/core/src/codex_delegate.rs
index e2c30ad988..4a77f764bf 100644
--- a/codex-rs/core/src/codex_delegate.rs
+++ b/codex-rs/core/src/codex_delegate.rs
@@ -121,6 +121,7 @@ pub(crate) async fn run_codex_thread_interactive(
code_mode_session_provider: parent_session.services.code_mode_service.session_provider(),
extensions,
conversation_history,
+ resume_preparation: None,
history_initialization,
disabled_plugin_ids: (isolation == codex_extension_api::SessionIsolation::Inherit)
.then(|| parent_ctx.disabled_plugin_ids.clone()),
diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rs
index 516db0886a..aad25b40d8 100644
--- a/codex-rs/core/src/session/mod.rs
+++ b/codex-rs/core/src/session/mod.rs
@@ -188,6 +188,7 @@ use codex_thread_store::ReadThreadParams;
use codex_thread_store::ResumeThreadParams;
use codex_thread_store::ThreadPersistenceMetadata;
use codex_thread_store::ThreadStore;
+use codex_thread_store::ThreadStoreResumePreparation;
use codex_utils_audio::prepare_response_items as prepare_audio_response_items;
use codex_utils_git_discovery::GitRootDiscovery;
use codex_utils_output_truncation::with_serialization_allowance;
@@ -495,6 +496,7 @@ pub(crate) struct SessionSpawnArgs {
pub(crate) code_mode_session_provider: Arc<dyn codex_code_mode::CodeModeSessionProvider>,
pub(crate) extensions: Arc<codex_extension_api::ExtensionRegistry<crate::config::Config>>,
pub(crate) conversation_history: InitialHistory,
+ pub(crate) resume_preparation: Option<ThreadStoreResumePreparation>,
pub(crate) history_initialization: HistoryInitialization,
pub(crate) disabled_plugin_ids: Option<Vec<String>>,
pub(crate) requested_history_mode: Option<ThreadHistoryMode>,
@@ -610,6 +612,7 @@ impl Session {
code_mode_session_provider,
extensions,
conversation_history,
+ resume_preparation,
history_initialization,
disabled_plugin_ids,
requested_history_mode,
@@ -991,6 +994,7 @@ impl Session {
analytics_events_client,
image_store,
thread_store,
+ resume_preparation,
parent_rollout_thread_trace,
attestation_provider,
external_time_provider,
diff --git a/codex-rs/core/src/session/session.rs b/codex-rs/core/src/session/session.rs
index 6de001d0dc..830127290f 100644
--- a/codex-rs/core/src/session/session.rs
+++ b/codex-rs/core/src/session/session.rs
@@ -807,6 +807,7 @@ impl Session {
analytics_events_client: Option<AnalyticsEventsClient>,
image_store: Arc<dyn AttachmentStore>,
thread_store: Arc<dyn ThreadStore>,
+ resume_preparation: Option<ThreadStoreResumePreparation>,
parent_rollout_thread_trace: ThreadTraceContext,
attestation_provider: Option<Arc<dyn AttestationProvider>>,
external_time_provider: Option<Arc<dyn TimeProvider>>,
@@ -1130,8 +1131,13 @@ impl Session {
let (context_tx, context_rx) = tokio::sync::oneshot::channel();
let live_thread = guard
.acquire(async move {
- let (live_thread, history) =
- LiveThread::resume(store, history_mode, params).await?;
+ let (live_thread, history) = LiveThread::resume(
+ store,
+ history_mode,
+ params,
+ resume_preparation,
+ )
+ .await?;
// Cancellation still leaves the writer with the acquisition guard.
let _ = context_tx.send(history);
Ok(live_thread)
diff --git a/codex-rs/core/src/session/tests.rs b/codex-rs/core/src/session/tests.rs
index 592d0e37f7..9b3ec7b698 100644
--- a/codex-rs/core/src/session/tests.rs
+++ b/codex-rs/core/src/session/tests.rs
@@ -7208,6 +7208,7 @@ async fn make_session_with_config_and_rx(
codex_thread_store::LocalThreadStoreConfig::from_config(config.as_ref()),
/*state_db*/ None,
)),
+ /*resume_preparation*/ None,
codex_rollout_trace::ThreadTraceContext::disabled(),
/*attestation_provider*/ None,
/*external_time_provider*/ None,
@@ -7350,6 +7351,7 @@ async fn make_session_with_history_source_and_agent_control_and_rx(
.expect("state db should initialize"),
),
)),
+ /*resume_preparation*/ None,
codex_rollout_trace::ThreadTraceContext::disabled(),
/*attestation_provider*/ None,
/*external_time_provider*/ None,
diff --git a/codex-rs/core/src/session/tests/guardian_tests.rs b/codex-rs/core/src/session/tests/guardian_tests.rs
index ab9a2be02e..e70fa5fd8f 100644
--- a/codex-rs/core/src/session/tests/guardian_tests.rs
+++ b/codex-rs/core/src/session/tests/guardian_tests.rs
@@ -1303,6 +1303,7 @@ async fn guardian_subagent_does_not_inherit_parent_exec_policy_rules() {
code_mode_session_provider: Arc::new(codex_code_mode::DisabledCodeModeSessionProvider),
extensions: codex_extension_api::empty_extension_registry(),
conversation_history: InitialHistory::New,
+ resume_preparation: None,
history_initialization: HistoryInitialization::New,
disabled_plugin_ids: None,
requested_history_mode: None,
diff --git a/codex-rs/core/src/thread_manager.rs b/codex-rs/core/src/thread_manager.rs
index 2fb6da8d71..4910246f07 100644
--- a/codex-rs/core/src/thread_manager.rs
+++ b/codex-rs/core/src/thread_manager.rs
@@ -108,6 +108,7 @@ use codex_thread_store::StoredThread;
use codex_thread_store::ThreadMetadataPatch;
use codex_thread_store::ThreadStore;
use codex_thread_store::ThreadStoreError;
+use codex_thread_store::ThreadStoreResumePreparation;
use codex_thread_store::UpdateThreadMetadataParams;
use codex_utils_absolute_path::AbsolutePathBuf;
use codex_utils_git_discovery::GitRootDiscovery;
@@ -283,6 +284,8 @@ pub struct StartThreadOptions {
pub thread_instructions_provider: Option<Arc<dyn ThreadInstructionsProvider>>,
pub allow_provider_model_fallback: bool,
pub initial_history: InitialHistory,
+ /// Store-owned state prepared while loading the resumed history.
+ pub resume_preparation: Option<ThreadStoreResumePreparation>,
/// Parent captured for `start_thread`, including a parent not in the live registry.
pub internal_parent: Option<InternalSessionParent>,
pub history_mode: Option<ThreadHistoryMode>,
@@ -313,6 +316,7 @@ impl StartThreadOptions {
thread_instructions_provider: None,
allow_provider_model_fallback: false,
initial_history: InitialHistory::New,
+ resume_preparation: None,
internal_parent: None,
history_mode: None,
session_source: None,
@@ -2106,6 +2110,7 @@ impl ThreadManagerState {
thread_instructions_provider,
allow_provider_model_fallback,
initial_history,
+ resume_preparation,
internal_parent: _,
history_mode,
session_source,
@@ -2122,6 +2127,13 @@ impl ThreadManagerState {
mut reserved_thread_id,
disabled_plugin_ids,
} = options;
+ if resume_preparation.is_some()
+ && (config.ephemeral || !matches!(&initial_history, InitialHistory::Resumed(_)))
+ {
+ return Err(CodexErr::InvalidRequest(
+ "thread store resume preparation requires a persisted resumed thread".to_string(),
+ ));
+ }
let inherited_environments = captured_environments.or(inherited_environments);
let session_source = session_source.unwrap_or_else(|| self.session_source.clone());
// Older callers and saved reviewers identify isolation through their source.
@@ -2339,6 +2351,7 @@ impl ThreadManagerState {
code_mode_session_provider: Arc::clone(&self.code_mode_session_provider),
extensions,
conversation_history: initial_history,
+ resume_preparation,
history_initialization,
disabled_plugin_ids,
requested_history_mode: history_mode,
diff --git a/codex-rs/core/tests/suite/resume.rs b/codex-rs/core/tests/suite/resume.rs
index b78e305857..138a73a203 100644
--- a/codex-rs/core/tests/suite/resume.rs
+++ b/codex-rs/core/tests/suite/resume.rs
@@ -4,12 +4,15 @@ use codex_core::TurnInputRequest;
use codex_history::InitialHistory;
use codex_history::ResumedHistory;
use codex_protocol::config_types::WindowsSandboxLevel;
+use codex_protocol::error::CodexErrorDetails;
use codex_protocol::mcp::ClientMcpExtensions;
use codex_protocol::protocol::EventMsg;
use codex_protocol::protocol::ThreadHistoryMode;
use codex_protocol::protocol::ThreadSettingsOverrides;
use codex_protocol::user_input::UserInput;
+use codex_thread_store::InMemoryThreadStore;
use codex_thread_store::LoadThreadHistoryParams;
+use codex_thread_store::ThreadStoreResumePreparation;
use core_test_support::responses::ev_assistant_message;
use core_test_support::responses::ev_completed;
use core_test_support::responses::ev_response_created;
@@ -23,6 +26,51 @@ use core_test_support::wait_for_event;
use pretty_assertions::assert_eq;
use std::sync::Arc;
+/// A supplied preparation must select the prepared store path instead of silently falling back to
+/// an ordinary resume.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn resume_uses_prepared_store_path_when_preparation_is_present() -> Result<()> {
+ skip_if_no_network!(Ok(()));
+
+ let server = start_mock_server().await;
+ let initial = test_codex()
+ .with_thread_store(Arc::new(InMemoryThreadStore::default()))
+ .build_with_auto_env(&server)
+ .await?;
+ let thread_id = initial.session_configured.thread_id;
+ initial.codex.shutdown_and_wait().await?;
+ initial.thread_manager.remove_thread(&thread_id).await;
+ let context = initial
+ .thread_store
+ .load_latest_model_context(LoadThreadHistoryParams {
+ thread_id,
+ include_archived: true,
+ })
+ .await?;
+
+ let mut options = initial.start_thread_options().await;
+ options.initial_history = InitialHistory::Resumed(ResumedHistory {
+ history_revision: context.revision,
+ conversation_id: context.thread_id,
+ history: Arc::new(context.items),
+ rollout_path: None,
+ });
+ options.resume_preparation = Some(ThreadStoreResumePreparation::new(()));
+
+ let Err(err) = initial.thread_manager.start_thread(options).await else {
+ panic!("prepared resume unexpectedly used the ordinary store path");
+ };
+ assert!(
+ matches!(
+ err.details(),
+ CodexErrorDetails::UnsupportedOperation(message)
+ if message == "resume_thread_with_preparation is not supported yet"
+ ),
+ "unexpected prepared resume error: {err}"
+ );
+ Ok(())
+}
+
#[test_case::test_case(None, ThreadHistoryMode::Paginated; "store default")]
#[test_case::test_case(Some(ThreadHistoryMode::Legacy), ThreadHistoryMode::Legacy; "explicit legacy")]
#[test_case::test_case(Some(ThreadHistoryMode::Paginated), ThreadHistoryMode::Paginated; "explicit paginated")]
diff --git a/codex-rs/thread-store/src/lib.rs b/codex-rs/thread-store/src/lib.rs
index 9cf1267574..8e0eccabec 100644
--- a/codex-rs/thread-store/src/lib.rs
+++ b/codex-rs/thread-store/src/lib.rs
@@ -58,6 +58,7 @@ pub use queue_store::QueueStore;
pub use store::PersistContext;
pub use store::ThreadStore;
pub use store::ThreadStoreFuture;
+pub use store::ThreadStoreResumePreparation;
pub use thread_attachments::AddThreadAttachmentParams;
pub use thread_attachments::ListThreadAttachmentThreadsParams;
pub use thread_attachments::ListThreadAttachmentsParams;
diff --git a/codex-rs/thread-store/src/live_thread.rs b/codex-rs/thread-store/src/live_thread.rs
index ab18df6d8e..a6de95b297 100644
--- a/codex-rs/thread-store/src/live_thread.rs
+++ b/codex-rs/thread-store/src/live_thread.rs
@@ -26,6 +26,7 @@ use crate::ThreadStore;
use crate::ThreadStoreError;
use crate::ThreadStoreFuture;
use crate::ThreadStoreResult;
+use crate::ThreadStoreResumePreparation;
use crate::UpdateThreadMetadataParams;
use crate::thread_metadata_sync::ThreadMetadataSync;
@@ -182,6 +183,7 @@ impl LiveThread {
thread_store: Arc<dyn ThreadStore>,
history_mode: ThreadHistoryMode,
mut params: ResumeThreadParams,
+ resume_preparation: Option<ThreadStoreResumePreparation>,
) -> ThreadStoreResult<(Self, Arc<Vec<RolloutItem>>)> {
let thread_id = params.thread_id;
let metadata = if history_mode == ThreadHistoryMode::Paginated
@@ -197,7 +199,14 @@ impl LiveThread {
} else {
None
};
- let history = thread_store.resume_thread(params.clone()).await?;
+ let history = match resume_preparation {
+ Some(preparation) => {
+ thread_store
+ .resume_thread_with_preparation(params.clone(), preparation)
+ .await?
+ }
+ None => thread_store.resume_thread(params.clone()).await?,
+ };
params.history = Some(Arc::clone(&history));
let metadata_sync = ThreadMetadataSync::for_resume(&params, metadata.as_ref());
Ok((
diff --git a/codex-rs/thread-store/src/local/mod.rs b/codex-rs/thread-store/src/local/mod.rs
index 5ec4719cc2..2df77f7239 100644
--- a/codex-rs/thread-store/src/local/mod.rs
+++ b/codex-rs/thread-store/src/local/mod.rs
@@ -1027,6 +1027,7 @@ mod tests {
memory_mode: ThreadMemoryMode::Enabled,
},
},
+ /*resume_preparation*/ None,
)
.await
.expect("resume paginated thread from its requested rollout");
@@ -1377,6 +1378,7 @@ mod tests {
memory_mode: ThreadMemoryMode::Enabled,
},
},
+ /*resume_preparation*/ None,
)
.await
.expect("resume live thread");
@@ -1433,6 +1435,7 @@ mod tests {
memory_mode: ThreadMemoryMode::Enabled,
},
},
+ /*resume_preparation*/ None,
)
.await
.expect("resume external live thread");
diff --git a/codex-rs/thread-store/src/store.rs b/codex-rs/thread-store/src/store.rs
index d604f47875..762861e771 100644
--- a/codex-rs/thread-store/src/store.rs
+++ b/codex-rs/thread-store/src/store.rs
@@ -2,6 +2,7 @@ use codex_protocol::ThreadId;
use codex_protocol::protocol::ThreadHistoryMode;
use codex_rollout::RolloutItem;
use std::any::Any;
+use std::fmt;
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
@@ -65,6 +66,37 @@ use crate::UpdatedProject;
/// Future returned by [`ThreadStore`] operations.
pub type ThreadStoreFuture<'a, T> = Pin<Box<dyn Future<Output = ThreadStoreResult<T>> + Send + 'a>>;
+/// Data a [`ThreadStore`] has already loaded while preparing a thread for resume.
+///
+/// Core does not inspect this value. It gives the value back to the store when reopening the
+/// thread, allowing the store to reuse the loaded history and writer state instead of loading them
+/// again. The value can only be used once because it may own resources that cannot be copied.
+pub struct ThreadStoreResumePreparation {
+ state: Box<dyn Any + Send>,
+}
+
+impl ThreadStoreResumePreparation {
+ pub fn new<T: Any + Send>(state: T) -> Self {
+ Self {
+ state: Box::new(state),
+ }
+ }
+
+ pub fn downcast<T: Any + Send>(self) -> Result<T, Self> {
+ match self.state.downcast::<T>() {
+ Ok(state) => Ok(*state),
+ Err(state) => Err(Self { state }),
+ }
+ }
+}
+
+impl fmt::Debug for ThreadStoreResumePreparation {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.debug_struct("ThreadStoreResumePreparation")
+ .finish_non_exhaustive()
+ }
+}
+
/// Why thread persistence is being requested.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PersistContext {
@@ -155,6 +187,22 @@ pub trait ThreadStore: Any + Send + Sync {
params: ResumeThreadParams,
) -> ThreadStoreFuture<'_, Arc<Vec<RolloutItem>>>;
+ /// Reopens a thread using implementation-owned state prepared before Core startup.
+ ///
+ /// Stores should only override this when they also produce the preparation. The returned
+ /// history and failure cleanup guarantees are the same as [`Self::resume_thread`].
+ fn resume_thread_with_preparation(
+ &self,
+ _params: ResumeThreadParams,
+ _preparation: ThreadStoreResumePreparation,
+ ) -> ThreadStoreFuture<'_, Arc<Vec<RolloutItem>>> {
+ Box::pin(async {
+ Err(ThreadStoreError::Unsupported {
+ operation: "resume_thread_with_preparation",
+ })
+ })
+ }
+
/// Appends raw rollout items to a live thread.
///
/// Implementations should apply the shared rollout persistence policy before writing durable