oxi-ai 0.63.0

//! Built-in provider registration.
//!
//! Defines all built-in providers with comprehensive metadata: names, aliases,
//! API key environment variables, base URLs, auth methods, and provider-specific
//! headers. The provider factory is data-driven from this metadata rather than
//! using hardcoded match arms.

use crate::Api;
use crate::catalog::BuiltinProviderEntry;

// ---------------------------------------------------------------------------
// Auth method
// ---------------------------------------------------------------------------

/// How a provider passes its API key in HTTP headers.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AuthMethod {
    /// `Authorization: Bearer <key>` — most OpenAI-compatible providers.
    Bearer,
    /// `x-api-key: <key>` — Anthropic and Anthropic-compatible providers.
    XApiKey,
    /// `api-key: <key>` — Azure OpenAI.
    ApiKey,
    /// No API key header (uses other auth like OAuth, SigV4).
    None,
}

// ---------------------------------------------------------------------------
// Provider metadata
// ---------------------------------------------------------------------------

/// Metadata for a built-in provider.
#[derive(Debug, Clone)]
pub struct BuiltinProvider {
    /// Primary provider name (e.g. "openai")
    pub name: &'static str,
    /// Display name (e.g. "OpenAI")
    pub display_name: &'static str,
    /// Alternative names that resolve to this provider
    pub aliases: &'static [&'static str],
    /// API type used by this provider
    pub api: Api,
    /// Environment variable(s) that may hold the API key (in priority order)
    pub env_key: &'static str,
    /// Additional environment variables to check
    pub extra_env_keys: &'static [&'static str],
    /// Default base URL for the API
    pub base_url: &'static str,
    /// Whether this provider is enabled by default
    pub default_enabled: bool,
    /// How to pass the API key
    pub auth_method: AuthMethod,
    /// Extra HTTP headers required by this provider
    pub extra_headers: &'static [(&'static str, &'static str)],
    /// Provider category for UI grouping ("primary", "chinese", "enterprise", "open",
    /// "coding", "cloud", "specialized")
    pub category: &'static str,
    /// Short human-readable description shown in the provider selection UI
    pub description: &'static str,
}

// ---------------------------------------------------------------------------
// API enum parsing
// ---------------------------------------------------------------------------

/// Parse the API string from a TOML entry into the `Api` enum.
///
/// Falls back to `Api::OpenAiCompletions` for unknown values — this matches
/// the historical behavior where most "AI gateway" providers expose an
/// OpenAI-compatible endpoint.
fn parse_api(s: &str) -> Api {
    // Delegate to the single authoritative parser on `Api` (covers all 14
    // KnownApi dialects). Unknown strings default to OpenAI-compatible — the
    // catalog only emits known dialects, so this is a defensive fallback for
    // ad-hoc gateways/aggregators.
    Api::from_kebab_str(s).unwrap_or(Api::OpenAiCompletions)
}

impl From<&BuiltinProviderEntry> for BuiltinProvider {
    fn from(entry: &BuiltinProviderEntry) -> Self {
        // SAFETY: These String→&'static str conversions are safe because the
        // resulting `BuiltinProvider` instances are stored in a `OnceLock<Vec<_>>`
        // that lives for the lifetime of the program. We leak the strings to
        // obtain `'static` references; this is a one-time cost at startup and
        // bounded by the models.dev snapshot (~70+ providers).
        let name: &'static str = Box::leak(entry.id.clone().into_boxed_str());
        let display_name: &'static str = Box::leak(entry.display_name.clone().into_boxed_str());
        let aliases: &'static [&'static str] = Box::leak(
            entry
                .aliases
                .iter()
                .map(|s| Box::leak(s.clone().into_boxed_str()) as &'static str)
                .collect::<Vec<_>>()
                .into_boxed_slice(),
        );
        let env_key: &'static str = Box::leak(entry.env_key.clone().into_boxed_str());
        let extra_env_keys: &'static [&'static str] = Box::leak(
            entry
                .extra_env_keys
                .iter()
                .map(|s| Box::leak(s.clone().into_boxed_str()) as &'static str)
                .collect::<Vec<_>>()
                .into_boxed_slice(),
        );
        let base_url: &'static str = Box::leak(entry.base_url.clone().into_boxed_str());
        let category: &'static str = Box::leak(entry.category.clone().into_boxed_str());
        let description: &'static str = Box::leak(entry.description.clone().into_boxed_str());
        let extra_headers: &'static [(&'static str, &'static str)] = Box::leak(
            entry
                .extra_headers
                .iter()
                .map(|(k, v)| {
                    (
                        Box::leak(k.clone().into_boxed_str()) as &'static str,
                        Box::leak(v.clone().into_boxed_str()) as &'static str,
                    )
                })
                .collect::<Vec<_>>()
                .into_boxed_slice(),
        );

