Lightweight coding agent that runs in your terminal
Rust
use super::*;
use codex_protocol::AgentPath;
use codex_protocol::ThreadId;
use codex_protocol::items::AgentMessageContent;
use codex_protocol::items::AgentMessageItem;
use codex_protocol::items::DynamicToolCallItem;
use codex_protocol::items::DynamicToolCallStatus;
use codex_protocol::items::ImageGenerationItem;
use codex_protocol::items::McpToolCallItem;
use codex_protocol::items::McpToolCallStatus;
use codex_protocol::items::SubAgentActivityItem;
use codex_protocol::items::UserMessageItem;
use codex_protocol::protocol::AgentMessageContentDeltaEvent;
use codex_protocol::protocol::ItemCompletedEvent;
use codex_protocol::protocol::ItemStartedEvent;
use codex_protocol::protocol::RealtimeConversationClosedEvent;
use codex_protocol::protocol::RealtimeConversationRealtimeEvent;
use codex_protocol::protocol::RealtimeConversationStartedEvent;
use codex_protocol::protocol::RealtimeConversationVersion;
use codex_protocol::protocol::SubAgentActivityKind;
use codex_protocol::protocol::TurnAbortReason;
use codex_protocol::protocol::TurnAbortedEvent;
use pretty_assertions::assert_eq;
use test_case::test_case;
use uuid::Uuid;
fn started_state() -> RealtimeHistoryState {
let mut state = RealtimeHistoryState::default();
state.observe(&EventMsg::TurnStarted(
codex_protocol::protocol::TurnStartedEvent {
turn_attribution: None,
turn_id: "turn-1".to_string(),
root_turn_id: None,
trace_id: None,
started_at: None,
model_context_window: None,
collaboration_mode_kind: Default::default(),
},
));
state.observe(&EventMsg::RealtimeConversationStarted(
RealtimeConversationStartedEvent {
realtime_session_id: Some("voice-1".to_string()),
version: RealtimeConversationVersion::V2,
},
));
state
}
fn observe_realtime(
state: &mut RealtimeHistoryState,
payload: RealtimeEvent,
) -> RealtimeEventEffects {
state.observe(&EventMsg::RealtimeConversationRealtime(
RealtimeConversationRealtimeEvent { payload },
))
}
fn assistant_delta(item_id: &str, delta: &str) -> EventMsg {
EventMsg::AgentMessageContentDelta(AgentMessageContentDeltaEvent {
thread_id: "thread-1".to_string(),
turn_id: "turn-1".to_string(),
item_id: item_id.to_string(),
delta: delta.to_string(),
})
}
fn completed_item(item: TurnItem) -> EventMsg {
EventMsg::ItemCompleted(ItemCompletedEvent {
thread_id: ThreadId::new(),
turn_id: "turn-1".to_string(),
item,
started_at_ms: None,
completed_at_ms: 0,
})
}
fn dynamic_tool_call(id: &str, status: DynamicToolCallStatus) -> TurnItem {
TurnItem::DynamicToolCall(DynamicToolCallItem {
id: id.to_string(),
namespace: Some("another_client".to_string()),
tool: "any_dynamic_tool".to_string(),
arguments: serde_json::Value::Null,
status,
content_items: None,
success: Some(status == DynamicToolCallStatus::Completed),
error: None,
duration: None,
})
}
fn mcp_tool_call(id: &str, server: &str, status: McpToolCallStatus) -> TurnItem {
TurnItem::McpToolCall(McpToolCallItem {
id: id.to_string(),
server: server.to_string(),
tool: "create_thread".to_string(),
arguments: serde_json::Value::Null,
connector_id: None,
mcp_app_resource_uri: None,
mcp_app_ui: None,
link_id: None,
app_name: None,
action_name: None,
plugin_id: None,
read_only_hint: None,
status,
result: None,
error: None,
duration: None,
})
}
fn contents(effects: RealtimeEventEffects) -> Vec<RealtimeItemContent> {
effects
.items
.into_iter()
.map(|item| {
assert_eq!(Uuid::parse_str(&item.id).unwrap().get_version_num(), 7);
item.content
})
.collect()
}
#[test_case(Some("turn-1"), None; "matching_turn")]
#[test_case(None, None; "without_turn_id")]
#[test_case(Some("another-turn"), Some("voice-2"); "unrelated_turn")]
fn interrupted_turn_is_not_associated_with_a_new_voice_session(
aborted_turn_id: Option<&str>,
expected_session_id: Option<&str>,
) {
let mut state = RealtimeHistoryState::default();
state.observe(&EventMsg::TurnStarted(
codex_protocol::protocol::TurnStartedEvent {
turn_attribution: None,
turn_id: "turn-1".to_string(),
root_turn_id: None,
trace_id: None,
started_at: None,
model_context_window: None,
collaboration_mode_kind: Default::default(),
},
));
let aborted = EventMsg::TurnAborted(TurnAbortedEvent {
root_turn_id: None,
turn_id: aborted_turn_id.map(str::to_string),
reason: TurnAbortReason::Interrupted,
error: None,
started_at: None,
completed_at: None,
duration_ms: None,
});
assert!(state.should_observe(&aborted));
state.observe(&aborted);
state.observe(&EventMsg::RealtimeConversationStarted(
RealtimeConversationStartedEvent {
realtime_session_id: Some("voice-2".to_string()),
version: RealtimeConversationVersion::V2,
},
));
let promoted = state
.observe(&completed_item(dynamic_tool_call(
"late-tool",
DynamicToolCallStatus::Completed,
)))
.items;
assert_eq!(
promoted
.iter()
.map(|item| item.realtime_session_id.as_str())
.collect::<Vec<_>>(),
expected_session_id.into_iter().collect::<Vec<_>>()
);
}
#[test]
fn interrupted_turn_keeps_its_existing_voice_session_for_late_artifacts() {
let mut state = started_state();
state.observe(&EventMsg::TurnAborted(TurnAbortedEvent {
root_turn_id: None,
turn_id: Some("turn-1".to_string()),
reason: TurnAbortReason::Interrupted,
error: None,
started_at: None,
completed_at: None,
duration_ms: None,
}));
state.observe(&EventMsg::RealtimeConversationStarted(
RealtimeConversationStartedEvent {
realtime_session_id: Some("voice-2".to_string()),
version: RealtimeConversationVersion::V2,
},
));
let promoted = state
.observe(&completed_item(dynamic_tool_call(
"late-tool",
DynamicToolCallStatus::Completed,
)))
.items;
assert_eq!(
promoted
.iter()
.map(|item| item.realtime_session_id.as_str())
.collect::<Vec<_>>(),
vec!["voice-1"]
);
}
#[test]
fn promotes_backing_agent_artifacts_once_without_a_client_request() {
let mut state = started_state();
let first_delta = assistant_delta("message-1", "[analysis] ::codex-realtime-inline{}");
assert!(state.observe(&first_delta).items.is_empty());
let second_delta = assistant_delta("message-1", "\nVisible explanation");
let effects = state.observe(&second_delta);
assert_eq!(effects.order, RealtimeEventOrder::AfterEvent);
assert_eq!(
contents(effects),
vec![RealtimeItemContent::BemItemPromoted {
turn_id: "turn-1".to_string(),
item_id: "message-1".to_string(),
presentation: BemItemPresentation::InlineMarkdown,
}]
);
let completed = completed_item(TurnItem::AgentMessage(AgentMessageItem {
id: "message-1".to_string(),
content: vec![AgentMessageContent::Text {
text: "[analysis] ::codex-realtime-inline{}\nVisible explanation".to_string(),
}],
phase: None,
memory_citation: None,
delivery: None,
questions: None,
}));
assert!(state.observe(&completed).items.is_empty());
let next_message = assistant_delta("message-2", "::codex-realtime-inline{}\nNext message");
assert_eq!(
contents(state.observe(&next_message)),
vec![RealtimeItemContent::BemItemPromoted {
turn_id: "turn-1".to_string(),
item_id: "message-2".to_string(),
presentation: BemItemPresentation::InlineMarkdown,
}]
);
let image = EventMsg::ItemStarted(ItemStartedEvent {
thread_id: ThreadId::new(),
turn_id: "turn-1".to_string(),
item: TurnItem::ImageGeneration(ImageGenerationItem {
id: "image-1".to_string(),
status: "in_progress".to_string(),
revised_prompt: None,
result: String::new(),
saved_path: None,
}),
started_at_ms: 0,
});
let subagent = completed_item(TurnItem::SubAgentActivity(SubAgentActivityItem {
model: None,
reasoning_effort: None,
id: "subagent-1".to_string(),
kind: SubAgentActivityKind::Started,
agent_thread_id: ThreadId::new(),
agent_path: AgentPath::root(),
}));
for (event, item_id) in [(image, "image-1"), (subagent, "subagent-1")] {
assert_eq!(
contents(state.observe(&event)),
vec![RealtimeItemContent::BemItemPromoted {
turn_id: "turn-1".to_string(),
item_id: item_id.to_string(),
presentation: BemItemPresentation::WholeItem,
}]
);
}
state.observe(&EventMsg::RealtimeConversationClosed(
RealtimeConversationClosedEvent { reason: None },
));
let late = state.observe(&assistant_delta(
"late-artifact",
"::codex-realtime-inline{}\npresent later",
));
assert_eq!(late.items.len(), 1);
assert_eq!(late.items[0].realtime_session_id, "voice-1");
}
#[test]
fn promotes_distinct_visualizations_once_and_ignores_markdown_fences() {
let mut state = started_state();
let text = "```\n::codex-inline-vis{file=hidden}\n```\n~~~\nvisualize{file=also-hidden}\n~~~\n::codex-inline-vis{file=first}\nvisualize{file=second}";
let message = assistant_delta("message-1", text);
assert_eq!(
contents(state.observe(&message)),
(0..2)
.map(|index| RealtimeItemContent::BemItemPromoted {
turn_id: "turn-1".to_string(),
item_id: "message-1".to_string(),
presentation: BemItemPresentation::InlineVisualization { index },
})
.collect::<Vec<_>>()
);
let completed = completed_item(TurnItem::AgentMessage(AgentMessageItem {
id: "message-1".to_string(),
content: vec![AgentMessageContent::Text {
text: text.to_string(),
}],
phase: None,
memory_citation: None,
delivery: None,
questions: None,
}));
assert!(state.observe(&completed).items.is_empty());
}
#[test]
fn streams_stable_segment_items_and_ignores_upstream_transcript_revisions() {
let mut state = started_state();
let effects = observe_realtime(
&mut state,
RealtimeEvent::OutputTranscriptDelta(RealtimeTranscriptDelta {
delta: "hello".to_string(),
}),
);
assert!(effects.items.is_empty());
let stream = effects.transcript_stream.expect("streaming delta");
let started = stream.started_item.expect("segment start");
assert_eq!(stream.item_id, started.id);
assert_eq!(Uuid::parse_str(&started.id).unwrap().get_version_num(), 7);
assert_eq!(stream.delta, "hello");
let done = observe_realtime(
&mut state,
RealtimeEvent::OutputTranscriptDone(RealtimeTranscriptDone {
text: "a substantially different upstream revision".to_string(),
}),
);
assert_eq!(
done.items,
vec![RealtimeItem {
id: started.id,
realtime_session_id: "voice-1".to_string(),
content: RealtimeItemContent::TranscriptSegment {
role: RealtimeTranscriptRole::Assistant,
text: "hello".to_string(),
},
}],
);
assert!(done.transcript_stream.is_none());
}
#[test]
fn emits_the_complete_item_lifecycle_when_only_a_final_transcript_arrives() {
let mut state = started_state();
let effects = observe_realtime(
&mut state,
RealtimeEvent::OutputTranscriptDone(RealtimeTranscriptDone {
text: "final transcript".to_string(),
}),
);
let stream = effects.transcript_stream.expect("final transcript stream");
let started = stream.started_item.expect("transcript item started");
assert_eq!(stream.item_id, started.id);
assert_eq!(stream.delta, "final transcript");
assert_eq!(
effects.items,
vec![RealtimeItem {
id: started.id,
realtime_session_id: "voice-1".to_string(),
content: RealtimeItemContent::TranscriptSegment {
role: RealtimeTranscriptRole::Assistant,
text: "final transcript".to_string(),
},
}]
);
}
#[test]
fn preserves_first_transcript_activity_order_when_both_speakers_are_active() {
for roles in [
[
RealtimeTranscriptRole::Assistant,
RealtimeTranscriptRole::User,
],
[
RealtimeTranscriptRole::User,
RealtimeTranscriptRole::Assistant,
],
] {
let mut state = started_state();
for role in roles {
let delta = RealtimeTranscriptDelta {
delta: format!("{role:?} speech"),
};
observe_realtime(
&mut state,
match role {
RealtimeTranscriptRole::User => RealtimeEvent::InputTranscriptDelta(delta),
RealtimeTranscriptRole::Assistant => {
RealtimeEvent::OutputTranscriptDelta(delta)
}
},
);
}
let items = state
.observe(&EventMsg::RealtimeConversationClosed(
RealtimeConversationClosedEvent { reason: None },
))
.items;
let observed_roles = items
.iter()
.filter_map(|item| match item.content {
RealtimeItemContent::TranscriptSegment { role, .. } => Some(role),
_ => None,
})
.collect::<Vec<_>>();
assert_eq!(observed_roles, roles);
}
}
#[test]
fn does_not_replay_a_final_transcript_after_a_promotion_split() {
let mut state = started_state();
observe_realtime(
&mut state,
RealtimeEvent::OutputTranscriptDelta(RealtimeTranscriptDelta {
delta: "Already spoken".to_string(),
}),
);
let promotion = completed_item(dynamic_tool_call(
"successful-tool",
DynamicToolCallStatus::Completed,
));
assert_eq!(state.observe(&promotion).items.len(), 2);
let done = observe_realtime(
&mut state,
RealtimeEvent::OutputTranscriptDone(RealtimeTranscriptDone {
text: "Already spoken, with an upstream revision".to_string(),
}),
);
assert!(done.items.is_empty());
assert!(done.transcript_stream.is_none());
}
#[test]
fn generates_distinct_boundary_ids_for_reused_realtime_sessions() {
let mut state = RealtimeHistoryState::default();
let mut boundary_ids = Vec::new();
for _ in 0..2 {
let started = state.observe(&EventMsg::RealtimeConversationStarted(
RealtimeConversationStartedEvent {
realtime_session_id: Some("reused-session".to_string()),
version: RealtimeConversationVersion::V2,
},
));
let closed = state.observe(&EventMsg::RealtimeConversationClosed(
RealtimeConversationClosedEvent { reason: None },
));
for item in started.items.into_iter().chain(closed.items) {
assert_eq!(item.realtime_session_id, "reused-session");
assert_eq!(Uuid::parse_str(&item.id).unwrap().get_version_num(), 7);
boundary_ids.push(item.id);
}
}
let unique_ids = boundary_ids
.iter()
.collect::<std::collections::HashSet<_>>();
assert_eq!(unique_ids.len(), 4);
let fallback = state.observe(&EventMsg::RealtimeConversationStarted(
RealtimeConversationStartedEvent {
realtime_session_id: None,
version: RealtimeConversationVersion::V2,
},
));
assert_eq!(fallback.items.len(), 1);
assert_eq!(
Uuid::parse_str(&fallback.items[0].realtime_session_id)
.unwrap()
.get_version_num(),
7
);
}
#[test]
fn promotes_successful_codex_app_mcp_calls_and_splits_active_transcripts() {
let mut state = started_state();
observe_realtime(
&mut state,
RealtimeEvent::OutputTranscriptDelta(RealtimeTranscriptDelta {
delta: "Before tool.".to_string(),
}),
);
for (server, status) in [
("other_server", McpToolCallStatus::Completed),
("codex_app", McpToolCallStatus::InProgress),
("codex_app", McpToolCallStatus::Failed),
] {
assert!(
state
.observe(&completed_item(mcp_tool_call(
"not-promoted",
server,
status
)),)
.items
.is_empty()
);
}
let completed = completed_item(mcp_tool_call(
"app-tool",
"codex_app",
McpToolCallStatus::Completed,
));
assert_eq!(
contents(state.observe(&completed)),
vec![
RealtimeItemContent::TranscriptSegment {
role: RealtimeTranscriptRole::Assistant,
text: "Before tool.".to_string(),
},
RealtimeItemContent::BemItemPromoted {
turn_id: "turn-1".to_string(),
item_id: "app-tool".to_string(),
presentation: BemItemPresentation::WholeItem,
},
]
);
assert!(state.observe(&completed).items.is_empty());
}
#[test]
fn promotes_successful_dynamic_tools_and_splits_active_transcripts() {
let mut state = started_state();
let first = observe_realtime(
&mut state,
RealtimeEvent::OutputTranscriptDelta(RealtimeTranscriptDelta {
delta: "Before tool. ".to_string(),
}),
)
.transcript_stream
.expect("first transcript stream");
let failed = completed_item(dynamic_tool_call(
"failed-tool",
DynamicToolCallStatus::Failed,
));
assert!(state.observe(&failed).items.is_empty());
let completed = completed_item(dynamic_tool_call(
"successful-tool",
DynamicToolCallStatus::Completed,
));
let effects = state.observe(&completed);
assert_eq!(effects.order, RealtimeEventOrder::AfterEvent);
let items = effects.items;
assert_eq!(items.len(), 2);
assert_eq!(
items[0],
RealtimeItem {
id: first.item_id.clone(),
realtime_session_id: "voice-1".to_string(),
content: RealtimeItemContent::TranscriptSegment {
role: RealtimeTranscriptRole::Assistant,
text: "Before tool. ".to_string(),
},
}
);
assert_eq!(
items[1].content,
RealtimeItemContent::BemItemPromoted {
turn_id: "turn-1".to_string(),
item_id: "successful-tool".to_string(),
presentation: BemItemPresentation::WholeItem,
}
);
assert_eq!(Uuid::parse_str(&items[1].id).unwrap().get_version_num(), 7);
let second = observe_realtime(
&mut state,
RealtimeEvent::OutputTranscriptDelta(RealtimeTranscriptDelta {
delta: "After tool.".to_string(),
}),
)
.transcript_stream
.expect("second transcript stream");
assert_ne!(first.item_id, second.item_id);
assert!(second.started_item.is_some());
assert!(state.observe(&completed).items.is_empty());
let closed = state.observe(&EventMsg::RealtimeConversationClosed(
RealtimeConversationClosedEvent { reason: None },
));
assert_eq!(closed.items[0].id, second.item_id);
let late = completed_item(dynamic_tool_call(
"late-tool",
DynamicToolCallStatus::Completed,
));
assert!(state.observe(&late).items.is_empty());
state.observe(&EventMsg::RealtimeConversationStarted(
RealtimeConversationStartedEvent {
realtime_session_id: Some("voice-2".to_string()),
version: RealtimeConversationVersion::V2,
},
));
let resumed = state.observe(&late).items;
assert_eq!(resumed.len(), 1);
assert_eq!(resumed[0].realtime_session_id, "voice-2");
}
#[test_case(|item| EventMsg::ItemStarted(ItemStartedEvent {
thread_id: ThreadId::new(),
turn_id: "turn-1".to_string(),
item,
started_at_ms: 0,
}); "started")]
#[test_case(completed_item; "completed")]
fn typed_input_seals_both_roles_but_realtime_delegation_does_not(
user_event: fn(TurnItem) -> EventMsg,
) {
let mut state = started_state();
for event in [
RealtimeEvent::OutputTranscriptDelta(RealtimeTranscriptDelta {
delta: "assistant".to_string(),
}),
RealtimeEvent::InputTranscriptDelta(RealtimeTranscriptDelta {
delta: "user".to_string(),
}),
] {
observe_realtime(&mut state, event);
}
assert!(
state
.observe(&user_event(TurnItem::UserMessage(UserMessageItem::new(&[
UserInput::Text {
text: "<realtime_delegation>delegated</realtime_delegation>".to_string(),
text_elements: Vec::new(),
}
]))))
.items
.is_empty()
);
let effects = state.observe(&user_event(TurnItem::UserMessage(UserMessageItem::new(&[
UserInput::Text {
text: "typed steering".to_string(),
text_elements: Vec::new(),
},
]))));
assert_eq!(effects.order, RealtimeEventOrder::BeforeEvent);
assert_eq!(
contents(effects),
vec![
RealtimeItemContent::TranscriptSegment {
role: RealtimeTranscriptRole::Assistant,
text: "assistant".to_string()
},
RealtimeItemContent::TranscriptSegment {
role: RealtimeTranscriptRole::User,
text: "user".to_string()
},
]
);
for event in [
RealtimeEvent::OutputTranscriptDone(RealtimeTranscriptDone {
text: "assistant revised".to_string(),
}),
RealtimeEvent::InputTranscriptDone(RealtimeTranscriptDone {
text: "user revised".to_string(),
}),
] {
assert!(observe_realtime(&mut state, event).items.is_empty());
}
}