Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
33.4 KB
Raw Blame
//! Provider factory.
//!
//! Maps the user-visible `ProviderChoice` + env config into a
//! concrete `Arc<dyn LlmProvider>`.

use std::sync::Arc;

use secrecy::{ExposeSecret, SecretString};

use crate::AnthropicProvider;
use crate::CodexProvider;
use crate::CopilotEmbedder;
use crate::CopilotProvider;
use crate::CursorAgentProvider;
use crate::GeminiProvider;
use crate::OpenAiCompatProvider;
use crate::OpenAiOAuthProvider;
use crate::OpenAiProvider;
use crate::OpenCodeProvider;
use crate::auth::{AuthRequirement, CopilotAuth, ProviderAuth};
use crate::embedding::{Embedder, OpenAiCompatEmbedder, OpenAiEmbedder, VoyageEmbedder};
use crate::error::{LlmError, LlmResult};
use crate::google::GoogleEmbedder;
use crate::openai::REQUEST_ID_HEADER;
use crate::provider::LlmProvider;

/// LLM providers available to ai-memory.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProviderChoice {
    /// Anthropic Messages API.
    Anthropic,
    /// OpenAI Chat Completions.
    OpenAi,
    /// Google Gemini (Generative Language API).
    Gemini,
    /// OpenAI-compatible (Ollama / vLLM / LM Studio).
    OpenAiCompat,
    /// OpenAI ChatGPT/Codex OAuth backend.
    OpenAiOAuth,
    /// Codex CLI-owned auth with refresh delegated to `codex app-server`.
    Codex,
    /// GitHub Copilot Chat backend.
    Copilot,
    /// Anthropic Messages API via a Claude-subscription OAuth token.
    AnthropicOAuth,
    /// OpenCode cloud API (OpenAI-compatible endpoint). Defaults to the Go
    /// endpoint; `base_url` selects Zen's general catalogue instead.
    OpenCode,
    /// Cursor subscription via the logged-in `agent` CLI (`--print --mode ask`).
    Cursor,
}

impl ProviderChoice {
    /// Wire-format provider name.
    #[must_use]
    pub const fn name(self) -> &'static str {
        match self {
            Self::Anthropic => "anthropic",
            Self::OpenAi => "openai",
            Self::Gemini => "gemini",
            Self::OpenAiCompat => "openai-compat",
            Self::OpenAiOAuth => "openai-oauth",
            Self::Codex => "codex",
            Self::Copilot => "copilot",
            Self::AnthropicOAuth => "anthropic-oauth",
            Self::OpenCode => "opencode",
            Self::Cursor => "cursor",
        }
    }

    /// Auth requirement for this provider.
    #[must_use]
    pub const fn auth_requirement(self) -> AuthRequirement {
        match self {
            Self::Anthropic => AuthRequirement::RequiredApiKey {
                env_var: "ANTHROPIC_API_KEY",
            },
            Self::OpenAi => AuthRequirement::RequiredApiKey {
                env_var: "OPENAI_API_KEY",
            },
            Self::Gemini => AuthRequirement::RequiredApiKey {
                env_var: "GEMINI_API_KEY",
            },
            Self::OpenAiCompat => AuthRequirement::OptionalApiKey {
                env_var: "LLM_API_KEY",
            },
            Self::OpenAiOAuth => AuthRequirement::OpenAiOAuthToken,
            Self::Codex => AuthRequirement::CodexAuthFile,
            Self::Copilot => AuthRequirement::CopilotToken,
            Self::AnthropicOAuth => AuthRequirement::AnthropicOAuthToken,
            Self::OpenCode => AuthRequirement::RequiredApiKey {
                env_var: "OPENCODE_API_KEY",
            },
            Self::Cursor => AuthRequirement::CursorCli,
        }
    }

    /// Whether the operator, rather than the vendor, decides where this
    /// provider's endpoint lives.
    ///
    /// True for the self-hosted / aggregator dialects: `openai-compat` has
    /// no endpoint at all without one, and `opencode` reaches Zen's general
    /// catalogue only through an override. Every other provider talks to a
    /// fixed vendor host, and a base URL aimed elsewhere does not speak its
    /// dialect — a Gemini request against an Ollama host is a 404, not a
    /// degraded answer. Callers use this to decide whether an *ambient*
    /// base URL (the cross-tool `LLM_BASE_URL` convention) may configure the
    /// provider; an explicit ai-memory setting always may.
    #[must_use]
    pub const fn endpoint_is_operator_chosen(self) -> bool {
        matches!(self, Self::OpenAiCompat | Self::OpenCode)
    }
}

