oxios_kernel/kernel_handle/

engine_api.rs

//! Engine API — LLM engine introspection + config writes + routing control.
//!
//! Provides access to the oxi-sdk model catalog (providers, models, search)
//! and write operations that persist to config.toml (model, API key, routing).
//!
//! Routing statistics (`RoutingStats`) are shared between this API and
//! `AgentRuntime` via an `Arc`, so model usage is recorded end-to-end.

use crate::config::OxiosConfig;
use crate::credential::CredentialStore;
use anyhow::Context;
use chrono::{DateTime, Utc};
use parking_lot::RwLock;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::fs;
use std::path::PathBuf;
use std::sync::Arc;

// ── Provider config persistence types ────────────────────────────────────────

/// Provider별 설정 (per-provider model list, sorting, custom endpoint).
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ProviderSettings {
    #[serde(default)]
    pub enabled: bool,
    #[serde(default)]
    pub sort_order: i32,
    #[serde(default)]
    pub custom_endpoint: Option<String>,
    #[serde(default)]
    pub models: ModelListSettings,
}

/// Model list configuration for a provider.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelListSettings {
    #[serde(default)]
    pub mode: ModelListMode,
    #[serde(default)]
    pub allow: Vec<String>,
    #[serde(default)]
    pub deny: Vec<String>,
}

impl Default for ModelListSettings {
    fn default() -> Self {
        Self {
            mode: ModelListMode::All,
            allow: vec![],
            deny: vec![],
        }
    }
}

/// Model list filtering mode.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(rename_all = "lowercase")]
pub enum ModelListMode {
    #[default]
    All,
    Allowlist,
    Denylist,
}

/// Definition for a custom (user-defined) provider.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CustomProviderDef {
    pub id: String,
    pub name: String,
    pub sdk_type: SdkType,
    pub base_url: String,
    #[serde(default)]
    pub api_key_env: Option<String>,
}

/// SDK protocol type for custom providers.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum SdkType {
    OpenAI,
    Anthropic,
    Google,
    #[serde(rename = "openai-compatible")]
    OpenAICompatible,
}

/// Persistent provider state (companion file alongside config.toml).
#[derive(Debug, Clone, Serialize, Deserialize)]
struct ProviderStateFile {
    #[serde(default)]
    providers: HashMap<String, ProviderSettings>,
    #[serde(default)]
    custom_providers: Vec<CustomProviderDef>,
}

// ── Routing types ─────────────────────────────────────────────────────────────

/// Snapshot of routing configuration (read-only API response).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RoutingConfigSnapshot {
    /// Whether automatic model routing is enabled.
    pub routing_enabled: bool,
    /// Whether cost-efficient models are preferred when routing.
    pub prefer_cost_efficient: bool,
    /// Ordered list of fallback models (tried left-to-right on primary failure).
    pub fallback_models: Vec<String>,
    /// Models excluded from automatic routing.
    pub excluded_models: Vec<String>,
}

/// Model usage statistics.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RoutingStatsSnapshot {
    /// Model ID → number of calls.
    pub model_calls: HashMap<String, u64>,
    /// Model ID → estimated total cost (USD).
    pub model_cost: HashMap<String, f64>,
    /// Total number of requests.
    pub total_requests: u64,
    /// Total estimated cost (USD).
    pub total_cost: f64,
}

/// Single fallback event record.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FallbackEvent {
    /// When the fallback occurred.
    pub timestamp: DateTime<Utc>,
    /// Model that was skipped/replaced.
    pub from_model: String,
    /// Model that was used instead.
    pub to_model: String,
    /// Reason for fallback (e.g. "rate_limit", "context_overflow", "error").
    pub reason: String,
    /// Whether the fallback succeeded (no further fallback needed).
    pub success: bool,
}

/// Request body for `PUT /api/engine/routing`.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RoutingUpdate {
    pub routing_enabled: Option<bool>,
    pub prefer_cost_efficient: Option<bool>,
    pub fallback_models: Option<Vec<String>>,
    pub excluded_models: Option<Vec<String>>,
}

// ── RoutingStats ─────────────────────────────────────────────────────────────

/// In-memory routing statistics, shared between `EngineApi` and `AgentRuntime`.
/// Uses simple RwLock for thread-safe reads/writes.
pub struct RoutingStats {
    calls: RwLock<HashMap<String, u64>>,
    costs: RwLock<HashMap<String, f64>>,
    /// Circular buffer of recent fallback events (max 200).
    fallbacks: RwLock<std::collections::VecDeque<FallbackEvent>>,
}

impl Default for RoutingStats {
    fn default() -> Self {
        Self {
            calls: RwLock::new(HashMap::new()),
            costs: RwLock::new(HashMap::new()),
            fallbacks: RwLock::new(std::collections::VecDeque::new()),
        }
    }
}

impl RoutingStats {
    /// Create a new stats tracker.
    pub fn new() -> Self {
        Self::default()
    }

    /// Record one model invocation.
    pub fn record_model_usage(&self, model_id: &str, cost_usd: f64) {
        let mut calls = self.calls.write();
        *calls.entry(model_id.to_string()).or_insert(0) += 1;
        if cost_usd > 0.0 {
            let mut costs = self.costs.write();
            *costs.entry(model_id.to_string()).or_insert(0.0) += cost_usd;
        }
    }

    /// Record a fallback event.
    ///
    /// Uses `VecDeque` so trimming is O(1) (`pop_front`) instead of the O(n)
    /// memmove that `Vec::drain(0..keep)` performs under the write lock.
    pub fn record_fallback(&self, event: FallbackEvent) {
        let mut fb = self.fallbacks.write();
        fb.push_back(event);
        while fb.len() > 200 {
            fb.pop_front();
        }
    }

    /// Get a snapshot of current stats.
    pub fn snapshot(&self) -> RoutingStatsSnapshot {
        let calls = self.calls.read();
        let costs = self.costs.read();
        let total_requests: u64 = calls.values().sum();
        let total_cost: f64 = costs.values().sum();
        RoutingStatsSnapshot {
            model_calls: calls.clone(),
            model_cost: costs.clone(),
            total_requests,
            total_cost,
        }
    }

    /// Get recent fallback events, newest first.
    pub fn fallback_history(&self, limit: usize) -> Vec<FallbackEvent> {
        let fb = self.fallbacks.read();
        fb.iter().rev().take(limit).cloned().collect()
    }
}

// ── Model cost estimation ────────────────────────────────────────────────────

/// Estimate cost in USD for a model given token usage.
/// Uses oxi-sdk's model_db for per-model pricing.
pub fn estimate_cost(model_id: &str, input_tokens: u64, output_tokens: u64) -> f64 {
    let entries = oxi_sdk::get_provider_models(model_id.split('/').next().unwrap_or(model_id));
    let entry = entries
        .iter()
        .find(|e| format!("{}/{}", e.provider, e.id) == model_id);
    match entry {
        Some(e) => {
            (e.cost_input * input_tokens as f64 / 1_000_000.0)
                + (e.cost_output * output_tokens as f64 / 1_000_000.0)
        }
        None => {
            // Fall back to a rough estimate for unknown models
            (0.003 * input_tokens as f64 / 1_000_000.0)
                + (0.015 * output_tokens as f64 / 1_000_000.0)
        }
    }
}

// ── Provider/Model response types ──────────────────────────────────────────

/// Provider category for UI grouping.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ProviderCategory {
    /// Major providers (Anthropic, OpenAI, Google).
    Major,
    /// Open / specialty providers (Groq, OpenRouter, DeepSeek, etc.).
    Open,
    /// Regional providers.
    Regional,
    /// Local / self-hosted providers.
    Local,
}

