Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(llm): send operator headers and identify ai-memory on every request
Lucas Oliveira53180c8d5177
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex fa882713..d57b06d7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- `AI_MEMORY_LLM_HEADERS` (`llm_headers` in `config.toml`) attaches extra+ HTTP headers to every LLM chat request, for gateways that require a+ caller-identifying header. Entries are `Name=Value` or `Name: Value`,+ comma separated in the env var. Parsed and validated once at the+ configuration boundary, so a malformed entry fails at startup rather than+ on the first consolidation pass, and providers consume typed header+ material instead of operator strings. Headers ai-memory sets itself+ (`authorization`, `content-type`, `x-api-key`, `x-goog-api-key`,+ `anthropic-version`, `anthropic-beta`, `openai-beta`, `host`,+ `content-length`) are refused: `reqwest` appends rather than replaces, so a+ duplicate would break the request instead of overriding it. Values are+ marked sensitive on the wire and never logged — the `Debug` output carries+ header names only.++### Changed+- Every LLM chat request now sends `User-Agent: ai-memory/<version>`.+ `reqwest` sends no user agent unless one is configured, so provider+ requests previously arrived anonymous, and gateways that require callers to+ identify themselves reported ai-memory as an unknown client. An+ `AI_MEMORY_LLM_HEADERS` entry for `user-agent` overrides it. The Copilot+ provider is unchanged: it keeps `GitHubCopilotChat/<version>`, the+ editor-plugin agent GitHub's Copilot API expects.+- The `opencode` provider now sends `x-opencode-session` on every request,+ defaulting to one id per process when `AI_MEMORY_LLM_HEADERS` does not+ supply one. OpenCode Zen/Go documents third-party access to its endpoints+ and asks callers to identify themselves and to send that header for+ request correlation; traffic without it is reported as unattributable.+ Set the header explicitly to keep the value stable across restarts or to+ tell several ai-memory instances apart.+### Fixed- `as_of` time-travel queries and the entity retrieval stream now workon real stores. Both read the entity index, which was populated onlydiff --git a/crates/ai-memory-cli/src/commands/llm_test.rs b/crates/ai-memory-cli/src/commands/llm_test.rsindex 382d345d..8a6c9475 100644--- a/crates/ai-memory-cli/src/commands/llm_test.rs+++ b/crates/ai-memory-cli/src/commands/llm_test.rs@@ -26,6 +26,9 @@ pub async fn run(config: &Config, args: LlmTestArgs) -> Result<()> {compat_strict: config.llm_compat_strict,request_timeout_secs: config.llm_timeout_secs,reasoning_effort: config.llm_reasoning_effort,+ extra_headers: config+ .llm_extra_headers()+ .context("parsing AI_MEMORY_LLM_HEADERS / llm_headers")?,};let client = build_provider(provider_config).context("building LLM provider")?;info!(diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 2249ad35..c358642f 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -9,8 +9,8 @@use std::path::{Path, PathBuf};use ai_memory_llm::{- AuthRequirement, EmbedderChoice, EmbedderConfig, LlmError, LlmResult, OPENCODE_DEFAULT_MODEL,- ProviderAuth, ProviderChoice, ProviderConfig, ReasoningEffort,+ AuthRequirement, EmbedderChoice, EmbedderConfig, ExtraHeaders, LlmError, LlmResult,+ OPENCODE_DEFAULT_MODEL, ProviderAuth, ProviderChoice, ProviderConfig, ReasoningEffort,};use anyhow::{Context, Result};use figment::{@@ -178,6 +178,22 @@ pub struct Config {/// `reasoning`, xAI Grok `reasoning_effort`, Anthropic/// `output_config.effort`, Codex `reasoning.effort`).pub llm_reasoning_effort: Option<ReasoningEffort>,+ /// Extra HTTP headers attached to every LLM chat request, as+ /// `Name: Value` (or `Name=Value`) entries. Empty by default.+ ///+ /// Exists for gateways that require a caller-identifying header:+ /// OpenCode Zen/Go asks callers for `x-opencode-session` plus a specific+ /// `User-Agent` and reports traffic carrying neither as an unknown+ /// client. Set with+ /// `AI_MEMORY_LLM_HEADERS=x-opencode-session=…,user-agent=…` (comma+ /// separated, so a header *value* cannot contain a comma — use+ /// `llm_headers` in `config.toml` for those) or `llm_headers = [...]`.+ ///+ /// Headers ai-memory sets itself (`authorization`, `content-type`,+ /// `x-api-key`, …) are refused at startup: `reqwest` appends rather than+ /// replaces, so a duplicate would break the request instead of+ /// overriding it. Values are never logged.+ pub llm_headers: Vec<String>,/// Opt-in: run LLM consolidation on SessionEnd (in addition to the/// always-written heuristic session page), when an LLM provider is/// configured. Off by default. Provider work is durably queued after the@@ -634,6 +650,7 @@ impl Default for Config {llm_compat_strict: true,llm_timeout_secs: ai_memory_llm::DEFAULT_REQUEST_TIMEOUT_SECS,llm_reasoning_effort: None,+ llm_headers: Vec::new(),consolidate_on_session_end: false,capture_assistant: false,strip_root_combinators: false,@@ -1032,6 +1049,13 @@ impl Config {config.llm_timeout_secs);}+ // Parsed (and discarded) here so a malformed header list is rejected+ // at startup rather than on the first consolidation pass. The typed+ // value is rebuilt by `llm_provider_config`: `ExtraHeaders` is not+ // serialisable, and `Config` must stay so.+ config+ .llm_extra_headers()+ .context("parsing AI_MEMORY_LLM_HEADERS / llm_headers")?;validate_auth_secrets(&config.auth)?;Ok(config)@@ -1043,11 +1067,22 @@ impl Config {self.server_url != DEFAULT_SERVER_URL || self.runtime_env.server_url.is_some()}+ /// Parse [`Self::llm_headers`] into typed header material.+ ///+ /// # Errors+ /// Returns [`LlmError::NotConfigured`] for an entry with no `Name: Value`+ /// separator, an invalid header name or value, or a header ai-memory+ /// sets itself.+ pub fn llm_extra_headers(&self) -> LlmResult<ExtraHeaders> {+ ExtraHeaders::parse(&self.llm_headers)+ }+/// Build the configured LLM provider settings, if LLM support is enabled.////// # Errors- /// Returns [`LlmError::NotConfigured`] for unknown providers or missing- /// provider-specific required values.+ /// Returns [`LlmError::NotConfigured`] for unknown providers, missing+ /// provider-specific required values, or a malformed+ /// [`Self::llm_headers`] entry.pub fn llm_provider_config(&self) -> LlmResult<Option<ProviderConfig>> {let Some(provider_raw) = non_empty(self.llm_provider.as_deref()) else {return Ok(None);@@ -1101,6 +1136,7 @@ impl Config {compat_strict: self.llm_compat_strict,request_timeout_secs: self.llm_timeout_secs,reasoning_effort: self.llm_reasoning_effort,+ extra_headers: self.llm_extra_headers()?,}))}@@ -1889,6 +1925,61 @@ mod tests {);}+ #[test]+ fn load_round_trips_llm_headers() {+ let tmp = TempDir::new().unwrap();+ let config_path = tmp.path().join("config.toml");+ std::fs::write(+ &config_path,+ "llm_headers = [\"x-opencode-session=ses-1\", \"x-tool: ai-memory\"]\n",+ )+ .unwrap();+ let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();+ assert_eq!(+ cfg.llm_headers,+ vec!["x-opencode-session=ses-1", "x-tool: ai-memory"]+ );+ }++ #[test]+ fn llm_headers_default_to_none_configured() {+ assert!(Config::default().llm_headers.is_empty());+ }++ /// Parsed during `load` so a typo surfaces at startup rather than on the+ /// first consolidation pass, hours later.+ #[test]+ fn load_rejects_a_malformed_llm_header() {+ let tmp = TempDir::new().unwrap();+ let config_path = tmp.path().join("config.toml");+ std::fs::write(&config_path, "llm_headers = [\"no-separator-here\"]\n").unwrap();+ let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))+ .expect_err("a malformed header entry must fail closed");+ assert!(+ error.to_string().contains("AI_MEMORY_LLM_HEADERS"),+ "unexpected error: {error:#}"+ );+ }++ /// A duplicate `authorization` would break provider auth rather than+ /// override it, so the boundary refuses it outright.+ #[test]+ fn load_rejects_an_llm_header_ai_memory_owns() {+ let tmp = TempDir::new().unwrap();+ let config_path = tmp.path().join("config.toml");+ std::fs::write(+ &config_path,+ "llm_headers = [\"authorization: Bearer x\"]\n",+ )+ .unwrap();+ let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))+ .expect_err("a reserved header must fail closed");+ assert!(+ format!("{error:#}").contains("set by ai-memory itself"),+ "unexpected error: {error:#}"+ );+ }+fn load_reasoning_effort(raw: &str) -> anyhow::Result<Config> {let tmp = TempDir::new().unwrap();let config_path = tmp.path().join("config.toml");@@ -2477,6 +2568,36 @@ mod tests {assert_eq!(provider.reasoning_effort, effort);}+ #[test]+ fn provider_config_forwards_the_operator_headers() {+ let tmp = TempDir::new().unwrap();+ let cfg = Config {+ data_dir: tmp.path().to_path_buf(),+ llm_provider: Some("opencode".into()),+ llm_headers: vec!["x-opencode-session=ses-1".into()],+ ..Config::default()+ };++ let provider = cfg.llm_provider_config().unwrap().unwrap();+ assert_eq!(+ provider.extra_headers,+ ExtraHeaders::parse(["x-opencode-session=ses-1"]).unwrap()+ );+ }++ #[test]+ fn provider_config_defaults_to_no_operator_headers() {+ let tmp = TempDir::new().unwrap();+ let cfg = Config {+ data_dir: tmp.path().to_path_buf(),+ llm_provider: Some("opencode".into()),+ ..Config::default()+ };++ let provider = cfg.llm_provider_config().unwrap().unwrap();+ assert_eq!(provider.extra_headers, ExtraHeaders::default());+ }+#[test]fn copilot_provider_uses_data_dir_token_file_and_env_token() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-llm/src/anthropic.rs b/crates/ai-memory-llm/src/anthropic.rsindex 1b2b2009..3e52f35e 100644--- a/crates/ai-memory-llm/src/anthropic.rs+++ b/crates/ai-memory-llm/src/anthropic.rs@@ -11,7 +11,7 @@ use tracing::debug;use crate::error::{LlmError, LlmResult};use crate::provider::LlmProvider;use crate::response::{provider_error_body, response_json_limited};-use crate::types::{ChatRequest, ChatResponse, ReasoningEffort, Usage};+use crate::types::{ChatRequest, ChatResponse, ExtraHeaders, ReasoningEffort, Usage};/// Default Anthropic API base.pub const DEFAULT_BASE_URL: &str = "https://api.anthropic.com";@@ -47,6 +47,7 @@ pub struct AnthropicProvider {model: String,timeout: Duration,reasoning_effort: Option<ReasoningEffort>,+ extra_headers: ExtraHeaders,}impl AnthropicProvider {@@ -64,6 +65,7 @@ impl AnthropicProvider {model: model.into(),timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),reasoning_effort: None,+ extra_headers: ExtraHeaders::default(),})}@@ -85,6 +87,7 @@ impl AnthropicProvider {model: model.into(),timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),reasoning_effort: None,+ extra_headers: ExtraHeaders::default(),})}@@ -111,6 +114,14 @@ impl AnthropicProvider {self.reasoning_effort = effort;self}++ /// Attach operator-configured headers to every chat request. The factory+ /// calls this with `ProviderConfig::extra_headers`.+ #[must_use]+ pub fn with_extra_headers(mut self, headers: ExtraHeaders) -> Self {+ self.extra_headers = headers;+ self+ }}#[derive(Debug, Serialize)]@@ -301,7 +312,7 @@ impl AnthropicProvider {for (name, value) in self.auth_headers() {builder = builder.header(name, value);}- let resp = builder.json(body).send().await?;+ let resp = self.extra_headers.apply(builder).json(body).send().await?;let status = resp.status();if !status.is_success() {let body = provider_error_body(resp).await;diff --git a/crates/ai-memory-llm/src/copilot.rs b/crates/ai-memory-llm/src/copilot.rsindex ee58ba42..c091caf9 100644--- a/crates/ai-memory-llm/src/copilot.rs+++ b/crates/ai-memory-llm/src/copilot.rs@@ -20,7 +20,7 @@ use crate::error::{LlmError, LlmResult};use crate::openai::{STRUCTURED_OUTPUT_SCHEMA_NAME, enforce_strict_object_schemas};use crate::provider::LlmProvider;use crate::response::{provider_error_body, response_json_limited};-use crate::types::{ChatRequest, ChatResponse, Usage};+use crate::types::{ChatRequest, ChatResponse, ExtraHeaders, Usage};/// GitHub Copilot's public OAuth client id used by Copilot clients.pub const GITHUB_COPILOT_CLIENT_ID: &str = "Iv1.b507a08c87ecfe98";@@ -186,6 +186,7 @@ pub struct CopilotProvider {auth: CopilotAuth,stored: Mutex<CopilotToken>,timeout: Duration,+ extra_headers: ExtraHeaders,}impl CopilotProvider {@@ -216,6 +217,7 @@ impl CopilotProvider {auth,stored: Mutex::new(stored),timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),+ extra_headers: ExtraHeaders::default(),})}@@ -228,6 +230,15 @@ impl CopilotProvider {self}+ /// Attach operator-configured headers to every chat request. The factory+ /// calls this with `ProviderConfig::extra_headers`. Replaces the client's+ /// default `user-agent` when the operator configures one.+ #[must_use]+ pub fn with_extra_headers(mut self, headers: ExtraHeaders) -> Self {+ self.extra_headers = headers;+ self+ }+async fn current_token(&self) -> LlmResult<CopilotApiToken> {if let Some(token) = self.auth.direct_api_token.as_ref() {return Ok(CopilotApiToken {@@ -284,16 +295,14 @@ impl CopilotProvider {let token = self.current_token().await?;let url = format!("{}/chat/completions", token.base_url.trim_end_matches('/'));debug!(url = %url, "POST copilot chat completions");- let resp = self- .client- .post(&url)- .timeout(self.timeout)- .bearer_auth(token.access.expose_secret())- .headers(copilot_runtime_headers())- .json(body)- .send()- .await- .map_err(LlmError::from)?;+ let request = self.extra_headers.apply(+ self.client+ .post(&url)+ .timeout(self.timeout)+ .bearer_auth(token.access.expose_secret())+ .headers(copilot_runtime_headers()),+ );+ let resp = request.json(body).send().await.map_err(LlmError::from)?;let status = resp.status();if !status.is_success() {let body = provider_error_body(resp).await;diff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rsindex abf8d5a1..ebc4f74f 100644--- a/crates/ai-memory-llm/src/factory.rs+++ b/crates/ai-memory-llm/src/factory.rs@@ -109,6 +109,12 @@ pub struct ProviderConfig {/// `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 Zen/Go 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.@@ -256,6 +262,27 @@ pub fn try_default_embedding_dim(provider: EmbedderChoice, model: &str) -> Optio}}+/// 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+}+/// Construct an `Arc<dyn LlmProvider>` matching the config.////// # Errors@@ -263,13 +290,15 @@ pub fn try_default_embedding_dim(provider: EmbedderChoice, model: &str) -> Optio/// 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()?;Ok(Arc::new(AnthropicProvider::new(key, config.model)?.with_timeout_secs(timeout)- .with_reasoning_effort(config.reasoning_effort),+ .with_reasoning_effort(config.reasoning_effort)+ .with_extra_headers(extra_headers),))}ProviderChoice::OpenAi => {@@ -277,7 +306,8 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>Ok(Arc::new(OpenAiProvider::new(key, config.model)?.with_timeout_secs(timeout)- .with_reasoning_effort(config.reasoning_effort),+ .with_reasoning_effort(config.reasoning_effort)+ .with_extra_headers(extra_headers),))}ProviderChoice::Gemini => {@@ -286,7 +316,11 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>if let Some(url) = config.base_url {provider = provider.with_base_url(url);}- Ok(Arc::new(provider.with_timeout_secs(timeout)))+ Ok(Arc::new(+ provider+ .with_timeout_secs(timeout)+ .with_extra_headers(extra_headers),+ ))}ProviderChoice::OpenAiCompat => {let base = config@@ -296,7 +330,8 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>OpenAiCompatProvider::new(base, config.auth.optional_api_key(), config.model)?.with_strict(config.compat_strict).with_timeout_secs(timeout)- .with_reasoning_effort(config.reasoning_effort),+ .with_reasoning_effort(config.reasoning_effort)+ .with_extra_headers(extra_headers),))}ProviderChoice::OpenAiOAuth => {@@ -304,13 +339,16 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>Ok(Arc::new(OpenAiOAuthProvider::new(path, config.model)?.with_timeout_secs(timeout)- .with_reasoning_effort(config.reasoning_effort),+ .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),+ CopilotProvider::new(auth, config.model)?+ .with_timeout_secs(timeout)+ .with_extra_headers(extra_headers),))}ProviderChoice::AnthropicOAuth => {@@ -322,7 +360,8 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>Ok(Arc::new(provider.with_timeout_secs(timeout)- .with_reasoning_effort(config.reasoning_effort),+ .with_reasoning_effort(config.reasoning_effort)+ .with_extra_headers(extra_headers),))}ProviderChoice::OpenCode => {@@ -330,7 +369,8 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>Ok(Arc::new(OpenCodeProvider::new(key, config.model)?.with_timeout_secs(timeout)- .with_reasoning_effort(config.reasoning_effort),+ .with_reasoning_effort(config.reasoning_effort)+ .with_extra_headers(extra_headers),))}}@@ -380,6 +420,41 @@ mod tests {);}+ /// `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");+ }+#[test]fn missing_required_provider_auth_preserves_error_shape() {let cfg = ProviderConfig {@@ -390,6 +465,7 @@ mod tests {compat_strict: false,request_timeout_secs: crate::DEFAULT_REQUEST_TIMEOUT_SECS,reasoning_effort: None,+ extra_headers: crate::ExtraHeaders::default(),};let err = match build_provider(cfg) {diff --git a/crates/ai-memory-llm/src/gemini.rs b/crates/ai-memory-llm/src/gemini.rsindex 23601c31..56ead252 100644--- a/crates/ai-memory-llm/src/gemini.rs+++ b/crates/ai-memory-llm/src/gemini.rs@@ -19,7 +19,7 @@ use tracing::debug;use crate::error::{LlmError, LlmResult};use crate::provider::LlmProvider;use crate::response::{provider_error_body, response_json_limited};-use crate::types::{ChatRequest, ChatResponse, Role, Usage};+use crate::types::{ChatRequest, ChatResponse, ExtraHeaders, Role, Usage};/// Default Gemini API base.pub const DEFAULT_BASE_URL: &str = "https://generativelanguage.googleapis.com";@@ -31,6 +31,7 @@ pub struct GeminiProvider {base_url: String,model: String,timeout: Duration,+ extra_headers: ExtraHeaders,}impl GeminiProvider {@@ -47,6 +48,7 @@ impl GeminiProvider {base_url: DEFAULT_BASE_URL.to_string(),model: model.into(),timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),+ extra_headers: ExtraHeaders::default(),})}@@ -64,6 +66,14 @@ impl GeminiProvider {self.timeout = Duration::from_secs(secs);self}++ /// Attach operator-configured headers to every chat request. The factory+ /// calls this with `ProviderConfig::extra_headers`.+ #[must_use]+ pub fn with_extra_headers(mut self, headers: ExtraHeaders) -> Self {+ self.extra_headers = headers;+ self+ }}#[derive(Debug, Serialize)]@@ -233,15 +243,14 @@ impl GeminiProvider {self.model);debug!(url, "POST gemini");- let resp = self- .client- .post(&url)- .timeout(self.timeout)- .header("x-goog-api-key", self.api_key.expose_secret())- .header("content-type", "application/json")- .json(body)- .send()- .await?;+ let request = self.extra_headers.apply(+ self.client+ .post(&url)+ .timeout(self.timeout)+ .header("x-goog-api-key", self.api_key.expose_secret())+ .header("content-type", "application/json"),+ );+ let resp = request.json(body).send().await?;let status = resp.status();if !status.is_success() {let body = provider_error_body(resp).await;diff --git a/crates/ai-memory-llm/src/lib.rs b/crates/ai-memory-llm/src/lib.rsindex e2778e23..8ed69944 100644--- a/crates/ai-memory-llm/src/lib.rs+++ b/crates/ai-memory-llm/src/lib.rs@@ -36,6 +36,22 @@/// (read once by `Config::load`, applied to every chat provider).pub const DEFAULT_REQUEST_TIMEOUT_SECS: u64 = 300;+/// `User-Agent` ai-memory sends on provider requests.+///+/// `reqwest` sends no `User-Agent` at all unless one is configured, so every+/// ai-memory provider request used to arrive anonymous. Gateways increasingly+/// require callers to identify themselves — OpenCode Zen/Go asks for a+/// specific agent ("no broad user agents") and reports traffic without one as+/// an unknown client — and an unattributable request is the one a rate+/// limiter throttles first.+///+/// Layered *under* `AI_MEMORY_LLM_HEADERS` by+/// [`factory::build_provider`], so an operator can still override it. The+/// Copilot provider keeps [`copilot::COPILOT_USER_AGENT`] instead: GitHub's+/// Copilot API expects the editor-plugin agent and rejects requests without+/// it.+pub const DEFAULT_USER_AGENT: &str = concat!("ai-memory/", env!("CARGO_PKG_VERSION"));+pub mod anthropic;pub mod auth;pub mod copilot;@@ -99,4 +115,6 @@ pub use opencode::{OPENCODE_DEFAULT_MODEL, OPENCODE_ZEN_BASE_URL, OpenCodeProvidpub use provider::{LlmProvider, complete_structured};pub use reranker::{LlmReranker, RerankCandidate, RerankScore, Reranker};pub use stored_token::StoredOAuthToken;-pub use types::{ChatMessage, ChatRequest, ChatResponse, ReasoningEffort, Role, Usage};+pub use types::{+ ChatMessage, ChatRequest, ChatResponse, ExtraHeaders, ReasoningEffort, Role, Usage,+};diff --git a/crates/ai-memory-llm/src/openai.rs b/crates/ai-memory-llm/src/openai.rsindex 7b951bf5..7ba9c32d 100644--- a/crates/ai-memory-llm/src/openai.rs+++ b/crates/ai-memory-llm/src/openai.rs@@ -11,7 +11,7 @@ use tracing::debug;use crate::error::{LlmError, LlmResult};use crate::provider::LlmProvider;use crate::response::{provider_error_body, response_json_limited};-use crate::types::{ChatRequest, ChatResponse, ReasoningEffort, Usage};+use crate::types::{ChatRequest, ChatResponse, ExtraHeaders, ReasoningEffort, Usage};/// Default OpenAI API base.pub const DEFAULT_BASE_URL: &str = "https://api.openai.com";@@ -91,6 +91,7 @@ pub struct OpenAiProvider {dialect: RequestDialect,timeout: Duration,reasoning_effort: Option<ReasoningEffort>,+ extra_headers: ExtraHeaders,}impl OpenAiProvider {@@ -110,6 +111,7 @@ impl OpenAiProvider {dialect: RequestDialect::Official,timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),reasoning_effort: None,+ extra_headers: ExtraHeaders::default(),})}@@ -153,6 +155,21 @@ impl OpenAiProvider {self.reasoning_effort = effort;self}++ /// Attach operator-configured headers to every chat request. The factory+ /// calls this with `ProviderConfig::extra_headers`.+ #[must_use]+ pub fn with_extra_headers(mut self, headers: ExtraHeaders) -> Self {+ self.extra_headers = headers;+ self+ }++ /// Headers this provider will send. Test-visible so the wrapper tests+ /// (`OpenAiCompatProvider`, `OpenCodeProvider`) can assert delegation.+ #[cfg(test)]+ pub(crate) fn extra_headers(&self) -> &ExtraHeaders {+ &self.extra_headers+ }}#[derive(Debug, Serialize)]@@ -362,15 +379,14 @@ impl OpenAiProvider {async fn post<B: Serialize>(&self, body: &B) -> LlmResult<OpenAiResponse> {let url = normalize_openai_base(&self.base_url, "chat/completions");debug!(url, "POST openai");- let resp = self- .client- .post(&url)- .timeout(self.timeout)- .bearer_auth(self.api_key.expose_secret())- .header("content-type", "application/json")- .json(body)- .send()- .await?;+ let request = self.extra_headers.apply(+ self.client+ .post(&url)+ .timeout(self.timeout)+ .bearer_auth(self.api_key.expose_secret())+ .header("content-type", "application/json"),+ );+ let resp = request.json(body).send().await?;let status = resp.status();if !status.is_success() {let body = provider_error_body(resp).await;diff --git a/crates/ai-memory-llm/src/openai_compat.rs b/crates/ai-memory-llm/src/openai_compat.rsindex 9a19f261..136b5954 100644--- a/crates/ai-memory-llm/src/openai_compat.rs+++ b/crates/ai-memory-llm/src/openai_compat.rs@@ -115,6 +115,23 @@ impl OpenAiCompatProvider {self.inner = self.inner.with_reasoning_effort(effort);self}++ /// Forward operator-configured headers to the inner client. Aggregators+ /// and gateways behind an OpenAI-compatible endpoint are the common case+ /// for caller-identifying headers.+ #[must_use]+ pub fn with_extra_headers(mut self, headers: crate::ExtraHeaders) -> Self {+ self.inner = self.inner.with_extra_headers(headers);+ self+ }++ /// Headers the inner client will send. Test-visible so the+ /// [`crate::OpenCodeProvider`] tests can assert its Zen/Go defaults+ /// survive delegation.+ #[cfg(test)]+ pub(crate) fn extra_headers(&self) -> &crate::ExtraHeaders {+ self.inner.extra_headers()+ }}#[async_trait]diff --git a/crates/ai-memory-llm/src/openai_oauth.rs b/crates/ai-memory-llm/src/openai_oauth.rsindex 1973512f..a89ed577 100644--- a/crates/ai-memory-llm/src/openai_oauth.rs+++ b/crates/ai-memory-llm/src/openai_oauth.rs@@ -22,7 +22,7 @@ use crate::provider::LlmProvider;use crate::response::{provider_error_body, response_json_limited, response_text_limited};use crate::stored_token::{StoredOAuthToken, refresh_grant};use crate::text::truncate_with_ellipsis;-use crate::types::{ChatRequest, ChatResponse, ReasoningEffort, Usage};+use crate::types::{ChatRequest, ChatResponse, ExtraHeaders, ReasoningEffort, Usage};/// OpenAI OAuth issuer used by Codex/OpenCode.pub const OPENAI_OAUTH_ISSUER: &str = "https://auth.openai.com";@@ -140,6 +140,7 @@ pub struct OpenAiOAuthProvider {token: Mutex<OpenAiOAuthToken>,timeout: Duration,reasoning_effort: Option<ReasoningEffort>,+ extra_headers: ExtraHeaders,}impl OpenAiOAuthProvider {@@ -162,6 +163,7 @@ impl OpenAiOAuthProvider {token: Mutex::new(token),timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),reasoning_effort: None,+ extra_headers: ExtraHeaders::default(),})}@@ -173,6 +175,14 @@ impl OpenAiOAuthProvider {self}+ /// Attach operator-configured headers to every chat request. The factory+ /// calls this with `ProviderConfig::extra_headers`.+ #[must_use]+ pub fn with_extra_headers(mut self, headers: ExtraHeaders) -> Self {+ self.extra_headers = headers;+ self+ }+/// Set Responses API `reasoning.effort`. `None` omits the field so the/// model default applies.#[must_use]@@ -216,6 +226,7 @@ impl OpenAiOAuthProvider {.header("originator", "codex_cli_rs").header("session_id", uuid::Uuid::new_v4().to_string()).json(body);+ request = self.extra_headers.apply(request);if let Some(account_id) = token.extra.account_id.as_deref() {request = request.header("chatgpt-account-id", account_id);}diff --git a/crates/ai-memory-llm/src/opencode.rs b/crates/ai-memory-llm/src/opencode.rsindex 88d0efd9..e148b971 100644--- a/crates/ai-memory-llm/src/opencode.rs+++ b/crates/ai-memory-llm/src/opencode.rs@@ -3,14 +3,23 @@//! Thin wrapper around [`OpenAiCompatProvider`] that bakes in the OpenCode//! Zen API base URL (`https://opencode.ai/zen/go/v1`) and names the provider//! `"opencode"`. Accepts an `sk-...` API key from `OPENCODE_API_KEY`.+//!+//! Zen/Go documents third-party access to these endpoints and asks every+//! tool using them to (1) not generate abusive traffic and (2) "properly+//! identify itself (no broad user agents)". The agent string is+//! [`crate::DEFAULT_USER_AGENT`], applied to every provider; what is+//! specific to this one is `x-opencode-session`, which Zen/Go correlates+//! requests by and which this provider defaults under anything the operator+//! set through `AI_MEMORY_LLM_HEADERS`.use async_trait::async_trait;+use reqwest::header::{HeaderName, HeaderValue};use secrecy::SecretString;use crate::error::LlmResult;use crate::openai_compat::OpenAiCompatProvider;use crate::provider::LlmProvider;-use crate::types::{ChatRequest, ChatResponse};+use crate::types::{ChatRequest, ChatResponse, ExtraHeaders};/// Public OpenCode Zen/Go OpenAI-compatible base URL.pub const OPENCODE_ZEN_BASE_URL: &str = "https://opencode.ai/zen/go/v1";@@ -18,6 +27,10 @@ pub const OPENCODE_ZEN_BASE_URL: &str = "https://opencode.ai/zen/go/v1";/// Default model when `AI_MEMORY_LLM_MODEL` is not set.pub const OPENCODE_DEFAULT_MODEL: &str = "claude-sonnet-4-6";+/// Session-correlation header Zen/Go asks callers to send. Requests arriving+/// without it are reported as unattributable and may be rejected.+pub const OPENCODE_SESSION_HEADER: &str = "x-opencode-session";+/// OpenCode Zen/Go LLM provider.////// Routes through `https://opencode.ai/zen/go/v1` using the OpenAI chat@@ -25,6 +38,11 @@ pub const OPENCODE_DEFAULT_MODEL: &str = "claude-sonnet-4-6";/// from <https://opencode.ai/auth>.pub struct OpenCodeProvider {inner: OpenAiCompatProvider,+ /// Sent as `x-opencode-session` unless the operator configured that+ /// header. Generated once per provider instance — the provider is built+ /// once per `serve` process, so a run's requests correlate to one id,+ /// which is what Zen/Go's metrics key on.+ session: HeaderValue,}impl OpenCodeProvider {@@ -33,8 +51,10 @@ impl OpenCodeProvider {/// # Errors/// Returns a `reqwest::Error` if the HTTP client cannot be built.pub fn new(api_key: SecretString, model: impl Into<String>) -> LlmResult<Self> {- let inner = OpenAiCompatProvider::new(OPENCODE_ZEN_BASE_URL, Some(api_key), model.into())?;- Ok(Self { inner })+ let session = new_session_id();+ let inner = OpenAiCompatProvider::new(OPENCODE_ZEN_BASE_URL, Some(api_key), model.into())?+ .with_extra_headers(with_session_default(&session, ExtraHeaders::default()));+ Ok(Self { inner, session })}/// Override the per-request timeout on the wrapped@@ -52,6 +72,34 @@ impl OpenCodeProvider {self.inner = self.inner.with_reasoning_effort(effort);self}++ /// Forward operator-configured headers, keeping this provider's session+ /// default when the operator left `x-opencode-session` unset.+ #[must_use]+ pub fn with_extra_headers(mut self, headers: ExtraHeaders) -> Self {+ let headers = with_session_default(&self.session, headers);+ self.inner = self.inner.with_extra_headers(headers);+ self+ }+}++/// A fresh session id. Prefixed so the value is self-describing in Zen/Go's+/// metrics rather than a bare UUID.+fn new_session_id() -> HeaderValue {+ HeaderValue::try_from(format!("ai-memory-{}", uuid::Uuid::new_v4()))+ // A UUID is always header-safe; the fallback exists so a runtime+ // path never panics on it.+ .unwrap_or_else(|_| HeaderValue::from_static("ai-memory"))+}++/// Layer the session id *under* the operator's headers, so an explicit+/// `AI_MEMORY_LLM_HEADERS` entry always wins.+fn with_session_default(session: &HeaderValue, mut headers: ExtraHeaders) -> ExtraHeaders {+ headers.set_default(+ HeaderName::from_static(OPENCODE_SESSION_HEADER),+ session.clone(),+ );+ headers}#[async_trait]@@ -93,4 +141,70 @@ mod tests {assert_eq!(OPENCODE_ZEN_BASE_URL, "https://opencode.ai/zen/go/v1");assert!(!OPENCODE_DEFAULT_MODEL.is_empty());}++ /// Zen/Go reports a request without this header as unattributable, so a+ /// zero-config `opencode` provider must supply one.+ #[test]+ fn zero_config_provider_sends_a_session_header() {+ let provider = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x").unwrap();+ assert!(+ provider+ .inner+ .extra_headers()+ .get(OPENCODE_SESSION_HEADER)+ .is_some_and(|v| v.starts_with("ai-memory-")),+ "session header missing or unprefixed"+ );+ }++ #[test]+ fn an_operator_session_header_wins_over_the_default() {+ let operator = ExtraHeaders::parse(["x-opencode-session: ses-mine"]).expect("valid");+ let provider = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x")+ .unwrap()+ .with_extra_headers(operator);+ assert_eq!(+ provider.inner.extra_headers().get(OPENCODE_SESSION_HEADER),+ Some("ses-mine")+ );+ }++ /// A default is filled in per header, not per map: operator headers that+ /// say nothing about the session must not drop it.+ #[test]+ fn unrelated_operator_headers_keep_the_session_default() {+ let operator = ExtraHeaders::parse(["x-opencode-client: ai-memory"]).expect("valid");+ let provider = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x")+ .unwrap()+ .with_extra_headers(operator);+ let headers = provider.inner.extra_headers();+ assert_eq!(headers.get("x-opencode-client"), Some("ai-memory"));+ assert!(headers.get(OPENCODE_SESSION_HEADER).is_some());+ }++ #[test]+ fn session_id_is_stable_across_builder_calls_on_one_instance() {+ let provider = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x").unwrap();+ let before = provider+ .inner+ .extra_headers()+ .get(OPENCODE_SESSION_HEADER)+ .expect("default session")+ .to_string();+ let provider = provider.with_timeout_secs(45).with_reasoning_effort(None);+ assert_eq!(+ provider.inner.extra_headers().get(OPENCODE_SESSION_HEADER),+ Some(before.as_str())+ );+ }++ #[test]+ fn separate_instances_get_separate_session_ids() {+ let a = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x").unwrap();+ let b = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x").unwrap();+ assert_ne!(+ a.inner.extra_headers().get(OPENCODE_SESSION_HEADER),+ b.inner.extra_headers().get(OPENCODE_SESSION_HEADER)+ );+ }}diff --git a/crates/ai-memory-llm/src/types.rs b/crates/ai-memory-llm/src/types.rsindex bb7e839b..efae28e4 100644--- a/crates/ai-memory-llm/src/types.rs+++ b/crates/ai-memory-llm/src/types.rs@@ -201,9 +201,156 @@ impl ReasoningEffort {}}+/// Operator-supplied HTTP headers attached to every chat request.+///+/// Some gateways require a caller-identifying header: OpenCode Zen/Go asks+/// every tool on its endpoint to send `x-opencode-session` and to identify+/// itself with a specific `User-Agent`, and flags accounts whose traffic+/// carries neither. Rather than teach each provider one gateway's wire+/// quirks, the operator declares headers once (`AI_MEMORY_LLM_HEADERS`) and+/// every chat provider sends them.+///+/// Parsed and validated at the configuration boundary, so providers consume+/// typed header material and never re-parse operator strings — the rule+/// provider auth already follows. Header values are treated as sensitive:+/// they are marked as such on the wire and the [`std::fmt::Debug`] impl+/// prints names only, because this is a plausible place for an operator to+/// put a token.+#[derive(Clone, Default, PartialEq)]+pub struct ExtraHeaders(reqwest::header::HeaderMap);++/// Headers ai-memory sets itself on provider requests. Rejected as operator+/// input: `reqwest` appends rather than replaces, so a second `authorization`+/// or `content-type` breaks the request instead of annotating it. Failing at+/// startup beats failing on the first consolidation pass.+const RESERVED_HEADERS: &[&str] = &[+ "anthropic-beta",+ "anthropic-version",+ "authorization",+ "content-length",+ "content-type",+ "host",+ "openai-beta",+ "x-api-key",+ "x-goog-api-key",+];++impl ExtraHeaders {+ /// Parse `Name: Value` / `Name=Value` entries, skipping blank ones.+ ///+ /// # Errors+ /// [`LlmError::NotConfigured`] when an entry has no separator, carries an+ /// invalid header name or value, or names a header from+ /// [`RESERVED_HEADERS`].+ pub fn parse<I, S>(entries: I) -> crate::error::LlmResult<Self>+ where+ I: IntoIterator<Item = S>,+ S: AsRef<str>,+ {+ use reqwest::header::{HeaderName, HeaderValue};++ let mut map = reqwest::header::HeaderMap::new();+ for (index, entry) in entries.into_iter().enumerate() {+ let entry = entry.as_ref().trim();+ if entry.is_empty() {+ continue;+ }+ // 1-based: operators count list entries from one, and the index+ // is what the message can safely name — see `split_entry`.+ let (raw_name, raw_value) = split_entry(entry, index + 1)?;+ let name = HeaderName::try_from(raw_name).map_err(|_| {+ crate::error::LlmError::NotConfigured(format!(+ "AI_MEMORY_LLM_HEADERS entry {}: {raw_name:?} is not a valid HTTP header name",+ index + 1+ ))+ })?;+ if RESERVED_HEADERS.contains(&name.as_str()) {+ return Err(crate::error::LlmError::NotConfigured(format!(+ "AI_MEMORY_LLM_HEADERS entry {}: {name} is set by ai-memory itself \+ and cannot be overridden",+ index + 1+ )));+ }+ let mut value = HeaderValue::try_from(raw_value).map_err(|_| {+ // Names the header, never the value.+ crate::error::LlmError::NotConfigured(format!(+ "AI_MEMORY_LLM_HEADERS entry {}: the value for {name} is not a valid \+ HTTP header value",+ index + 1+ ))+ })?;+ value.set_sensitive(true);+ map.insert(name, value);+ }+ Ok(Self(map))+ }++ /// Set `name: value` only when the operator has not configured that+ /// header, so a provider default never overrides an explicit+ /// `AI_MEMORY_LLM_HEADERS` entry.+ pub(crate) fn set_default(+ &mut self,+ name: reqwest::header::HeaderName,+ value: reqwest::header::HeaderValue,+ ) {+ if !self.0.contains_key(&name) {+ self.0.insert(name, value);+ }+ }++ /// Attach the configured headers to `builder`.+ ///+ /// Uses `RequestBuilder::headers`, which *replaces* any value already set+ /// for the same name. `RequestBuilder::header` appends instead, which+ /// would send two `user-agent` values on the Copilot provider (its client+ /// carries one as a default) — a duplicate breaks the request rather than+ /// overriding it.+ pub(crate) fn apply(&self, builder: reqwest::RequestBuilder) -> reqwest::RequestBuilder {+ if self.0.is_empty() {+ return builder;+ }+ builder.headers(self.0.clone())+ }++ /// Value configured for `name`. Test-visible so provider tests can assert+ /// what the boundary parsed without exposing values to normal callers.+ #[cfg(test)]+ pub(crate) fn get(&self, name: &str) -> Option<&str> {+ self.0.get(name).and_then(|v| v.to_str().ok())+ }+}++/// Names only — never values. `ProviderConfig` derives `Debug` and is logged+/// on configuration errors.+impl std::fmt::Debug for ExtraHeaders {+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ f.debug_set().entries(self.0.keys()).finish()+ }+}++/// Split `Name: Value` or `Name=Value` on whichever separator appears first,+/// so a value containing the other character survives intact.+///+/// Errors name the entry by position rather than echoing it: an entry with no+/// separator at all may well be a bare token the operator pasted by mistake.+fn split_entry(entry: &str, position: usize) -> crate::error::LlmResult<(&str, &str)> {+ let at = match (entry.find(':'), entry.find('=')) {+ (Some(colon), Some(equals)) => colon.min(equals),+ (Some(colon), None) => colon,+ (None, Some(equals)) => equals,+ (None, None) => {+ return Err(crate::error::LlmError::NotConfigured(format!(+ "AI_MEMORY_LLM_HEADERS entry {position} is neither `Name: Value` nor `Name=Value`"+ )));+ }+ };+ let (name, rest) = entry.split_at(at);+ Ok((name.trim(), rest[1..].trim()))+}+#[cfg(test)]mod tests {- use super::ReasoningEffort;+ use super::{ExtraHeaders, ReasoningEffort};use rstest::rstest;const ALL_EFFORTS: [ReasoningEffort; 9] = [@@ -286,4 +433,88 @@ mod tests {) {assert_eq!(input.openai_wire_effort(), expected);}+ #[test]+ fn parse_accepts_both_separators_and_trims() {+ let headers =+ ExtraHeaders::parse(["x-opencode-session = ses-1", " x-tool: ai-memory ", " "])+ .expect("valid entries");+ assert_eq!(headers.get("x-opencode-session"), Some("ses-1"));+ assert_eq!(headers.get("x-tool"), Some("ai-memory"));+ }++ /// A value containing `=` must survive a `Name: Value` entry, and one+ /// containing `:` a `Name=Value` entry — the split takes the *first*+ /// separator, not whichever kind it finds.+ #[test]+ fn parse_splits_on_the_first_separator_only() {+ let headers =+ ExtraHeaders::parse(["x-a: k=v", "x-b=https://example.test/p"]).expect("valid entries");+ assert_eq!(headers.get("x-a"), Some("k=v"));+ assert_eq!(headers.get("x-b"), Some("https://example.test/p"));+ }++ #[test]+ fn parse_rejects_entry_without_a_separator() {+ let err = ExtraHeaders::parse(["sk-not-a-header"]).expect_err("must fail closed");+ let rendered = err.to_string();+ assert!(rendered.contains("entry 1"), "{rendered}");+ // The malformed entry may be a pasted secret; it must not be echoed.+ assert!(!rendered.contains("sk-not-a-header"), "{rendered}");+ }++ #[test]+ fn parse_rejects_invalid_header_name() {+ let err = ExtraHeaders::parse(["not a name: v"]).expect_err("must fail closed");+ assert!(err.to_string().contains("valid HTTP header name"));+ }++ /// Newlines are the header-injection vector; rejecting them closes it.+ /// The message names the header but never the offending value.+ #[test]+ fn parse_rejects_invalid_header_value_without_echoing_it() {+ let err = ExtraHeaders::parse(["x-a: bad\nvalue-smuggled"]).expect_err("must fail closed");+ let rendered = err.to_string();+ assert!(rendered.contains("value for x-a"), "{rendered}");+ assert!(!rendered.contains("smuggled"), "{rendered}");+ }++ #[rstest::rstest]+ #[case("authorization: Bearer x")]+ #[case("Content-Type: text/plain")]+ #[case("x-api-key: k")]+ #[case("anthropic-version: 2023-06-01")]+ fn parse_rejects_headers_ai_memory_owns(#[case] entry: &str) {+ let err = ExtraHeaders::parse([entry]).expect_err("reserved header must fail closed");+ assert!(err.to_string().contains("set by ai-memory itself"), "{err}");+ }++ #[test]+ fn set_default_never_overrides_an_operator_entry() {+ let mut headers = ExtraHeaders::parse(["user-agent: mine/1"]).expect("valid");+ headers.set_default(+ reqwest::header::USER_AGENT,+ reqwest::header::HeaderValue::from_static("fallback/1"),+ );+ assert_eq!(headers.get("user-agent"), Some("mine/1"));+ }++ #[test]+ fn set_default_fills_an_absent_header() {+ let mut headers = ExtraHeaders::default();+ headers.set_default(+ reqwest::header::USER_AGENT,+ reqwest::header::HeaderValue::from_static("fallback/1"),+ );+ assert_eq!(headers.get("user-agent"), Some("fallback/1"));+ }++ /// `ProviderConfig` derives `Debug` and gets rendered into configuration+ /// errors; values must not ride along.+ #[test]+ fn debug_renders_names_but_not_values() {+ let headers = ExtraHeaders::parse(["x-opencode-session: ses-secret"]).expect("valid");+ let rendered = format!("{headers:?}");+ assert!(rendered.contains("x-opencode-session"), "{rendered}");+ assert!(!rendered.contains("ses-secret"), "{rendered}");+ }}diff --git a/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rs b/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rsnew file mode 100644index 00000000..a7c5bfa6--- /dev/null+++ b/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rs@@ -0,0 +1,121 @@+//! Integration tests asserting operator headers and the default user agent+//! actually reach the provider request, driving `build_provider` against a+//! real in-process HTTP mock (wiremock).+//!+//! Why not unit tests: `ExtraHeaders`' unit tests cover parsing, and the+//! factory's cover which defaults get layered. Neither proves the headers+//! survive `reqwest`'s request builder — and that is the whole point of the+//! feature. `reqwest::RequestBuilder::header` *appends* while `headers`+//! *replaces*, so "the value is on the struct" and "the right single value+//! is on the wire" are genuinely different claims.++use ai_memory_llm::types::ChatRequest;+use ai_memory_llm::{+ DEFAULT_USER_AGENT, ExtraHeaders, ProviderAuth, ProviderChoice, ProviderConfig, build_provider,+};+use serde_json::json;+use wiremock::matchers::{method, path};+use wiremock::{Mock, MockServer, Request, ResponseTemplate};++fn ok_body() -> serde_json::Value {+ json!({+ "id": "id",+ "object": "chat.completion",+ "created": 0,+ "model": "mistral-nemo",+ "choices": [{+ "index": 0,+ "message": { "role": "assistant", "content": "ok" },+ "finish_reason": "stop",+ }],+ "usage": { "prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2 },+ })+}++/// Drive one completion through `build_provider` against a fresh mock and+/// hand back the single request the mock received. Going through the factory+/// (rather than constructing a provider directly) is deliberate: the default+/// user agent is layered there, so this covers both halves at once.+async fn captured_request(headers: ExtraHeaders) -> Request {+ let server = MockServer::start().await;+ Mock::given(method("POST"))+ .and(path("/v1/chat/completions"))+ .respond_with(ResponseTemplate::new(200).set_body_json(ok_body()))+ .mount(&server)+ .await;++ let provider = build_provider(ProviderConfig {+ provider: ProviderChoice::OpenAiCompat,+ model: "mistral-nemo".into(),+ auth: ProviderAuth::optional_api_key_from_env("LLM_API_KEY", None),+ base_url: Some(server.uri()),+ compat_strict: false,+ request_timeout_secs: 30,+ reasoning_effort: None,+ extra_headers: headers,+ })+ .expect("provider builds");++ provider+ .complete(ChatRequest::user_prompt("hi"))+ .await+ .expect("mock responds 200");++ let mut received = server+ .received_requests()+ .await+ .expect("mock recorded requests");+ assert_eq!(received.len(), 1, "expected exactly one upstream request");+ received.remove(0)+}++/// Every value sent for `name`. A `Vec` rather than a lookup so a duplicated+/// header fails the assertion instead of hiding behind the first value.+fn values(request: &Request, name: &str) -> Vec<String> {+ request+ .headers+ .get_all(name)+ .iter()+ .map(|v| v.to_str().unwrap_or_default().to_string())+ .collect()+}++#[tokio::test]+async fn operator_headers_reach_the_provider_request() {+ let headers = ExtraHeaders::parse(["x-opencode-session: ses-1"]).expect("valid");+ let request = captured_request(headers).await;+ assert_eq!(values(&request, "x-opencode-session"), vec!["ses-1"]);+}++/// `reqwest` sends no user agent unless configured; `build_provider` layers+/// one in, and it must arrive as a single value.+#[tokio::test]+async fn the_default_user_agent_reaches_the_provider_request() {+ let request = captured_request(ExtraHeaders::default()).await;+ assert_eq!(values(&request, "user-agent"), vec![DEFAULT_USER_AGENT]);+}++/// Replace, not append: an operator user agent must not arrive alongside the+/// default. Two values would be worse than either one alone.+#[tokio::test]+async fn an_operator_user_agent_replaces_the_default_on_the_wire() {+ let headers = ExtraHeaders::parse(["user-agent: ai-memory-fork/9"]).expect("valid");+ let request = captured_request(headers).await;+ assert_eq!(values(&request, "user-agent"), vec!["ai-memory-fork/9"]);+}++/// The provider's own auth and wire-format headers must survive alongside+/// the operator's — `headers` replaces per name, so a regression here would+/// silently strip authentication rather than fail loudly.+#[tokio::test]+async fn provider_owned_headers_survive_alongside_operator_headers() {+ let headers = ExtraHeaders::parse(["x-tool: ai-memory"]).expect("valid");+ let request = captured_request(headers).await;+ assert_eq!(values(&request, "x-tool"), vec!["ai-memory"]);+ assert_eq!(values(&request, "content-type"), vec!["application/json"]);+ assert_eq!(+ request.headers.get_all("authorization").iter().count(),+ 1,+ "provider auth must be sent exactly once"+ );+}diff --git a/docker/.env.production.example b/docker/.env.production.exampleindex 18ae9c6e..78330c03 100644--- a/docker/.env.production.example+++ b/docker/.env.production.example@@ -45,6 +45,21 @@ AI_MEMORY_LLM_MODEL=moonshotai/kimi-k2.6# OPENCODE_API_KEY=sk-... (from opencode.ai/auth, for AI_MEMORY_LLM_PROVIDER=opencode)LLM_API_KEY=sk-or-v1-REPLACE_ME+# -- Extra headers on every LLM request --------------------------------+# Every chat request already carries `User-Agent: ai-memory/<version>` so a+# gateway can tell what is calling it. Add this only for a gateway that also+# requires a header of its own for request correlation.+#+# Comma-separated `Name=Value` (or `Name: Value`) entries. A header *value*+# cannot contain a comma here — use `llm_headers = [...]` in config.toml if+# one must. Headers ai-memory sets itself (authorization, content-type,+# x-api-key, ...) are refused at startup. Values are never logged.+#+# The `opencode` provider needs nothing here: it generates an+# `x-opencode-session` per process. Set one explicitly to keep it stable+# across restarts, or to tell several instances apart.+# AI_MEMORY_LLM_HEADERS=x-opencode-session=homelab-01,x-opencode-client=ai-memory+# -- Embeddings (hybrid retrieval) -------------------------------------# Optional. When set, ai-memory computes + stores embeddings for every# page and uses Reciprocal Rank Fusion to combine FTS5 with vectordiff --git a/docker/docker-compose.yml b/docker/docker-compose.ymlindex 4ed7a753..3ba4fa0c 100644--- a/docker/docker-compose.yml+++ b/docker/docker-compose.yml@@ -32,6 +32,11 @@ services:# anthropic | openai | openai-oauth | anthropic-oauth | copilot |# gemini | openai-compat | opencode# See .env.production.example for the full reference.+ #+ # Extra headers on every LLM chat request, for a gateway that requires+ # a caller-identifying one. Comma-separated `Name=Value` entries; the+ # default `User-Agent: ai-memory/<version>` needs no configuration.+ # - AI_MEMORY_LLM_HEADERS=x-opencode-session=homelab-01healthcheck:test: ["CMD", "/usr/local/bin/ai-memory", "status"]interval: 30sdiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex a399ad57..b6f6ba5b 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -606,12 +606,31 @@ AI_MEMORY_LLM_REASONING_EFFORT optional reasoning/thinking effortCodex `reasoning.effort`. Gemini and Copilotignore the key. Host-unsupported values areclamped to each provider's published enum.+AI_MEMORY_LLM_HEADERS optional extra HTTP headers on every chat request, as+ comma-separated `Name=Value` (or `Name: Value`) entries;+ e.g. `x-opencode-session=prod-01,x-opencode-client=ai-memory`.+ For gateways that require a caller-identifying header.+ Headers ai-memory sets itself (authorization,+ content-type, x-api-key, x-goog-api-key,+ anthropic-version, anthropic-beta, openai-beta,+ host, content-length) are refused at startup.+ Values are never logged. A header value cannot+ contain a comma through the env var — use+ `llm_headers = [...]` in config.toml for that.AI_MEMORY_RERANKER optional `llm`; reranks project/scopes query candidatesCOPILOT_GITHUB_TOKEN optional GitHub token for copilotGITHUB_COPILOT_API_TOKEN optional pre-minted Copilot API tokenCOPILOT_API_URL optional Copilot API base URL override```+Every chat request carries `User-Agent: ai-memory/<version>`+(`ai_memory_llm::DEFAULT_USER_AGENT`, layered in `build_provider`). `reqwest`+sends no user agent unless configured, so provider requests used to arrive+anonymous — which gateways that require callers to identify themselves report+as an unknown client. `AI_MEMORY_LLM_HEADERS=user-agent=...` overrides it. The+Copilot provider keeps `GitHubCopilotChat/<version>` instead, the+editor-plugin agent GitHub's Copilot API expects.+`openai-oauth` uses `auth login openai-oauth` and stores the ChatGPT/Codexrefresh token in `<data_dir>/auth.json`; it is separate from MCP/server bearerauth and from OpenAI Platform API keys.diff --git a/docs/install.md b/docs/install.mdindex b0243069..44bf453e 100644--- a/docs/install.md+++ b/docs/install.md@@ -1762,6 +1762,31 @@ ceiling to match the gateway's worst-case generation time:-e AI_MEMORY_LLM_TIMEOUT_SECS=900```+#### Send a caller-identifying header to a gateway that requires one++Every chat request already carries `User-Agent: ai-memory/<version>`, so a+gateway can tell what is calling it. Some also require a header of their own+for request correlation, and reject or throttle traffic without it. Declare+those once — they are sent on every chat request, whatever the provider:++```bash+-e AI_MEMORY_LLM_HEADERS=x-opencode-session=prod-01,x-opencode-client=ai-memory+```++Entries are `Name=Value` or `Name: Value`, comma separated. A header *value*+cannot contain a comma through the env var; use `llm_headers = [...]` in+`config.toml` when one must. Headers ai-memory sets itself (`authorization`,+`content-type`, `x-api-key`, `x-goog-api-key`, `anthropic-version`,+`anthropic-beta`, `openai-beta`, `host`, `content-length`) are refused at+startup rather than duplicated onto the request. An entry for `user-agent`+overrides the default. Values are never logged.++The `opencode` provider needs no configuration for this: OpenCode Zen/Go asks+callers for `x-opencode-session`, so that provider generates one per process+unless `AI_MEMORY_LLM_HEADERS` supplies it. Set it explicitly when several+ai-memory instances should be distinguishable, or should stay stable across+restarts.+#### Match the consolidation budget to a local model's context windowConsolidation defaults to an approximate 100k-token input target plus a 32kdiff --git a/evals/src/ab.rs b/evals/src/ab.rsindex 94c991e8..15511aa8 100644--- a/evals/src/ab.rs+++ b/evals/src/ab.rs@@ -361,6 +361,10 @@ impl From<ResolvedConfig> for ProviderConfig {// effort stays at each model's own default unless a future// flag threads it through.reasoning_effort: None,+ // No operator header list here: `build_provider` still layers+ // the default user agent, which is what a gateway needs to+ // attribute harness traffic.+ extra_headers: ai_memory_llm::ExtraHeaders::default(),}}}diff --git a/packaging/env/ai-memory.env b/packaging/env/ai-memory.envindex db7bae48..103526eb 100644--- a/packaging/env/ai-memory.env+++ b/packaging/env/ai-memory.env@@ -9,5 +9,6 @@# AI_MEMORY_LLM_PROVIDER=anthropic# ANTHROPIC_API_KEY=sk-ant-...# AI_MEMORY_LLM_REASONING_EFFORT=low+# AI_MEMORY_LLM_HEADERS=x-opencode-session=host-01,x-opencode-client=ai-memory# AI_MEMORY_EMBEDDING_PROVIDER=openai# OPENAI_API_KEY=sk-...