        BuiltinProvider {
            name,
            display_name,
            aliases,
            api: parse_api(&entry.api),
            env_key,
            extra_env_keys,
            base_url,
            default_enabled: entry.default_enabled,
            auth_method: match entry.auth_method {
                crate::catalog::AuthMethod::Bearer => AuthMethod::Bearer,
                crate::catalog::AuthMethod::XApiKey => AuthMethod::XApiKey,
                crate::catalog::AuthMethod::ApiKey => AuthMethod::ApiKey,
                crate::catalog::AuthMethod::None => AuthMethod::None,
            },
            extra_headers,
            category,
            description,
        }
    }
}

// ---------------------------------------------------------------------------
// Built-in provider definitions (deprecated, now in data/catalog/providers.toml)
// ---------------------------------------------------------------------------

// ---------------------------------------------------------------------------
// API-to-provider mappings
// ---------------------------------------------------------------------------

/// Mapping from API identifier to the primary provider name.
static API_TO_PROVIDER: &[(&str, Api)] = &[
    ("anthropic-messages", Api::AnthropicMessages),
    ("openai-completions", Api::OpenAiCompletions),
    ("openai-responses", Api::OpenAiResponses),
    ("openai-codex-responses", Api::OpenAiCodexResponses),
    ("azure-openai-responses", Api::AzureOpenAiResponses),
    ("google-generative-ai", Api::GoogleGenerativeAi),
    ("google-gemini-cli", Api::GoogleGeminiCli),
    ("google-vertex", Api::GoogleVertex),
    ("bedrock-converse-stream", Api::BedrockConverseStream),
    ("cursor-agent", Api::CursorAgent),
    ("cursor", Api::CursorAgent),
    ("devin-agent", Api::DevinAgent),
    ("devin", Api::DevinAgent),
    ("gitlab-duo", Api::GitLabDuo),
    ("gitlab-duo-agent", Api::GitLabDuoAgent),
];

// ---------------------------------------------------------------------------
// Registry access functions
// ---------------------------------------------------------------------------

/// Get all built-in providers, built lazily from the catalog TOML.
///
/// This replaces the historical `static BUILTIN_PROVIDERS` array. The first
/// call parses `data/catalog/providers.toml` and converts each entry to a
/// `BuiltinProvider`; subsequent calls return the cached `&'static` slice.
///
/// **Layer 2 (user overrides) is applied here**: before conversion, the
/// `OverrideFile` from `crate::catalog::load_overrides()` (if any) is
/// merged with the built-in providers. Override entries with the same id
/// replace built-in ones; new ids are appended.
pub fn get_builtin_providers() -> &'static [BuiltinProvider] {
    static CACHE: std::sync::OnceLock<Vec<BuiltinProvider>> = std::sync::OnceLock::new();
    CACHE
        .get_or_init(|| {
            // Materialize providers from the embedded models.dev snapshot.
            // This replaces the old TOML-based path (CatalogRoot::providers.toml)
            // gives us all ~145 providers from models.dev.
            let mut builtins = crate::catalog::materialize::materialize_providers();
            if let Some(overrides) = crate::catalog::load_overrides() {
                crate::catalog::apply_provider_overrides(&mut builtins, &overrides.provider);
            }
            builtins.iter().map(BuiltinProvider::from).collect()
        })
        .as_slice()
}

/// Look up a built-in provider by name or alias.
pub fn get_builtin_provider(name: &str) -> Option<&'static BuiltinProvider> {
    get_builtin_providers()
        .iter()
        .find(|p| p.name == name || p.aliases.contains(&name))
}

/// Get the environment variable name for a provider.
pub fn get_provider_env_key(name: &str) -> Option<&'static str> {
    get_builtin_provider(name).map(|p| p.env_key)
}

/// Get all environment variable names for a provider (primary + extras).
pub fn get_provider_env_keys(name: &str) -> Vec<&'static str> {
    if let Some(p) = get_builtin_provider(name) {
        let mut keys = vec![p.env_key];
        keys.extend_from_slice(p.extra_env_keys);
        keys
    } else {
        vec![]
    }
}

/// Get the API type for a provider by name or alias.
pub fn get_provider_api(name: &str) -> Option<Api> {
    get_builtin_provider(name).map(|p| p.api)
}

/// Get the default base URL for a provider.
pub fn get_provider_base_url(name: &str) -> Option<&'static str> {
    get_builtin_provider(name).map(|p| p.base_url)
}

/// Get all API-to-provider mappings.
pub fn get_api_mappings() -> &'static [(&'static str, Api)] {
    API_TO_PROVIDER
}

/// Get all provider names (primary names only).
pub fn get_all_provider_names() -> Vec<&'static str> {
    get_builtin_providers().iter().map(|p| p.name).collect()
}

/// Get all provider names including aliases.
pub fn get_all_provider_aliases() -> Vec<&'static str> {
    let mut names: Vec<&'static str> = get_builtin_providers()
        .iter()
        .flat_map(|p| std::iter::once(p.name).chain(p.aliases.iter().copied()))
        .collect();
    names.sort();
    names.dedup();
    names
}