/// Static metadata for an LLM provider.
///
/// This table is the **single source of truth** for provider-facing
/// metadata in the Web UI. It enriches the dynamic list returned by
/// `oxi_sdk::get_providers()` with human-friendly labels, UI grouping,
/// and a flag for providers that should not be exposed to the Web
/// dashboard (e.g. those requiring non-API-key auth like AWS SigV4 or
/// OAuth, or region-specific endpoints).
///
/// New providers added to `oxi-sdk` automatically appear in the UI
/// with sensible fallbacks (`Open` category, derived display name)
/// even before they get an entry here.
#[derive(Debug, Clone, Copy)]
struct ProviderMeta {
    /// Canonical provider id (matches `oxi_sdk::get_providers()`).
    id: &'static str,
    /// Human-readable name shown in dropdowns and badges.
    display_name: &'static str,
    /// UI grouping for the provider selector.
    category: ProviderCategory,
    /// Whether to exclude from the Web UI providers list.
    /// Used for providers with non-standard auth (AWS SigV4, OAuth,
    /// account-scoped URLs) or that are region-specific duplicates.
    hidden: bool,
    /// Short description for tooltips / help text.
    description: &'static str,
    /// Primary environment variable name holding the API key.
    /// Empty string when the provider does not use a single env var
    /// (e.g. AWS Bedrock uses a credential chain).
    env_key: &'static str,
    /// Alternative ids that should resolve to this provider.
    /// Used so that an alias such as `aws-bedrock` matches the
    /// canonical `amazon-bedrock` entry.
    aliases: &'static [&'static str],
}

/// All provider metadata, in a single static table.
///
/// Order is for human readability only — the runtime lookup is O(n)
/// linear scan, which is fine for ~30 entries. If the table grows
/// past ~100 entries, swap to a `phf` or `once_cell` hash map.
const PROVIDER_META: &[ProviderMeta] = &[
    // ── Major (top 3) ──────────────────────────────────────────────
    ProviderMeta {
        id: "anthropic",
        display_name: "Anthropic",
        category: ProviderCategory::Major,
        hidden: false,
        description: "Claude models with extended thinking",
        env_key: "ANTHROPIC_API_KEY",
        aliases: &["anthropic"],
    },
    ProviderMeta {
        id: "openai",
        display_name: "OpenAI",
        category: ProviderCategory::Major,
        hidden: false,
        description: "GPT, o-series, and Codex models",
        env_key: "OPENAI_API_KEY",
        aliases: &["openai"],
    },
    ProviderMeta {
        id: "google",
        display_name: "Google Gemini",
        category: ProviderCategory::Major,
        hidden: false,
        description: "Gemini models with thinking and tool use",
        env_key: "GOOGLE_API_KEY",
        aliases: &["google"],
    },
    // ── Open / specialty (gateways + open-weight hosts) ────────────
    ProviderMeta {
        id: "groq",
        display_name: "Groq",
        category: ProviderCategory::Open,
        hidden: false,
        description: "Fast Llama, Mixtral, and Gemma inference",
        env_key: "GROQ_API_KEY",
        aliases: &["groq"],
    },
    ProviderMeta {
        id: "openrouter",
        display_name: "OpenRouter",
        category: ProviderCategory::Open,
        hidden: false,
        description: "Unified gateway to 200+ models",
        env_key: "OPENROUTER_API_KEY",
        aliases: &["openrouter"],
    },
    ProviderMeta {
        id: "deepseek",
        display_name: "DeepSeek",
        category: ProviderCategory::Open,
        hidden: false,
        description: "DeepSeek-V3 and DeepSeek-R1",
        env_key: "DEEPSEEK_API_KEY",
        aliases: &["deepseek"],
    },
    ProviderMeta {
        id: "mistral",
        display_name: "Mistral",
        category: ProviderCategory::Open,
        hidden: false,
        description: "Mistral and Codestral models",
        env_key: "MISTRAL_API_KEY",
        aliases: &["mistral"],
    },
    ProviderMeta {
        id: "xai",
        display_name: "xAI (Grok)",
        category: ProviderCategory::Open,
        hidden: false,
        description: "Grok models from xAI",
        env_key: "XAI_API_KEY",
        aliases: &["xai", "grok"],
    },
    ProviderMeta {
        id: "cerebras",
        display_name: "Cerebras",
        category: ProviderCategory::Open,
        hidden: false,
        description: "Ultra-fast open model inference",
        env_key: "CEREBRAS_API_KEY",
        aliases: &["cerebras"],
    },
    ProviderMeta {
        id: "fireworks",
        display_name: "Fireworks",
        category: ProviderCategory::Open,
        hidden: false,
        description: "Fast open-source model serving",
        env_key: "FIREWORKS_API_KEY",
        aliases: &["fireworks"],
    },
    ProviderMeta {
        id: "github-copilot",
        display_name: "GitHub Copilot",
        category: ProviderCategory::Open,
        hidden: false,
        description: "GitHub Copilot models (GPT-4, Claude)",
        env_key: "GITHUB_COPILOT_TOKEN",
        aliases: &["github-copilot", "copilot"],
    },
    ProviderMeta {
        id: "huggingface",
        display_name: "Hugging Face",
        category: ProviderCategory::Open,
        hidden: false,
        description: "Open model inference hub",
        env_key: "HUGGINGFACE_API_KEY",
        aliases: &["huggingface", "hf"],
    },
    ProviderMeta {
        id: "together",
        display_name: "Together AI",
        category: ProviderCategory::Open,
        hidden: false,
        description: "Open-source model hosting (Llama, Mixtral, ...)",
        env_key: "TOGETHER_API_KEY",
        aliases: &["together", "togetherai"],
    },
    ProviderMeta {
        id: "opencode",
        display_name: "OpenCode",
        category: ProviderCategory::Open,
        hidden: false,
        description: "OpenCode coding agent gateway",
        env_key: "",
        aliases: &["opencode"],
    },
    ProviderMeta {
        id: "perplexity",
        display_name: "Perplexity",
        category: ProviderCategory::Open,
        hidden: false,
        description: "Search-augmented answer models",
        env_key: "PERPLEXITY_API_KEY",
        aliases: &["perplexity"],
    },
    ProviderMeta {
        id: "cohere",
        display_name: "Cohere",
        category: ProviderCategory::Open,
        hidden: false,
        description: "Cohere Command and Embed models",
        env_key: "COHERE_API_KEY",
        aliases: &["cohere"],
    },
    // ── Regional (Chinese / Asian providers) ───────────────────────
    ProviderMeta {
        id: "minimax",
        display_name: "MiniMax",
        category: ProviderCategory::Regional,
        hidden: false,
        description: "MiniMax-M2.7, abab models",
        env_key: "MINIMAX_API_KEY",
        aliases: &["minimax"],
    },
    ProviderMeta {
        id: "moonshotai",
        display_name: "Moonshot AI (Kimi)",
        category: ProviderCategory::Regional,
        hidden: false,
        description: "Kimi models from Moonshot AI",
        env_key: "MOONSHOT_API_KEY",
        aliases: &["moonshotai", "moonshot", "kimi"],
    },
    ProviderMeta {
        id: "kimi-coding",
        display_name: "Kimi Coding",
        category: ProviderCategory::Regional,
        hidden: false,
        description: "Kimi Coding Plan — optimized for coding",
        env_key: "KIMI_CODING_API_KEY",
        aliases: &["kimi-coding"],
    },
    ProviderMeta {
        id: "zai",
        display_name: "Z.AI (GLM)",
        category: ProviderCategory::Regional,
        hidden: false,
        description: "Z.AI GLM models (coding plan)",
        env_key: "ZAI_API_KEY",
        aliases: &["zai"],
    },
    // ── Hidden in Web UI today; mapped for forward-compatibility ───
    // These providers are not exposed by `EngineHandle::providers()`
    // because they require non-standard auth or region-specific setup,
    // but listing them here means the metadata is already wired up if
    // a future change decides to surface them.
    ProviderMeta {
        id: "amazon-bedrock",
        display_name: "Amazon Bedrock",
        category: ProviderCategory::Open,
        hidden: true,
        description: "Multi-model via AWS Bedrock ConverseStream",
        env_key: "AWS_ACCESS_KEY_ID",
        aliases: &["amazon-bedrock", "aws-bedrock", "bedrock"],
    },
    ProviderMeta {
        id: "azure-openai-responses",
        display_name: "Azure OpenAI (Responses)",
        category: ProviderCategory::Open,
        hidden: true,
        description: "OpenAI models via Azure Cognitive Services",
        env_key: "AZURE_OPENAI_API_KEY",
        aliases: &["azure-openai-responses", "azure"],
    },
    ProviderMeta {
        id: "cloudflare-ai-gateway",
        display_name: "Cloudflare AI Gateway",
        category: ProviderCategory::Open,
        hidden: true,
        description: "Serverless AI via Cloudflare AI Gateway",
        env_key: "CLOUDFLARE_API_TOKEN",
        aliases: &["cloudflare-ai-gateway", "cf-ai-gateway"],
    },
    ProviderMeta {
        id: "cloudflare-workers-ai",
        display_name: "Cloudflare Workers AI",
        category: ProviderCategory::Open,
        hidden: true,
        description: "Serverless AI via Cloudflare Workers",
        env_key: "CLOUDFLARE_API_KEY",
        aliases: &["cloudflare-workers-ai", "cloudflare", "workers-ai"],
    },
    ProviderMeta {
        id: "google-vertex",
        display_name: "Google Vertex AI",
        category: ProviderCategory::Open,
        hidden: true,
        description: "Gemini via Google Cloud Vertex AI",
        env_key: "GOOGLE_APPLICATION_CREDENTIALS",
        aliases: &["google-vertex", "vertex"],
    },
    ProviderMeta {
        id: "minimax-cn",
        display_name: "MiniMax (China)",
        category: ProviderCategory::Regional,
        hidden: true,
        description: "MiniMax China region endpoint",
        env_key: "MINIMAX_CN_API_KEY",
        aliases: &["minimax-cn"],
    },
    ProviderMeta {
        id: "moonshotai-cn",
        display_name: "Moonshot AI (China)",
        category: ProviderCategory::Regional,
        hidden: true,
        description: "Kimi models — China region endpoint",
        env_key: "MOONSHOT_CN_API_KEY",
        aliases: &["moonshotai-cn", "moonshot-cn"],
    },
    ProviderMeta {
        id: "openai-codex",
        display_name: "OpenAI Codex",
        category: ProviderCategory::Open,
        hidden: true,
        description: "OpenAI Codex coding agent (Responses API)",
        env_key: "OPENAI_API_KEY",
        aliases: &["openai-codex"],
    },
    ProviderMeta {
        id: "opencode-go",
        display_name: "OpenCode Go",
        category: ProviderCategory::Open,
        hidden: true,
        description: "OpenCode Go Gateway",
        env_key: "OPENCODE_GO_API_KEY",
        aliases: &["opencode-go"],
    },
    ProviderMeta {
        id: "vercel-ai-gateway",
        display_name: "Vercel AI Gateway",
        category: ProviderCategory::Open,
        hidden: true,
        description: "Vercel AI Gateway",
        env_key: "VERCEL_API_KEY",
        aliases: &["vercel-ai-gateway", "vercel"],
    },
    ProviderMeta {
        id: "xiaomi",
        display_name: "Xiaomi MiMo",
        category: ProviderCategory::Regional,
        hidden: true,
        description: "Xiaomi MiMo models",
        env_key: "XIAOMI_API_KEY",
        aliases: &["xiaomi"],
    },
];

