Prewarm shell snapshots for eligible turns (#42137)

## Why

Shell Snapshot V2 previously captured the login-shell environment lazily when a
command started, adding that work to the command path.

## What changed

- Start one asynchronous snapshot capture after turn hooks accept the turn, so
  eligible local `exec_command` calls can reuse it without blocking the model.
- Use the turn's resolved tools, permissions, sandbox, environment, and shell
  configuration, and skip prewarming for unsupported or network-managed cases.
- Cancel outstanding prewarming during shutdown. Keep failed speculative
  captures retryable by real commands without consuming their retry budget.

## Testing

Added coverage for non-blocking capture and reuse, failure recovery, sandbox and
permission isolation, shutdown cancellation, hook-stopped turns, eligibility
gates, and concurrent capture retries.

GitOrigin-RevId: ff24a4f0328c06653e09d03fd0a3db1eccd65030
This commit is contained in:
jif
2026-09-01 21:16:12 +00:00
committed by copyberry
parent c5b5fa8089
commit 612e6491d5
13 changed files with 783 additions and 50 deletions
+5
View File
@@ -405,6 +405,11 @@ pub(super) async fn shutdown_session_runtime(sess: &Arc<Session>) {
}
let _ = sess.conversation.shutdown().await;
sess.abort_all_tasks(TurnAbortReason::Interrupted).await;
let shell_snapshot_prewarm = sess.state.lock().await.shell_snapshot_prewarm.take();
if let Some(shell_snapshot_prewarm) = shell_snapshot_prewarm {
shell_snapshot_prewarm.abort();
let _ = shell_snapshot_prewarm.await;
}
sess.hooks().shutdown().await;
sess.async_hook_results.close();
while sess.async_hook_results.try_recv().is_ok() {}
+9
View File
@@ -269,6 +269,15 @@ pub(crate) async fn run_turn(
return Ok(None);
}
// Only speculate after hooks accept the turn, using its finalized tools and permissions.
{
let mut state = sess.state.lock().await;
if state.shell_snapshot_prewarm.is_none() {
state.shell_snapshot_prewarm =
sess.prewarm_shell_snapshots(first_step_context.as_ref());
}
}
sess.merge_connector_selection(explicitly_enabled_connectors.clone())
.await;
sess.set_previous_turn_settings(Some(PreviousTurnSettings {
+4
View File
@@ -27,6 +27,7 @@ use codex_protocol::protocol::TokenUsageInfo;
use codex_protocol::protocol::TokenUsageRecord;
use codex_protocol::protocol::TurnContextItem;
use codex_utils_output_truncation::TruncationPolicy;
use tokio_util::task::AbortOnDropHandle;
/// Persistent, session-scoped state previously stored directly on `Session`.
pub(crate) struct SessionState {
@@ -47,6 +48,8 @@ pub(crate) struct SessionState {
auto_compact_window: AutoCompactWindow,
/// Startup prewarmed session prepared during session initialization.
pub(crate) startup_prewarm: Option<SessionStartupPrewarmHandle>,
/// Retained after completion so later turns do not repeat speculative captures.
pub(crate) shell_snapshot_prewarm: Option<AbortOnDropHandle<()>>,
pub(crate) current_time_reminder: CurrentTimeReminderState,
pub(crate) active_connector_selection: HashSet<String>,
pub(crate) pending_session_start_sources: VecDeque<codex_hooks::SessionStartSource>,
@@ -81,6 +84,7 @@ impl SessionState {
previous_turn_settings: None,
auto_compact_window: AutoCompactWindow::new_with_ids(auto_compact_window_ids),
startup_prewarm: None,
shell_snapshot_prewarm: None,
current_time_reminder: CurrentTimeReminderState::default(),
active_connector_selection: HashSet::new(),
pending_session_start_sources: VecDeque::new(),
+1 -1
View File
@@ -114,7 +114,7 @@ impl ToolCallRuntime {
}
let router = &self.step_context.tool_router;
let supports_parallel = router.tool_supports_parallel(&call);
let tool_runtime = router.tool_runtime(&call);
let tool_runtime = router.tool_runtime(&call.tool_name);
let router = Arc::clone(router);
let session = Arc::clone(&self.session);
let step_context = Arc::clone(&self.step_context);
+2 -2
View File
@@ -238,8 +238,8 @@ impl ToolRouter {
.unwrap_or(false)
}
pub(crate) fn tool_runtime(&self, call: &ToolCall) -> Option<Arc<dyn CoreToolRuntime>> {
self.registry.tool(&call.tool_name)
pub(crate) fn tool_runtime(&self, tool_name: &ToolName) -> Option<Arc<dyn CoreToolRuntime>> {
self.registry.tool(tool_name)
}
#[instrument(level = "trace", skip_all, err)]
+4 -11
View File
@@ -190,14 +190,7 @@ async fn parallel_support_does_not_match_namespaced_local_tool_names() -> anyhow
assert_eq!(
router
.tool_runtime(&ToolCall {
tool_name: ToolName::plain(parallel_tool_name),
call_id: "call-local-tool".to_string(),
payload: ToolPayload::Function {
arguments: "{}".to_string(),
},
encrypted_function_args: None,
})
.tool_runtime(&ToolName::plain(parallel_tool_name))
.map(|runtime| runtime.tool_name()),
Some(ToolName::plain(parallel_tool_name))
);
@@ -369,7 +362,7 @@ async fn mcp_parallel_support_uses_handler_data() -> anyhow::Result<()> {
assert!(router.tool_supports_parallel(&call));
assert_eq!(
router
.tool_runtime(&call)
.tool_runtime(&call.tool_name)
.map(|runtime| runtime.tool_name()),
Some(call.tool_name.clone())
);
@@ -385,7 +378,7 @@ async fn mcp_parallel_support_uses_handler_data() -> anyhow::Result<()> {
assert!(!router.tool_supports_parallel(&different_server_call));
assert_eq!(
router
.tool_runtime(&different_server_call)
.tool_runtime(&different_server_call.tool_name)
.map(|runtime| runtime.tool_name()),
Some(different_server_call.tool_name.clone())
);
@@ -399,7 +392,7 @@ async fn mcp_parallel_support_uses_handler_data() -> anyhow::Result<()> {
encrypted_function_args: None,
};
assert!(!router.tool_supports_parallel(&hidden_call));
assert!(router.tool_runtime(&hidden_call).is_some());
assert!(router.tool_runtime(&hidden_call.tool_name).is_some());
let nested_only_call = ToolCall {
tool_name: ToolName::namespaced("mcp__nested_echo__", "query_with_delay"),
@@ -121,14 +121,14 @@ fn should_use_deterministic_process_ids() -> bool {
cfg!(test) || deterministic_process_ids_forced_for_tests()
}
fn apply_unified_exec_env(mut env: HashMap<String, String>) -> HashMap<String, String> {
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
}
fn exec_env_policy_from_shell_policy(
pub(super) fn exec_env_policy_from_shell_policy(
policy: &ShellEnvironmentPolicy,
) -> codex_exec_server::ExecEnvPolicy {
let mut exclude = policy
@@ -1,12 +1,175 @@
use std::collections::HashMap;
use std::sync::Arc;
use codex_exec_server::ExecParams;
use codex_exec_server::FileSystemSandboxContext;
use codex_exec_server::ShellInfo;
use codex_exec_server::ShellSnapshotRequest;
use codex_features::Feature;
use codex_protocol::protocol::AskForApproval;
use codex_sandboxing::SandboxManager;
use codex_sandboxing::SandboxablePreference;
use codex_tools::ToolName;
use codex_tools::UnifiedExecShellMode;
use codex_utils_path_uri::PathUri;
use tokio_util::task::AbortOnDropHandle;
use uuid::Uuid;
use super::ExecCommandRequest;
use super::UnifiedExecContext;
use super::process_manager::apply_unified_exec_env;
use super::process_manager::exec_env_policy_from_shell_policy;
use crate::config::NetworkProxySpec;
use crate::exec_env::CODEX_THREAD_ID_ENV_VAR;
use crate::exec_env::inject_apply_patch_env;
use crate::exec_env::inject_permission_profile_env;
use crate::exec_env::inject_session_id_env;
use crate::session::session::Session;
use crate::session::step_context::StepContext;
use crate::shell::ShellType;
use crate::tools::sandboxing::executor_windows_sandbox_level;
impl Session {
pub(crate) fn prewarm_shell_snapshots(
self: &Arc<Self>,
step_context: &StepContext,
) -> Option<AbortOnDropHandle<()>> {
if !self.features().enabled(Feature::ShellSnapshotV2)
|| step_context
.tool_router
.tool_runtime(&ToolName::plain("exec_command"))
.is_none()
{
return None;
}
let config = Arc::clone(&step_context.turn.config);
let user_shell = self.user_shell();
if config.active_project.is_untrusted()
|| matches!(
step_context.settings.approval_policy(),
AskForApproval::UnlessTrusted
)
|| step_context.turn.network.is_some()
|| config
.permissions
.network
.as_ref()
.is_some_and(NetworkProxySpec::enabled)
|| !matches!(
step_context.turn.unified_exec_shell_mode,
UnifiedExecShellMode::Direct
)
{
return None;
}
let environments = step_context.environments.clone();
let session = Arc::clone(self);
Some(AbortOnDropHandle::new(tokio::spawn(async move {
for environment in environments.turn_environments() {
// Remote starts cannot cancel an in-flight capture. Leave them, deferred
// environments, and managed networking on the normal lazy capture path.
if environment.environment.is_remote()
|| !environment.shell_snapshot_v2_supported
|| !environment.config().allow_login_shell
|| environment.config().network_policy.is_some()
{
continue;
}
let shell = environment.shell.as_ref().unwrap_or(user_shell.as_ref());
if !matches!(
shell.shell_type,
ShellType::Bash | ShellType::Zsh | ShellType::Sh
) {
continue;
}
let sandbox = SandboxManager::new()
.should_sandbox(
environment.permission_profile(),
SandboxablePreference::Auto,
/*has_managed_network_requirements*/ false,
)
.then(|| FileSystemSandboxContext {
permissions: environment.permission_profile().clone().into(),
cwd: Some(environment.cwd().clone()),
workspace_roots: environment.workspace_roots().to_vec(),
user_home_dir: None,
temporary_directories: None,
windows_sandbox_level: executor_windows_sandbox_level(
environment.config().windows_sandbox_level,
environment.cwd(),
),
windows_sandbox_private_desktop: environment
.config()
.windows_sandbox_private_desktop,
windows_sandbox_proxy_settings_mode: Some(
session.windows_sandbox_proxy_settings_mode,
),
use_legacy_landlock: environment.config().use_legacy_landlock,
});
let mut env = apply_unified_exec_env(HashMap::new());
env.insert(
CODEX_THREAD_ID_ENV_VAR.to_string(),
session.thread_id().to_string(),
);
inject_session_id_env(&mut env, session.session_id());
inject_apply_patch_env(&mut env, &config.features);
inject_permission_profile_env(
&mut env,
environment.active_permission_profile().as_ref(),
);
#[cfg(unix)]
if let Some(path) = environment.shell_environment_policy().r#set.get("PATH") {
env.insert("PATH".to_string(), path.clone());
crate::tools::runtimes::apply_package_path_prepend(
&mut env,
&mut crate::tools::runtimes::RuntimePathPrepends::default(),
);
}
let params = ExecParams {
process_id: format!("shell-snapshot-warmup-{}", Uuid::new_v4()).into(),
// This capture-only operation never starts the command or routes
// speculative work through tool approvals or exec-policy bypass.
argv: shell.derive_exec_args("", /*use_login_shell*/ true),
cwd: environment.cwd().clone(),
env_policy: Some(exec_env_policy_from_shell_policy(
environment.shell_environment_policy(),
)),
shell_snapshot: Some(ShellSnapshotRequest {
scope_id: format!(
"{}:{}",
session.thread_id(),
environment.selection.environment_id
),
shell: ShellInfo {
name: shell.name().to_string(),
path: shell.shell_path.to_string_lossy().into_owned(),
},
}),
env,
tty: false,
pipe_stdin: false,
arg0: None,
sandbox,
enforce_managed_network: false,
managed_network: None,
network_proxy: None,
};
let result = environment
.environment
.get_exec_backend()
.prewarm_shell_snapshot(params)
.await;
if let Err(err) = result {
tracing::debug!("failed to warm shell snapshot: {err}");
}
}
})))
}
}
pub(super) fn shell_snapshot_request(
request: &ExecCommandRequest,