Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Add history-aware prewarming for idle threads (#48812)

vkg-oai3f4668da20a5
diff --git a/codex-rs/core/src/client.rs b/codex-rs/core/src/client.rs
index f02cba4d6c..f5ac495337 100644
--- a/codex-rs/core/src/client.rs
+++ b/codex-rs/core/src/client.rs
@@ -1845,6 +1845,7 @@ impl ModelClientSession {
request_trace: Option<W3cTraceContext>,
inference_trace: &InferenceTraceContext,
) -> Result<WebsocketStreamOutcome> {
+ let after_prewarm = !warmup && self.websocket_session.last_response_from_untraced_warmup;
let provider = Arc::clone(&self.client.state.provider);
let auth_manager = provider.auth_manager();
@@ -2063,6 +2064,10 @@ impl ModelClientSession {
("mode", mode),
("reason", reason),
("phase", if warmup { "warmup" } else { "generation" }),
+ (
+ "after_prewarm",
+ if after_prewarm { "true" } else { "false" },
+ ),
],
);
let stream_result = websocket_connection
diff --git a/codex-rs/core/src/codex_thread.rs b/codex-rs/core/src/codex_thread.rs
index 7fd17e3016..316af05c08 100644
--- a/codex-rs/core/src/codex_thread.rs
+++ b/codex-rs/core/src/codex_thread.rs
@@ -9,6 +9,7 @@ use crate::session::SessionSettingsUpdate;
use crate::session::Submission;
use crate::session::new_submission_id;
use crate::session::session::Session;
+use crate::session::startup_prewarm::PrewarmInput;
use crate::session::step_settings::StepSettingsUpdate;
use crate::thread_startup_metadata::ThreadStartupMetadata;
use codex_diagnostics::Gauge;
@@ -248,7 +249,18 @@ impl CodexThread {
/// The next turn consumes the warmup through the existing startup handoff.
/// Call after installing host services such as the thread's attestation routing.
pub async fn prewarm(&self) {
- self.session.schedule_startup_prewarm().await;
+ self.session
+ .schedule_startup_prewarm(PrewarmInput::Base)
+ .await;
+ }
+
+ /// Schedule an idle-thread warmup with existing history when the connection needs preparation.
+ /// Sends `generate: false`; the next turn reuses the prepared response only if its prompt
+ /// still extends this history and its request settings match. Uses the same handoff as `prewarm`.
+ pub async fn prewarm_with_history(&self) {
+ self.session
+ .schedule_startup_prewarm(PrewarmInput::History)
+ .await;
}
/// Whether analytics is enabled for this thread after configuration and host overrides.
diff --git a/codex-rs/core/src/session/session.rs b/codex-rs/core/src/session/session.rs
index 01c8a36cb0..62be2d34e2 100644
--- a/codex-rs/core/src/session/session.rs
+++ b/codex-rs/core/src/session/session.rs
@@ -1884,7 +1884,8 @@ impl Session {
)
.await?;
sess.start_mcp_prewarm_worker(mcp_prewarm_rx, mcp_auth_changes);
- sess.schedule_startup_prewarm().await;
+ sess.schedule_startup_prewarm(super::startup_prewarm::PrewarmInput::Base)
+ .await;
let session_start_source = match &initial_history {
InitialHistory::Forked(_) if forked_from_id.is_some() => {
codex_hooks::SessionStartSource::Fork
diff --git a/codex-rs/core/src/session/startup_prewarm.rs b/codex-rs/core/src/session/startup_prewarm.rs
index 5e538c87aa..b59308436d 100644
--- a/codex-rs/core/src/session/startup_prewarm.rs
+++ b/codex-rs/core/src/session/startup_prewarm.rs
@@ -2,6 +2,7 @@
//! One scheduled task owns the prepared client session until the next regular
//! turn consumes it; shutdown and turn cancellation use the same handoff.
+use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;
use std::time::Instant;
@@ -31,6 +32,21 @@ use codex_protocol::models::BaseInstructions;
use codex_protocol::protocol::SessionSource;
use codex_protocol::protocol::SubAgentSource;
+#[derive(Clone, Copy, Debug)]
+pub(crate) enum PrewarmInput {
+ Base,
+ History,
+}
+
+impl PrewarmInput {
+ fn as_str(self) -> &'static str {
+ match self {
+ Self::Base => "base",
+ Self::History => "history",
+ }
+ }
+}
+
pub(crate) struct SessionStartupPrewarmHandle {
task: AbortOnDropHandle<CodexResult<ModelClientSession>>,
started_at: Instant,
@@ -190,7 +206,7 @@ impl SessionStartupPrewarmHandle {
}
impl Session {
- pub(crate) async fn schedule_startup_prewarm(self: &Arc<Self>) {
+ pub(crate) async fn schedule_startup_prewarm(self: &Arc<Self>, input: PrewarmInput) {
let websocket_connect_timeout = self.provider().await.websocket_connect_timeout();
let mut state = self.state.lock().await;
if state.shutting_down {
@@ -242,7 +258,7 @@ impl Session {
let startup_prewarm_session = Arc::clone(self);
let startup_prewarm = tokio::spawn(
async move {
- let result = schedule_startup_prewarm_inner(startup_prewarm_session).await;
+ let result = schedule_startup_prewarm_inner(startup_prewarm_session, input).await;
let status = if result.is_ok() { "ready" } else { "failed" };
session_telemetry.record_startup_phase(
"startup_prewarm_total",
@@ -252,7 +268,7 @@ impl Session {
session_telemetry.record_duration(
STARTUP_PREWARM_DURATION_METRIC,
started_at.elapsed(),
- &[("status", status)],
+ &[("status", status), ("input", input.as_str())],
);
result
}
@@ -260,6 +276,7 @@ impl Session {
"startup_prewarm",
otel.name = "startup_prewarm",
thread.id = %self.thread_id(),
+ prewarm.input = input.as_str(),
)),
);
state.set_session_startup_prewarm(SessionStartupPrewarmHandle::new(
@@ -285,7 +302,10 @@ impl Session {
}
}
-async fn schedule_startup_prewarm_inner(session: Arc<Session>) -> CodexResult<ModelClientSession> {
+async fn schedule_startup_prewarm_inner(
+ session: Arc<Session>,
+ input: PrewarmInput,
+) -> CodexResult<ModelClientSession> {
let prewarm_started_at = Instant::now();
let mut client_session = session.services.model_client.new_session();
let websocket_ready = client_session.is_websocket_prewarmed().await;
@@ -293,14 +313,17 @@ async fn schedule_startup_prewarm_inner(session: Arc<Session>) -> CodexResult<Mo
session.services.session_telemetry.counter(
"codex.startup_prewarm.websocket_check",
/*inc*/ 1,
- &[(
- "outcome",
- if websocket_ready {
- "ready"
- } else {
- "needs_prewarm"
- },
- )],
+ &[
+ (
+ "outcome",
+ if websocket_ready {
+ "ready"
+ } else {
+ "needs_prewarm"
+ },
+ ),
+ ("input", input.as_str()),
+ ],
);
if websocket_ready {
return Ok(client_session);
@@ -372,8 +395,24 @@ async fn schedule_startup_prewarm_inner(session: Arc<Session>) -> CodexResult<Mo
),
)?;
let build_prompt_started_at = Instant::now();
+ let prompt_input = match input {
+ PrewarmInput::Base => Vec::new(),
+ PrewarmInput::History => {
+ // Use the same history projection and tool metadata as a sampling request.
+ // The real turn still checks this prefix before reusing the prepared response.
+ let mut history = session
+ .clone_history()
+ .await
+ .for_prompt(&step_context.settings.model_info.input_modalities);
+ session
+ .services
+ .executed_tool_calls
+ .attach_to_prompt(&mut history, &mut HashMap::new());
+ history
+ }
+ };
let startup_prompt = build_prompt(
- Vec::new(),
+ prompt_input,
step_context.as_ref(),
BaseInstructions {
text: base_instructions,
diff --git a/codex-rs/core/src/session/tests.rs b/codex-rs/core/src/session/tests.rs
index 7364ddd297..156225736f 100644
--- a/codex-rs/core/src/session/tests.rs
+++ b/codex-rs/core/src/session/tests.rs
@@ -8462,7 +8462,9 @@ async fn shutdown_complete_does_not_append_to_thread_store_after_shutdown() {
assert!(result_sender.is_closed());
assert!(session.services.model_client.responses_websocket_enabled());
- session.schedule_startup_prewarm().await;
+ session
+ .schedule_startup_prewarm(super::startup_prewarm::PrewarmInput::Base)
+ .await;
assert!(session.state.lock().await.startup_prewarm.is_none());
assert_eq!(
diff --git a/codex-rs/core/src/session/turn_context.rs b/codex-rs/core/src/session/turn_context.rs
index bdaf4382f8..0d7b59d77e 100644
--- a/codex-rs/core/src/session/turn_context.rs
+++ b/codex-rs/core/src/session/turn_context.rs
@@ -956,7 +956,7 @@ impl Session {
);
if per_turn_config
.features
- .persistent_mode_enabled(step_settings.reasoning_effort())
+ .persistent_execution_enabled(step_settings.reasoning_effort())
{
super::time_reminder::apply_persistent_defaults(&mut per_turn_config);
}
diff --git a/codex-rs/core/src/session/world_state.rs b/codex-rs/core/src/session/world_state.rs
index fc10919d06..c0d7dea64d 100644
--- a/codex-rs/core/src/session/world_state.rs
+++ b/codex-rs/core/src/session/world_state.rs
@@ -218,7 +218,7 @@ impl Session {
.iter()
.any(|tool| tool == "send_user_message_async");
world_state.add_section(PersistentModeState::new(
- turn_context.config.features.persistent_mode_enabled(
+ turn_context.config.features.persistent_execution_enabled(
step_context.settings.effective_reasoning_effort().as_ref(),
),
model_messages.persistent_instructions(),
diff --git a/codex-rs/core/tests/suite/client_websockets.rs b/codex-rs/core/tests/suite/client_websockets.rs
index 7dbcb21c25..c6345c160d 100755
--- a/codex-rs/core/tests/suite/client_websockets.rs
+++ b/codex-rs/core/tests/suite/client_websockets.rs
@@ -614,7 +614,11 @@ async fn responses_websocket_resume_prewarm_reuses_and_repairs_connection() -> a
requests: vec![
vec![ev_response_created("warm-1"), ev_completed("warm-1")],
vec![ev_response_created("resp-1"), ev_completed("resp-1")],
- vec![ev_response_created("resp-2"), ev_completed("resp-2")],
+ vec![
+ ev_response_created("resp-2"),
+ ev_assistant_message("msg_2", "ready to continue"),
+ ev_completed("resp-2"),
+ ],
],
response_headers: Vec::new(),
accept_delay: None,
@@ -646,8 +650,8 @@ async fn responses_websocket_resume_prewarm_reuses_and_repairs_connection() -> a
// A healthy warm resume skips preparation; only the user turn reloads instructions.
let instruction_loads = instructions.load_count();
- test.codex.prewarm().await;
- test.codex.prewarm().await;
+ test.codex.prewarm_with_history().await;
+ test.codex.prewarm_with_history().await;
test.submit_text_turn("continue").await?;
assert_eq!(instructions.load_count(), instruction_loads + 1);
@@ -662,7 +666,16 @@ async fn responses_websocket_resume_prewarm_reuses_and_repairs_connection() -> a
);
let connection = server.single_connection();
assert_eq!(connection.len(), 3);
+ assert_eq!(connection[0].body_json()["input"], json!([]));
assert_eq!(connection[2].body_json()["previous_response_id"], "resp-1");
+ let mut expected_history = connection
+ .iter()
+ .flat_map(|request| request.body_json()["input"].as_array().unwrap().clone())
+ .collect::<Vec<_>>();
+ expected_history.push(serde_json::to_value(assistant_message_item(
+ "2",
+ "ready to continue",
+ ))?);
// Turn idle does not synchronize with the reader observing the server's close.
// Retry resume until it sees the close; pending attempts must still share one socket.
@@ -670,8 +683,8 @@ async fn responses_websocket_resume_prewarm_reuses_and_repairs_connection() -> a
let instruction_loads = instructions.load_count();
let warmup = tokio::time::timeout(Duration::from_secs(10), async {
loop {
- test.codex.prewarm().await;
- test.codex.prewarm().await;
+ test.codex.prewarm_with_history().await;
+ test.codex.prewarm_with_history().await;
tokio::select! {
request = server.wait_for_request(/*connection_index*/ 1, /*request_index*/ 0) => break request,
_ = tokio::time::sleep(Duration::from_millis(10)) => {}
@@ -682,6 +695,14 @@ async fn responses_websocket_resume_prewarm_reuses_and_repairs_connection() -> a
assert!(instructions.load_count() > instruction_loads);
assert_eq!(warmup.body_json()["generate"], false);
assert!(warmup.body_json().get("previous_response_id").is_none());
+ let mut actual_history: Vec<ResponseItem> =
+ serde_json::from_value(warmup.body_json()["input"].clone())?;
+ let mut expected_history: Vec<ResponseItem> = serde_json::from_value(json!(expected_history))?;
+ for item in actual_history.iter_mut().chain(&mut expected_history) {
+ item.clear_internal_chat_message_metadata_passthrough();
+ }
+ assert_eq!(actual_history, expected_history);
+ assert!(warmup.body_json().get("prompt_cache_options").is_none());
test.submit_text_turn("continue after reconnect").await?;
assert_eq!(server.handshakes().len(), 2);
@@ -2247,6 +2268,7 @@ async fn responses_websocket_creates_on_non_prefix() {
assert_eq!(second["type"].as_str(), Some("response.create"));
assert_eq!(second["model"].as_str(), Some(MODEL));
assert_eq!(second["stream"], serde_json::Value::Bool(true));
+ assert_eq!(second.get("previous_response_id"), None);
assert_eq!(
second["input"],
serde_json::to_value(&prompt_two.input).unwrap()
diff --git a/codex-rs/features/src/lib.rs b/codex-rs/features/src/lib.rs
index 4eeb3aa35b..ebd6d89f6c 100644
--- a/codex-rs/features/src/lib.rs
+++ b/codex-rs/features/src/lib.rs
@@ -516,7 +516,7 @@ impl Features {
}
/// Returns whether persistent execution is enabled for the selected effort.
- pub fn persistent_mode_enabled(&self, reasoning_effort: Option<&ReasoningEffort>) -> bool {
+ pub fn persistent_execution_enabled(&self, reasoning_effort: Option<&ReasoningEffort>) -> bool {
reasoning_effort == Some(&ReasoningEffort::Persistent)
}