/// Look up metadata by canonical id or alias.
fn provider_meta(id: &str) -> Option<&'static ProviderMeta> {
    PROVIDER_META
        .iter()
        .find(|m| m.id == id || m.aliases.contains(&id))
}

fn provider_category(id: &str) -> ProviderCategory {
    provider_meta(id)
        .map(|m| m.category)
        .unwrap_or(ProviderCategory::Open)
}

/// Resolve a display name for a provider id.
///
/// Falls back to a Title-Cased id for unknown providers so that
/// newly added `oxi-sdk` providers still render acceptably until a
/// real entry lands in [`PROVIDER_META`].
fn provider_display_name(id: &str) -> String {
    provider_meta(id)
        .map(|m| m.display_name.to_string())
        .unwrap_or_else(|| fallback_display_name(id))
}

/// Render a fallback display name by splitting on `-` / `_` and
/// Title-Casing each segment. Examples:
///   `"kimi-coding"`   → `"Kimi Coding"`
///   `"some_id"`       → `"Some Id"`
///   `"openai"`        → `"Openai"`
fn fallback_display_name(id: &str) -> String {
    id.split(['-', '_'])
        .filter(|s| !s.is_empty())
        .map(|segment| {
            let mut chars = segment.chars();
            match chars.next() {
                Some(c) => c.to_uppercase().collect::<String>() + chars.as_str(),
                None => String::new(),
            }
        })
        .collect::<Vec<_>>()
        .join(" ")
}

/// Summary of an LLM provider.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ProviderInfo {
    /// Provider identifier (e.g. "anthropic", "openai").
    pub id: String,
    /// Human-readable display name.
    pub name: String,
    /// Category for UI grouping.
    pub category: ProviderCategory,
    /// Number of models available for this provider.
    pub model_count: usize,
    /// Whether an API key is currently configured.
    pub has_key: bool,
    /// Source of the API key: `"env"`, `"auth_store"`, `"config"`, or `"none"`.
    /// Used by the Web UI to determine whether the key is removable
    /// (env-var-sourced keys cannot be cleared via the API).
    #[serde(default)]
    pub key_source: String,
    /// Short description for tooltips / help text. Empty for unknown
    /// providers that have no entry in [`PROVIDER_META`].
    #[serde(default)]
    pub description: String,
    /// Primary environment variable name for the API key. Empty for
    /// providers that do not use a single env var (e.g. AWS Bedrock
    /// uses a credential chain rather than a single API key var).
    #[serde(default)]
    pub env_key: String,
}

/// Input modality for a model.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum InputModality {
    /// Text input.
    Text,
    /// Image input (vision).
    Image,
}

/// Summary of a model from the catalog.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ModelInfo {
    /// Full model ID: "provider/model-id".
    pub id: String,
    /// Human-readable model name.
    pub name: String,
    /// API protocol used by the model's provider.
    pub api: String,
    /// Provider name.
    pub provider: String,
    /// Whether this model supports reasoning/thinking.
    pub reasoning: bool,
    /// Supported input modalities.
    pub input: Vec<InputModality>,
    /// Maximum context window in tokens.
    pub context_window: u32,
    /// Maximum output tokens.
    pub max_tokens: u32,
    /// Cost per million input tokens (USD).
    pub cost_input: f64,
    /// Cost per million output tokens (USD).
    pub cost_output: f64,
    /// Cost per million cached read tokens (USD).
    pub cost_cache_read: f64,
    /// Cost per million cached write tokens (USD).
    pub cost_cache_write: f64,
}

impl From<&oxi_sdk::ModelEntry> for ModelInfo {
    fn from(entry: &oxi_sdk::ModelEntry) -> Self {
        Self {
            id: format!("{}/{}", entry.provider, entry.id),
            name: entry.name.to_string(),
            api: entry.api.to_string(),
            provider: entry.provider.to_string(),
            reasoning: entry.reasoning,
            input: entry
                .input
                .iter()
                .map(|m| match m {
                    oxi_sdk::InputModality::Text => InputModality::Text,
                    oxi_sdk::InputModality::Image => InputModality::Image,
                    _ => InputModality::Text,
                })
                .collect(),
            context_window: entry.context_window,
            max_tokens: entry.max_tokens,
            cost_input: entry.cost_input,
            cost_output: entry.cost_output,
            cost_cache_read: entry.cost_cache_read,
            cost_cache_write: entry.cost_cache_write,
        }
    }
}

impl From<&oxi_sdk::CatalogModelEntry> for ModelInfo {
    /// Build a [`ModelInfo`] from a live catalog entry (catalog port).
    ///
    /// Same fields as the [`ModelEntry`](oxi_sdk::ModelEntry) path; the
    /// catalog entry additionally reflects runtime models.dev refresh +
    /// user overrides when wired into the engine.
    fn from(entry: &oxi_sdk::CatalogModelEntry) -> Self {
        Self {
            id: format!("{}/{}", entry.provider, entry.model_id),
            name: entry.name.clone(),
            api: entry.protocol.as_str().to_string(),
            provider: entry.provider.clone(),
            reasoning: entry.reasoning,
            input: entry
                .input_modalities
                .iter()
                .map(|m| match m.as_str() {
                    "image" => InputModality::Image,
                    _ => InputModality::Text,
                })
                .collect(),
            context_window: entry.context_window,
            max_tokens: entry.max_tokens,
            cost_input: entry.cost_input,
            cost_output: entry.cost_output,
            cost_cache_read: entry.cost_cache_read,
            cost_cache_write: entry.cost_cache_write,
        }
    }
}

