GitCorner

Code

ossartcraftcraftanything🌐
642d5a256791
//! AI backends, the agent loop and crews.
//!
//! The UI talks to this crate only through [`AiHub`] and [`Conversation`]: start a conversation,
//! send a message, then poll [`AgentEvent`]s every frame. All network and subprocess work happens
//! on background threads; nothing here ever blocks the caller (except the explicitly blocking
//! helpers `test_backend`, `list_models` and `check_reachability`, which the UI runs on a worker).
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]

pub mod agent;
pub mod anthropic;
pub mod cli_agents;
pub mod config;
pub mod context;
pub mod detect;
mod failure;
pub use craft_anything_engine::failure_log;
pub mod http;
pub mod key_tools;
pub mod keys;
pub mod model;
pub mod model_options;
pub mod model_tools;
pub mod openai;
mod pace;
pub mod price;
pub mod prompt;
pub mod providers;
pub mod rebuild;
pub mod ssh;
pub mod window;

pub use agent::FULL_TOOLS_BUDGET;
pub use cli_agents::models::{AgentModel, ModelContext};
pub use config::{AiConfig, BackendEntry, BackendOptions, Price, ToolList};
pub use failure::{FailureKind, TurnFailure};
pub use keys::KeyStore;
pub use model::Effort;

use crate::agent::{ApiConversation, EngineHost, LoopConfig, ModelSlot};
use crate::model::{ChatModel, Delta, Msg, Stop, TurnRequest, TurnResult};
use craft_anything_engine::{CancelToken, Engine, Settings};
use craft_anything_evidence::{ErrorCode, ToolError};
use craft_anything_platform::sync::Mutex;
use serde::{Deserialize, Serialize};
use std::path::PathBuf;
use std::sync::Arc;
use std::time::{Duration, Instant};

/// How long adding a server by its address waits to reach it.
pub const SERVER_CONNECT_WAIT: Duration = Duration::from_secs(15);
/// How long adding a server by its address waits for its models once it's reached: one still
/// starting, or loading a model before it answers, took longer than the 10 seconds it had (#1429).
pub const SERVER_ANSWER_WAIT: Duration = Duration::from_secs(60);

/// The chat models a server listed when [`AiHub::add_server`] refused to guess between them
/// (#1434): empty for any other error.
pub fn models_to_choose(e: &ToolError) -> Vec<String> {
    e.details
        .as_ref()
        .and_then(|d| d.get("choose_model"))
        .and_then(serde_json::Value::as_array)
        .map(|a| a.iter().filter_map(serde_json::Value::as_str).map(str::to_string).collect())
        .unwrap_or_default()
}

/// Kinds of backend. See `plan/05-ai-backends.md`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum BackendKind {
    Anthropic,
    Openai,
    Openrouter,
    /// Google AI Studio (a Gemini API key), through Gemini's OpenAI-compatible endpoint.
    Gemini,
    /// Ollama, LM Studio, llama.cpp, vLLM… (OpenAI-compatible HTTP).
    OpenaiCompatible,
    /// Claude Code, Codex, Gemini CLI, Hermes Agent, OpenCode… run as a subprocess with our MCP server.
    AgentCli,
}

impl BackendKind {
    pub fn title(self) -> &'static str {
        match self {
            BackendKind::Anthropic => "Anthropic (Claude API)",
            BackendKind::Openai => "OpenAI",
            BackendKind::Openrouter => "OpenRouter",
            BackendKind::Gemini => "Gemini (Google AI Studio)",
            BackendKind::OpenaiCompatible => "Local / OpenAI-compatible server",
            BackendKind::AgentCli => "Agent app (command line)",
        }
    }

    /// Models offered in a dropdown before a live list is fetched.
    pub fn suggested_models(self) -> &'static [&'static str] {
        match self {
            BackendKind::Anthropic => anthropic::MODELS,
            BackendKind::Openai => &[openai::OPENAI_DEFAULT_MODEL],
            BackendKind::Openrouter => openai::OPENROUTER_MODELS,
            BackendKind::Gemini => openai::GEMINI_MODELS,
            BackendKind::OpenaiCompatible => &[],
            BackendKind::AgentCli => {
                &["claude-code", "codex", "copilot", "grok", "gemini-cli", "opencode", "antigravity", "hermes", "maki", "aider", "dsh", "devin"]
            }
        }
    }

    /// A coding agent run as a program, rather than an HTTP API.
    pub fn is_harness(self) -> bool {
        match self {
            BackendKind::AgentCli => true,
            BackendKind::Anthropic | BackendKind::Openai | BackendKind::Openrouter | BackendKind::Gemini | BackendKind::OpenaiCompatible => false,
        }
    }

    pub fn needs_key(self) -> bool {
        matches!(self, BackendKind::Anthropic | BackendKind::Openai | BackendKind::Openrouter | BackendKind::Gemini)
    }
}

/// One configured backend (stored in `settings.ai`; secrets live in the OS keychain).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BackendConfig {
    /// User-chosen name, unique: "Claude", "Local Llama", "Codex on studio-mac".
    pub name: String,
    pub kind: BackendKind,
    /// Model id (API backends) or agent id (`claude-code`, `codex`, `gemini-cli`, `antigravity`, `hermes`, `opencode`…).
    pub model: String,
    /// Base URL for API backends (defaults per kind).
    #[serde(default)]
    pub base_url: Option<String>,
    /// SSH host alias for running an agent CLI or reaching a local-LLM server remotely.
    #[serde(default)]
    pub ssh_host: Option<String>,
    #[serde(default = "yes")]
    pub enabled: bool,
}

fn yes() -> bool {
    true
}

/// A new session id for OpenCode Go: random enough to tell installations apart, with no personal
/// data in it.
fn new_session_id() -> String {
    use std::time::{SystemTime, UNIX_EPOCH};
    let n = SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_nanos()).unwrap_or(0);
    format!("craft-{:x}-{:x}", std::process::id(), n)
}

/// Gives `cfg` this installation's OpenCode Go session id when one of its backends is OpenCode Go
/// and none is saved yet. Returns whether it did (#1225).
fn give_session_id(cfg: &mut AiConfig) -> bool {
    let blank = cfg.install_id.as_deref().is_none_or(|s| s.trim().is_empty());
    let has_go = cfg.backends.iter().any(|b| openai::is_opencode_go(b.config.base_url.as_deref().unwrap_or("")));
    if blank && has_go {
        cfg.install_id = Some(new_session_id());
        return true;
    }
    false
}

/// The OpenCode Go key from the environment, when the base URL is its own. A blank value counts as
/// unset, so the other name is still tried.
fn go_env_key(base: &str) -> Option<String> {
    if !openai::is_opencode_go(base) {
        return None;
    }
    ["OPENCODEGO_API_KEY", "OPENCODE_GO_API_KEY"].iter().filter_map(|v| std::env::var(v).ok()).find(|k| !k.trim().is_empty())
}

/// An API backend's own limit on a streamed answer, its `timeout_secs`; none uses the defaults
/// ([`http::stream_agent`]). A slow local model can need hours for a long answer (#1096); 0 is not a
/// limit anyone means.
fn stream_limit(options: &BackendOptions) -> Option<std::time::Duration> {
    options.timeout_secs.filter(|s| *s > 0).map(std::time::Duration::from_secs)
}

/// An OpenAI-compatible client, carrying OpenCode Go's session header when the base is its own.
fn compatible_client(name: &str, base: &str, key: Option<String>, model: &str, session: &str) -> openai::OpenAi {
    let mut o = openai::OpenAi::compatible(name, base, key, model);
    if openai::is_opencode_go(base) && !session.is_empty() {
        o.extra_headers.push((openai::OPENCODE_GO_SESSION_HEADER, session.to_string()));
    }
    o
}

/// Where OpenCode Go lists its models: the chat base ends in `/openai/v1`, while the list answers at
/// the same service root with `/v1` (https://opencode.ai/inference/go/v1/models).
/// Run a blocking request on a helper thread and wait for its answer, giving up as soon as `cancel`
/// is set. A request given up on ends by itself when its own time limits run out.
fn until_cancelled<T: Send + 'static>(cancel: &CancelToken, ask: impl FnOnce() -> Result<T, ToolError> + Send + 'static) -> Result<T, ToolError> {
    let (send, answer) = std::sync::mpsc::channel();
    std::thread::Builder::new()
        .name("ask-server".into())
        .spawn(move || {
            let _ = send.send(ask());
        })
        .map_err(|e| ToolError::internal(format!("Couldn't start asking the server: {e}")))?;
    loop {
        cancel.check()?;
        match answer.recv_timeout(Duration::from_millis(100)) {
            Ok(result) => return result,
            Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {}
            Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => return Err(ToolError::internal("Asking the server stopped without an answer.")),
        }
    }
}

