Skip to content

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.md
index 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 stalled
connection instead of hanging startup forever (#602): a 30s connect
timeout 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 are
left 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 work
on real stores. Both read the entity index, which was populated only
from an LLM consolidator's `entities:` frontmatter — absent on the
diff --cc crates/ai-memory-llm/src/lib.rs
index 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.rs
index 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::debug
use 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 OpenAiProvider
dialect: 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.rs
index 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 OpenAiCompatProvider
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
+ }
+
++ /// 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.rs
index 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 tests
assert!(!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.rs
index d180c129,00000000..f93cd577
mode 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.md
index 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. |