/// Current engine configuration + credential status + routing.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EngineConfigResponse {
    /// Currently configured default model.
    pub default_model: String,
    /// Whether an API key is set for the current provider.
    pub api_key_set: bool,
    /// Source of the API key (if any).
    pub api_key_source: Option<String>,
    /// Provider name extracted from default_model.
    pub provider: Option<String>,
    /// Current routing configuration.
    pub routing: RoutingConfigSnapshot,
    /// Role-based model routing config (RFC-032).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub role_routing: Option<crate::config::RoleRoutingConfig>,
    /// Default model for one-shot (QuickAsk) requests. None ⇒ falls back to
    /// `default_model`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quick_ask_model: Option<String>,
}

/// Result of an API key validation attempt.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ValidateKeyResult {
    /// Whether the key is valid.
    pub valid: bool,
    /// Provider that was validated.
    pub provider: String,
    /// Optional message (error detail or success note).
    pub message: Option<String>,
}

/// Response for provider config endpoint.
#[derive(Debug, Clone, Serialize)]
pub struct ProviderConfigResponse {
    pub provider: ProviderInfo,
    pub settings: ProviderSettings,
    pub models: Vec<String>,
}

/// Connection test result.
#[derive(Debug, Clone, Serialize)]
pub struct ConnectionCheckResult {
    pub success: bool,
    pub model: String,
    pub latency_ms: u64,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
}

// ── EngineApi ───────────────────────────────────────────────────────────────

/// Engine API facade — model catalog introspection + config writes + routing.
///
/// Holds a shared reference to the live config (behind `RwLock`) and the
/// path to config.toml so write operations can persist to disk.
/// Routing stats are shared with `AgentRuntime` via `Arc<RoutingStats>`.
///
/// When config writes change the model or API key, `EngineApi` rebuilds
/// `OxiosEngine` via [`EngineHandle`] so the runtime picks up the change
/// on the next agent execution (hot-swap, no restart required).
pub struct EngineApi {
    config: Arc<RwLock<OxiosConfig>>,
    config_path: PathBuf,
    routing_stats: Arc<RoutingStats>,
    /// Hot-swap handle — config writes rebuild `OxiosEngine` and swap it in.
    engine_handle: Arc<crate::engine::EngineHandle>,
    /// Per-provider config settings, backed by companion file `config.providers.toml`.
    provider_configs: parking_lot::RwLock<HashMap<String, ProviderSettings>>,
    /// Custom user-defined provider definitions.
    custom_providers: parking_lot::RwLock<Vec<CustomProviderDef>>,
}

impl EngineApi {
    /// Create a new EngineApi.
    ///
    /// - `config` — shared config store (backed by RwLock)
    /// - `config_path` — path to config.toml for persistence
    /// - `routing_stats` — shared stats tracker (shared with AgentRuntime)
    /// - `engine_handle` — hot-swap handle for live engine replacement
    pub fn new(
        config: Arc<RwLock<OxiosConfig>>,
        config_path: PathBuf,
        routing_stats: Arc<RoutingStats>,
        engine_handle: Arc<crate::engine::EngineHandle>,
    ) -> Self {
        let api = Self {
            config,
            config_path,
            routing_stats,
            engine_handle,
            provider_configs: parking_lot::RwLock::new(HashMap::new()),
            custom_providers: parking_lot::RwLock::new(Vec::new()),
        };
        // Load persisted provider state from companion file.
        if let Ok(state) = api.read_provider_state() {
            *api.provider_configs.write() = state.providers;
            *api.custom_providers.write() = state.custom_providers;
        }
        api
    }
    /// Get a reference to the engine handle.
    pub fn engine_handle(&self) -> &Arc<crate::engine::EngineHandle> {
        &self.engine_handle
    }

    /// Validate that a model ID is resolvable by the current engine.
    ///
    /// Checks the catalog→static resolution path (same as
    /// `agent_runtime.rs:503` and `AgentBuilder::build()`). Use this
    /// to reject unknown model IDs early — before the orchestrator
    /// wastes time on assess/crystallize for a model that can't stream.
    pub fn validate_model(&self, model_id: &str) -> Result<(), String> {
        self.engine_handle
            .get()
            .resolve_model(model_id)
            .map(|_| ())
            .map_err(|e| format!("Unknown model '{model_id}': {e}"))
    }
    /// RFC-032: Get the current role routing config (role → model mapping).
    pub fn role_routing(&self) -> crate::config::RoleRoutingConfig {
        self.config.read().engine.role_routing.clone()
    }

    /// RFC-032: Resolve the model ID for a given role, if configured.
    /// Reads the LIVE config under its shared RwLock so updates take
    /// effect immediately. Returns `None` when the role is not in
    /// the mapping.
    pub fn model_for_role(&self, role: &str) -> Option<String> {
        self.config
            .read()
            .engine
            .role_routing
            .roles
            .get(role)
            .cloned()
    }

    /// RFC-032: Update role routing config and persist to config.toml.
    pub fn set_role_routing(
        &self,
        role_routing: crate::config::RoleRoutingConfig,
    ) -> anyhow::Result<()> {
        let snapshot = {
            let mut cfg = self.config.write();
            cfg.engine.role_routing = role_routing;
            cfg.clone()
        };
        self.persist(&snapshot)?;
        tracing::info!("Role routing updated");
        Ok(())
    }

    // ── Read operations ────────────────────────────────────────────────

    /// List all available providers from the oxi-sdk catalog.
    ///
    /// Reads provider/model counts from the live catalog (runtime models.dev
    /// refresh + user overrides) when wired into the engine, falling back to
    /// the static registry otherwise.
    ///
    /// Filters out hidden/internal providers (those flagged with
    /// `hidden: true` in [`PROVIDER_META`]) and augments each entry
    /// with credential status, display name, and description.
    ///
    /// Providers without a [`PROVIDER_META`] entry are shown by
    /// default — a new provider landing in `oxi-sdk` should be
    /// available to users even before its metadata is added here.
    pub fn providers(&self) -> Vec<ProviderInfo> {
        let catalog = self.engine_handle.get().oxi().catalog().clone();
        let use_catalog = catalog.model_count_sync() > 0;
        let all: Vec<String> = if use_catalog {
            catalog.list_providers_sync()
        } else {
            oxi_sdk::get_providers()
                .into_iter()
                .map(|s| s.to_string())
                .collect()
        };

        // Hoist the read-lock out of the per-provider closure: the previous
        // implementation took the lock once per provider (~30 times) and
        // re-read the same api_key each time. One read + clone is enough.
        let api_key_override = {
            let cfg = self.config.read();
            cfg.engine
                .api_key
                .as_deref()
                .filter(|k| !k.is_empty())
                .map(str::to_owned)
        };
        all.into_iter()
            .filter(|p| provider_meta(p).map(|m| !m.hidden).unwrap_or(true))
            .map(|p| {
                let model_count = if use_catalog {
                    catalog.list_models_sync(&p).len()
                } else {
                    oxi_sdk::get_provider_models(&p).len()
                };
                let resolved = CredentialStore::resolve(&p, api_key_override.as_deref());
                let has_key = resolved.is_some();
                let key_source = resolved
                    .map(|(_, src)| match src {
                        crate::credential::CredentialSource::EnvVar => "env",
                        crate::credential::CredentialSource::Config => "config",
                        crate::credential::CredentialSource::OxiAuthStore => "auth_store",
                    })
                    .unwrap_or("none")
                    .to_string();
                let meta = provider_meta(&p);
                ProviderInfo {
                    id: p.clone(),
                    name: provider_display_name(&p),
                    category: provider_category(&p),
                    model_count,
                    has_key,
                    key_source,
                    description: meta.map(|m| m.description.to_string()).unwrap_or_default(),
                    env_key: meta.map(|m| m.env_key.to_string()).unwrap_or_default(),
                }
            })
            .collect()
    }