/// A server on this computer or its network (Ollama, LM Studio, one reached over ssh): it costs
/// nothing and gets the small context budget, and Auto trims its builder's tools by its window. A
/// remote OpenAI-compatible service has a large context and a bill, as any other cloud API (#374).
pub fn runs_here(c: &BackendConfig) -> bool {
    let over_ssh = c.ssh_host.as_deref().is_some_and(|h| !h.trim().is_empty());
    c.kind == BackendKind::OpenaiCompatible && (over_ssh || c.base_url.as_deref().filter(|b| !b.trim().is_empty()).is_none_or(detect::on_this_network))
}

fn opencode_go_models_base(base: &str) -> String {
    let base = base.trim_end_matches('/');
    match base.strip_suffix("/openai/v1") {
        Some(root) => format!("{root}/v1"),
        None => base.to_string(),
    }
}

/// The reasoning levels OpenAI's API takes, which OpenAI-compatible services follow.
pub const OPENAI_EFFORTS: [Effort; 6] = [Effort::None, Effort::Minimal, Effort::Low, Effort::Medium, Effort::High, Effort::Xhigh];

/// The levels every Gemini model takes through its OpenAI-compatible API: `xhigh` is for one
/// model only, and `none` can't turn reasoning off on 2.5 Pro, 3 or 4 (Google's OpenAI
/// compatibility page). shortcut: not per model, so a model's extra level isn't offered;
/// add a per-model table if someone needs `none` or `xhigh` on Gemini.
pub const GEMINI_EFFORTS: [Effort; 4] = [Effort::Minimal, Effort::Low, Effort::Medium, Effort::High];

/// The effort levels an AI can be set to (Settings β†’ AI): every Claude level for the Claude API
/// and Claude Code, OpenAI's for the OpenAI-style APIs (#1813), none for the others.
pub fn effort_levels(config: &BackendConfig) -> &'static [Effort] {
    match config.kind {
        BackendKind::Anthropic => &Effort::ALL,
        // By adapter, not id: Claude Code is also saved as `claude`.
        BackendKind::AgentCli if cli_agents::adapter_for(&config.model).ids().contains(&"claude-code") => &Effort::ALL,
        BackendKind::Gemini => &GEMINI_EFFORTS,
        BackendKind::Openai | BackendKind::Openrouter | BackendKind::OpenaiCompatible => &OPENAI_EFFORTS,
        BackendKind::AgentCli => &[],
    }
}

/// The effort an AI thinks at: for Claude, the chosen level or high; for an OpenAI-style API,
/// the chosen level, since not every model there takes one, so nothing is sent until it's
/// chosen. `None` when no level is sent.
pub fn effort_in_use(config: &BackendConfig, options: Option<&BackendOptions>) -> Option<Effort> {
    let chosen = options.and_then(|o| o.effort);
    match effort_levels(config) {
        [] => None,
        levels if levels == Effort::ALL => Some(prompt::choose_effort(chosen)),
        levels => chosen.filter(|e| levels.contains(e)),
    }
}

/// The model an AI uses, when it can be chosen (Settings β†’ AI, #123): an API's own, or the one
/// a coding agent is asked for. `None` for an agent app that picks its own.
pub fn model_in_use(config: &BackendConfig, options: Option<&BackendOptions>) -> Option<String> {
    match config.kind {
        BackendKind::AgentCli if cli_agents::adapter_for(&config.model).has_model_catalog() => {
            Some(options.and_then(|o| o.cli_model.clone()).unwrap_or_else(|| format!("{} default", cli_agents::display_for(&config.model))))
        }
        BackendKind::AgentCli => cli_agents::adapter_for(&config.model).model_in_use(options),
        _ => Some(config.model.clone()),
    }
}

/// The variable that moves an agent app's own folder (its sign-in, settings and sessions), when
/// it has one: Claude Code's `CLAUDE_CONFIG_DIR`. `None` for the others, which
/// [`BackendOptions::config_dir`] doesn't apply to.
pub fn folder_var(config: &BackendConfig) -> Option<&'static str> {
    (config.kind == BackendKind::AgentCli).then(|| cli_agents::adapter_for(&config.model).folder_var()).flatten()
}

/// The backend that builds when none is named: the Builder role's choice while it's on, else an
/// agent app, else an API backend. The same rule as [`AiConfig::backend_for`] for
/// [`Role::Builder`], for a client that holds only the list (the app decides "can it build?"
/// with it, so its warning and Start never disagree).
pub fn default_builder<'a>(backends: &'a [BackendConfig], chosen: Option<&str>) -> Option<&'a BackendConfig> {
    let on = || backends.iter().filter(|b| b.enabled);
    chosen
        .and_then(|n| on().find(|b| b.name == n))
        .or_else(|| on().find(|b| b.kind == BackendKind::AgentCli))
        .or_else(|| on().find(|b| b.kind != BackendKind::AgentCli))
}

/// Whether `name` is a saved AI that is switched on. One saved but switched off is not set up:
/// it's offered again when found, so it can be turned on (#423).
pub fn is_on(backends: &[BackendConfig], name: &str) -> bool {
    backends.iter().any(|b| b.enabled && b.name == name)
}

/// The found AIs that aren't already set up and on.
pub fn leave_out_set_up(found: Vec<Detected>, backends: &[BackendConfig]) -> Vec<Detected> {
    found.into_iter().filter(|d| !is_on(backends, &d.suggestion.name)).collect()
}

/// What a backend does in a crew.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Role {
    Lead,
    Worker,
    Reviewer,
    Builder,
    /// Takes the original game's files out after the study, in Deep mode (only when chosen).
    Extractor,
}

/// Something that was found on this machine and can be added with one click.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Detected {
    pub suggestion: BackendConfig,
    /// Plain words: "Found Ollama running with 3 models", "Found ANTHROPIC_API_KEY".
    pub reason: String,
    /// True when a key is still needed before it works.
    pub needs_key: bool,
}

/// Events the UI renders, in order.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum AgentEvent {
    /// Streaming text from the assistant (append to the current message).
    TextDelta {
        text: String,
    },
    /// A short note on what it's doing ("Looking at the functions that mention 'percent'…").
    Status {
        text: String,
    },
    /// A line a program printed outside the conversation (its stderr), for logs: never part of
    /// the answer.
    Output {
        text: String,
    },
    ToolStarted {
        call_id: String,
        tool: String,
        input: serde_json::Value,
    },
    ToolFinished {
        call_id: String,
        tool: String,
        ok: bool,
        summary: String,
        evidence_id: Option<String>,
    },
    /// The agent wants to run a tool that needs the user's OK. Answer with [`Conversation::answer_consent`].
    ConsentNeeded {
        call_id: String,
        tool: String,
        title: String,
        explanation: String,
    },
    /// One assistant turn finished.
    TurnDone {
        backend: String,
        /// Every prompt token, cached ones included, as agent apps report them.
        input_tokens: u64,
        output_tokens: u64,
        /// The backend didn't report token counts attributable to this turn.
        #[serde(default)]
        tokens_unknown: bool,
        cost_usd: Option<f64>,
        /// `cost_usd` is the agent's own guess at API prices, not what a key was charged: a
        /// subscription may cover the whole of it.
        #[serde(default)]
        cost_is_estimate: bool,
    },
    Error {
        message: String,
        remediation: Option<String>,
        /// A log with everything known about the failure, to open and inspect.
        log: Option<std::path::PathBuf>,
    },
}

/// A chat with the agent about the current session.
pub trait Conversation: Send {
    fn send(&mut self, text: &str);
    /// Retry an interrupted turn. Stateless adapters resend `text`; a conversation that keeps
    /// its own history can continue it without appending the user's message again.
    fn retry(&mut self, text: &str) {
        let prompt = if self.session_id().is_some() { failure::CONTINUE_TURN } else { text };
        self.send(prompt);
    }
    /// Why the last turn failed, supplied by its protocol or process boundary. An unknown
    /// failure is never retried automatically. Cleared when the next turn starts.
    fn last_failure(&self) -> Option<TurnFailure> {
        None
    }
    /// A saved session to continue later, for agents that have one (agent CLIs).
    fn session_id(&self) -> Option<String> {
        None
    }
    /// The saved session the last message was to continue isn't on this computer (the project
    /// was started on another one, or in another folder): that message did nothing, and the next
    /// one starts a new session, which knows nothing of the old.
    fn session_lost(&self) -> bool {
        false
    }
    /// Drain new events (non-blocking).
    fn poll(&mut self) -> Vec<AgentEvent>;
    fn answer_consent(&mut self, call_id: &str, allow: bool);
    /// Refuse a tool without asking anyone: the model is told `why`, not that the person said no.
    fn refuse_consent(&mut self, call_id: &str, why: &str) {
        let _ = why;
        self.answer_consent(call_id, false);
    }
    fn stop(&mut self);
    fn is_busy(&self) -> bool;
}

