Add opt-in reasoning status for realtime V3 delegations (#47377)

## What changed

Add `backend_reasoning_status`, disabled by default, to relay public reasoning summaries during active, server-managed realtime V3 delegations.

Use the last non-empty summary from each completed reasoning item, truncate it to 256 bytes at a character boundary, and append it as `[STATUS]` context on the `commentary` channel. Discard queued updates if their delegation is no longer active.

## Testing

Add an integration test covering enabled and disabled behavior, selection of the latest non-empty summary, exclusion of raw reasoning and partial summaries, and delivery without triggering `response.create` or changing the model's reasoning-summary setting.

GitOrigin-RevId: 75ce87dbbbab15a6d9d0ad0b23737738837192fd
This commit is contained in:
guinness-oai
2026-09-22 22:20:00 +00:00
committed by copyberry
parent 418199f6ad
commit 90e653014a
20 changed files with 303 additions and 9 deletions
@@ -100,6 +100,7 @@ const OUTPUT_EVENTS_QUEUE_CAPACITY: usize = 256;
const REALTIME_THREAD_SOURCE_MAX_BYTES: usize = 256;
const REALTIME_STARTUP_CONTEXT_TOKEN_BUDGET: usize = 5_300;
const REALTIME_ASSISTANT_OUTPUT_TOKEN_BUDGET: usize = 1_000;
const REALTIME_REASONING_STATUS_MAX_BYTES: usize = 256;
const REALTIME_INITIAL_ITEMS_MAX_COUNT: usize = 128;
const REALTIME_INITIAL_ITEMS_MAX_TOKENS: usize = 8_192;
const REALTIME_MODE_INSTRUCTIONS_MAX_TOKENS: usize = 8_192;
@@ -189,6 +190,7 @@ struct RealtimeHandoffState {
codex_responses_as_items: bool,
codex_response_item_prefix: Option<String>,
codex_response_handoff_mode: CodexResponseHandoffMode,
backend_reasoning_status: bool,
codex_response_handoff_channel_prefixes: Arc<BTreeMap<String, Vec<String>>>,
session_kind: RealtimeSessionKind,
event_parser: RealtimeEventParser,
@@ -361,6 +363,10 @@ fn take_last_bytes_at_char_boundary(text: &str, max_bytes: usize) -> &str {
#[derive(Clone, Debug, PartialEq, Eq)]
enum RealtimeOutbound {
QuietReasoningStatus {
handoff_id: String,
text: String,
},
StandaloneHandoff {
text: String,
phase: Option<MessagePhase>,
@@ -516,6 +522,7 @@ struct RealtimeStart {
codex_responses_as_items: bool,
codex_response_item_prefix: Option<String>,
codex_response_handoff_mode: CodexResponseHandoffMode,
backend_reasoning_status: bool,
codex_response_handoff_channel_prefixes: Option<BTreeMap<String, Vec<String>>>,
realtime_call_api_provider: Option<ApiProvider>,
session_config: RealtimeSessionConfig,
@@ -610,6 +617,7 @@ impl RealtimeConversationManager {
codex_responses_as_items,
codex_response_item_prefix,
codex_response_handoff_mode,
backend_reasoning_status,
codex_response_handoff_channel_prefixes,
realtime_call_api_provider,
session_config,
@@ -644,6 +652,7 @@ impl RealtimeConversationManager {
codex_responses_as_items,
codex_response_item_prefix,
codex_response_handoff_mode,
backend_reasoning_status,
codex_response_handoff_channel_prefixes: Arc::new(
codex_response_handoff_channel_prefixes.unwrap_or_default(),
),
@@ -840,6 +849,34 @@ impl RealtimeConversationManager {
Ok(())
}
pub(crate) async fn send_reasoning_status(&self, text: &str) -> CodexResult<()> {
let handoff = self
.state
.lock()
.await
.as_ref()
.map(|state| state.handoff.clone());
let Some(handoff) = handoff.filter(|handoff| {
handoff.backend_reasoning_status
&& !handoff.client_managed_handoffs
&& handoff.event_parser == RealtimeEventParser::FramelessBidi
}) else {
return Ok(());
};
let Some(handoff_id) = handoff.stream.lock().await.active_handoff.clone() else {
return Ok(());
};
let text = take_bytes_at_char_boundary(text, REALTIME_REASONING_STATUS_MAX_BYTES);
handoff
.output_tx
.send(RealtimeOutbound::QuietReasoningStatus {
handoff_id,
text: format!("[STATUS] {text}"),
})
.await
.map_err(|_| CodexErr::InvalidRequest("conversation is not running".to_string()))
}
pub(crate) async fn handoff_out(
&self,
output_text: String,
@@ -1215,6 +1252,7 @@ struct PreparedRealtimeConversationStart {
codex_responses_as_items: bool,
codex_response_item_prefix: Option<String>,
codex_response_handoff_mode: CodexResponseHandoffMode,
backend_reasoning_status: bool,
codex_response_handoff_channel_prefixes: Option<BTreeMap<String, Vec<String>>>,
realtime_start_instructions: Option<String>,
realtime_end_instructions: Option<String>,
@@ -1357,6 +1395,7 @@ async fn prepare_realtime_start(
codex_responses_as_items: params.codex_responses_as_items,
codex_response_item_prefix: params.codex_response_item_prefix,
codex_response_handoff_mode: params.codex_response_handoff_mode,
backend_reasoning_status: params.backend_reasoning_status,
codex_response_handoff_channel_prefixes: params.codex_response_handoff_channel_prefixes,
realtime_start_instructions: params.realtime_start_instructions,
realtime_end_instructions: params.realtime_end_instructions,
@@ -1580,6 +1619,7 @@ async fn handle_start_inner(
codex_responses_as_items,
codex_response_item_prefix,
codex_response_handoff_mode,
backend_reasoning_status,
codex_response_handoff_channel_prefixes,
realtime_start_instructions,
realtime_end_instructions,
@@ -1609,6 +1649,7 @@ async fn handle_start_inner(
codex_responses_as_items,
codex_response_item_prefix,
codex_response_handoff_mode,
backend_reasoning_status,
codex_response_handoff_channel_prefixes,
realtime_call_api_provider,
session_config,
@@ -2190,6 +2231,7 @@ async fn handle_handoff_output(
let handoff_output = handoff_output.context("handoff output channel closed")?;
let result = match event_parser {
RealtimeEventParser::V1 => match handoff_output {
RealtimeOutbound::QuietReasoningStatus { .. } => Ok(()),
RealtimeOutbound::StandaloneHandoff { text, phase: _ } => {
writer
.send_standalone_handoff(STANDALONE_HANDOFF_ID.to_string(), text)
@@ -2231,6 +2273,18 @@ async fn handle_handoff_output(
RealtimeOutbound::HandoffCompleteAck { .. } => Ok(()),
},
RealtimeEventParser::FramelessBidi => match handoff_output {
RealtimeOutbound::QuietReasoningStatus { handoff_id, text } => {
if handoff_state.stream.lock().await.active_handoff.as_deref() != Some(&handoff_id)
{
return Ok(());
}
// An omitted channel defaults to speakable on this wire protocol.
writer
.clone()
.with_context_append_channel(RealtimeContextAppendChannel::Commentary)
.send_conversation_handoff_append(handoff_id, text)
.await
}
RealtimeOutbound::StandaloneHandoff { text, phase } => {
v3_output_writer(
writer,
@@ -2298,6 +2352,7 @@ async fn handle_handoff_output(
RealtimeOutbound::HandoffCompleteAck { .. } => Ok(()),
},
RealtimeEventParser::RealtimeV2 => match handoff_output {
RealtimeOutbound::QuietReasoningStatus { .. } => Ok(()),
RealtimeOutbound::StandaloneHandoff { text, phase: _ } => {
if let Err(err) = writer
.send_conversation_item_create(text, ConversationTextRole::User)
@@ -214,6 +214,7 @@ async fn clears_active_handoff_explicitly() {
client_managed_handoffs: false,
codex_responses_as_items: false,
codex_response_item_prefix: None,
backend_reasoning_status: false,
codex_response_handoff_mode: CodexResponseHandoffMode::Thinking,
codex_response_handoff_channel_prefixes: Arc::new(BTreeMap::new()),
session_kind: RealtimeSessionKind::V1,
+10 -3
View File
@@ -278,6 +278,7 @@ use self::session::SessionSettingsCommit;
pub(crate) use self::session::SessionSettingsUpdate;
#[cfg(test)]
use self::turn::AssistantMessageStreamParsers;
use self::turn::RealtimeEventText;
use self::turn::agent_message_text;
#[cfg(test)]
use self::turn::collect_explicit_app_ids_from_skill_items;
@@ -2491,10 +2492,16 @@ impl Session {
}
_ => {}
}
let Some((text, phase)) = realtime_text_for_event(msg) else {
return;
let result = match realtime_text_for_event(msg) {
Some(RealtimeEventText::Handoff(text, phase)) => {
self.conversation.handoff_out(text, phase).await
}
Some(RealtimeEventText::QuietReasoning(text)) => {
self.conversation.send_reasoning_status(&text).await
}
None => return,
};
if let Err(err) = self.conversation.handoff_out(text, phase).await {
if let Err(err) = result {
debug!("failed to mirror event text to realtime conversation: {err}");
}
}
+27 -5
View File
@@ -2000,7 +2000,13 @@ pub(super) fn agent_message_text(item: &codex_protocol::items::AgentMessageItem)
.collect()
}
pub(super) fn realtime_text_for_event(msg: &EventMsg) -> Option<(String, Option<MessagePhase>)> {
#[derive(Debug, PartialEq)]
pub(super) enum RealtimeEventText {
Handoff(String, Option<MessagePhase>),
QuietReasoning(String),
}
pub(super) fn realtime_text_for_event(msg: &EventMsg) -> Option<RealtimeEventText> {
match msg {
EventMsg::ElicitationRequest(request)
if matches!(
@@ -2008,11 +2014,27 @@ pub(super) fn realtime_text_for_event(msg: &EventMsg) -> Option<(String, Option<
codex_protocol::approvals::ElicitationRequest::UserVerification { .. }
) =>
{
Some((UserVerificationNotice.render(), None))
Some(RealtimeEventText::Handoff(
UserVerificationNotice.render(),
None,
))
}
EventMsg::AgentMessage(event) => Some((event.message.clone(), event.phase.clone())),
EventMsg::AgentMessage(event) => Some(RealtimeEventText::Handoff(
event.message.clone(),
event.phase.clone(),
)),
EventMsg::ItemCompleted(event) => match &event.item {
TurnItem::AgentMessage(item) => Some((agent_message_text(item), item.phase.clone())),
TurnItem::AgentMessage(item) => Some(RealtimeEventText::Handoff(
agent_message_text(item),
item.phase.clone(),
)),
TurnItem::Reasoning(item) => item
.summary_text
.iter()
.rev()
.map(|summary| summary.trim())
.find(|summary| !summary.is_empty())
.map(|summary| RealtimeEventText::QuietReasoning(summary.to_owned())),
_ => None,
},
EventMsg::ExecApprovalRequest(_)
@@ -2030,7 +2052,7 @@ pub(super) fn realtime_text_for_event(msg: &EventMsg) -> Option<(String, Option<
};
serde_json::to_string(msg)
.ok()
.map(|request| (format!("{message}\n\n{request}"), None))
.map(|request| RealtimeEventText::Handoff(format!("{message}\n\n{request}"), None))
}
EventMsg::Error(_)
| EventMsg::Warning(_)
+1 -1
View File
@@ -103,7 +103,7 @@ fn realtime_user_verification_notice_excludes_request_payload() {
});
assert_eq!(
realtime_text_for_event(&event),
Some((
Some(RealtimeEventText::Handoff(
"<user_verification_notice>User verification is required. Please respond in the app.</user_verification_notice>".to_string(),
None,
)),