Lightweight coding agent that runs in your terminal
Rust
Track history initialization in Responses turn metadata (#52325)
Adam Perry @ OpenAI780d7ab09741
diff --git a/codex-rs/app-server/tests/suite/v2/thread_resume.rs b/codex-rs/app-server/tests/suite/v2/thread_resume.rsindex 7fe3bb7a7c..1413da3b7e 100644--- a/codex-rs/app-server/tests/suite/v2/thread_resume.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_resume.rs@@ -541,6 +541,34 @@ async fn thread_resume_with_empty_path_uses_running_thread_id() -> Result<()> {} = timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(resume_id)).await??;assert_eq!(resumed.id, thread.id);+ mcp.start_turn_and_wait_for_completion(TurnStartParams {+ thread_id: resumed.id,+ input: vec![UserInput::Text {+ text: "after warm resume".to_string(),+ text_elements: Vec::new(),+ }],+ ..Default::default()+ })+ .await?;+ let requests = responses::received_responses_requests(&server).await;+ let initialization = requests+ .iter()+ .map(|request| {+ let body = request.body_json();+ let metadata: serde_json::Value = serde_json::from_str(+ body["client_metadata"]["x-codex-turn-metadata"]+ .as_str()+ .expect("turn metadata"),+ )+ .expect("valid turn metadata");+ metadata["history_initialization"].clone()+ })+ .collect::<Vec<_>>();+ // Rejoining the live runtime must not relabel it as reconstructed history.+ assert_eq!(+ serde_json::Value::Array(initialization),+ json!(["new", "new"])+ );Ok(())}@@ -6102,6 +6130,24 @@ async fn thread_resume_supports_history_and_overrides() -> Result<()> {assert_eq!(resumed.preview, history_text);assert_eq!(resumed.status, ThreadStatus::Idle);+ mcp.start_turn_and_wait_for_completion(TurnStartParams {+ thread_id: resumed.id,+ input: vec![UserInput::Text {+ text: "after supplied history".to_string(),+ text_elements: Vec::new(),+ }],+ ..Default::default()+ })+ .await?;+ let requests = responses::received_responses_requests(&server).await;+ let body = requests.last().expect("resumed model request").body_json();+ let metadata: serde_json::Value = serde_json::from_str(+ body["client_metadata"]["x-codex-turn-metadata"]+ .as_str()+ .expect("turn metadata"),+ )?;+ assert_eq!(metadata["history_initialization"], "supplied_history");+Ok(())}diff --git a/codex-rs/core/src/client_tests.rs b/codex-rs/core/src/client_tests.rsindex 5b6f7276b4..42e546e8f8 100644--- a/codex-rs/core/src/client_tests.rs+++ b/codex-rs/core/src/client_tests.rs@@ -22,6 +22,7 @@ use codex_api::AgentIdentityTelemetry;use codex_api::ApiError;use codex_api::ResponseEvent;use codex_api::TransportError;+use codex_history::HistoryInitialization;use codex_http_client::HttpClientFactory;use codex_http_client::OutboundProxyPolicy;use codex_login::AuthManager;@@ -1541,13 +1542,14 @@ fn build_ws_client_metadata_includes_window_lineage_and_turn_metadata() {let thread_id = client.state.thread_id.to_string();let expected_window_id = format!("{thread_id}:1");- let responses_metadata = test_responses_metadata_for_client(+ let mut responses_metadata = test_responses_metadata_for_client(&client,Some("turn-123"),expected_window_id.clone(),Some(parent_thread_id),TestCodexResponsesRequestKind::Turn,);+ responses_metadata.history_initialization = Some(HistoryInitialization::WarmFork);let client_metadata = client.build_ws_client_metadata(&responses_metadata,/*include_internal*/ true,@@ -1560,6 +1562,7 @@ fn build_ws_client_metadata_includes_window_lineage_and_turn_metadata() {.expect("turn metadata"),).expect("valid turn metadata");+ assert_eq!(turn_metadata["history_initialization"], "warm_fork");for (client_key, metadata_key, expected) in [(X_CODEX_INSTALLATION_ID_HEADER,diff --git a/codex-rs/core/src/codex_delegate.rs b/codex-rs/core/src/codex_delegate.rsindex c15e4d7f19..e2c30ad988 100644--- a/codex-rs/core/src/codex_delegate.rs+++ b/codex-rs/core/src/codex_delegate.rs@@ -31,6 +31,7 @@ use crate::session::session::Session;use crate::session::startup::SessionStartup;use crate::session::startup::SessionStartupGuard;use crate::session::turn_context::TurnContext;+use codex_history::HistoryInitialization;use codex_history::InitialHistory;use codex_login::AuthManager;use codex_models_manager::manager::SharedModelsManager;@@ -80,6 +81,13 @@ pub(crate) async fn run_codex_thread_interactive(let conversation_history = initial_history.unwrap_or(InitialHistory::New);let forked_from_thread_id = conversation_history.forked_from_id();+ let history_initialization = if matches!(&conversation_history, InitialHistory::Forked(_))+ && forked_from_thread_id == Some(parent_session.thread_id)+ {+ HistoryInitialization::WarmFork+ } else {+ HistoryInitialization::from_history(&conversation_history)+ };let runtime = parent_session.services.local_agent_runtime.clone();let startup = Arc::new(SessionStartup::default());startup.hold_membership(runtime.admit_start()?);@@ -113,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,+ history_initialization,disabled_plugin_ids: (isolation == codex_extension_api::SessionIsolation::Inherit).then(|| parent_ctx.disabled_plugin_ids.clone()),requested_history_mode: None,diff --git a/codex-rs/core/src/responses_metadata.rs b/codex-rs/core/src/responses_metadata.rsindex bfdeb3b40f..bcc2f9e945 100644--- a/codex-rs/core/src/responses_metadata.rs+++ b/codex-rs/core/src/responses_metadata.rs@@ -26,6 +26,7 @@ use crate::client::X_CODEX_PARENT_THREAD_ID_HEADER;use crate::client::X_CODEX_TURN_METADATA_HEADER;use crate::client::X_CODEX_WINDOW_ID_HEADER;use crate::client::X_OPENAI_SUBAGENT_HEADER;+use codex_history::HistoryInitialization;pub(crate) const INSTALLATION_ID_KEY: &str = "installation_id";pub(crate) const SESSION_ID_KEY: &str = "session_id";@@ -43,6 +44,7 @@ pub(crate) const TOOL_NAMESPACES_INFO_KEY: &str = "tool_namespaces_info";pub(crate) const TURN_STARTED_AT_UNIX_MS_KEY: &str = "turn_started_at_unix_ms";pub(crate) const HISTORY_INGEST_REQUESTED_KEY: &str = "history_ingest_requested";pub(crate) const ANALYTICS_ENABLED_KEY: &str = "analytics_enabled";+pub(crate) const HISTORY_INITIALIZATION_KEY: &str = "history_initialization";pub(crate) const MCP_ATTRIBUTION_CLIENT_METADATA_KEY: &str = "mcp_attribution";pub(crate) const MAX_MCP_ATTRIBUTION_BYTES: usize = 16 * 1024;@@ -86,6 +88,7 @@ const RESERVED_METADATA_KEYS: &[&str] = &[TURN_STARTED_AT_UNIX_MS_KEY,HISTORY_INGEST_REQUESTED_KEY,ANALYTICS_ENABLED_KEY,+ HISTORY_INITIALIZATION_KEY,FORKED_FROM_THREAD_ID_KEY,FORKED_FROM_ORDINAL_EXCLUSIVE_KEY,PARENT_THREAD_ID_KEY,@@ -240,6 +243,7 @@ pub struct CodexResponsesMetadata {pub(crate) window_id: String,pub(crate) window_number: Option<u64>,pub(crate) context_window_id: Option<Uuid>,+ pub(crate) history_initialization: Option<HistoryInitialization>,pub(crate) request_kind: Option<CodexResponsesRequestKind>,pub(crate) forked_from_thread_id: Option<ThreadId>,pub(crate) forked_from_ordinal_exclusive: Option<u64>,@@ -285,6 +289,7 @@ impl CodexResponsesMetadata {window_id,window_number: None,context_window_id: None,+ history_initialization: None,request_kind: None,forked_from_thread_id: None,forked_from_ordinal_exclusive: None,@@ -428,6 +433,7 @@ impl CodexResponsesMetadata {.then_some(self.context_window_id).flatten(),request_kind: request_kind_value,+ history_initialization: self.history_initialization,forked_from_thread_id: self.forked_from_thread_id,forked_from_ordinal_exclusive: self.forked_from_ordinal_exclusive,parent_thread_id: self.parent_thread_id,@@ -559,6 +565,8 @@ struct CodexTurnMetadataPayload<'a> {#[serde(default, skip_serializing_if = "Option::is_none")]request_kind: Option<&'static str>,#[serde(default, skip_serializing_if = "Option::is_none")]+ history_initialization: Option<HistoryInitialization>,+ #[serde(default, skip_serializing_if = "Option::is_none")]forked_from_thread_id: Option<ThreadId>,#[serde(default, skip_serializing_if = "Option::is_none")]forked_from_ordinal_exclusive: Option<u64>,diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rsindex b9e96e3c8a..c30252eee8 100644--- a/codex-rs/core/src/session/mod.rs+++ b/codex-rs/core/src/session/mod.rs@@ -84,6 +84,7 @@ use codex_features::FEATURES;use codex_features::Feature;use codex_features::Features;use codex_features::unstable_features_warning_event;+use codex_history::HistoryInitialization;use codex_history::RolloutItem;use codex_hooks::Hooks;use codex_hooks::HooksConfig;@@ -458,6 +459,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) history_initialization: HistoryInitialization,pub(crate) disabled_plugin_ids: Option<Vec<String>>,pub(crate) requested_history_mode: Option<ThreadHistoryMode>,pub(crate) fork_persistence: ForkPersistence,@@ -572,6 +574,7 @@ impl Session {code_mode_session_provider,extensions,conversation_history,+ history_initialization,disabled_plugin_ids,requested_history_mode,fork_persistence,@@ -935,6 +938,7 @@ impl Session {tx_event.clone(),agent_status_tx.clone(),conversation_history,+ history_initialization,fork_persistence,session_source_clone,skills_service,diff --git a/codex-rs/core/src/session/session.rs b/codex-rs/core/src/session/session.rsindex 928c976edb..3d944cb9bd 100644--- a/codex-rs/core/src/session/session.rs+++ b/codex-rs/core/src/session/session.rs@@ -95,6 +95,7 @@ pub(crate) struct Session {pub(crate) services: SessionServices,pub(super) git_enrichment_policy: GitEnrichmentPolicy,pub(super) fork_persistence: ForkPersistence,+ pub(super) history_initialization: HistoryInitialization,pub(super) forked_from_ordinal_exclusive: Option<u64>,pub(super) next_internal_sub_id: AtomicU64,}@@ -740,6 +741,7 @@ impl Session {context_window_id: uuid::Uuid,) -> CodexResponsesMetadata {CodexResponsesMetadata {+ history_initialization: Some(self.history_initialization),window_number: Some(window_number),context_window_id: Some(context_window_id),mcp_attribution: Some(self.services.executed_tool_calls.mcp_attribution_snapshot()),@@ -774,6 +776,7 @@ impl Session {tx_event: Sender<Event>,agent_status: watch::Sender<AgentStatus>,mut initial_history: InitialHistory,+ history_initialization: HistoryInitialization,fork_persistence: ForkPersistence,session_source: SessionSource,skills_service: Arc<HostSkillsService>,@@ -1839,6 +1842,7 @@ impl Session {services,git_enrichment_policy,fork_persistence,+ history_initialization,forked_from_ordinal_exclusive,next_internal_sub_id: AtomicU64::new(0),});diff --git a/codex-rs/core/src/session/tests.rs b/codex-rs/core/src/session/tests.rsindex acbd1ac26c..db3b4efc85 100644--- a/codex-rs/core/src/session/tests.rs+++ b/codex-rs/core/src/session/tests.rs@@ -6968,6 +6968,7 @@ pub(crate) async fn make_session_and_context() -> (Session, TurnContext) {services,git_enrichment_policy: GitEnrichmentPolicy::Fresh,fork_persistence: ForkPersistence::Copied,+ history_initialization: HistoryInitialization::New,forked_from_ordinal_exclusive: None,next_internal_sub_id: AtomicU64::new(0),};@@ -7142,6 +7143,7 @@ async fn make_session_with_config_and_rx(tx_event,agent_status_tx,InitialHistory::New,+ HistoryInitialization::New,ForkPersistence::Copied,SessionSource::Exec,skills_service,@@ -7260,6 +7262,7 @@ async fn make_session_with_history_source_and_agent_control_and_rx());let environment_manager = Arc::new(EnvironmentManager::default_for_tests());+ let history_initialization = HistoryInitialization::from_history(&initial_history);let session = Session::new(/*startup*/ None,session_configuration,@@ -7275,6 +7278,7 @@ async fn make_session_with_history_source_and_agent_control_and_rx(tx_event,agent_status_tx,initial_history,+ history_initialization,ForkPersistence::Copied,session_source,skills_service,@@ -9231,6 +9235,7 @@ whereservices,git_enrichment_policy: GitEnrichmentPolicy::Fresh,fork_persistence: ForkPersistence::Copied,+ history_initialization: HistoryInitialization::New,forked_from_ordinal_exclusive: None,next_internal_sub_id: AtomicU64::new(0),});diff --git a/codex-rs/core/src/session/tests/guardian_tests.rs b/codex-rs/core/src/session/tests/guardian_tests.rsindex 349376c587..ab9a2be02e 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,+ history_initialization: HistoryInitialization::New,disabled_plugin_ids: None,requested_history_mode: None,fork_persistence: ForkPersistence::Copied,diff --git a/codex-rs/core/src/thread_manager.rs b/codex-rs/core/src/thread_manager.rsindex d7297f48c0..a6248c0aef 100644--- a/codex-rs/core/src/thread_manager.rs+++ b/codex-rs/core/src/thread_manager.rs@@ -10,6 +10,7 @@ pub(crate) use shutdown::thread_store_error_kind;use crate::CodexAppsToolsCache;use crate::CodexThreadSettingsOverrides;+use crate::agent::AgentStatus;use crate::agent::LocalAgentControl;use crate::agent::api::AgentConfigUpdate;use crate::agent::api::AgentControl;@@ -56,6 +57,7 @@ use codex_extension_api::ThreadInstructionsProvider;use codex_extension_api::UserInstructionsProvider;use codex_extension_api::empty_extension_registry;use codex_features::Feature;+use codex_history::HistoryInitialization;use codex_history::InitialHistory;use codex_history::ResumedHistory;use codex_history::RolloutItem;@@ -2043,6 +2045,21 @@ impl ThreadManagerState {inherited_exec_policy,user_shell_override,} = request;+ let history_initialization = if matches!(+ &options.initial_history,+ InitialHistory::New | InitialHistory::Forked(_)+ ) && let Some(source_thread_id) = forked_from_thread_id+ {+ if let Ok(source) = self.get_thread(source_thread_id).await+ && source.agent_status().await != AgentStatus::Shutdown+ {+ HistoryInitialization::WarmFork+ } else {+ HistoryInitialization::ColdFork+ }+ } else {+ HistoryInitialization::from_history(&options.initial_history)+ };let StartThreadOptions {mut config,thread_instructions_provider,@@ -2281,6 +2298,7 @@ impl ThreadManagerState {code_mode_session_provider: Arc::clone(&self.code_mode_session_provider),extensions,conversation_history: initial_history,+ history_initialization,disabled_plugin_ids,requested_history_mode: history_mode,fork_persistence,diff --git a/codex-rs/core/src/turn_metadata_tests.rs b/codex-rs/core/src/turn_metadata_tests.rsindex 5ad52a1dda..f0f69e641e 100644--- a/codex-rs/core/src/turn_metadata_tests.rs+++ b/codex-rs/core/src/turn_metadata_tests.rs@@ -708,6 +708,10 @@ fn turn_metadata_state_ignores_client_reserved_metadata_before_start() {("parent_turn_id".to_string(), "client-supplied".to_string()),(ROOT_TURN_ID_KEY.to_string(), "client-supplied".to_string()),("subagent_kind".to_string(), "client-supplied".to_string()),+ (+ "history_initialization".to_string(),+ "client-supplied".to_string(),+ ),(SANDBOX_MODE_KEY.to_string(),"danger-full-access".to_string(),@@ -731,6 +735,7 @@ fn turn_metadata_state_ignores_client_reserved_metadata_before_start() {assert!(json.get("parent_turn_id").is_none());assert!(json.get(ROOT_TURN_ID_KEY).is_none());assert!(json.get("subagent_kind").is_none());+ assert!(json.get("history_initialization").is_none());assert_eq!(json[SANDBOX_MODE_KEY].as_str(), Some("read-only"));assert_eq!(json[AUTO_REVIEW_ENABLED_KEY].as_bool(), Some(false));assert_eq!(diff --git a/codex-rs/core/tests/suite/direct_tool_metadata.rs b/codex-rs/core/tests/suite/direct_tool_metadata.rsindex 68fc43e217..8656e538e8 100644--- a/codex-rs/core/tests/suite/direct_tool_metadata.rs+++ b/codex-rs/core/tests/suite/direct_tool_metadata.rs@@ -654,11 +654,13 @@ async fn direct_function_and_tool_search_mark_complete_attempts(Ok(())}-#[test_case(false; "ungranted_provider")]-#[test_case(true; "granted_provider")]+#[test_case(false, false; "ungranted_provider")]+#[test_case(true, false; "granted_provider_cold_fork")]+#[test_case(true, true; "granted_provider_warm_fork")]#[tokio::test(flavor = "multi_thread", worker_threads = 2)]async fn direct_metadata_limit_respects_provider_support(include_internal_metadata: bool,+ fork_from_running_thread: bool,) -> Result<()> {skip_if_no_network!(Ok(()));let server = start_mock_server().await;@@ -844,7 +846,14 @@ async fn direct_metadata_limit_respects_provider_support(}let rollout_path = test.codex.rollout_path().expect("rollout path");- test.codex.shutdown_and_wait().await?;+ if fork_from_running_thread {+ test.codex.flush_rollout().await?;+ } else {+ test.codex.shutdown_and_wait().await?;+ test.thread_manager+ .remove_thread(&test.session_configured.thread_id)+ .await;+ }let rollout = tokio::fs::read_to_string(&rollout_path).await?;let rollout = rollout.lines()@@ -887,6 +896,10 @@ async fn direct_metadata_limit_respects_provider_support(.await.expect("shutdown fork");+ if fork_from_running_thread {+ test.codex.shutdown_and_wait().await?;+ }+let resumed = search_capable_apps_builder(apps.chatgpt_base_url).with_config(configure_metadata).resume(&server, test.home.clone(), rollout_path)@@ -907,6 +920,36 @@ async fn direct_metadata_limit_respects_provider_support(let requests = responses.requests();assert_eq!(requests.len(), 7);+ let expected_fork = if fork_from_running_thread {+ "warm_fork"+ } else {+ "cold_fork"+ };+ let initialization = requests+ .iter()+ .map(|request| {+ let body = request.body_json();+ let metadata: Value = serde_json::from_str(+ body["client_metadata"]["x-codex-turn-metadata"]+ .as_str()+ .expect("turn metadata"),+ )+ .expect("valid turn metadata");+ metadata["history_initialization"].clone()+ })+ .collect::<Vec<_>>();+ assert_eq!(+ Value::Array(initialization),+ json!([+ "new",+ "new",+ "new",+ expected_fork,+ expected_fork,+ "cold_resume",+ "cold_resume"+ ])+ );for request in &requests[3..] {for original in [&first_output, &second_output] {let call_id = original["call_id"].as_str().expect("call ID");diff --git a/codex-rs/history/src/initialization.rs b/codex-rs/history/src/initialization.rsnew file mode 100644index 0000000000..6f190ca13c--- /dev/null+++ b/codex-rs/history/src/initialization.rs@@ -0,0 +1,34 @@+//! Request-only provenance for the history installed when a runtime starts.+//! Warm resumes retain this value: reconnecting does not reconstruct history or+//! explain metadata that was already missing before the reconnect.++use crate::InitialHistory;+use serde::Serialize;++/// Describes a reconstruction path, not proof that tool metadata was captured or lost.+/// Fork temperature records whether the source runtime was loaded and not shut down+/// at initialization. The value lasts for the runtime, including after compaction;+/// consumers must check missing tool metadata independently for each window.+#[derive(Clone, Copy, Debug, Serialize)]+#[serde(rename_all = "snake_case")]+pub enum HistoryInitialization {+ New,+ Cleared,+ ColdResume,+ WarmFork,+ ColdFork,+ SuppliedHistory,+}++impl HistoryInitialization {+ /// Classifies history without assuming that a fork's source runtime is available.+ pub fn from_history(history: &InitialHistory) -> Self {+ match history {+ InitialHistory::New => Self::New,+ InitialHistory::Cleared => Self::Cleared,+ InitialHistory::Resumed(_) => Self::ColdResume,+ // Callers with a known fork source supply its runtime availability.+ InitialHistory::Forked(_) => Self::SuppliedHistory,+ }+ }+}diff --git a/codex-rs/history/src/lib.rs b/codex-rs/history/src/lib.rsindex 41b99f95a0..5ce19f056a 100644--- a/codex-rs/history/src/lib.rs+++ b/codex-rs/history/src/lib.rs@@ -14,6 +14,9 @@ pub use compaction_resume_metadata::resume_multi_agent_version;mod compaction_checkpoint;pub use compaction_checkpoint::CompactionCheckpoint;+mod initialization;+pub use initialization::HistoryInitialization;+use std::borrow::Borrow;use std::ops::Deref;use std::ops::DerefMut;