/// A conversation tagged with its backend's name (compare mode).
pub type Labeled = (String, Box<dyn Conversation>);

/// Result of a backend test.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TestReport {
    pub backend: String,
    pub model: String,
    pub latency_ms: u64,
    pub reply: String,
    /// Only the coding agent's `--version` ran (`reply` is its first line): it's installed, but
    /// whether it's signed in, has a model and quota shows only when it gets a message (#48).
    #[serde(default)]
    pub version_only: bool,
    /// The coding agent's program that ran, which `reply` is the answer of.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub program: Option<String>,
    /// The saved program that couldn't be used, when `program` ran in its place (#721: an update
    /// moved it), so a passing test doesn't hide a setting that's out of date.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub saved_program_replaced: Option<String>,
}

/// Text kept in the journal for a user message (bounded).
pub(crate) fn journal_text(t: &str) -> String {
    t.chars().take(4000).collect()
}

/// A model reached through an ssh tunnel; the tunnel lives as long as the model.
struct Tunneled {
    inner: Box<dyn ChatModel>,
    _tunnel: ssh::Tunnel,
}

impl ChatModel for Tunneled {
    fn turn(&mut self, req: &TurnRequest<'_>, on_delta: &mut dyn FnMut(Delta), stop: &Stop) -> Result<TurnResult, ToolError> {
        self.inner.turn(req, on_delta, stop)
    }

    fn model(&self) -> String {
        self.inner.model()
    }

    fn context_window(&self) -> Option<window::Window> {
        self.inner.context_window()
    }
}

/// The tools this layer adds to the engine's (rebuild control), for
/// [`craft_anything_engine::Engine::shared`].
pub fn tools() -> Vec<craft_anything_engine::ToolSpec> {
    let mut v = rebuild::tools::specs();
    v.extend(key_tools::specs());
    v.extend(model_tools::specs());
    v.extend(model_options::specs());
    v
}

/// Entry point for the UI and CLI.
pub struct AiHub {
    pub engine: Arc<Engine>,
    settings_path: Option<PathBuf>,
    keys: KeyStore,
    /// Serializes a backend's key and configuration changes, so a save can't land after a remove
    /// has deleted the key and the backend. Held across a keychain call or a settings save, so a
    /// waiter is a job, not a stuck lock.
    backend_edits: Mutex<()>,
}

impl AiHub {
    pub fn new(engine: Arc<Engine>) -> Self {
        AiHub { engine, settings_path: None, keys: KeyStore::system(), backend_edits: Mutex::new(()) }
    }

    /// A hub with explicit settings file and key store (tests, portable installs).
    pub fn with_stores(engine: Arc<Engine>, settings_path: PathBuf, keys: KeyStore) -> Self {
        AiHub { engine, settings_path: Some(settings_path), keys, backend_edits: Mutex::new(()) }
    }

    fn settings_path(&self) -> PathBuf {
        self.settings_path.clone().unwrap_or_else(Settings::path)
    }

    /// Where a failed model turn writes its log: `logs/` beside the settings file, as an agent
    /// CLI's failures do (see [`failure_log`]).
    fn failure_logs(&self) -> Option<PathBuf> {
        self.settings_path().parent().map(failure_log::dir_in)
    }

    /// The current AI configuration. Never blocks on a running tool: if the session is busy the
    /// saved settings file is read instead.
    pub fn config(&self) -> AiConfig {
        match self.engine.try_session() {
            Some(s) => AiConfig::from_settings(&s.settings),
            None => AiConfig::from_settings(&Settings::load_from(&self.settings_path())),
        }
    }

    /// The configuration to change and save back. An [ai] section that can't be read is an error
    /// here, never the empty default, so a change can't save over it (#261).
    fn config_to_change(&self) -> Result<AiConfig, ToolError> {
        match self.engine.try_session() {
            Some(s) => AiConfig::from_table(&s.settings.ai),
            None => AiConfig::from_table(&Settings::load_from(&self.settings_path()).ai),
        }
    }

    /// Save the AI configuration into the settings file, then the session: a save that fails
    /// changes nothing, so the app never shows a backend or role that isn't saved.
    pub fn save_config(&self, cfg: &AiConfig) -> Result<(), ToolError> {
        let table = cfg.to_table()?;
        let mut s = self.engine.session();
        let mut next = s.settings.clone();
        next.ai = table;
        next.save_to(&self.settings_path())?;
        s.settings = next;
        Ok(())
    }

    /// Configured backends.
    pub fn backends(&self) -> Vec<BackendConfig> {
        self.config().backends.into_iter().map(|b| b.config).collect()
    }

    /// Look for keys, local servers and agent CLIs (runs quickly; network probes are bounded).
    /// Things already configured (by name) are left out.
    pub fn detect(&self) -> Vec<Detected> {
        leave_out_set_up(detect::detect_all(), &self.backends())
    }

    /// Why a coding agent people expect may not be found (only the Claude desktop app, say).
    pub fn detect_hints(&self) -> Vec<detect::DetectHint> {
        detect::hints()
    }

    /// Host aliases from `~/.ssh/config`, for the "run on another machine" picker.
    pub fn ssh_hosts(&self) -> Vec<String> {
        ssh::ssh_hosts()
    }

    /// The backend the person chose for `role` in Settings β†’ AI, while it's still enabled.
    pub fn chosen(&self, role: Role) -> Option<String> {
        let cfg = self.config();
        cfg.roles.get(config::role_key(role)).filter(|n| cfg.get(n).is_some_and(|b| b.config.enabled)).cloned()
    }

    /// Choose the backend for `role`; `None` goes back to its default (the builder: an agent app,
    /// else any AI backend; the extractor: none).
    pub fn set_role(&self, role: Role, name: Option<&str>) -> Result<(), ToolError> {
        let mut cfg = self.config_to_change()?;
        let role = config::role_key(role).to_string();
        match name {
            Some(n) if cfg.get(n).is_none() => {
                return Err(
                    ToolError::invalid(format!("No AI backend named {n:?}")).with_remediation("See `craft-anything-cli ai list`, or add one in Settings β†’ AI.")
                );
            }
            Some(n) => {
                cfg.roles.insert(role, n.to_string());
            }
            None => {
                cfg.roles.remove(&role);
            }
        }
        self.save_config(&cfg)
    }

    /// Add (or replace) a backend, storing its key in the keychain when given.
    pub fn add_backend(&self, cfg: BackendConfig, key: Option<String>) -> Result<(), ToolError> {
        self.add_backend_with(BackendEntry { config: cfg, options: BackendOptions::default() }, key)
    }

    /// Add an OpenAI-compatible server by its address: Ollama or LM Studio on another computer, or
    /// a hosted service with its key. It's added only when it answers with its models; without a
    /// model, a chat model it says is loaded (`/api/ps`) is used, else the only one it lists that
    /// can chat; when it lists several, the person chooses ([`models_to_choose`] reads them from
    /// the error). Returns the model. Anthropic's own
    /// address is added as an Anthropic backend, as its API isn't OpenAI's.
    pub fn add_server(&self, name: &str, address: &str, model: Option<&str>, key: Option<String>) -> Result<String, ToolError> {
        self.add_server_within(name, address, model, key, SERVER_ANSWER_WAIT, &CancelToken::default())
    }

    /// [`AiHub::add_server`], given up as soon as `cancel` is set, even while the server is still
    /// being asked for its models: a person can stop waiting for one that is slow to answer (#1429).
    pub fn add_server_until(&self, name: &str, address: &str, model: Option<&str>, key: Option<String>, cancel: &CancelToken) -> Result<String, ToolError> {
        self.add_server_within(name, address, model, key, SERVER_ANSWER_WAIT, cancel)
    }