/// Resolve a provider name/alias to its canonical name.
pub fn resolve_provider_name(name: &str) -> Option<&'static str> {
    get_builtin_provider(name).map(|p| p.name)
}

/// Check if a provider name or alias is a known built-in.
pub fn is_builtin_provider(name: &str) -> bool {
    get_builtin_provider(name).is_some()
}

// ---------------------------------------------------------------------------
// Data-driven provider factory
// ---------------------------------------------------------------------------

/// Create a built-in provider by name.
///
/// This is the **single source of truth** for provider instantiation. It reads
/// the `BuiltinProvider` metadata and creates the appropriate provider struct
/// with the correct base URL, API key, and extra headers.
///
/// The returned transport carries **no identity** — provider identity (the
/// canonical catalog id) lives in the registry key / `Model.provider` field,
/// not on the transport. This completes the omp three-way split (transport /
/// identity / metadata) — see
/// `docs/superpowers/specs/2026-07-27-omp-realignment-design.md` (P0.3).
///
/// Returns `None` if the name is not a known built-in provider.
pub fn create_builtin_provider(name: &str) -> Option<Box<dyn super::Provider>> {
    let builtin = get_builtin_provider(name)?;
    build_builtin_transport(builtin)
}

/// Build the transport for a built-in provider.
///
/// Transports carry no identity; the canonical catalog id is the registry key
/// (see [`create_builtin_provider`]). Part of the omp three-way split — see
/// `docs/superpowers/specs/2026-07-27-omp-realignment-design.md` (P0.3).
fn build_builtin_transport(builtin: &'static BuiltinProvider) -> Option<Box<dyn super::Provider>> {
    match builtin.api {
        // ── Anthropic Messages API ──────────────────────────────────────
        Api::AnthropicMessages => {
            let extra_headers: Vec<(String, String)> = builtin
                .extra_headers
                .iter()
                .map(|(k, v)| (k.to_string(), v.to_string()))
                .collect();

            // If the provider has its own base URL (MiniMax, etc.), use it
            if !builtin.base_url.is_empty() && builtin.name != "anthropic" {
                Some(Box::new(super::anthropic::AnthropicProvider::with_config(
                    builtin.base_url,
                    None,
                    extra_headers,
                )))
            } else {
                Some(Box::new(super::anthropic::AnthropicProvider::new()))
            }
        }

        // ── Google APIs ─────────────────────────────────────────────────
        Api::GoogleGenerativeAi => Some(Box::new(super::google::GoogleProvider::new())),
        Api::GoogleGeminiCli => Some(Box::new(super::gemini_cli::GeminiCliProvider::new())),
        Api::GoogleVertex => Some(Box::new(super::vertex::VertexProvider::new())),

        // ── Azure ───────────────────────────────────────────────────────
        Api::AzureOpenAiResponses => Some(Box::new(super::azure::AzureProvider::new())),

        // ── Bedrock ─────────────────────────────────────────────────────
        Api::BedrockConverseStream => Some(Box::new(super::bedrock::BedrockProvider::new())),

        // ── OpenAI Responses API ────────────────────────────────────────
        Api::OpenAiResponses => Some(Box::new(
            super::openai_responses::OpenAiResponsesProvider::new(),
        )),
        // ── OpenAI Codex Responses API ─────────────────────────────────
        // Same wire format as `openai-responses`; reuse
        // `OpenAiResponsesProvider` (upstream `scripts/catalog/port-openclaw.py:43`
        // maps `openai-codex → openai-responses`). `openai_responses_shared.rs`
        // doc comment makes the same statement.
        Api::OpenAiCodexResponses => Some(Box::new(
            super::openai_responses::OpenAiResponsesProvider::new(),
        )),

        // ── OpenAI Chat Completions API ─────────────────────────────────
        // All OpenAI-compatible providers use OpenAiProvider with custom base
        // URLs and optional extra headers from their BuiltinProvider metadata.
        Api::OpenAiCompletions => {
            let extra_headers: Vec<(String, String)> = builtin
                .extra_headers
                .iter()
                .map(|(k, v)| (k.to_string(), v.to_string()))
                .collect();

            if builtin.base_url.is_empty() {
                // OpenAI itself (no custom base URL)
                if extra_headers.is_empty() {
                    Some(Box::new(super::openai::OpenAiProvider::new()))
                } else {
                    Some(Box::new(super::openai::OpenAiProvider::with_config(
                        "https://api.openai.com/v1",
                        None,
                        extra_headers,
                    )))
                }
            } else if extra_headers.is_empty() {
                Some(Box::new(super::openai::OpenAiProvider::with_base_url(
                    builtin.base_url,
                )))
            } else {
                Some(Box::new(super::openai::OpenAiProvider::with_config(
                    builtin.base_url,
                    None,
                    extra_headers,
                )))
            }
        }
        // ── Ollama chat API (local NDJSON server) ──────────────────────
        Api::OllamaChat => {
            let base = if builtin.base_url.is_empty() {
                "http://localhost:11434"
            } else {
                builtin.base_url
            };
            Some(Box::new(super::ollama::OllamaProvider::with_base_url(base)))
        }
        // ── Remote-AGENT providers (WebSocket/protobuf) ─────────────────
        // These providers require additional infra (HTTP/2, protobuf,
        // WebSocket) that oxi-ai does not currently bundle.
        Api::CursorAgent => Some(Box::new(super::cursor::CursorProvider::new())),
        Api::DevinAgent => Some(Box::new(super::devin::DevinProvider::new())),
        Api::GitLabDuo => Some(Box::new(super::gitlab_duo::GitLabDuoProvider::new())),
        Api::GitLabDuoAgent => Some(Box::new(
            super::gitlab_duo_agent::GitLabDuoAgentProvider::new(),
        )),
        _ => None,
    }
}

