//! AI-driven installation investigation. //! //! The model does not get a shell. It runs a **bounded, multi-turn //! investigation**: it may ask for typed, read-only evidence (via //! [`InstallSession::investigate`]), ask the user a question about intent //! (via [`InstallSession::ask`]), and only then return a structured //! [`InstallProposal`]. The proposal is validated structurally here and //! *independently* by the deterministic resolver in `phoebus-executor`, which //! must confirm the candidate against real backend metadata. //! //! Bounds: a turn limit, a per-turn request limit, a response-size limit and //! repeated-request detection. A repeated evidence request is not executed //! again; the model is told to finalise or ask the user instead of looping. use phoebus_core::action::{valid_application_name, valid_candidate_id, SystemAction}; use phoebus_core::selection::Backend; use serde::{Deserialize, Serialize}; use crate::provider::{ extract_content, ChatMessage, ChatRequest, ModelTransport, ProviderKind, ResponseFormat, SystemFacts, }; use crate::AiError; /// The model's structured installation recommendation. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct InstallProposal { /// The user-facing application (identity, not a backend id). pub application: String, pub backend: Backend, /// The backend-native identifier, copied from evidence. pub candidate: String, #[serde(default, skip_serializing_if = "Option::is_none")] pub version: Option, /// Why this candidate suits this machine and request. pub reason: String, #[serde(default)] pub tradeoffs: Vec, /// Evidence the recommendation rests on (candidate ids, measured facts). #[serde(default)] pub evidence: Vec, } const MAX_TEXT: usize = 4096; const MAX_ITEM: usize = 1024; const MAX_ITEMS: usize = 16; impl InstallProposal { /// Structural validation only. The deterministic resolver still confirms /// the candidate against real metadata; this just rejects malformed or /// absurd proposals before they reach it. pub fn validate_structural(&self) -> Result<(), String> { if !valid_application_name(&self.application) { return Err(format!("invalid application name: {}", self.application)); } if !valid_candidate_id(self.backend, &self.candidate) { return Err(format!( "invalid {} candidate id: {}", self.backend.as_str(), self.candidate )); } if self.reason.trim().is_empty() || self.reason.len() > MAX_TEXT { return Err("a bounded, non-empty reason is required".into()); } for list in [&self.tradeoffs, &self.evidence] { if list.len() > MAX_ITEMS { return Err(format!("at most {MAX_ITEMS} items are allowed")); } if list.iter().any(|s| s.len() > MAX_ITEM) { return Err("an item is too long".into()); } } if let Some(version) = &self.version { if version.len() > 256 || version.chars().any(|c| c.is_control()) { return Err("invalid version string".into()); } } Ok(()) } pub fn render(&self) -> String { let mut out = String::new(); out.push_str(&format!( "application: {}\n backend: {}\n candidate: {}\n", self.application, self.backend.as_str(), self.candidate )); if let Some(version) = &self.version { out.push_str(&format!(" version: {version}\n")); } out.push_str(&format!(" why: {}\n", self.reason)); for t in &self.tradeoffs { out.push_str(&format!(" tradeoff: {t}\n")); } for e in &self.evidence { out.push_str(&format!(" evidence: {e}\n")); } out } } /// A step in the investigation conversation. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub enum InstallStep { Ask { question: String, }, Investigate { requests: Vec, }, Propose { summary: String, proposal: InstallProposal, }, } /// The closed set of read-only actions the model may request as evidence. pub fn is_investigation_action(action: &SystemAction) -> bool { matches!( action, SystemAction::DiscoverCandidates { .. } | SystemAction::InspectCandidate { .. } | SystemAction::CheckBackend { .. } | SystemAction::InspectInstallation { .. } ) } /// One piece of evidence returned for a request. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct Evidence { pub request: String, pub output: String, } /// The system-side half of the loop: produce evidence and, optionally, ask the /// user a question about intent. Implemented by `phoebus-executor`/`sys`. pub trait InstallSession { /// Execute read-only investigation actions and return their evidence. fn investigate(&self, requests: &[SystemAction]) -> Vec; /// Ask the user a question about intent or preference. `None` means no /// answer is available (non-interactive); the model is then told to proceed /// with a conservative, reversible assumption. fn ask(&self, question: &str) -> Option; } /// Hard bounds on the investigation loop. #[derive(Debug, Clone)] pub struct Limits { pub max_turns: usize, pub max_requests_per_turn: usize, /// Maximum bytes of evidence fed back in one turn. pub max_evidence_bytes: usize, /// How many times the exact same evidence request set may repeat before the /// loop refuses to execute it again. pub max_identical_requests: usize, } impl Default for Limits { fn default() -> Self { Self { max_turns: 8, max_requests_per_turn: 6, max_evidence_bytes: 24 * 1024, max_identical_requests: 1, } } } pub const INSTALL_PROMPT: &str = "\ You are the Phoebus OS installation advisor. The user asked to install an application. \ You must recommend the single best installation option for THIS machine and the user's \ request, using only real candidate identifiers returned to you. You have no shell, no \ root, no filesystem access and no credentials. Each reply is ONE JSON object with version 2 and a `kind`: 1. Investigate (read-only evidence): \ {\"version\":2,\"kind\":\"investigate\",\"requests\":[,...]}. Allowed actions: \ discover_candidates (query, optional kind/gui/requires_sandbox), inspect_candidate \ (backend, id), check_backend (backend), inspect_installation (application). 2. Ask the user about intent (only when system facts cannot answer): \ {\"version\":2,\"kind\":\"ask\",\"question\":\"...\"}. Use this sparingly, e.g. whether \ the application must access local development tools or a specific file. 3. Propose: {\"version\":2,\"kind\":\"propose\",\"proposal\":{\"application\":\"...\",\ \"backend\":\"...\",\"candidate\":\"...\",\"version\":\"...\",\"reason\":\"...\",\ \"tradeoffs\":[\"...\"],\"evidence\":[\"...\"]}}. Backends: portage-source, portage-binary, portage-vendor, nix, flatpak, snap, appimage, \ custom-ebuild. Rules: compare suitable options across lanes; do NOT choose a lane merely because the \ application is a desktop app (Flatpak/Snap) or a developer tool (Nix) — base the choice on \ the machine facts, the user's requirement, permissions, confinement, integration, size, \ measured compile time and update behaviour. Never invent a candidate id, version, size, \ checksum, availability or compatibility: use only what discover_candidates returned. \ Portage owns the kernel, drivers, systemd, the host graphics/audio stack and boot tooling. \ Prefer an existing installation and the user's saved preference; never migrate or duplicate \ silently. If the user asked for a specific backend, honour it. When you have enough \ evidence, propose."; /// Build the first request of the investigation. pub fn build_open_request( provider: ProviderKind, model: &str, facts: &SystemFacts, request: &str, ) -> ChatRequest { let model = if model.trim().is_empty() { provider.default_model().to_string() } else { model.trim().to_string() }; let user = format!( "System facts (JSON):\n{}\n\nUser installation request: {request}\n\n\ Investigate or propose.", facts.render() ); ChatRequest { model, messages: vec![ ChatMessage { role: "system".into(), content: INSTALL_PROMPT.into(), }, ChatMessage { role: "user".into(), content: user, }, ], temperature: 0.0, response_format: Some(ResponseFormat { kind: "json_object".into(), }), } } /// Parse one model message strictly. Unknown fields, an unsupported version, an /// unknown kind, or a mutating/invalid investigation action fail closed. pub fn parse_step(text: &str) -> Result { let value: serde_json::Value = serde_json::from_str(text)?; let obj = value .as_object() .ok_or_else(|| AiError::Rejected("the reply must be a JSON object".into()))?; let version = obj .get("version") .and_then(|v| v.as_u64()) .ok_or_else(|| AiError::Rejected("missing `version`".into()))?; if version != 2 { return Err(AiError::UnsupportedVersion(version as u32)); } let kind = obj .get("kind") .and_then(|k| k.as_str()) .ok_or_else(|| AiError::Rejected("missing `kind`".into()))?; let allowed: &[&str] = match kind { "ask" => &["version", "kind", "question"], "investigate" => &["version", "kind", "requests"], "propose" => &["version", "kind", "proposal"], other => return Err(AiError::Rejected(format!("unknown kind `{other}`"))), }; for key in obj.keys() { if !allowed.contains(&key.as_str()) { return Err(AiError::Rejected(format!("unexpected field `{key}`"))); } } let get = |key: &str| { obj.get(key) .cloned() .ok_or_else(|| AiError::Rejected(format!("missing `{key}`"))) }; match kind { "ask" => { let question: String = serde_json::from_value(get("question")?)?; if question.trim().is_empty() || question.len() > 1024 { return Err(AiError::Rejected("invalid question".into())); } Ok(InstallStep::Ask { question }) } "investigate" => { let requests: Vec = serde_json::from_value(get("requests")?)?; for request in &requests { if !is_investigation_action(request) { return Err(AiError::Rejected(format!( "`{}` is not a permitted read-only investigation action", request.describe() ))); } request .validate() .map_err(|e| AiError::Rejected(format!("invalid request: {e}")))?; } Ok(InstallStep::Investigate { requests }) } "propose" => { let proposal: InstallProposal = serde_json::from_value(get("proposal")?)?; proposal.validate_structural().map_err(AiError::Rejected)?; Ok(InstallStep::Propose { summary: String::new(), proposal, }) } _ => unreachable!(), } } fn messages_body(request: &ChatRequest) -> Result { Ok(serde_json::to_string(request)?) } /// Run the bounded investigation and return a structurally valid proposal. /// /// `validate` is the deterministic resolver's check (provided by the caller). /// A rejected proposal is fed back to the model for a bounded revision rather /// than being accepted. #[allow(clippy::too_many_arguments)] pub fn investigate_install( provider: ProviderKind, endpoint: &str, model: &str, facts: &SystemFacts, request: &str, transport: &dyn ModelTransport, session: &dyn InstallSession, validate: &dyn Fn(&InstallProposal) -> Result<(), String>, limits: &Limits, ) -> Result { if provider == ProviderKind::None { return Err(AiError::ProviderUnavailable( "no AI provider selected".into(), )); } crate::provider::validate_endpoint(endpoint)?; facts.validate_no_forbidden()?; let mut chat = build_open_request(provider, model, facts, request); let mut repeated: std::collections::BTreeMap = std::collections::BTreeMap::new(); let mut turns = 0usize; while turns < limits.max_turns { turns += 1; let body = messages_body(&chat)?; let response = transport.send(provider, endpoint, &body)?; let content = extract_content(&response)?; let step = parse_step(&content)?; match step { InstallStep::Ask { question } => { chat.messages.push(ChatMessage { role: "assistant".into(), content: content.clone(), }); let answer = session.ask(&question); let user = match answer { Some(answer) => format!("The user answered: {answer}"), None => "No answer is available (non-interactive). Proceed with a \ conservative, reversible choice and state your assumption." .to_string(), }; chat.messages.push(ChatMessage { role: "user".into(), content: user, }); } InstallStep::Investigate { requests } => { if requests.is_empty() { return Err(AiError::Rejected("empty investigation request".into())); } if requests.len() > limits.max_requests_per_turn { return Err(AiError::Rejected(format!( "too many investigation requests in one turn (max {})", limits.max_requests_per_turn ))); } for request in &requests { if !is_investigation_action(request) { return Err(AiError::Rejected(format!( "`{}` is not a permitted read-only investigation action", request.describe() ))); } request .validate() .map_err(|e| AiError::Rejected(format!("invalid request: {e}")))?; } // Canonical key: sorted action JSON, so order does not matter. let mut keys: Vec = requests .iter() .filter_map(|r| serde_json::to_string(r).ok()) .collect(); keys.sort(); let key = keys.join("|"); let count = repeated.entry(key).or_insert(0); *count += 1; chat.messages.push(ChatMessage { role: "assistant".into(), content: content.clone(), }); if *count > limits.max_identical_requests { chat.messages.push(ChatMessage { role: "user".into(), content: "You already requested exactly this evidence; it will not \ be fetched again. Propose now, or ask the user a question \ if their intent is genuinely unknown." .to_string(), }); continue; } let evidence = session.investigate(&requests); let mut payload = String::new(); for item in &evidence { payload.push_str(&format!( "Request: {}\nOutput:\n{}\n\n", item.request, item.output )); if payload.len() >= limits.max_evidence_bytes { break; } } if payload.len() > limits.max_evidence_bytes { payload.truncate(limits.max_evidence_bytes); payload.push_str("\n[evidence truncated]"); } chat.messages.push(ChatMessage { role: "user".into(), content: format!("Evidence:\n{payload}"), }); } InstallStep::Propose { proposal, .. } => { proposal.validate_structural().map_err(AiError::Rejected)?; match validate(&proposal) { Ok(()) => return Ok(proposal), Err(findings) => { chat.messages.push(ChatMessage { role: "assistant".into(), content: content.clone(), }); chat.messages.push(ChatMessage { role: "user".into(), content: format!( "Your proposal was rejected by the deterministic resolver: \ {findings}. Investigate further or propose a different, \ real candidate." ), }); } } } } } Err(AiError::Rejected(format!( "the investigation did not reach a valid proposal within {} turns", limits.max_turns ))) } #[cfg(test)] mod tests { use super::*; use crate::provider::chat_response; fn facts() -> SystemFacts { SystemFacts { arch: "x86_64".into(), cpu_cores: 8, memory_mib: 16384, ..Default::default() } } struct Sessions { evidence: std::cell::RefCell>>, answer: Option, } impl InstallSession for Sessions { fn investigate(&self, requests: &[SystemAction]) -> Vec { self.evidence.borrow_mut().push(requests.to_vec()); requests .iter() .map(|r| Evidence { request: r.describe(), output: "[{\"backend\":\"flatpak\",\"id\":\"org.mozilla.firefox\"}]".into(), }) .collect() } fn ask(&self, _q: &str) -> Option { self.answer.clone() } } fn ok_proposal() -> &'static str { r#"{"version":2,"kind":"propose","proposal":{"application":"firefox","backend":"flatpak","candidate":"org.mozilla.firefox","reason":"sandboxed, native Wayland","evidence":["org.mozilla.firefox"]}}"# } #[test] fn parse_accepts_the_three_step_kinds() { let ask = parse_step(r#"{"version":2,"kind":"ask","question":"Do you need dev tools?"}"#) .unwrap(); assert!(matches!(ask, InstallStep::Ask { .. })); let inv = parse_step( r#"{"version":2,"kind":"investigate","requests":[{"action":"discover_candidates","query":"firefox"}]}"#, ) .unwrap(); assert!(matches!(inv, InstallStep::Investigate { .. })); let prop = parse_step(ok_proposal()).unwrap(); assert!(matches!(prop, InstallStep::Propose { .. })); } #[test] fn parse_rejects_mutation_unknown_fields_and_bad_version() { // A mutating action is not a permitted investigation request. let err = parse_step( r#"{"version":2,"kind":"investigate","requests":[{"action":"install_package","atom":"vim"}]}"#, ) .unwrap_err(); assert!(err.to_string().contains("read-only") || err.to_string().contains("permitted")); // Unknown top-level field. assert!(parse_step(r#"{"version":2,"kind":"ask","question":"q","shell":"sh"}"#).is_err()); // Unsupported version. assert!(matches!( parse_step(r#"{"version":1,"kind":"ask","question":"q"}"#), Err(AiError::UnsupportedVersion(1)) )); // Bad candidate for the backend. let bad = r#"{"version":2,"kind":"propose","proposal":{"application":"firefox","backend":"flatpak","candidate":"bad id","reason":"x"}}"#; assert!(parse_step(bad).unwrap_err().to_string().contains("invalid")); } #[test] fn investigation_then_proposal_succeeds() { let transport = crate::provider::ScriptedTransport::new(vec![ chat_response( r#"{"version":2,"kind":"investigate","requests":[{"action":"discover_candidates","query":"firefox"}]}"#, ), chat_response(ok_proposal()), ]); let session = Sessions { evidence: std::cell::RefCell::new(Vec::new()), answer: None, }; let proposal = investigate_install( ProviderKind::Local, "http://127.0.0.1:11434/v1/chat/completions", "m", &facts(), "install firefox", &transport, &session, &|_| Ok(()), &Limits::default(), ) .unwrap(); assert_eq!(proposal.candidate, "org.mozilla.firefox"); assert_eq!(session.evidence.borrow().len(), 1); let requests = transport.requests(); assert_eq!(requests.len(), 2); // The second request must carry the evidence back to the model. assert!(requests[1].contains("org.mozilla.firefox")); } #[test] fn a_rejected_proposal_is_revised_with_findings() { let transport = crate::provider::ScriptedTransport::new(vec![ chat_response(ok_proposal()), chat_response(ok_proposal()), ]); let session = Sessions { evidence: std::cell::RefCell::new(Vec::new()), answer: None, }; let attempts = std::cell::Cell::new(0); let validate = |_: &InstallProposal| -> Result<(), String> { attempts.set(attempts.get() + 1); if attempts.get() == 1 { Err("no such Flatpak id in the configured remotes".into()) } else { Ok(()) } }; let proposal = investigate_install( ProviderKind::Local, "http://127.0.0.1:11434/v1/chat/completions", "m", &facts(), "install firefox", &transport, &session, &validate, &Limits::default(), ) .unwrap(); assert_eq!(proposal.application, "firefox"); assert_eq!(attempts.get(), 2); let requests = transport.requests(); assert!(requests[1].contains("rejected")); } #[test] fn truncated_by_the_turn_limit() { // The model keeps investigating forever; the loop stops. let transport = crate::provider::ScriptedTransport::new( (0..10) .map(|_| { chat_response( r#"{"version":2,"kind":"investigate","requests":[{"action":"check_backend","backend":"flatpak"}]}"#, ) }) .collect(), ); let session = Sessions { evidence: std::cell::RefCell::new(Vec::new()), answer: None, }; let limits = Limits { max_turns: 4, ..Default::default() }; let err = investigate_install( ProviderKind::Local, "http://127.0.0.1:11434/v1/chat/completions", "m", &facts(), "install x", &transport, &session, &|_| Ok(()), &limits, ) .unwrap_err(); assert!(err.to_string().contains("did not reach a valid proposal")); // The identical evidence is fetched exactly once. assert_eq!(session.evidence.borrow().len(), 1); } #[test] fn too_many_requests_in_a_turn_are_refused() { let transport = crate::provider::ScriptedTransport::new(vec![chat_response( r#"{"version":2,"kind":"investigate","requests":[{"action":"check_backend","backend":"flatpak"},{"action":"check_backend","backend":"nix"},{"action":"check_backend","backend":"snap"},{"action":"check_backend","backend":"appimage"},{"action":"check_backend","backend":"portage-source"},{"action":"check_backend","backend":"portage-binary"},{"action":"check_backend","backend":"custom-ebuild"}]}"#, )]); let session = Sessions { evidence: std::cell::RefCell::new(Vec::new()), answer: None, }; let err = investigate_install( ProviderKind::Local, "http://127.0.0.1:11434/v1/chat/completions", "m", &facts(), "install x", &transport, &session, &|_| Ok(()), &Limits::default(), ) .unwrap_err(); assert!(err.to_string().contains("too many")); assert!(session.evidence.borrow().is_empty()); } #[test] fn ask_feeds_the_answer_back_and_none_is_explicit() { let transport = crate::provider::ScriptedTransport::new(vec![ chat_response(r#"{"version":2,"kind":"ask","question":"Do you need dev tools?"}"#), chat_response(ok_proposal()), ]); let session = Sessions { evidence: std::cell::RefCell::new(Vec::new()), answer: Some("yes".into()), }; investigate_install( ProviderKind::Local, "http://127.0.0.1:11434/v1/chat/completions", "m", &facts(), "install nodejs", &transport, &session, &|_| Ok(()), &Limits::default(), ) .unwrap(); assert!(transport.requests()[1].contains("The user answered: yes")); } #[test] fn an_unavailable_provider_is_explicit() { let transport = crate::provider::TestTransport::new("{}"); let session = Sessions { evidence: std::cell::RefCell::new(Vec::new()), answer: None, }; let err = investigate_install( ProviderKind::None, "http://127.0.0.1:11434/v1/chat/completions", "m", &facts(), "install x", &transport, &session, &|_| Ok(()), &Limits::default(), ) .unwrap_err(); assert!(matches!(err, AiError::ProviderUnavailable(_))); } }