/// All settings needed to construct one LLM provider instance.
#[derive(Debug, Clone)]
pub struct ProviderConfig {
    /// Provider selection.
    pub provider: ProviderChoice,
    /// Model id (`claude-opus-4-7`, `gpt-4o-mini`, `llama3.1:8b`, …).
    pub model: String,
    /// Resolved provider authentication material.
    pub auth: ProviderAuth,
    /// Base URL override (required for OpenAI-compat).
    pub base_url: Option<String>,
    /// Strict mode for the `openai-compat` provider: send
    /// `response_format=json_schema` instead of the tolerant prose-JSON
    /// parser. Enabled by default and ignored by every other provider.
    /// Sourced once from `AI_MEMORY_LLM_COMPAT_STRICT` by `Config::load`.
    pub compat_strict: bool,
    /// OpenAI-compat only: send
    /// `chat_template_kwargs: {"enable_thinking": false}` with every chat
    /// request, for thinking-capable local engines (vLLM / SGLang serving
    /// Qwen3-class models) that would otherwise spend the output budget on
    /// a reasoning pass and truncate the structured payload. Opt-in, off
    /// by default, ignored by every other provider. Sourced once from
    /// `AI_MEMORY_LLM_COMPAT_DISABLE_THINKING` by `Config::load`.
    pub compat_disable_thinking: bool,
    /// Per-request timeout for every chat provider, in seconds.
    /// Sourced once from `AI_MEMORY_LLM_TIMEOUT_SECS` by `Config::load`;
    /// defaults to [`crate::DEFAULT_REQUEST_TIMEOUT_SECS`].
    pub request_timeout_secs: u64,
    /// Optional reasoning / thinking effort. Each provider maps this to
    /// its native request field (OpenAI `reasoning_effort`, OpenRouter
    /// `reasoning`, xAI Grok `reasoning_effort`, Anthropic
    /// `output_config.effort`, Codex `reasoning.effort`). `None` omits
    /// the field so the model default applies. Gemini and Copilot ignore it.
    pub reasoning_effort: Option<crate::ReasoningEffort>,
    /// Operator-supplied HTTP headers sent on every chat request. Gateways
    /// that require a caller-identifying header (OpenCode asks for
    /// `x-opencode-session` and a specific `User-Agent`) are configured
    /// through this rather than per-provider special cases. Parsed once from
    /// `AI_MEMORY_LLM_HEADERS` by `Config::load`; empty by default.
    pub extra_headers: crate::ExtraHeaders,
}

/// Embedding providers available to ai-memory.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EmbedderChoice {
    /// OpenAI Embeddings API.
    OpenAi,
    /// Voyage Embeddings API.
    Voyage,
    /// Google Gemini Embeddings API (`embedContent`).
    Google,
    /// OpenAI-compatible embeddings endpoint (Ollama / LM Studio /
    /// vLLM). Keyless-capable; base URL, model, and dim are required.
    OpenAiCompat,
    /// In-process pure-Rust embeddings (all-MiniLM-L6-v2, 384-dim) —
    /// no API key, no server. Requires the model files under
    /// `<data_dir>/models/` (fetched at serve startup or dropped in
    /// manually; docs/local-embeddings.md).
    #[cfg(feature = "local-embeddings")]
    Local,
    /// GitHub Copilot's OpenAI-compatible `/embeddings` endpoint. Reuses the
    /// Copilot OAuth login (no separate API key).
    Copilot,
}

impl EmbedderChoice {
    /// Wire-format provider name; matches what the `Embedder::provider`
    /// implementations return so the refuse-on-mismatch query lines up.
    #[must_use]
    pub const fn name(self) -> &'static str {
        match self {
            Self::OpenAi => "openai",
            Self::Voyage => "voyage",
            Self::Google => "google",
            Self::OpenAiCompat => "openai-compat",
            #[cfg(feature = "local-embeddings")]
            Self::Local => "local",
            Self::Copilot => "copilot",
        }
    }
}