    /// [`AiHub::add_server`], waiting `wait` for the server to list its models once reached.
    fn add_server_within(
        &self,
        name: &str,
        address: &str,
        model: Option<&str>,
        key: Option<String>,
        wait: Duration,
        cancel: &CancelToken,
    ) -> Result<String, ToolError> {
        let name = name.trim();
        let address = address.trim().trim_end_matches('/');
        if name.is_empty() {
            return Err(ToolError::invalid("A backend needs a name."));
        }
        if !(address.starts_with("http://") || address.starts_with("https://")) {
            return Err(ToolError::invalid(format!("{address:?} isn't a web address."))
                .with_remediation("Give the server's address, like http://192.168.1.20:11434/v1."));
        }
        let key = key.map(|k| k.trim().to_string()).filter(|k| !k.is_empty());
        let kind = if anthropic::is_anthropic_api(address) { BackendKind::Anthropic } else { BackendKind::OpenaiCompatible };
        let (asked_name, asked_address, asked_key) = (name.to_string(), address.to_string(), key.clone());
        let listed = until_cancelled(cancel, move || {
            if kind == BackendKind::Anthropic {
                anthropic::Anthropic::new(Some(&asked_address), asked_key.unwrap_or_default(), "").list_models(Duration::from_secs(10))
            } else {
                // OpenCode Go lists its models at /v1, not under the chat path a person would paste.
                let probe = if openai::is_opencode_go(&asked_address) { opencode_go_models_base(&asked_address) } else { asked_address };
                openai::OpenAi::compatible(&asked_name, &probe, asked_key, "").list_models_within(SERVER_CONNECT_WAIT, wait)
            }
        });
        let models = listed.map_err(|e| {
            if e.code == ErrorCode::Cancelled {
                return e;
            }
            // A server that took the request has the right address: it may still be starting, or
            // loading a model before it answers (#1429).
            if http::was_reached(&e) {
                let secs = wait.as_secs();
                return e.with_remediation(format!(
                    "The server was reached but didn't list its models within {secs} seconds. It may still be starting or loading a model: \
                     wait until it's ready, then add it again."
                ));
            }
            e.with_remediation(
                "Check the address (it usually ends in /v1), that the server is running and can be reached from this computer, and its key if it needs one.",
            )
        })?;
        // With no model named, one the server has loaded comes first: its `/models` may be a
        // download catalogue, and the first entry there may start a download and unload the
        // model in use (#1434).
        cancel.check()?;
        let loaded = || {
            if kind == BackendKind::Anthropic || openai::is_opencode_go(address) {
                return None;
            }
            detect::chat_model(&openai::OpenAi::compatible(name, address, key.clone(), "").loaded_models(Duration::from_secs(5)))
        };
        // Several chat models and none known to be loaded: which one is in use can't be told, and
        // the first may be one the server would download (#1434). The person picks; the list
        // goes in `details.choose_model` for the form to offer.
        let several = || {
            let chats = detect::chat_models(&models);
            if kind == BackendKind::Anthropic || chats.len() < 2 {
                return Ok(None);
            }
            let some = chats.iter().take(5).map(String::as_str).collect::<Vec<_>>().join(", ");
            let more = if chats.len() > 5 { ", …" } else { "" };
            Err(ToolError::new(ErrorCode::BadInput, format!("{address} lists {} chat models and doesn't say which one is loaded.", chats.len()))
                .with_remediation(format!(
                    "Choose the model to use ({some}{more}), then add it again: asking for one the server hasn't got may start a download."
                ))
                .with_details(serde_json::json!({ "choose_model": chats })))
        };
        let model = match model.map(str::trim).filter(|m| !m.is_empty()) {
            Some(m) => m.to_string(),
            None => loaded().map_or_else(several, |m| Ok(Some(m)))?.or_else(|| detect::chat_model(&models)).ok_or_else(|| {
                let reason = if models.is_empty() { "has no models yet" } else { "doesn't list a model that can chat" };
                ToolError::new(ErrorCode::NotFound, format!("{address} {reason}."))
                    .with_remediation("Load a chat model on the server first, or enter the name of a chat model you know is available.")
            })?,
        };
        let config = BackendConfig { name: name.to_string(), kind, model: model.clone(), base_url: Some(address.to_string()), ssh_host: None, enabled: true };
        self.add_backend(config, key)?;
        Ok(model)
    }

    /// Like [`AiHub::add_backend`], with options.
    pub fn add_backend_with(&self, entry: BackendEntry, key: Option<String>) -> Result<(), ToolError> {
        if entry.config.name.trim().is_empty() {
            return Err(ToolError::invalid("A backend needs a name."));
        }
        let mut cfg = self.config_to_change()?;
        if let Some(k) = key.filter(|k| !k.trim().is_empty()) {
            self.keys.set(&entry.config.name, k.trim())?;
        }
        cfg.upsert(entry);
        give_session_id(&mut cfg);
        self.save_config(&cfg)
    }

    /// Makes this installation's OpenCode Go session id and saves it, when a Go backend is set up
    /// and has none (#1225). Returns whether it saved one. The app and the CLI call this at startup,
    /// before any session lock is taken: a backend that never went through [`AiHub::add_backend`]
    /// (one from an older version, or one copied in) would otherwise send a new id every run, which
    /// OpenCode Go doesn't route efficiently.
    pub fn ensure_session_id(&self) -> Result<bool, ToolError> {
        let mut cfg = self.config_to_change()?;
        if !give_session_id(&mut cfg) {
            return Ok(false);
        }
        self.save_config(&cfg)?;
        Ok(true)
    }

    /// Turn a backend on or off; it keeps its settings and key. Returns false when there was no
    /// such backend.
    pub fn set_enabled(&self, name: &str, on: bool) -> Result<bool, ToolError> {
        let mut cfg = self.config_to_change()?;
        let Some(b) = cfg.backends.iter_mut().find(|b| b.config.name == name) else { return Ok(false) };
        b.config.enabled = on;
        self.save_config(&cfg)?;
        Ok(true)
    }

    /// The program an agent app runs (`None` or empty: found by its usual name, on PATH and in the
    /// usual install folders). Returns false when there was no such backend.
    pub fn set_command(&self, name: &str, command: Option<&str>) -> Result<bool, ToolError> {
        let command = command.map(str::trim).filter(|c| !c.is_empty());
        let mut cfg = self.config_to_change()?;
        let Some(b) = cfg.backends.iter_mut().find(|b| b.config.name == name) else { return Ok(false) };
        // A folder can't be started, and on a Mac an app is one (#467: the file picker returned
        // `Antigravity.app`). Another computer's path isn't looked at here.
        let local = b.config.ssh_host.as_deref().is_none_or(|h| h.trim().is_empty());
        if let Some(c) = command
            && local
            && std::path::Path::new(c).is_dir()
        {
            return Err(ToolError::invalid(format!("{c} is a folder, so it can't be the agent's program. On a Mac an app is a folder."))
                .with_remediation("Pick the agent's command-line program instead, such as `agy`, or clear the program to use the usual one."));
        }
        b.options.command = command.map(str::to_string);
        self.save_config(&cfg)?;
        Ok(true)
    }

    /// The folder an agent app keeps its sign-in, settings and sessions in ([`folder_var`]), so
    /// each AI can be another account (`None` or empty: its usual one). A full path or one under
    /// `~/`; over SSH it's a folder on that computer. Returns false when there was no such backend.
    pub fn set_config_dir(&self, name: &str, dir: Option<&str>) -> Result<bool, ToolError> {
        let dir = dir.map(str::trim).filter(|d| !d.is_empty());
        let mut cfg = self.config_to_change()?;
        let Some(b) = cfg.backends.iter_mut().find(|b| b.config.name == name) else { return Ok(false) };
        if let Some(d) = dir {
            if folder_var(&b.config).is_none() {
                return Err(ToolError::invalid(format!("{name} doesn't keep a folder of its own.")).with_remediation("A folder is for Claude Code."));
            }
            // A relative folder would move with whatever folder the agent is started in.
            let remote = b.config.ssh_host.as_deref().is_some_and(|h| !h.trim().is_empty());
            let full = d == "~" || d.starts_with("~/") || if remote { d.starts_with('/') } else { std::path::Path::new(d).is_absolute() };
            if !full {
                return Err(ToolError::invalid(format!("{d:?} isn't a full path."))
                    .with_remediation("Give the whole path, or one starting with ~/ for the home folder."));
            }
        }
        b.options.config_dir = dir.map(str::to_string);
        self.save_config(&cfg)?;
        Ok(true)
    }

    /// Each backend's options (an agent app's program and model…), by name.
    pub fn options(&self) -> std::collections::BTreeMap<String, BackendOptions> {
        self.config().backends.into_iter().map(|b| (b.config.name, b.options)).collect()
    }

    /// For each agent app on this computer whose saved program can't be used (an update moved it,
    /// #721), the program that runs in its place. It looks at the disk and PATH: call it on a worker.
    pub fn replaced_programs(&self) -> std::collections::BTreeMap<String, String> {
        self.config()
            .backends
            .into_iter()
            .filter(|b| b.config.kind == BackendKind::AgentCli && b.config.ssh_host.as_deref().is_none_or(|h| h.trim().is_empty()))
            .filter_map(|b| {
                let program = cli_agents::program_of(&b.config, &b.options).ok()?;
                cli_agents::replaced_program(&b.options, &program)?;
                Some((b.config.name, program))
            })
            .collect()
    }