    /// List models for a given provider, optionally filtered by a query.
    ///
    /// Reads from the live catalog (runtime models.dev refresh + user
    /// overrides) when wired into the engine, falling back to the static
    /// registry (embedded snapshot) otherwise.
    pub fn models(&self, provider: &str, query: Option<&str>) -> Vec<ModelInfo> {
        let catalog = self.engine_handle.get().oxi().catalog().clone();
        let live = catalog.list_models_sync(provider);
        let models: Vec<ModelInfo> = if !live.is_empty() {
            live.iter().map(ModelInfo::from).collect()
        } else {
            oxi_sdk::get_provider_models(provider)
                .iter()
                .map(ModelInfo::from)
                .collect()
        };
        models
            .into_iter()
            .filter(|m| !m.name.contains("latest"))
            .filter(|m| {
                if let Some(q) = query {
                    let q = q.to_lowercase();
                    m.name.to_lowercase().contains(&q)
                        || m.id.to_lowercase().contains(&q)
                        || m.provider.to_lowercase().contains(&q)
                } else {
                    true
                }
            })
            .collect()
    }

    /// Search models across all providers.
    ///
    /// Uses the live catalog's `search_sync` when available, else the static
    /// registry.
    pub fn search_models(&self, query: &str) -> Vec<ModelInfo> {
        let catalog = self.engine_handle.get().oxi().catalog().clone();
        let live = catalog.search_sync(query);
        if !live.is_empty() {
            live.iter().map(ModelInfo::from).collect()
        } else {
            oxi_sdk::search_models(query)
                .into_iter()
                .map(ModelInfo::from)
                .collect()
        }
    }

    /// Get the current engine configuration + credential status + routing.
    pub fn config(&self) -> EngineConfigResponse {
        let cfg = self.config.read();
        let provider =
            CredentialStore::provider_from_model(&cfg.engine.default_model).map(|s| s.to_string());
        let api_key_source = provider.as_deref().and_then(|p| {
            CredentialStore::resolve(p, cfg.api_key().as_deref()).map(|(_, src)| {
                match src {
                    crate::credential::CredentialSource::EnvVar => "env",
                    crate::credential::CredentialSource::Config => "config",
                    crate::credential::CredentialSource::OxiAuthStore => "auth_store",
                }
                .to_string()
            })
        });
        let api_key_set = provider
            .as_deref()
            .map(|p| CredentialStore::has_credential(p, cfg.api_key().as_deref()))
            .unwrap_or(false);

        let role_routing = if cfg.engine.role_routing.roles.is_empty() {
            None
        } else {
            Some(cfg.engine.role_routing.clone())
        };

        EngineConfigResponse {
            default_model: cfg.engine.default_model.clone(),
            api_key_set,
            api_key_source,
            provider,
            routing: RoutingConfigSnapshot {
                routing_enabled: cfg.engine.routing_enabled,
                prefer_cost_efficient: cfg.engine.prefer_cost_efficient,
                fallback_models: cfg.engine.fallback_models.clone(),
                excluded_models: cfg.engine.excluded_models.clone(),
            },
            role_routing,
            quick_ask_model: cfg.engine.quick_ask_model.clone(),
        }
    }

    pub fn routing_stats_snapshot(&self) -> RoutingStatsSnapshot {
        self.routing_stats.snapshot()
    }

    /// Get recent fallback history.
    pub fn fallback_history(&self, limit: usize) -> Vec<FallbackEvent> {
        self.routing_stats.fallback_history(limit)
    }

    // ── Write operations ───────────────────────────────────────────────

    /// Set the default model in config.toml.
    ///
    /// Updates both the in-memory config and the on-disk file, then
    /// hot-swaps the runtime engine so the next agent execution uses the new model.
    pub fn set_model(&self, model_id: &str) -> anyhow::Result<()> {
        // Validate BEFORE persisting/swapping: reject unknown models and
        // unconfigured providers so the Web UI's "switch succeeded" is truthful.
        // This prevents the divergence where a bad model ID was silently
        // accepted at swap time and only surfaced as "Model not found" at the
        // execute phase — after interview/crystallize had already run.
        {
            let engine = self.engine_handle.get();
            let model = engine
                .resolve_model(model_id)
                .with_context(|| format!("Unknown model '{model_id}'"))?;
            engine.create_provider(&model.provider).with_context(|| {
                format!(
                    "Provider '{}' is not configured for '{model_id}'",
                    model.provider
                )
            })?;
        }
        let snapshot = {
            let mut cfg = self.config.write();
            cfg.engine.default_model = model_id.to_string();
            cfg.clone()
        };
        // Persist outside the write lock — synchronous fs::write under the
        // lock would serialize every reader (providers/config/routing_stats).
        self.persist(&snapshot)?;
        tracing::info!(model = %model_id, "Default model updated in config");
        self.rebuild_and_swap();
        Ok(())
    }

    /// Set the default model for one-shot (QuickAsk) requests.
    ///
    /// Unlike `set_model`, this does NOT validate the model or hot-swap the
    /// runtime — it is a pure config value. The one-shot WS message carries
    /// it as `model` → `model_override`, which the agent runtime validates at
    /// execute time (`agent_runtime.rs:481-484`).
    pub fn set_quick_ask_model(&self, model_id: Option<&str>) -> anyhow::Result<()> {
        let snapshot = {
            let mut cfg = self.config.write();
            cfg.engine.quick_ask_model = model_id.map(String::from);
            cfg.clone()
        };
        self.persist(&snapshot)?;
        tracing::info!(model = ?model_id, "QuickAsk model updated in config");
        Ok(())
    }

    /// Set an API key for a provider.
    ///
    /// Stores the key via CredentialStore (→ ~/.oxi/auth.json) and also
    /// updates config.toml's `[engine].api_key` when the provider matches
    /// the current default model. Hot-swaps the runtime engine afterward.
    pub fn set_api_key(&self, provider: &str, key: &str) -> anyhow::Result<()> {
        CredentialStore::store(provider, key)?;

        // Acquire the write lock up-front and do the provider-match check and
        // the assignment atomically. The previous read-lock-then-write-lock
        // sequence was a TOCTOU: another writer could change `default_model`
        // between the check and the assignment, leaving an api_key stored
        // against the wrong provider.
        let snapshot = {
            let mut cfg = self.config.write();
            let matches = CredentialStore::provider_from_model(&cfg.engine.default_model)
                .is_some_and(|current_provider| current_provider == provider);
            if matches {
                cfg.engine.api_key = Some(key.to_string());
                Some(cfg.clone())
            } else {
                None
            }
        };
        if let Some(snap) = snapshot {
            // Persist outside the lock (see set_model).
            self.persist(&snap)?;
        }
        tracing::info!(provider = %provider, "API key stored");
        self.rebuild_and_swap();
        Ok(())
    }

    /// Clear an API key for a provider.
    ///
    /// Removes the key from config.toml's `[engine].api_key` (when the
    /// provider matches the current default model) and rebuilds the engine
    /// so the credential is dropped from the running process. The key in
    /// `~/.oxi/auth.json` must be removed separately via `CredentialStore::delete`.
    pub fn clear_api_key(&self, provider: &str) -> anyhow::Result<()> {
        let snapshot = {
            let mut cfg = self.config.write();
            let matches = CredentialStore::provider_from_model(&cfg.engine.default_model)
                .is_some_and(|current_provider| current_provider == provider);
            if matches {
                cfg.engine.api_key = None;
                Some(cfg.clone())
            } else {
                None
            }
        };
        if let Some(snap) = snapshot {
            self.persist(&snap)?;
        }
        tracing::info!(provider = %provider, "API key cleared from config");
        self.rebuild_and_swap();
        Ok(())
    }

    /// Delete a provider's API key entirely.
    ///
    /// Removes the credential from both the auth store (`~/.oxi/auth.json`)
    /// and `config.toml` (when the provider matches the current default).
    /// Hot-swaps the runtime engine so the credential is dropped immediately.
    ///
    /// Note: keys sourced from environment variables (`OXIOS_<PROVIDER>_API_KEY`
    /// or provider-native vars) cannot be removed via this method — they persist
    /// as long as the env var is set. The caller should check the credential
    /// source before offering a "remove" action.
    pub fn delete_api_key(&self, provider: &str) -> anyhow::Result<()> {
        CredentialStore::delete(provider)?;
        // Also clear from config.toml if this is the default provider.
        let snapshot = {
            let mut cfg = self.config.write();
            let matches = CredentialStore::provider_from_model(&cfg.engine.default_model)
                .is_some_and(|current_provider| current_provider == provider);
            if matches {
                cfg.engine.api_key = None;
                Some(cfg.clone())
            } else {
                None
            }
        };
        if let Some(snap) = snapshot {
            self.persist(&snap)?;
        }
        tracing::info!(provider = %provider, "API key deleted from credential store");
        self.rebuild_and_swap();
        Ok(())
    }