/// Settings to build an embedder.
#[derive(Debug, Clone)]
pub struct EmbedderConfig {
    /// Provider selection.
    pub provider: EmbedderChoice,
    /// Model id (e.g. `text-embedding-3-small`).
    pub model: String,
    /// Vector dimensionality. Refused on mismatch with the stored
    /// pages' dim.
    pub dim: u32,
    /// API key. An empty value selects keyless `openai-compat`; hosted
    /// providers require a non-empty key from the CLI configuration boundary.
    pub api_key: SecretString,
    /// Optional base URL override. Required for openai-compat.
    pub base_url: Option<String>,
    /// `<data_dir>/models/` root, required by the `local` provider.
    pub models_dir: Option<std::path::PathBuf>,
    /// Resolved Copilot auth, required by the `copilot` provider. `None`
    /// for every other provider.
    pub copilot_auth: Option<CopilotAuth>,
    /// True when no provider was configured and `local` was chosen as
    /// the 2.0 default. Best-effort semantics: a defaulted embedder
    /// that cannot fetch or load its model degrades to no-embedder with
    /// a warning instead of refusing to start; an explicitly configured
    /// one still fails hard.
    pub defaulted: bool,
    /// Prepended to every query text before embedding, ahead of the
    /// existing truncation. Empty (the default) is a no-op. Only the
    /// `openai` and `openai-compat` embedders apply it; other providers
    /// (`google` has its own built-in task-type asymmetry, `voyage`,
    /// `local`, `copilot`) ignore it. Needed for asymmetric self-hosted
    /// models whose publisher specifies a query-side instruction the
    /// OpenAI-compatible `/v1/embeddings` wire format has no field for.
    /// `nvidia/Nemotron-3-Embed-1B-BF16` and base E5 models
    /// (`intfloat/e5-base-v2`, multilingual E5, …) use a simple
    /// `"query: "` string; instruction-tuned E5 variants and
    /// Qwen3-Embedding instead need a full task-instruction string (their
    /// documents stay plain — leave `document_prefix` unset for those).
    pub query_prefix: String,
    /// Document-side counterpart of `query_prefix` (e.g. `"passage: "` for
    /// Nemotron-3-Embed / base E5 — not every model needs one; see
    /// `query_prefix`'s doc comment).
    pub document_prefix: String,
}

/// Construct an `Arc<dyn Embedder>` from the config.
///
/// # Errors
/// Returns [`LlmError::NotConfigured`] for a zero dimension or missing required
/// base URL; propagates HTTP-client construction errors.
pub fn build_embedder(config: EmbedderConfig) -> LlmResult<Arc<dyn Embedder>> {
    if config.dim == 0 {
        return Err(LlmError::NotConfigured(
            "AI_MEMORY_EMBEDDING_DIM must be greater than zero".into(),
        ));
    }
    let arc: Arc<dyn Embedder> = match config.provider {
        EmbedderChoice::OpenAi => {
            let mut e = OpenAiEmbedder::new(config.api_key, config.model, config.dim)?
                .with_prefixes(config.query_prefix, config.document_prefix);
            if let Some(url) = config.base_url {
                e = e.with_base_url(url);
            }
            Arc::new(e)
        }
        EmbedderChoice::Voyage => {
            let mut e = VoyageEmbedder::new(config.api_key, config.model, config.dim)?;
            if let Some(url) = config.base_url {
                e = e.with_base_url(url);
            }
            Arc::new(e)
        }
        EmbedderChoice::Google => {
            let mut e = GoogleEmbedder::new(config.api_key, config.model, config.dim)?;
            if let Some(url) = config.base_url {
                e = e.with_base_url(url);
            }
            Arc::new(e)
        }
        EmbedderChoice::OpenAiCompat => {
            let base = config
                .base_url
                .ok_or_else(|| LlmError::NotConfigured("AI_MEMORY_EMBEDDING_BASE_URL".into()))?;
            let api_key = (!config.api_key.expose_secret().is_empty()).then_some(config.api_key);
            Arc::new(
                OpenAiCompatEmbedder::new(base, api_key, config.model, config.dim)?
                    .with_prefixes(config.query_prefix, config.document_prefix),
            )
        }
        #[cfg(feature = "local-embeddings")]
        EmbedderChoice::Local => {
            let models_dir = config.models_dir.ok_or_else(|| {
                LlmError::NotConfigured("local embeddings need the data dir's models/ root".into())
            })?;
            Arc::new(crate::local::LocalEmbedder::load(&models_dir)?)
        }
        EmbedderChoice::Copilot => {
            let auth = config.copilot_auth.ok_or_else(|| {
                LlmError::NotConfigured("copilot embedding provider requires Copilot auth".into())
            })?;
            Arc::new(CopilotEmbedder::new(auth, config.model, config.dim)?)
        }
    };
    Ok(arc)
}

