use std::collections::BTreeMap; use std::collections::HashMap; use std::future::Future; use std::path::PathBuf; use std::sync::Arc; use std::sync::Mutex; use std::sync::OnceLock; use std::sync::RwLock; use std::sync::atomic::AtomicBool; use std::sync::atomic::Ordering; use serde_json::Value; use tokio::sync::oneshot; use tokio::sync::watch; use tokio_util::task::AbortOnDropHandle; use crate::responses_metadata::AGENT_NAME_KEY; use crate::responses_metadata::CodexResponsesMetadata; use crate::responses_metadata::CodexResponsesRequestKind; use crate::responses_metadata::MAX_EXTRA_METADATA_VALUE_BYTES; use crate::responses_metadata::PARENT_TURN_ID_KEY; use crate::responses_metadata::ROOT_TURN_ID_KEY; use crate::responses_metadata::TurnMetadataWorkspace; use crate::responses_metadata::filter_extra_metadata; use crate::responses_metadata::subagent_header_value; use crate::responses_metadata::subagent_metadata_kind; use crate::sandbox_tags::SandboxTags; use crate::sandbox_tags::record_policy_metadata; use crate::session::step_settings::ResolvedStepSettings; use codex_file_system::WindowsSandboxSelection; use codex_git_utils::GitHeadState; use codex_git_utils::GitWorktreeStatus; use codex_git_utils::SanitizedGitUrl; use codex_git_utils::get_head_state; use codex_git_utils::get_worktree_status_in_repo; use codex_git_utils::observe_git_remote_urls; use codex_protocol::AgentPath; use codex_protocol::ThreadId; use codex_protocol::models::PermissionProfile; use codex_protocol::openai_models::ModelInfo; use codex_protocol::openai_models::ReasoningEffort as ReasoningEffortConfig; use codex_protocol::protocol::SessionSource; use codex_protocol::protocol::ThreadSource; use codex_protocol::turn_input::ResponsesApiClientMetadataUpdate; use codex_utils_absolute_path::AbsolutePathBuf; use codex_utils_git_discovery::GitRootDiscovery; use futures::FutureExt; use futures::future::FusedFuture; // Memory requests await this optional metadata before sending their model request. const MEMORY_GIT_METADATA_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(1); const MODEL_KEY: &str = "model"; const CODEX_VERSION_KEY: &str = "codex_version"; const REASONING_EFFORT_KEY: &str = "reasoning_effort"; const USER_INPUT_REQUESTED_DURING_TURN_KEY: &str = "user_input_requested_during_turn"; const WORKSPACE_KIND_KEY: &str = "workspace_kind"; fn is_targeted_continuation(value: &str) -> bool { serde_json::from_str::(value).is_ok_and(|value| value.get("review_target").is_some()) } /// Captured execution settings shared by Responses and MCP metadata. pub(crate) struct ExecutionMetadata<'a> { pub(crate) model: &'a str, pub(crate) reasoning_effort: Option, pub(crate) node_repl_disabled: bool, pub(crate) auto_review_enabled: bool, pub(crate) node_repl_auto_review_required: bool, } impl<'a> ExecutionMetadata<'a> { pub(crate) fn from_settings(settings: &'a ResolvedStepSettings) -> Self { Self { model: settings.model_info.slug.as_str(), reasoning_effort: settings.effective_reasoning_effort(), node_repl_disabled: settings.model_info.node_repl_disabled, auto_review_enabled: crate::guardian::routes_approval_policy_to_guardian( settings.approval_policy(), settings.approvals_reviewer(), ), node_repl_auto_review_required: settings.model_info.computer_use_review_required(), } } pub(crate) fn apply_to(&self, metadata: &mut CodexResponsesMetadata) { metadata.auto_review_enabled = Some(self.auto_review_enabled); metadata.node_repl_auto_review_required = Some(self.node_repl_auto_review_required); metadata.node_repl_disabled = Some(self.node_repl_disabled); metadata .extra .insert(MODEL_KEY.to_string(), self.model.to_string()); match &self.reasoning_effort { Some(reasoning_effort) => { metadata.extra.insert( REASONING_EFFORT_KEY.to_string(), reasoning_effort.to_string(), ); } None => { metadata.extra.remove(REASONING_EFFORT_KEY); } } } } #[allow(clippy::too_many_arguments)] pub async fn detached_memory_responses_metadata( thread_manager: &crate::ThreadManager, installation_id: String, session_id: String, thread_id: String, window_id: String, session_source: &SessionSource, cwd: &AbsolutePathBuf, permission_profile: &PermissionProfile, sandbox: Option<&str>, ) -> CodexResponsesMetadata { let turn_id = uuid::Uuid::now_v7().to_string(); let mut metadata = CodexResponsesMetadata { turn_id: Some(turn_id.clone()), root_turn_id: Some(turn_id), request_kind: Some(CodexResponsesRequestKind::Memory), thread_source: Some(ThreadSource::MemoryConsolidation), turn_trigger: Some("memory_consolidation".to_owned()), subagent_header: subagent_header_value(session_source), sandbox: sandbox.map(ToString::to_string), workspaces: memory_workspaces( cwd, thread_manager.git_root_discovery().discover(cwd.clone()), ) .await, ..CodexResponsesMetadata::new(installation_id, session_id, thread_id, window_id) }; record_policy_metadata(permission_profile, cwd.as_path(), &mut metadata); metadata } /// A single turn owns both its current Git snapshot and the task publishing it. #[derive(Debug, Default)] pub(crate) struct TurnGitEnrichment { workspaces: Option>>, task: Option>, admission: Option>, } impl TurnGitEnrichment { pub(crate) fn start(cwd: AbsolutePathBuf, git_root_discovery: Arc) -> Self { let (updates, workspaces) = watch::channel(BTreeMap::new()); let (admission, request) = oneshot::channel(); let task = tokio::spawn(async move { let repo_root = git_root_discovery.discover(cwd.clone()); collect_git_workspaces( &cwd, repo_root, GitCollectionAdmission::Pending(request), |observed| { updates.send_replace(observed); }, ) .await; }); Self { workspaces: Some(workspaces), task: Some(AbortOnDropHandle::new(task)), admission: Some(admission), } } } #[derive(Debug)] pub(crate) struct TurnMetadataState { cwd: AbsolutePathBuf, session_id: String, thread_id: String, agent_name: String, forked_from_thread_id: Option, parent_thread_id: Option, parent_turn_id: OnceLock, initiating_agent_path: OnceLock, root_turn_id: OnceLock, subagent_header: Option, subagent_kind: Option, thread_source: Option, turn_trigger: OnceLock, turn_id: String, // TODO(anp): Derive this cached tag from TurnEnvironment::sandbox_context // so metadata reflects the selected environment's backend. pub(crate) sandbox_tags: SandboxTags, auto_review_enabled: bool, node_repl_auto_review_required: bool, node_repl_disabled: bool, git_enrichment: Mutex, turn_started_at_unix_ms: RwLock>, responses_api_metadata: RwLock>, responsesapi_client_metadata: RwLock>, user_input_requested_during_turn: AtomicBool, } impl codex_analytics::TurnAnalyticsMetadata for TurnMetadataState { fn root_turn_id(&self) -> Option { TurnMetadataState::root_turn_id(self) } fn turn_trigger(&self) -> Option { self.turn_trigger .get() .filter(|trigger| trigger.len() <= MAX_EXTRA_METADATA_VALUE_BYTES) .cloned() } fn codex_turn_source(&self) -> Option { // Match Responses metadata precedence without copying oversized client values to analytics. let configured_metadata = self .responses_api_metadata .read() .unwrap_or_else(std::sync::PoisonError::into_inner); let client_metadata = self .responsesapi_client_metadata .read() .unwrap_or_else(std::sync::PoisonError::into_inner); configured_metadata .get("source") .or_else(|| client_metadata.get("source")) .filter(|source| source.len() <= MAX_EXTRA_METADATA_VALUE_BYTES) .cloned() } } impl TurnMetadataState { #[allow(clippy::too_many_arguments)] pub(crate) fn new( session_id: String, thread_id: String, forked_from_thread_id: Option, parent_thread_id: Option, session_source: &SessionSource, thread_source: Option, turn_id: String, cwd: AbsolutePathBuf, permission_profile: &PermissionProfile, windows_sandbox_selection: impl Into, enforce_managed_network: bool, auto_review_enabled: bool, model_info: &ModelInfo, ) -> Self { let sandbox_tags = SandboxTags::new( permission_profile, cwd.as_path(), windows_sandbox_selection.into(), enforce_managed_network, ); let agent_name = session_source .get_agent_path() .unwrap_or_else(AgentPath::root) .to_string(); Self { cwd, session_id, thread_id, agent_name, forked_from_thread_id, parent_thread_id, parent_turn_id: OnceLock::new(), initiating_agent_path: OnceLock::new(), root_turn_id: OnceLock::new(), subagent_header: subagent_header_value(session_source), subagent_kind: subagent_metadata_kind(session_source), thread_source, turn_trigger: OnceLock::new(), turn_id, sandbox_tags, auto_review_enabled, node_repl_auto_review_required: model_info.computer_use_review_required(), node_repl_disabled: model_info.node_repl_disabled, git_enrichment: Mutex::default(), turn_started_at_unix_ms: RwLock::new(None), responses_api_metadata: RwLock::new(BTreeMap::new()), responsesapi_client_metadata: RwLock::new(BTreeMap::new()), user_input_requested_during_turn: AtomicBool::new(false), } } pub(crate) fn current_meta_value_for_mcp_request( &self, execution: ExecutionMetadata<'_>, ) -> Option { self.current_meta_value_for_tool_request(self.mcp_metadata_template(), execution) } pub(crate) fn current_meta_value_for_extension_request( &self, execution: ExecutionMetadata<'_>, ) -> Option { // Native extensions need configured Responses metadata for request attribution, // which the MCP template omits for external servers. self.current_meta_value_for_tool_request(self.responses_metadata_template(), execution) } fn current_meta_value_for_tool_request( &self, mut responses_metadata: CodexResponsesMetadata, execution: ExecutionMetadata<'_>, ) -> Option { if responses_metadata .extra .get("misalignment_override") .is_some_and(|value| is_targeted_continuation(value)) { // A review target is for Responses admission, not external tools or hooks. responses_metadata.extra.remove("misalignment_override"); } execution.apply_to(&mut responses_metadata); // Never serialize harness-owned tool inventory for tool requests. responses_metadata.tool_namespaces_info = None; let Value::Object(mut metadata) = responses_metadata.turn_metadata_value()? else { return None; }; metadata.remove(AGENT_NAME_KEY); metadata.remove(PARENT_TURN_ID_KEY); metadata.remove(ROOT_TURN_ID_KEY); metadata.insert( CODEX_VERSION_KEY.to_string(), Value::String(env!("CARGO_PKG_VERSION").to_string()), ); if self .user_input_requested_during_turn .load(Ordering::Relaxed) { metadata.insert( USER_INPUT_REQUESTED_DURING_TURN_KEY.to_string(), Value::Bool(true), ); } else { metadata.remove(USER_INPUT_REQUESTED_DURING_TURN_KEY); } Some(Value::Object(metadata)) } pub(crate) fn to_responses_metadata( &self, installation_id: String, window_id: String, request_kind: CodexResponsesRequestKind, ) -> CodexResponsesMetadata { let mut metadata = self.responses_metadata_template(); if matches!(request_kind, CodexResponsesRequestKind::Compaction(_)) && metadata .extra .get("misalignment_override") .is_some_and(|value| is_targeted_continuation(value)) { // Target-based intent belongs to the pending turn, not compaction. Preserve the // legacy timestamp path until servers can admit pre-turn compaction separately. metadata.extra.remove("misalignment_override"); } CodexResponsesMetadata { installation_id, window_id, request_kind: Some(request_kind), ..metadata } } pub(crate) fn mark_user_input_requested_during_turn(&self) { self.user_input_requested_during_turn .store(true, Ordering::Relaxed); } pub(crate) fn set_parent_turn_id(&self, parent_turn_id: String) { if parent_turn_id.trim().is_empty() { return; } let _ = self.parent_turn_id.set(parent_turn_id); } pub(crate) fn parent_turn_id(&self) -> Option { self.parent_turn_id.get().cloned() } pub(crate) fn set_initiating_agent_path(&self, initiating_agent_path: AgentPath) { let _ = self.initiating_agent_path.set(initiating_agent_path); } pub(crate) fn initiating_agent_path(&self) -> Option<&AgentPath> { self.initiating_agent_path.get() } pub(crate) fn set_root_turn_id(&self, root_turn_id: String) { if root_turn_id.trim().is_empty() { return; } let _ = self.root_turn_id.set(root_turn_id); } pub(crate) fn set_turn_trigger(&self, turn_trigger: String) { if turn_trigger.trim().is_empty() { return; } let _ = self.turn_trigger.set(turn_trigger); } pub(crate) fn current_turn_trigger(&self) -> Option { self.turn_trigger.get().cloned() } pub(crate) fn root_turn_id(&self) -> Option { self.root_turn_id.get().cloned() } pub(crate) fn apply_start_responsesapi_client_metadata( &self, update: ResponsesApiClientMetadataUpdate, ) { self.update_responsesapi_client_metadata(update); } /// Capture client attribution without carrying the parent's review or routing intent. pub(crate) fn client_metadata_for_child(&self) -> HashMap { self.responsesapi_client_metadata .read() .unwrap_or_else(std::sync::PoisonError::into_inner) .iter() .filter(|(key, _)| { !matches!( key.as_str(), "misalignment_override" | "parent_response_id" | "mcp_request_meta" ) }) .map(|(key, value)| (key.clone(), value.clone())) .collect() } pub(crate) fn update_responsesapi_client_metadata( &self, update: ResponsesApiClientMetadataUpdate, ) { let replacement = update.replacement.map(filter_extra_metadata); let patch = update.patch.map(filter_extra_metadata).unwrap_or_default(); if replacement.is_none() && patch.is_empty() { return; } let mut current = self .responsesapi_client_metadata .write() .unwrap_or_else(std::sync::PoisonError::into_inner); let continuation = current .get("misalignment_override") .filter(|value| is_targeted_continuation(value)) .cloned(); if let Some(replacement) = replacement { *current = replacement; } current.extend(patch); if let Some(continuation) = continuation { // Steering may update other metadata, but cannot replace the reviewed block. current.insert("misalignment_override".to_string(), continuation); } } pub(crate) fn set_responses_api_metadata( &self, responses_api_metadata: BTreeMap, ) { let mut metadata = filter_extra_metadata(responses_api_metadata); // Only explicit per-turn metadata can acknowledge a reviewed block. metadata.remove("misalignment_override"); *self .responses_api_metadata .write() .unwrap_or_else(std::sync::PoisonError::into_inner) = metadata; } pub(crate) fn workspace_kind(&self) -> Option { self.responsesapi_client_metadata .read() .unwrap_or_else(std::sync::PoisonError::into_inner) .get(WORKSPACE_KIND_KEY) .cloned() } fn responses_metadata_template(&self) -> CodexResponsesMetadata { let mut metadata = self.mcp_metadata_template(); if metadata.parent_thread_id.is_some() { metadata.forked_from_thread_id = None; } metadata.extra.extend( self.responses_api_metadata .read() .unwrap_or_else(std::sync::PoisonError::into_inner) .clone(), ); metadata } fn mcp_metadata_template(&self) -> CodexResponsesMetadata { let mut extra = self .responsesapi_client_metadata .read() .unwrap_or_else(std::sync::PoisonError::into_inner) .clone(); // Extract Guardian's internal parent before filtering configured metadata keys. // Ordinary app-server client metadata stays in `extra`. let parent_response_id = if self.subagent_header.as_deref() == Some(crate::guardian::GUARDIAN_REVIEWER_NAME) { extra.remove("parent_response_id") } else { None }; for key in self .responses_api_metadata .read() .unwrap_or_else(std::sync::PoisonError::into_inner) .keys() { extra.remove(key); } let mut metadata = CodexResponsesMetadata { parent_response_id, turn_id: Some(self.turn_id.clone()), agent_name: Some(self.agent_name.clone()), forked_from_thread_id: self.forked_from_thread_id, parent_thread_id: self.parent_thread_id, parent_turn_id: self.parent_turn_id.get().cloned(), root_turn_id: self.root_turn_id(), subagent_header: self.subagent_header.clone(), subagent_kind: self.subagent_kind.clone(), thread_source: self.thread_source.clone(), turn_trigger: self.turn_trigger.get().cloned(), auto_review_enabled: Some(self.auto_review_enabled), node_repl_auto_review_required: Some(self.node_repl_auto_review_required), node_repl_disabled: Some(self.node_repl_disabled), workspaces: self.current_workspaces(), tool_namespaces_info: None, turn_started_at_unix_ms: self.current_turn_started_at_unix_ms(), extra, ..CodexResponsesMetadata::new( String::new(), self.session_id.clone(), self.thread_id.clone(), String::new(), ) }; self.sandbox_tags.record_metadata(&mut metadata); metadata } fn current_workspaces(&self) -> BTreeMap { self.git_enrichment .lock() .unwrap_or_else(std::sync::PoisonError::into_inner) .workspaces .as_ref() .map(|workspaces| workspaces.borrow().clone()) .unwrap_or_default() } fn current_turn_started_at_unix_ms(&self) -> Option { *self .turn_started_at_unix_ms .read() .unwrap_or_else(std::sync::PoisonError::into_inner) } pub(crate) fn set_turn_started_at_unix_ms(&self, turn_started_at_unix_ms: i64) { *self .turn_started_at_unix_ms .write() .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(turn_started_at_unix_ms); } pub(crate) fn set_git_enrichment(&self, enrichment: TurnGitEnrichment) { *self .git_enrichment .lock() .unwrap_or_else(std::sync::PoisonError::into_inner) = enrichment; } pub(crate) fn spawn_git_enrichment_task(&self, git_root_discovery: Arc) { let mut enrichment = self .git_enrichment .lock() .unwrap_or_else(std::sync::PoisonError::into_inner); if enrichment.task.is_none() { *enrichment = TurnGitEnrichment::start(self.cwd.clone(), git_root_discovery); } } pub(crate) async fn wait_for_git_enrichment(&self) { let workspaces = self .git_enrichment .lock() .unwrap_or_else(std::sync::PoisonError::into_inner) .workspaces .clone(); if let Some(mut workspaces) = workspaces { // Only the collector owns a sender. Completion and cancellation both close it. while workspaces.changed().await.is_ok() {} } } pub(crate) fn admit_git_enrichment(&self) { let admission = self .git_enrichment .lock() .unwrap_or_else(std::sync::PoisonError::into_inner) .admission .take(); if let Some(admission) = admission { let _ = admission.send(()); } } pub(crate) fn cancel_git_enrichment_task(&self) { self.git_enrichment .lock() .unwrap_or_else(std::sync::PoisonError::into_inner) .task .take(); } } async fn memory_workspaces( cwd: &AbsolutePathBuf, repo_root: impl Future>, ) -> BTreeMap { let mut workspaces = BTreeMap::new(); let collect = collect_git_workspaces( cwd, repo_root, GitCollectionAdmission::Immediate, |observed| workspaces = observed, ); let _ = tokio::time::timeout(MEMORY_GIT_METADATA_TIMEOUT, collect).await; workspaces } async fn collect_git_workspaces( cwd: &AbsolutePathBuf, repo_root: impl Future>, admission: GitCollectionAdmission, mut publish: impl FnMut(BTreeMap), ) { let Some(repo_root) = repo_root.await else { return; }; let workspace_key = repo_root.to_string_lossy().into_owned(); let status = collect_git_status_after_admission(admission, get_worktree_status_in_repo(cwd, &repo_root)); collect_workspace_git_metadata( get_head_state(cwd), |updates| async move { observe_git_remote_urls(cwd, &updates).await }, status, |workspace| { publish(BTreeMap::from([(workspace_key.clone(), workspace)])); }, ) .await; } enum GitCollectionAdmission { Immediate, Pending(oneshot::Receiver<()>), } async fn collect_git_status_after_admission( admission: GitCollectionAdmission, status: impl Future>, ) -> Option { if let GitCollectionAdmission::Pending(request) = admission && request.await.is_err() { return None; } status.await } async fn collect_workspace_git_metadata>( head: impl Future, collect_remotes: impl FnOnce(watch::Sender>) -> R, status: impl Future>, mut publish: impl FnMut(TurnMetadataWorkspace), ) { let (updates, mut remotes) = watch::channel(BTreeMap::new()); let observe = async { let mut head = std::pin::pin!(head.fuse()); let mut status = std::pin::pin!(status.fuse()); let mut head_state = GitHeadState::Unavailable; let mut observed_status = None; let mut latest_git_commit_hash = None; let mut has_changes = None; let mut observed_remote_urls = false; loop { let mut changed = tokio::select! { result = &mut head, if !head.is_terminated() => { head_state = result; if let GitHeadState::Commit(sha) = &head_state { latest_git_commit_hash = Some(sha.0.clone()); } latest_git_commit_hash.is_some() } Ok(()) = remotes.changed() => { observed_remote_urls = true; true } result = &mut status, if !status.is_terminated() => { observed_status = result; false } else => break, }; // A shared scan can be stale. Use its HEAD and status together when // the independent lookup failed, but reject a conflicting known HEAD. if head.is_terminated() && let Some(observed) = observed_status.take() { let matches_head = match &head_state { GitHeadState::Commit(sha) => observed.head_commit_hash.as_ref() == Some(sha), GitHeadState::Missing => observed.head_commit_hash.is_none(), GitHeadState::Unavailable => true, }; if matches_head { latest_git_commit_hash = observed.head_commit_hash.map(|sha| sha.0); has_changes = Some(observed.has_changes); changed = true; } } if changed { publish(TurnMetadataWorkspace { associated_remote_urls: observed_remote_urls .then(|| remotes.borrow_and_update().clone()), latest_git_commit_hash: latest_git_commit_hash.clone(), has_changes, }); } } }; tokio::join!(collect_remotes(updates), observe); } #[cfg(test)] #[path = "turn_metadata_tests.rs"] mod tests;