phoebus_os/installer-rs/crates/phoebus-installer/src/conversation.rs
2026-09-24 18:01:13 -07:00

630 lines
22 KiB
Rust

//! 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<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub chosen_candidate: Option<Candidate>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub alternatives: Vec<Rejected>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub plan_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub plan_digest: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub rationale: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ConversationHistory {
pub turns: Vec<ConversationTurn>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FollowupResolution {
/// Explain the tradeoffs between the chosen candidate and alternative backend.
Comparison {
application: String,
target_backend: Option<Backend>,
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::<Vec<_>>().join(" ");
if collapsed.chars().count() > MAX_TEXT_CHARS {
collapsed.chars().take(MAX_TEXT_CHARS).collect::<String>() + "…"
} 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<Backend> {
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 <app>` or `install <app> using/via/with <source>`
/// request. Returns `None` for a vague reference such as "install the flatpak
/// one", which is a conversational follow-up rather than a new application.
pub fn parse_explicit_install(query: &str) -> Option<(String, Option<Backend>)> {
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 "))?;
let tokens: Vec<&str> = rest.split_whitespace().collect();
let app = tokens
.first()
.copied()
.filter(|t| !NON_APP_TOKENS.contains(t) && !t.starts_with('-'))?;
let mut backend = None;
for token in &tokens[1..] {
if let Some(b) = backend_from_word(token) {
backend = Some(b);
} else if !NON_APP_TOKENS.contains(token) {
// A trailing word that is not a source or a filler makes this an
// ambiguous instruction; let the model investigate it instead.
return None;
}
}
Some((app.to_string(), backend))
}
/// Analyze incoming query against the most recent conversation turn.
pub fn resolve_followup(query: &str, history: &ConversationHistory) -> Option<FollowupResolution> {
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))
);
// 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);
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("<redacted>"));
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));
}
}