/// Default dim for known embedding models. Used when the operator omits
/// `AI_MEMORY_EMBEDDING_DIM`. `openai-compat` has no safe default and returns
/// zero; new callers should use [`try_default_embedding_dim`] when accepting
/// that provider.
#[must_use]
pub fn default_embedding_dim(provider: EmbedderChoice, model: &str) -> u32 {
    try_default_embedding_dim(provider, model).unwrap_or(0)
}

/// Return the model-family embedding dimension when ai-memory has a safe
/// default. Self-hosted OpenAI-compatible models require an explicit value.
#[must_use]
pub fn try_default_embedding_dim(provider: EmbedderChoice, model: &str) -> Option<u32> {
    match (provider, model) {
        (EmbedderChoice::OpenAi, "text-embedding-3-small") => Some(1536),
        (EmbedderChoice::OpenAi, "text-embedding-3-large") => Some(3072),
        (EmbedderChoice::OpenAi, _) => Some(1536),
        (EmbedderChoice::Voyage, "voyage-3-large") => Some(1024),
        (EmbedderChoice::Voyage, _) => Some(1024),
        #[cfg(feature = "local-embeddings")]
        (EmbedderChoice::Local, _) => Some(crate::local::LOCAL_DIM),
        (EmbedderChoice::Google, "gemini-embedding-2") => Some(768),
        (EmbedderChoice::Google, "gemini-embedding-001") => Some(768),
        (EmbedderChoice::Google, _) => Some(768),
        (EmbedderChoice::OpenAiCompat, _) => None,
        (EmbedderChoice::Copilot, _) => Some(crate::copilot::COPILOT_DEFAULT_EMBED_DIM),
    }
}

/// Layer [`crate::DEFAULT_USER_AGENT`] under the operator's headers so every
/// provider request identifies ai-memory, while an explicit
/// `AI_MEMORY_LLM_HEADERS` entry still wins.
///
/// Copilot is excluded: its client and per-request headers both carry
/// [`crate::COPILOT_USER_AGENT`], the editor-plugin agent GitHub's Copilot
/// API expects, and `ExtraHeaders` replaces rather than appends — so a
/// default here would silently break that provider.
fn with_default_user_agent(
    provider: ProviderChoice,
    mut headers: crate::ExtraHeaders,
) -> crate::ExtraHeaders {
    if provider != ProviderChoice::Copilot {
        headers.set_default(
            reqwest::header::USER_AGENT,
            reqwest::header::HeaderValue::from_static(crate::DEFAULT_USER_AGENT),
        );
    }
    headers
}

/// Layer OpenRouter's app-attribution headers (`HTTP-Referer`, `X-Title`)
/// under the operator's headers when the `openai-compat` base URL points at
/// OpenRouter, so ai-memory's usage shows up on OpenRouter's app leaderboard
/// without requiring `AI_MEMORY_LLM_HEADERS` configuration. An explicit
/// operator entry for either header still wins, same precedence as the
/// default user agent.
fn with_default_openrouter_headers(
    base_url: &str,
    mut headers: crate::ExtraHeaders,
) -> crate::ExtraHeaders {
    if crate::openai::is_openrouter_base(base_url) {
        headers.set_default(
            reqwest::header::HeaderName::from_static("http-referer"),
            reqwest::header::HeaderValue::from_static(crate::OPENROUTER_HTTP_REFERER),
        );
        headers.set_default(
            reqwest::header::HeaderName::from_static("x-title"),
            reqwest::header::HeaderValue::from_static(crate::OPENROUTER_X_TITLE),
        );
    }
    headers
}