    /// The model a backend uses: an API's model, or the one its agent is asked for. Returns
    /// false when there was no such backend.
    pub fn set_model(&self, name: &str, model: &str) -> Result<bool, ToolError> {
        let model = model.trim();
        if model.is_empty() {
            return Err(ToolError::invalid("Name a model."));
        }
        if self.config().get(name).is_some_and(|e| e.config.kind == BackendKind::AgentCli && cli_agents::adapter_for(&e.config.model).has_model_catalog()) {
            return self.set_agent_model(name, Some(model), None);
        }
        let mut cfg = self.config_to_change()?;
        let Some(b) = cfg.backends.iter_mut().find(|b| b.config.name == name) else { return Ok(false) };
        match b.config.kind {
            BackendKind::AgentCli => {
                // Ask the adapter, not the id: Claude Code is also saved as `claude`, and both, like
                // Codex, must mean "no model passed" when the choice is the default.
                let own_default = cli_agents::adapter_for(&b.config.model).offers_own_default();
                let clear = own_default && model == crate::anthropic::CLAUDE_CODE_DEFAULT;
                if model_options::supported(&b.config) && (clear || b.options.cli_model.as_deref() != Some(model)) {
                    b.options.cli_context = None;
                    b.options.cli_reasoning_effort = None;
                    b.options.effort = None;
                }
                b.options.cli_model = if clear { None } else { Some(model.to_string()) };
            }
            _ => b.config.model = model.to_string(),
        }
        self.save_config(&cfg)?;
        Ok(true)
    }

    /// How hard a backend thinks (`None`: the usual level again). Only the levels in
    /// [`effort_levels`] are taken. Returns false when there was no such backend.
    pub fn set_effort(&self, name: &str, effort: Option<Effort>) -> Result<bool, ToolError> {
        let mut cfg = self.config_to_change()?;
        let Some(b) = cfg.backends.iter_mut().find(|b| b.config.name == name) else { return Ok(false) };
        let levels = effort_levels(&b.config);
        if let Some(e) = effort.filter(|e| !levels.contains(e)) {
            let fix = match levels {
                [] => "Effort is for the Claude API, Claude Code and OpenAI-style APIs.".to_string(),
                levels => format!("Use one of: {}.", levels.iter().map(|l| l.as_str()).collect::<Vec<_>>().join(", ")),
            };
            return Err(ToolError::invalid(format!("{name} doesn't take the effort level {}.", e.as_str())).with_remediation(fix));
        }
        b.options.effort = effort;
        self.save_config(&cfg)?;
        Ok(true)
    }

    /// The request rate for a configured API backend. No rate means requests are not paced.
    pub fn requests_per_minute(&self, name: &str) -> Result<Option<u32>, ToolError> {
        Self::api_request_rate(&self.entry(name)?)
    }

    /// Change the rate for future conversations. Zero removes the pacing setting.
    pub fn set_requests_per_minute(&self, name: &str, rate: u32) -> Result<Option<u32>, ToolError> {
        let mut config = self.config_to_change()?;
        let entry = config.backends.iter_mut().find(|entry| entry.config.name == name).ok_or_else(|| {
            ToolError::invalid(format!("No AI backend named {name:?}")).with_remediation("See `craft-anything-cli ai list`, or add one in Settings β†’ AI.")
        })?;
        Self::api_request_rate(entry)?;
        let requested = Some(rate).filter(|rate| *rate != 0);
        if entry.options.requests_per_minute != requested {
            entry.options.requests_per_minute = requested;
            self.save_config(&config)?;
        }
        Ok(requested)
    }

    /// The tools a builder on this API backend is offered, and whether Auto here depends on the
    /// model's window (a local model) rather than offering every tool (a paid service).
    pub fn tool_list(&self, name: &str) -> Result<(ToolList, bool), ToolError> {
        let entry = self.entry(name)?;
        Self::api_only(&entry, "tool list")?;
        Ok((entry.options.tools.unwrap_or_default(), runs_here(&entry.config)))
    }

    /// Change the tools future builders on this backend are offered. Auto is saved as no setting.
    pub fn set_tool_list(&self, name: &str, list: ToolList) -> Result<ToolList, ToolError> {
        let mut config = self.config_to_change()?;
        let entry = config.backends.iter_mut().find(|entry| entry.config.name == name).ok_or_else(|| {
            ToolError::invalid(format!("No AI backend named {name:?}")).with_remediation("See `craft-anything-cli ai list`, or add one in Settings β†’ AI.")
        })?;
        Self::api_only(entry, "tool list")?;
        let requested = Some(list).filter(|l| *l != ToolList::Auto);
        if entry.options.tools != requested {
            entry.options.tools = requested;
            self.save_config(&config)?;
        }
        Ok(list)
    }

    fn api_only(entry: &BackendEntry, what: &str) -> Result<(), ToolError> {
        if entry.config.kind == BackendKind::AgentCli {
            return Err(ToolError::invalid(format!("Agent apps choose their own tools. Set a {what} on an API backend.")));
        }
        Ok(())
    }

    fn api_request_rate(entry: &BackendEntry) -> Result<Option<u32>, ToolError> {
        if entry.config.kind == BackendKind::AgentCli {
            return Err(ToolError::invalid("Agent apps send their own requests. Set a request rate on an API backend."));
        }
        Ok(entry.options.requests_per_minute.filter(|rate| *rate != 0))
    }

    /// The models a backend can be set to: the API's or registered agent's list.
    /// Empty for an agent app that picks its own. Blocking (bounded); run it off the UI thread.
    pub fn model_choices(&self, name: &str) -> Result<Vec<String>, ToolError> {
        let e = self.entry(name)?;
        if e.config.kind == BackendKind::AgentCli && cli_agents::adapter_for(&e.config.model).has_model_catalog() {
            return Ok(self.agent_models(&self.model_context(name)?)?.into_iter().map(|m| m.id).collect());
        }
        match (e.config.kind, model_in_use(&e.config, Some(&e.options))) {
            (_, None) => Ok(Vec::new()),
            (BackendKind::AgentCli, Some(_)) => cli_agents::adapter_for(&e.config.model).model_choices(&e.config, &e.options),
            _ => self.list_models(name),
        }
    }

    /// Capture the exact settings and working directory that model discovery will use.
    pub fn model_context(&self, name: &str) -> Result<ModelContext, ToolError> {
        // Capture both fields under one guard: a busy session is not an absent project,
        // and a concurrent settings change must not produce a mixed snapshot.
        let session = self.engine.try_session().ok_or_else(|| ToolError::invalid("The app is busy with another task. Try again in a moment."))?;
        let config = AiConfig::from_table(&session.settings.ai)?;
        let backend = config.get(name).cloned().ok_or_else(|| {
            ToolError::invalid(format!("No AI backend named {name:?}")).with_remediation("See `craft-anything-cli ai list`, or add one in Settings β†’ AI.")
        })?;
        Ok(ModelContext { backend, directory: session.project.as_ref().map(|p| p.root.clone()) })
    }

    /// Model metadata from an agent's own instance; no API-provider catalogue is substituted.
    pub fn agent_models(&self, context: &ModelContext) -> Result<Vec<AgentModel>, ToolError> {
        let e = &context.backend;
        cli_agents::adapter_for(&e.config.model).model_catalog(&e.config, &e.options, context.directory.as_deref(), &Stop::default())
    }

    /// Set an agent's model and thinking together. None uses OpenCode's default.
    /// Discovery happens before taking the session lock, and stale settings aren't overwritten.
    pub fn set_agent_model(&self, name: &str, model: Option<&str>, thinking: Option<Effort>) -> Result<bool, ToolError> {
        let context = self.model_context(name)?;
        self.set_agent_selection(&context, model, thinking)
    }

    /// Commit a picker selection only if its captured settings and project are still current.
    pub fn set_agent_selection(&self, context: &ModelContext, model: Option<&str>, thinking: Option<Effort>) -> Result<bool, ToolError> {
        let options = cli_agents::models::select(context, model, thinking)?;
        // Re-read and compare under the same lock as the save. A long catalogue lookup must
        // not overwrite another settings change that finished while it was running.
        let mut session = self.engine.session();
        config::save_agent_selection(&mut session, &self.settings_path(), context, options)
    }

