Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
Merge upstream/main: reconcile operator headers with the 2.0.2 client headers
Lucas Oliveira25573e007760
diff --cc CHANGELOG.mdindex a4af606d,135484b6..42941be5--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -7,46 -7,7 +7,38 @@@ and this project adheres to [Semantic V## [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's Go documentation covers third-party access to its- endpoints and asks callers to identify themselves; both Go and Zen- correlate requests by that header, and 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.++- `x-opencode-session` and the `opencode` user agent, both shipped in 2.0.2,++ are now operator-overridable like any other header: an++ `AI_MEMORY_LLM_HEADERS` entry for either name takes precedence over the++ provider's default. The default remains 2.0.2's — one `LlmOperationId` per++ logical operation, stable across retries and the strict/tolerant fallback —++ so nothing changes unless an operator asks for it. Override the session++ header to tell several ai-memory instances apart in OpenCode's metrics.+### Fixed- - `install-hooks --agent zcode --apply` now removes stale ai-memory- hooks left under event keys this version no longer manages (e.g. a- legacy `SessionEnd`), instead of reporting "already up to date" while- a broken/orphaned entry lingered (#600). The dry-run printed snippet- also now states plainly that `--apply` persists the auth token to- `<data-dir>/auth-token` (0600) and writes token-less args, so the- applied config differs from the embedded-token snippet by design.- Local-embedding model download (`fetch_model`) now bounds a stalledconnection instead of hanging startup forever (#602): a 30s connecttimeout and a generous 600s overall ceiling (large model files, so@@@ -73,18 -34,28 +65,40 @@@does not imply a secret, so it must be qualified by an auth word:`Idempotency-Key`, `Continuation-Token` and storage partition keys areleft intact and stay readable in captured output.+ - `install-hooks --agent zcode --apply` no longer reports a hooks block+ ZCode has thrown away as `no-op … (already up to date)` (#600). ZCode+ validates `hooks.events` strictly and rejects the whole block, including+ ai-memory's own entries, over a single key it does not recognize, so+ capture never ran (`hookCount: 0`). Apply only ever merged the six event+ keys it writes, so a key it does not write was neither inspected nor+ reported, the file kept matching byte for byte, and the report claimed+ the install was current. Apply now also withdraws ai-memory's own+ entries from event keys it no longer writes, wherever they sit, and+ reports what it found: a warning naming any key it withdrew from, and a+ note for a key left unable to run anything, both naming the config file.+ **Changed output:** an unchanged ZCode config with such a key now reports+ `no-op … (unchanged; see the notes below)` instead of `already up to+ date`, so a redirected stdout no longer carries the reassurance without+ the cause. Event keys are never deleted and hooks ai-memory did not write+ are never removed, so a key holding someone else's hook is reported, not+ touched.+ - OpenCode Go requests now send `User-Agent: ai-memory/<version>` and a+ per-operation `x-opencode-session` header. Session consolidation and+ auto-improvement reuse the captured ai-memory session ID, while retries and+ structured-output fallback keep the same ID instead of appearing as unrelated+ requests (#608).+- `AI_MEMORY_LLM_BASE_URL` now works with `AI_MEMORY_LLM_PROVIDER=opencode`.+ The provider hardcoded OpenCode's **Go** endpoint and the factory dropped+ the configured base URL without a word, so Zen's general catalogue at+ `https://opencode.ai/zen/v1` was unreachable through it — Zen and Go are+ separate products, not two spellings of one. Go remains the default, so+ existing setups are unaffected; an override keeps the `x-opencode-session`+ default and the user agent, since both endpoints correlate requests the+ same way. Model ids are per catalogue, so set `AI_MEMORY_LLM_MODEL`+ explicitly when overriding. `OPENCODE_ZEN_BASE_URL` is deprecated in+ favour of `OPENCODE_GO_BASE_URL`: the constant named Zen but has always+ held Go's URL. It keeps its value, so code compiled against it is+ unaffected.- `as_of` time-travel queries and the entity retrieval stream now workon real stores. Both read the entity index, which was populated onlyfrom an LLM consolidator's `entities:` frontmatter — absent on thediff --cc crates/ai-memory-llm/src/lib.rsindex 62e1a72c,134266dc..e7337a23--- a/crates/ai-memory-llm/src/lib.rs+++ b/crates/ai-memory-llm/src/lib.rs@@@ -111,12 -95,10 +111,13 @@@ pub use openai_oauth::OPENAI_OAUTH_TOKEN_URL, OpenAiExtras, OpenAiOAuthProvider, OpenAiOAuthToken,OpenAiOAuthTokenResponse,};-pub use opencode::{OPENCODE_DEFAULT_MODEL, OPENCODE_ZEN_BASE_URL, OpenCodeProvider};+#[allow(deprecated)]+pub use opencode::OPENCODE_ZEN_BASE_URL;+pub use opencode::{OPENCODE_DEFAULT_MODEL, OPENCODE_GO_BASE_URL, OpenCodeProvider};- pub use provider::{LlmProvider, complete_structured};+ pub use provider::{LlmProvider, complete_structured, complete_structured_with_operation_id};pub use reranker::{LlmReranker, RerankCandidate, RerankScore, Reranker};pub use stored_token::StoredOAuthToken;pub use types::{- ChatMessage, ChatRequest, ChatResponse, ExtraHeaders, ReasoningEffort, Role, Usage,- ChatMessage, ChatRequest, ChatResponse, LlmOperationId, ReasoningEffort, Role, Usage,++ ChatMessage, ChatRequest, ChatResponse, ExtraHeaders, LlmOperationId, ReasoningEffort, Role,++ Usage,};diff --cc crates/ai-memory-llm/src/openai.rsindex 3a98512a,e8b9304e..13f04c60--- a/crates/ai-memory-llm/src/openai.rs+++ b/crates/ai-memory-llm/src/openai.rs@@@ -11,7 -11,7 +11,11 @@@ use tracing::debuguse crate::error::{LlmError, LlmResult};use crate::provider::LlmProvider;use crate::response::{provider_error_body, response_json_limited};- use crate::types::{ChatRequest, ChatResponse, ExtraHeaders, ReasoningEffort, Usage};-use crate::types::{ChatRequest, ChatResponse, LlmOperationId, ReasoningEffort, Usage};++use reqwest::header::{HeaderName, HeaderValue};++++use crate::types::{++ ChatRequest, ChatResponse, ExtraHeaders, LlmOperationId, ReasoningEffort, Usage,++};/// Default OpenAI API base.pub const DEFAULT_BASE_URL: &str = "https://api.openai.com";@@@ -91,7 -91,13 +95,20 @@@ pub struct OpenAiProviderdialect: RequestDialect,timeout: Duration,reasoning_effort: Option<ReasoningEffort>,++ /// Operator-configured headers from `AI_MEMORY_LLM_HEADERS`. Applied++ /// last, so an explicit entry wins over any default below.+ extra_headers: ExtraHeaders,++ /// Caller-identifying defaults a provider opts into. Layered *under*++ /// `extra_headers`.+ client_headers: Option<ClientHeaders>,+ }+++/// Defaults for a provider whose gateway wants the caller identified: an++/// agent string, and the header name to report the logical operation under.+ #[derive(Debug, Clone, Copy)]+ struct ClientHeaders {+ user_agent: &'static str,+ operation_id: &'static str,}impl OpenAiProvider {@@@ -111,7 -117,7 +128,8 @@@dialect: RequestDialect::Official,timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),reasoning_effort: None,+ extra_headers: ExtraHeaders::default(),+ client_headers: None,})}@@@ -156,27 -162,17 +174,36 @@@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.++ /// Opt this provider into caller-identifying defaults: `user_agent` as++ /// the agent string, and `operation_id` as the header *name* to report++ /// each logical operation under. Both are defaults — an++ /// `AI_MEMORY_LLM_HEADERS` entry for either name takes precedence.+ pub(crate) fn with_client_headers(+ mut self,+ user_agent: &'static str,+ operation_id: &'static str,+ ) -> Self {+ self.client_headers = Some(ClientHeaders {+ user_agent,+ operation_id,+ });+ self+ }+++ /// Endpoint the client will call. Test-visible so wrappers that default+ /// the base URL and let it be overridden can assert which one is set.+ #[cfg(test)]+ pub(crate) fn base_url(&self) -> &str {+ &self.base_url+ }-- #[cfg(test)]- pub(crate) fn extra_headers(&self) -> &ExtraHeaders {- &self.extra_headers- }}#[derive(Debug, Serialize)]@@@ -383,17 -413,25 +444,46 @@@ impl OpenAiProvider}}- async fn post<B: Serialize>(&self, body: &B) -> LlmResult<OpenAiResponse> {+ async fn post<B: Serialize>(+ &self,+ body: &B,+ operation_id: LlmOperationId,+ ) -> LlmResult<OpenAiResponse> {let url = normalize_openai_base(&self.base_url, "chat/completions");debug!(url, "POST openai");- 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 mut request = self++ let builder = self+ .client+ .post(&url)+ .timeout(self.timeout)+ .bearer_auth(self.api_key.expose_secret())- .header("content-type", "application/json")- .json(body);- if let Some(headers) = self.client_headers {- request = request.header(reqwest::header::USER_AGENT, headers.user_agent);- request = request.header(headers.operation_id, operation_id.to_string());- }- let resp = request.send().await?;++ .header("content-type", "application/json");++ // Both header layers go on in one `apply`, which replaces per name.++ // Adding them separately with `RequestBuilder::header` would *append*++ // — two `user-agent` values whenever the operator configures one, and++ // a duplicate is worse than either value alone. `set_default` leaves++ // an operator entry untouched, so the layering is explicit here++ // rather than dependent on call order.++ let request = match self.client_headers {++ None => self.extra_headers.apply(builder),++ Some(client) => {++ let mut headers = self.extra_headers.clone();++ headers.set_default(++ reqwest::header::USER_AGENT,++ HeaderValue::from_static(client.user_agent),++ );++ // Both are our own constants, so an invalid name is a bug to++ // surface in the first test run, not a runtime branch.++ let name = HeaderName::from_static(client.operation_id);++ // A UUID is always a valid header value; on the impossible++ // failure, omitting a correlation header beats failing the++ // consolidation pass that carries it.++ if let Ok(value) = HeaderValue::from_str(&operation_id.to_string()) {++ headers.set_default(name, value);++ }++ headers.apply(builder)++ }++ };+ let resp = request.json(body).send().await?;let status = resp.status();if !status.is_success() {let body = provider_error_body(resp).await;diff --cc crates/ai-memory-llm/src/openai_compat.rsindex 838f2cab,5fa1ff6f..c25a76c9--- a/crates/ai-memory-llm/src/openai_compat.rs+++ b/crates/ai-memory-llm/src/openai_compat.rs@@@ -128,30 -116,14 +128,33 @@@ impl OpenAiCompatProviderself}+ /// 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+ }+++ /// Forward the caller-identifying defaults to the inner client. Only++ /// [`crate::OpenCodeProvider`] opts in today; the values sit under any++ /// operator-configured header of the same name.+ pub(crate) fn with_client_headers(+ mut self,+ user_agent: &'static str,+ operation_id: &'static str,+ ) -> Self {+ self.inner = self.inner.with_client_headers(user_agent, operation_id);+ self+ }+ /// Endpoint the inner client will call. Test-visible so+ /// [`crate::OpenCodeProvider`]'s tests can assert Go stays the default+ /// and a Zen override takes effect.+ #[cfg(test)]+ pub(crate) fn base_url(&self) -> &str {+ self.inner.base_url()+ }-- /// Headers the inner client will send. Test-visible so the- /// [`crate::OpenCodeProvider`] tests can assert its Go defaults survive- /// delegation.- #[cfg(test)]- pub(crate) fn extra_headers(&self) -> &crate::ExtraHeaders {- self.inner.extra_headers()- }}#[async_trait]diff --cc crates/ai-memory-llm/src/opencode.rsindex cb02c2a1,ba614e0b..9ed0e8f2--- a/crates/ai-memory-llm/src/opencode.rs+++ b/crates/ai-memory-llm/src/opencode.rs@@@ -1,65 -1,24 +1,64 @@@-//! OpenCode Zen/Go provider.+//! OpenCode provider — Go by default, Zen on request.//!-//! 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`.+//! Thin wrapper around [`OpenAiCompatProvider`] that names the provider+//! `"opencode"` and accepts an `sk-...` API key from `OPENCODE_API_KEY`.+//!+//! OpenCode serves two endpoints, and they are different products rather+//! than two names for one: **Go** ([`OPENCODE_GO_BASE_URL`]) is a smaller,+//! cost-optimised model set, while **Zen** (`https://opencode.ai/zen/v1`)+//! serves the full catalogue. Go is the default here; an operator selects+//! Zen with `AI_MEMORY_LLM_BASE_URL`, which the factory passes to+//! [`OpenCodeProvider::with_base_url`]. Model ids are per catalogue, so an+//! override wants an explicit `AI_MEMORY_LLM_MODEL` too.+//!+//! Go's documentation covers third-party access and asks every tool using+//! it 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 both endpoints+//! correlate 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, ExtraHeaders};-use crate::types::{ChatRequest, ChatResponse, LlmOperationId};--/// Public OpenCode Zen/Go OpenAI-compatible base URL.-pub const OPENCODE_ZEN_BASE_URL: &str = "https://opencode.ai/zen/go/v1";++use crate::types::{ChatRequest, ChatResponse, ExtraHeaders, LlmOperationId};-/// Default model when `AI_MEMORY_LLM_MODEL` is not set.+/// Public OpenCode **Go** OpenAI-compatible base URL, and this provider's+/// default endpoint.+///+/// Go is a distinct product from Zen's general catalogue, not another+/// spelling of it: Go serves a smaller, cost-optimised model set under+/// `zen/go/v1`, while Zen serves the full catalogue at+/// `https://opencode.ai/zen/v1`. Both authenticate with the same+/// `OPENCODE_API_KEY` and both correlate requests by+/// [`OPENCODE_SESSION_HEADER`], so reaching Zen is a base-URL override —+/// see [`OpenCodeProvider::with_base_url`].+pub const OPENCODE_GO_BASE_URL: &str = "https://opencode.ai/zen/go/v1";++/// Misnomer for [`OPENCODE_GO_BASE_URL`], kept so the released public API+/// keeps compiling: the value has always been Go's endpoint, never Zen's+/// general one.+#[deprecated(+ since = "2.1.0",+ note = "names Zen but holds Go's endpoint; use OPENCODE_GO_BASE_URL"+)]+pub const OPENCODE_ZEN_BASE_URL: &str = OPENCODE_GO_BASE_URL;++/// Default model when `AI_MEMORY_LLM_MODEL` is not set. Taken from Go's+/// catalogue, so an operator overriding the base URL should set the model+/// explicitly rather than assume this id exists on the other endpoint.pub const OPENCODE_DEFAULT_MODEL: &str = "claude-sonnet-4-6";-/// OpenCode Zen/Go LLM provider.+/// Session-correlation header OpenCode asks callers to send, on Zen and Go+/// alike. Requests arriving without it are reported as unattributable and+/// may be rejected.+pub const OPENCODE_SESSION_HEADER: &str = "x-opencode-session";++/// OpenCode LLM provider, pointed at Go unless repointed at Zen.////// Routes through `https://opencode.ai/zen/go/v1` using the OpenAI chat/// completions wire format. Authenticate with the `sk-...` key obtained@@@ -80,25 -33,28 +74,43 @@@ 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 session = new_session_id();- let inner = OpenAiCompatProvider::new(OPENCODE_GO_BASE_URL, Some(api_key), model.into())?- .with_extra_headers(with_session_default(&session, ExtraHeaders::default()));- Ok(Self { inner, session })- Self::new_with_base_url(api_key, model, OPENCODE_ZEN_BASE_URL)++ Self::new_with_base_url(api_key, model, OPENCODE_GO_BASE_URL)+ }+++ /// Construct against an explicit endpoint. The session header carries a++ /// [`LlmOperationId`], so one logical operation keeps one id across++ /// retries and the strict/tolerant fallback — which is what OpenCode's++ /// metrics key on. Both values are defaults: an `AI_MEMORY_LLM_HEADERS`++ /// entry for either name wins.+ fn new_with_base_url(+ api_key: SecretString,+ model: impl Into<String>,+ base_url: impl Into<String>,+ ) -> LlmResult<Self> {+ let inner = OpenAiCompatProvider::new(base_url, Some(api_key), model.into())?- .with_client_headers(- concat!("ai-memory/", env!("CARGO_PKG_VERSION")),- "x-opencode-session",- );++ .with_client_headers(crate::DEFAULT_USER_AGENT, OPENCODE_SESSION_HEADER);+ Ok(Self { inner })}+ /// Point the provider at a different OpenCode endpoint — Zen's general+ /// catalogue (`https://opencode.ai/zen/v1`) instead of Go's default.+ ///+ /// The factory calls this with `ProviderConfig::base_url`- /// (`AI_MEMORY_LLM_BASE_URL`). The session header and user agent are- /// unaffected: both endpoints correlate requests the same way, so the- /// override changes where requests go, not how they identify themselves.++ /// (`AI_MEMORY_LLM_BASE_URL`). Identification is unaffected: both++ /// endpoints correlate requests the same way, so the override changes++ /// where requests go, not how they identify themselves.+ #[must_use]+ pub fn with_base_url(mut self, url: impl Into<String>) -> Self {+ self.inner = self.inner.with_base_url(url);+ self+ }++ #[cfg(test)]+ fn with_strict(mut self, strict: bool) -> Self {+ self.inner = self.inner.with_strict(strict);+ self+ }+/// Override the per-request timeout on the wrapped/// [`OpenAiCompatProvider`]. The factory calls this with/// `ProviderConfig::request_timeout_secs`.@@@ -114,36 -70,8 +126,17 @@@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.++ /// Forward operator-configured headers. The session header and user++ /// agent this provider sets are defaults applied per request, so an++ /// `AI_MEMORY_LLM_HEADERS` entry for either name wins here.+ #[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 OpenCode'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]impl LlmProvider for OpenCodeProvider {fn name(&self) -> &'static str {@@@ -185,68 -155,36 +221,57 @@@ mod testsassert!(!OPENCODE_DEFAULT_MODEL.is_empty());}+ /// The deprecated name kept its value, so code compiled against v2.0+ /// keeps hitting the endpoint it already hit.+ #[test]+ #[allow(deprecated)]+ fn the_deprecated_alias_still_resolves_to_go() {+ assert_eq!(OPENCODE_ZEN_BASE_URL, OPENCODE_GO_BASE_URL);+ }++ /// Zen's general catalogue is reachable, and is not the default — the+ /// bug this pair pins is a base URL that could not be overridden.+ #[test]+ fn with_base_url_repoints_the_provider_at_zen() {+ let go = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x").unwrap();+ assert_eq!(go.inner.base_url(), OPENCODE_GO_BASE_URL);++ let zen = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x")+ .unwrap()+ .with_base_url("https://opencode.ai/zen/v1");+ assert_eq!(zen.inner.base_url(), "https://opencode.ai/zen/v1");+ }+- /// Overriding the endpoint must not cost the caller its identity: both- /// endpoints correlate by the same header.- #[test]- fn a_zen_override_keeps_the_session_header() {- let provider = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x")- .unwrap()- .with_base_url("https://opencode.ai/zen/v1");- assert!(- provider- .inner- .extra_headers()- .get(OPENCODE_SESSION_HEADER)- .is_some_and(|v| v.starts_with("ai-memory-")),- "session header lost when the base URL was overridden"- );- }+ #[tokio::test]+ async fn completion_identifies_ai_memory_and_its_logical_operation() {+ let server = MockServer::start().await;+ Mock::given(method("POST"))+ .and(path("/v1/chat/completions"))+ .respond_with(ResponseTemplate::new(200).set_body_json(response_with_content("ok")))+ .mount(&server)+ .await;- /// OpenCode 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"- );- }+ let provider = OpenCodeProvider::new_with_base_url(+ SecretString::from("sk-test"),+ "model-x",+ server.uri(),+ )+ .unwrap();+ let operation_id = LlmOperationId::new();+ provider+ .complete_with_operation_id(ChatRequest::user_prompt("hello"), operation_id)+ .await+ .unwrap();- #[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);+ let requests = server.received_requests().await.unwrap();+ assert_eq!(requests.len(), 1);assert_eq!(- provider.inner.extra_headers().get(OPENCODE_SESSION_HEADER),- Some("ses-mine")+ header_value(&requests[0], "user-agent"),+ Some(concat!("ai-memory/", env!("CARGO_PKG_VERSION")))+ );+ assert_eq!(+ header_value(&requests[0], "x-opencode-session"),+ Some(operation_id.to_string().as_str()));}diff --cc crates/ai-memory-llm/tests/extra_headers_on_the_wire.rsindex d180c129,00000000..f93cd577mode 100644,000000..100644--- a/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rs+++ b/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rs@@@ -1,173 -1,0 +1,219 @@@+//! 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 secrecy::SecretString;+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"+ );+}++/// The `opencode` provider defaults to Go, so a base URL an operator sets+/// must actually redirect it — this is the regression the silently-dropped+/// `ProviderConfig::base_url` caused. Driving it against a mock is the only+/// way to see *where* the request went.+#[tokio::test]+async fn an_operator_base_url_redirects_the_opencode_provider() {+ 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::OpenCode,+ model: "mistral-nemo".into(),+ auth: ProviderAuth::required_api_key_from_env(+ "OPENCODE_API_KEY",+ Some(SecretString::from("sk-test")),+ ),+ base_url: Some(server.uri()),+ compat_strict: false,+ request_timeout_secs: 30,+ reasoning_effort: None,+ extra_headers: ExtraHeaders::default(),+ })+ .expect("provider builds");++ provider+ .complete(ChatRequest::user_prompt("hi"))+ .await+ .expect("the override must reach the mock, not opencode.ai");++ let received = server+ .received_requests()+ .await+ .expect("mock recorded requests");+ assert_eq!(received.len(), 1, "request did not reach the override");++ // Redirecting must not cost the caller its identity: Zen and Go+ // correlate requests by the same header.+ let request = &received[0];+ assert!(+ values(request, "x-opencode-session")+ .first()- .is_some_and(|v| v.starts_with("ai-memory-")),++ .is_some_and(|v| !v.is_empty()),+ "session header lost when the base URL was overridden"+ );+ assert_eq!(values(request, "user-agent"), vec![DEFAULT_USER_AGENT]);+}++++/// The load-bearing claim of layering operator headers over the provider's++/// own defaults: an explicit `AI_MEMORY_LLM_HEADERS` entry must beat the++/// per-operation id, and must arrive exactly once. Appending instead of++/// replacing would send both values, which is worse than either alone.++#[tokio::test]++async fn an_operator_session_header_beats_the_per_operation_default() {++ 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::OpenCode,++ model: "mistral-nemo".into(),++ auth: ProviderAuth::required_api_key_from_env(++ "OPENCODE_API_KEY",++ Some(SecretString::from("sk-test")),++ ),++ base_url: Some(server.uri()),++ compat_strict: false,++ request_timeout_secs: 30,++ reasoning_effort: None,++ extra_headers: ExtraHeaders::parse([++ "x-opencode-session: homelab-01",++ "user-agent: ai-memory-fork/9",++ ])++ .expect("valid"),++ })++ .expect("provider builds");++++ provider++ .complete(ChatRequest::user_prompt("hi"))++ .await++ .expect("mock responds 200");++++ let received = server++ .received_requests()++ .await++ .expect("mock recorded requests");++ let request = &received[0];++ assert_eq!(values(request, "x-opencode-session"), vec!["homelab-01"]);++ assert_eq!(values(request, "user-agent"), vec!["ai-memory-fork/9"]);++}diff --cc docs/install.mdindex 4b3d25c7,4bfb2032..5d84215c--- a/docs/install.md+++ b/docs/install.md@@@ -1499,7 -1499,7 +1499,7 @@@ If you set only the provider, ai-memor| `AI_MEMORY_LLM_PROVIDER=openai-oauth` | `gpt-5.5` | ChatGPT/Codex backend. Run `ai-memory auth login openai-oauth` once; ai-memory stores the refresh token in `<data_dir>/auth.json` and refreshes access tokens automatically. Optional `AI_MEMORY_LLM_REASONING_EFFORT` (`none`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max`/`ultra`/`persistent`) is mapped to each provider's native reasoning field; omit it to keep the model default. || `AI_MEMORY_LLM_PROVIDER=copilot` | `gpt-5.5` | GitHub Copilot Chat backend. ai-memory stores a GitHub user token in `<data_dir>/auth.json`, exchanges it for a short-lived Copilot API token, and refreshes before expiry. || `AI_MEMORY_LLM_PROVIDER=gemini` | `gemini-3.5-flash` | Google's hosted option with a generous free tier. ai-memory disables Gemini 3.5 Flash's default dynamic thinking so hidden thought tokens do not truncate strict JSON. Set `GEMINI_API_KEY` (or `GOOGLE_API_KEY`). |- | `AI_MEMORY_LLM_PROVIDER=opencode` | `claude-sonnet-4-6` | [OpenCode](https://opencode.ai) cloud API. Defaults to the **Go** endpoint, `opencode.ai/zen/go/v1` — a cost-optimised model subset. For **Zen**'s full catalogue, set `AI_MEMORY_LLM_BASE_URL=https://opencode.ai/zen/v1` plus an `AI_MEMORY_LLM_MODEL` from it; the default model id is Go's. Both take `OPENCODE_API_KEY` (key from `opencode.ai/auth`) and both get `x-opencode-session`. Alias: `opencode-zen` — historical, and it selects Go like the others; the endpoint is chosen by the base URL, not the alias. |-| `AI_MEMORY_LLM_PROVIDER=opencode` | `claude-sonnet-4-6` | [OpenCode Zen/Go](https://opencode.ai) cloud API at the OpenAI-compatible `opencode.ai/zen/go/v1` endpoint. Requests identify ai-memory by version and reuse one session header across related attempts. Set `OPENCODE_API_KEY` (key from `opencode.ai/auth`). Alias: `opencode-zen`. |++| `AI_MEMORY_LLM_PROVIDER=opencode` | `claude-sonnet-4-6` | [OpenCode](https://opencode.ai) cloud API. Defaults to the **Go** endpoint, `opencode.ai/zen/go/v1` — a cost-optimised model subset. For **Zen**'s full catalogue, set `AI_MEMORY_LLM_BASE_URL=https://opencode.ai/zen/v1` plus an `AI_MEMORY_LLM_MODEL` from it; the default model id is Go's. Requests identify ai-memory by version and reuse one session header across related attempts. Both endpoints take `OPENCODE_API_KEY` (key from `opencode.ai/auth`). Alias: `opencode-zen` — historical, and it selects Go like the others; the endpoint is chosen by the base URL, not the alias. || `AI_MEMORY_EMBEDDING_PROVIDER=openai` | `text-embedding-3-small` (1536-dim) | 5× cheaper than `-3-large` with marginal recall loss. || `AI_MEMORY_EMBEDDING_PROVIDER=openai` + `AI_MEMORY_EMBEDDING_BASE_URL=https://openrouter.ai/api/v1` | `openai/text-embedding-3-small` via [OpenRouter](https://openrouter.ai) | Uses `EMBEDDING_API_KEY`, else reuses `LLM_API_KEY` or `OPENAI_API_KEY`, with the OpenAI-compatible embedding client. || `AI_MEMORY_EMBEDDING_PROVIDER=openai` + `AI_MEMORY_EMBEDDING_BASE_URL=https://api.orcarouter.ai/v1` | `openai/text-embedding-3-small` via [OrcaRouter](https://www.orcarouter.ai) | Uses `EMBEDDING_API_KEY`, else reuses `LLM_API_KEY`, with the OpenAI-compatible embedding client. |