Lightweight coding agent that runs in your terminal
Rust
use rand::Rng;
use std::cmp::Reverse;
use std::collections::HashMap;
use std::collections::HashSet;
use std::num::NonZeroUsize;
use std::sync::Arc;
use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering;
use tokio::sync::watch;
use tokio::time::Duration;
use tokio::time::Instant;
use tokio_util::sync::CancellationToken;
use uuid::Uuid;
use super::oneshot::Completion;
use super::process::OutputDrainPolicy;
use crate::codex_thread::BackgroundTerminalInfo;
use crate::exec_env::CODEX_PERMISSION_PROFILE_ENV_VAR;
use crate::exec_env::CODEX_THREAD_ID_ENV_VAR;
use crate::exec_env::CODEX_VERSION_ENV_VAR;
use crate::exec_env::create_env;
use crate::exec_env::inject_apply_patch_env;
use crate::exec_env::inject_permission_profile_env;
use crate::exec_env::inject_session_env;
use crate::exec_env::set_tool_call_id_env_var;
use crate::exec_policy::ExecApprovalRequest;
use crate::guardian::GuardianReviewContext;
use crate::plugins::metrics::finish_and_track_measurements;
use crate::sandboxing::ExecOptions;
use crate::sandboxing::ExecRequest;
use crate::sandboxing::ExecServerEnvConfig;
use crate::tools::ApprovalContext;
use crate::tools::context::ExecCommandToolOutput;
use crate::tools::events::ToolEmitter;
use crate::tools::events::ToolEventCtx;
use crate::tools::events::ToolEventStage;
use crate::tools::network_approval::DeferredNetworkApproval;
use crate::tools::network_approval::finish_deferred_network_approval;
use crate::tools::orchestrator::ToolOrchestrator;
use crate::tools::runtimes::is_managed_proxy_env_var;
use crate::tools::runtimes::unified_exec::UnifiedExecAttempt;
use crate::tools::runtimes::unified_exec::UnifiedExecRequest as UnifiedExecToolRequest;
use crate::tools::runtimes::unified_exec::UnifiedExecRuntime;
use crate::tools::sandboxing::SandboxAttempt;
use crate::tools::sandboxing::ToolCtx;
use crate::tools::sandboxing::ToolError;
use crate::unified_exec::ExecCommandRequest;
use crate::unified_exec::MAX_UNIFIED_EXEC_PROCESSES;
use crate::unified_exec::MAX_YIELD_TIME_MS;
use crate::unified_exec::MIN_EMPTY_YIELD_TIME_MS;
use crate::unified_exec::MIN_YIELD_TIME_MS;
use crate::unified_exec::ProcessEntry;
use crate::unified_exec::ProcessStore;
use crate::unified_exec::TerminalSession;
use crate::unified_exec::UnifiedExecContext;
use crate::unified_exec::UnifiedExecError;
use crate::unified_exec::UnifiedExecProcessManager;
use crate::unified_exec::WriteStdinInteractionEvent;
use crate::unified_exec::WriteStdinRequest;
use crate::unified_exec::async_watcher::emit_exec_end_for_unified_exec;
use crate::unified_exec::async_watcher::emit_failed_exec_end_for_unified_exec;
use crate::unified_exec::async_watcher::spawn_exit_watcher;
use crate::unified_exec::async_watcher::start_streaming_output;
use crate::unified_exec::clamp_yield_time;
use crate::unified_exec::generate_chunk_id;
use crate::unified_exec::head_tail_buffer::HeadTailBuffer;
use crate::unified_exec::process::OutputBuffers;
use crate::unified_exec::process::OutputHandles;
use crate::unified_exec::process::UnifiedExecProcess;
use crate::unified_exec::shell_snapshot::shell_snapshot_request;
use crate::unified_exec::take_plugin_metrics_sidecar;
use crate::unified_exec::trace_id;
use crate::windows_sandbox::windows_sandbox_level_for_legacy_checks;
use codex_core_plugins::PLUGIN_METRICS_OUTPUT_ENV_VAR;
use codex_core_plugins::PluginCommandAttribution;
use codex_core_plugins::PluginMetricsSidecar;
use codex_core_plugins::strip_output_env;
use codex_network_proxy::NetworkPolicyDecider;
use codex_network_proxy::NetworkProxy;
use codex_protocol::config_types::ShellEnvironmentPolicy;
use codex_protocol::error::CodexErr;
use codex_protocol::error::CodexErrorDetails;
use codex_protocol::error::SandboxErr;
use codex_protocol::protocol::EventMsg;
use codex_protocol::protocol::ExecCommandSource;
use codex_protocol::protocol::TerminalInteractionEvent;
use codex_protocol::shell_environment::is_non_inheritable_env_var;
use codex_sandboxing::SandboxCommand;
use codex_shell_command::is_dangerous_command::DangerousCommandPlatform;
use codex_tools::ToolName;
use codex_utils_output_truncation::approx_tokens_from_byte_count;
use codex_utils_path_uri::PathUri;
const UNIFIED_EXEC_ENV: [(&str, &str); 10] = [
("NO_COLOR", "1"),
("TERM", "dumb"),
("LANG", "C.UTF-8"),
("LC_CTYPE", "C.UTF-8"),
("LC_ALL", "C.UTF-8"),
("COLORTERM", ""),
("PAGER", "cat"),
("GIT_PAGER", "cat"),
("GH_PAGER", "cat"),
("CODEX_CI", "1"),
];
const NETWORK_ACCESS_DENIED_MESSAGE: &str =
"Network access was denied by the Codex sandbox network proxy.";
const LATE_NETWORK_DENIAL_GRACE_PERIOD: Duration = Duration::from_millis(100);
const MAX_STDIN_APPROVAL_BYTES: usize = 8_000;
const INTERRUPT: &str = "\u{3}";
/// Test-only override for deterministic unified exec process IDs.
///
/// In production builds this value should remain at its default (`false`) and
/// must not be toggled.
static FORCE_DETERMINISTIC_PROCESS_IDS: AtomicBool = AtomicBool::new(false);
pub(super) fn set_deterministic_process_ids_for_tests(enabled: bool) {
FORCE_DETERMINISTIC_PROCESS_IDS.store(enabled, Ordering::Relaxed);
}
fn deterministic_process_ids_forced_for_tests() -> bool {
FORCE_DETERMINISTIC_PROCESS_IDS.load(Ordering::Relaxed)
}
pub(super) fn should_use_deterministic_process_ids() -> bool {
cfg!(test) || deterministic_process_ids_forced_for_tests()
}
pub(super) fn apply_unified_exec_env(mut env: HashMap<String, String>) -> HashMap<String, String> {
for (key, value) in UNIFIED_EXEC_ENV {
env.insert(key.to_string(), value.to_string());
}
env
}
pub(crate) fn exec_env_policy_from_shell_policy(
policy: &ShellEnvironmentPolicy,
) -> codex_exec_server::ExecEnvPolicy {
let mut exclude = policy
.exclude
.iter()
.map(std::string::ToString::to_string)
.collect::<Vec<_>>();
exclude.extend([
CODEX_PERMISSION_PROFILE_ENV_VAR.to_string(),
CODEX_VERSION_ENV_VAR.to_string(),
codex_apply_patch::CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR.to_string(),
PLUGIN_METRICS_OUTPUT_ENV_VAR.to_string(),
]);
let mut r#set = policy.r#set.clone();
r#set.retain(|key, _| {
![
CODEX_PERMISSION_PROFILE_ENV_VAR,
CODEX_VERSION_ENV_VAR,
codex_apply_patch::CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR,
PLUGIN_METRICS_OUTPUT_ENV_VAR,
]
.iter()
.any(|runtime_key| key.eq_ignore_ascii_case(runtime_key))
&& !is_non_inheritable_env_var(key)
});
codex_exec_server::ExecEnvPolicy {
inherit: policy.inherit.clone(),
ignore_default_excludes: policy.ignore_default_excludes,
exclude,
r#set,
include_only: policy
.include_only
.iter()
.map(std::string::ToString::to_string)
.collect(),
}
}
fn env_overlay_for_exec_server(
request_env: &HashMap<String, String>,
local_policy_env: &HashMap<String, String>,
) -> HashMap<String, String> {
request_env
.iter()
.filter(|(key, value)| {
!is_non_inheritable_env_var(key)
&& (matches!(
key.as_str(),
CODEX_PERMISSION_PROFILE_ENV_VAR
| CODEX_VERSION_ENV_VAR
| codex_apply_patch::CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR
) || local_policy_env.get(*key) != Some(*value))
})
.map(|(key, value)| (key.clone(), value.clone()))
.collect()
}
fn exec_server_env_for_request(
request: &ExecRequest,
) -> (
Option<codex_exec_server::ExecEnvPolicy>,
HashMap<String, String>,
) {
if let Some(exec_server_env_config) = &request.exec_server_env_config {
let mut env =
env_overlay_for_exec_server(&request.env, &exec_server_env_config.local_policy_env);
if request.exec_server_shell_snapshot.is_some()
&& !exec_server_env_config.policy.r#set.contains_key("PATH")
{
env.remove("PATH");
}
if request.exec_server_managed_network.is_some() {
for (key, value) in &request.env {
if is_managed_proxy_env_var(key, value) {
env.insert(key.clone(), value.clone());
}
}
}
(Some(exec_server_env_config.policy.clone()), env)
} else {
(None, request.env.clone())
}
}
fn exec_server_params_for_request(
process_id: i32,
request: &ExecRequest,
tool_ctx: Option<&ToolCtx>,
windows_sandbox_proxy_settings_mode: codex_sandboxing::WindowsSandboxProxySettingsMode,
tty: bool,
) -> codex_exec_server::ExecParams {
let (env_policy, env) = exec_server_env_for_request(request);
let sandbox = request.exec_server_sandbox.clone().map(|mut sandbox| {
sandbox.windows_sandbox_proxy_settings_mode = Some(windows_sandbox_proxy_settings_mode);
sandbox
});
// Threads sharing an executor and sandbox retries can reuse a public handle
// while the executor still retains its previous process.
let exec_server_process_id = format!("{process_id}-{}", Uuid::new_v4());
codex_exec_server::ExecParams {
process_id: exec_server_process_id.into(),
metadata: tool_ctx.map(|ctx| codex_exec_server::ExecMetadata {
thread_id: Some(ctx.session.thread_id()),
tool_call_id: Some(ctx.call_id.clone()),
}),
argv: request.command.clone(),
cwd: request.cwd.clone(),
env_policy,
shell_snapshot: request.exec_server_shell_snapshot.clone(),
env,
tty,
pipe_stdin: false,
arg0: request.arg0.clone(),
sandbox,
enforce_managed_network: request.exec_server_enforce_managed_network,
managed_network: request.exec_server_managed_network.clone(),
network_proxy: request.exec_server_network_proxy.clone(),
}
}
/// Borrowed process state prepared for a `write_stdin` or poll operation.
struct PreparedProcessHandles {
process: Arc<UnifiedExecProcess>,
output: OutputHandles,
pause_state: Option<watch::Receiver<bool>>,
session: Option<Arc<crate::session::session::Session>>,
network_approval: Option<DeferredNetworkApproval>,
call_id: String,
hook_command: String,
process_id: i32,
tty: bool,
}
struct InitialExecCommandGuard {
active: Option<Arc<AtomicBool>>,
metrics_sidecar: Option<PluginMetricsSidecar>,
collection_finished: CancellationToken,
}
impl InitialExecCommandGuard {
async fn finish_plugin_metrics(&mut self, context: &UnifiedExecContext, exit_code: i32) {
let model_context = context.step_context.model_context();
finish_and_track_measurements(
self.metrics_sidecar.take(),
exit_code,
&context.session,
&context.step_context.turn,
&model_context,
&context.call_id,
)
.await;
}
}
impl Drop for InitialExecCommandGuard {
fn drop(&mut self) {
if let Some(active) = self.active.as_ref() {
active.store(false, Ordering::Release);
}
self.collection_finished.cancel();
}
}
async fn unregister_network_approval_for_entry(entry: &ProcessEntry) {
if let Some(network_approval) = entry.network_approval.as_ref()
&& let Some(session) = entry.session.upgrade()
{
session
.services
.network_approval
.unregister_call(network_approval.registration_id())
.await;
}
}
async fn finish_network_approval_after_process_exit_for_entry(
entry: &ProcessEntry,
) -> Result<(), String> {
let session = entry.session.upgrade();
finish_deferred_network_approval_after_process_exit_for_session(
session.as_ref(),
entry.network_approval.clone(),
)
.await
}
async fn finish_deferred_network_approval_for_session(
session: Option<&Arc<crate::session::session::Session>>,
deferred: Option<DeferredNetworkApproval>,
) -> Result<(), String> {
let Some(session) = session else {
return Ok(());
};
finish_deferred_network_approval(session.as_ref(), deferred)
.await
.map_err(network_approval_error_message)
}
fn network_approval_error_message(err: ToolError) -> String {
match err {
ToolError::Rejected(message) => message,
ToolError::Codex(err) => err.to_string(),
}
}
async fn network_denial_message_for_session(
session: Option<&Arc<crate::session::session::Session>>,
deferred: Option<DeferredNetworkApproval>,
) -> String {
let Some(session) = session else {
return NETWORK_ACCESS_DENIED_MESSAGE.to_string();
};
match finish_deferred_network_approval(session.as_ref(), deferred).await {
Ok(()) => NETWORK_ACCESS_DENIED_MESSAGE.to_string(),
Err(err) => network_approval_error_message(err),
}
}
async fn wait_for_late_network_denial(network_cancelled: Option<CancellationToken>) -> bool {
let Some(network_cancelled) = network_cancelled else {
return false;
};
if network_cancelled.is_cancelled() {
return true;
}
tokio::select! {
_ = network_cancelled.cancelled() => true,
_ = tokio::time::sleep(LATE_NETWORK_DENIAL_GRACE_PERIOD) => false,
}
}
async fn finish_deferred_network_approval_after_process_exit_for_session(
session: Option<&Arc<crate::session::session::Session>>,
deferred: Option<DeferredNetworkApproval>,
) -> Result<(), String> {
wait_for_late_network_denial(
deferred
.as_ref()
.map(DeferredNetworkApproval::cancellation_token),
)
.await;
finish_deferred_network_approval_for_session(session, deferred).await
}
fn fail_process_with_message(process: &UnifiedExecProcess, message: String) -> UnifiedExecError {
if let Some(message) = process.failure_message() {
process.terminate();
return UnifiedExecError::process_failed(message);
}
process.fail_and_terminate(message.clone());
UnifiedExecError::process_failed(process.failure_message().unwrap_or(message))
}
#[allow(clippy::too_many_arguments)]
async fn emit_failed_initial_exec_end_if_unstored(
process_stored: bool,
sandbox_type: Option<codex_protocol::sandbox::SandboxType>,
context: &UnifiedExecContext,
request: &ExecCommandRequest,
cwd: PathUri,
plugin_attribution: Option<PluginCommandAttribution>,
output_buffer: Arc<tokio::sync::Mutex<OutputBuffers>>,
fallback_output: String,
message: String,
wall_time: Duration,
) {
if process_stored {
return;
}
emit_failed_exec_end_for_unified_exec(
sandbox_type,
Arc::clone(&context.session),
Arc::clone(&context.step_context.turn),
Arc::clone(&context.step_context.settings.model_info),
context.call_id.clone(),
request.command.clone(),
cwd,
Some(request.process_id.to_string()),
plugin_attribution,
output_buffer,
fallback_output,
message,
wall_time,
)
.await;
}
fn terminate_process_on_network_denial(
process: Arc<UnifiedExecProcess>,
session: std::sync::Weak<crate::session::session::Session>,
deferred: DeferredNetworkApproval,
) -> tokio::task::JoinHandle<()> {
let network_cancelled = deferred.cancellation_token();
let process_exited = process.cancellation_token();
tokio::spawn(async move {
let denied = tokio::select! {
_ = network_cancelled.cancelled() => true,
_ = process_exited.cancelled() => {
wait_for_late_network_denial(Some(network_cancelled.clone())).await
}
};
if !denied {
return;
}
let session = session.upgrade();
let message = network_denial_message_for_session(session.as_ref(), Some(deferred)).await;
process.fail_and_terminate(message);
})
}
impl UnifiedExecProcessManager {
pub(crate) async fn allocate_process_id(&self) -> i32 {
loop {
let mut store = self.process_store.lock().await;
let process_id = if should_use_deterministic_process_ids() {
// test or deterministic mode
store
.reserved_process_ids
.iter()
.copied()
.max()
.map(|m| std::cmp::max(m, 999) + 1)
.unwrap_or(1000)
} else {
// production mode → random
rand::rng().random_range(1_000..100_000)
};
if store.reserved_process_ids.contains(&process_id) {
continue;
}
store.reserved_process_ids.insert(process_id);
return process_id;
}
}
pub(crate) async fn release_process_id(&self, process_id: i32) {
self.release_process(process_id, /*expected_process*/ None)
.await;
}
async fn release_process(
&self,
process_id: i32,
expected_process: Option<&Arc<UnifiedExecProcess>>,
) {
let removed = {
let mut store = self.process_store.lock().await;
if let Some(expected) = expected_process
&& !store
.processes
.get(&process_id)
.is_some_and(|entry| Arc::ptr_eq(&entry.process, expected))
{
return;
}
store.remove(process_id)
};
if let Some(entry) = removed {
unregister_network_approval_for_entry(&entry).await;
}
}
#[tracing::instrument(
name = "unified_exec.exec_command",
level = "info",
skip_all,
fields(
conversation.id = %context.session.thread_id,
turn_id = trace_id(&context.step_context.turn.sub_id),
call_id = trace_id(&context.call_id),
unified_exec_process_id = request.process_id,
mode = "resumable",
outcome = tracing::field::Empty,
)
)]
pub(crate) async fn exec_command(
&self,
request: ExecCommandRequest,
context: &UnifiedExecContext,
) -> Result<ExecCommandToolOutput, UnifiedExecError> {
let result = self
.exec_command_inner(request, context, /*completion*/ None)
.await;
let outcome = match &result {
Ok(output) if output.process_id.is_some() => "yielded",
Ok(_) => "exited",
Err(_) if context.cancellation_token.is_cancelled() => "cancelled",
Err(_) => "failed",
};
tracing::Span::current().record("outcome", outcome);
result
}
pub(super) async fn exec_command_inner(
&self,
request: ExecCommandRequest,
context: &UnifiedExecContext,
mut completion: Option<&mut Completion<'_>>,
) -> Result<ExecCommandToolOutput, UnifiedExecError> {
let cwd = request.cwd.clone();
let process = self
.open_session_with_sandbox(&request, cwd.clone(), context)
.await;
let (attempt, mut deferred_network_approval) = match process {
Ok((attempt, deferred_network_approval)) => (attempt, deferred_network_approval),
Err(err) => {
self.release_process_id(request.process_id).await;
return Err(err);
}
};
let UnifiedExecAttempt {
process,
metrics_sidecar,
permissions,
} = attempt;
let process = Arc::new(process);
if let Some(completion) = completion.as_ref() {
let _ = completion.process.set(Arc::clone(&process));
}
let network_denial_monitor = deferred_network_approval.as_ref().map(|deferred| {
terminate_process_on_network_denial(
Arc::clone(&process),
Arc::downgrade(&context.session),
deferred.clone(),
)
});
let output_buffer = Arc::clone(&process.output_handles().output_buffer);
let model_context = context.step_context.model_context();
let mut event_ctx = ToolEventCtx::new(
context.session.as_ref(),
context.step_context.turn.as_ref(),
&context.step_context.settings.model_info,
&context.call_id,
/*turn_diff_tracker*/ None,
);
event_ctx.model_context = Some(&model_context);
let plugin_attribution = if request.turn_environment.environment.is_remote() {
let file_system = request.turn_environment.environment.get_filesystem();
context
.step_context
.turn
.plugin_attribution_for_executor_command(
&request.command,
&cwd,
file_system.as_ref(),
)
.await
} else {
cwd.to_abs_path().ok().and_then(|cwd| {
context
.step_context
.turn
.plugin_attribution_for_command(&request.command, &cwd)
})
};
let emitter = ToolEmitter::unified_exec(
&request.command,
cwd.clone(),
ExecCommandSource::UnifiedExecStartup,
Some(request.process_id.to_string()),
plugin_attribution.clone(),
);
emitter.emit(event_ctx, ToolEventStage::Begin).await;
// Serialize remote collection with later polls and final transcript publication.
let _interaction_guard =
if process.output_handles().drain_policy == OutputDrainPolicy::WaitForOutputClosure {
Some(process.interaction_lock().lock_owned().await)
} else {
None
};
start_streaming_output(&process, context);
let start = Instant::now();
// Persist live sessions and remote output that remains pollable after an early exit.
let process_stored = (!process.has_exited() && process.exit_code().is_none())
|| (process.output_handles().drain_policy == OutputDrainPolicy::WaitForOutputClosure
&& !process
.output_handles()
.output_closed
.load(Ordering::Acquire));
let mut initial_exec_command_guard = InitialExecCommandGuard {
active: None,
metrics_sidecar,
collection_finished: process.output_handles().collection_finished.clone(),
};
if process_stored {
let initial_exec_command_active = Arc::new(AtomicBool::new(true));
initial_exec_command_guard.active = Some(Arc::clone(&initial_exec_command_active));
self.store_process(
Arc::clone(&process),
context,
&request.command,
request.hook_command.clone(),
cwd.clone(),
request.turn_environment.selection.environment_id.clone(),
permissions,
plugin_attribution.clone(),
start,
request.process_id,
request.tty,
deferred_network_approval.clone(),
network_denial_monitor,
initial_exec_command_guard.metrics_sidecar.take(),
Arc::clone(&output_buffer),
Arc::clone(&initial_exec_command_active),
)
.await;
}
let yield_time_ms = clamp_yield_time(request.yield_time_ms);
// For the initial exec_command call, we both stream output to events
// (via start_streaming_output above) and collect a snapshot here for
// the tool response body.
let wait = completion.as_ref().map_or_else(
|| Duration::from_millis(yield_time_ms),
|completion| completion.timeout,
);
let deadline = start
.checked_add(wait)
.ok_or_else(|| UnifiedExecError::process_failed("timeout_ms is too large".into()))?;
let collected_output = Self::collect_output_until_deadline(
process.output_handles(),
Some(context.session.subscribe_elicitation_pause_state()),
deadline,
)
.await;
if let Some(completion) = completion.as_mut()
&& !process.has_exited()
{
completion.timed_out = true;
process.mark_timed_out();
if let Err(err) = process.terminate_confirmed().await {
process.fail_and_terminate(err.to_string());
}
}
let wall_time = Instant::now().saturating_duration_since(start);
let original_token_count = usize::try_from(approx_tokens_from_byte_count(
collected_output.total_bytes(),
))
.unwrap_or(usize::MAX);
let output_omitted_bytes = NonZeroUsize::new(collected_output.omitted_bytes());
let collected = collected_output.to_bytes_with_omission_marker();
let text = String::from_utf8_lossy(&collected).to_string();
let chunk_id = generate_chunk_id();
if deferred_network_approval
.as_ref()
.is_some_and(DeferredNetworkApproval::is_cancelled)
{
let message = network_denial_message_for_session(
Some(&context.session),
deferred_network_approval.take(),
)
.await;
emit_failed_initial_exec_end_if_unstored(
process_stored,
process.sandbox_type(),
context,
&request,
cwd.clone(),
plugin_attribution.clone(),
Arc::clone(&output_buffer),
text.clone(),
message.clone(),
wall_time,
)
.await;
self.release_process_id(request.process_id).await;
return Err(fail_process_with_message(process.as_ref(), message));
}
if let Some(message) = process.failure_message() {
let finish_result = finish_deferred_network_approval_for_session(
Some(&context.session),
deferred_network_approval.take(),
)
.await;
emit_failed_initial_exec_end_if_unstored(
process_stored,
process.sandbox_type(),
context,
&request,
cwd.clone(),
plugin_attribution.clone(),
Arc::clone(&output_buffer),
text.clone(),
message.clone(),
wall_time,
)
.await;
self.release_process_id(request.process_id).await;
if let Err(message) = finish_result {
return Err(fail_process_with_message(process.as_ref(), message));
}
return Err(UnifiedExecError::process_failed(message));
}
let process_id = request.process_id;
let (response_process_id, exit_code) = if process_stored {
let retention = if completion.is_some() {
OutputRetention::UntilExit
} else {
OutputRetention::UntilCollected
};
match self
.refresh_process_state(process_id, &process, retention)
.await
{
ProcessStatus::Alive {
exit_code,
process_id,
..
} => (Some(process_id), exit_code),
ProcessStatus::Exited { exit_code, entry } => {
entry.process.cancellation_token().cancel();
if let Err(message) =
finish_deferred_network_approval_after_process_exit_for_session(
Some(&context.session),
deferred_network_approval.take(),
)
.await
{
return Err(fail_process_with_message(entry.process.as_ref(), message));
}
if !completion
.as_ref()
.is_some_and(|completion| completion.timed_out)
{
process
.check_for_sandbox_denial_with_text(&text)
.await
.map_err(|err| {
err.with_output_collection_metadata(
original_token_count,
output_omitted_bytes,
)
})?;
}
let metrics_sidecar = entry
.plugin_metrics_sidecar
.as_ref()
.and_then(take_plugin_metrics_sidecar);
finish_and_track_measurements(
metrics_sidecar,
exit_code.unwrap_or(-1),
&context.session,
&context.step_context.turn,
&model_context,
&context.call_id,
)
.await;
(None, exit_code)
}
ProcessStatus::Unknown => {
return Err(UnifiedExecError::UnknownProcessId { process_id });
}
}
} else {
// Short-lived command: emit the completed command item immediately
// using the same helper as the background watcher.
let finish_result = finish_deferred_network_approval_after_process_exit_for_session(
Some(&context.session),
deferred_network_approval.take(),
)
.await;
if let Err(message) = finish_result {
emit_failed_initial_exec_end_if_unstored(
process_stored,
process.sandbox_type(),
context,
&request,
cwd.clone(),
plugin_attribution.clone(),
Arc::clone(&output_buffer),
text.clone(),
message.clone(),
wall_time,
)
.await;
self.release_process_id(request.process_id).await;
return Err(fail_process_with_message(process.as_ref(), message));
}
let exit_code = process.exit_code();
let exit = exit_code.unwrap_or(-1);
initial_exec_command_guard
.finish_plugin_metrics(context, exit)
.await;
emit_exec_end_for_unified_exec(
process.sandbox_type(),
Arc::clone(&context.session),
Arc::clone(&context.step_context.turn),
Arc::clone(&context.step_context.settings.model_info),
context.call_id.clone(),
request.command.clone(),
cwd.clone(),
Some(process_id.to_string()),
plugin_attribution.clone(),
Arc::clone(&output_buffer),
text.clone(),
exit,
wall_time,
process.timed_out(),
)
.await;
self.release_process_id(request.process_id).await;
process
.check_for_sandbox_denial_with_text(&text)
.await
.map_err(|err| {
err.with_output_collection_metadata(original_token_count, output_omitted_bytes)
})?;
(None, exit_code)
};
let response = ExecCommandToolOutput {
event_call_id: context.call_id.clone(),
chunk_id,
wall_time,
raw_output: collected,
truncation_policy: context
.step_context
.settings
.model_info
.truncation_policy
.into(),
max_output_tokens: request.max_output_tokens,
process_id: response_process_id,
exit_code,
original_token_count: Some(original_token_count),
output_omitted_bytes,
hook_command: Some(request.hook_command.clone()),
};
Ok(response)
}
#[tracing::instrument(
name = "unified_exec.write_stdin",
level = "info",
skip_all,
fields(
conversation.id = %context.session.thread_id,
turn_id = trace_id(&context.step_context.turn.sub_id),
call_id = trace_id(&context.call_id),
original_exec_call_id = tracing::field::Empty,
unified_exec_process_id = request.terminal.process_id,
interaction = if request.input.is_empty() { "poll" } else { "write" },
outcome = tracing::field::Empty,
)
)]
pub(crate) async fn write_stdin(
&self,
context: &UnifiedExecContext,
request: WriteStdinRequest<'_>,
) -> Result<ExecCommandToolOutput, UnifiedExecError> {
let result = self.write_stdin_inner(context, request).await;
let outcome = match &result {
Ok(output) if output.process_id.is_some() => "yielded",
Ok(_) => "exited",
Err(_) if context.cancellation_token.is_cancelled() => "cancelled",
Err(_) => "failed",
};
tracing::Span::current().record("outcome", outcome);
result
}
async fn write_stdin_inner(
&self,
context: &UnifiedExecContext,
request: WriteStdinRequest<'_>,
) -> Result<ExecCommandToolOutput, UnifiedExecError> {
let process_id = request.terminal.process_id;
let locked_process = &request.terminal.process;
if let Some(call_id) = trace_id(&request.terminal.call_id) {
tracing::Span::current().record("original_exec_call_id", call_id);
}
// Serialize writes and polls on the original terminal.
let _interaction_guard = locked_process.interaction_lock().lock_owned().await;
// A queued write must observe strict review enabled while it was waiting.
let strict_auto_review = context.step_context.turn.strict_auto_review_enabled();
let approval = {
let store = self.process_store.lock().await;
let entry = store
.processes
.get(&process_id)
.filter(|entry| Arc::ptr_eq(&entry.process, locked_process))
.ok_or(UnifiedExecError::UnknownProcessId { process_id })?;
entry.stdin_approval(context, request.input, strict_auto_review)?
};
if let Some((approval, approval_reason)) = approval {
let unreviewable_input_error = || {
UnifiedExecError::StdinApproval(ToolError::Rejected(
"terminal input and permission details are too large to review safely; use a smaller input or start a new terminal with fewer grants".to_string(),
))
};
let reviewed = crate::guardian::format_guardian_action_pretty(
&approval
.clone()
.into_guardian_request(/*exec_command_cwd_convention*/ None)
.map_err(|err| {
UnifiedExecError::StdinApproval(ToolError::Rejected(err.to_string()))
})?,
)
.map_err(|_| unreviewable_input_error())?;
// Bound the entire serialized action plus its reason, including JSON
// escaping. Reject, never execute an unreviewed tail.
let oversized =
reviewed.len().saturating_add(approval_reason.len()) > MAX_STDIN_APPROVAL_BYTES;
let size_check_result = if oversized {
"over_limit"
} else {
"within_limit"
};
let input_kind = if request.input.chars().all(char::is_control) {
"control"
} else {
"text"
};
context.step_context.session_telemetry.counter(
"codex.unified_exec.stdin_review.size_check",
/*inc*/ 1,
&[("result", size_check_result), ("input_kind", input_kind)],
);
if oversized {
return Err(unreviewable_input_error());
}
let approval_context = ApprovalContext {
review_context: GuardianReviewContext::from(&context.step_context),
cancellation_token: Some(context.cancellation_token.clone()),
call_id: context.call_id.clone(),
tool_name: ToolName::plain("write_stdin"),
strict_auto_review,
approval_reason: Some(approval_reason),
retry_reason: None,
network_approval_context: None,
};
context
.session
.request_approval(approval, approval_context)
.await
.result
.map_err(UnifiedExecError::StdinApproval)?;
}
// Revalidate the identity after approval: a removed process ID can be reused.
let PreparedProcessHandles {
process,
output,
pause_state,
session,
network_approval,
call_id,
hook_command,
process_id,
tty,
..
} = self
.prepare_process_handles(process_id, locked_process)
.await?;
context
.session
.services
.rollout_thread_trace
.record_stdin_target(
&context.step_context.turn.sub_id,
&context.call_id,
&call_id,
);
let remote_exited =
process.has_exited() && output.drain_policy == OutputDrainPolicy::WaitForOutputClosure;
// A write racing with remote exit still collects the final output.
if !request.input.is_empty() && !remote_exited {
if !tty {
if request.input == INTERRUPT {
process.interrupt().await?;
} else {
return Err(UnifiedExecError::StdinClosed);
}
} else {
match process.write(request.input.as_bytes()).await {
Ok(()) => {
// Give the remote process a brief window to react so that we are
// more likely to capture its output in the poll below.
tokio::time::sleep(Duration::from_millis(100)).await;
}
Err(err) => {
if !process.has_exited() {
if matches!(err, UnifiedExecError::ProcessFailed { .. }) {
process.terminate();
self.release_process(process_id, Some(locked_process)).await;
}
return Err(err);
}
}
}
}
}
let yield_time_ms = {
// Empty polls use configurable background timeout bounds. Non-empty
// writes keep a fixed max cap so interactive stdin remains responsive.
let time_ms = request.yield_time_ms.max(MIN_YIELD_TIME_MS);
if request.input.is_empty() {
time_ms.clamp(MIN_EMPTY_YIELD_TIME_MS, self.max_write_stdin_yield_time_ms)
} else {
time_ms.min(MAX_YIELD_TIME_MS)
}
};
let start = Instant::now();
let deadline = start + Duration::from_millis(yield_time_ms);
let collected_output =
Self::collect_output_until_deadline(&output, pause_state, deadline).await;
let wall_time = Instant::now().saturating_duration_since(start);
let original_token_count = usize::try_from(approx_tokens_from_byte_count(
collected_output.total_bytes(),
))
.unwrap_or(usize::MAX);
let output_omitted_bytes = NonZeroUsize::new(collected_output.omitted_bytes());
let collected = collected_output.to_bytes_with_omission_marker();
let chunk_id = generate_chunk_id();
if network_approval
.as_ref()
.is_some_and(DeferredNetworkApproval::is_cancelled)
{
let message =
network_denial_message_for_session(session.as_ref(), network_approval.clone())
.await;
self.release_process(process_id, Some(locked_process)).await;
return Err(fail_process_with_message(process.as_ref(), message));
}
if let Some(message) = process.failure_message() {
let finish_result = finish_deferred_network_approval_for_session(
session.as_ref(),
network_approval.clone(),
)
.await;
self.release_process(process_id, Some(locked_process)).await;
if let Err(message) = finish_result {
return Err(fail_process_with_message(process.as_ref(), message));
}
return Err(UnifiedExecError::process_failed(message));
}
// Only finalize remote sessions after both process exit and output collection.
let status = self
.refresh_process_state(process_id, locked_process, OutputRetention::UntilCollected)
.await;
let (process_id, exit_code, event_call_id) = match status {
ProcessStatus::Alive {
exit_code,
call_id,
process_id,
} => (Some(process_id), exit_code, call_id),
ProcessStatus::Exited { exit_code, entry } => {
entry.process.cancellation_token().cancel();
let call_id = entry.call_id.clone();
if let Err(message) =
finish_network_approval_after_process_exit_for_entry(&entry).await
{
return Err(fail_process_with_message(entry.process.as_ref(), message));
}
(None, exit_code, call_id)
}
ProcessStatus::Unknown => {
if process.has_exited() {
(None, process.exit_code(), call_id)
} else {
return Err(UnifiedExecError::UnknownProcessId { process_id });
}
}
};
let response = ExecCommandToolOutput {
event_call_id,
chunk_id,
wall_time,
raw_output: collected,
truncation_policy: request.truncation_policy,
max_output_tokens: request.max_output_tokens,
process_id,
exit_code,
original_token_count: Some(original_token_count),
output_omitted_bytes,
hook_command: Some(hook_command),
};
let should_emit_interaction = !request.input.is_empty() || response.process_id.is_some();
if should_emit_interaction
&& let Some(WriteStdinInteractionEvent { session, turn }) = request.interaction_event
{
let interaction = TerminalInteractionEvent {
call_id: response.event_call_id.clone(),
process_id: response
.process_id
.unwrap_or(request.terminal.process_id)
.to_string(),
stdin: request.input.to_string(),
};
session
.send_event(turn.as_ref(), EventMsg::TerminalInteraction(interaction))
.await;
}
Ok(response)
}
async fn refresh_process_state(
&self,
process_id: i32,
expected_process: &Arc<UnifiedExecProcess>,
retention: OutputRetention,
) -> ProcessStatus {
let mut store = self.process_store.lock().await;
let Some(entry) = store
.processes
.get_mut(&process_id)
.filter(|entry| Arc::ptr_eq(&entry.process, expected_process))
else {
return ProcessStatus::Unknown;
};
let exit_code = entry.process.exit_code();
let process_id = entry.process_id;
if entry.process.has_exited() {
let output = entry.process.output_handles();
// Never wait for output under the shared process-store lock. Retain busy output
// for another poll; closed, empty output cannot grow again.
if retention == OutputRetention::UntilCollected
&& output.drain_policy == OutputDrainPolicy::WaitForOutputClosure
&& !entry.process.termination_requested.load(Ordering::Acquire)
&& (!output.output_closed.load(Ordering::Acquire)
|| output
.output_buffer
.try_lock()
.map_or(true, |buffer| buffer.pending.total_bytes() > 0))
{
return ProcessStatus::Alive {
exit_code: None,
call_id: entry.call_id.clone(),
process_id,
};
}
let Some(entry) = store.remove(process_id) else {
return ProcessStatus::Unknown;
};
ProcessStatus::Exited {
exit_code,
entry: Box::new(entry),
}
} else {
ProcessStatus::Alive {
exit_code,
call_id: entry.call_id.clone(),
process_id,
}
}
}
async fn prepare_process_handles(
&self,
process_id: i32,
expected_process: &Arc<UnifiedExecProcess>,
) -> Result<PreparedProcessHandles, UnifiedExecError> {
let mut store = self.process_store.lock().await;
let entry = store
.processes
.get_mut(&process_id)
.ok_or(UnifiedExecError::UnknownProcessId { process_id })?;
if !Arc::ptr_eq(&entry.process, expected_process) {
return Err(UnifiedExecError::UnknownProcessId { process_id });
}
entry.last_used = Instant::now();
let output = entry.process.output_handles().clone();
let pause_state = entry
.session
.upgrade()
.map(|session| session.subscribe_elicitation_pause_state());
let session = entry.session.upgrade();
Ok(PreparedProcessHandles {
process: Arc::clone(&entry.process),
output,
pause_state,
session,
network_approval: entry.network_approval.clone(),
call_id: entry.call_id.clone(),
hook_command: entry.hook_command.clone(),
process_id: entry.process_id,
tty: entry.tty,
})
}
#[allow(clippy::too_many_arguments)]
async fn store_process(
&self,
process: Arc<UnifiedExecProcess>,
context: &UnifiedExecContext,
command: &[String],
hook_command: String,
cwd: PathUri,
environment_id: String,
permissions: super::TerminalPermissions,
plugin_attribution: Option<PluginCommandAttribution>,
started_at: Instant,
process_id: i32,
tty: bool,
network_approval: Option<DeferredNetworkApproval>,
network_denial_monitor: Option<tokio::task::JoinHandle<()>>,
metrics_sidecar: Option<PluginMetricsSidecar>,
output_buffer: Arc<tokio::sync::Mutex<OutputBuffers>>,
initial_exec_command_active: Arc<AtomicBool>,
) {
let plugin_metrics_sidecar =
metrics_sidecar.map(|sidecar| Arc::new(std::sync::Mutex::new(Some(sidecar))));
let entry = ProcessEntry {
process: Arc::clone(&process),
plugin_metrics_sidecar: plugin_metrics_sidecar.clone(),
call_id: context.call_id.clone(),
process_id,
cwd: cwd.clone(),
initial_exec_command_active,
hook_command,
tty,
environment_id,
permissions,
network_approval,
session: Arc::downgrade(&context.session),
last_used: started_at,
};
let pruned_entry = {
let mut store = self.process_store.lock().await;
let pruned_entry = Self::prune_processes_if_needed(&mut store);
store.processes.insert(process_id, entry);
pruned_entry
};
spawn_exit_watcher(
Arc::clone(&process),
context,
command.to_vec(),
cwd,
process_id,
plugin_attribution,
output_buffer,
started_at,
network_denial_monitor,
plugin_metrics_sidecar,
);
// Install the watcher before cancellable cleanup, and outside the process-store lock.
if let Some(pruned_entry) = pruned_entry {
unregister_network_approval_for_entry(&pruned_entry).await;
pruned_entry.process.terminate();
}
}
#[allow(clippy::too_many_arguments)]
pub(crate) async fn open_session_with_exec_env(
&self,
process_id: i32,
tool_ctx: &ToolCtx,
command: SandboxCommand,
options: ExecOptions,
attempt: &SandboxAttempt<'_>,
network: Option<&NetworkProxy>,
network_proxy_launch: Option<codex_network_proxy::RemoteNetworkProxyLaunchConfig>,
environment_id: Option<&str>,
exec_server_env_config: Option<ExecServerEnvConfig>,
shell_snapshot: Option<codex_exec_server::ShellSnapshotRequest>,
windows_sandbox_proxy_settings_mode: codex_sandboxing::WindowsSandboxProxySettingsMode,
tty: bool,
environment: &codex_exec_server::Environment,
) -> Result<UnifiedExecProcess, ToolError> {
let mut request = if environment.is_remote() || shell_snapshot.is_some() {
attempt.env_for_exec_server(command, options).await
} else {
attempt
.env_for(command, options, network, environment_id)
.await
}
.map_err(ToolError::Codex)?;
let network_policy_decider = network_proxy_launch
.as_ref()
.filter(|launch| launch.policy_decision_timeout_ms.is_some())
.and_then(|launch| network?.remote_policy_decider(launch.proxy.allow_local_binding));
if environment.is_remote() && network.is_some() && network_proxy_launch.is_none() {
request.exec_server_enforce_managed_network = false;
}
request.exec_server_network_proxy = network_proxy_launch;
request.exec_server_env_config = exec_server_env_config;
request.exec_server_shell_snapshot = shell_snapshot;
self.open_session_with_prepared_exec_env(
process_id,
&request,
Some(tool_ctx),
windows_sandbox_proxy_settings_mode,
network_policy_decider,
tty,
environment,
)
.await
.map_err(|err| match err {
UnifiedExecError::SandboxDenied { output, .. } => {
ToolError::Codex(CodexErr::Sandbox(SandboxErr::Denied {
output: Box::new(output),
network_policy_decision: None,
}))
}
other => ToolError::Rejected(other.to_string()),
})
}
#[allow(clippy::too_many_arguments)]
pub(crate) async fn open_session_with_prepared_exec_env(
&self,
process_id: i32,
request: &ExecRequest,
tool_ctx: Option<&ToolCtx>,
windows_sandbox_proxy_settings_mode: codex_sandboxing::WindowsSandboxProxySettingsMode,
network_policy_decider: Option<Arc<dyn NetworkPolicyDecider>>,
tty: bool,
environment: &codex_exec_server::Environment,
) -> Result<UnifiedExecProcess, UnifiedExecError> {
if environment.is_remote() || request.exec_server_shell_snapshot.is_some() {
let backend = environment.get_exec_backend();
let params = exec_server_params_for_request(
process_id,
request,
tool_ctx,
windows_sandbox_proxy_settings_mode,
tty,
);
// Sandbox retries can reuse the public ID for a new executor process.
tracing::event!(
name: "codex.unified_exec.process_start_requested",
target: "codex_otel.trace_safe",
tracing::Level::INFO,
event.name = "codex.unified_exec.process_start_requested",
unified_exec_process_id = process_id,
process.id = params.process_id.as_str(),
);
let started = match network_policy_decider {
Some(decider) => {
backend
.start_with_network_policy_decider(params, decider)
.await
}
None => backend.start(params).await,
}
.map_err(|err| UnifiedExecError::create_process(err.to_string()))?;
let output_drain_policy = if environment.is_remote() {
OutputDrainPolicy::WaitForOutputClosure
} else {
OutputDrainPolicy::BoundedAfterExit
};
return UnifiedExecProcess::from_exec_server_started(started, output_drain_policy)
.await;
}
// TODO(anp): Keep PathUri through the local PTY/process launch boundary.
let native_cwd = request
.cwd
.to_abs_path()
.map_err(|_| UnifiedExecError::ForeignPath {
path: request.cwd.clone(),
})?;
if request.command.is_empty() {
return Err(UnifiedExecError::MissingCommandLine);
}
let network_proxy_restricting_sid = {
#[cfg(target_os = "windows")]
{
if request.sandbox == codex_sandboxing::SandboxType::WindowsRestrictedToken {
request
.network
.as_ref()
.map(|network| {
network
.network_proxy_restricting_sid(
request.network_environment_id.as_deref(),
)
.ok_or_else(|| {
UnifiedExecError::create_process(
"managed Windows proxy route is missing its restricting SID"
.to_string(),
)
})
})
.transpose()?
} else {
None
}
}
#[cfg(not(target_os = "windows"))]
{
None::<String>
}
};
let windows_sandbox =
if request.sandbox == codex_sandboxing::SandboxType::WindowsRestrictedToken {
Some(codex_sandboxing::WindowsSandboxSpawnRequest {
permission_profile: &request.permission_profile,
workspace_roots: &request.windows_sandbox_workspace_roots,
windows_sandbox_level: request.windows_sandbox_level,
proxy_enforced: request.network.is_some(),
network_proxy_restricting_sid: network_proxy_restricting_sid.as_deref(),
proxy_settings_mode: windows_sandbox_proxy_settings_mode,
filesystem_overrides: request.windows_sandbox_filesystem_overrides.as_ref(),
})
} else {
None
};
let spawn_result = codex_sandboxing::spawn_process(codex_sandboxing::SpawnRequest {
command: &request.command,
cwd: native_cwd.as_path(),
env: &request.env,
arg0: &request.arg0,
sandbox: request.sandbox,
windows_sandbox,
tty,
stdin_open: tty,
inherited_fds: codex_utils_pty::ChildFds::Inherited(&[]),
})
.await;
let spawned =
spawn_result.map_err(|err| UnifiedExecError::create_process(err.to_string()))?;
UnifiedExecProcess::from_spawned(spawned, request.sandbox).await
}
#[tracing::instrument(
name = "unified_exec.open_session",
level = "info",
skip_all,
fields(outcome = tracing::field::Empty)
)]
pub(super) async fn open_session_with_sandbox(
&self,
request: &ExecCommandRequest,
cwd: PathUri,
context: &UnifiedExecContext,
) -> Result<(UnifiedExecAttempt, Option<DeferredNetworkApproval>), UnifiedExecError> {
let shell_environment_policy = request.turn_environment.shell_environment_policy();
let local_policy_env = create_env(shell_environment_policy, /*thread_id*/ None);
let mut env = local_policy_env.clone();
#[cfg(windows)]
env.retain(|name, _| !name.eq_ignore_ascii_case(CODEX_THREAD_ID_ENV_VAR));
env.insert(
CODEX_THREAD_ID_ENV_VAR.to_string(),
context.session.thread_id.to_string(),
);
set_tool_call_id_env_var(&mut env, Some(&context.call_id));
inject_session_env(&mut env, context.session.session_id());
inject_apply_patch_env(&mut env);
let active_permission_profile = request.turn_environment.active_permission_profile();
inject_permission_profile_env(&mut env, active_permission_profile.as_ref());
let mut env = apply_unified_exec_env(env);
strip_output_env(&mut env);
let mut explicit_env_overrides = shell_environment_policy.r#set.clone();
strip_output_env(&mut explicit_env_overrides);
let exec_server_env_config = ExecServerEnvConfig {
policy: exec_env_policy_from_shell_policy(shell_environment_policy),
local_policy_env,
};
let shell_snapshot = shell_snapshot_request(request, &cwd, context);
let mut orchestrator = ToolOrchestrator::new();
let mut runtime = UnifiedExecRuntime::new(self);
let session_shell = context.session.user_shell();
let configured_shell = request
.turn_environment
.shell
.as_ref()
.unwrap_or(session_shell.as_ref());
// Legacy executors omit the platform. Unknown reported platforms use the
// more conservative Windows rules rather than silently weakening checks.
let command_platform = match request.turn_environment.executor_platform_os.as_deref() {
Some("linux" | "macos") => DangerousCommandPlatform::Posix,
Some("windows") | Some(_) => DangerousCommandPlatform::Windows,
None => DangerousCommandPlatform::host(),
};
let exec_approval_requirement = context
.session
.services
.exec_policy
.create_exec_approval_requirement_for_shell(
ExecApprovalRequest {
command: &request.command,
approval_policy: context.step_context.settings.approval_policy(),
permission_profile: request.turn_environment.permission_profile().clone(),
environment_policy: request.turn_environment.config().exec_policy.as_ref(),
windows_sandbox_level: windows_sandbox_level_for_legacy_checks(
request.turn_environment.config().windows_sandbox_type,
request.turn_environment.config().windows_sandbox_level,
),
sandbox_permissions: if request.additional_permissions_preapproved {
crate::sandboxing::SandboxPermissions::UseDefault
} else {
request.sandbox_permissions
},
prefix_rule: request.prefix_rule.clone(),
allow_prefix_rules: context.step_context.turn.allow_prefix_rules(),
},
configured_shell,
command_platform,
)
.await;
let req = UnifiedExecToolRequest {
command: request.command.clone(),
shell: request.shell.clone(),
hook_command: request.hook_command.clone(),
process_id: request.process_id,
cwd,
sandbox_cwd: request.sandbox_cwd.clone(),
turn_environment: request.turn_environment.clone(),
env,
exec_server_env_config: Some(exec_server_env_config),
shell_snapshot,
explicit_env_overrides,
network: request.network.clone(),
tty: request.tty,
sandbox_permissions: request.sandbox_permissions,
additional_permissions: request.additional_permissions.clone(),
justification: request.justification.clone(),
exec_approval_requirement,
};
let tool_ctx = ToolCtx {
session: context.session.clone(),
step_context: Arc::clone(&context.step_context),
cancellation_token: context.cancellation_token.clone(),
call_id: context.call_id.clone(),
tool_name: ToolName::plain("exec_command"),
};
let result = orchestrator
.run(&mut runtime, &req, &tool_ctx)
.await
.map(|result| (result.output, result.deferred_network_approval))
.map_err(|err| match err {
ToolError::Codex(err) => match err.details() {
CodexErrorDetails::Sandbox(SandboxErr::Denied { output, .. }) => {
let output = output.as_ref().clone();
let message = if output.aggregated_output.text.is_empty() {
let exit_code = output.exit_code;
format!("Process exited with code {exit_code}")
} else {
output.aggregated_output.text.clone()
};
UnifiedExecError::sandbox_denied(message, output)
}
_ => UnifiedExecError::create_process(format!("{err:?}")),
},
other => UnifiedExecError::create_process(format!("{other:?}")),
});
let outcome = match &result {
Ok(_) => "completed",
Err(_) if context.cancellation_token.is_cancelled() => "cancelled",
Err(_) => "failed",
};
tracing::Span::current().record("outcome", outcome);
result
}
#[tracing::instrument(
name = "unified_exec.collect_output",
level = "info",
skip_all,
fields(
outcome = tracing::field::Empty,
stop_reason = tracing::field::Empty,
exit_signaled = tracing::field::Empty,
output_closed = tracing::field::Empty,
)
)]
pub(super) async fn collect_output_until_deadline<const MAX_BYTES: usize>(
output: &OutputHandles<MAX_BYTES>,
mut pause_state: Option<watch::Receiver<bool>>,
mut deadline: Instant,
) -> HeadTailBuffer<MAX_BYTES> {
const POST_EXIT_CLOSE_WAIT_CAP: Duration = Duration::from_millis(50);
enum StopReason {
OutputClosed,
Deadline,
PostExitDeadline,
}
let OutputHandles {
output_buffer,
output_notify,
output_closed,
output_closed_notify,
cancellation_token,
..
} = output;
let mut collected = HeadTailBuffer::default();
let mut exit_signal_received = cancellation_token.is_cancelled();
let mut post_exit_deadline: Option<Instant> = None;
let stop_reason = loop {
Self::extend_deadlines_while_paused(
&mut pause_state,
&mut deadline,
&mut post_exit_deadline,
)
.await;
let drained_output: HeadTailBuffer<MAX_BYTES>;
let has_drained_output: bool;
let mut wait_for_output = None;
{
let mut guard = output_buffer.lock().await;
drained_output = std::mem::take(&mut guard.pending);
has_drained_output =
drained_output.retained_bytes() > 0 || drained_output.omitted_bytes() > 0;
if !has_drained_output {
wait_for_output = Some(output_notify.notified());
}
}
if !has_drained_output {
exit_signal_received |= cancellation_token.is_cancelled();
if exit_signal_received && output_closed.load(Ordering::Acquire) {
break StopReason::OutputClosed;
}
let remaining = deadline.saturating_duration_since(Instant::now());
if remaining == Duration::ZERO {
break StopReason::Deadline;
}
if exit_signal_received {
let now = Instant::now();
let close_wait_deadline = *post_exit_deadline
.get_or_insert_with(|| now + remaining.min(POST_EXIT_CLOSE_WAIT_CAP));
let close_wait_remaining = close_wait_deadline.saturating_duration_since(now);
if close_wait_remaining == Duration::ZERO {
break StopReason::PostExitDeadline;
}
let notified = wait_for_output.unwrap_or_else(|| output_notify.notified());
let closed = output_closed_notify.notified();
tokio::pin!(notified);
tokio::pin!(closed);
tokio::select! {
_ = &mut notified => {}
_ = &mut closed => {}
_ = tokio::time::sleep(close_wait_remaining) => break StopReason::PostExitDeadline,
_ = Self::wait_for_pause_change(pause_state.as_ref()) => {}
}
continue;
}
let notified = wait_for_output.unwrap_or_else(|| output_notify.notified());
tokio::pin!(notified);
let exit_notified = cancellation_token.cancelled();
tokio::pin!(exit_notified);
tokio::select! {
_ = &mut notified => {}
_ = &mut exit_notified => exit_signal_received = true,
_ = tokio::time::sleep(remaining) => break StopReason::Deadline,
_ = Self::wait_for_pause_change(pause_state.as_ref()) => {}
}
continue;
}
collected.push_buffer(drained_output);
exit_signal_received |= cancellation_token.is_cancelled();
if Instant::now() >= deadline {
break StopReason::Deadline;
}
};
let span = tracing::Span::current();
span.record(
"stop_reason",
match stop_reason {
StopReason::OutputClosed => "output_closed",
StopReason::Deadline => "deadline",
StopReason::PostExitDeadline => "post_exit_deadline",
},
);
span.record(
"exit_signaled",
exit_signal_received || cancellation_token.is_cancelled(),
);
span.record("output_closed", output_closed.load(Ordering::Acquire));
span.record("outcome", "completed");
collected
}
async fn extend_deadlines_while_paused(
pause_state: &mut Option<watch::Receiver<bool>>,
deadline: &mut Instant,
post_exit_deadline: &mut Option<Instant>,
) {
let Some(receiver) = pause_state.as_mut() else {
return;
};
if !*receiver.borrow() {
return;
}
let paused_at = Instant::now();
while *receiver.borrow() {
if receiver.changed().await.is_err() {
break;
}
}
let paused_for = paused_at.elapsed();
*deadline += paused_for;
if let Some(post_exit_deadline) = post_exit_deadline.as_mut() {
*post_exit_deadline += paused_for;
}
}
async fn wait_for_pause_change(pause_state: Option<&watch::Receiver<bool>>) {
match pause_state {
Some(pause_state) => {
let mut receiver = pause_state.clone();
let _ = receiver.changed().await;
}
None => std::future::pending::<()>().await,
}
}
fn prune_processes_if_needed(store: &mut ProcessStore) -> Option<ProcessEntry> {
if store.processes.len() < MAX_UNIFIED_EXEC_PROCESSES {
return None;
}
let mut meta: Vec<(i32, Instant, bool)> = store
.processes
.iter()
.map(|(id, entry)| (*id, entry.last_used, entry.process.has_exited()))
.collect();
let mut found_locked_exited_process = false;
while let Some(process_id) = Self::process_id_to_prune_from_meta(&meta) {
let candidate_process = store
.processes
.get(&process_id)
.map(|entry| Arc::clone(&entry.process));
let candidate_has_exited = candidate_process
.as_ref()
.is_some_and(|process| process.has_exited());
if found_locked_exited_process && !candidate_has_exited {
// The store may temporarily exceed its soft cap while an exited
// process is publishing its terminal event. Do not evict a live
// process just because that exited process is briefly locked.
return None;
}
// Do not prune processes while write_stdin or terminal event
// publication holds their interaction lock.
if let Some(interaction_lock) = candidate_process
.as_ref()
.map(|process| process.interaction_lock())
&& let Ok(_interaction_guard) = interaction_lock.try_lock_owned()
{
return store.remove(process_id);
}
found_locked_exited_process |= candidate_has_exited
|| candidate_process.is_some_and(|process| process.has_exited());
meta.retain(|(id, _, _)| *id != process_id);
}
None
}
// Centralized pruning policy so we can easily swap strategies later.
fn process_id_to_prune_from_meta(meta: &[(i32, Instant, bool)]) -> Option<i32> {
if meta.is_empty() {
return None;
}
let mut by_recency = meta.to_vec();
by_recency.sort_by_key(|(_, last_used, _)| Reverse(*last_used));
let protected: HashSet<i32> = by_recency
.iter()
.take(8)
.map(|(process_id, _, _)| *process_id)
.collect();
let mut lru = meta.to_vec();
lru.sort_by_key(|(_, last_used, _)| *last_used);
if let Some((process_id, _, _)) = lru
.iter()
.find(|(process_id, _, exited)| !protected.contains(process_id) && *exited)
{
return Some(*process_id);
}
lru.into_iter()
.find(|(process_id, _, _)| !protected.contains(process_id))
.map(|(process_id, _, _)| process_id)
}
pub(crate) async fn terminate_all_processes(&self) {
let entries: Vec<ProcessEntry> = {
let mut processes = self.process_store.lock().await;
let entries: Vec<ProcessEntry> = processes
.processes
.drain()
.map(|(_, entry)| entry)
.collect();
processes.reserved_process_ids.clear();
entries
};
for entry in entries {
unregister_network_approval_for_entry(&entry).await;
entry.process.terminate();
}
}
pub(crate) async fn resolve_terminal(
&self,
process_id: i32,
) -> Result<TerminalSession, UnifiedExecError> {
let store = self.process_store.lock().await;
let entry = store
.processes
.get(&process_id)
.ok_or(UnifiedExecError::UnknownProcessId { process_id })?;
Ok(TerminalSession {
process_id,
process: Arc::clone(&entry.process),
call_id: entry.call_id.clone(),
environment_id: entry.environment_id.clone(),
})
}
pub(crate) async fn list_processes(&self) -> Vec<BackgroundTerminalInfo> {
let store = self.process_store.lock().await;
let mut entries = store
.processes
.values()
.filter(|entry| !entry.process.has_exited())
.collect::<Vec<_>>();
entries.sort_by_key(|entry| entry.process_id);
entries
.into_iter()
.map(|entry| BackgroundTerminalInfo {
item_id: entry.call_id.clone(),
process_id: entry.process_id.to_string(),
command: entry.hook_command.clone(),
cwd: entry.cwd.clone(),
})
.collect()
}
pub(crate) async fn terminate_process(&self, process_id: i32) -> bool {
let (process, already_exited) = {
let store = self.process_store.lock().await;
let Some(entry) = store.processes.get(&process_id) else {
return false;
};
(Arc::clone(&entry.process), entry.process.has_exited())
};
if already_exited {
// Stop the output producer even when only its inherited pipes remain open.
process.terminate();
} else if process.terminate_confirmed().await.is_err() {
return false;
}
let entry = {
let mut store = self.process_store.lock().await;
let Some(entry) = store.processes.get(&process_id) else {
return true;
};
if !Arc::ptr_eq(&entry.process, &process) {
return true;
}
if entry.initial_exec_command_active.load(Ordering::Acquire) {
return true;
}
let Some(entry) = store.remove(process_id) else {
return false;
};
entry
};
unregister_network_approval_for_entry(&entry).await;
true
}
}
#[derive(PartialEq, Eq)]
enum OutputRetention {
UntilExit,
UntilCollected,
}
enum ProcessStatus {
Alive {
exit_code: Option<i32>,
call_id: String,
process_id: i32,
},
Exited {
exit_code: Option<i32>,
entry: Box<ProcessEntry>,
},
Unknown,
}
#[cfg(test)]
#[path = "process_manager_tests.rs"]
mod tests;