    /// Context tiers and reasoning choices for a selected CLI model. Discovery is bounded and
    /// sends no model prompt; call off the UI thread.
    pub fn model_tuning(&self, name: &str) -> Result<model_options::ModelTuning, ToolError> {
        let entry = self.entry(name)?;
        if !model_options::supported(&entry.config) {
            return Err(ToolError::invalid("This backend does not offer CLI model options."));
        }
        cli_agents::acp_model_tuning(&entry.config, &entry.options, &Stop::default())
    }

    /// Save a model picker's two settings together, before replacing the in-memory config.
    pub fn set_model_options(&self, params: &model_options::SetModelOptions) -> Result<(), ToolError> {
        let mut config = self.config_to_change()?;
        model_options::update(&mut config, params)?;
        self.save_config(&config)
    }

    /// Remove a backend and its stored key. Returns false when there was no such backend.
    pub fn remove_backend(&self, name: &str) -> Result<bool, ToolError> {
        let edit = self.backend_edits.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
        edit.label("Backend key or removal");
        if self.config_to_change()?.get(name).is_none() {
            return Ok(false);
        }
        // The key first: if it can't be removed the backend stays, so this can be tried again. The
        // settings are read after it, because the keychain can take seconds and they may change.
        self.keys.delete(name)?;
        let mut cfg = self.config_to_change()?;
        let removed = cfg.remove(name);
        if removed {
            self.save_config(&cfg)?;
        }
        Ok(removed)
    }

    /// Some built-in asset provider has a key, so builds can generate assets.
    pub fn has_asset_keys(&self) -> bool {
        let providers = craft_anything_engines::assets::AssetProviders::built_in();
        providers.ids().into_iter().any(|id| self.has_asset_key(&providers, id))
    }