    /// Update provider options in config.toml.
    ///
    /// Persists the options and makes them available for the next agent run.
    /// They are passed through to `AgentLoopConfig::provider_options`.
    pub fn set_provider_options(&self, opts: &oxi_sdk::ProviderOptions) -> anyhow::Result<()> {
        let snapshot = {
            let mut cfg = self.config.write();
            cfg.engine.provider_options = Some(opts.clone());
            cfg.clone()
        };
        self.persist(&snapshot)?;
        tracing::info!("Provider options updated and persisted");
        // No engine rebuild needed — provider_options are per-request,
        // picked up from config on the next agent run.
        Ok(())
    }

    /// Update routing configuration in config.toml.
    ///
    /// Only the fields provided in `update` are changed; others are left untouched.
    /// Changes are persisted to disk immediately.
    pub fn set_routing(&self, update: RoutingUpdate) -> anyhow::Result<()> {
        let snapshot = {
            let mut cfg = self.config.write();
            if let Some(v) = update.routing_enabled {
                cfg.engine.routing_enabled = v;
            }
            if let Some(v) = update.prefer_cost_efficient {
                cfg.engine.prefer_cost_efficient = v;
            }
            if let Some(v) = update.fallback_models {
                cfg.engine.fallback_models = v;
            }
            if let Some(v) = update.excluded_models {
                cfg.engine.excluded_models = v;
            }
            cfg.clone()
        };
        self.persist(&snapshot)?;
        tracing::info!("Routing configuration updated via API");
        self.rebuild_and_swap();
        Ok(())
    }

    /// Validate an API key by making a real minimal completion request.
    ///
    /// Sends a 1-token "Hi" request to the provider's API. If the key
    /// is invalid or expired, the provider returns an auth error.
    pub async fn validate_key(&self, provider: &str, api_key: &str) -> ValidateKeyResult {
        match self.try_validate(provider, api_key).await {
            Ok(()) => ValidateKeyResult {
                valid: true,
                provider: provider.to_string(),
                message: Some("API key is valid".to_string()),
            },
            Err(e) => ValidateKeyResult {
                valid: false,
                provider: provider.to_string(),
                message: Some(format!("{e}")),
            },
        }
    }

    /// Validate the stored API key for a provider.
    ///
    /// Resolves the key from the credential store (env var → config → auth.json)
    /// and validates it via a real API call. Returns `valid: false` with a
    /// descriptive message when no key is found.
    pub async fn validate_stored_key(&self, provider: &str) -> ValidateKeyResult {
        let api_key_override = {
            let cfg = self.config.read();
            cfg.api_key().as_deref().map(str::to_owned)
        };
        match CredentialStore::resolve(provider, api_key_override.as_deref()) {
            Some((key, _)) => self.validate_key(provider, &key).await,
            None => ValidateKeyResult {
                valid: false,
                provider: provider.to_string(),
                message: Some("No API key found for this provider".to_string()),
            },
        }
    }

    // ── Provider Config API ──────────────────────────────────────────────

    /// Get provider configuration and model list.
    pub fn get_provider_config(&self, provider_id: &str) -> anyhow::Result<ProviderConfigResponse> {
        let ps = self
            .provider_configs
            .read()
            .get(provider_id)
            .cloned()
            .unwrap_or_default();

        let models: Vec<String> = self.list_model_names(provider_id);

        let provider = self.build_provider_info(provider_id);
        Ok(ProviderConfigResponse {
            provider,
            settings: ps,
            models,
        })
    }

    /// Save provider settings and apply to RoutingControl.
    pub fn set_provider_config(
        &self,
        provider_id: &str,
        settings: ProviderSettings,
    ) -> anyhow::Result<ProviderConfigResponse> {
        // Update in-memory state
        {
            let mut providers = self.provider_configs.write();
            providers.insert(provider_id.to_string(), settings.clone());
            self.save_provider_state()?;
        }

        // Apply to live RoutingControl
        let engine = self.engine_handle.get();
        if let Some(routing) = engine.routing_control() {
            match settings.models.mode {
                ModelListMode::Denylist => {
                    for denied in &settings.models.deny {
                        routing.exclude_model(&format!("{provider_id}/{denied}"));
                    }
                }
                ModelListMode::Allowlist => {
                    let all_models = self.list_model_names(provider_id);
                    for model in &all_models {
                        if !settings.models.allow.contains(model) {
                            routing.exclude_model(&format!("{provider_id}/{model}"));
                        }
                    }
                }
                ModelListMode::All => {}
            }
        }

        self.get_provider_config(provider_id)
    }

    /// Test connection to a provider with a specific model.
    /// oxi-sdk 0.56.0: create_provider consults AuthProvider port live,
    /// so credential changes are picked up without engine rebuild.
    pub fn check_provider_connection(
        &self,
        provider_id: &str,
        model_id: &str,
    ) -> anyhow::Result<ConnectionCheckResult> {
        let start = std::time::Instant::now();
        let engine = self.engine_handle.get();
        match engine.create_provider(provider_id) {
            Ok(_provider) => {
                let latency = start.elapsed().as_millis() as u64;
                Ok(ConnectionCheckResult {
                    success: true,
                    model: model_id.to_string(),
                    latency_ms: latency,
                    error: None,
                })
            }
            Err(e) => {
                let latency = start.elapsed().as_millis() as u64;
                Ok(ConnectionCheckResult {
                    success: false,
                    model: model_id.to_string(),
                    latency_ms: latency,
                    error: Some(e.to_string()),
                })
            }
        }
    }

    /// Update model list config for a provider.
    pub fn set_model_list(
        &self,
        provider_id: &str,
        model_config: ModelListSettings,
    ) -> anyhow::Result<ProviderConfigResponse> {
        let mut settings = {
            let providers = self.provider_configs.read();
            providers.get(provider_id).cloned().unwrap_or_default()
        };
        settings.models = model_config;
        self.set_provider_config(provider_id, settings)
    }

    /// Register a new custom provider.
    pub fn add_custom_provider(&self, def: CustomProviderDef) -> anyhow::Result<ProviderInfo> {
        let provider_id = def.id.clone();
        {
            let mut custom = self.custom_providers.write();
            if custom.iter().any(|cp| cp.id == provider_id) {
                anyhow::bail!("Custom provider '{}' already exists", provider_id);
            }
            custom.push(def);
            self.save_provider_state()?;
        }
        // Trigger engine hot-swap to register the new provider
        self.rebuild_and_swap();
        Ok(self.build_provider_info(&provider_id))
    }

    /// Remove a custom provider.
    pub fn remove_custom_provider(&self, id: &str) -> anyhow::Result<()> {
        {
            let mut custom = self.custom_providers.write();
            let before = custom.len();
            custom.retain(|cp| cp.id != id);
            if custom.len() == before {
                anyhow::bail!("Custom provider '{}' not found", id);
            }
            self.save_provider_state()?;
        }
        self.rebuild_and_swap();
        Ok(())
    }

    /// Make a real minimal API call to verify the key works.
    ///
    /// Sends a "Hi" completion request with a 15-second timeout.
    /// Invalid/expired keys trigger an immediate auth error from the provider.
    async fn try_validate(&self, provider: &str, api_key: &str) -> anyhow::Result<()> {
        if api_key.is_empty() {
            anyhow::bail!("API key is empty");
        }

        let builder = oxi_sdk::OxiBuilder::new()
            .with_builtins()
            .api_key(provider, api_key);
        let oxi = builder.build();

        let models = oxi_sdk::get_provider_models(provider);
        if models.is_empty() {
            anyhow::bail!("No models found for provider '{provider}'");
        }

        let model_id = format!("{}/{}", provider, models[0].id);
        let model = oxi
            .resolve_model(&model_id)
            .with_context(|| format!("Unknown model '{model_id}'"))?;
        let provider_inst = oxi
            .create_provider(provider)
            .with_context(|| format!("Failed to create provider '{provider}'"))?;

        let mut ctx = oxi_sdk::Context::new();
        ctx.add_message(oxi_sdk::Message::User(oxi_sdk::UserMessage::new("Hi")));

        let stream_result = tokio::time::timeout(
            std::time::Duration::from_secs(15),
            provider_inst.stream(&model, &ctx, None),
        )
        .await
        .map_err(|_| anyhow::anyhow!("Request timed out (15s)"))?;

        match stream_result {
            Ok(_) => {
                tracing::debug!(provider = %provider, model = %model_id, "Key validated via real API call");
                Ok(())
            }
            Err(e) => Err(anyhow::anyhow!("{e}")),
        }
    }

