Lightweight coding agent that runs in your terminal
Rust
Add diagnostic reasons to MCP attribution errors (#47899)
peilin-openai62197a65e52f
diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zstindex bb761a91dc..bc896e3ea9 100644Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst differdiff --git a/codex-rs/core/src/agent/control_tests.rs b/codex-rs/core/src/agent/control_tests.rsindex 1357e6c3c1..d40411b787 100644--- a/codex-rs/core/src/agent/control_tests.rs+++ b/codex-rs/core/src/agent/control_tests.rs@@ -58,6 +58,7 @@ use codex_protocol::items::TurnItem;use codex_protocol::items::UserMessageItem;use codex_protocol::mcp::ClientMcpExtensions;use codex_protocol::mcp::McpAttribution;+use codex_protocol::mcp::McpAttributionErrorReason;use codex_protocol::mcp::McpAttributionSource;use codex_protocol::mcp::McpAttributionStatus;use codex_protocol::mcp::OPENAI_FORM_EXTENSION_ID;@@ -3159,8 +3160,12 @@ async fn spawn_agent_full_fork_legacy_compaction_rebuilds_child_instructions_onc}}+#[test_case::test_case(false; "complete")]+#[test_case::test_case(true; "error_reason")]#[tokio::test]-async fn resume_and_cold_fork_restore_mcp_attribution_in_constructed_requests() {+async fn resume_and_cold_fork_restore_mcp_attribution_in_constructed_requests(+ record_invalid_source: bool,+) {let harness = AgentControlHarness::new().await;let (source_thread_id, source_thread) = harness.start_thread().await;let turn_context = source_thread.session.new_default_turn().await;@@ -3184,6 +3189,16 @@ async fn resume_and_cold_fork_restore_mcp_attribution_in_constructed_requests().services.executed_tool_calls.record_mcp_source(source.clone());+ if record_invalid_source {+ source_thread+ .session+ .services+ .executed_tool_calls+ .record_mcp_source(McpAttributionSource {+ tool_name: String::new(),+ ..source.clone()+ });+ }source_thread.session.record_conversation_items(@@ -3232,7 +3247,12 @@ async fn resume_and_cold_fork_restore_mcp_attribution_in_constructed_requests().await.expect("resume source thread");let expected = McpAttribution {- status: McpAttributionStatus::Complete,+ status: if record_invalid_source {+ McpAttributionStatus::AttributionError+ } else {+ McpAttributionStatus::Complete+ },+ error_reason: record_invalid_source.then_some(McpAttributionErrorReason::SourceInvalid),sources: vec![source],};assert_eq!(@@ -3475,6 +3495,7 @@ async fn spawn_agent_fork_last_n_turns_keeps_only_recent_turns() {mcp_attribution_in_constructed_request(&child_thread).await,McpAttribution {status: McpAttributionStatus::Complete,+ error_reason: None,sources: vec![source],});diff --git a/codex-rs/core/src/client_tests.rs b/codex-rs/core/src/client_tests.rsindex 318486aacc..92c84d4b66 100644--- a/codex-rs/core/src/client_tests.rs+++ b/codex-rs/core/src/client_tests.rs@@ -501,6 +501,7 @@ fn responses_request_limits_internal_metadata_to_resolved_first_party_https_endplet without_raw_metadata = output_with_tool_result_metadata(ToolResultMetadata::default());let attribution = McpAttribution {status: McpAttributionStatus::Complete,+ error_reason: None,sources: vec![McpAttributionSource {connector_id: Some("connector_example".to_string()),plugin_id: Some("example@openai-bundled".to_string()),@@ -587,6 +588,36 @@ fn responses_request_limits_internal_metadata_to_resolved_first_party_https_endpassert_eq!(prompt.input, vec![output.clone()]);}}+ responses_metadata.mcp_attribution = Some(McpAttribution {+ status: McpAttributionStatus::AttributionError,+ error_reason: Some(+ codex_protocol::mcp::McpAttributionErrorReason::HistoryMissingCheckpoint,+ ),+ sources: attribution.sources.clone(),+ });+ let request = client.build_responses_request(+ &prompt,+ &test_model_info(),+ /*effort*/ None,+ codex_protocol::config_types::ReasoningSummary::None,+ /*service_tier*/ None,+ &responses_metadata,+ /*include_internal*/ true,+ )?;+ assert_eq!(+ request+ .client_metadata+ .as_ref()+ .and_then(|metadata| metadata.get(MCP_ATTRIBUTION_CLIENT_METADATA_KEY))+ .map(|value| serde_json::from_str::<serde_json::Value>(value))+ .transpose()?,+ Some(json!({+ "status": "attribution_error",+ "sources": attribution.sources,+ "error_reason": "history_missing_checkpoint",+ })),+ );+let mut oversized_attribution = attribution;oversized_attribution.sources[0].tool_name = "a".repeat(MAX_MCP_ATTRIBUTION_BYTES);responses_metadata.mcp_attribution = Some(oversized_attribution);@@ -605,7 +636,7 @@ fn responses_request_limits_internal_metadata_to_resolved_first_party_https_endp.get(MCP_ATTRIBUTION_CLIENT_METADATA_KEY).map(String::as_str)}),- Some(r#"{"status":"attribution_error"}"#),+ Some(r#"{"status":"attribution_error","error_reason":"payload_too_large"}"#),);Ok(())}diff --git a/codex-rs/core/src/responses_metadata.rs b/codex-rs/core/src/responses_metadata.rsindex dcc6f5e407..bfdeb3b40f 100644--- a/codex-rs/core/src/responses_metadata.rs+++ b/codex-rs/core/src/responses_metadata.rs@@ -1,5 +1,6 @@use std::collections::BTreeMap;use std::collections::HashMap;+use std::io::ErrorKind;use codex_analytics::CompactionImplementation;use codex_analytics::CompactionPhase;@@ -359,7 +360,15 @@ impl CodexResponsesMetadata {}if include_internal && let Some(attribution) = &self.mcp_attribution {let serialized = to_json_string_bounded(attribution, MAX_MCP_ATTRIBUTION_BYTES)- .unwrap_or_else(|_| r#"{"status":"attribution_error"}"#.to_string());+ .unwrap_or_else(|error| {+ if error.io_error_kind() == Some(ErrorKind::WriteZero) {+ r#"{"status":"attribution_error","error_reason":"payload_too_large"}"#+ .to_string()+ } else {+ r#"{"status":"attribution_error","error_reason":"serialization_failed"}"#+ .to_string()+ }+ });client_metadata.insert(MCP_ATTRIBUTION_CLIENT_METADATA_KEY.to_string(), serialized);}client_metadatadiff --git a/codex-rs/core/src/session/tests.rs b/codex-rs/core/src/session/tests.rsindex 8f13c38d1e..d4f444d583 100644--- a/codex-rs/core/src/session/tests.rs+++ b/codex-rs/core/src/session/tests.rs@@ -5638,6 +5638,7 @@ async fn mcp_attribution_checkpoints_cover_batch_prefixes_compaction_and_restore.record_mcp_source(source.clone());let expected = McpAttribution {status: McpAttributionStatus::Complete,+ error_reason: None,sources: vec![source],};session@@ -6294,6 +6295,7 @@ async fn response_metadata_builders_capture_fresh_mcp_attribution() {.await;let expected = Some(McpAttribution {status: McpAttributionStatus::Complete,+ error_reason: None,sources: vec![source],});assert_eq!(before.mcp_attribution, Some(McpAttribution::default()));diff --git a/codex-rs/core/src/tools/executed_tool_calls/mcp_attribution.rs b/codex-rs/core/src/tools/executed_tool_calls/mcp_attribution.rsindex fce3f8f36d..86b03077c7 100644--- a/codex-rs/core/src/tools/executed_tool_calls/mcp_attribution.rs+++ b/codex-rs/core/src/tools/executed_tool_calls/mcp_attribution.rs@@ -7,6 +7,7 @@ use std::sync::MutexGuard;use codex_history::InitialHistory;use codex_history::RolloutItem;use codex_protocol::mcp::McpAttribution;+use codex_protocol::mcp::McpAttributionErrorReason;use codex_protocol::mcp::McpAttributionSource;use codex_protocol::mcp::McpAttributionStatus;@@ -56,25 +57,24 @@ impl McpAttributionRecorder {for item in history.get_rollout_items() {match item {RolloutItem::ResponseItem(envelope) => {- if let Some(checkpoint) = envelope- .metadata- .as_ref()- .and_then(|metadata| metadata.mcp_attribution.as_ref())+ if let Some(metadata) = envelope.metadata.as_ref()+ && let Some(checkpoint) = metadata.mcp_attribution.as_ref(){found_checkpoint = true;state.merge_checkpoint(checkpoint);}}RolloutItem::Compacted(compacted) => {- for checkpoint in compacted+ for metadata in compacted.replacement_history.iter().flatten().filter_map(|envelope| envelope.metadata.as_ref())- .filter_map(|metadata| metadata.mcp_attribution.as_ref()){- found_checkpoint = true;- state.merge_checkpoint(checkpoint);+ if let Some(checkpoint) = metadata.mcp_attribution.as_ref() {+ found_checkpoint = true;+ state.merge_checkpoint(checkpoint);+ }}}_ => {}@@ -82,7 +82,7 @@ impl McpAttributionRecorder {}if !found_checkpoint {// Pre-attribution history cannot establish that earlier context was MCP-free.- state.mark_error();+ state.mark_error(McpAttributionErrorReason::HistoryMissingCheckpoint);}Self(Arc::new(Mutex::new(state)))}@@ -90,7 +90,7 @@ impl McpAttributionRecorder {fn lock(&self) -> MutexGuard<'_, State> {self.0.lock().unwrap_or_else(|poisoned| {let mut state = poisoned.into_inner();- state.mark_error();+ state.mark_error(McpAttributionErrorReason::RecorderPoisoned);state})}@@ -116,20 +116,27 @@ impl McpAttributionRecorder {}impl State {- fn mark_error(&mut self) {+ fn mark_error(&mut self, reason: McpAttributionErrorReason) {if self.attribution.status != McpAttributionStatus::AttributionError {self.attribution.status = McpAttributionStatus::AttributionError;+ self.attribution.error_reason = Some(reason);self.revision += 1;}}fn merge_checkpoint(&mut self, checkpoint: &McpAttribution) {- if checkpoint.status == McpAttributionStatus::AttributionError- || (checkpoint.status == McpAttributionStatus::None && !checkpoint.sources.is_empty())+ if checkpoint.status == McpAttributionStatus::AttributionError {+ self.mark_error(+ checkpoint+ .error_reason+ .unwrap_or(McpAttributionErrorReason::RestoredErrorUnknown),+ );+ } else if (checkpoint.status == McpAttributionStatus::None+ && !checkpoint.sources.is_empty())|| (checkpoint.status == McpAttributionStatus::Complete&& checkpoint.sources.is_empty()){- self.mark_error();+ self.mark_error(McpAttributionErrorReason::CheckpointInvalid);}for source in &checkpoint.sources {self.record(source.clone(), /*restoring*/ true);@@ -145,7 +152,7 @@ impl State {.find(|existing| SourceIdentity::from(*existing) == identity){if restoring && existing.first_turn_id != source.first_turn_id {- self.mark_error();+ self.mark_error(McpAttributionErrorReason::CheckpointSourceConflict);}return;}@@ -153,7 +160,11 @@ impl State {|| source.tool_name.is_empty()|| source.first_turn_id.is_empty(){- self.mark_error();+ self.mark_error(if restoring {+ McpAttributionErrorReason::CheckpointInvalid+ } else {+ McpAttributionErrorReason::SourceInvalid+ });return;}if self.attribution.status == McpAttributionStatus::None {diff --git a/codex-rs/core/src/tools/executed_tool_calls/mcp_attribution_tests.rs b/codex-rs/core/src/tools/executed_tool_calls/mcp_attribution_tests.rsindex a7c9dbb391..8d90927ddc 100644--- a/codex-rs/core/src/tools/executed_tool_calls/mcp_attribution_tests.rs+++ b/codex-rs/core/src/tools/executed_tool_calls/mcp_attribution_tests.rs@@ -44,6 +44,7 @@ fn records_the_first_turn_for_each_unique_source() {recorder.snapshot(),McpAttribution {status: McpAttributionStatus::Complete,+ error_reason: None,sources: vec![source("search", "turn_1"), source("fetch", "turn_2")],});@@ -53,10 +54,12 @@ fn records_the_first_turn_for_each_unique_source() {fn restores_cumulative_item_and_compaction_checkpoints() {let initial = McpAttribution {status: McpAttributionStatus::Complete,+ error_reason: None,sources: vec![source("search", "turn_1")],};let cumulative = McpAttribution {status: McpAttributionStatus::Complete,+ error_reason: None,sources: vec![source("search", "turn_1"), source("fetch", "turn_2")],};let history = InitialHistory::Forked(vec![@@ -89,6 +92,7 @@ fn legacy_or_conflicting_history_is_not_complete() {McpAttributionRecorder::new(&legacy).snapshot(),McpAttribution {status: McpAttributionStatus::AttributionError,+ error_reason: Some(McpAttributionErrorReason::HistoryMissingCheckpoint),sources: Vec::new(),});@@ -98,6 +102,7 @@ fn legacy_or_conflicting_history_is_not_complete() {.map(|turn_id| {RolloutItem::ResponseItem(envelope(Some(McpAttribution {status: McpAttributionStatus::Complete,+ error_reason: None,sources: vec![source("search", turn_id)],})))})@@ -107,11 +112,116 @@ fn legacy_or_conflicting_history_is_not_complete() {McpAttributionRecorder::new(&history).snapshot(),McpAttribution {status: McpAttributionStatus::AttributionError,+ error_reason: Some(McpAttributionErrorReason::CheckpointSourceConflict),sources: vec![source("search", "turn_1")],});}+#[test]+fn first_error_reason_survives_checkpoints_and_later_sources() {+ let recorder = McpAttributionRecorder::default();+ recorder.record(source("", "turn_1"));+ recorder.record(source("search", "turn_2"));+ let (snapshot, _) = recorder+ .checkpoint(/*force*/ true)+ .expect("error checkpoint");+ let checkpoint = envelope(Some(snapshot));+ let mut compacted: CompactedItem =+ serde_json::from_value(serde_json::json!({"message": "summary"}))+ .expect("compaction checkpoint");+ compacted.replacement_history = Some(vec![checkpoint.clone()]);+ for item in [+ RolloutItem::ResponseItem(checkpoint),+ RolloutItem::Compacted(compacted),+ ] {+ let restored = McpAttributionRecorder::new(&InitialHistory::Forked(vec![item]));+ restored.record(source("", "turn_3"));++ assert_eq!(+ restored.snapshot(),+ McpAttribution {+ status: McpAttributionStatus::AttributionError,+ error_reason: Some(McpAttributionErrorReason::SourceInvalid),+ sources: vec![source("search", "turn_2")],+ },+ );+ }+}++#[test]+fn poisoned_recorder_reports_a_bounded_reason() {+ let recorder = McpAttributionRecorder::default();+ let poisoned = recorder.clone();+ assert!(+ std::thread::spawn(move || {+ let _state = poisoned.0.lock().expect("unpoisoned recorder");+ panic!("poison recorder");+ })+ .join()+ .is_err()+ );+ assert_eq!(+ recorder.snapshot(),+ McpAttribution {+ status: McpAttributionStatus::AttributionError,+ error_reason: Some(McpAttributionErrorReason::RecorderPoisoned),+ sources: Vec::new(),+ }+ );+}++#[test]+fn restored_diagnostics_do_not_change_attribution_state() {+ let checkpoint = envelope(Some(McpAttribution {+ status: McpAttributionStatus::Complete,+ error_reason: Some(McpAttributionErrorReason::SourceInvalid),+ sources: vec![source("search", "turn_1")],+ }));+ assert_eq!(+ McpAttributionRecorder::new(&InitialHistory::Forked(vec![RolloutItem::ResponseItem(+ checkpoint+ ),]))+ .snapshot(),+ McpAttribution {+ status: McpAttributionStatus::Complete,+ error_reason: None,+ sources: vec![source("search", "turn_1")],+ }+ );++ for (attribution, expected_reason) in [+ (+ McpAttribution {+ status: McpAttributionStatus::AttributionError,+ error_reason: None,+ sources: Vec::new(),+ },+ McpAttributionErrorReason::RestoredErrorUnknown,+ ),+ (+ McpAttribution {+ status: McpAttributionStatus::Complete,+ error_reason: None,+ sources: Vec::new(),+ },+ McpAttributionErrorReason::CheckpointInvalid,+ ),+ ] {+ assert_eq!(+ McpAttributionRecorder::new(&InitialHistory::Forked(vec![RolloutItem::ResponseItem(+ envelope(Some(attribution))+ ),]))+ .snapshot(),+ McpAttribution {+ status: McpAttributionStatus::AttributionError,+ error_reason: Some(expected_reason),+ sources: Vec::new(),+ }+ );+ }+}+#[test]fn acknowledging_an_older_checkpoint_does_not_clear_newer_changes() {let recorder = McpAttributionRecorder::default();diff --git a/codex-rs/history/src/lib.rs b/codex-rs/history/src/lib.rsindex e30ebd1a4d..5a8876aaa5 100644--- a/codex-rs/history/src/lib.rs+++ b/codex-rs/history/src/lib.rs@@ -124,6 +124,7 @@ whereOk(Some(serde_json::from_value(value).unwrap_or_else(|_| {McpAttribution {status: McpAttributionStatus::AttributionError,+ error_reason: None,sources: Vec::new(),}})))diff --git a/codex-rs/history/src/tests.rs b/codex-rs/history/src/tests.rsindex c414bacb77..96733b2041 100644--- a/codex-rs/history/src/tests.rs+++ b/codex-rs/history/src/tests.rs@@ -181,12 +181,54 @@ fn mcp_checkpoint_handles_missing_or_unknown_identity() -> Result<()> {restored.mcp_attribution,Some(McpAttribution {status: McpAttributionStatus::AttributionError,+ error_reason: None,sources: Vec::new(),}));Ok(())}+#[test]+fn mcp_error_diagnostics_do_not_invalidate_checkpoints() -> Result<()> {+ let metadata = CodexHarnessMetadata {+ mcp_attribution: Some(McpAttribution {+ status: McpAttributionStatus::AttributionError,+ error_reason: Some(+ codex_protocol::mcp::McpAttributionErrorReason::HistoryMissingCheckpoint,+ ),+ sources: Vec::new(),+ }),+ ..Default::default()+ };+ for (reason, expected_reason) in [+ (None, None),+ (+ Some(json!("future_reason")),+ Some(codex_protocol::mcp::McpAttributionErrorReason::Unknown),+ ),+ (Some(json!({"invalid": true})), None),+ ] {+ let mut serialized = serde_json::to_value(&metadata)?;+ let attribution = serialized["mcp_attribution"]+ .as_object_mut()+ .expect("attribution object");+ if let Some(reason) = reason {+ attribution.insert("error_reason".to_string(), reason);+ } else {+ attribution.remove("error_reason");+ }+ let restored: CodexHarnessMetadata = serde_json::from_value(serialized)?;+ let mut expected = metadata.clone();+ expected+ .mcp_attribution+ .as_mut()+ .expect("attribution checkpoint")+ .error_reason = expected_reason;+ assert_eq!(restored, expected);+ }+ Ok(())+}+#[test]/// Keeps legacy response-item rollout lines readable and byte-shape compatible.fn response_item_rollout_line_preserves_shape() -> Result<()> {diff --git a/codex-rs/protocol/src/mcp.rs b/codex-rs/protocol/src/mcp.rsindex fe34031f48..3e5c62e741 100644--- a/codex-rs/protocol/src/mcp.rs+++ b/codex-rs/protocol/src/mcp.rs@@ -5,6 +5,7 @@//! `schemars`) so they can be embedded in Codex's own protocol structures.use schemars::JsonSchema;use serde::Deserialize;+use serde::Deserializer;use serde::Serialize;use std::collections::HashMap;use ts_rs::TS;@@ -70,6 +71,27 @@ pub enum McpAttributionStatus {AttributionError,}+/// Bounded diagnostics for an attribution error, never a policy decision.+///+/// Recorder reasons identify the first observed error and survive checkpoints.+/// Payload reasons describe a request-serialization fallback and are not checkpointed.+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]+#[serde(rename_all = "snake_case")]+#[non_exhaustive]+pub enum McpAttributionErrorReason {+ HistoryMissingCheckpoint,+ CheckpointInvalid,+ CheckpointSourceConflict,+ SourceInvalid,+ RecorderPoisoned,+ /// An earlier error checkpoint did not retain its cause.+ RestoredErrorUnknown,+ PayloadTooLarge,+ SerializationFailed,+ #[serde(other)]+ Unknown,+}+/// One source and the first runtime turn in which Codex recorded it.////// Server and tool names are retained when no stable identifier is available;@@ -92,10 +114,27 @@ pub struct McpAttributionSource {#[serde(deny_unknown_fields)]pub struct McpAttribution {pub status: McpAttributionStatus,+ /// First observed attribution error, absent for non-error states.+ #[serde(+ default,+ skip_serializing_if = "Option::is_none",+ deserialize_with = "deserialize_mcp_attribution_error_reason"+ )]+ pub error_reason: Option<McpAttributionErrorReason>,#[serde(default, skip_serializing_if = "Vec::is_empty")]pub sources: Vec<McpAttributionSource>,}+fn deserialize_mcp_attribution_error_reason<'de, D>(+ deserializer: D,+) -> Result<Option<McpAttributionErrorReason>, D::Error>+where+ D: Deserializer<'de>,+{+ let value = serde_json::Value::deserialize(deserializer)?;+ Ok(serde_json::from_value(value).ok())+}+/// Bounded app-resource provenance retained across a compaction checkpoint.#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]pub struct McpResourceOriginCheckpoint {