    /// Save an asset provider's key (keychain first). Returns where it went.
    pub fn set_asset_key(&self, provider: &str, key: &str) -> Result<&'static str, ToolError> {
        self.keys.set(&keys::asset_key_name(provider), key.trim())
    }

    pub fn remove_asset_key(&self, provider: &str) -> Result<(), ToolError> {
        self.keys.delete(&keys::asset_key_name(provider))
    }

    /// See [`keys::refresh_loaded`]: for callers that don't hold the session. It can wait for a
    /// running tool, so never call it from the UI thread or a tool.
    pub fn refresh_loaded_asset_keys(&self) {
        keys::refresh_loaded(&mut self.engine.session(), &self.keys);
    }

    /// The provider's key is stored or in its environment variable.
    pub fn has_asset_key(&self, providers: &craft_anything_engines::assets::AssetProviders, provider: &str) -> bool {
        providers.get(provider).is_some_and(|p| keys::asset_key(&self.keys, p.as_ref()).is_some())
    }

    /// True when a key is stored or in the environment (keys themselves are never returned).
    pub fn has_key(&self, name: &str) -> bool {
        self.config().get(name).is_some_and(|b| {
            let base = b.config.base_url.as_deref().unwrap_or("");
            if b.config.kind == BackendKind::OpenaiCompatible {
                // A local server holds no key; a hosted one is only ready once its key is somewhere.
                if openai::is_opencode_go(base) || providers::of_base(base).is_some() {
                    return self.keys.resolve(name, b.config.kind).is_some() || go_env_key(base).is_some() || providers::env_key(base).is_some();
                }
                return true;
            }
            !b.config.kind.needs_key() || self.keys.resolve(name, b.config.kind).is_some()
        })
    }

    /// Which backends have a key saved in the app, rather than only in the environment. The
    /// keychain can be slow, so the app reads this on a worker.
    pub fn stored_backend_keys(&self) -> std::collections::BTreeMap<String, bool> {
        self.config()
            .backends
            .iter()
            .filter(|b| b.config.kind != BackendKind::AgentCli)
            .map(|b| (b.config.name.clone(), self.keys.get(&b.config.name).is_some()))
            .collect()
    }

    /// Whether an API backend has a key saved in the app (not the environment); never the key.
    pub fn saved_backend_key(&self, name: &str) -> Result<bool, ToolError> {
        if self.entry(name)?.config.kind == BackendKind::AgentCli {
            return Err(ToolError::invalid("A coding agent keeps its own sign-in; there is no saved key to report here."));
        }
        Ok(self.keys.get(name).is_some())
    }

    /// Replace the key saved for an API backend (#1358). The backend and its options stay as they
    /// are; an older key in the system keychain must not keep winning, so the new one is read back.
    pub fn set_backend_key(&self, name: &str, key: &str) -> Result<(), ToolError> {
        let edit = self.backend_edits.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
        edit.label("Backend key or removal");
        if self.entry(name)?.config.kind == BackendKind::AgentCli {
            return Err(ToolError::invalid("A coding agent keeps its own sign-in; there is no key to save for it here."));
        }
        let key = key.trim();
        if key.is_empty() {
            return Err(ToolError::invalid("The key is empty."));
        }
        self.keys.set(name, key)?;
        // A keychain that refused the write can leave the fallback file holding the new key while
        // the keychain still wins with the old one. Reading back makes that a loud failure; trying
        // again after unlocking the keychain is safe.
        if self.keys.get(name).as_deref() != Some(key) {
            return Err(ToolError::new(ErrorCode::NoPermission, format!("The new key for {name} wasn't used: the system keychain still has an older one."))
                .with_remediation("Unlock the keychain, or delete this AI's entry in your keychain app, then save the key again."));
        }
        Ok(())
    }

    /// Forget the key saved for an API backend, so the one in the environment is used again. The
    /// backend itself stays.
    pub fn remove_backend_key(&self, name: &str) -> Result<(), ToolError> {
        let edit = self.backend_edits.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
        edit.label("Backend key or removal");
        if self.entry(name)?.config.kind == BackendKind::AgentCli {
            return Err(ToolError::invalid("A coding agent keeps its own sign-in; there is no saved key to forget here."));
        }
        self.keys.delete(name)
    }

    /// This installation's OpenCode Go session id. A backend added before one was made, or found
    /// from an environment key, has none saved: it gets one for the life of this process, as
    /// OpenCode Go refuses a request without the header (#1225). Reading never writes:
    /// `build_model` runs under the session lock, so a save there would deadlock or freeze the
    /// window.
    fn session_id(&self) -> String {
        static FOR_THIS_RUN: std::sync::OnceLock<String> = std::sync::OnceLock::new();
        self.config().install_id.clone().filter(|s| !s.trim().is_empty()).unwrap_or_else(|| FOR_THIS_RUN.get_or_init(new_session_id).clone())
    }

    fn entry(&self, name: &str) -> Result<BackendEntry, ToolError> {
        self.config().get(name).cloned().ok_or_else(|| {
            ToolError::invalid(format!("No AI backend named {name:?}")).with_remediation("See `craft-anything-cli ai list`, or add one in Settings β†’ AI.")
        })
    }

    fn key_for(&self, e: &BackendEntry) -> Result<String, ToolError> {
        let base = e.config.base_url.as_deref().unwrap_or("");
        self.keys.resolve(&e.config.name, e.config.kind).or_else(|| go_env_key(base).or_else(|| providers::env_key(base))).ok_or_else(|| {
            let var = if openai::is_opencode_go(base) {
                "OPENCODEGO_API_KEY or OPENCODE_GO_API_KEY"
            } else if e.config.kind == BackendKind::OpenaiCompatible {
                providers::of_base(base).map_or("an API key", |p| p.key_env)
            } else {
                keys::env_var(e.config.kind).unwrap_or("an API key")
            };
            ToolError::new(ErrorCode::BadSettings, format!("{} has no API key.", e.config.name))
                .with_remediation(format!("Add the key in Settings β†’ AI, or set {var}."))
        })
    }

    /// Build the model for an API backend (not agent CLIs).
    pub fn build_model(&self, e: &BackendEntry) -> Result<ModelSlot, ToolError> {
        let c = &e.config;
        let base = c.base_url.as_deref().filter(|b| !b.trim().is_empty());
        let mut tunnel = None;
        // Over ssh: forward a local port to the server as seen from the remote host.
        let tunneled_base = match (&c.ssh_host, c.kind) {
            (Some(host), BackendKind::OpenaiCompatible) if !host.trim().is_empty() => {
                let b = base.unwrap_or("http://127.0.0.1:11434/v1");
                let after = b.split("://").nth(1).unwrap_or(b);
                let hostport = after.split('/').next().unwrap_or_default();
                let path = after.get(hostport.len()..).unwrap_or("/v1");
                let (rh, rp) = hostport.rsplit_once(':').unwrap_or((hostport, "80"));
                let rp: u16 = rp.parse().map_err(|_| ToolError::invalid(format!("Bad port in {b}")))?;
                let t = ssh::open_tunnel(host, rh, rp)?;
                let url = format!("http://127.0.0.1:{}{path}", t.local_port);
                tunnel = Some(t);
                Some(url)
            }
            _ => None,
        };
        let base = tunneled_base.as_deref().or(base);
        let local = runs_here(c);
        let limit = stream_limit(&e.options);
        let sends_effort = effort_in_use(c, Some(&e.options)).is_some();
        let with_limit = |mut o: openai::OpenAi| {
            o.stream_limit = limit;
            o.sends_effort = sends_effort;
            Box::new(o) as Box<dyn ChatModel>
        };
        let model: Box<dyn ChatModel> = match c.kind {
            BackendKind::Anthropic => {
                let mut a = anthropic::Anthropic::new(base, self.key_for(e)?, &c.model);
                a.fallbacks = e.options.fallbacks_enabled.unwrap_or(true);
                a.stream_limit = limit;
                Box::new(a)
            }
            BackendKind::Openai => with_limit(openai::OpenAi::official(base, self.key_for(e)?, &c.model)),
            BackendKind::Openrouter => with_limit(openai::OpenAi::openrouter(base, self.key_for(e)?, &c.model)),
            BackendKind::Gemini => with_limit(openai::OpenAi::gemini(base, self.key_for(e)?, &c.model)),
            BackendKind::OpenaiCompatible => {
                let base = base.unwrap_or("http://127.0.0.1:11434/v1");
                let key = self.keys.get(&c.name).or_else(|| go_env_key(base).or_else(|| providers::env_key(base)));
                let mut o = compatible_client(&c.name, base, key, &c.model, &self.session_id());
                o.react = e.options.react_fallback.unwrap_or(false);
                o.asks_window = true;
                o.on_this_network = local;
                with_limit(o)
            }
            BackendKind::AgentCli => return Err(ToolError::invalid(format!("{} is an agent app, not an API backend.", c.name))),
        };
        let model = match tunnel {
            Some(t) => Box::new(Tunneled { inner: model, _tunnel: t }) as Box<dyn ChatModel>,
            None => model,
        };
        let model = match pace::gap(e.options.requests_per_minute) {
            Some(gap) => Box::new(pace::Paced { inner: model, backend: c.name.clone(), gap }) as Box<dyn ChatModel>,
            None => model,
        };
        Ok(ModelSlot {
            name: c.name.clone(),
            model,
            local,
            effort: e.options.effort,
            max_turns: e.options.max_turns.unwrap_or(agent::DEFAULT_MAX_TURNS),
            context_tokens: e.options.context_tokens.unwrap_or(0),
            tools: e.options.tools.unwrap_or_default(),
        })
    }

    /// Start a conversation with the lead backend (or the named one, while it is enabled).
    pub fn start(&self, backend: Option<&str>, beginner: bool) -> Result<Box<dyn Conversation>, ToolError> {
        let cfg = self.config();
        let first = match backend {
            Some(n) => self.entry(n)?,
            None => cfg
                .backend_for(Role::Lead)
                .cloned()
                .ok_or_else(|| ToolError::unavailable("No AI is set up yet.").with_remediation("Add one in Settings β†’ AI."))?,
        };
        if !first.config.enabled {
            return Err(ToolError::new(ErrorCode::BadSettings, format!("{} is turned off.", first.config.name))
                .with_remediation("Turn it on in Settings β†’ AI, or choose another backend for this conversation."));
        }
        if first.config.kind == BackendKind::AgentCli {
            return Ok(Box::new(cli_agents::SharedConversation::new(self.engine.clone(), self.keys.clone(), first, beginner)?));
        }
        let mut chain = vec![self.build_model(&first)?];
        for name in cfg.chain_from(&first.config.name).into_iter().skip(1) {
            if let Some(e) = cfg.get(&name).filter(|e| e.config.kind != BackendKind::AgentCli) {
                match self.build_model(e) {
                    Ok(slot) => chain.push(slot),
                    Err(err) => log::info!("fallback {name} skipped: {}", err.message),
                }
            }
        }
        let host = Arc::new(EngineHost(self.engine.clone()));
        let conv =
            ApiConversation::start(host, chain, LoopConfig { beginner, prices: cfg.prices.clone(), logs: self.failure_logs(), ..LoopConfig::default() })?;
        Ok(Box::new(conv))
    }

    /// A builder conversation on an API backend: our agent loop with the Build toolset (files and
    /// commands in the project) enabled from the start, and room for a long build. In Deep mode
    /// every toolset is enabled, so it can look inside the original with all of them.
    /// `transcript`: where the conversation is kept, and resumed from when it's there in this
    /// mode. `deep` is the run's mode, given by the caller: a tool that starts a build holds the
    /// session (#1102). `notes`: the build's notes folder, read between tool steps.
    pub fn start_builder(
        &self,
        entry: &BackendEntry,
        beginner: bool,
        transcript: Option<PathBuf>,
        deep: bool,
        notes: Option<PathBuf>,
    ) -> Result<ApiConversation, ToolError> {
        use craft_anything_engine::Toolset;
        let toolsets = if deep { self.engine.registry().toolsets() } else { vec![Toolset::Core, Toolset::Build] };
        self.start_loop(entry, &toolsets, LoopConfig { beginner, transcript, deep, lean_for_local: true, notes, ..LoopConfig::default() })
    }

    /// Start the asset extractor: our agent loop with the Build tools and the game archive tools.
    pub fn start_extractor(&self, entry: &BackendEntry, beginner: bool, transcript: Option<PathBuf>) -> Result<ApiConversation, ToolError> {
        use craft_anything_engine::Toolset;
        let cfg = LoopConfig { beginner, transcript, deep: true, ..LoopConfig::default() };
        self.start_loop(entry, &[Toolset::Core, Toolset::Build, Toolset::Formats], cfg)
    }

    /// Start one loop with these toolsets and `cfg`, which keeps its transcript and resumes it only
    /// in its mode; the prices and failure logs are the hub's.
    fn start_loop(&self, entry: &BackendEntry, toolsets: &[craft_anything_engine::Toolset], cfg: LoopConfig) -> Result<ApiConversation, ToolError> {
        let mut slot = self.build_model(entry)?;
        slot.max_turns = slot.max_turns.max(agent::BUILDER_MAX_TURNS);
        let host = Arc::new(EngineHost(self.engine.clone()));
        let cfg = LoopConfig { prices: self.config().prices.clone(), logs: self.failure_logs(), ..cfg };
        ApiConversation::start_with(host, vec![slot], cfg, toolsets.iter().copied().collect())
    }

    /// Start a conversation with whichever backend fills `role` in the crew.
    pub fn start_role(&self, role: Role, beginner: bool) -> Result<Box<dyn Conversation>, ToolError> {
        let cfg = self.config();
        let e = cfg.backend_for(role).ok_or_else(|| {
            ToolError::unavailable(format!("No backend is set for the {} role.", config::role_key(role)))
                .with_remediation("Choose one in Settings β†’ AI β†’ Roles.")
        })?;
        self.start(Some(&e.config.name), beginner)
    }

    /// Compare mode: the same question to two backends. Returns one conversation per backend,
    /// tagged by name; the caller sends the same text to both and shows them side by side.
    pub fn compare(&self, a: &str, b: &str, beginner: bool) -> Result<Vec<Labeled>, ToolError> {
        if a == b {
            return Err(ToolError::invalid("Pick two different backends to compare."));
        }
        Ok(vec![(a.to_string(), self.start(Some(a), beginner)?), (b.to_string(), self.start(Some(b), beginner)?)])
    }

    /// Live model list for a backend. Blocking (bounded); run it off the UI thread.
    pub fn list_models(&self, name: &str) -> Result<Vec<String>, ToolError> {
        let e = self.entry(name)?;
        let base = e.config.base_url.as_deref().filter(|b| !b.trim().is_empty());
        let t = Duration::from_secs(10);
        match e.config.kind {
            BackendKind::Anthropic => anthropic::Anthropic::new(base, self.key_for(&e)?, &e.config.model).list_models(t),
            BackendKind::Openai => openai::OpenAi::official(base, self.key_for(&e)?, &e.config.model).list_models(t),
            BackendKind::Openrouter => openai::OpenAi::openrouter(base, self.key_for(&e)?, &e.config.model).list_models(t),
            BackendKind::Gemini => openai::OpenAi::gemini(base, self.key_for(&e)?, &e.config.model).list_models(t),
            BackendKind::OpenaiCompatible => {
                if e.config.ssh_host.as_deref().is_some_and(|h| !h.trim().is_empty()) {
                    return Err(ToolError::unavailable("Listing models on a remote server isn't supported yet.").with_remediation("Type the model name."));
                }
                let b = base.unwrap_or("http://127.0.0.1:11434/v1");
                let key = self.keys.get(&e.config.name).or_else(|| go_env_key(b).or_else(|| providers::env_key(b)));
                if openai::is_opencode_go(b) {
                    // The chat base ends in /openai/v1; the model list answers at /v1 instead.
                    return compatible_client(&e.config.name, &opencode_go_models_base(b), key, "", "").list_models(t);
                }
                compatible_client(&e.config.name, b, key, "", "").list_models(t)
            }
            BackendKind::AgentCli => self.model_choices(name),
        }
    }

    /// Send a tiny request and time it; a coding agent checks its version and, when its local
    /// adapter can tell, sign-in, without a prompt (`version_only`). Blocking; run off the UI thread.
    pub fn test_backend(&self, name: &str) -> Result<TestReport, ToolError> {
        let e = self.entry(name)?;
        let start = Instant::now();
        if e.config.kind == BackendKind::AgentCli {
            let program = cli_agents::program_of(&e.config, &e.options)?;
            let p = match e.config.ssh_host.as_deref().filter(|h| !h.trim().is_empty()) {
                Some(h) => craft_anything_platform::Process::new("ssh").args(ssh::ssh_args(h, &[program.clone(), "--version".into()])),
                None => craft_anything_platform::Process::new(&program).arg("--version"),
            };
            let out = p.timeout(Duration::from_secs(15)).run_checked()?;
            let mut reply = out.stdout_text().lines().next().unwrap_or_default().trim().to_string();
            if e.config.ssh_host.as_deref().is_none_or(|host| host.trim().is_empty()) {
                let adapter = cli_agents::AgentAdapters::built_in().for_backend(&e.config.model, &e.options);
                match adapter.signed_in(&program) {
                    Some(true) => reply.push_str(" Β· signed in (model access is checked when you send a message)"),
                    Some(false) => {
                        return Err(ToolError::new(ErrorCode::BadSettings, format!("{} is installed but is not signed in.", e.config.name))
                            .with_remediation(adapter.sign_in_fix().unwrap_or_default()));
                    }
                    None => {}
                }
            }
            return Ok(TestReport {
                backend: e.config.name.clone(),
                model: e.config.model.clone(),
                latency_ms: start.elapsed().as_millis() as u64,
                reply,
                version_only: true,
                saved_program_replaced: crate::cli_agents::replaced_program(&e.options, &program),
                program: Some(program),
            });
        }
        let mut slot = self.build_model(&e)?;
        let stop = Stop::default();
        let (tx, rx) = std::sync::mpsc::channel();
        // A hard bound even if the server trickles bytes forever.
        std::thread::Builder::new()
            .name("ai-test".into())
            .spawn(move || {
                let msgs = req_parts();
                // The level the AI is set to, so the test sends what its conversations will.
                let req = TurnRequest { effort: prompt::choose_effort(slot.effort), ..req_owned(&msgs) };
                let r = slot.model.turn(&req, &mut |_| {}, &stop).map(|r| (r, slot.model.model()));
                let _ = tx.send(r);
            })
            .map_err(|e| ToolError::internal(e.to_string()))?;
        let (r, model) =
            rx.recv_timeout(Duration::from_secs(60)).map_err(|_| ToolError::new(ErrorCode::TimedOut, format!("{name} didn't answer within 60 s.")))??;
        Ok(TestReport {
            backend: e.config.name.clone(),
            model: if r.model.is_empty() { model } else { r.model },
            latency_ms: start.elapsed().as_millis() as u64,
            reply: r.message.text().trim().to_string(),
            version_only: false,
            program: None,
            saved_program_replaced: None,
        })
    }

    /// For `doctor`: is each enabled backend reachable? `(name, Ok(latency ms) | Err(reason))`.
    /// Probes run in parallel; the whole check is bounded to about 12 s.
    pub fn check_reachability(&self) -> Vec<(String, Result<u64, String>)> {
        let entries: Vec<BackendEntry> = self.config().enabled().cloned().collect();
        let (tx, rx) = std::sync::mpsc::channel();
        for (i, e) in entries.iter().enumerate() {
            let e = e.clone();
            let key = self.keys.resolve(&e.config.name, e.config.kind);
            let tx = tx.clone();
            let _ = std::thread::Builder::new().name("ai-reach".into()).spawn(move || {
                let _ = tx.send((i, reach(&e, key)));
            });
        }
        drop(tx);
        let deadline = Instant::now() + Duration::from_secs(12);
        let mut results: Vec<Option<Result<u64, String>>> = vec![None; entries.len()];
        while results.iter().any(Option::is_none) {
            match rx.recv_timeout(deadline.saturating_duration_since(Instant::now())) {
                Ok((i, r)) => {
                    if let Some(slot) = results.get_mut(i) {
                        *slot = Some(r);
                    }
                }
                Err(_) => break,
            }
        }
        entries.into_iter().zip(results).map(|(e, r)| (e.config.name, r.unwrap_or_else(|| Err("no answer in time".into())))).collect()
    }
}