    // ── Helpers ─────────────────────────────────────────────────────────

    /// Estimate cost for a model invocation.
    pub fn estimate_cost(model_id: &str, input_tokens: u64, output_tokens: u64) -> f64 {
        estimate_cost(model_id, input_tokens, output_tokens)
    }

    /// Persist the current config to disk.
    fn persist(&self, config: &OxiosConfig) -> anyhow::Result<()> {
        let content = toml::to_string_pretty(config)
            .map_err(|e| anyhow::anyhow!("Failed to serialize config: {e}"))?;
        std::fs::write(&self.config_path, content)?;
        Ok(())
    }

    /// Rebuild `OxiosEngine` from current config and swap into the handle.
    ///
    /// Reuses the model catalog from the current engine (it holds the
    /// in-memory models.dev snapshot — re-initializing it on every config
    /// change would just reload the same data). No network calls beyond
    /// what `CredentialStore` already caches in memory.
    fn rebuild_and_swap(&self) {
        // Narrow the read-lock window: clone the small fields we need, then
        // build the engine outside the lock so concurrent readers/writers are
        // not blocked by `OxiosEngine::from_config_with_catalog` work.
        let (model_id, api_key, catalog) = {
            let cfg = self.config.read();
            let catalog = self.engine_handle.get().oxi().catalog().clone();
            (cfg.engine.default_model.clone(), cfg.api_key(), catalog)
        };
        let new_engine = crate::engine::OxiosEngine::from_config_with_catalog(
            &model_id,
            api_key.as_deref(),
            catalog,
        );
        self.engine_handle.swap(new_engine);
    }
    /// Path to the provider state companion file.
    /// Lives alongside config.toml as `<config-root>/config.providers.toml`.
    fn provider_state_path(&self) -> PathBuf {
        let mut p = self.config_path.clone();
        p.set_extension("providers.toml");
        p
    }

    /// Read persisted provider state from the companion file.
    fn read_provider_state(&self) -> anyhow::Result<ProviderStateFile> {
        let path = self.provider_state_path();
        if !path.exists() {
            return Ok(ProviderStateFile {
                providers: HashMap::new(),
                custom_providers: Vec::new(),
            });
        }
        let content = fs::read_to_string(&path)?;
        let state: ProviderStateFile = toml::from_str(&content)
            .map_err(|e| anyhow::anyhow!("Failed to parse provider state: {e}"))?;
        Ok(state)
    }

    /// Persist provider state to the companion file.
    fn save_provider_state(&self) -> anyhow::Result<()> {
        let state = ProviderStateFile {
            providers: self.provider_configs.read().clone(),
            custom_providers: self.custom_providers.read().clone(),
        };
        let content = toml::to_string_pretty(&state)
            .map_err(|e| anyhow::anyhow!("Failed to serialize provider state: {e}"))?;
        fs::write(self.provider_state_path(), content)?;
        Ok(())
    }

    /// Build a [`ProviderInfo`] for the given provider id.
    fn build_provider_info(&self, provider_id: &str) -> ProviderInfo {
        let meta = provider_meta(provider_id);
        let resolved = CredentialStore::resolve(provider_id, None);
        let key_source = resolved
            .as_ref()
            .map(|(_, src)| match src {
                crate::credential::CredentialSource::EnvVar => "env",
                crate::credential::CredentialSource::Config
                | crate::credential::CredentialSource::OxiAuthStore => "auth_store",
            })
            .unwrap_or("none")
            .to_string();
        ProviderInfo {
            id: provider_id.to_string(),
            name: provider_display_name(provider_id),
            category: provider_category(provider_id),
            model_count: 0,
            has_key: resolved.is_some(),
            key_source,
            description: meta.map(|m| m.description.to_string()).unwrap_or_default(),
            env_key: meta.map(|m| m.env_key.to_string()).unwrap_or_default(),
        }
    }

    /// List bare model names (without provider prefix) for a given provider,
    /// consulting the live catalog first, then the static registry.
    fn list_model_names(&self, provider_id: &str) -> Vec<String> {
        let catalog = self.engine_handle.get().oxi().catalog().clone();
        let live = catalog.list_models_sync(provider_id);
        if !live.is_empty() {
            live.iter().map(|m| m.model_id.clone()).collect()
        } else {
            oxi_sdk::get_provider_models(provider_id)
                .iter()
                .map(|m| m.id.to_string())
                .collect()
        }
    }
}

impl std::fmt::Debug for EngineApi {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("EngineApi")
            .field("config_path", &self.config_path)
            .field("provider_configs", &self.provider_configs.read().len())
            .field("custom_providers", &self.custom_providers.read().len())
            .finish()
    }
}

