Add ThreadManager sample crate (#20141)

Summary:
- Add codex-thread-manager-sample, a one-shot binary that starts a
ThreadManager thread, submits a prompt, and prints the final assistant
output.
- Pass ThreadStore into ThreadManager::new and expose
thread_store_from_config for existing callsites.
- Build the sample Config directly with only --model and prompt inputs.

Verification:
- just fmt
- cargo check -p codex-thread-manager-sample -p codex-app-server -p
codex-mcp-server
- git diff --check

Tests: Not run per request.

codex-rs/core/src/tools/handlers/multi_agents_tests.rs

@@ -5,6 +5,7 @@ use crate::config::DEFAULT_AGENT_MAX_DEPTH;
 use crate::function_tool::FunctionCallError;
 use crate::session::tests::make_session_and_context;
 use crate::session_prefix::format_subagent_notification_message;
+use crate::thread_manager::thread_store_from_config;
 use crate::tools::context::ToolOutput;
 use crate::tools::handlers::multi_agents_v2::CloseAgentHandler as CloseAgentHandlerV2;
 use crate::tools::handlers::multi_agents_v2::FollowupTaskHandler as FollowupTaskHandlerV2;
@@ -296,7 +297,10 @@ async fn spawn_agent_fork_context_rejects_agent_type_override() {
     let role_name = install_role_with_model_override(&mut turn).await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -328,7 +332,10 @@ async fn spawn_agent_fork_context_rejects_child_model_overrides() {
     let (mut session, turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -363,7 +370,10 @@ async fn multi_agent_v2_spawn_fork_turns_all_rejects_agent_type_override() {
     let role_name = install_role_with_model_override(&mut turn).await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -406,7 +416,10 @@ async fn multi_agent_v2_spawn_defaults_to_full_fork_and_rejects_child_model_over
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -447,7 +460,10 @@ async fn multi_agent_v2_spawn_partial_fork_turns_allows_agent_type_override() {
     let role_name = install_role_with_model_override(&mut turn).await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -530,7 +546,10 @@ async fn multi_agent_v2_spawn_requires_task_name() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -564,7 +583,10 @@ async fn multi_agent_v2_spawn_rejects_legacy_items_field() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -624,7 +646,10 @@ async fn multi_agent_v2_spawn_returns_path_and_send_message_accepts_relative_pat
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -721,7 +746,10 @@ async fn multi_agent_v2_spawn_rejects_legacy_fork_context() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -760,7 +788,10 @@ async fn multi_agent_v2_spawn_rejects_invalid_fork_turns_string() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -799,7 +830,10 @@ async fn multi_agent_v2_spawn_rejects_zero_fork_turns() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -838,7 +872,10 @@ async fn multi_agent_v2_send_message_accepts_root_target_from_child() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -914,7 +951,10 @@ async fn multi_agent_v2_followup_task_rejects_root_target_from_child() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -995,7 +1035,10 @@ async fn multi_agent_v2_list_agents_returns_completed_status_and_last_task_messa
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -1089,7 +1132,10 @@ async fn multi_agent_v2_list_agents_filters_by_relative_path_prefix() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -1176,7 +1222,10 @@ async fn multi_agent_v2_list_agents_omits_closed_agents() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -1240,7 +1289,10 @@ async fn multi_agent_v2_send_message_rejects_legacy_items_field() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -1296,7 +1348,10 @@ async fn multi_agent_v2_send_message_rejects_interrupt_parameter() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -1369,7 +1424,10 @@ async fn multi_agent_v2_followup_task_completion_notifies_parent_on_every_turn()
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -1504,7 +1562,10 @@ async fn multi_agent_v2_followup_task_rejects_legacy_items_field() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -1557,7 +1618,10 @@ async fn multi_agent_v2_interrupted_turn_does_not_notify_parent() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -1634,7 +1698,10 @@ async fn multi_agent_v2_spawn_omits_agent_id_when_named() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -1673,7 +1740,10 @@ async fn multi_agent_v2_spawn_surfaces_task_name_validation_errors() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -1887,7 +1957,7 @@ async fn multi_agent_v2_spawn_agent_ignores_configured_max_depth() {
         .enable(Feature::MultiAgentV2)
         .expect("test config should allow feature update");
     let root = manager
-        .start_thread(config.clone())
+        .start_thread(config.clone(), thread_store_from_config(&config))
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -2011,7 +2081,10 @@ async fn send_input_interrupts_before_prompt() {
     let manager = thread_manager();
     session.services.agent_control = manager.agent_control();
     let config = turn.config.as_ref().clone();
-    let thread = manager.start_thread(config).await.expect("start thread");
+    let thread = manager
+        .start_thread(config.clone(), thread_store_from_config(&config))
+        .await
+        .expect("start thread");
     let agent_id = thread.thread_id;
     let invocation = invocation(
         Arc::new(session),
@@ -2050,7 +2123,10 @@ async fn send_input_accepts_structured_items() {
     let manager = thread_manager();
     session.services.agent_control = manager.agent_control();
     let config = turn.config.as_ref().clone();
-    let thread = manager.start_thread(config).await.expect("start thread");
+    let thread = manager
+        .start_thread(config.clone(), thread_store_from_config(&config))
+        .await
+        .expect("start thread");
     let agent_id = thread.thread_id;
     let invocation = invocation(
         Arc::new(session),
@@ -2142,7 +2218,10 @@ async fn resume_agent_noops_for_active_agent() {
     let manager = thread_manager();
     session.services.agent_control = manager.agent_control();
     let config = turn.config.as_ref().clone();
-    let thread = manager.start_thread(config).await.expect("start thread");
+    let thread = manager
+        .start_thread(config.clone(), thread_store_from_config(&config))
+        .await
+        .expect("start thread");
     let agent_id = thread.thread_id;
     let status_before = manager.agent_control().get_status(agent_id).await;
     let invocation = invocation(
@@ -2180,7 +2259,8 @@ async fn resume_agent_restores_closed_agent_and_accepts_send_input() {
     let config = turn.config.as_ref().clone();
     let thread = manager
         .resume_thread_with_history(
-            config,
+            config.clone(),
+            thread_store_from_config(&config),
             InitialHistory::Forked(vec![RolloutItem::ResponseItem(ResponseItem::Message {
                 id: None,
                 role: "user".to_string(),
@@ -2345,7 +2425,10 @@ async fn multi_agent_v2_wait_agent_accepts_timeout_only_argument() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -2521,7 +2604,10 @@ async fn wait_agent_times_out_when_status_is_not_final() {
     let manager = thread_manager();
     session.services.agent_control = manager.agent_control();
     let config = turn.config.as_ref().clone();
-    let thread = manager.start_thread(config).await.expect("start thread");
+    let thread = manager
+        .start_thread(config.clone(), thread_store_from_config(&config))
+        .await
+        .expect("start thread");
     let agent_id = thread.thread_id;
     let invocation = invocation(
         Arc::new(session),
@@ -2561,7 +2647,10 @@ async fn wait_agent_clamps_short_timeouts_to_minimum() {
     let manager = thread_manager();
     session.services.agent_control = manager.agent_control();
     let config = turn.config.as_ref().clone();
-    let thread = manager.start_thread(config).await.expect("start thread");
+    let thread = manager
+        .start_thread(config.clone(), thread_store_from_config(&config))
+        .await
+        .expect("start thread");
     let agent_id = thread.thread_id;
     let invocation = invocation(
         Arc::new(session),
@@ -2596,7 +2685,10 @@ async fn wait_agent_returns_final_status_without_timeout() {
     let manager = thread_manager();
     session.services.agent_control = manager.agent_control();
     let config = turn.config.as_ref().clone();
-    let thread = manager.start_thread(config).await.expect("start thread");
+    let thread = manager
+        .start_thread(config.clone(), thread_store_from_config(&config))
+        .await
+        .expect("start thread");
     let agent_id = thread.thread_id;
     let mut status_rx = manager
         .agent_control()
@@ -2644,7 +2736,10 @@ async fn multi_agent_v2_wait_agent_returns_summary_for_mailbox_activity() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -2735,7 +2830,10 @@ async fn multi_agent_v2_wait_agent_returns_for_already_queued_mail() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -2813,7 +2911,10 @@ async fn multi_agent_v2_wait_agent_wakes_on_any_mailbox_notification() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -2901,7 +3002,10 @@ async fn multi_agent_v2_wait_agent_does_not_return_completed_content() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -2987,7 +3091,10 @@ async fn multi_agent_v2_close_agent_accepts_task_name_target() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -3046,7 +3153,10 @@ async fn multi_agent_v2_close_agent_rejects_root_target_and_id() {
     let (mut session, mut turn) = make_session_and_context().await;
     let manager = thread_manager();
     let root = manager
-        .start_thread((*turn.config).clone())
+        .start_thread(
+            (*turn.config).clone(),
+            thread_store_from_config(turn.config.as_ref()),
+        )
         .await
         .expect("root thread should start");
     session.services.agent_control = manager.agent_control();
@@ -3095,7 +3205,10 @@ async fn close_agent_submits_shutdown_and_returns_previous_status() {
     let manager = thread_manager();
     session.services.agent_control = manager.agent_control();
     let config = turn.config.as_ref().clone();
-    let thread = manager.start_thread(config).await.expect("start thread");
+    let thread = manager
+        .start_thread(config.clone(), thread_store_from_config(&config))
+        .await
+        .expect("start thread");
     let agent_id = thread.thread_id;
     let status_before = manager.agent_control().get_status(agent_id).await;
 
@@ -3137,7 +3250,7 @@ async fn tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtr
         .expect("test config should allow sqlite");
 
     let parent = manager
-        .start_thread(config.clone())
+        .start_thread(config.clone(), thread_store_from_config(&config))
         .await
         .expect("parent thread should start");
     let parent_thread_id = parent.thread_id;
@@ -3268,7 +3381,7 @@ async fn tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtr
     );
 
     let operator = manager
-        .start_thread(config)
+        .start_thread(config.clone(), thread_store_from_config(&config))
         .await
         .expect("operator thread should start");
     let operator_session = operator.thread.codex.session.clone();