feat(installer): require AI to install; add local provider

Installing Phoebus now requires a connected model: the install gate refuses
with no provider unless the explicit break-glass --no-ai (alias --legacy, or
PHOEBUS_NO_AI=1) is used. Add a 'local' provider kind (Ollama/llama.cpp/
LM Studio) with an optional API key and --ai-endpoint override, so a user can
run a model they downloaded; no model is shipped. Desktop installs now include
xdg-desktop-portal + gtk/wlr backends for Flatpak and Wayland apps.
This commit is contained in:
Phoebus 2026-09-20 14:41:53 -07:00
parent d36b2fe5fe
commit 3a405dd1e7
6 changed files with 228 additions and 18 deletions

View file

@ -22,6 +22,9 @@ pub enum ProviderKind {
None, None,
DeepSeek, DeepSeek,
OpenAi, OpenAi,
/// An OpenAI-compatible server the user runs locally (Ollama, llama.cpp,
/// LM Studio, ...). No model is shipped; the user downloads and serves one.
Local,
} }
impl ProviderKind { impl ProviderKind {
@ -30,6 +33,7 @@ impl ProviderKind {
ProviderKind::None => "none", ProviderKind::None => "none",
ProviderKind::DeepSeek => "deepseek", ProviderKind::DeepSeek => "deepseek",
ProviderKind::OpenAi => "openai", ProviderKind::OpenAi => "openai",
ProviderKind::Local => "local",
} }
} }
@ -39,16 +43,21 @@ impl ProviderKind {
"" | "none" | "no" | "off" | "without" => Some(ProviderKind::None), "" | "none" | "no" | "off" | "without" => Some(ProviderKind::None),
"deepseek" => Some(ProviderKind::DeepSeek), "deepseek" => Some(ProviderKind::DeepSeek),
"openai" | "chatgpt" | "gpt" => Some(ProviderKind::OpenAi), "openai" | "chatgpt" | "gpt" => Some(ProviderKind::OpenAi),
"local" | "ollama" | "llama" | "llamacpp" | "llama.cpp" | "lmstudio" | "lm-studio" => {
Some(ProviderKind::Local)
}
_ => None, _ => None,
} }
} }
/// The chat-completions endpoint. /// The default chat-completions endpoint. For `Local` this is the common
/// Ollama OpenAI-compatible address; `--ai-endpoint` overrides it.
pub fn endpoint(self) -> &'static str { pub fn endpoint(self) -> &'static str {
match self { match self {
ProviderKind::None => "", ProviderKind::None => "",
ProviderKind::DeepSeek => "https://api.deepseek.com/chat/completions", ProviderKind::DeepSeek => "https://api.deepseek.com/chat/completions",
ProviderKind::OpenAi => "https://api.openai.com/v1/chat/completions", ProviderKind::OpenAi => "https://api.openai.com/v1/chat/completions",
ProviderKind::Local => "http://127.0.0.1:11434/v1/chat/completions",
} }
} }
@ -57,11 +66,14 @@ impl ProviderKind {
ProviderKind::None => "", ProviderKind::None => "",
ProviderKind::DeepSeek => "deepseek-chat", ProviderKind::DeepSeek => "deepseek-chat",
ProviderKind::OpenAi => "gpt-4o-mini", ProviderKind::OpenAi => "gpt-4o-mini",
ProviderKind::Local => "llama3.1",
} }
} }
/// Only the hosted providers need an API key; a local server usually does
/// not, but `--ai-api-key-file` may still be supplied if it does.
pub fn requires_key(self) -> bool { pub fn requires_key(self) -> bool {
!matches!(self, ProviderKind::None) matches!(self, ProviderKind::DeepSeek | ProviderKind::OpenAi)
} }
} }
@ -327,16 +339,33 @@ pub fn complete_proposal(
model: &str, model: &str,
facts: &SystemFacts, facts: &SystemFacts,
transport: &dyn ModelTransport, transport: &dyn ModelTransport,
) -> Result<AiProposal, AiError> {
complete_proposal_at(provider, provider.endpoint(), model, facts, transport)
}
/// As `complete_proposal`, but with an explicit endpoint (`--ai-endpoint`), for
/// a self-hosted model on a non-default port.
pub fn complete_proposal_at(
provider: ProviderKind,
endpoint: &str,
model: &str,
facts: &SystemFacts,
transport: &dyn ModelTransport,
) -> Result<AiProposal, AiError> { ) -> Result<AiProposal, AiError> {
if provider == ProviderKind::None { if provider == ProviderKind::None {
return Err(AiError::ProviderUnavailable( return Err(AiError::ProviderUnavailable(
"no AI provider selected".into(), "no AI provider selected".into(),
)); ));
} }
if endpoint.trim().is_empty() {
return Err(AiError::ProviderUnavailable(
"no provider endpoint configured".into(),
));
}
facts.validate_no_forbidden()?; facts.validate_no_forbidden()?;
let request = build_request(provider, model, facts); let request = build_request(provider, model, facts);
let body = serde_json::to_string(&request)?; let body = serde_json::to_string(&request)?;
let response = transport.send(provider, provider.endpoint(), &body)?; let response = transport.send(provider, endpoint, &body)?;
let content = extract_content(&response)?; let content = extract_content(&response)?;
parse_proposal(&content) parse_proposal(&content)
} }
@ -429,12 +458,36 @@ mod tests {
); );
assert_eq!(ProviderKind::parse("continue without AI"), None); assert_eq!(ProviderKind::parse("continue without AI"), None);
assert_eq!(ProviderKind::parse("none"), Some(ProviderKind::None)); assert_eq!(ProviderKind::parse("none"), Some(ProviderKind::None));
assert_eq!(ProviderKind::parse("ollama"), Some(ProviderKind::Local));
assert_eq!(ProviderKind::parse("Local"), Some(ProviderKind::Local));
assert!(ProviderKind::OpenAi.endpoint().starts_with("https://")); assert!(ProviderKind::OpenAi.endpoint().starts_with("https://"));
assert!(ProviderKind::None.endpoint().is_empty()); assert!(ProviderKind::None.endpoint().is_empty());
assert!(ProviderKind::Local
.endpoint()
.starts_with("http://127.0.0.1"));
assert!(ProviderKind::DeepSeek.requires_key()); assert!(ProviderKind::DeepSeek.requires_key());
assert!(ProviderKind::OpenAi.requires_key());
// A self-hosted local server needs no key.
assert!(!ProviderKind::Local.requires_key());
assert!(!ProviderKind::None.requires_key()); assert!(!ProviderKind::None.requires_key());
} }
#[test]
fn local_provider_uses_an_explicit_endpoint() {
let proposal = r#"{"version":1,"changes":[{"action":"set_flatpak","value":true}]}"#;
let transport = TestTransport::proposal(proposal);
let parsed = complete_proposal_at(
ProviderKind::Local,
"http://127.0.0.1:8080/v1/chat/completions",
"qwen2.5-coder",
&facts(),
&transport,
)
.unwrap();
assert_eq!(parsed.changes.len(), 1);
assert!(complete_proposal_at(ProviderKind::Local, "", "", &facts(), &transport).is_err());
}
#[test] #[test]
fn request_has_no_secret_and_pins_the_schema() { fn request_has_no_secret_and_pins_the_schema() {
let request = build_request(ProviderKind::DeepSeek, "", &facts()); let request = build_request(ProviderKind::DeepSeek, "", &facts());

View file

@ -58,6 +58,11 @@ pub fn desktop_packages(profile: DesktopProfile) -> Vec<&'static str> {
"net-misc/networkmanager", "net-misc/networkmanager",
"sys-auth/polkit", "sys-auth/polkit",
"gnome-extra/polkit-gnome", "gnome-extra/polkit-gnome",
// Desktop portals: required by Flatpak (file chooser, screencast,
// screenshots) and expected by many Wayland apps.
"sys-apps/xdg-desktop-portal",
"sys-apps/xdg-desktop-portal-gtk",
"gui-libs/xdg-desktop-portal-wlr",
], ],
} }
.into_iter() .into_iter()
@ -653,6 +658,15 @@ mod tests {
assert!(text.contains("uki_generator=none")); assert!(text.contains("uki_generator=none"));
} }
#[test]
fn desktop_includes_portals_for_flatpak_and_wayland() {
let pkgs = desktop_packages(DesktopProfile::Dwl);
assert!(pkgs.contains(&"sys-apps/xdg-desktop-portal"));
assert!(pkgs.contains(&"sys-apps/xdg-desktop-portal-gtk"));
assert!(pkgs.contains(&"gui-libs/xdg-desktop-portal-wlr"));
assert!(desktop_packages(DesktopProfile::None).is_empty());
}
#[test] #[test]
fn desktop_none_has_no_x_use_block() { fn desktop_none_has_no_x_use_block() {
let mut cfg = InstallConfig::default(); let mut cfg = InstallConfig::default();

View file

@ -41,14 +41,19 @@ pub fn load_api_key(path: &Path) -> Result<SecretString> {
} }
/// A transport that talks to an OpenAI-compatible endpoint with curl. /// A transport that talks to an OpenAI-compatible endpoint with curl.
///
/// The API key is optional: a self-hosted local model usually needs none, while
/// DeepSeek/OpenAI require one.
pub struct CurlTransport<'a> { pub struct CurlTransport<'a> {
exec: &'a Exec, exec: &'a Exec,
api_key: SecretString, api_key: Option<SecretString>,
} }
impl<'a> CurlTransport<'a> { impl<'a> CurlTransport<'a> {
pub fn new(exec: &'a Exec, api_key: SecretString) -> Self { pub fn new(exec: &'a Exec, api_key: Option<SecretString>) -> Self {
exec.register_secret(&api_key); if let Some(key) = &api_key {
exec.register_secret(key);
}
Self { exec, api_key } Self { exec, api_key }
} }
} }
@ -72,13 +77,16 @@ impl ModelTransport for CurlTransport<'_> {
// curl reads this config from stdin, so Exec marks the stdin as hidden // curl reads this config from stdin, so Exec marks the stdin as hidden
// and never logs it. The key is therefore absent from argv and logs. // and never logs it. The key is therefore absent from argv and logs.
let auth = match &self.api_key {
Some(key) => format!("header = \"Authorization: Bearer {}\"\n", key.expose()),
None => String::new(),
};
let config = format!( let config = format!(
"url = \"{url}\"\n\ "url = \"{url}\"\n\
header = \"Content-Type: application/json\"\n\ header = \"Content-Type: application/json\"\n\
header = \"Authorization: Bearer {key}\"\n\ {auth}\
data = \"@{path}\"\n\ data = \"@{path}\"\n\
silent\nshow-error\nfail-with-body\nmax-time = 120\n", silent\nshow-error\nfail-with-body\nmax-time = 120\n",
key = self.api_key.expose(),
path = request.path().display() path = request.path().display()
); );
let spec = CommandSpec::new("ai", "query model", "curl") let spec = CommandSpec::new("ai", "query model", "curl")
@ -132,7 +140,7 @@ mod tests {
}, },
); );
let exec = make_exec(runner.clone()); let exec = make_exec(runner.clone());
let transport = CurlTransport::new(&exec, SecretString::new("sk-secret-value")); let transport = CurlTransport::new(&exec, Some(SecretString::new("sk-secret-value")));
let out = transport let out = transport
.send( .send(
ProviderKind::OpenAi, ProviderKind::OpenAi,
@ -155,4 +163,32 @@ mod tests {
// And the key is registered for redaction. // And the key is registered for redaction.
assert_eq!(exec.redactor().redact("sk-secret-value"), "<redacted>"); assert_eq!(exec.redactor().redact("sk-secret-value"), "<redacted>");
} }
#[test]
fn curl_transport_omits_auth_without_a_key() {
let runner = RecordingRunner::new();
runner.set_response(
"curl",
CommandOutput {
status: 0,
success: true,
stdout: b"{}".to_vec(),
stderr: Vec::new(),
duration: Duration::from_millis(1),
},
);
let exec = make_exec(runner.clone());
let transport = CurlTransport::new(&exec, None);
transport
.send(
ProviderKind::Local,
"http://127.0.0.1:11434/v1/chat/completions",
"{}",
)
.unwrap();
let spec = &runner.recorded()[0];
let stdin = String::from_utf8(spec.stdin.clone().unwrap()).unwrap();
assert!(!stdin.contains("Authorization"));
assert!(stdin.contains("http://127.0.0.1"));
}
} }