// Expose `RoutingStats::record_model_usage` via a public helper for AgentRuntime.
// This avoids exposing the internal Arc to outside crates.
pub fn record_usage_to_stats(
    stats: &Option<Arc<RoutingStats>>,
    model_id: &str,
    input_tokens: u64,
    output_tokens: u64,
) {
    if let Some(s) = stats {
        let cost = estimate_cost(model_id, input_tokens, output_tokens);
        s.record_model_usage(model_id, cost);
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_provider_category_known() {
        // Major
        assert_eq!(provider_category("anthropic"), ProviderCategory::Major);
        assert_eq!(provider_category("openai"), ProviderCategory::Major);
        assert_eq!(provider_category("google"), ProviderCategory::Major);
        // Open / specialty
        assert_eq!(provider_category("groq"), ProviderCategory::Open);
        assert_eq!(provider_category("opencode"), ProviderCategory::Open);
        // Regional
        assert_eq!(provider_category("minimax"), ProviderCategory::Regional);
        assert_eq!(provider_category("moonshotai"), ProviderCategory::Regional);
        assert_eq!(provider_category("kimi-coding"), ProviderCategory::Regional);
        assert_eq!(provider_category("zai"), ProviderCategory::Regional);
        assert_eq!(provider_category("minimax-cn"), ProviderCategory::Regional);
        assert_eq!(provider_category("xiaomi"), ProviderCategory::Regional);
    }

    #[test]
    fn test_provider_category_fallback() {
        // Unknown ids fall back to Open, not panic.
        assert_eq!(
            provider_category("not-a-real-provider"),
            ProviderCategory::Open
        );
        assert_eq!(provider_category(""), ProviderCategory::Open);
    }

    #[test]
    fn test_provider_display_name_known() {
        assert_eq!(provider_display_name("anthropic"), "Anthropic");
        assert_eq!(provider_display_name("minimax"), "MiniMax");
        assert_eq!(provider_display_name("moonshotai"), "Moonshot AI (Kimi)");
        assert_eq!(provider_display_name("kimi-coding"), "Kimi Coding");
        assert_eq!(provider_display_name("zai"), "Z.AI (GLM)");
        assert_eq!(provider_display_name("opencode"), "OpenCode");
        assert_eq!(provider_display_name("amazon-bedrock"), "Amazon Bedrock");
    }

    #[test]
    fn test_provider_display_name_fallback() {
        // Unknown ids get Title-Cased per segment as a fallback.
        assert_eq!(
            provider_display_name("some-new-provider"),
            "Some New Provider"
        );
        assert_eq!(provider_display_name("kimi-coding"), "Kimi Coding");
        assert_eq!(provider_display_name("some_id"), "Some Id");
        // Empty string stays empty.
        assert_eq!(provider_display_name(""), "");
    }

    #[test]
    fn test_provider_meta_lookup_by_alias() {
        // Aliases resolve to the same meta entry as the canonical id.
        let by_id = provider_meta("github-copilot").unwrap();
        let by_alias = provider_meta("copilot").unwrap();
        assert_eq!(by_id.id, by_alias.id);

        let bedrock_id = provider_meta("amazon-bedrock").unwrap();
        let bedrock_alias = provider_meta("aws-bedrock").unwrap();
        let bedrock_canonical = provider_meta("bedrock").unwrap();
        assert_eq!(bedrock_id.id, bedrock_alias.id);
        assert_eq!(bedrock_id.id, bedrock_canonical.id);
    }

    #[test]
    fn test_provider_meta_unknown_is_none() {
        assert!(provider_meta("not-a-real-provider").is_none());
        assert!(provider_meta("").is_none());
    }

    #[test]
    fn test_provider_info_serialization() {
        let info = ProviderInfo {
            id: "anthropic".to_string(),
            name: "Anthropic".to_string(),
            category: ProviderCategory::Major,
            model_count: 15,
            has_key: true,
            key_source: "auth_store".to_string(),
            description: "Claude models with extended thinking".to_string(),
            env_key: "ANTHROPIC_API_KEY".to_string(),
        };
        let json = serde_json::to_string(&info).unwrap();
        // camelCase serialization
        assert!(json.contains("\"modelCount\":15"));
        assert!(json.contains("\"hasKey\":true"));
        assert!(json.contains("\"envKey\":\"ANTHROPIC_API_KEY\""));
        let restored: ProviderInfo = serde_json::from_str(&json).unwrap();
        assert_eq!(restored.id, "anthropic");
        assert_eq!(restored.name, "Anthropic");
        assert_eq!(restored.model_count, 15);
        assert!(restored.has_key);
        assert_eq!(restored.env_key, "ANTHROPIC_API_KEY");
    }

    #[test]
    fn test_provider_info_serialization_missing_optional() {
        // description / env_key have serde(default) so old clients that
        // omit them still deserialize cleanly.
        let json = r#"{
            "id": "anthropic",
            "name": "Anthropic",
            "category": "major",
            "modelCount": 15,
            "hasKey": true
        }"#;
        let info: ProviderInfo = serde_json::from_str(json).unwrap();
        assert_eq!(info.id, "anthropic");
        assert_eq!(info.description, "");
        assert_eq!(info.env_key, "");
    }

    #[test]
    fn test_model_info_serialization() {
        let info = ModelInfo {
            id: "anthropic/claude-sonnet-4".to_string(),
            name: "Claude Sonnet 4".to_string(),
            api: "anthropic-messages".to_string(),
            provider: "anthropic".to_string(),
            reasoning: true,
            input: vec![InputModality::Text, InputModality::Image],
            context_window: 200000,
            max_tokens: 16000,
            cost_input: 3.0,
            cost_output: 15.0,
            cost_cache_read: 0.3,
            cost_cache_write: 3.75,
        };
        let json = serde_json::to_string(&info).unwrap();
        let restored: ModelInfo = serde_json::from_str(&json).unwrap();
        assert_eq!(restored.id, "anthropic/claude-sonnet-4");
        assert!(restored.reasoning);
        assert_eq!(restored.context_window, 200000);
        assert!(restored.input.contains(&InputModality::Image));
        assert_eq!(restored.api, "anthropic-messages");
    }

    #[test]
    fn test_engine_config_response_serialization() {
        let resp = EngineConfigResponse {
            default_model: "anthropic/claude-sonnet-4".to_string(),
            api_key_set: true,
            api_key_source: Some("config.toml".to_string()),
            provider: Some("anthropic".to_string()),
            routing: RoutingConfigSnapshot {
                routing_enabled: false,
                prefer_cost_efficient: false,
                fallback_models: vec![],
                excluded_models: vec![],
            },
            role_routing: None,
            quick_ask_model: None,
        };
        let json = serde_json::to_string(&resp).unwrap();
        let restored: EngineConfigResponse = serde_json::from_str(&json).unwrap();
        assert_eq!(restored.default_model, "anthropic/claude-sonnet-4");
        assert!(restored.api_key_set);
        assert_eq!(restored.api_key_source.as_deref(), Some("config.toml"));
        assert!(!restored.routing.routing_enabled);
    }

    #[test]
    fn test_validate_key_result_serialization() {
        let result = ValidateKeyResult {
            valid: true,
            provider: "openai".to_string(),
            message: Some("API key is valid".to_string()),
        };
        let json = serde_json::to_string(&result).unwrap();
        let restored: ValidateKeyResult = serde_json::from_str(&json).unwrap();
        assert!(restored.valid);
        assert_eq!(restored.provider, "openai");
    }

    #[test]
    fn test_validate_key_result_invalid() {
        let result = ValidateKeyResult {
            valid: false,
            provider: "anthropic".to_string(),
            message: Some("Validation failed: key too short".to_string()),
        };
        assert!(!result.valid);
        assert!(result.message.as_ref().unwrap().contains("failed"));
    }

    #[test]
    fn test_routing_stats_snapshot() {
        let stats = RoutingStats::new();
        stats.record_model_usage("anthropic/claude-sonnet-4", 0.05);
        stats.record_model_usage("anthropic/claude-sonnet-4", 0.03);
        stats.record_model_usage("openai/gpt-4o-mini", 0.01);

        let snap = stats.snapshot();
        assert_eq!(snap.total_requests, 3);
        assert_eq!(snap.model_calls["anthropic/claude-sonnet-4"], 2);
        assert_eq!(snap.model_calls["openai/gpt-4o-mini"], 1);
        assert!((snap.total_cost - 0.09).abs() < 0.001);
    }

    #[test]
    fn test_fallback_history_circular() {
        let stats = RoutingStats::new();
        for i in 0..210 {
            stats.record_fallback(FallbackEvent {
                timestamp: DateTime::from_timestamp(i as i64, 0).unwrap(),
                from_model: format!("model-{}", i),
                to_model: "fallback".to_string(),
                reason: "test".to_string(),
                success: true,
            });
        }
        let history = stats.fallback_history(200);
        assert_eq!(history.len(), 200);
        // Most recent first (i=209 down to i=10)
        assert_eq!(history[0].from_model, "model-209");
        assert_eq!(history[199].from_model, "model-10");
    }

    #[test]
    fn set_model_rejects_unknown_model_before_persist() {
        use crate::engine::{EngineHandle, OxiosEngine};

        let engine = Arc::new(OxiosEngine::new("anthropic/claude-sonnet-4-20250514"));
        let handle = Arc::new(EngineHandle::new(engine));
        let config = Arc::new(parking_lot::RwLock::new(OxiosConfig::default()));
        // Validation runs before any IO, so a non-existent path is safe — it
        // must never be written to.
        let path = PathBuf::from("/tmp/oxios-set-model-test-NONEXISTENT.toml");
        let api = EngineApi::new(config, path, Arc::new(RoutingStats::new()), handle);

        // The malformed id from the user-reported bug. Must be rejected, not
        // silently accepted and deferred to the execute phase.
        let before = api.config.read().engine.default_model.clone();
        let err = api.set_model("zai-coding-plan/glm-5-turbo").unwrap_err();
        assert!(
            err.to_string().contains("Unknown model"),
            "expected unknown-model error, got: {err}"
        );
        // Rejection happened before persist: config is untouched.
        assert_eq!(api.config.read().engine.default_model, before);
    }

    #[test]
    fn set_model_accepts_known_builtin_model() {
        use crate::engine::{EngineHandle, OxiosEngine};

        let engine = Arc::new(OxiosEngine::new("anthropic/claude-sonnet-4-20250514"));
        let handle = Arc::new(EngineHandle::new(engine));
        let config = Arc::new(parking_lot::RwLock::new(OxiosConfig::default()));
        let tmp =
            std::env::temp_dir().join(format!("oxios-set-model-ok-{}.toml", std::process::id()));
        let api = EngineApi::new(config, tmp.clone(), Arc::new(RoutingStats::new()), handle);

        // A builtin model with a built-in provider resolves + creates a provider
        // without any API key, so validation passes. The swap should succeed.
        let result = api.set_model("openai/gpt-4o");
        // create_provider may still fail without a key on some SDK builds; treat
        // both Ok and a provider-config error as acceptable, but never an
        // "Unknown model" rejection for a known builtin.
        match result {
            Ok(()) => assert_eq!(api.config.read().engine.default_model, "openai/gpt-4o"),
            Err(e) => assert!(
                !e.to_string().contains("Unknown model"),
                "known model rejected as unknown: {e}"
            ),
        }
        let _ = std::fs::remove_file(&tmp);
    }
}