agent/codex
2
0
Fork 0
mirror of https://github.com/pchuan98/codex.git synced 2026-07-01 00:31:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(core): add metadata field to ResponseItem (#28355)

Browse Source 
## Description

This PR adds an optional `metadata` field to `ResponseItem` for
Responses API calls. Only mechanical plumbing, no actual values
populated and sent yet. Turns out just adding a new field to
`ResponseItem` has quite a large blast radius already.

This change is backwards compatible because `metadata` is optional and
omitted when absent, so existing response items and rollout history
without it still deserialize and requests that do not set it keep the
same wire shape. For provider compatibility, we strip out `metadata`
before non-OpenAI Responses requests so Azure and AWS Bedrock never see
this field.

My followup PR here will actually make use of it to start storing and
passing along `turn_id`: https://github.com/openai/codex/pull/28360

## What changed

- Added `ResponseItemMetadata` with optional `turn_id`, plus optional
`metadata` on Responses API item variants and inter-agent communication.
- Preserved item metadata through response-item rewrites such as
truncation, missing tool-output synthesis, compaction history
rebuilding, visible-history conversion, rollout/resume, and generated
app-server schemas/types.
- Strip item metadata from non-OpenAI Responses requests while
preserving it for OpenAI-shaped requests.
- Updated the mechanical fixture/test construction churn required by the
new optional field.
This commit is contained in:
Owen Lin
2026-06-15 15:05:28 -07:00
committed by GitHub
Unverified
parent bef99f861b
commit 040dafa32d
85 changed files with 1637 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
codex-rs/protocol/src/items.rs
+1
View File
@@ -391,6 +391,7 @@ pub fn build_hook_prompt_message(fragments: &[HookPromptFragment]) -> Option<Res
role: "user".to_string(),
content,
phase: None,
metadata: None,
})
}
codex-rs/protocol/src/models.rs
+219 -7
View File
@@ -750,6 +750,13 @@ pub enum MessagePhase {
FinalAnswer,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, JsonSchema, TS)]
pub struct ResponseItemMetadata {
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
pub turn_id: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, JsonSchema, TS)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ResponseItem {
@@ -765,11 +772,17 @@ pub enum ResponseItem {
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
phase: Option<MessagePhase>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
AgentMessage {
author: String,
recipient: String,
content: Vec<AgentMessageInputContent>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
Reasoning {
#[serde(default, skip_serializing)]
@@ -781,6 +794,9 @@ pub enum ResponseItem {
#[ts(optional)]
content: Option<Vec<ReasoningItemContent>>,
encrypted_content: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
LocalShellCall {
/// Legacy id field retained for compatibility with older payloads.
@@ -791,6 +807,9 @@ pub enum ResponseItem {
call_id: Option<String>,
status: LocalShellStatus,
action: LocalShellAction,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
FunctionCall {
#[serde(default, skip_serializing)]
@@ -805,6 +824,9 @@ pub enum ResponseItem {
// Session::handle_function_call parse it into a Value.
arguments: String,
call_id: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
ToolSearchCall {
#[serde(default, skip_serializing)]
@@ -817,6 +839,9 @@ pub enum ResponseItem {
execution: String,
#[ts(type = "unknown")]
arguments: serde_json::Value,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
// NOTE: The `output` field for `function_call_output` uses a dedicated payload type with
// custom serialization. On the wire it is either:
@@ -828,6 +853,9 @@ pub enum ResponseItem {
#[ts(as = "FunctionCallOutputBody")]
#[schemars(with = "FunctionCallOutputBody")]
output: FunctionCallOutputPayload,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
CustomToolCall {
#[serde(default, skip_serializing)]
@@ -840,6 +868,9 @@ pub enum ResponseItem {
call_id: String,
name: String,
input: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
// `custom_tool_call_output.output` uses the same wire encoding as
// `function_call_output.output` so freeform tools can return either plain
@@ -852,6 +883,9 @@ pub enum ResponseItem {
#[ts(as = "FunctionCallOutputBody")]
#[schemars(with = "FunctionCallOutputBody")]
output: FunctionCallOutputPayload,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
ToolSearchOutput {
call_id: Option<String>,
@@ -859,6 +893,9 @@ pub enum ResponseItem {
execution: String,
#[ts(type = "unknown[]")]
tools: Vec<serde_json::Value>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
// Emitted by the Responses API when the agent triggers a web search.
// Example payload (from SSE `response.output_item.done`):
@@ -878,6 +915,9 @@ pub enum ResponseItem {
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
action: Option<WebSearchAction>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
// Emitted by the Responses API when the agent triggers image generation.
// Example payload:
@@ -895,16 +935,29 @@ pub enum ResponseItem {
#[ts(optional)]
revised_prompt: Option<String>,
result: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
#[serde(alias = "compaction_summary")]
Compaction {
encrypted_content: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
CompactionTrigger {
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
CompactionTrigger,
ContextCompaction {
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
encrypted_content: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
metadata: Option<ResponseItemMetadata>,
},
#[serde(other)]
Other,
@@ -915,6 +968,75 @@ impl ResponseItem {
pub fn is_user_message(&self) -> bool {
matches!(self, Self::Message { role, .. } if role == "user")
}
/// Returns the non-empty turn ID stamped onto this item, if present.
pub fn turn_id(&self) -> Option<&str> {
self.metadata()
.and_then(|metadata| metadata.turn_id.as_deref())
.filter(|turn_id| !turn_id.is_empty())
}
/// Stamps the item with `turn_id` unless it already has a non-empty turn ID.
pub fn stamp_turn_id_if_missing(&mut self, turn_id: &str) {
if turn_id.is_empty() || self.turn_id().is_some() {
return;
}
let Some(metadata) = self.metadata_mut() else {
return;
};
metadata
.get_or_insert_with(ResponseItemMetadata::default)
.turn_id = Some(turn_id.to_string());
}
/// Removes Responses API item metadata before sending to a provider that does not accept it.
pub fn clear_metadata(&mut self) {
if let Some(metadata) = self.metadata_mut() {
*metadata = None;
}
}
fn metadata(&self) -> Option<&ResponseItemMetadata> {
match self {
Self::Message { metadata, .. }
| Self::AgentMessage { metadata, .. }
| Self::Reasoning { metadata, .. }
| Self::LocalShellCall { metadata, .. }
| Self::FunctionCall { metadata, .. }
| Self::ToolSearchCall { metadata, .. }
| Self::FunctionCallOutput { metadata, .. }
| Self::CustomToolCall { metadata, .. }
| Self::CustomToolCallOutput { metadata, .. }
| Self::ToolSearchOutput { metadata, .. }
| Self::WebSearchCall { metadata, .. }
| Self::ImageGenerationCall { metadata, .. }
| Self::Compaction { metadata, .. }
| Self::CompactionTrigger { metadata }
| Self::ContextCompaction { metadata, .. } => metadata.as_ref(),
Self::Other => None,
}
}
fn metadata_mut(&mut self) -> Option<&mut Option<ResponseItemMetadata>> {
match self {
Self::Message { metadata, .. }
| Self::AgentMessage { metadata, .. }
| Self::Reasoning { metadata, .. }
| Self::LocalShellCall { metadata, .. }
| Self::FunctionCall { metadata, .. }
| Self::ToolSearchCall { metadata, .. }
| Self::FunctionCallOutput { metadata, .. }
| Self::CustomToolCall { metadata, .. }
| Self::CustomToolCallOutput { metadata, .. }
| Self::ToolSearchOutput { metadata, .. }
| Self::WebSearchCall { metadata, .. }
| Self::ImageGenerationCall { metadata, .. }
| Self::Compaction { metadata, .. }
| Self::CompactionTrigger { metadata }
| Self::ContextCompaction { metadata, .. } => Some(metadata),
Self::Other => None,
}
}
}
pub const BASE_INSTRUCTIONS_DEFAULT: &str = include_str!("prompts/base_instructions/default.md");
@@ -1153,13 +1275,20 @@ impl From<ResponseInputItem> for ResponseItem {
content,
id: None,
phase,
metadata: None,
},
ResponseInputItem::FunctionCallOutput { call_id, output } => Self::FunctionCallOutput {
call_id,
output,
metadata: None,
},
ResponseInputItem::FunctionCallOutput { call_id, output } => {
Self::FunctionCallOutput { call_id, output }
}
ResponseInputItem::McpToolCallOutput { call_id, output } => {
let output = output.into_function_call_output_payload();
Self::FunctionCallOutput { call_id, output }
Self::FunctionCallOutput {
call_id,
output,
metadata: None,
}
}
ResponseInputItem::CustomToolCallOutput {
call_id,
@@ -1169,6 +1298,7 @@ impl From<ResponseInputItem> for ResponseItem {
call_id,
name,
output,
metadata: None,
},
ResponseInputItem::ToolSearchOutput {
call_id,
@@ -1180,6 +1310,7 @@ impl From<ResponseInputItem> for ResponseItem {
status,
execution,
tools,
metadata: None,
},
}
}
@@ -1718,10 +1849,64 @@ mod tests {
text: "still working".to_string(),
}],
phase: Some(MessagePhase::Commentary),
metadata: None,
}
);
}
#[test]
fn response_item_metadata_round_trips_and_stamps_turn_ids() -> Result<()> {
let mut item = response_item_with_metadata(Some(response_item_metadata("turn-1")));
let round_trip: ResponseItem = serde_json::from_value(serde_json::to_value(&item)?)?;
assert_eq!(round_trip, item);
let unknown_metadata: ResponseItem = serde_json::from_value(serde_json::json!({
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "hello"}],
"metadata": {
"turn_id": "turn-1",
"other": "ignored",
},
}))?;
assert_eq!(unknown_metadata, item);
item.stamp_turn_id_if_missing("turn-2");
assert_eq!(item.turn_id(), Some("turn-1"));
let mut empty_turn_id = response_item_with_metadata(Some(response_item_metadata("")));
empty_turn_id.stamp_turn_id_if_missing("turn-1");
assert_eq!(empty_turn_id.turn_id(), Some("turn-1"));
let mut missing_turn_id = response_item_with_metadata(/*metadata*/ None);
missing_turn_id.stamp_turn_id_if_missing("");
missing_turn_id.stamp_turn_id_if_missing("turn-1");
assert_eq!(missing_turn_id.turn_id(), Some("turn-1"));
let mut other = ResponseItem::Other;
other.stamp_turn_id_if_missing("turn-1");
assert_eq!(other.turn_id(), None);
Ok(())
}
fn response_item_with_metadata(metadata: Option<ResponseItemMetadata>) -> ResponseItem {
ResponseItem::Message {
id: None,
role: "user".to_string(),
content: vec![ContentItem::InputText {
text: "hello".to_string(),
}],
phase: None,
metadata,
}
}
fn response_item_metadata(turn_id: &str) -> ResponseItemMetadata {
ResponseItemMetadata {
turn_id: Some(turn_id.to_string()),
}
}
#[test]
fn image_detail_roundtrips_all_wire_values() -> Result<()> {
assert_eq!(
@@ -1823,6 +2008,7 @@ mod tests {
status: "completed".to_string(),
revised_prompt: Some("A small blue square".to_string()),
result: "Zm9v".to_string(),
metadata: None,
}
);
}
@@ -1844,6 +2030,7 @@ mod tests {
status: "completed".to_string(),
revised_prompt: None,
result: "Zm9v".to_string(),
metadata: None,
}
);
}
@@ -2195,6 +2382,7 @@ mod tests {
namespace: Some("mcp__codex_apps__gmail".to_string()),
arguments: "{\"top_k\":5}".to_string(),
call_id: "call-1".to_string(),
metadata: None,
}
);
}
@@ -2541,6 +2729,7 @@ mod tests {
item,
ResponseItem::Compaction {
encrypted_content: "abc".into(),
metadata: None,
}
);
Ok(())
@@ -2556,6 +2745,7 @@ mod tests {
item,
ResponseItem::ContextCompaction {
encrypted_content: Some("abc".into()),
metadata: None,
}
);
Ok(())
@@ -2563,7 +2753,7 @@ mod tests {
#[test]
fn serializes_compaction_trigger_without_payload() -> Result<()> {
let item = ResponseItem::CompactionTrigger;
let item = ResponseItem::CompactionTrigger { metadata: None };
assert_eq!(
serde_json::to_value(item)?,
@@ -2574,13 +2764,30 @@ mod tests {
Ok(())
}
#[test]
fn serializes_stamped_compaction_trigger_metadata() -> Result<()> {
let mut item = ResponseItem::CompactionTrigger { metadata: None };
item.stamp_turn_id_if_missing("turn-1");
assert_eq!(
serde_json::to_value(item)?,
serde_json::json!({
"type": "compaction_trigger",
"metadata": {
"turn_id": "turn-1",
},
})
);
Ok(())
}
#[test]
fn deserializes_compaction_trigger_without_payload() -> Result<()> {
let json = r#"{"type":"compaction_trigger"}"#;
let item: ResponseItem = serde_json::from_str(json)?;
assert_eq!(item, ResponseItem::CompactionTrigger);
assert_eq!(item, ResponseItem::CompactionTrigger { metadata: None });
Ok(())
}
@@ -2677,6 +2884,7 @@ mod tests {
id: expected_id.clone(),
status: expected_status.clone(),
action: expected_action.clone(),
metadata: None,
};
assert_eq!(parsed, expected);
@@ -2764,6 +2972,7 @@ mod tests {
"query": "calendar create",
"limit": 1,
}),
metadata: None,
}
);
@@ -2824,6 +3033,7 @@ mod tests {
"additionalProperties": false,
}
})],
metadata: None,
}
);
@@ -2877,6 +3087,7 @@ mod tests {
arguments: serde_json::json!({
"paths": ["crm"],
}),
metadata: None,
}
);
@@ -2896,6 +3107,7 @@ mod tests {
status: "completed".to_string(),
execution: "server".to_string(),
tools: vec![],
metadata: None,
}
);
codex-rs/protocol/src/protocol.rs
+9
View File
@@ -41,6 +41,7 @@ use crate::models::MessagePhase;
use crate::models::PermissionProfile;
use crate::models::ResponseInputItem;
use crate::models::ResponseItem;
use crate::models::ResponseItemMetadata;
use crate::models::SandboxEnforcement;
use crate::models::WebSearchAction;
use crate::num_format::format_with_separators;
@@ -669,6 +670,9 @@ pub struct InterAgentCommunication {
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
pub encrypted_content: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(optional)]
pub metadata: Option<ResponseItemMetadata>,
pub trigger_turn: bool,
}
@@ -686,6 +690,7 @@ impl InterAgentCommunication {
other_recipients,
content,
encrypted_content: None,
metadata: None,
trigger_turn,
}
}
@@ -703,6 +708,7 @@ impl InterAgentCommunication {
other_recipients,
content: String::new(),
encrypted_content: Some(encrypted_content),
metadata: None,
trigger_turn,
}
}
@@ -730,6 +736,7 @@ impl InterAgentCommunication {
author: self.author.to_string(),
recipient: self.recipient.to_string(),
content: vec![content],
metadata: self.metadata.clone(),
}
}
@@ -2932,6 +2939,7 @@ impl From<CompactedItem> for ResponseItem {
text: value.message,
}],
phase: None,
metadata: None,
}
}
}
@@ -4217,6 +4225,7 @@ mod tests {
other_recipients: vec![AgentPath::root().join("worker").expect("recipient path")],
content: "review the diff".to_string(),
encrypted_content: None,
metadata: None,
trigger_turn: true,
};