Overlap startup WebSocket preconnect with tool discovery (#47635)

## Why

Startup prewarm waited for tool discovery before opening its WebSocket connection. Slow MCP startup therefore delayed connection setup even though the handshake could proceed independently.

## What changed

- Run the WebSocket handshake concurrently with tool capture, then send `generate=false` with the discovered tools and finalized request metadata.
- Include model and effective service-tier routing hints in preconnect, including the inherited tier for spawned subagents. Omit routing hints for guardian reviewer requests.
- Recover authentication failures during preconnect and switch to HTTP fallback on `426 Upgrade Required`.

## Testing

Add and extend regression coverage for handshake overlap with delayed MCP discovery, cancellation before warmup, finalized Responses Lite tool metadata, socket reuse and reconnection, service-tier changes and inheritance, and authentication recovery during preconnect.

GitOrigin-RevId: ecb53540765df8227e55e79910a13a05260a4c8d
This commit is contained in:
Ben Romano
2026-09-23 19:16:20 +00:00
committed by copyberry
parent dce62a50a2
commit ce7df36237
11 changed files with 727 additions and 440 deletions
+95 -67
View File
@@ -1129,9 +1129,7 @@ impl ModelClient {
metadata.remove("guardian_credits_requested");
metadata.remove("parent_response_id");
}
let guardian_reviewer = responses_headers
.get("x-codex-guardian")
.is_some_and(|value| value == "reviewer");
let guardian_reviewer = is_guardian_reviewer(responses_headers);
if guardian_reviewer && let Some(parent_response_id) = parent_response_id {
metadata.get_or_insert_with(HashMap::new).insert(
"parent_response_id".to_owned(),
@@ -1156,10 +1154,11 @@ impl ModelClient {
fn build_routing_hint_header(
&self,
auth: Option<&CodexAuth>,
responses_headers: &ApiHeaderMap,
model: &str,
service_tier: Option<&str>,
) -> Option<HeaderValue> {
if !self.uses_codex_backend(auth) {
if !self.uses_codex_backend(auth) || is_guardian_reviewer(responses_headers) {
return None;
}
@@ -1448,52 +1447,85 @@ impl ModelClientSession {
pub async fn preconnect_websocket(
&mut self,
model_info: &ModelInfo,
service_tier: Option<String>,
session_telemetry: &SessionTelemetry,
responses_metadata: &CodexResponsesMetadata,
) -> std::result::Result<(), ApiError> {
) -> Result<()> {
if !self.client.responses_websocket_enabled() {
return Ok(());
}
let client_setup = self
.client
.current_client_setup(ClientRouting::Workspace)
.await
.map_err(|err| {
ApiError::Stream(format!(
"failed to build websocket prewarm client setup: {err}"
))
})?;
let connection_key =
ResponsesConnectionKey::new(&client_setup.api_provider, client_setup.auth_revision);
if self.websocket_session.connection.is_some()
&& self.websocket_session.connection_key.as_ref() == Some(&connection_key)
{
return Ok(());
let provider = Arc::clone(&self.client.state.provider);
let auth_manager = provider.auth_manager();
let mut auth_recovery = auth_manager
.as_ref()
.map(AuthManager::unauthorized_recovery);
let mut provider_auth_recovery_attempted = false;
let mut pending_retry = PendingUnauthorizedRetry::default();
loop {
let client_setup = self
.client
.current_client_setup(ClientRouting::Workspace)
.await?;
let auth_context = AuthRequestTelemetryContext::new(
client_setup.auth.as_ref().map(CodexAuth::auth_mode),
client_setup.api_auth.as_ref(),
client_setup.agent_identity_telemetry.clone(),
pending_retry,
);
let responses_headers = self
.client
.responses_headers(client_setup.auth.as_ref(), &model_info.slug);
let mut websocket_metadata = responses_metadata.clone();
websocket_metadata.routing_hint = self.client.build_routing_hint_header(
client_setup.auth.as_ref(),
&responses_headers,
&model_info.slug,
model_info
.service_tier_for_request(service_tier.clone())
.as_deref(),
);
match self
.websocket_connection(WebsocketConnectParams {
session_telemetry,
api_provider: client_setup.api_provider,
auth_revision: client_setup.auth_revision,
api_auth: client_setup.api_auth,
auth_owner_generation: client_setup.auth_owner_generation,
responses_metadata: &websocket_metadata,
auth_context,
request_route_telemetry: RequestRouteTelemetry::for_endpoint("/responses"),
responses_headers: &responses_headers,
})
.await
{
Ok(_) => return Ok(()),
Err(ApiError::Transport(TransportError::Http { status, .. }))
if status == StatusCode::UPGRADE_REQUIRED =>
{
self.try_switch_fallback_transport(session_telemetry, model_info);
return Ok(());
}
Err(ApiError::Transport(unauthorized_transport))
if provider.is_recoverable_auth_error(&unauthorized_transport) =>
{
pending_retry = PendingUnauthorizedRetry::from_recovery(
handle_unauthorized(
unauthorized_transport,
&mut auth_recovery,
&mut provider_auth_recovery_attempted,
session_telemetry,
&provider,
self.client.event_sender.as_ref(),
responses_metadata.turn_id.as_deref(),
)
.await?,
);
}
Err(err) => return Err(provider.map_api_error(err)),
}
}
self.websocket_session.reset(Some("other"));
let auth_context = AuthRequestTelemetryContext::new(
client_setup.auth.as_ref().map(CodexAuth::auth_mode),
client_setup.api_auth.as_ref(),
client_setup.agent_identity_telemetry.clone(),
PendingUnauthorizedRetry::default(),
);
let responses_headers = self
.client
.responses_headers(client_setup.auth.as_ref(), &model_info.slug);
self.websocket_connection(WebsocketConnectParams {
session_telemetry,
api_provider: client_setup.api_provider,
auth_revision: client_setup.auth_revision,
api_auth: client_setup.api_auth,
auth_owner_generation: client_setup.auth_owner_generation,
responses_metadata,
auth_context,
request_route_telemetry: RequestRouteTelemetry::for_endpoint("/responses"),
responses_headers: &responses_headers,
})
.await?;
Ok(())
}
/// Returns a websocket connection for this turn.
#[instrument(
name = "model_client.websocket_connection",
@@ -1674,19 +1706,15 @@ impl ModelClientSession {
client_setup.auth.as_ref(),
&responses_headers,
);
let guardian_reviewer = responses_headers
.get("x-codex-guardian")
.is_some_and(|value| value == "reviewer");
if guardian_reviewer {
if is_guardian_reviewer(&responses_headers) {
request.service_tier = None;
}
if !guardian_reviewer
&& let Some(header_value) = self.client.build_routing_hint_header(
client_setup.auth.as_ref(),
&request.model,
request.service_tier.as_deref(),
)
{
if let Some(header_value) = self.client.build_routing_hint_header(
client_setup.auth.as_ref(),
&responses_headers,
&request.model,
request.service_tier.as_deref(),
) {
options
.extra_headers
.insert(X_CODEX_ROUTING_HINT_HEADER, header_value);
@@ -1828,10 +1856,7 @@ impl ModelClientSession {
responses_metadata,
include_internal,
)?;
let guardian_reviewer = responses_headers
.get("x-codex-guardian")
.is_some_and(|value| value == "reviewer");
if guardian_reviewer {
if is_guardian_reviewer(&responses_headers) {
request.service_tier = None;
}
request.access_programs = cyber_access_program::for_auth(
@@ -1839,15 +1864,12 @@ impl ModelClientSession {
prompt.cyber_access_program,
);
let mut websocket_metadata = responses_metadata.clone();
websocket_metadata.routing_hint = if !guardian_reviewer {
self.client.build_routing_hint_header(
client_setup.auth.as_ref(),
&request.model,
request.service_tier.as_deref(),
)
} else {
None
};
websocket_metadata.routing_hint = self.client.build_routing_hint_header(
client_setup.auth.as_ref(),
&responses_headers,
&request.model,
request.service_tier.as_deref(),
);
let request_session_telemetry = if warmup {
// `generate=false` prewarm is connection setup, not an inference request.
session_telemetry.clone()
@@ -2216,6 +2238,12 @@ fn stamp_ws_stream_request_start_ms(request: &mut ResponsesWsRequest<'_>) {
);
}
fn is_guardian_reviewer(responses_headers: &ApiHeaderMap) -> bool {
responses_headers
.get("x-codex-guardian")
.is_some_and(|value| value == "reviewer")
}
/// Builds the extra headers attached to Responses API requests.
///
/// These headers implement Codex-specific conventions:
+1 -1
View File
@@ -1071,7 +1071,7 @@ pub(crate) fn new_submission_id() -> String {
Uuid::now_v7().to_string()
}
fn get_service_tier(
pub(crate) fn get_service_tier(
configured_service_tier: Option<String>,
fast_mode_enabled: bool,
model_info: &ModelInfo,
+1 -1
View File
@@ -709,7 +709,7 @@ impl Session {
)
}
fn with_window_and_fork_metadata(
pub(crate) fn with_window_and_fork_metadata(
&self,
turn_context: &TurnContext,
responses_metadata: CodexResponsesMetadata,
+58 -12
View File
@@ -23,6 +23,8 @@ use codex_otel::STARTUP_PREWARM_DURATION_METRIC;
use codex_otel::SessionTelemetry;
use codex_protocol::error::Result as CodexResult;
use codex_protocol::models::BaseInstructions;
use codex_protocol::protocol::SessionSource;
use codex_protocol::protocol::SubAgentSource;
pub(crate) struct SessionStartupPrewarmHandle {
task: AbortOnDropHandle<CodexResult<ModelClientSession>>,
@@ -273,19 +275,63 @@ async fn schedule_startup_prewarm_inner(
/*status*/ None,
);
let startup_cancellation_token = CancellationToken::new();
let built_tools_started_at = Instant::now();
// Startup prewarm runs before run_turn and needs its own tool-building snapshot.
let step_context = session
.capture_step_context(
Arc::clone(&startup_turn_context),
&startup_cancellation_token,
let preconnect_model_info = Arc::clone(startup_turn_context.model_info());
// Spawned subagents inherit the root's selection, with the same feature and model filtering
// that capture applies to the actual request.
let preconnect_service_tier = if matches!(
startup_turn_context.session_source,
SessionSource::SubAgent(SubAgentSource::ThreadSpawn { .. })
) {
crate::session::get_service_tier(
session.services.agent_control.service_tier(),
session.features().enabled(Feature::FastMode),
&preconnect_model_info,
)
.await?;
startup_turn_context.session_telemetry.record_startup_phase(
"startup_prewarm_build_tools",
built_tools_started_at.elapsed(),
/*status*/ None,
} else {
startup_turn_context.initial_settings.service_tier.clone()
};
// The handshake precedes tool capture; attach the finalized step metadata to the warmup.
let (window_id, window_number, context_window_id) = session.current_window().await;
let mut handshake_metadata = startup_turn_context
.turn_metadata_state
.to_responses_metadata(
session.installation_id.clone(),
window_id,
CodexResponsesRequestKind::Prewarm,
);
crate::turn_metadata::ExecutionMetadata::from_settings(&startup_turn_context.initial_settings)
.apply_to(&mut handshake_metadata);
let handshake_metadata = session.with_window_and_fork_metadata(
&startup_turn_context,
handshake_metadata,
window_number,
context_window_id,
);
let mut client_session = session.services.model_client.new_session();
// Start the handshake with the expected route while capturing tools for generate=false.
let (step_context, ()) = tokio::try_join!(
async {
let built_tools_started_at = Instant::now();
let step_context = session
.capture_step_context(
Arc::clone(&startup_turn_context),
&startup_cancellation_token,
)
.await?;
startup_turn_context.session_telemetry.record_startup_phase(
"startup_prewarm_build_tools",
built_tools_started_at.elapsed(),
/*status*/ None,
);
Ok(step_context)
},
client_session.preconnect_websocket(
&preconnect_model_info,
preconnect_service_tier,
&startup_turn_context.session_telemetry,
&handshake_metadata,
),
)?;
let build_prompt_started_at = Instant::now();
let startup_prompt = build_prompt(
Vec::new(),
@@ -300,10 +346,10 @@ async fn schedule_startup_prewarm_inner(
build_prompt_started_at.elapsed(),
/*status*/ None,
);
// Tool discovery may have updated Responses Lite metadata since the eager handshake.
let responses_metadata = session
.responses_metadata(step_context.as_ref(), CodexResponsesRequestKind::Prewarm)
.await;
let mut client_session = session.services.model_client.new_session();
let websocket_warmup_started_at = Instant::now();
// Prewarm establishes the request baseline before the first turn can change effort.
client_session