Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! 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),
);
}
}