Skip to content

armgit / codex

Public Imported from GitHub
0

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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 @@ where
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),
});
diff --git a/codex-rs/core/src/session/tests/guardian_tests.rs b/codex-rs/core/src/session/tests/guardian_tests.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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;