Skip to content

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.md
index 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 work
on real stores. Both read the entity index, which was populated only
diff --git a/crates/ai-memory-cli/src/commands/llm_test.rs b/crates/ai-memory-cli/src/commands/llm_test.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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, OpenCodeProvid
pub 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.example
index 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 vector
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index 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-01
healthcheck:
test: ["CMD", "/usr/local/bin/ai-memory", "status"]
interval: 30s
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index a399ad57..b6f6ba5b 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -606,12 +606,31 @@ AI_MEMORY_LLM_REASONING_EFFORT optional reasoning/thinking effort
Codex `reasoning.effort`. Gemini and Copilot
ignore the key. Host-unsupported values are
clamped 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 candidates
COPILOT_GITHUB_TOKEN optional GitHub token for copilot
GITHUB_COPILOT_API_TOKEN optional pre-minted Copilot API token
COPILOT_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/Codex
refresh token in `<data_dir>/auth.json`; it is separate from MCP/server bearer
auth and from OpenAI Platform API keys.
diff --git a/docs/install.md b/docs/install.md
index 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 window
Consolidation defaults to an approximate 100k-token input target plus a 32k
diff --git a/evals/src/ab.rs b/evals/src/ab.rs
index 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.env
index 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-...