fn req_parts() -> Vec<Msg> {
    vec![Msg::user_text("Reply with the single word: ready")]
}

fn req_owned(msgs: &[Msg]) -> TurnRequest<'_> {
    TurnRequest { system: "You are a connectivity check. Answer in one word.", messages: msgs, tools: &[], effort: Effort::High, max_tokens: 2048 }
}

fn reach(e: &BackendEntry, key: Option<String>) -> Result<u64, String> {
    let start = Instant::now();
    let t = Duration::from_secs(8);
    let base = e.config.base_url.as_deref().filter(|b| !b.trim().is_empty());
    let need =
        |k: Option<String>| k.ok_or_else(|| format!("no API key (set it in Settings β†’ AI or {})", keys::env_var(e.config.kind).unwrap_or("the environment")));
    let r: Result<(), String> = match e.config.kind {
        BackendKind::Anthropic => anthropic::Anthropic::new(base, need(key)?, &e.config.model).list_models(t).map(|_| ()).map_err(|x| x.message),
        BackendKind::Openai => openai::OpenAi::official(base, need(key)?, &e.config.model).list_models(t).map(|_| ()).map_err(|x| x.message),
        BackendKind::Openrouter => openai::OpenAi::openrouter(base, need(key)?, &e.config.model).list_models(t).map(|_| ()).map_err(|x| x.message),
        BackendKind::Gemini => openai::OpenAi::gemini(base, need(key)?, &e.config.model).list_models(t).map(|_| ()).map_err(|x| x.message),
        BackendKind::OpenaiCompatible | BackendKind::AgentCli if e.config.ssh_host.as_deref().is_some_and(|h| !h.trim().is_empty()) => {
            let host = e.config.ssh_host.clone().unwrap_or_default();
            craft_anything_platform::Process::new("ssh")
                .args(ssh::ssh_args(&host, &["true".to_string()]))
                .timeout(Duration::from_secs(10))
                .run_checked()
                .map(|_| ())
                .map_err(|x| x.message)
        }
        BackendKind::OpenaiCompatible => {
            let b = base.unwrap_or("http://127.0.0.1:11434/v1");
            let key = key.or_else(|| go_env_key(b).or_else(|| providers::env_key(b)));
            if openai::is_opencode_go(b) {
                // The list answers at /v1, not under the chat path's /openai/v1. A key is still
                // required here, so "reachable" never means "callable without one".
                let key = need(key)?;
                compatible_client(&e.config.name, &opencode_go_models_base(b), Some(key), "", "").list_models(t).map(|_| ()).map_err(|x| x.message)
            } else if !b.starts_with("https://") && !detect::port_open(b, Duration::from_millis(500)) {
                Err(format!("nothing is listening at {b}"))
            } else {
                // An open port isn't a model server: another program may hold it (#37).
                compatible_client(&e.config.name, b, key, &e.config.model, "").list_models(t).map(|_| ()).map_err(|x| x.message)
            }
        }
        BackendKind::AgentCli => match cli_agents::program_of(&e.config, &e.options) {
            Err(x) => Err(x.message),
            Ok(program) => {
                // A saved path that's gone (#721): PATH has nothing to do with it.
                let by_path = std::path::Path::new(&program).parent().is_some_and(|p| !p.as_os_str().is_empty());
                craft_anything_platform::which(&program)
                    .map(|_| ())
                    .ok_or_else(|| if by_path { format!("there's no program at {program}") } else { format!("{program} isn't on PATH") })
            }
        },
    };
    r.map(|_| start.elapsed().as_millis() as u64)
}

#[cfg(test)]
mod tests;