View file

@ -7,7 +7,9 @@
use std::path::Path; use std::path::Path;
use phoebus_ai::provider::{complete_proposal, ModelTransport, ProviderKind, SystemFacts}; use phoebus_ai::provider::{
complete_proposal, complete_proposal_at, ModelTransport, ProviderKind, SystemFacts,
};
use phoebus_ai::{parse_proposal, review, AiError, ReviewOutcome}; use phoebus_ai::{parse_proposal, review, AiError, ReviewOutcome};
use phoebus_core::InstallConfig; use phoebus_core::InstallConfig;
@ -54,6 +56,20 @@ pub fn generate_and_review(
review(config, &proposal) review(config, &proposal)
} }
/// As `generate_and_review`, with an explicit endpoint (a self-hosted local
/// model on a non-default address).
pub fn generate_and_review_at(
config: &mut InstallConfig,
facts: &SystemFacts,
provider: ProviderKind,
endpoint: &str,
model: &str,
transport: &dyn ModelTransport,
) -> Result<ReviewOutcome, AiError> {
let proposal = complete_proposal_at(provider, endpoint, model, facts, transport)?;
review(config, &proposal)
}
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use super::*; use super::*;

View file

@ -101,6 +101,15 @@ struct Cli {
/// Print the system facts that would be sent to the model, then exit. /// Print the system facts that would be sent to the model, then exit.
#[arg(long)] #[arg(long)]
ai_facts: bool, ai_facts: bool,
/// Override the provider endpoint (self-hosted/local models).
#[arg(long, value_name = "URL")]
ai_endpoint: Option<String>,
/// Install without AI (break-glass for recovery/automation). Also
/// `--legacy` or `PHOEBUS_NO_AI=1`.
#[arg(long, alias = "legacy")]
no_ai: bool,
} }
struct TerminalConfirm; struct TerminalConfirm;
@ -145,8 +154,33 @@ fn resolve_provider(
.ai_provider .ai_provider
.as_deref() .as_deref()
.unwrap_or(config.ai.provider.as_str()); .unwrap_or(config.ai.provider.as_str());
ProviderKind::parse(raw) ProviderKind::parse(raw).ok_or_else(|| {
.ok_or_else(|| format!("unknown AI provider `{raw}` (use deepseek, openai or none)").into()) format!("unknown AI provider `{raw}` (use deepseek, openai, local or none)").into()
})
}
/// Whether the user explicitly asked for a deterministic, no-AI run.
fn no_ai_requested(cli: &Cli) -> bool {
cli.no_ai
|| std::env::var("PHOEBUS_NO_AI")
.map(|v| matches!(v.to_ascii_lowercase().as_str(), "1" | "yes" | "true"))
.unwrap_or(false)
}
/// Installing Phoebus requires a connected model. `--no-ai`/`--legacy` is the
/// explicit, documented break-glass for recovery or automation.
fn require_ai_for_install(
cli: &Cli,
provider: ProviderKind,
) -> std::result::Result<(), Box<dyn std::error::Error>> {
if no_ai_requested(cli) || provider != ProviderKind::None {
return Ok(());
}
Err("installing Phoebus requires a connected AI model.\n\
Connect a provider (--ai-provider deepseek|openai|local, with \
--ai-api-key-file and/or --ai-endpoint), or pass --no-ai (alias \
--legacy) for a deterministic install."
.into())
} }
/// Apply AI guidance to the configuration before the plan is shown or install /// Apply AI guidance to the configuration before the plan is shown or install
@ -181,17 +215,29 @@ fn run_ai_guidance(
); );
eprintln!("{}", facts.render()); eprintln!("{}", facts.render());
let key_path = cli let endpoint = cli
.ai_api_key_file .ai_endpoint
.as_ref() .clone()
.ok_or("--ai-api-key-file is required for a live AI provider")?; .unwrap_or_else(|| provider.endpoint().to_string());
let api_key = phoebus_executor::ai::load_api_key(key_path)?; let api_key = match (&cli.ai_api_key_file, provider.requires_key()) {
(Some(path), _) => Some(phoebus_executor::ai::load_api_key(path)?),
(None, true) => {
return Err(format!(
"--ai-api-key-file is required for provider `{}`",
provider.as_str()
)
.into());
}
// A self-hosted local model usually needs no key.
(None, false) => None,
};
let model = cli.ai_model.clone().unwrap_or_default(); let model = cli.ai_model.clone().unwrap_or_default();
let transport = phoebus_executor::ai::CurlTransport::new(&installer.exec, api_key); let transport = phoebus_executor::ai::CurlTransport::new(&installer.exec, api_key);
match phoebus_installer::ai_guide::generate_and_review( match phoebus_installer::ai_guide::generate_and_review_at(
&mut installer.config, &mut installer.config,
&facts, &facts,
provider, provider,
&endpoint,
&model, &model,
&transport, &transport,
) { ) {
@ -320,6 +366,12 @@ fn run() -> std::result::Result<ExitCode, Box<dyn std::error::Error>> {
} }
run_ai_guidance(&cli, &mut installer)?; run_ai_guidance(&cli, &mut installer)?;
// AI is mandatory to install; a deterministic no-AI run needs the explicit
// break-glass. Dry-run and plan modes are exempt.
if do_install && !installer.config.runtime.dry_run {
require_ai_for_install(&cli, resolve_provider(&cli, &installer.config)?)?;
}
if let Some(path) = &cli.save_config { if let Some(path) = &cli.save_config {
std::fs::write(path, installer.config.to_toml_string()?)?; std::fs::write(path, installer.config.to_toml_string()?)?;
println!("wrote {}", path.display()); println!("wrote {}", path.display());

View file

@ -100,6 +100,45 @@ fn invalid_value_is_refused() {
assert!(!out.status.success()); assert!(!out.status.success());
} }
#[test]
fn install_without_ai_is_refused() {
// Installing Phoebus requires a connected model.
let out = Command::new(bin())
.args(["--install", "--yes"])
.output()
.expect("run phoebus-installer");
assert!(!out.status.success());
let err = String::from_utf8_lossy(&out.stderr);
assert!(err.contains("requires a connected AI"), "{err}");
}
#[test]
fn no_ai_is_the_explicit_break_glass() {
// `--no-ai` passes the gate; the (incomplete) default config then stops
// before any disk is touched, with no AI requirement.
for flag in ["--no-ai", "--legacy"] {
let out = Command::new(bin())
.args(["--install", "--yes", flag])
.output()
.expect("run phoebus-installer");
let err = String::from_utf8_lossy(&out.stderr);
assert!(!err.contains("requires a connected AI"), "{flag}: {err}");
assert!(err.contains("configuration is incomplete"), "{flag}: {err}");
}
}
#[test]
fn local_provider_needs_no_key_at_the_gate() {
// A local provider satisfies the gate without --no-ai (it fails later at
// the incomplete config, not at the AI gate).
let out = Command::new(bin())
.args(["--install", "--yes", "--ai", "--ai-provider", "local"])
.output()
.expect("run phoebus-installer");
let err = String::from_utf8_lossy(&out.stderr);
assert!(!err.contains("requires a connected AI"), "{err}");
}
#[test] #[test]
fn no_ai_fallback_still_prints_a_plan() { fn no_ai_fallback_still_prints_a_plan() {
let out = Command::new(bin()) let out = Command::new(bin())