Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Report specific reasons for WebSocket continuation failures (#51895)

pakrym-oaifac5d0ba91b9
diff --git a/codex-rs/core/src/client.rs b/codex-rs/core/src/client.rs
index 24f2964ffe..085a6bd52f 100644
--- a/codex-rs/core/src/client.rs
+++ b/codex-rs/core/src/client.rs
@@ -334,14 +334,56 @@ struct WebsocketSession {
continuation_reset_reason: Option<&'static str>,
}
+// Continuation diagnostics use bounded labels, never request contents or identifiers.
+#[derive(Debug, PartialEq, Eq)]
+enum NonIncrementalReason {
+ NoPreviousRequest,
+ NoPreviousResponse,
+ NoPreviousResponseId,
+ RequestPropertyChanged {
+ reason: &'static str,
+ },
+ InputShortened {
+ previous: &'static str,
+ },
+ InputMismatch {
+ previous: &'static str,
+ current: &'static str,
+ },
+}
+
+impl NonIncrementalReason {
+ fn as_str(&self) -> &'static str {
+ match self {
+ Self::NoPreviousRequest => "no_previous_request",
+ Self::NoPreviousResponse => "no_previous_response",
+ Self::NoPreviousResponseId => "no_previous_response_id",
+ Self::RequestPropertyChanged { reason } => reason,
+ Self::InputShortened { .. } => "input_shortened",
+ Self::InputMismatch { .. } => "input_mismatch",
+ }
+ }
+
+ fn item_types(&self) -> (&'static str, &'static str) {
+ match self {
+ Self::InputShortened { previous } => (previous, "none"),
+ Self::InputMismatch { previous, current } => (previous, current),
+ Self::NoPreviousRequest
+ | Self::NoPreviousResponse
+ | Self::NoPreviousResponseId
+ | Self::RequestPropertyChanged { .. } => ("none", "none"),
+ }
+ }
+}
+
// This is intentionally not a `PartialEq` implementation: request equality includes `input` and
// `client_metadata`, while websocket reuse compares input and late tool-result metadata separately.
// Access programs are authorized per response, including continuations, without replaying input.
// Keep the destructuring exhaustive so new request fields require an explicit reuse decision.
-fn responses_request_properties_match(
+fn responses_request_properties_mismatch(
previous: &ResponsesApiRequest,
current: &ResponsesApiRequest,
-) -> bool {
+) -> Option<&'static str> {
let ResponsesApiRequest {
model: previous_model,
input: _,
@@ -377,19 +419,34 @@ fn responses_request_properties_match(
access_programs: _,
} = current;
- previous_model == current_model
- && previous_tools == current_tools
- && previous_tool_choice == current_tool_choice
- && previous_parallel_tool_calls == current_parallel_tool_calls
- && previous_reasoning == current_reasoning
- && previous_store == current_store
- && previous_stream == current_stream
- // Stream options control delivery for this response, not the context
- // referenced by `previous_response_id`.
- && previous_include == current_include
- && previous_service_tier == current_service_tier
- && previous_prompt_cache_key == current_prompt_cache_key
- && previous_text == current_text
+ // Stream options control delivery for this response, not the context
+ // referenced by `previous_response_id`.
+ let reason = if previous_model != current_model {
+ "model_changed"
+ } else if previous_tools != current_tools {
+ "tools_changed"
+ } else if previous_tool_choice != current_tool_choice {
+ "tool_choice_changed"
+ } else if previous_parallel_tool_calls != current_parallel_tool_calls {
+ "parallel_tool_calls_changed"
+ } else if previous_reasoning != current_reasoning {
+ "reasoning_changed"
+ } else if previous_store != current_store {
+ "store_changed"
+ } else if previous_stream != current_stream {
+ "stream_changed"
+ } else if previous_include != current_include {
+ "include_changed"
+ } else if previous_service_tier != current_service_tier {
+ "service_tier_changed"
+ } else if previous_prompt_cache_key != current_prompt_cache_key {
+ "prompt_cache_key_changed"
+ } else if previous_text != current_text {
+ "text_changed"
+ } else {
+ return None;
+ };
+ Some(reason)
}
fn response_items_equal_ignoring_internal_metadata(
@@ -1402,35 +1459,33 @@ impl ModelClientSession {
&self,
request: &ResponsesApiRequest,
last_response: &LastResponse,
- ) -> Option<Vec<ResponseItem>> {
- let previous_request = self.websocket_session.last_request.as_ref()?;
- if !responses_request_properties_match(previous_request, request) {
- trace!("incremental request failed, websocket reuse properties didn't match");
- return None;
+ ) -> std::result::Result<Vec<ResponseItem>, NonIncrementalReason> {
+ let previous_request = self
+ .websocket_session
+ .last_request
+ .as_ref()
+ .ok_or(NonIncrementalReason::NoPreviousRequest)?;
+ if let Some(reason) = responses_request_properties_mismatch(previous_request, request) {
+ return Err(NonIncrementalReason::RequestPropertyChanged { reason });
}
let response_items = &last_response.items_added;
- let previous_items_len = previous_request
- .input
- .len()
- .checked_add(response_items.len())?;
- let Some((request_items_to_compare, incremental_items)) =
- request.input.split_at_checked(previous_items_len)
- else {
- trace!("incremental request failed, incompatible request length");
- return None;
- };
let previous_items = previous_request.input.iter().chain(response_items);
- if !previous_items
- .zip(request_items_to_compare)
- .all(|(previous, current)| {
- response_items_equal_ignoring_internal_metadata(previous, current)
- })
- {
- trace!("incremental request failed, items didn't match");
- return None;
+ let mut current_items = request.input.iter();
+ for previous in previous_items {
+ let Some(current) = current_items.next() else {
+ return Err(NonIncrementalReason::InputShortened {
+ previous: previous.item_type(),
+ });
+ };
+ if !response_items_equal_ignoring_internal_metadata(previous, current) {
+ return Err(NonIncrementalReason::InputMismatch {
+ previous: previous.item_type(),
+ current: current.item_type(),
+ });
+ }
}
- Some(incremental_items.to_vec())
+ Ok(current_items.cloned().collect())
}
fn get_last_response(&mut self) -> Option<LastResponse> {
@@ -1446,16 +1501,17 @@ impl ModelClientSession {
fn prepare_websocket_request(
&mut self,
request: &ResponsesApiRequest,
- ) -> Option<WebsocketContinuation> {
- let last_response = self.get_last_response()?;
+ ) -> std::result::Result<WebsocketContinuation, NonIncrementalReason> {
+ let last_response = self
+ .get_last_response()
+ .ok_or(NonIncrementalReason::NoPreviousResponse)?;
let items = self.get_incremental_items(request, &last_response)?;
if last_response.response_id.is_empty() {
- trace!("incremental request failed, no previous response id");
- return None;
+ return Err(NonIncrementalReason::NoPreviousResponseId);
}
- Some(WebsocketContinuation {
+ Ok(WebsocketContinuation {
response_id: last_response.response_id,
items,
from_untraced_warmup: self.websocket_session.last_response_from_untraced_warmup,
@@ -1976,23 +2032,35 @@ impl ModelClientSession {
if let Some(turn_state) = self.turn_state.get() {
client_metadata.insert(X_CODEX_TURN_STATE_HEADER.to_string(), turn_state.clone());
}
- let continuation = self.prepare_websocket_request(&request);
- let (mode, reason) = if continuation.is_some() {
- ("incremental", "incremental")
- } else {
- let reason = self
- .websocket_session
- .continuation_reset_reason
- .take()
- .unwrap_or(if self.websocket_session.last_request.is_some() {
- "other"
- } else if self.client.restored_history {
- "restored_history"
- } else {
- "no_previous_request"
- });
- ("full", reason)
- };
+ let (continuation, mode, reason, previous_item_type, current_item_type) =
+ match self.prepare_websocket_request(&request) {
+ Ok(continuation) => (
+ Some(continuation),
+ "incremental",
+ "incremental",
+ "none",
+ "none",
+ ),
+ Err(failure) => {
+ let reason = self
+ .websocket_session
+ .continuation_reset_reason
+ .take()
+ .unwrap_or(if self.websocket_session.last_request.is_some() {
+ failure.as_str()
+ } else if self.client.restored_history {
+ "restored_history"
+ } else {
+ "no_previous_request"
+ });
+ let (previous_item_type, current_item_type) = failure.item_types();
+ trace!(
+ reason,
+ previous_item_type, current_item_type, "non-incremental request"
+ );
+ (None, "full", reason, previous_item_type, current_item_type)
+ }
+ };
let previous_response_id_from_untraced_warmup = continuation
.as_ref()
.is_some_and(|c| c.from_untraced_warmup);
@@ -2082,6 +2150,8 @@ impl ModelClientSession {
&[
("mode", mode),
("reason", reason),
+ ("previous_item_type", previous_item_type),
+ ("current_item_type", current_item_type),
("phase", if warmup { "warmup" } else { "generation" }),
(
"after_prewarm",
diff --git a/codex-rs/core/src/client_tests.rs b/codex-rs/core/src/client_tests.rs
index 779a40ca2b..5b6f7276b4 100644
--- a/codex-rs/core/src/client_tests.rs
+++ b/codex-rs/core/src/client_tests.rs
@@ -1,5 +1,6 @@
use super::AuthRequestTelemetryContext;
use super::ModelClient;
+use super::NonIncrementalReason;
use super::PendingUnauthorizedRetry;
use super::Prompt;
use super::UnauthorizedRecoveryExecution;
@@ -943,13 +944,77 @@ fn websocket_incremental_reuse_tracks_raw_result_metadata() -> anyhow::Result<()
continuation.items,
continuation.from_untraced_warmup,
)),
- expect_incremental.then_some(("previous-response".to_string(), vec![follow_up], false)),
+ if expect_incremental {
+ Ok(("previous-response".to_string(), vec![follow_up], false))
+ } else {
+ Err(NonIncrementalReason::InputMismatch {
+ previous: "custom_tool_call_output",
+ current: "custom_tool_call_output",
+ })
+ },
"{scenario}",
);
}
Ok(())
}
+#[test]
+fn websocket_continuation_reports_unavailable_response_state() {
+ let client = test_model_client(SessionSource::Cli);
+ let request = client
+ .build_responses_request(
+ &Prompt::default(),
+ &test_model_info(),
+ /*effort*/ None,
+ codex_protocol::config_types::ReasoningSummary::None,
+ /*service_tier*/ None,
+ &test_responses_metadata_for_client(
+ &client,
+ /*turn_id*/ None,
+ format!("{}:0", client.state.thread_id),
+ /*parent_thread_id*/ None,
+ TestCodexResponsesRequestKind::Turn,
+ ),
+ /*include_internal*/ true,
+ )
+ .expect("build continuation request");
+ let mut session = client.new_session();
+ session.websocket_session.last_request = Some(request.clone());
+ assert_eq!(
+ session.prepare_websocket_request(&request).err(),
+ Some(NonIncrementalReason::NoPreviousResponse),
+ );
+
+ let (sender, receiver) = tokio::sync::oneshot::channel();
+ session.websocket_session.last_response_rx = Some(receiver);
+ assert_eq!(
+ session.prepare_websocket_request(&request).err(),
+ Some(NonIncrementalReason::NoPreviousResponse),
+ );
+ drop(sender);
+
+ let (sender, receiver) = tokio::sync::oneshot::channel();
+ drop(sender);
+ session.websocket_session.last_response_rx = Some(receiver);
+ assert_eq!(
+ session.prepare_websocket_request(&request).err(),
+ Some(NonIncrementalReason::NoPreviousResponse),
+ );
+
+ let (sender, receiver) = tokio::sync::oneshot::channel();
+ sender
+ .send(super::LastResponse {
+ response_id: String::new(),
+ items_added: Vec::new(),
+ })
+ .unwrap();
+ session.websocket_session.last_response_rx = Some(receiver);
+ assert_eq!(
+ session.prepare_websocket_request(&request).err(),
+ Some(NonIncrementalReason::NoPreviousResponseId),
+ );
+}
+
#[tokio::test]
async fn responses_http_preserves_raw_tool_metadata_for_openai_custom_endpoint()
-> anyhow::Result<()> {
diff --git a/codex-rs/core/src/stream_events_utils.rs b/codex-rs/core/src/stream_events_utils.rs
index 0264a09389..d1e2b06be5 100644
--- a/codex-rs/core/src/stream_events_utils.rs
+++ b/codex-rs/core/src/stream_events_utils.rs
@@ -438,28 +438,8 @@ pub(crate) async fn handle_non_tool_response_item(
item: &ResponseItem,
plan_mode: bool,
) -> Option<TurnItem> {
- let item_type = match item {
- ResponseItem::AdditionalTools { .. } => "additional_tools",
- ResponseItem::Message { .. } => "message",
- ResponseItem::AgentMessage { .. } => "agent_message",
- ResponseItem::Reasoning { .. } => "reasoning",
- ResponseItem::LocalShellCall { .. } => "local_shell_call",
- ResponseItem::FunctionCall { .. } => "function_call",
- ResponseItem::ToolSearchCall { .. } => "tool_search_call",
- ResponseItem::FunctionCallOutput { .. } => "function_call_output",
- ResponseItem::CustomToolCall { .. } => "custom_tool_call",
- ResponseItem::CustomToolCallOutput { .. } => "custom_tool_call_output",
- ResponseItem::ToolSearchOutput { .. } => "tool_search_output",
- ResponseItem::WebSearchCall { .. } => "web_search_call",
- ResponseItem::ImageGenerationCall { .. } => "image_generation_call",
- ResponseItem::Compaction { .. } => "compaction",
- ResponseItem::ConfigurationUpdate { .. } => "configuration_update",
- ResponseItem::CompactionTrigger { .. } => "compaction_trigger",
- ResponseItem::ContextCompaction { .. } => "context_compaction",
- ResponseItem::Other => "other",
- };
debug!(
- item_type,
+ item_type = item.item_type(),
item_id = item.id().map(ResponseItemId::as_str),
"Output item"
);
diff --git a/codex-rs/core/tests/suite/client_websockets.rs b/codex-rs/core/tests/suite/client_websockets.rs
index 6659bba1f4..80532652c3 100755
--- a/codex-rs/core/tests/suite/client_websockets.rs
+++ b/codex-rs/core/tests/suite/client_websockets.rs
@@ -2240,12 +2240,36 @@ async fn responses_websocket_uses_previous_response_id_when_prefix_after_complet
server.shutdown().await;
}
+#[test_case::test_case(vec![message_item("different")], "input_mismatch", "message"; "rewritten")]
+#[test_case::test_case(
+ vec![ResponseItem::Compaction {
+ id: None,
+ encrypted_content: "compacted".to_string(),
+ internal_chat_message_metadata_passthrough: None,
+ }],
+ "input_mismatch",
+ "compaction"; "replaced"
+)]
+#[test_case::test_case(
+ vec![message_item("hello"), assistant_message_item("1", "changed output")],
+ "input_mismatch",
+ "message"; "rewritten server output"
+)]
+#[test_case::test_case(vec![message_item("hello")], "input_shortened", "none"; "missing server output")]
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn responses_websocket_creates_on_non_prefix() {
+async fn responses_websocket_creates_on_non_prefix(
+ input: Vec<ResponseItem>,
+ reason: &str,
+ current_item_type: &str,
+) {
skip_if_no_network!();
let server = start_websocket_server(vec![vec![
- vec![ev_response_created("resp-1"), ev_completed("resp-1")],
+ vec![
+ ev_response_created("resp-1"),
+ ev_assistant_message("msg_1", "assistant output"),
+ ev_completed("resp-1"),
+ ],
vec![ev_response_created("resp-2"), ev_completed("resp-2")],
]])
.await;
@@ -2253,7 +2277,7 @@ async fn responses_websocket_creates_on_non_prefix() {
let harness = websocket_harness(&server).await;
let mut client_session = harness.client.new_session();
let prompt_one = prompt_with_input(vec![message_item("hello")]);
- let prompt_two = prompt_with_input(vec![message_item("different")]);
+ let prompt_two = prompt_with_input(input);
stream_until_complete(&mut client_session, &harness, &prompt_one).await;
stream_until_complete(&mut client_session, &harness, &prompt_two).await;
@@ -2271,11 +2295,17 @@ async fn responses_websocket_creates_on_non_prefix() {
serde_json::to_value(&prompt_two.input).unwrap()
);
- assert_continuation_metrics(
+ assert_continuation_metrics_with_item_types(
&harness.session_telemetry,
&[
- (["full", "other", "generation"], 1),
- (["full", "no_previous_request", "generation"], 1),
+ (
+ ["full", reason, "generation", "message", current_item_type],
+ 1,
+ ),
+ (
+ ["full", "no_previous_request", "generation", "none", "none"],
+ 1,
+ ),
],
);
server.shutdown().await;
@@ -2322,11 +2352,17 @@ async fn responses_websocket_creates_when_instructions_change() {
.unwrap()
);
- assert_continuation_metrics(
+ assert_continuation_metrics_with_item_types(
&harness.session_telemetry,
&[
- (["full", "no_previous_request", "generation"], 1),
- (["full", "other", "generation"], 1),
+ (
+ ["full", "no_previous_request", "generation", "none", "none"],
+ 1,
+ ),
+ (
+ ["full", "input_mismatch", "generation", "message", "message"],
+ 1,
+ ),
],
);
server.shutdown().await;
@@ -2374,9 +2410,15 @@ async fn responses_websocket_v2_creates_with_previous_response_id_on_prefix() {
server.shutdown().await;
}
+#[test_case::test_case(None, Some(json!({"type": "object", "properties": {}})), "text_changed"; "output schema")]
+#[test_case::test_case(Some("changed-model"), None, "model_changed"; "model")]
+#[test_case::test_case(Some("changed-model"), Some(json!({"type": "object"})), "model_changed"; "first changed property")]
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn responses_websocket_v2_creates_without_previous_response_id_when_non_input_fields_change()
-{
+async fn responses_websocket_v2_creates_without_previous_response_id_when_non_input_fields_change(
+ model: Option<&str>,
+ output_schema: Option<serde_json::Value>,
+ reason: &str,
+) {
skip_if_no_network!();
let server = start_websocket_server(vec![vec![
@@ -2389,10 +2431,21 @@ async fn responses_websocket_v2_creates_without_previous_response_id_when_non_in
let mut session = harness.client.new_session();
let prompt_one = prompt_with_input(vec![message_item("hello")]);
let mut prompt_two = prompt_with_input(vec![message_item("hello"), message_item("second")]);
- prompt_two.output_schema = Some(json!({"type": "object", "properties": {}}));
+ prompt_two.output_schema = output_schema;
+ let mut model_info = harness.model_info.clone();
+ if let Some(model) = model {
+ model_info.slug = model.to_string();
+ }
stream_until_complete(&mut session, &harness, &prompt_one).await;
- stream_until_complete(&mut session, &harness, &prompt_two).await;
+ stream_until_complete_with_model_info(
+ &mut session,
+ &harness,
+ &prompt_two,
+ &model_info,
+ "resp-2",
+ )
+ .await;
let connection = server.single_connection();
assert_eq!(connection.len(), 2);
@@ -2405,6 +2458,13 @@ async fn responses_websocket_v2_creates_without_previous_response_id_when_non_in
serde_json::to_value(&prompt_two.input).expect("serialize full input")
);
+ assert_continuation_metrics(
+ &harness.session_telemetry,
+ &[
+ (["full", "no_previous_request", "generation"], 1),
+ (["full", reason, "generation"], 1),
+ ],
+ );
server.shutdown().await;
}
@@ -2880,6 +2940,17 @@ async fn responses_websocket_restored_history_metric(fork: bool) -> anyhow::Resu
}
fn assert_continuation_metrics(telemetry: &SessionTelemetry, expected: &[([&str; 3], u64)]) {
+ let expected = expected
+ .iter()
+ .map(|([mode, reason, phase], count)| ([*mode, *reason, *phase, "none", "none"], *count))
+ .collect::<Vec<_>>();
+ assert_continuation_metrics_with_item_types(telemetry, &expected);
+}
+
+fn assert_continuation_metrics_with_item_types(
+ telemetry: &SessionTelemetry,
+ expected: &[([&str; 5], u64)],
+) {
use opentelemetry_sdk::metrics::data::AggregatedMetrics;
use opentelemetry_sdk::metrics::data::MetricData;
@@ -2899,7 +2970,14 @@ fn assert_continuation_metrics(telemetry: &SessionTelemetry, expected: &[([&str;
let mut actual: Vec<_> = sum
.data_points()
.map(|point| {
- let tags = ["mode", "reason", "phase"].map(|key| {
+ let tags = [
+ "mode",
+ "reason",
+ "phase",
+ "previous_item_type",
+ "current_item_type",
+ ]
+ .map(|key| {
point
.attributes()
.find(|attr| attr.key.as_str() == key)
diff --git a/codex-rs/protocol/src/models.rs b/codex-rs/protocol/src/models.rs
index 0d3305379f..f0ac0e51d7 100644
--- a/codex-rs/protocol/src/models.rs
+++ b/codex-rs/protocol/src/models.rs
@@ -1259,6 +1259,30 @@ pub enum ResponseItem {
}
impl ResponseItem {
+ /// Returns the wire type name for this response item.
+ pub fn item_type(&self) -> &'static str {
+ match self {
+ Self::AdditionalTools { .. } => "additional_tools",
+ Self::Message { .. } => "message",
+ Self::AgentMessage { .. } => "agent_message",
+ Self::Reasoning { .. } => "reasoning",
+ Self::LocalShellCall { .. } => "local_shell_call",
+ Self::FunctionCall { .. } => "function_call",
+ Self::ToolSearchCall { .. } => "tool_search_call",
+ Self::FunctionCallOutput { .. } => "function_call_output",
+ Self::CustomToolCall { .. } => "custom_tool_call",
+ Self::CustomToolCallOutput { .. } => "custom_tool_call_output",
+ Self::ToolSearchOutput { .. } => "tool_search_output",
+ Self::WebSearchCall { .. } => "web_search_call",
+ Self::ImageGenerationCall { .. } => "image_generation_call",
+ Self::Compaction { .. } => "compaction",
+ Self::ConfigurationUpdate { .. } => "configuration_update",
+ Self::CompactionTrigger { .. } => "compaction_trigger",
+ Self::ContextCompaction { .. } => "context_compaction",
+ Self::Other => "other",
+ }
+ }
+
/// Returns whether this item is an ordinary user-role message.
pub fn is_user_message(&self) -> bool {
matches!(self, Self::Message { role, .. } if role == "user")