Use transient developer instructions for realtime sessions

This commit is contained in:
Ahmed Ibrahim
2026-02-27 11:35:25 -08:00
parent be2529b0eb
commit 8d4dcadd7c
16 changed files with 254 additions and 178 deletions
+93 -47
View File
@@ -162,6 +162,10 @@ pub enum SteerInputError {
ExpectedTurnMismatch { expected: String, actual: String },
EmptyInput,
}
const REALTIME_START_DEVELOPER_INSTRUCTIONS: &str = "Realtime conversation handling is now active. Keep responses concise, low-latency, interruption-safe, and operationally safe for live interaction. This instruction applies only while realtime is active.";
const REALTIME_END_DEVELOPER_INSTRUCTIONS: &str = "Realtime conversation handling has ended. The realtime-specific developer instruction no longer applies.";
use crate::exec_policy::ExecPolicyUpdateError;
use crate::feedback_tags;
use crate::file_watcher::FileWatcher;
@@ -3035,45 +3039,69 @@ impl Session {
state.session_configuration.collaboration_mode.clone()
}
pub(crate) async fn enter_realtime_collaboration_mode(&self) -> ConstraintResult<()> {
let current = self.collaboration_mode().await;
let collaboration_mode = self
.services
.models_manager
.list_collaboration_modes()
.into_iter()
.find(|mask| mask.mode == Some(ModeKind::Realtime))
.map(|mask| current.apply_mask(&mask))
.unwrap_or_else(|| CollaborationMode {
mode: ModeKind::Realtime,
settings: Settings {
model: current.model().to_string(),
reasoning_effort: current.reasoning_effort(),
developer_instructions: None,
},
});
self.update_settings(SessionSettingsUpdate {
collaboration_mode: Some(collaboration_mode),
..Default::default()
})
.await
pub(crate) async fn realtime_instructions_active(&self) -> bool {
let state = self.state.lock().await;
state.realtime_instructions_active()
}
pub(crate) async fn reset_to_default_collaboration_mode(&self) -> ConstraintResult<()> {
let current = self.collaboration_mode().await;
self.update_settings(SessionSettingsUpdate {
collaboration_mode: Some(CollaborationMode {
mode: ModeKind::Default,
settings: Settings {
model: current.model().to_string(),
reasoning_effort: current.reasoning_effort(),
developer_instructions: None,
},
}),
..Default::default()
})
.await
pub(crate) async fn emit_realtime_start_instructions(&self) {
if self.realtime_instructions_active().await {
return;
}
self.record_session_developer_message(REALTIME_START_DEVELOPER_INSTRUCTIONS)
.await;
let mut state = self.state.lock().await;
state.set_realtime_instructions_active(true);
}
pub(crate) async fn emit_realtime_end_instructions(&self) {
if !self.realtime_instructions_active().await {
return;
}
self.record_session_developer_message(REALTIME_END_DEVELOPER_INSTRUCTIONS)
.await;
let mut state = self.state.lock().await;
state.set_realtime_instructions_active(false);
}
async fn record_session_developer_message(&self, text: &str) {
let message: ResponseItem = DeveloperInstructions::new(text.to_string()).into();
let active_turn_context = {
let active = self.active_turn.lock().await;
active
.as_ref()
.and_then(|active_turn| active_turn.tasks.first())
.map(|(_, task)| Arc::clone(&task.turn_context))
};
if let Some(turn_context) = active_turn_context {
self.record_conversation_items(turn_context.as_ref(), std::slice::from_ref(&message))
.await;
return;
}
let session_configuration = {
let state = self.state.lock().await;
state.session_configuration.clone()
};
let per_turn_config = Self::build_per_turn_config(&session_configuration);
let model_info = self
.services
.models_manager
.get_model_info(
session_configuration.collaboration_mode.model(),
&per_turn_config,
)
.await;
{
let mut state = self.state.lock().await;
state.record_items(
std::slice::from_ref(&message).iter(),
model_info.truncation_policy.into(),
);
}
self.persist_rollout_response_items(std::slice::from_ref(&message))
.await;
}
async fn send_raw_response_items(&self, turn_context: &TurnContext, items: &[ResponseItem]) {
@@ -4592,9 +4620,7 @@ mod handlers {
pub async fn shutdown(sess: &Arc<Session>, sub_id: String) -> bool {
sess.abort_all_tasks(TurnAbortReason::Interrupted).await;
let _ = sess.conversation.shutdown().await;
if let Err(err) = sess.reset_to_default_collaboration_mode().await {
warn!("failed to reset collaboration mode during shutdown: {err}");
}
sess.emit_realtime_end_instructions().await;
sess.services
.unified_exec_manager
.terminate_all_processes()
@@ -8967,16 +8993,36 @@ mod tests {
}
#[tokio::test]
async fn shutdown_resets_realtime_collaboration_mode_to_default() {
async fn shutdown_emits_realtime_end_instructions() {
let (session, _turn_context, _rx) = make_session_and_context_with_rx().await;
session
.enter_realtime_collaboration_mode()
.await
.expect("enter realtime collaboration mode");
assert_eq!(session.collaboration_mode().await.mode, ModeKind::Realtime);
session.emit_realtime_start_instructions().await;
assert!(session.realtime_instructions_active().await);
assert!(handlers::shutdown(&session, "shutdown-test".to_string()).await);
assert_eq!(session.collaboration_mode().await.mode, ModeKind::Default);
assert!(!session.realtime_instructions_active().await);
let developer_texts = session
.clone_history()
.await
.raw_items()
.iter()
.filter_map(|item| match item {
ResponseItem::Message { role, content, .. } if role == "developer" => {
content.iter().find_map(|content| match content {
ContentItem::InputText { text } => Some(text.clone()),
_ => None,
})
}
_ => None,
})
.collect::<Vec<_>>();
assert_eq!(
developer_texts,
vec![
REALTIME_START_DEVELOPER_INSTRUCTIONS.to_string(),
REALTIME_END_DEVELOPER_INSTRUCTIONS.to_string(),
]
);
}
#[tokio::test]
@@ -6,8 +6,6 @@ use codex_protocol::openai_models::ReasoningEffort;
const COLLABORATION_MODE_PLAN: &str = include_str!("../../templates/collaboration_mode/plan.md");
const COLLABORATION_MODE_DEFAULT: &str =
include_str!("../../templates/collaboration_mode/default.md");
const COLLABORATION_MODE_REALTIME: &str =
include_str!("../../templates/collaboration_mode/realtime.md");
const KNOWN_MODE_NAMES_PLACEHOLDER: &str = "{{KNOWN_MODE_NAMES}}";
const REQUEST_USER_INPUT_AVAILABILITY_PLACEHOLDER: &str = "{{REQUEST_USER_INPUT_AVAILABILITY}}";
const ASKING_QUESTIONS_GUIDANCE_PLACEHOLDER: &str = "{{ASKING_QUESTIONS_GUIDANCE}}";
@@ -26,11 +24,7 @@ pub struct CollaborationModesConfig {
pub(crate) fn builtin_collaboration_mode_presets(
collaboration_modes_config: CollaborationModesConfig,
) -> Vec<CollaborationModeMask> {
vec![
plan_preset(),
default_preset(collaboration_modes_config),
realtime_preset(),
]
vec![plan_preset(), default_preset(collaboration_modes_config)]
}
fn plan_preset() -> CollaborationModeMask {
@@ -53,16 +47,6 @@ fn default_preset(collaboration_modes_config: CollaborationModesConfig) -> Colla
}
}
fn realtime_preset() -> CollaborationModeMask {
CollaborationModeMask {
name: ModeKind::Realtime.display_name().to_string(),
mode: Some(ModeKind::Realtime),
model: None,
reasoning_effort: None,
developer_instructions: Some(Some(COLLABORATION_MODE_REALTIME.to_string())),
}
}
fn default_mode_instructions(collaboration_modes_config: CollaborationModesConfig) -> String {
let known_mode_names = format_mode_names(&TUI_VISIBLE_COLLABORATION_MODES);
let request_user_input_availability = request_user_input_availability_message(
@@ -134,8 +118,6 @@ mod tests {
plan_preset().reasoning_effort,
Some(Some(ReasoningEffort::Medium))
);
assert_eq!(realtime_preset().name, ModeKind::Realtime.display_name());
assert_eq!(realtime_preset().reasoning_effort, None);
}
#[test]
@@ -174,19 +156,4 @@ mod tests {
.contains("ask the user directly with a concise plain-text question")
);
}
#[test]
fn realtime_preset_only_sets_developer_instructions() {
let realtime = realtime_preset();
assert_eq!(realtime.mode, Some(ModeKind::Realtime));
assert_eq!(realtime.model, None);
assert_eq!(realtime.reasoning_effort, None);
assert!(
realtime
.developer_instructions
.expect("realtime preset should include instructions")
.expect("realtime instructions should be set")
.contains("Realtime mode")
);
}
}
+8 -16
View File
@@ -186,6 +186,9 @@ pub(crate) async fn handle_start(
.session_id
.or_else(|| Some(sess.conversation_id.to_string()));
info!("starting realtime conversation");
if sess.realtime_instructions_active().await {
sess.emit_realtime_end_instructions().await;
}
let events_rx = match sess
.conversation
.start(api_provider, None, prompt, requested_session_id.clone())
@@ -198,11 +201,7 @@ pub(crate) async fn handle_start(
return Ok(());
}
};
if let Err(err) = sess.enter_realtime_collaboration_mode().await {
let _ = sess.conversation.shutdown().await;
send_conversation_error(sess, sub_id, err.to_string(), CodexErrorInfo::BadRequest).await;
return Ok(());
}
sess.emit_realtime_start_instructions().await;
info!("realtime conversation started");
@@ -243,7 +242,7 @@ pub(crate) async fn handle_start(
}
if let Some(()) = sess_clone.conversation.running_state().await {
info!("realtime conversation transport closed");
close_realtime_and_reset_mode(
close_realtime_and_emit_end_instruction(
&sess_clone,
ev,
"transport_closed",
@@ -304,7 +303,7 @@ pub(crate) async fn handle_text(
pub(crate) async fn handle_close(sess: &Arc<Session>, sub_id: String) {
let error_sub_id = sub_id.clone();
close_realtime_and_reset_mode(
close_realtime_and_emit_end_instruction(
sess,
|msg| Event {
id: sub_id.clone(),
@@ -316,7 +315,7 @@ pub(crate) async fn handle_close(sess: &Arc<Session>, sub_id: String) {
.await;
}
async fn close_realtime_and_reset_mode<F>(
async fn close_realtime_and_emit_end_instruction<F>(
sess: &Arc<Session>,
event_builder: F,
reason: &str,
@@ -333,14 +332,7 @@ async fn close_realtime_and_reset_mode<F>(
return;
}
if let Err(err) = sess.reset_to_default_collaboration_mode().await {
if let Some(sub_id) = error_sub_id {
send_conversation_error(sess, sub_id, err.to_string(), CodexErrorInfo::Other).await;
} else {
warn!("failed to reset collaboration mode after realtime close: {err}");
}
return;
}
sess.emit_realtime_end_instructions().await;
sess.send_event_raw(event_builder(EventMsg::RealtimeConversationClosed(
RealtimeConversationClosedEvent {
+10
View File
@@ -19,6 +19,7 @@ use codex_protocol::protocol::TurnContextItem;
pub(crate) struct SessionState {
pub(crate) session_configuration: SessionConfiguration,
pub(crate) history: ContextManager,
pub(crate) realtime_instructions_active: bool,
pub(crate) latest_rate_limits: Option<RateLimitSnapshot>,
pub(crate) server_reasoning_included: bool,
pub(crate) dependency_env: HashMap<String, String>,
@@ -40,6 +41,7 @@ impl SessionState {
Self {
session_configuration,
history,
realtime_instructions_active: false,
latest_rate_limits: None,
server_reasoning_included: false,
dependency_env: HashMap::new(),
@@ -71,6 +73,14 @@ impl SessionState {
self.history.clone()
}
pub(crate) fn realtime_instructions_active(&self) -> bool {
self.realtime_instructions_active
}
pub(crate) fn set_realtime_instructions_active(&mut self, active: bool) {
self.realtime_instructions_active = active;
}
pub(crate) fn replace_history(
&mut self,
items: Vec<ResponseItem>,
@@ -132,7 +132,6 @@ mod tests {
fn request_user_input_mode_availability_defaults_to_plan_only() {
assert!(ModeKind::Plan.allows_request_user_input());
assert!(!ModeKind::Default.allows_request_user_input());
assert!(!ModeKind::Realtime.allows_request_user_input());
assert!(!ModeKind::Execute.allows_request_user_input());
assert!(!ModeKind::PairProgramming.allows_request_user_input());
}
@@ -151,10 +150,6 @@ mod tests {
request_user_input_unavailable_message(ModeKind::Default, true),
None
);
assert_eq!(
request_user_input_unavailable_message(ModeKind::Realtime, false),
Some("request_user_input is unavailable in Realtime mode".to_string())
);
assert_eq!(
request_user_input_unavailable_message(ModeKind::Execute, false),
Some("request_user_input is unavailable in Execute mode".to_string())