Skip to content

armgit / codex

Public Imported from GitHub
0

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.zst
index bb761a91dc..bc896e3ea9 100644
Binary 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 differ
diff --git a/codex-rs/core/src/agent/control_tests.rs b/codex-rs/core/src/agent/control_tests.rs
index 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.rs
index 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_endp
let 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_endp
assert_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.rs
index 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_metadata
diff --git a/codex-rs/core/src/session/tests.rs b/codex-rs/core/src/session/tests.rs
index 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.rs
index 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.rs
index 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.rs
index e30ebd1a4d..5a8876aaa5 100644
--- a/codex-rs/history/src/lib.rs
+++ b/codex-rs/history/src/lib.rs
@@ -124,6 +124,7 @@ where
Ok(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.rs
index 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.rs
index 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 {