Compare commits

..

3 commits

Author SHA1 Message Date
32a124e3f9 docs: fix handoff numbering
Some checks are pending
ci / test (push) Waiting to run
2026-09-20 14:44:00 -07:00
f8b34635c7 docs: record the mandatory-AI gate, local provider and portals
Note the rebuilt appliance ISO (fec8e312) and the new desktop portals; add
Nix packaging as the top next task since it was deliberately not faked.
2026-09-20 14:43:34 -07:00
3a405dd1e7 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.
2026-09-20 14:41:53 -07:00
10 changed files with 258 additions and 26 deletions

View file

@ -7,6 +7,16 @@ Format: Keep a Changelog. Dates are UTC.
## Unreleased
### Changed
- **Installing Phoebus now requires an AI.** The installer refuses an install
with no provider unless the explicit break-glass `--no-ai` (alias `--legacy`,
or `PHOEBUS_NO_AI=1`) is used. A new `local` provider (Ollama/llama.cpp/
LM Studio) and `--ai-endpoint` support a model the user downloaded; no model
is shipped.
- Desktop installs now include `sys-apps/xdg-desktop-portal`,
`xdg-desktop-portal-gtk` and `xdg-desktop-portal-wlr`, so Flatpak and
Wayland apps get file choosers and screencast support.
### Added
- `sys` offline package commands: `sys install <name>`, `sys remove <name>`,
`sys search <query>` (plus the `remove_package`/`search_packages` typed

View file

@ -17,17 +17,20 @@ commit it. It should be short and current; use `git log` for detail.
## Next actions (in order)
1. **Physical-seat desktop**: run `/usr/local/bin/phoebus-session` on a real VT
1. **Nix packaging**: author a `sys-apps/nix` ebuild (Phoebus overlay) +
`nix-daemon.service`, wire it into the installer, and VM-verify. This is the
remaining piece of "Nix is built in"; it was deliberately not faked.
2. **Physical-seat desktop**: run `/usr/local/bin/phoebus-session` on a real VT
and check kitty, XWayland, the polkit agent, logout/reap and reboot
(`docs/DEVELOPMENT.md` -> "Physical VT / real-seat check").
2. **Matching signed binhost**: the official Gentoo binhost is OpenRC/hardened,
3. **Matching signed binhost**: the official Gentoo binhost is OpenRC/hardened,
so systemd/desktop packages compile from source. Publish (or point at) a
systemd/desktop binhost to raise binary reuse; verify with `emerge -pv`.
3. **Rollback gate**: implement Btrfs default-subvolume + ESP handling and pass
4. **Rollback gate**: implement Btrfs default-subvolume + ESP handling and pass
a detached-boot test before exposing `sys undo`.
4. **Live AI provider call**: exercise DeepSeek/OpenAI with a real 0600 key
file; the path is currently fixture-verified only.
5. **Desktop graphical login**: exercise a real logind seat.
5. **Live AI provider call**: exercise DeepSeek/OpenAI/local with a real 0600
key file; the path is currently fixture-verified only.
6. **Desktop graphical login**: exercise a real logind seat.
## Known blockers / risks

View file

@ -21,7 +21,8 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**.
| 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; no scheduling/publish/smoke test |
| 15 | Recovery environment | Later | recovery BLS entry generated; full recovery image not built |
| — | Rust TUI | Partial | ratatui UI with plan/ERASE and AI provider selection; not yet the default on all paths |
| — | AI-guided install optimization | Partial | DeepSeek/OpenAI providers, evidence-gated typed review, TUI opt-in; fixture-verified, no live call |
| — | AI-guided install optimization | Partial | DeepSeek/OpenAI/local providers, evidence-gated typed review, mandatory at install with `--no-ai` break-glass; fixture-verified, no live call |
| — | Nix as a built-in second lane | Next | `sys-apps/nix` Portage overlay + `nix-daemon`; installer wiring; not yet packaged |
| — | Git workflow + agent guide | Done | this `docs/` set, `.githooks/`, `scripts/` |
## Immediate next steps

View file

@ -285,9 +285,17 @@ the remaining step; no time estimate is claimed beyond the recorded ~26 min.
## Debian-Live installer appliance (actual ISO)
An appliance ISO was built **without root** by `installer/live/build.sh`
(Debian-Live 13.7 standard base + `/phoebus` overlay), SHA-256
(Debian-Live 13.7 standard base + `/phoebus` overlay). The full-install
evidence below was recorded with build
`c0105bc9a282fddcbefab42baa577ea99843060f00fa45a75bcbc8358186bfd5`.
The current build is
`fec8e312bfe641c423f2656970ae4271a1544b3a6107b407a8a29cb71f8850be`; it carries
the mandatory-AI install gate (`--no-ai`/`--legacy` break-glass), the `local`
model provider, and the desktop portals. It was **not** re-run through the full
install in this session (resource constraints); treat the earlier run as the
boot/install evidence and this as the current artifact.
Firmware boot (UEFI/OVMF, no `-kernel`; the ISO's own grub chain):
- auto-boots the live system on the serial console;

View file

@ -22,6 +22,9 @@ pub enum ProviderKind {
None,
DeepSeek,
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 {
@ -30,6 +33,7 @@ impl ProviderKind {
ProviderKind::None => "none",
ProviderKind::DeepSeek => "deepseek",
ProviderKind::OpenAi => "openai",
ProviderKind::Local => "local",
}
}
@ -39,16 +43,21 @@ impl ProviderKind {
"" | "none" | "no" | "off" | "without" => Some(ProviderKind::None),
"deepseek" => Some(ProviderKind::DeepSeek),
"openai" | "chatgpt" | "gpt" => Some(ProviderKind::OpenAi),
"local" | "ollama" | "llama" | "llamacpp" | "llama.cpp" | "lmstudio" | "lm-studio" => {
Some(ProviderKind::Local)
}
_ => 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 {
match self {
ProviderKind::None => "",
ProviderKind::DeepSeek => "https://api.deepseek.com/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::DeepSeek => "deepseek-chat",
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 {
!matches!(self, ProviderKind::None)
matches!(self, ProviderKind::DeepSeek | ProviderKind::OpenAi)
}
}
@ -327,16 +339,33 @@ pub fn complete_proposal(
model: &str,
facts: &SystemFacts,
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> {
if provider == ProviderKind::None {
return Err(AiError::ProviderUnavailable(
"no AI provider selected".into(),
));
}
if endpoint.trim().is_empty() {
return Err(AiError::ProviderUnavailable(
"no provider endpoint configured".into(),
));
}
facts.validate_no_forbidden()?;
let request = build_request(provider, model, facts);
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)?;
parse_proposal(&content)
}
@ -429,12 +458,36 @@ mod tests {
);
assert_eq!(ProviderKind::parse("continue without AI"), 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::None.endpoint().is_empty());
assert!(ProviderKind::Local
.endpoint()
.starts_with("http://127.0.0.1"));
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());
}
#[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]
fn request_has_no_secret_and_pins_the_schema() {
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",
"sys-auth/polkit",
"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()
@ -653,6 +658,15 @@ mod tests {
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]
fn desktop_none_has_no_x_use_block() {
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.
///
/// The API key is optional: a self-hosted local model usually needs none, while
/// DeepSeek/OpenAI require one.
pub struct CurlTransport<'a> {
exec: &'a Exec,
api_key: SecretString,
api_key: Option<SecretString>,
}
impl<'a> CurlTransport<'a> {
pub fn new(exec: &'a Exec, api_key: SecretString) -> Self {
exec.register_secret(&api_key);
pub fn new(exec: &'a Exec, api_key: Option<SecretString>) -> Self {
if let Some(key) = &api_key {
exec.register_secret(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
// 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!(
"url = \"{url}\"\n\
header = \"Content-Type: application/json\"\n\
header = \"Authorization: Bearer {key}\"\n\
{auth}\
data = \"@{path}\"\n\
silent\nshow-error\nfail-with-body\nmax-time = 120\n",
key = self.api_key.expose(),
path = request.path().display()
);
let spec = CommandSpec::new("ai", "query model", "curl")
@ -132,7 +140,7 @@ mod tests {
},
);
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
.send(
ProviderKind::OpenAi,
@ -155,4 +163,32 @@ mod tests {
// And the key is registered for redaction.
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 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_core::InstallConfig;
@ -54,6 +56,20 @@ pub fn generate_and_review(
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)]
mod tests {
use super::*;

View file

@ -101,6 +101,15 @@ struct Cli {
/// Print the system facts that would be sent to the model, then exit.
#[arg(long)]
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;
@ -145,8 +154,33 @@ fn resolve_provider(
.ai_provider
.as_deref()
.unwrap_or(config.ai.provider.as_str());
ProviderKind::parse(raw)
.ok_or_else(|| format!("unknown AI provider `{raw}` (use deepseek, openai or none)").into())
ProviderKind::parse(raw).ok_or_else(|| {
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
@ -181,17 +215,29 @@ fn run_ai_guidance(
);
eprintln!("{}", facts.render());
let key_path = cli
.ai_api_key_file
.as_ref()
.ok_or("--ai-api-key-file is required for a live AI provider")?;
let api_key = phoebus_executor::ai::load_api_key(key_path)?;
let endpoint = cli
.ai_endpoint
.clone()
.unwrap_or_else(|| provider.endpoint().to_string());
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 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,
&facts,
provider,
&endpoint,
&model,
&transport,
) {
@ -320,6 +366,12 @@ fn run() -> std::result::Result<ExitCode, Box<dyn std::error::Error>> {
}
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 {
std::fs::write(path, installer.config.to_toml_string()?)?;
println!("wrote {}", path.display());

View file

@ -100,6 +100,45 @@ fn invalid_value_is_refused() {
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]
fn no_ai_fallback_still_prints_a_plan() {
let out = Command::new(bin())