/// Create a built-in provider with optional credential and base URL overrides.
///
/// This is like [`create_builtin_provider`] but allows injecting an API key
/// and/or base URL at construction time instead of reading from environment
/// variables. When `api_key` is `Some`, it takes precedence over the
/// environment. When `base_url` is `Some`, the provider's default endpoint
/// is overridden.
///
/// Returns `None` if the name is not a known built-in provider.
pub fn create_builtin_provider_with_options(
    name: &str,
    api_key: Option<&str>,
    base_url: Option<&str>,
) -> Option<Box<dyn super::Provider>> {
    let builtin = get_builtin_provider(name)?;
    build_builtin_transport_with_options(builtin, api_key, base_url)
}

/// Build the transport for a built-in provider with credential/base-URL
/// overrides. Transports carry no identity (the canonical catalog id is the
/// registry key). Falls back to [`build_builtin_transport`] when no override
/// applies.
fn build_builtin_transport_with_options(
    builtin: &'static BuiltinProvider,
    api_key: Option<&str>,
    base_url: Option<&str>,
) -> Option<Box<dyn super::Provider>> {
    // Resolve API key: explicit override > environment variables
    let resolved_key = api_key.map(String::from).or_else(|| {
        std::env::var(builtin.env_key).ok().or_else(|| {
            builtin
                .extra_env_keys
                .iter()
                .find_map(|k| std::env::var(k).ok())
        })
    });

    // Resolve base URL: explicit override > built-in default
    let resolved_base_url = base_url.map(String::from).or_else(|| {
        if builtin.base_url.is_empty() {
            None
        } else {
            Some(builtin.base_url.to_string())
        }
    });

    let extra_headers: Vec<(String, String)> = builtin
        .extra_headers
        .iter()
        .map(|(k, v)| (k.to_string(), v.to_string()))
        .collect();

    match builtin.api {
        // ── Anthropic Messages API ──────────────────────────────────────
        Api::AnthropicMessages => {
            if let Some(key) = resolved_key {
                Some(Box::new(super::anthropic::AnthropicProvider::with_config(
                    resolved_base_url
                        .as_deref()
                        .unwrap_or("https://api.anthropic.com"),
                    Some(key),
                    extra_headers,
                )))
            } else if resolved_base_url.is_some() {
                Some(Box::new(super::anthropic::AnthropicProvider::with_config(
                    resolved_base_url
                        .as_deref()
                        .unwrap_or("https://api.anthropic.com"),
                    None,
                    extra_headers,
                )))
            } else {
                // No key and no base URL — fall back to default construction
                // (reads from env at stream time)
                build_builtin_transport(builtin)
            }
        }

        // ── Google APIs ─────────────────────────────────────────────────
        Api::GoogleGenerativeAi => build_builtin_transport(builtin),
        Api::GoogleGeminiCli => build_builtin_transport(builtin),
        Api::GoogleVertex => build_builtin_transport(builtin),
        // ── Azure ───────────────────────────────────────────────────────
        Api::AzureOpenAiResponses => build_builtin_transport(builtin),

        // ── Bedrock ─────────────────────────────────────────────────────
        Api::BedrockConverseStream => build_builtin_transport(builtin),

        Api::OpenAiResponses => build_builtin_transport(builtin),
        Api::OpenAiCodexResponses => build_builtin_transport(builtin),

        // ── OpenAI Chat Completions API ─────────────────────────────────
        Api::OpenAiCompletions => {
            let url = resolved_base_url
                .as_deref()
                .unwrap_or(if builtin.base_url.is_empty() {
                    "https://api.openai.com/v1"
                } else {
                    builtin.base_url
                });

            if let Some(key) = resolved_key {
                if extra_headers.is_empty() {
                    Some(Box::new(
                        super::openai::OpenAiProvider::with_base_url_and_key(url, Some(key)),
                    ))
                } else {
                    Some(Box::new(super::openai::OpenAiProvider::with_config(
                        url,
                        Some(key),
                        extra_headers,
                    )))
                }
            } else if url != builtin.base_url || !extra_headers.is_empty() {
                // Base URL override or extra headers without explicit key
                Some(Box::new(super::openai::OpenAiProvider::with_config(
                    url,
                    None,
                    extra_headers,
                )))
            } else {
                build_builtin_transport(builtin)
            }
        }
        // ── Ollama chat API ────────────────────────────────────────────
        Api::OllamaChat => {
            let url = resolved_base_url
                .as_deref()
                .unwrap_or("http://localhost:11434");
            Some(Box::new(super::ollama::OllamaProvider::with_config(
                url,
                resolved_key,
            )))
        }
        // ── Remote-AGENT providers (WebSocket/protobuf) ─────────────────
        Api::CursorAgent => build_builtin_transport(builtin),
        Api::DevinAgent => build_builtin_transport(builtin),
        Api::GitLabDuo => build_builtin_transport(builtin),
        Api::GitLabDuoAgent => build_builtin_transport(builtin),
        _ => None,
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    #[test]
    fn test_create_builtin_provider_anthropic() {
        // Identity is the registry key, not a method on the transport.
        assert!(create_builtin_provider("anthropic").is_some());
    }

    #[test]
    fn test_create_builtin_provider_openai() {
        assert!(create_builtin_provider("openai").is_some());
    }

    #[test]
    fn test_create_builtin_provider_by_alias() {
        // "amazon-bedrock" is the catalog id; the transport is BedrockProvider.
        assert!(create_builtin_provider("amazon-bedrock").is_some());
    }

    #[test]
    fn test_create_builtin_provider_unknown() {
        assert!(create_builtin_provider("unknown").is_none());
    }

    #[test]
    fn layer2_override_adds_provider() {
        // Set OXI_CATALOG_OVERRIDE to a known override file, then verify
        // the provider shows up. We use a tempfile in the test target dir.
        use std::io::Write;

        let dir = std::env::temp_dir().join("oxi-test-layer2");
        std::fs::create_dir_all(&dir).unwrap();
        let path = dir.join("overrides.toml");
        let mut f = std::fs::File::create(&path).unwrap();
        writeln!(
            f,
            r#"
[[provider]]
id = "test-injected-{}"
display_name = "Test Injected"
api = "openai-completions"
env_key = "TEST_INJECTED_KEY"
auth_method = "bearer"
category = "primary"
description = "Test provider from override"
"#,
            std::process::id()
        )
        .unwrap();
        drop(f);

        // SAFETY: only this test mutates this env var, and only briefly.
        // The test is #[test] which runs on a single thread within a test binary.
        unsafe {
            std::env::set_var("OXI_CATALOG_OVERRIDE", &path);
        }
        // Invalidate the cache so the override is picked up.
        // (The OnceLock has no reset API; this test only checks the load
        //  machinery via find_override_files, not the full integration.)
        let files = crate::catalog::find_override_files();
        unsafe {
            std::env::remove_var("OXI_CATALOG_OVERRIDE");
        }
        assert!(!files.is_empty(), "OXI_CATALOG_OVERRIDE should be detected");
        let (found_path, _content) = &files[0];
        assert_eq!(found_path, &path);
    }

    #[test]
    fn test_create_builtin_provider_deepseek() {
        // P0.3 regression: "deepseek" must resolve (identity = registry key,
        // transport is OpenAI-compatible). Previously the transport reported
        // name() == "openai"; now identity lives in the catalog key.
        assert!(create_builtin_provider("deepseek").is_some());
    }

    #[test]
    fn test_create_builtin_provider_minimax() {
        assert!(create_builtin_provider("minimax").is_some());
    }

    #[test]
    fn test_create_builtin_provider_minimax_cn() {
        assert!(create_builtin_provider("minimax-cn").is_some());
    }

    #[test]
    fn test_create_builtin_provider_togetherai() {
        assert!(create_builtin_provider("togetherai").is_some());
    }

    #[test]
    fn test_create_builtin_provider_openrouter() {
        assert!(create_builtin_provider("openrouter").is_some());
    }

    #[test]
    fn test_create_builtin_provider_cerebras() {
        assert!(create_builtin_provider("cerebras").is_some());
    }

    #[test]
    fn test_get_builtin_provider_openai() {
        let p = get_builtin_provider("openai").unwrap();
        assert_eq!(p.name, "openai");
        assert_eq!(p.display_name, "OpenAI");
        assert_eq!(p.api, Api::OpenAiCompletions);
        assert_eq!(p.auth_method, AuthMethod::Bearer);
    }

    #[test]
    fn test_get_builtin_provider_anthropic() {
        let p = get_builtin_provider("anthropic").unwrap();
        assert_eq!(p.name, "anthropic");
        assert_eq!(p.auth_method, AuthMethod::XApiKey);
    }

    #[test]
    fn test_get_builtin_provider_azure() {
        let p = get_builtin_provider("azure").unwrap();
        assert_eq!(p.auth_method, AuthMethod::ApiKey);
    }

    #[test]
    fn test_get_builtin_provider_by_alias() {
        // With models.dev IDs, the canonical id is "amazon-bedrock".
        let p = get_builtin_provider("amazon-bedrock").unwrap();
        assert_eq!(p.name, "amazon-bedrock");
    }

    #[test]
    fn test_get_builtin_provider_unknown() {
        assert!(get_builtin_provider("unknown-provider").is_none());
    }

    #[test]
    fn test_get_provider_env_key() {
        assert_eq!(get_provider_env_key("openai"), Some("OPENAI_API_KEY"));
        assert_eq!(get_provider_env_key("anthropic"), Some("ANTHROPIC_API_KEY"));
    }

    #[test]
    fn test_get_provider_env_keys_with_extras() {
        let keys = get_provider_env_keys("google");
        assert!(keys.contains(&"GOOGLE_API_KEY"));
        assert!(keys.contains(&"GEMINI_API_KEY"));
    }

    #[test]
    fn test_get_provider_api() {
        assert_eq!(get_provider_api("anthropic"), Some(Api::AnthropicMessages));
        assert_eq!(get_provider_api("google-vertex"), Some(Api::GoogleVertex));
        assert_eq!(get_provider_api("google"), Some(Api::GoogleGenerativeAi));
    }

    #[test]
    fn test_resolve_provider_name() {
        // With models.dev IDs, canonical names are the models.dev IDs.
        assert_eq!(
            resolve_provider_name("google-vertex"),
            Some("google-vertex")
        );
        assert_eq!(
            resolve_provider_name("amazon-bedrock"),
            Some("amazon-bedrock")
        );
        assert_eq!(resolve_provider_name("openai"), Some("openai"));
    }

    #[test]
    fn test_is_builtin_provider() {
        assert!(is_builtin_provider("openai"));
        assert!(is_builtin_provider("deepseek"));
        assert!(is_builtin_provider("togetherai"));
        assert!(!is_builtin_provider("fake-provider"));
    }

    #[test]
    fn test_all_providers_have_env_key() {
        for p in get_builtin_providers() {
            assert!(!p.env_key.is_empty(), "Provider {} has no env key", p.name);
        }
    }

    #[test]
    fn test_all_providers_have_auth_method() {
        for p in get_builtin_providers() {
            // Just verify they all have a valid auth method
            match p.auth_method {
                AuthMethod::Bearer
                | AuthMethod::XApiKey
                | AuthMethod::ApiKey
                | AuthMethod::None => {}
            }
        }
    }

    #[test]
    fn test_get_all_provider_names() {
        // Provider names are now models.dev IDs.
        let names = get_all_provider_names();
        assert!(names.contains(&"openai"));
        assert!(names.contains(&"anthropic"));
        assert!(names.contains(&"amazon-bedrock"));
        assert!(names.contains(&"togetherai"));
        // models.dev snapshot has 145+ providers
    }

    // ── Tests for materialized providers (models.dev as source of truth) ─

    #[test]
    fn test_openclaw_ported_providers_present() {
        // Verify key models.dev providers are present after materialize.
        // Local-only providers (ollama/lmstudio/vllm/sglang) are not in
        // models.dev — they're handled by the runtime discovery layer.
        let names = get_all_provider_names();
        for p in [
            "chutes",
            "venice",
            "moonshotai",
            "novita-ai",
            "stepfun-ai",
            "alibaba",
            "google-vertex-anthropic",
            "synthetic",
            "amazon-bedrock",
            "opencode",
        ] {
            assert!(names.contains(&p), "Missing materialized provider: {p}");
        }
    }

    #[test]
    fn test_openclaw_provider_aliases() {
        // With models.dev IDs, there's no alias layer — the ID is the ID.
        // Legacy aliases (gmi-cloud, dashscope, etc.) are no longer valid.
        assert_eq!(resolve_provider_name("chutes"), Some("chutes"));
        assert_eq!(resolve_provider_name("anthropic"), Some("anthropic"));
        assert_eq!(resolve_provider_name("openai"), Some("openai"));
        // Unknown IDs return None (no alias fallback)
        assert_eq!(resolve_provider_name("nonexistent-provider"), None);
    }

    #[test]
    fn test_openclaw_provider_base_urls() {
        // URLs come from models.dev `api` field. Native SDK providers
        // (venice, anthropic) have `api: null` → empty base_url.
        assert_eq!(
            get_provider_base_url("chutes"),
            Some("https://llm.chutes.ai/v1")
        );
        assert_eq!(get_provider_base_url("venice"), Some(""));
        assert_eq!(
            get_provider_base_url("synthetic"),
            Some("https://api.synthetic.new/openai/v1")
        );
        assert_eq!(
            get_provider_base_url("openrouter"),
            Some("https://openrouter.ai/api/v1")
        );
    }

    #[test]
    fn test_openclaw_local_providers_use_bearer() {
        // Local-only providers (ollama/lmstudio/vllm/sglang) are NOT in
        // models.dev — they're handled by the LOCAL discovery layer
        // (crate::catalog::runtime) which uses Bearer auth by default.
        // This test is a placeholder for future LOCAL-layer testing.
        // Verify that at least some providers use Bearer auth (the
        // OpenAI-compatible default).
        let names = get_all_provider_names();
        let bearer_count = names
            .iter()
            .filter(|n| {
                get_builtin_provider(n)
                    .map(|p| p.auth_method == AuthMethod::Bearer)
                    .unwrap_or(false)
            })
            .count();
        assert!(
            bearer_count > 50,
            "expected >50 Bearer providers, got {bearer_count}"
        );
    }

    #[test]
    fn test_openclaw_anthropic_compat_providers() {
        // Providers using Anthropic protocol (identified by @ai-sdk/anthropic
        // or compatible npm package).
        // google-vertex-anthropic uses @ai-sdk/google-vertex/anthropic.
        let bp = get_builtin_provider("google-vertex-anthropic").unwrap();
        assert_eq!(
            bp.api,
            Api::GoogleVertex,
            "google-vertex-anthropic maps to GoogleVertex"
        );
        // minimax uses @ai-sdk/anthropic
        let bp = get_builtin_provider("minimax").unwrap();
        assert_eq!(
            bp.api,
            Api::AnthropicMessages,
            "minimax uses AnthropicMessages"
        );
    }

    #[test]
    fn test_create_openclaw_providers() {
        // Smoke test that materialized providers can be instantiated.
        // These are models.dev provider IDs (not legacy oxi IDs).
        for p in [
            "chutes",
            "venice",
            "moonshotai",
            "novita-ai",
            "gmicloud",
            "deepinfra",
            "fireworks-ai",
            "togetherai",
            "alibaba",
            "amazon-bedrock",
            "opencode",
            "minimax",
        ] {
            let bp = create_builtin_provider(p);
            assert!(bp.is_some(), "create_builtin_provider({p}) failed");
        }
    }

    #[test]
    fn test_get_all_provider_aliases() {
        // With models.dev as the source of truth, provider IDs are the
        // canonical models.dev IDs (e.g. "amazon-bedrock", "togetherai").
        // Legacy oxi aliases ("bedrock", "together") are no longer present.
        let aliases = get_all_provider_aliases();
        assert!(aliases.contains(&"amazon-bedrock"));
        assert!(aliases.contains(&"togetherai"));
        assert!(aliases.contains(&"anthropic"));
        assert!(aliases.contains(&"openai"));
    }

    #[test]
    fn test_get_provider_base_url() {
        // With models.dev as the source of truth, base URLs come from
        // the `api` field. Native SDK providers (openai, anthropic, google)
        // have `api: null`, so their base_url is empty (computed at runtime).
        assert_eq!(get_provider_base_url("openai"), Some(""));
        assert_eq!(get_provider_base_url("anthropic"), Some(""));
        // OpenRouter has an explicit api URL
        assert_eq!(
            get_provider_base_url("openrouter"),
            Some("https://openrouter.ai/api/v1")
        );
    }

    #[test]
    fn test_minimax_base_url() {
        let p = get_builtin_provider("minimax").unwrap();
        // models.dev: api = "https://api.minimax.io/anthropic/v1"
        assert_eq!(p.base_url, "https://api.minimax.io/anthropic/v1");
        assert_eq!(p.api, Api::AnthropicMessages);
    }

    #[test]
    fn test_openrouter_extra_headers() {
        let p = get_builtin_provider("openrouter").unwrap();
        assert_eq!(
            p.extra_headers,
            &[("HTTP-Referer", "https://oxi.dev/"), ("X-Title", "oxi")]
        );
    }

    #[test]
    fn test_cerebras_extra_headers() {
        let p = get_builtin_provider("cerebras").unwrap();
        assert_eq!(
            p.extra_headers,
            &[("X-Cerebras-3rd-Party-Integration", "opencode")]
        );
    }

    #[test]
    fn test_create_builtin_provider_with_options_openai() {
        // With explicit API key and base URL
        let p = create_builtin_provider_with_options(
            "openai",
            Some("sk-test-key"),
            Some("https://my-proxy.example.com/v1"),
        );
        assert!(p.is_some());
    }

    #[test]
    fn test_create_builtin_provider_with_options_anthropic() {
        let p = create_builtin_provider_with_options("anthropic", Some("sk-ant-test-key"), None);
        assert!(p.is_some());
    }

    #[test]
    fn test_create_builtin_provider_with_options_no_override() {
        // No key or URL — should fall back to default creation
        let p = create_builtin_provider_with_options("deepseek", None, None);
        assert!(p.is_some());
    }

    #[test]
    fn test_create_builtin_provider_with_options_unknown() {
        let p = create_builtin_provider_with_options("nonexistent_provider", None, None);
        assert!(p.is_none());
    }

    // ────────────────────────────────────────────────────────────────────
    // Codex Responses + Gemini CLI dispatch (P0.5 — provider/API realignment)
    //
    // Proves the previously-silent `_ => None` arms at the bottom of
    // `build_builtin_transport` and `build_builtin_transport_with_options`
    // are now reached via explicit arms, and that:
    // - `Api::OpenAiCodexResponses` dispatches to `OpenAiResponsesProvider`
    //   (same Responses protocol as plain `openai-responses`).
    // - `Api::GoogleGeminiCli` dispatches to `GeminiCliProvider`, which
    //   surfaces `ProviderError::NotImplemented` rather than faking success.
    // - The Codex Responses SSE parser produces the expected `ProviderEvent`s.
    // ────────────────────────────────────────────────────────────────────

    /// Build a `BuiltinProvider` from a `BuiltinProviderEntry` whose `api`
    /// field is whatever the caller wants, then dispatch it through
    /// `build_builtin_transport`. The entry is leaked (one-time test cost)
    /// so the `&'static BuiltinProvider` signature is satisfied.
    fn dispatch_with_api(api: &str) -> Option<Box<dyn crate::Provider>> {
        let entry = crate::catalog::BuiltinProviderEntry {
            id: "test-dispatch-target".to_string(),
            display_name: "Test Dispatch Target".to_string(),
            aliases: vec![],
            api: api.to_string(),
            env_key: "TEST_DISPATCH_KEY".to_string(),
            extra_env_keys: vec![],
            base_url: "http://127.0.0.1:1".to_string(),
            auth_method: crate::catalog::AuthMethod::Bearer,
            extra_headers: vec![],
            category: "test".to_string(),
            description: "Synthetic builtin for dispatch-arm coverage".to_string(),
            default_enabled: true,
        };
        let builtin: &'static BuiltinProvider = Box::leak(Box::new(BuiltinProvider::from(&entry)));
        build_builtin_transport(builtin)
    }

    /// Build a `BuiltinProvider` and dispatch through
    /// `build_builtin_transport_with_options`. Used to prove the
    /// `_with_options` path also has explicit arms.
    fn dispatch_with_options_api(api: &str) -> Option<Box<dyn crate::Provider>> {
        let entry = crate::catalog::BuiltinProviderEntry {
            id: "test-dispatch-options-target".to_string(),
            display_name: "Test Dispatch Options Target".to_string(),
            aliases: vec![],
            api: api.to_string(),
            env_key: "TEST_DISPATCH_KEY".to_string(),
            extra_env_keys: vec![],
            base_url: "http://127.0.0.1:1".to_string(),
            auth_method: crate::catalog::AuthMethod::Bearer,
            extra_headers: vec![],
            category: "test".to_string(),
            description: "Synthetic builtin for dispatch-arm coverage".to_string(),
            default_enabled: true,
        };
        let builtin: &'static BuiltinProvider = Box::leak(Box::new(BuiltinProvider::from(&entry)));
        build_builtin_transport_with_options(builtin, None, None)
    }

    #[test]
    fn dispatch_openai_codex_responses_returns_some() {
        let provider = dispatch_with_api("openai-codex-responses")
            .expect("Api::OpenAiCodexResponses must dispatch to a transport");
        let _ = provider;
    }

    #[test]
    fn dispatch_openai_codex_responses_with_options_returns_some() {
        let provider = dispatch_with_options_api("openai-codex-responses")
            .expect("Api::OpenAiCodexResponses must dispatch via _with_options path");
        let _ = provider;
    }

    #[test]
    fn dispatch_google_gemini_cli_returns_some() {
        let provider = dispatch_with_api("google-gemini-cli")
            .expect("Api::GoogleGeminiCli must dispatch to a transport");
        let _ = provider;
    }

    #[test]
    fn dispatch_google_gemini_cli_with_options_returns_some() {
        let provider = dispatch_with_options_api("google-gemini-cli")
            .expect("Api::GoogleGeminiCli must dispatch via _with_options path");
        let _ = provider;
    }

    #[test]
    fn gemini_cli_transport_emits_not_implemented_error() {
        use crate::{Context, Model, ProviderError, StreamOptions};
        let provider: Box<dyn crate::Provider> = dispatch_with_api("google-gemini-cli")
            .expect("Api::GoogleGeminiCli must dispatch to a transport");

        let model = Model::new(
            "gemini-cli-test",
            "Gemini CLI Test Model",
            Api::GoogleGeminiCli,
            "google-gemini-cli",
            "http://127.0.0.1:1",
        );
        let context = Context::new();
        let options = StreamOptions::default();

        let result = futures::executor::block_on(provider.stream(&model, &context, Some(options)));
        match result {
            Err(ProviderError::NotImplemented(name)) => {
                assert!(
                    name.to_lowercase().contains("gemini"),
                    "NotImplemented error name should mention gemini, got: {name}"
                );
            }
            Ok(_) => panic!(
                "Gemini CLI transport must NOT fake success — stream() must return NotImplemented"
            ),
            Err(other) => panic!("Gemini CLI stream must return NotImplemented, got: {other:?}"),
        }
    }
}