phoebus_os/installer-rs/crates/phoebus-ai/src/install.rs
Phoebus f9e39925b4 feat(install): AI-first sys install workflow
Implement the shared installation workflow (ADR 0013). sys install, sys ask
install and the explicit backend flags all use one path: identify -> evidence
-> AI investigation -> deterministic validation/effects -> review -> approval
-> execute -> verify -> history.

- phoebus-ai::install: bounded, multi-turn investigation. The model may request
  typed read-only evidence (discover_candidates, inspect_candidate,
  check_backend, inspect_installation), ask one bounded question about intent,
  and must return a structured InstallProposal. Turn/request/size limits and
  repeated-request detection bound it; a rejected proposal is revised.
- phoebus-core: add the four read-only investigation actions and strict
  validators; add a transaction id; backend/kind wire names now match as_str.
- phoebus-executor::install: resolve_explicit (no model, no fallback),
  resolve_deterministic and resolve_with_ai; validate_proposal re-resolves the
  candidate against real metadata, rejects fabrication/ambiguity/staleness/
  duplicates, maps it to the existing broker action, and binds approval to a
  digest; revalidate + verify_installed. chooser gains per-lane friendly-name
  resolution and structured evidence.
- transaction::begin/finish record an in-progress transaction before mutation.
- sys: --portage/--flatpak/--nix/--snap/--appimage/--ebuild (mutually
  exclusive) bypass the model; an unqualified install consults the model and,
  with none, prints the deterministic selection and installs nothing.
- The installer persists /etc/phoebus/install.toml; sys loads it and adds free
  space, Wayland, usable lanes, saved preferences and recovery capability to
  the bounded facts.
- Docs: ADR 0013, docs/SYS.md install sections and cases 23-31, CHANGELOG,
  STATUS, HANDOFF, ROADMAP. New live-VM workflow check script.

Host gates pass: fmt, clippy (no new warnings), workspace tests, make test.
VM: verified the workflow CLI and read-only investigation on the reference
LiveGUI ISO; a full target install journey is running (see HANDOFF).
2026-09-23 20:30:13 -07:00

712 lines
27 KiB
Rust

//! 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<String>,
/// Why this candidate suits this machine and request.
pub reason: String,
#[serde(default)]
pub tradeoffs: Vec<String>,
/// Evidence the recommendation rests on (candidate ids, measured facts).
#[serde(default)]
pub evidence: Vec<String>,
}
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<SystemAction>,
},
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<Evidence>;
/// 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<String>;
}
/// 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\":[<action>,...]}. 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<InstallStep, AiError> {
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<SystemAction> = 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<String, AiError> {
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<InstallProposal, AiError> {
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<String, usize> = 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<String> = 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<Vec<Vec<SystemAction>>>,
answer: Option<String>,
}
impl InstallSession for Sessions {
fn investigate(&self, requests: &[SystemAction]) -> Vec<Evidence> {
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<String> {
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(_)));
}
}