//! Structured-output schema and normalization for generated TUI thread titles. //! //! Automatic titles use the first message until generation completes and as a fallback; //! a saved side chat may also replace the name it inherited at fork. Manual //! renames cancel pending requests; canceled events cannot affect newer requests. use super::App; use super::thread_events::ThreadBufferedEvent; use crate::app_event::AppEvent; use crate::app_event::ThreadTitleDestination; use crate::app_server_session::AppServerSession; use crate::temporary_structured_request::TemporaryStructuredThreadOptions; use crate::temporary_structured_request::TemporaryThreadKind; use crate::temporary_structured_request::run_temporary_structured_turn; use crate::temporary_structured_request::start_temporary_thread; use crate::temporary_structured_request::unsubscribe_temporary_thread; use codex_app_server_client::AppServerRequestHandle; use codex_app_server_protocol::ServerNotification; use codex_app_server_protocol::ThreadItemPayload; use codex_app_server_protocol::Turn; use codex_app_server_protocol::UserInput; use codex_protocol::ThreadId; use codex_protocol::models::MessagePhase; use codex_protocol::openai_models::ReasoningEffort; use pulldown_cmark::Event; use pulldown_cmark::Parser; use pulldown_cmark::TagEnd; use serde::Deserialize; use serde_json::Value; use serde_json::json; use tokio::sync::mpsc; use tokio_util::sync::CancellationToken; pub(super) const THREAD_TITLE_MAX_CHARS: usize = 36; const THREAD_TITLE_MODEL: &str = "gpt-5.6-luna"; pub(super) const THREAD_TITLE_PROMPT_MAX_BYTES: usize = 960; const THREAD_TITLE_RECENT_MESSAGES: usize = 8; #[derive(Deserialize)] #[serde(deny_unknown_fields)] struct GeneratedThreadTitle { title: String, } impl App { pub(super) fn finish_thread_title_generation( &mut self, thread_id: ThreadId, destination: ThreadTitleDestination, ) { self.pending_thread_titles.remove(&(thread_id, destination)); } /// A saved manual name supersedes any pending title generation for that thread. pub(super) fn cancel_thread_title_generation(&mut self, thread_id: ThreadId) { self.pending_thread_titles.retain(|(id, _), cancellation| { if *id == thread_id { cancellation.cancel(); false } else { true } }); } /// Generate a title without blocking the UI loop. pub(super) fn generate_thread_title( &mut self, app_server: &mut AppServerSession, thread_id: ThreadId, destination: ThreadTitleDestination, source_text: &str, expected_name: Option, ) { let request_handle = app_server.request_handle(); if let AppServerRequestHandle::Cloud(_) = &request_handle && let ThreadTitleDestination::RenameSuggestion { request_id } = destination { self.chat_widget .apply_thread_name_suggestion(thread_id, request_id, /*suggestion*/ None); return; } let std::collections::hash_map::Entry::Vacant(entry) = self.pending_thread_titles.entry((thread_id, destination)) else { return; }; let cancellation = entry.insert(CancellationToken::new()).clone(); let (prompt, fallback_title) = match destination { ThreadTitleDestination::Automatic => { let fallback = fallback_thread_title(source_text); if !self.side_threads.contains_key(&thread_id) && let Some(title) = &fallback { self.chat_widget .display_thread_name(thread_id, title.clone()); } (thread_title_prompt(source_text), fallback) } ThreadTitleDestination::RenameSuggestion { .. } => { (recent_conversation_thread_title_prompt(source_text), None) } }; let model = if (matches!(&request_handle, AppServerRequestHandle::Cloud(_)) || self.chat_widget.config_ref().model_provider_id == "openai") && self.chat_widget.has_chatgpt_account() && self .chat_widget .model_catalog() .try_list_models() .is_ok_and(|models| models.iter().any(|model| model.model == THREAD_TITLE_MODEL)) { THREAD_TITLE_MODEL.to_string() } else { self.chat_widget.current_model().to_string() }; let effort = (model == THREAD_TITLE_MODEL).then_some(ReasoningEffort::Low); let event_sender = self.app_event_tx.clone(); if let AppServerRequestHandle::Cloud(handle) = request_handle { let writer = app_server.automatic_thread_name_writer(thread_id, expected_name); let mut shutdown = self.cloud_title_shutdown.subscribe(); tokio::spawn(async move { let result = tokio::select! { biased; _ = cancellation.cancelled() => return, _ = shutdown.changed() => Err(color_eyre::eyre::eyre!("shutting down")), result = handle.generate_thread_title(&model, effort, prompt, thread_title_output_schema()) => result, }; if let Some(title) = result .as_deref() .ok() .and_then(parse_thread_title) .or(fallback_title) { writer.save(title, &cancellation).await; } event_sender.send(AppEvent::GeneratedThreadTitle { cancellation, thread_id, temporary_thread_id: None, destination, result: result.map_err(|error| error.to_string()), }); }); return; } let config = self.chat_widget.config_ref(); let options = TemporaryStructuredThreadOptions { kind: TemporaryThreadKind::Title, model, model_provider: config.model_provider_id.clone(), cwd: config.cwd.display().to_string(), active_permission_profile: config .permissions .active_permission_profile() .map(|profile| profile.id), }; tokio::spawn(async move { let result = start_temporary_thread(&request_handle, options) .await .map(|thread| thread.thread.id) .map_err(|error| error.to_string()); event_sender.send(AppEvent::ThreadTitleStarted { cancellation, thread_id, destination, prompt, expected_name, fallback_title, effort, result, }); }); } /// Register a started hidden thread and generate its structured title. #[allow(clippy::too_many_arguments)] pub(super) fn on_thread_title_started( &mut self, app_server: &mut AppServerSession, thread_id: ThreadId, destination: ThreadTitleDestination, prompt: String, expected_name: Option, fallback_title: Option, effort: Option, result: Result, cancellation: CancellationToken, ) { if cancellation.is_cancelled() { if let Ok(temporary_thread_id) = result { let request_handle = app_server.request_handle(); tokio::spawn(async move { unsubscribe_temporary_thread(&request_handle, temporary_thread_id).await; }); } return; } let save_name = (destination == ThreadTitleDestination::Automatic) .then(|| app_server.automatic_thread_name_writer(thread_id, expected_name)); let temporary_thread_id = match result .and_then(|id| ThreadId::from_string(&id).map_err(|error| error.to_string())) { Ok(id) => id, Err(error) => { tracing::debug!(%error, "failed to start title-generation thread"); self.finish_thread_title_generation(thread_id, destination); if let (Some(writer), Some(title)) = (save_name, fallback_title) { tokio::spawn(async move { writer.save(title, &cancellation).await }); } if let ThreadTitleDestination::RenameSuggestion { request_id } = destination { self.chat_widget.apply_thread_name_suggestion( thread_id, request_id, /*suggestion*/ None, ); } return; } }; let (sender, receiver) = mpsc::unbounded_channel(); self.temporary_structured_requests .insert(temporary_thread_id, (TemporaryThreadKind::Title, sender)); let request_handle = app_server.request_handle(); let event_sender = self.app_event_tx.clone(); tokio::spawn(async move { let result = run_temporary_structured_turn( request_handle, TemporaryThreadKind::Title.turn_params( temporary_thread_id.to_string(), prompt, thread_title_output_schema(), effort, ), receiver, cancellation.clone(), ) .await .map_err(|error| error.to_string()); if let Some(save_name) = save_name && let Some(title) = result .as_deref() .ok() .and_then(parse_thread_title) .or(fallback_title) { save_name.save(title, &cancellation).await; } event_sender.send(AppEvent::GeneratedThreadTitle { cancellation, thread_id, temporary_thread_id: Some(temporary_thread_id), destination, result, }); }); } /// Suggest a title from stored and live conversation items without persisting it. pub(super) async fn suggest_thread_name( &mut self, app_server: &mut AppServerSession, thread_id: ThreadId, request_id: uuid::Uuid, ) { if self.chat_widget.thread_id() != Some(thread_id) { return; } let Some(channel) = self.thread_event_channels.get(&thread_id) else { self.chat_widget .apply_thread_name_suggestion(thread_id, request_id, /*suggestion*/ None); return; }; let conversation = { let store = channel.store.lock().await; let mut seen = std::collections::HashSet::new(); recent_conversation_messages( store .turns .iter() .flat_map(Turn::item_payloads) .chain(store.buffer.iter().filter_map(|event| { let ThreadBufferedEvent::Notification(notification) = event else { return None; }; let ServerNotification::ItemCompleted(notification) = notification.as_ref() else { return None; }; Some(¬ification.item.payload) })) .filter(|item| seen.insert(item.id().to_string())), ) }; let Some(conversation) = conversation else { self.chat_widget .apply_thread_name_suggestion(thread_id, request_id, /*suggestion*/ None); return; }; self.generate_thread_title( app_server, thread_id, ThreadTitleDestination::RenameSuggestion { request_id }, &conversation, /*expected_name*/ None, ); } } /// Constrain generated metadata to one nonempty title within the display limit. pub(super) fn thread_title_output_schema() -> Value { json!({ "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": THREAD_TITLE_MAX_CHARS, }, }, "required": ["title"], "additionalProperties": false, }) } fn thread_title_instructions() -> String { format!( "Generate a concise, single-line task title of at most \ {THREAD_TITLE_MAX_CHARS} characters and under five words where possible. \ Start with an imperative verb. Capitalize only the first word unless the \ user's language, proper nouns, acronyms, or code terms require otherwise. \ Preserve ticket references exactly. Write in the user's language. \ Do not use quotes, markdown, or trailing punctuation. \ Do not answer the request." ) } /// Desktop shows a single line from the first message until a generated title is available. fn fallback_thread_title(message: &str) -> Option { const MAX_CHARS: usize = 60; const INPUT_CHAR_LIMIT: usize = 2_000; let excerpt: String = message.trim().chars().take(INPUT_CHAR_LIMIT).collect(); let mut text = String::new(); for event in Parser::new(&excerpt) { match event { Event::Text(value) | Event::Code(value) => text.push_str(&value), Event::SoftBreak | Event::HardBreak | Event::Rule | Event::End( TagEnd::Paragraph | TagEnd::Heading(_) | TagEnd::Item | TagEnd::CodeBlock, ) => text.push(' '), _ => {} } } let mut title = text.split_whitespace().collect::>().join(" "); let mut chars = title.char_indices().skip(MAX_CHARS - 1); if let Some((end, _)) = chars.next() && chars.next().is_some() { title.truncate(title[..end].trim_end().len()); title.push('…'); } (!title.is_empty()).then_some(title) } /// Build a bounded title request without truncating a Unicode character. pub(super) fn thread_title_prompt(user_message: &str) -> String { let instructions = thread_title_instructions(); let prefix = format!("{instructions}\n\nUser prompt:\n"); let remaining_bytes = THREAD_TITLE_PROMPT_MAX_BYTES.saturating_sub(prefix.len()); let user_message = user_message .trim() .char_indices() .take_while(|(index, character)| index + character.len_utf8() <= remaining_bytes) .map(|(_, character)| character) .collect::(); format!("{prefix}{user_message}") } pub(super) fn user_message_text(content: &[UserInput]) -> Option { let text = content .iter() .filter_map(|item| match item { UserInput::Text { text, .. } => { Some(crate::user_prompt::extract_prompt_request_with_offset(text).0) } _ => None, }) .collect::>() .join(" "); (!text.trim().is_empty()).then_some(text) } /// Format recent substantive messages chronologically without trusting their markup. pub(super) fn recent_conversation_messages<'a, I>(items: I) -> Option where I: IntoIterator, I::IntoIter: DoubleEndedIterator, { let mut messages = items .into_iter() .rev() .filter_map(|item| match item { ThreadItemPayload::UserMessage { content, .. } => { let text = content .iter() .filter_map(|input| match input { UserInput::Text { text, .. } => { Some(crate::user_prompt::extract_prompt_request_with_offset(text).0) } _ => None, }) .collect::>() .join("\n"); (!text.trim().is_empty()).then_some(("user", text)) } ThreadItemPayload::AgentMessage { text, phase, .. } if !matches!(phase, Some(MessagePhase::Commentary)) && !text.trim().is_empty() => { Some(("assistant", text.clone())) } _ => None, }) .take(THREAD_TITLE_RECENT_MESSAGES) .map(|(role, text)| { let escaped = text .trim() .replace('&', "&") .replace('<', "<") .replace('>', ">"); (role, escaped) }) .collect::>(); if messages.is_empty() { return None; } messages.reverse(); let conversation_bytes = THREAD_TITLE_PROMPT_MAX_BYTES .saturating_sub(recent_conversation_thread_title_prompt("").len()); let markup_bytes = "\n".len() + "\n".len() + messages.len().saturating_sub(/*rhs*/ 1) + messages .iter() .map(|(role, _)| "".len() + role.len()) .sum::(); let message_bytes = conversation_bytes.saturating_sub(markup_bytes) / messages.len(); let content_bytes = messages.iter().map(|(_, text)| text.len()).sum::(); let should_truncate = content_bytes > conversation_bytes.saturating_sub(markup_bytes); let messages = messages .into_iter() .map(|(role, mut text)| { if should_truncate && text.len() > message_bytes { let mut end = message_bytes; while !text.is_char_boundary(end) { end -= 1; } if let Some(entity_start) = text[..end].rfind('&') && !text[entity_start..end].contains(';') { end = entity_start; } text.truncate(end); } format!("{text}") }) .collect::>(); Some(format!( "\n{}\n", messages.join("\n") )) } /// Bound the entire suggestion prompt while preserving complete Unicode characters. pub(super) fn recent_conversation_thread_title_prompt(conversation: &str) -> String { let instructions = thread_title_instructions(); let prefix = format!( "{instructions}\n\ Prioritize the current task and latest substantive user request.\n\n\ Recent conversation messages:\n" ); let conversation = conversation.trim(); let remaining_bytes = THREAD_TITLE_PROMPT_MAX_BYTES.saturating_sub(prefix.len()); let mut start = conversation.len().saturating_sub(remaining_bytes); while !conversation.is_char_boundary(start) { start += 1; } let conversation = &conversation[start..]; format!("{prefix}{conversation}") } /// Normalize a generated title and truncate it without splitting Unicode characters. pub(super) fn parse_thread_title(response: &str) -> Option { if !response.trim_start().starts_with('{') { return None; } let title = serde_json::from_str::(response) .ok()? .title; let normalized = title .trim() .trim_matches(|character| matches!(character, '"' | '\'' | '`' | '“' | '”' | '‘' | '’')) .split_whitespace() .collect::>() .join(" ") .trim_end_matches(['.', '?', '!']) .trim_end() .to_string(); if normalized.is_empty() { return None; } Some(normalized.chars().take(THREAD_TITLE_MAX_CHARS).collect()) } #[cfg(test)] #[path = "thread_title_tests.rs"] mod tests;