/// Construct an `Arc<dyn LlmProvider>` matching the config.
///
/// # Errors
/// Returns [`LlmError::NotConfigured`] if a required env value (API
/// key, base URL) is missing.
pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>> {
    let timeout = config.request_timeout_secs;
    let extra_headers = with_default_user_agent(config.provider, config.extra_headers);
    match config.provider {
        ProviderChoice::Anthropic => {
            let key = config.auth.require_api_key()?;
            let mut provider = AnthropicProvider::new(key, config.model)?;
            if let Some(url) = config.base_url {
                provider = provider.with_base_url(url);
            }
            Ok(Arc::new(
                provider
                    .with_timeout_secs(timeout)
                    .with_reasoning_effort(config.reasoning_effort)
                    .with_extra_headers(extra_headers),
            ))
        }
        ProviderChoice::OpenAi => {
            let key = config.auth.require_api_key()?;
            let mut provider = OpenAiProvider::new(key, config.model)?;
            if let Some(url) = config.base_url {
                provider = provider.with_base_url(url);
            }
            Ok(Arc::new(
                provider
                    .with_timeout_secs(timeout)
                    .with_reasoning_effort(config.reasoning_effort)
                    .with_extra_headers(extra_headers),
            ))
        }
        ProviderChoice::Gemini => {
            let key = config.auth.require_api_key()?;
            let mut provider = GeminiProvider::new(key, config.model)?;
            if let Some(url) = config.base_url {
                provider = provider.with_base_url(url);
            }
            Ok(Arc::new(
                provider
                    .with_timeout_secs(timeout)
                    .with_extra_headers(extra_headers),
            ))
        }
        ProviderChoice::OpenAiCompat => {
            let base = config
                .base_url
                .ok_or_else(|| LlmError::NotConfigured("LLM_BASE_URL".into()))?;
            // The openai-compat provider sends `x-request-id` itself, with
            // the logical operation id on every chat attempt. A static
            // operator value cannot serve that role, and `reqwest` would
            // append a second value; refuse the conflict at startup, the
            // same fail-closed way reserved headers are refused.
            if extra_headers.contains(REQUEST_ID_HEADER) {
                return Err(LlmError::NotConfigured(format!(
                    "AI_MEMORY_LLM_HEADERS must not set {REQUEST_ID_HEADER}: the \
                     openai-compat provider sends it itself on every chat attempt \
                     with the logical operation id"
                )));
            }
            let extra_headers = with_default_openrouter_headers(&base, extra_headers);
            Ok(Arc::new(
                OpenAiCompatProvider::new(base, config.auth.optional_api_key(), config.model)?
                    .with_strict(config.compat_strict)
                    .with_disable_thinking(config.compat_disable_thinking)
                    .with_timeout_secs(timeout)
                    .with_reasoning_effort(config.reasoning_effort)
                    .with_extra_headers(extra_headers)
                    .with_request_id_header(),
            ))
        }
        ProviderChoice::OpenAiOAuth => {
            let path = config.auth.require_openai_oauth_token_file()?.to_path_buf();
            Ok(Arc::new(
                OpenAiOAuthProvider::new(path, config.model)?
                    .with_timeout_secs(timeout)
                    .with_reasoning_effort(config.reasoning_effort)
                    .with_extra_headers(extra_headers),
            ))
        }
        ProviderChoice::Codex => {
            let auth = config.auth.require_codex_auth()?;
            Ok(Arc::new(
                CodexProvider::new(auth, config.model)?
                    .with_timeout_secs(timeout)
                    .with_reasoning_effort(config.reasoning_effort)
                    .with_extra_headers(extra_headers),
            ))
        }
        ProviderChoice::Copilot => {
            let auth = config.auth.require_copilot_auth()?;
            Ok(Arc::new(
                CopilotProvider::new(auth, config.model)?
                    .with_timeout_secs(timeout)
                    .with_extra_headers(extra_headers),
            ))
        }
        ProviderChoice::AnthropicOAuth => {
            let token = config.auth.require_anthropic_oauth_token()?;
            let mut provider = AnthropicProvider::new_oauth(token, config.model)?;
            if let Some(url) = config.base_url {
                provider = provider.with_base_url(url);
            }
            Ok(Arc::new(
                provider
                    .with_timeout_secs(timeout)
                    .with_reasoning_effort(config.reasoning_effort)
                    .with_extra_headers(extra_headers),
            ))
        }
        ProviderChoice::Cursor => {
            let auth = config.auth.require_cursor_auth()?;
            Ok(Arc::new(
                CursorAgentProvider::new(auth, config.model).with_timeout_secs(timeout),
            ))
        }
        ProviderChoice::OpenCode => {
            let key = config.auth.require_api_key()?;
            // Defaults to Go; an operator reaches Zen's general catalogue
            // through AI_MEMORY_LLM_BASE_URL. Silently dropping the override
            // (as this arm used to) left `provider=opencode` unable to speak
            // to anything but Go.
            let mut provider = OpenCodeProvider::new(key, config.model)?;
            if let Some(url) = config.base_url {
                provider = provider.with_base_url(url);
            }
            Ok(Arc::new(
                provider
                    // Go's Chat Completions catalogue supports JSON Schema;
                    // the wrapper falls back only when a model explicitly
                    // rejects the parameter or returns an unparsable shape.
                    .with_strict(true)
                    .with_timeout_secs(timeout)
                    .with_reasoning_effort(config.reasoning_effort)
                    .with_extra_headers(extra_headers),
            ))
        }
    }
}

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

    // Exhaustive on purpose: adding a provider must be a decision about whose
    // endpoint it is, not a default inherited from whichever arm was copied.
    #[test]
    fn only_the_operator_supplied_dialects_accept_an_ambient_base_url() {
        for choice in [ProviderChoice::OpenAiCompat, ProviderChoice::OpenCode] {
            assert!(
                choice.endpoint_is_operator_chosen(),
                "{} has no endpoint without an operator-supplied one",
                choice.name()
            );
        }
        for choice in [
            ProviderChoice::Anthropic,
            ProviderChoice::OpenAi,
            ProviderChoice::Gemini,
            ProviderChoice::OpenAiOAuth,
            ProviderChoice::Copilot,
            ProviderChoice::AnthropicOAuth,
            ProviderChoice::Codex,
            ProviderChoice::Cursor,
        ] {
            assert!(
                !choice.endpoint_is_operator_chosen(),
                "{} talks to a fixed vendor host",
                choice.name()
            );
        }
    }

    #[test]
    fn provider_choices_declare_current_auth_requirements() {
        assert_eq!(
            ProviderChoice::Anthropic.auth_requirement(),
            AuthRequirement::RequiredApiKey {
                env_var: "ANTHROPIC_API_KEY"
            }
        );
        assert_eq!(
            ProviderChoice::OpenAi.auth_requirement(),
            AuthRequirement::RequiredApiKey {
                env_var: "OPENAI_API_KEY"
            }
        );
        assert_eq!(
            ProviderChoice::Gemini.auth_requirement(),
            AuthRequirement::RequiredApiKey {
                env_var: "GEMINI_API_KEY"
            }
        );
        assert_eq!(
            ProviderChoice::OpenAiCompat.auth_requirement(),
            AuthRequirement::OptionalApiKey {
                env_var: "LLM_API_KEY"
            }
        );
        assert_eq!(
            ProviderChoice::OpenAiOAuth.auth_requirement(),
            AuthRequirement::OpenAiOAuthToken
        );
        assert_eq!(ProviderChoice::Codex.name(), "codex");
        assert_eq!(
            ProviderChoice::Codex.auth_requirement(),
            AuthRequirement::CodexAuthFile
        );
        assert_eq!(
            ProviderChoice::Copilot.auth_requirement(),
            AuthRequirement::CopilotToken
        );
        assert_eq!(
            ProviderChoice::AnthropicOAuth.auth_requirement(),
            AuthRequirement::AnthropicOAuthToken
        );
        assert_eq!(ProviderChoice::Cursor.name(), "cursor");
        assert_eq!(
            ProviderChoice::Cursor.auth_requirement(),
            AuthRequirement::CursorCli
        );
    }

    /// `reqwest` sends no `User-Agent` unless configured, which left every
    /// ai-memory provider request anonymous.
    #[test]
    fn default_user_agent_is_layered_under_operator_headers() {
        let headers =
            with_default_user_agent(ProviderChoice::OpenCode, crate::ExtraHeaders::default());
        assert_eq!(headers.get("user-agent"), Some(crate::DEFAULT_USER_AGENT));
    }

    #[test]
    fn an_operator_user_agent_wins_over_the_default() {
        let operator = crate::ExtraHeaders::parse(["user-agent: ai-memory-fork/9"]).unwrap();
        let headers = with_default_user_agent(ProviderChoice::OpenAi, operator);
        assert_eq!(headers.get("user-agent"), Some("ai-memory-fork/9"));
    }

    /// GitHub's Copilot API expects the editor-plugin agent; `ExtraHeaders`
    /// replaces rather than appends, so a default here would break it.
    #[test]
    fn copilot_is_left_with_its_editor_plugin_user_agent() {
        let headers =
            with_default_user_agent(ProviderChoice::Copilot, crate::ExtraHeaders::default());
        assert_eq!(headers.get("user-agent"), None);
    }

    /// "Properly identifies itself (no broad user agents)" means naming
    /// ai-memory and a version — never impersonating another client.
    #[test]
    fn default_user_agent_names_ai_memory_with_a_version() {
        let ua = crate::DEFAULT_USER_AGENT;
        assert!(ua.starts_with("ai-memory/"), "{ua}");
        assert!(ua.len() > "ai-memory/".len(), "{ua} carries no version");
        assert!(!ua.contains("opencode"), "{ua} impersonates another client");
    }

    /// OpenRouter attributes usage on its app leaderboard by these headers;
    /// without a default, a plain `openai-compat` setup pointed at
    /// OpenRouter would arrive unattributed.
    #[test]
    fn openrouter_app_headers_are_layered_for_an_openrouter_base_url() {
        let headers = with_default_openrouter_headers(
            "https://openrouter.ai/api/v1",
            crate::ExtraHeaders::default(),
        );
        assert_eq!(
            headers.get("http-referer"),
            Some(crate::OPENROUTER_HTTP_REFERER)
        );
        assert_eq!(headers.get("x-title"), Some(crate::OPENROUTER_X_TITLE));
    }

    /// A self-hosted `openai-compat` endpoint (Ollama, vLLM, LM Studio) has
    /// no leaderboard to attribute to, so it must not receive these.
    #[test]
    fn openrouter_app_headers_are_absent_for_a_non_openrouter_base_url() {
        let headers = with_default_openrouter_headers(
            "http://localhost:11434/v1",
            crate::ExtraHeaders::default(),
        );
        assert_eq!(headers.get("http-referer"), None);
        assert_eq!(headers.get("x-title"), None);
    }

    #[test]
    fn an_operator_http_referer_wins_over_the_openrouter_default() {
        let operator = crate::ExtraHeaders::parse(["http-referer: https://example.com"]).unwrap();
        let headers = with_default_openrouter_headers("https://openrouter.ai/api/v1", operator);
        assert_eq!(headers.get("http-referer"), Some("https://example.com"));
        assert_eq!(headers.get("x-title"), Some(crate::OPENROUTER_X_TITLE));
    }

    #[test]
    fn missing_required_provider_auth_preserves_error_shape() {
        let cfg = ProviderConfig {
            provider: ProviderChoice::OpenAi,
            model: "gpt-4o-mini".into(),
            auth: ProviderAuth::required_api_key_from_env("OPENAI_API_KEY", None),
            base_url: None,
            compat_strict: false,
            compat_disable_thinking: false,
            request_timeout_secs: crate::DEFAULT_REQUEST_TIMEOUT_SECS,
            reasoning_effort: None,
            extra_headers: crate::ExtraHeaders::default(),
        };

        let err = match build_provider(cfg) {
            Ok(_) => panic!("provider should fail without OPENAI_API_KEY"),
            Err(err) => err,
        };
        assert!(matches!(err, LlmError::NotConfigured(msg) if msg == "OPENAI_API_KEY"));
    }

    fn compat_config(extra_headers: crate::ExtraHeaders) -> ProviderConfig {
        ProviderConfig {
            provider: ProviderChoice::OpenAiCompat,
            model: "qwen3.8-27b".into(),
            auth: ProviderAuth::optional_api_key_from_env("LLM_API_KEY", None),
            base_url: Some("http://127.0.0.1:11434/v1".into()),
            compat_strict: true,
            compat_disable_thinking: false,
            request_timeout_secs: crate::DEFAULT_REQUEST_TIMEOUT_SECS,
            reasoning_effort: None,
            extra_headers,
        }
    }

    /// A static `x-request-id` in `AI_MEMORY_LLM_HEADERS` cannot coexist
    /// with the dynamic one — the conflict is refused at startup, before
    /// any send, rather than letting two values (or the operator's stale
    /// value) reach the gateway.
    #[test]
    fn openai_compat_refuses_a_static_request_id_header() {
        let headers = crate::ExtraHeaders::parse(["x-request-id: static-1"]).expect("valid");
        let err = match build_provider(compat_config(headers)) {
            Ok(_) => panic!("the conflicting entry must be refused at startup"),
            Err(err) => err,
        };
        let rendered = err.to_string();
        assert!(matches!(err, LlmError::NotConfigured(_)), "{rendered}");
        assert!(rendered.contains(REQUEST_ID_HEADER), "{rendered}");
        assert!(rendered.contains("openai-compat"), "{rendered}");
    }

    /// Case insensitivity is on the wire: a mixed-case operator entry is the
    /// same conflict and gets the same refusal.
    #[test]
    fn openai_compat_refuses_a_mixed_case_static_request_id_header() {
        let headers = crate::ExtraHeaders::parse(["X-Request-Id: static-1"]).expect("valid");
        assert!(
            build_provider(compat_config(headers)).is_err(),
            "the wire treats header names case-insensitively"
        );
    }

    /// The refusal is scoped to the provider that owns the header: the same
    /// static entry is a legitimate operator configuration everywhere else.
    #[test]
    fn a_static_request_id_header_is_allowed_for_other_providers() {
        let headers = crate::ExtraHeaders::parse(["x-request-id: static-1"]).expect("valid");
        let cfg = ProviderConfig {
            provider: ProviderChoice::OpenAi,
            model: "gpt-4o-mini".into(),
            auth: ProviderAuth::required_api_key_from_env(
                "OPENAI_API_KEY",
                Some(secrecy::SecretString::from("sk-test")),
            ),
            base_url: None,
            compat_strict: false,
            compat_disable_thinking: false,
            request_timeout_secs: crate::DEFAULT_REQUEST_TIMEOUT_SECS,
            reasoning_effort: None,
            extra_headers: headers,
        };
        assert!(
            build_provider(cfg).is_ok(),
            "only openai-compat owns the header"
        );
    }

    /// End to end: the provider the factory builds for the configured
    /// `openai-compat` choice sends exactly one `x-request-id` per chat
    /// attempt, carrying the operation's id — this is the gateway-facing
    /// contract the whole slice exists for.
    #[tokio::test]
    async fn the_factory_built_compat_provider_sends_the_operation_id() {
        let server = wiremock::MockServer::start().await;
        wiremock::Mock::given(wiremock::matchers::method("POST"))
            .and(wiremock::matchers::path("/v1/chat/completions"))
            .respond_with(
                wiremock::ResponseTemplate::new(200).set_body_json(serde_json::json!({
                    "model": "model-x",
                    "choices": [{ "message": { "content": "ok" } }],
                    "usage": { "prompt_tokens": 1, "completion_tokens": 1 },
                })),
            )
            .mount(&server)
            .await;

        let mut cfg = compat_config(crate::ExtraHeaders::default());
        cfg.base_url = Some(server.uri());
        let provider = build_provider(cfg).expect("provider builds");
        let operation_id = crate::LlmOperationId::new();
        provider
            .complete_with_operation_id(crate::ChatRequest::user_prompt("hi"), operation_id)
            .await
            .expect("completion succeeds");

        let requests = server.received_requests().await.expect("requests");
        assert_eq!(requests.len(), 1);
        assert_eq!(
            requests[0]
                .headers
                .get(REQUEST_ID_HEADER)
                .and_then(|value| value.to_str().ok()),
            Some(operation_id.to_string().as_str()),
        );
        assert_eq!(
            requests[0]
                .headers
                .get_all(REQUEST_ID_HEADER)
                .into_iter()
                .count(),
            1
        );
        // The layered defaults still apply alongside the new header.
        assert_eq!(
            requests[0]
                .headers
                .get(reqwest::header::USER_AGENT)
                .and_then(|value| value.to_str().ok()),
            Some(crate::DEFAULT_USER_AGENT),
        );
    }
}