//! Conversation continuity and contextual follow-up tracking for Phoebus assistant. //! //! Tracks recent interaction turns to support contextual follow-ups such as //! "why did you choose that over nix?", "install the flatpak one", or "proceed with that" //! without restarting candidate investigation from scratch. //! //! All stored history is bounded (max 10 turns) and minimized before //! persistence. Only structured context (the application, chosen candidate, //! rationale and a short summary) is kept, never the unrestricted raw request. //! Registered secrets are scrubbed with the caller's redactor; that is an //! honest boundary — it removes known secrets, it does not detect arbitrary //! sensitive text, which is why raw requests are not stored. //! //! History is kept in a 0600 file inside a 0700 directory, written atomically, //! and can be cleared without leaving the follow-up context behind. use std::io::Write; use std::path::{Path, PathBuf}; use std::time::{SystemTime, UNIX_EPOCH}; use phoebus_core::selection::{Backend, Candidate, Rejected}; use phoebus_core::Redactor; use serde::{Deserialize, Serialize}; const MAX_TURNS: usize = 10; const FOLLOWUP_WINDOW_SECONDS: u64 = 1800; // 30 minutes /// Upper bound on a persisted free-text summary or rationale line. const MAX_TEXT_CHARS: usize = 240; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ConversationTurn { pub timestamp_unix: u64, /// A minimized, structured summary of the request (e.g. "install firefox"), /// never the unrestricted raw natural-language request. pub query: String, pub response_kind: String, // "install", "removal", "plan", "info" #[serde(default, skip_serializing_if = "Option::is_none")] pub application: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub chosen_candidate: Option, #[serde(default, skip_serializing_if = "Vec::is_empty")] pub alternatives: Vec, #[serde(default, skip_serializing_if = "Option::is_none")] pub plan_id: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub plan_digest: Option, #[serde(default, skip_serializing_if = "Vec::is_empty")] pub rationale: Vec, } #[derive(Debug, Clone, Serialize, Deserialize, Default)] pub struct ConversationHistory { pub turns: Vec, } #[derive(Debug, Clone, PartialEq, Eq)] pub enum FollowupResolution { /// Explain the tradeoffs between the chosen candidate and alternative backend. Comparison { application: String, target_backend: Option, explanation: String, }, /// Switch candidate to an alternative backend requested by user. SwitchBackend { application: String, target_backend: Backend, }, /// Execute or confirm previously prepared plan. ConfirmPlan { plan_id: String, digest: String }, } fn now_unix() -> u64 { SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_secs()) .unwrap_or(0) } pub fn history_path() -> PathBuf { if let Ok(dir) = std::env::var("PHOEBUS_CONVERSATION_DIR") { return PathBuf::from(dir).join("conversation.json"); } if let Ok(user_dir) = std::env::var("XDG_DATA_HOME") { return PathBuf::from(user_dir) .join("phoebus") .join("conversation.json"); } if let Ok(home) = std::env::var("HOME") { return PathBuf::from(home).join(".local/share/phoebus/conversation.json"); } std::env::temp_dir().join("phoebus-conversation.json") } pub fn load_history(path: &Path) -> ConversationHistory { if !path.is_file() { return ConversationHistory::default(); } let data = match std::fs::read_to_string(path) { Ok(d) => d, Err(_) => return ConversationHistory::default(), }; serde_json::from_str(&data).unwrap_or_default() } /// Bound a piece of free text: collapse whitespace, drop control characters /// and cap the length. Combined with the registered-secret redactor, this keeps /// persisted history minimal and stable. fn minimize(redactor: &Redactor, text: &str) -> String { let redacted = redactor.redact(text); let cleaned: String = redacted .chars() .filter(|c| !c.is_control() || *c == ' ') .collect(); let collapsed = cleaned.split_whitespace().collect::>().join(" "); if collapsed.chars().count() > MAX_TEXT_CHARS { collapsed.chars().take(MAX_TEXT_CHARS).collect::() + "…" } else { collapsed } } /// Append a turn. The caller supplies the process redactor (which holds any /// registered secret), so a known secret can never be persisted. Returns an /// error on a write failure instead of silently discarding history. pub fn save_turn( path: &Path, redactor: &Redactor, mut turn: ConversationTurn, ) -> std::io::Result<()> { let mut history = load_history(path); turn.query = minimize(redactor, &turn.query); turn.rationale = turn .rationale .into_iter() .map(|r| minimize(redactor, &r)) .collect(); if let Some(app) = &turn.application { turn.application = Some(minimize(redactor, app)); } history.turns.push(turn); if history.turns.len() > MAX_TURNS { history.turns.drain(0..history.turns.len() - MAX_TURNS); } if let Some(parent) = path.parent() { std::fs::create_dir_all(parent)?; #[cfg(unix)] { use std::os::unix::fs::PermissionsExt; let _ = std::fs::set_permissions(parent, std::fs::Permissions::from_mode(0o700)); } } let serialized = serde_json::to_string_pretty(&history) .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?; atomic_write_private(path, serialized.as_bytes()) } /// Delete the persisted history so it can no longer inform a later follow-up. pub fn clear_history(path: &Path) -> std::io::Result<()> { match std::fs::remove_file(path) { Ok(()) => Ok(()), Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()), Err(e) => Err(e), } } fn atomic_write_private(path: &Path, bytes: &[u8]) -> std::io::Result<()> { let tmp = path.with_extension("tmp"); { let mut opts = std::fs::OpenOptions::new(); opts.write(true).create(true).truncate(true); #[cfg(unix)] { use std::os::unix::fs::OpenOptionsExt; opts.mode(0o600); } let mut file = opts.open(&tmp)?; file.write_all(bytes)?; file.flush()?; file.sync_all()?; } std::fs::rename(&tmp, path)?; Ok(()) } fn backend_from_word(word: &str) -> Option { match word { "flatpak" => Some(Backend::Flatpak), "portage" => Some(Backend::PortageSource), "source" => Some(Backend::PortageSource), "binary" => Some(Backend::PortageBinary), "nix" => Some(Backend::Nix), "nixpkgs" => Some(Backend::Nix), "snap" => Some(Backend::Snap), "appimage" => Some(Backend::AppImage), "ebuild" => Some(Backend::CustomEbuild), _ => None, } } /// Tokens that are never an application name: articles, pronouns, verbs and /// software-lane names. const NON_APP_TOKENS: &[&str] = &[ "the", "a", "an", "that", "this", "it", "one", "those", "these", "using", "via", "with", "from", "through", "instead", "please", "install", "add", "remove", "uninstall", "delete", "for", "and", "to", "switch", "try", "flatpak", "portage", "source", "binary", "nix", "nixpkgs", "snap", "appimage", "ebuild", ]; /// Parse an explicit install request, including natural prefixes and multi-word /// application names. Vague references such as "install the flatpak one" remain /// conversational follow-ups rather than new applications. pub fn parse_explicit_install(query: &str) -> Option<(String, Option)> { let lower = query.trim().to_ascii_lowercase(); let lower = lower.strip_prefix("please ").unwrap_or(&lower).trim(); let rest = lower .strip_prefix("install ") .or_else(|| lower.strip_prefix("add ")) .or_else(|| lower.strip_prefix("i want to install ")) .or_else(|| lower.strip_prefix("i'd like to install "))?; let tokens: Vec<&str> = rest.split_whitespace().collect(); let first = tokens.first()?.trim_matches(['"', '\'']); if NON_APP_TOKENS.contains(&first) || first.starts_with('-') { return None; } let source_start = tokens .iter() .position(|token| matches!(*token, "using" | "via" | "with" | "through")); let mut app_end = source_start.unwrap_or(tokens.len()); if app_end > 0 && tokens[app_end - 1] == "please" { app_end -= 1; } let app_tokens = &tokens[..app_end]; if app_tokens.is_empty() || app_tokens.len() > 6 || app_tokens .iter() .any(|token| NON_APP_TOKENS.contains(token) || token.starts_with('-')) { return None; } let app = app_tokens.join(" "); let app = app.trim_matches(['"', '\'']).trim(); if app.is_empty() || app.chars().any(char::is_control) { return None; } let mut backend = None; if let Some(start) = source_start { for token in &tokens[start + 1..] { if let Some(b) = backend_from_word(token) { backend = Some(b); } else if !NON_APP_TOKENS.contains(token) { return None; } } backend?; } Some((app.to_string(), backend)) } /// Analyze incoming query against the most recent conversation turn. pub fn resolve_followup(query: &str, history: &ConversationHistory) -> Option { let last = history.turns.last()?; let now = now_unix(); if now.saturating_sub(last.timestamp_unix) > FOLLOWUP_WINDOW_SECONDS { return None; } let q_lower = query.trim().to_ascii_lowercase(); // 1. Confirmation ("install that one", "proceed", "yes, do it") if matches!( q_lower.as_str(), "install that one" | "install that" | "proceed" | "proceed with that" | "confirm" | "yes" | "yes do it" | "go ahead" ) { if let (Some(plan_id), Some(digest)) = (&last.plan_id, &last.plan_digest) { return Some(FollowupResolution::ConfirmPlan { plan_id: plan_id.clone(), digest: digest.clone(), }); } } let app = last.application.as_deref()?; let backends = [ ("flatpak", Backend::Flatpak), ("portage", Backend::PortageSource), ("source", Backend::PortageSource), ("binary", Backend::PortageBinary), ("nix", Backend::Nix), ("snap", Backend::Snap), ("appimage", Backend::AppImage), ("ebuild", Backend::CustomEbuild), ]; // Prefer an explicit application reference over an inferred one. If the // request names a concrete application different from the one under // discussion, it is a fresh request, not a follow-up about the old one. if let Some((named, _)) = parse_explicit_install(query) { if !named.eq_ignore_ascii_case(app) { return None; } } // 2. Switch backend ("install the flatpak one", "use portage instead", // "use flatpak for that one"). No explicit new application is present // (it would have returned above). for (name, backend) in backends { if (q_lower.contains("install") || q_lower.contains("use") || q_lower.contains("switch")) && q_lower.contains(name) { return Some(FollowupResolution::SwitchBackend { application: app.to_string(), target_backend: backend, }); } } // 3. Comparison / Why question. Only answer about the previous package // choice when the question actually refers to it (a named backend, a // demonstrative, or the application itself). A generic "why is my audio // broken?" must not become an explanation of an unrelated choice. let is_why = q_lower.starts_with("why") || q_lower.contains("how come") || q_lower.contains("explain") || q_lower.contains("compare") || q_lower.contains("difference") || q_lower.contains("versus") || q_lower.contains(" vs "); if is_why { let mut target_backend = None; for (name, backend) in backends { if q_lower.contains(name) { target_backend = Some(backend); break; } } let refers_to_previous = target_backend.is_some() || q_lower.contains("that") || q_lower.contains("this") || q_lower.contains("chosen") || q_lower.contains("recommend") || q_lower.contains("it ") || q_lower.contains(&app.to_ascii_lowercase()); if !refers_to_previous { return None; } let mut explanation = String::new(); if let Some(cand) = &last.chosen_candidate { explanation.push_str(&format!( "For `{app}`, **{}** was recommended because:\n", cand.backend.as_str() )); for r in &last.rationale { explanation.push_str(&format!(" - {r}\n")); } } if let Some(tb) = target_backend { if let Some(rejected) = last.alternatives.iter().find(|r| r.backend == tb) { explanation.push_str(&format!( "\nCompared to **{}**: rejected because {}.", tb.as_str(), rejected.reason.explain() )); } else if let Some(cand) = &last.chosen_candidate { if cand.backend == tb { explanation.push_str(&format!( "\n**{}** is the currently chosen backend.", tb.as_str() )); } } } else if !last.alternatives.is_empty() { explanation.push_str("\nAlternatives considered:\n"); for alt in &last.alternatives { explanation.push_str(&format!( " - **{}**: {}\n", alt.backend.as_str(), alt.reason.explain() )); } } if !explanation.is_empty() { return Some(FollowupResolution::Comparison { application: app.to_string(), target_backend, explanation, }); } } None } #[cfg(test)] mod tests { use super::*; use phoebus_core::selection::{Capability, RejectReason, SandboxLevel}; use tempfile::tempdir; fn make_test_candidate(backend: Backend) -> Candidate { let mut cand = Candidate::new(backend, "firefox", "flathub"); cand.version = Some("120.0".into()); cand.verified = true; cand.download_mib = Some(85); cand.install_mib = Some(220); cand.sandbox = SandboxLevel::Strong; cand.wayland = Capability::Yes; cand.desktop_integration = Capability::Yes; cand.permissions = vec!["network".into()]; cand } #[test] fn test_conversation_followup_switch_and_comparison() { let temp = tempdir().unwrap(); let path = temp.path().join("conversation.json"); let turn = ConversationTurn { timestamp_unix: now_unix(), query: "install firefox".into(), response_kind: "install".into(), application: Some("firefox".into()), chosen_candidate: Some(make_test_candidate(Backend::Flatpak)), alternatives: vec![Rejected { backend: Backend::Nix, id: "firefox".into(), reason: RejectReason::BackendNotRequested, }], plan_id: Some("plan-1234".into()), plan_digest: Some("abc123digest".into()), rationale: vec!["provides application isolation".into()], }; save_turn(&path, &Redactor::new(), turn).unwrap(); let history = load_history(&path); assert_eq!(history.turns.len(), 1); // Test switch backend let switch = resolve_followup("install the nix one", &history); assert_eq!( switch, Some(FollowupResolution::SwitchBackend { application: "firefox".into(), target_backend: Backend::Nix, }) ); // Test comparison question let comparison = resolve_followup("why did you choose that over nix?", &history); assert!(matches!( comparison, Some(FollowupResolution::Comparison { ref application, target_backend: Some(Backend::Nix), .. }) if application == "firefox" )); // Test plan confirmation let confirm = resolve_followup("proceed with that", &history); assert_eq!( confirm, Some(FollowupResolution::ConfirmPlan { plan_id: "plan-1234".into(), digest: "abc123digest".into(), }) ); } #[test] fn explicit_install_is_parsed_and_not_a_stale_followup() { // "install vlc using flatpak" names VLC and the lane; it must not be // captured as a backend switch for a previously discussed FireFox. assert_eq!( parse_explicit_install("install vlc using flatpak"), Some(("vlc".into(), Some(Backend::Flatpak))) ); assert_eq!( parse_explicit_install("install firefox"), Some(("firefox".into(), None)) ); assert_eq!( parse_explicit_install("i want to install chatgpt desktop"), Some(("chatgpt desktop".into(), None)) ); assert_eq!( parse_explicit_install("please install 'visual studio code' via flatpak"), Some(("visual studio code".into(), Some(Backend::Flatpak))) ); assert_eq!( parse_explicit_install("install chatgpt desktop through nix"), Some(("chatgpt desktop".into(), Some(Backend::Nix))) ); assert_eq!( parse_explicit_install("install firefox please"), Some(("firefox".into(), None)) ); // Vague references are not explicit applications. assert_eq!(parse_explicit_install("install the flatpak one"), None); assert_eq!(parse_explicit_install("install the nix one"), None); assert_eq!( parse_explicit_install("i want to install the flatpak one"), None ); let temp = tempdir().unwrap(); let path = temp.path().join("conversation.json"); save_turn( &path, &Redactor::new(), ConversationTurn { timestamp_unix: now_unix(), query: "install firefox".into(), response_kind: "install".into(), application: Some("firefox".into()), chosen_candidate: Some(make_test_candidate(Backend::Flatpak)), alternatives: vec![], plan_id: None, plan_digest: None, rationale: vec![], }, ) .unwrap(); let history = load_history(&path); // A different explicit app is a fresh request, not a follow-up. assert_eq!( resolve_followup("install vlc using flatpak", &history), None ); // A demonstrative switch still refers to the previous app. assert_eq!( resolve_followup("use flatpak for that one", &history), Some(FollowupResolution::SwitchBackend { application: "firefox".into(), target_backend: Backend::Flatpak, }) ); // An unrelated question is not a package explanation. assert_eq!(resolve_followup("why is my audio broken?", &history), None); } #[test] fn history_is_minimized_redacted_private_and_clearable() { use std::os::unix::fs::PermissionsExt; let temp = tempdir().unwrap(); let path = temp.path().join("phoebus/conversation.json"); let redactor = Redactor::new(); redactor.register_plain("sk-supersecret"); save_turn( &path, &redactor, ConversationTurn { timestamp_unix: now_unix(), query: "install firefox with key sk-supersecret".into(), response_kind: "install".into(), application: Some("firefox".into()), chosen_candidate: None, alternatives: vec![], plan_id: None, plan_digest: None, rationale: vec!["token sk-supersecret leaked".into()], }, ) .unwrap(); let raw = std::fs::read_to_string(&path).unwrap(); assert!(!raw.contains("sk-supersecret"), "secret must be redacted"); assert!(raw.contains("")); let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777; assert_eq!(mode, 0o600, "history must be private"); // Clearing removes the context used for later follow-ups. clear_history(&path).unwrap(); assert!(!path.exists()); assert!(load_history(&path).turns.is_empty()); } #[test] fn history_is_bounded() { let temp = tempdir().unwrap(); let path = temp.path().join("conversation.json"); for i in 0..(MAX_TURNS + 5) { save_turn( &path, &Redactor::new(), ConversationTurn { timestamp_unix: now_unix(), query: format!("install app{i}"), response_kind: "install".into(), application: Some(format!("app{i}")), chosen_candidate: None, alternatives: vec![], plan_id: None, plan_digest: None, rationale: vec![], }, ) .unwrap(); } assert_eq!(load_history(&path).turns.len(), MAX_TURNS); } #[test] fn long_text_is_bounded_not_stored_raw() { let temp = tempdir().unwrap(); let path = temp.path().join("conversation.json"); let long = "x".repeat(2000); save_turn( &path, &Redactor::new(), ConversationTurn { timestamp_unix: now_unix(), query: long.clone(), response_kind: "plan".into(), application: None, chosen_candidate: None, alternatives: vec![], plan_id: None, plan_digest: None, rationale: vec![], }, ) .unwrap(); let history = load_history(&path); assert!(history.turns[0].query.chars().count() <= MAX_TEXT_CHARS + 1); assert!(!history.turns[0].query.contains(&long)); } }