opencode-cache-engine 0.3.4 → 0.3.6

package/README.md

@@ -3,21 +3,35 @@
 Provider-aware prompt-cache optimization and observability for
 [OpenCode](https://opencode.ai).
 
-`opencode-cache-engine` is an OpenCode npm plugin with two targets:
+`opencode-cache-engine` is distributed as an npm package. The Git repository is
+the development source of truth; the published package is a release artifact.
+The package exposes two separate targets required by OpenCode's installed
+plugin model:
 
-- **Server target** — the actual cache-engine runtime and provider policies.
-- **TUI target** — registration with OpenCode's TUI plugin manager.
+- **`./server`** — the CacheEngine runtime, hooks, provider policies, and telemetry.
+- **`./tui`** — plugin-manager registration and enable/disable integration; it
+  has no CacheEngine-specific UI.
 
-The server target handles cache optimization, prompt-shape diagnostics, compaction handling, and cache telemetry. The TUI target provides the plugin-manager integration and enable/disable state for the TUI-facing plugin entry.
+For local development, use the package from this Git checkout through the
+repository's OpenCode/package development path. Do not maintain or edit a copied
+plugin under `~/.config/opencode/plugins/`. For released installs where
+reproducibility matters, pin an exact package version rather than relying on
+`@latest` resolution or a moving cache entry; see [Installation](#installation).
 
 `CacheEngine` is an OpenCode plugin designed for long-running agent sessions where prompt-cache efficiency affects both latency and cost. It keeps the harness conservative for providers whose cache behavior is already automatic, while applying provider-specific optimizations where the provider exposes useful cache controls or where prompt structure can be safely improved.
 
 The plugin currently has four cache-policy families:
 
-* **DeepSeek V4.1 Flash** — passive cache-stability and observability
-* **GPT-5.6 Luna** — active cache-control configuration
-* **GLM-5.3 Flash** — conservative system-prompt stabilization
-* **MiMo-V2.6 (Flash / Pro)** — prefix stability and OpenRouter session-affinity diagnostics
+* **DeepSeek** — passive cache observability; request structure is preserved.
+* **GPT-5.6** — documented cache-key/options metadata, with prompt text unchanged.
+* **GLM-5.3** — narrow, content-preserving `<env>` relocation and diagnostics.
+* **MiMo-V2.6** — narrow, content-preserving `<env>` relocation and diagnostics.
+
+For both MiMo-V2.6 and GLM-5.3, CacheEngine adds its deterministic
+`x-session-id` request header only when OpenCode identifies the actual provider
+as `openrouter`. It does not add that OpenRouter-specific header for
+non-OpenRouter providers; direct provider endpoints retain their provider-native
+caching behavior.
 
 The central design principle is:
 
@@ -38,7 +52,7 @@ It:
 6. Applies GPT-5.6 cache-control metadata.
 7. Applies the GLM-5.3 and MiMo-V2.6 volatile-environment relocation.
 8. Records diagnostics that help determine whether prompt-shape changes correlate with cache behavior.
-9. Records MiMo-V2.6 provider identity and provider-switch diagnostics.
+9. Records MiMo/GLM affinity outcomes and provider-identity changes.
 
 The plugin deliberately avoids pretending that a local hash is proof of a provider cache hit. Provider-reported token usage remains the authoritative signal.
 
@@ -165,7 +179,9 @@ This prevents a compaction-specific prompt from sharing the same GPT cache names
 
 ### Policy: input-shape optimization
 
-GLM-5.3 receives the only prompt-text transformation in the current plugin.
+GLM-5.3 and MiMo-V2.6 use the only prompt-text transformation in the current
+plugin: a narrow, content-preserving relocation of the identifiable `<env>`
+block for the eligible model family.
 
 The plugin identifies OpenCode's volatile `<env>` section and moves it to the **tail of the system prompt**.
 
@@ -225,6 +241,22 @@ It only occurs when:
 
 The plugin does not arbitrarily rearrange unrelated prompt content.
 
+### OpenRouter session affinity
+
+For GLM-5.3 requests whose actual OpenCode provider identity is `openrouter`,
+CacheEngine adds its deterministic `x-session-id` request header unless a
+case-insensitive `x-session-id` is already present in model or plugin headers.
+The existing value is preserved. This header is affinity metadata, not a prompt
+transformation or cache-control field.
+
+For direct Z.AI or any other non-OpenRouter endpoint, CacheEngine does not add
+the OpenRouter-specific affinity header. It leaves the endpoint's native cache
+behavior intact.
+
+Affinity observations record eligibility, the observed provider identity,
+whether a header was already present or added, and provider-identity changes
+(`glm_provider_changed`). They do not record the header value.
+
 
 ## MiMo-V2.6 (Flash / Pro)
 
@@ -287,28 +319,24 @@ Explicit telemetry events:
 * `mimo_system_env_relocated`
 * `mimo_system_prefix_changed`
 
-### OpenRouter sticky session — derived but not injected
-
-OpenRouter documents a top-level `session_id` request field for sticky provider
-routing, which keeps a session's requests on the same upstream provider so
-provider-side prompt caches stay warm.
+### OpenRouter session affinity
 
-The plugin includes a pure, session-scoped derivation (`mimoSessionIdFor`):
-deterministic, distinct per session, printable/no-whitespace, and well under the
-256-character cap. However, **the derived id is not injected into requests**.
+For MiMo-V2.6 requests whose actual OpenCode provider identity is `openrouter`,
+CacheEngine adds its existing deterministic, session-scoped `x-session-id`
+request header. If a case-insensitive `x-session-id` already exists in model or
+plugin headers, CacheEngine preserves it and does not replace it. Eligibility
+uses both the MiMo-V2.6 family and the actual provider identity; a matching model
+slug on another endpoint is not enough.
 
-Rationale (verified against the installed runtime): OpenCode's OpenRouter
-request adapter forwards only `usage`, `reasoning`, and `prompt_cache_key` from
-provider options, and exposes no top-level `session_id` path. Adding an
-unsupported field would be guessing, so the id is recorded as telemetry only,
-and `mimo26.stickySession` currently gates that recording. If a future runtime
-gains a verified `session_id` path, the helper is already in place.
+For Xiaomi's direct endpoint and every other non-OpenRouter provider, CacheEngine
+does not add its OpenRouter-specific `x-session-id`. Direct provider endpoints
+retain their provider-native caching behavior. Any header already supplied by
+the user or runtime is left untouched.
 
-Note that OpenCode itself sets `x-session-affinity` / `X-Session-Id` HTTP
-headers for non-opencode providers, and can set a flat `promptCacheKey` for
-OpenRouter when `setCacheKey: true` is configured. Those are HTTP routing
-headers and an OpenAI-style cache key respectively — they are not OpenRouter's
-documented body `session_id`.
+The `x-session-id` header is not a top-level request-body `session_id`, a
+`promptCacheKey`, or a cache-control option. MiMo uses provider-managed implicit
+caching: CacheEngine sends no undocumented `promptCacheKey`, `cacheControl`,
+cache breakpoint, or TTL.
 
 ### MiMo cache metrics
 
@@ -374,12 +402,16 @@ and are reported diagnostically; the message content is left untouched.
 
 # Provider comparison
 
-| Provider            | Detection                          | Prompt text changed?        | Cache metadata changed?            | Primary cache signal                    |
-| ------------------- | ---------------------------------- | --------------------------- | ---------------------------------- | --------------------------------------- |
-| DeepSeek V4.1 Flash | `deepseek`                         | No                          | No                                 | provider `cache.read`/`cache.write`     |
-| GPT-5.6 Luna        | `gpt-5.6*` on OpenAI-ish endpoints | No                          | Yes: `prompt_cache_key` + options  | provider cache tokens                   |
-| GLM-5.3 Flash       | `glm-5.3*`                         | Yes, narrowly (`<env>` tail) | No provider cache key              | provider cache tokens (GLM ratio)       |
-| MiMo-V2.6 Flash/Pro | `mimo-v2.6-flash` / `mimo-v2.6-pro` | Yes, narrowly (`<env>` tail) | No: implicit caching only          | `cached_tokens / prompt_tokens`         |
+| Policy family | Detection | Prompt text changed? | Cache metadata changed? | OpenRouter affinity header | Primary cache signal |
+| ------------- | --------- | ------------------- | ----------------------- | -------------------------- | -------------------- |
+| DeepSeek | `deepseek` | No | No | None | provider `cache.read` / `cache.write` |
+| GPT-5.6 | `gpt-5.6*` on OpenAI-ish endpoints | No | Yes: `prompt_cache_key` + options | None | provider cache tokens |
+| GLM-5.3 | `glm-5.3*` | Yes, narrowly (`<env>` tail) | No provider cache key | `x-session-id` on OpenRouter only | provider cache tokens (GLM ratio) |
+| MiMo-V2.6 | Flash / Pro only | Yes, narrowly (`<env>` tail) | No: implicit caching only | `x-session-id` on OpenRouter only | `cached_tokens / prompt_tokens` |
+
+`x-session-id` is an HTTP affinity header, not a provider cache key or
+cache-control field. Non-OpenRouter endpoints do not receive CacheEngine's
+OpenRouter-specific affinity value; their native cache behavior is unchanged.
 
 
 # Prompt-cache strategy
@@ -614,9 +646,17 @@ Telemetry is intended to answer questions such as:
 * Did the GLM system stabilization actually change the observed prompt shape?
 * Did MiMo's environment relocation fire (`mimo_system_env_relocated`)?
 * Did MiMo's stable system prefix change (`mimo_system_prefix_changed`)?
-* Did the MiMo provider change within a session (`mimo_provider_changed`)?
+* Was MiMo/GLM affinity eligible, and did CacheEngine add its header?
+* Was affinity bypassed for a non-OpenRouter or missing provider identity?
+* Did the MiMo provider change (`mimo_provider_changed`) or the GLM provider
+  change (`glm_provider_changed`) within a session?
 * What was MiMo's provider-reported cache hit rate (`cacheHitRate`)?
 
+Affinity observations are `boundary` records. They contain provider/model
+identity and booleans/source classification such as `eligible`,
+`headerPresent`, `headerAttached`, and `headerSource`; they do not include the
+`x-session-id` header value or full request headers.
+
 A MiMo usage record adds the provider-reported cache fields:
 
 ```json
@@ -792,6 +832,10 @@ Defaults to:
 
 Existing request options are not overwritten by the plugin.
 
+The established **272K pricing boundary** is controlled by user/harness-side
+configuration and remains unchanged. CacheEngine does not set or raise GPT
+context or output limits; apply the existing harness/user-side limits.
+
 
 # GLM-5.3 configuration
 
@@ -844,10 +888,11 @@ Enables relocation of the volatile `<env>` section to the system-prompt tail
 
 ### `stickySession`
 
-Gates derivation/recording of the OpenRouter sticky-session id
-(`mimoSessionIdFor`). The id is recorded as telemetry; it is **not** injected
-into the request because this runtime exposes no verified OpenRouter top-level
-`session_id` path. See "OpenRouter sticky session — derived but not injected".
+Controls whether MiMo usage/provider-change telemetry includes the derived
+`stickySessionId` field. It does not control the existing `x-session-id` header
+injection, which is gated by MiMo family plus actual `openrouter` provider
+identity. The telemetry field contains the derived identifier, not request
+headers or prompt data.
 
 ### `preserveThinkingIntegrity`
 
@@ -898,7 +943,10 @@ This plugin is compatible with OpenRouter because the cache policy is based on t
 
 For cache-sensitive workloads, provider stability remains important.
 
-The plugin does not attempt to compensate for provider switching by rewriting prompts. It records MiMo provider identity and provider-switch diagnostics so routing instability is at least observable.
+The plugin does not attempt to compensate for provider switching by rewriting
+prompts. For MiMo and GLM it records observed provider identity and provider
+changes so routing instability is observable; it never overrides the selected
+provider or inspects OpenRouter's hidden upstream provider selection.
 
 For that reason, a stable provider route is preferable when your goal is to measure and maximize prefix reuse.
 
@@ -929,7 +977,9 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
 }
 ```
 
-The identifier `CacheEngine` is the OpenCode plugin export name. It does not determine the eventual npm package name.
+`CacheEngine` is the exported plugin factory. The npm package name remains
+`opencode-cache-engine`; the server and TUI package exports are listed in
+[File layout](#file-layout).
 
 ---
 
@@ -1118,7 +1168,8 @@ For reliable cache measurements:
 
 # File layout
 
-A typical standalone repository can use:
+This Git repository is the canonical development source. The npm package is
+built from this tree and exposes the runtime entry points separately:
 
 ```text
 opencode-cache-engine/
@@ -1135,51 +1186,49 @@ opencode-cache-engine/
 └── LICENSE
 ```
 
-The OpenCode plugin export remains:
-
-```ts
-export const CacheEngine
-```
-
-regardless of the eventual npm package name.
-
-For example, the npm package could be named:
+The package exports in `package.json` are:
 
-```text
-opencode-cache-engine
+```json
+{
+  "./server": "./src/cache-engine.ts",
+  "./tui": "./src/tui.mjs"
+}
 ```
 
-without changing the `CacheEngine` export identifier.
+The server target owns all CacheEngine runtime hooks and request behavior. The
+TUI target only registers the package with OpenCode's plugin manager; it does
+not duplicate server logic.
 
 ---
 
 # Installation
 
-Install the plugin into the OpenCode plugins directory according to your OpenCode plugin-loading setup.
+### Local development
 
-`opencode-cache-engine` is distributed as an npm package.
+Develop against this repository/package checkout using the project's OpenCode
+plugin development path. Edit and test the Git working tree as the source of
+truth; do not copy the plugin into `~/.config/opencode/plugins/` or keep a
+second active source tree there.
 
-## Server/runtime plugin
+### Released package
 
-Add the package to the OpenCode runtime plugin configuration:
+OpenCode loads the server and TUI targets from the npm package's separate
+exports. For reproducible released installs, pin an exact version. For this
+release, use:
 
 ```json
 {
   "plugin": [
-    "opencode-cache-engine"
+    "opencode-cache-engine@0.3.6"
   ]
 }
 ```
 
-The runtime entry should expose:
-
-```ts
-export const CacheEngine: Plugin = async ({ client, directory }) => {
-  // ...
-}
-```
+Avoid a bare package name that resolves a moving `@latest` version when
+reproducibility matters. Update the pinned version deliberately when upgrading.
 
-After installation, verify that OpenCode loads the plugin successfully before benchmarking cache behavior.
+After installation, verify that OpenCode loads the plugin successfully before
+benchmarking cache behavior.
 
 ---
 
@@ -1209,7 +1258,7 @@ GLM-5.3:
 MiMo-V2.6:
     volatile env block relocated when eligible
     no GPT/GLM-only cache fields present
-    no OpenRouter top-level session_id injected (unsupported by this runtime)
+    x-session-id added only for actual OpenRouter provider identity
     telemetry carries provider/model/promptTokens/cachedTokens/cacheHitRate
 ```
 
@@ -1278,14 +1327,15 @@ not matched.
 
 ---
 
-## No OpenRouter `session_id` is sent for MiMo
+## OpenRouter affinity header is not added
 
-This is expected. The installed OpenCode runtime's OpenRouter request adapter
-forwards only `usage`, `reasoning`, and `prompt_cache_key` from provider options
-and exposes no top-level `session_id` path. The plugin derives a stable
-`stickySessionId` and records it as telemetry, but does not inject it rather than
-send an unsupported field. This may change if a future runtime exposes a verified
-path.
+CacheEngine adds its `x-session-id` only for a detected MiMo-V2.6 or GLM-5.3
+request when the actual OpenCode `providerID` is exactly `openrouter`. A direct
+provider route or missing provider identity is bypassed. If a case-insensitive
+`x-session-id` is already present in model or plugin headers, it is preserved
+and CacheEngine does not replace it. Check the `openrouter_affinity_*` boundary
+records for eligibility, provider identity, and whether CacheEngine added the
+header; the record does not include the header value.
 
 ---
 
@@ -1311,9 +1361,9 @@ The current implementation is intentionally conservative:
 
 ```text
 DeepSeek  -> preserve and measure
-GPT-5.6   -> configure cache controls
-GLM-5.3   -> isolate volatile prompt content
-MiMo-V2.6 -> stabilize prefix + observe provider/cache reality
+GPT-5.6   -> documented cache key/options; user/harness controls the 272K pricing boundary
+GLM-5.3   -> preserve-content <env> relocation + OpenRouter affinity header
+MiMo-V2.6 -> preserve-content <env> relocation + OpenRouter affinity header
 ```
 
 That separation is the core design of the project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-cache-engine",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "private": false,
   "description": "Provider-aware prompt-cache optimization and telemetry for OpenCode",
   "keywords": [

package/src/cache-engine-core.mjs

@@ -500,14 +500,51 @@ export function isOpenRouterAffinityEligible(policyFamily, providerID) {
   )
 }
 
+// Produce safe telemetry fields for one affinity-capable request. Provider
+// identity is observable and recorded; header values are deliberately not.
+// A supplied non-OpenRouter identity is classified from the observed value
+// rather than guessed against a provider allowlist.
+export function affinityTelemetryFields(policyFamily, providerID, headerSource) {
+  if (policyFamily !== POLICY_MIMO26 && policyFamily !== POLICY_GLM53) return null
+
+  const identity = typeof providerID === "string" && providerID.length > 0 ? providerID : null
+  const eligible = isOpenRouterAffinityEligible(policyFamily, identity)
+  if (!eligible) {
+    return {
+      reason: identity
+        ? "openrouter_affinity_bypassed_non_openrouter"
+        : "openrouter_affinity_bypassed_provider_missing_or_unknown",
+      eligible: false,
+      providerIdentityKnown: identity !== null,
+      provider: identity,
+      headerPresent: false,
+      headerAttached: false,
+      headerSource: "not_applicable",
+    }
+  }
+
+  const source = ["cache_engine", "preexisting", "unavailable"].includes(headerSource)
+    ? headerSource
+    : "unavailable"
+  const headerPresent = source === "cache_engine" || source === "preexisting"
+  return {
+    reason: "openrouter_affinity_eligible",
+    eligible: true,
+    providerIdentityKnown: true,
+    provider: identity,
+    headerPresent,
+    headerAttached: source === "cache_engine",
+    headerSource: source,
+  }
+}
+
 // Derive a stable, session-scoped identifier suitable for OpenRouter's
 // documented `session_id` sticky-routing key. Pure function of the OpenCode
 // session id only: identical sessions map to identical ids, distinct sessions
-// map to distinct ids, and transient request contents cannot influence it.
-// The value is printable, contains no whitespace, and is far below the 256-char
-// cap (25 chars). NOTE: this runtime's OpenRouter request adapter does not emit
-// a top-level `session_id` (it forwards only usage/reasoning/prompt_cache_key),
-// so this id is currently recorded as telemetry only and is never injected.
+// map to distinct ids, and transient request contents cannot influence it. The
+// value is printable, contains no whitespace, and is far below the 256-char cap
+// (25 chars). The plugin uses it as the existing OpenRouter x-session-id header
+// value for eligible MiMo/GLM requests.
 export function mimoSessionIdFor(sessionID) {
   if (typeof sessionID !== "string" || sessionID.length === 0) return null
   return `mimo-ses-${shorthash(sessionID)}`

package/src/cache-engine.ts

@@ -3,6 +3,7 @@ import type { Event, Message, Part } from "@opencode-ai/sdk"
 import {
   DEFAULT_CONFIG_PATH,
   DIGEST_TEMPLATE,
+  affinityTelemetryFields,
   POLICY_GLM53,
   POLICY_GPT56,
   POLICY_MIMO26,
@@ -127,6 +128,7 @@ type SessionState = {
   reasoningSeen: Map<string, number>
   reasoningLastSeq: string[] | null
   mimoProvider: { providerID: string; modelID: string } | null
+  glmProvider: { providerID: string; modelID: string } | null
 }
 
 const emptyShape = (): Shape => ({
@@ -175,6 +177,7 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
         reasoningSeen: new Map(),
         reasoningLastSeq: null,
         mimoProvider: null,
+        glmProvider: null,
       }
       sessions.set(sid, s)
     }
@@ -493,14 +496,37 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
         const model = input.model as unknown as ChatParamsModel
         const providerID = String(model?.providerID ?? "")
         const family = detectPolicy(model)
-        if (providerID !== "openrouter" || (family !== POLICY_MIMO26 && family !== POLICY_GLM53)) return
+        if (family !== POLICY_MIMO26 && family !== POLICY_GLM53) return
 
         const hasSessionIDHeader = (headers?: Record<string, string>) =>
           Object.keys(headers ?? {}).some((name) => name.toLowerCase() === "x-session-id")
-        if (hasSessionIDHeader(model?.headers) || hasSessionIDHeader(output.headers)) return
+        let headerSource = "not_applicable"
+        if (providerID === "openrouter") {
+          if (hasSessionIDHeader(model?.headers) || hasSessionIDHeader(output.headers)) {
+            headerSource = "preexisting"
+          } else {
+            const sessionID = mimoSessionIdFor(input.sessionID)
+            if (sessionID) {
+              output.headers["x-session-id"] = sessionID
+              headerSource = "cache_engine"
+            } else {
+              headerSource = "unavailable"
+            }
+          }
+        }
 
-        const sessionID = mimoSessionIdFor(input.sessionID)
-        if (sessionID) output.headers["x-session-id"] = sessionID
+        const telemetry = affinityTelemetryFields(family, providerID, headerSource)
+        if (telemetry) {
+          rec.record({
+            kind: "boundary",
+            sid: input.sessionID,
+            ts: Date.now(),
+            policy: family,
+            provider: telemetry.provider,
+            model: String(model?.api?.id ?? model?.id ?? "") || null,
+            ...telemetry,
+          })
+        }
       } catch (e) {
         rec.record({ kind: "telemetry-error", ts: Date.now(), error: String(e) })
       }
@@ -552,6 +578,33 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
           return
         }
 
+        // ---- GLM-5.3 provider identity observation (telemetry only) ----------
+        if (family === POLICY_GLM53 && policyEnabled(cfg, POLICY_GLM53) && info) {
+          const live = input.model as unknown as ChatParamsModel
+          const cur = {
+            providerID: String(live?.providerID ?? ""),
+            modelID: String(live?.api?.id ?? live?.id ?? ""),
+          }
+          if (cur.providerID) {
+            const s = get(input.sessionID)
+            const ev = providerChangeEvent(s.glmProvider, cur)
+            if (ev.changed) {
+              rec.record({
+                kind: "boundary",
+                sid: input.sessionID,
+                ts: Date.now(),
+                reason: "glm_provider_changed",
+                policy: POLICY_GLM53,
+                from: ev.from,
+                to: ev.to,
+                note: "OpenCode providerID changed; provider-specific upstream routing is not plugin-visible",
+              })
+            }
+            s.glmProvider = cur
+          }
+          return
+        }
+
         if (!(family === POLICY_GPT56 && policyEnabled(cfg, POLICY_GPT56))) {
           // DeepSeek / GLM / neutral: nothing to inject. GLM has no cache-key API;
           // DeepSeek caching is fully passive; we never mutate requests for them.

package/test/cache-engine.test.mjs

@@ -19,6 +19,7 @@ import {
   POLICY_GPT56,
   POLICY_MIMO26,
   POLICY_NEUTRAL,
+  affinityTelemetryFields,
   canonicalStringify,
   commonPrefixLength,
   createRecorder,
@@ -938,6 +939,42 @@ test("OpenRouter affinity is ineligible for unknown families and providers", ()
   assert.equal(isOpenRouterAffinityEligible(POLICY_MIMO26, undefined), false)
 })
 
+test("affinity telemetry fields classify eligibility, attachment, bypass, and missing identity", () => {
+  assert.deepEqual(affinityTelemetryFields(POLICY_MIMO26, "openrouter", "cache_engine"), {
+    reason: "openrouter_affinity_eligible",
+    eligible: true,
+    providerIdentityKnown: true,
+    provider: "openrouter",
+    headerPresent: true,
+    headerAttached: true,
+    headerSource: "cache_engine",
+  })
+  assert.deepEqual(affinityTelemetryFields(POLICY_GLM53, "openrouter", "preexisting"), {
+    reason: "openrouter_affinity_eligible",
+    eligible: true,
+    providerIdentityKnown: true,
+    provider: "openrouter",
+    headerPresent: true,
+    headerAttached: false,
+    headerSource: "preexisting",
+  })
+  assert.equal(affinityTelemetryFields(POLICY_MIMO26, "xiaomi", "not_applicable").reason,
+    "openrouter_affinity_bypassed_non_openrouter")
+  assert.equal(affinityTelemetryFields(POLICY_GLM53, "unknown-provider", "not_applicable").reason,
+    "openrouter_affinity_bypassed_non_openrouter")
+  assert.deepEqual(affinityTelemetryFields(POLICY_MIMO26, "", "not_applicable"), {
+    reason: "openrouter_affinity_bypassed_provider_missing_or_unknown",
+    eligible: false,
+    providerIdentityKnown: false,
+    provider: null,
+    headerPresent: false,
+    headerAttached: false,
+    headerSource: "not_applicable",
+  })
+  assert.equal(affinityTelemetryFields(POLICY_DEEPSEEK, "openrouter", "not_applicable"), null)
+  assert.equal(affinityTelemetryFields(POLICY_GPT56, "openrouter", "not_applicable"), null)
+})
+
 // ===========================================================================
 // MiMo-V2.6: cached/prompt token metrics
 // ===========================================================================
@@ -1019,8 +1056,10 @@ async function runMiMoHeaderHookProbe() {
   const coreURL = new URL("../src/cache-engine-core.mjs", import.meta.url).href
   const script = `
     import assert from "node:assert/strict"
+    import { readFileSync } from "node:fs"
+    process.env.CACHE_ENGINE_METRICS_FILE = process.env.HOME + "/affinity-metrics.jsonl"
     const { CacheEngine } = await import(${JSON.stringify(pluginURL)})
-    const { mimoSessionIdFor } = await import(${JSON.stringify(coreURL)})
+    const { detectPolicy, mimoSessionIdFor, POLICY_GLM53, POLICY_MIMO26 } = await import(${JSON.stringify(coreURL)})
     const client = {
       app: { log: async () => ({}) },
       session: { get: async () => ({ data: { parentID: null } }) },
@@ -1031,6 +1070,16 @@ async function runMiMoHeaderHookProbe() {
     const invoke = async (model, sessionID, existingHeaders = {}) => {
       const output = { headers: { ...existingHeaders } }
       const headersRef = output.headers
+      const family = detectPolicy(model)
+      if (family === POLICY_MIMO26 || family === POLICY_GLM53) {
+        await hooks["chat.params"]({
+          sessionID,
+          agent: "build",
+          model,
+          provider: { source: "config", info: { id: model.providerID }, options: {} },
+          message: { id: "msg", sessionID, role: "user", content: "probe" },
+        }, { options: {} })
+      }
       await hooks["chat.headers"]({
         sessionID,
         agent: "build",
@@ -1062,6 +1111,10 @@ async function runMiMoHeaderHookProbe() {
     const glm2 = await invoke(glmOpenRouter, "ses_glm_same")
     const glmDifferent = await invoke(glmOpenRouter, "ses_glm_other")
     const glmDirect = await invoke({ ...glmOpenRouter, providerID: "zai" }, "ses_glm_direct", { "User-Agent": "preserve-glm" })
+    const mimoSwitchOpen = await invoke(mimoOpenRouter, "ses_mimo_switch")
+    const mimoSwitchDirect = await invoke({ ...mimoOpenRouter, providerID: "xiaomi" }, "ses_mimo_switch")
+    const glmSwitchOpen = await invoke(glmOpenRouter, "ses_glm_switch")
+    const glmSwitchDirect = await invoke({ ...glmOpenRouter, providerID: "zai" }, "ses_glm_switch")
     const nonOpenRouterMatrix = [
       ["mimo-direct", { ...mimoOpenRouter, providerID: "xiaomi" }],
       ["glm-direct", { ...glmOpenRouter, providerID: "zai" }],
@@ -1101,6 +1154,10 @@ async function runMiMoHeaderHookProbe() {
       glm2,
       glmDifferent,
       glmDirect,
+      mimoSwitchOpen,
+      mimoSwitchDirect,
+      glmSwitchOpen,
+      glmSwitchDirect,
       compatibility,
       gptOptions: gptOutput.options,
       configured,
@@ -1110,6 +1167,8 @@ async function runMiMoHeaderHookProbe() {
       expectedOther: mimoSessionIdFor("ses_other"),
       expectedGlm: mimoSessionIdFor("ses_glm_same"),
       expectedGlmOther: mimoSessionIdFor("ses_glm_other"),
+      telemetry: readFileSync(process.env.CACHE_ENGINE_METRICS_FILE, "utf8")
+        .trim().split("\\n").filter(Boolean).map((line) => JSON.parse(line)),
     }
     assert.equal(configured.headers["x-session-id"], undefined)
     assert.equal(earlierPlugin.headers["X-SESSION-ID"], "earlier-plugin-value")
@@ -1186,3 +1245,74 @@ test("OpenAI GPT retains its existing chat.params cache options without affinity
   assert.equal(typeof result.gptOptions.promptCacheKey, "string")
   assert.deepEqual(result.gptOptions.promptCacheOptions, { mode: "implicit", ttl: "30m" })
 })
+
+test("affinity telemetry classifies eligible, attached, preexisting, bypassed, and missing-provider requests", async () => {
+  const result = await miMoHeaderResults()
+  const events = result.telemetry.filter((event) => event.reason?.startsWith("openrouter_affinity_"))
+  const eventFor = (sid, policy) => events.find((event) => event.sid === sid && event.policy === policy)
+
+  for (const [sid, policy] of [
+    ["ses_same", POLICY_MIMO26],
+    ["ses_glm_same", POLICY_GLM53],
+  ]) {
+    const event = eventFor(sid, policy)
+    assert.equal(event.reason, "openrouter_affinity_eligible")
+    assert.equal(event.eligible, true)
+    assert.equal(event.provider, "openrouter")
+    assert.equal(event.headerPresent, true)
+    assert.equal(event.headerAttached, true)
+    assert.equal(event.headerSource, "cache_engine")
+  }
+
+  const configured = eventFor("ses_configured", POLICY_MIMO26)
+  assert.equal(configured.reason, "openrouter_affinity_eligible")
+  assert.equal(configured.headerPresent, true)
+  assert.equal(configured.headerAttached, false)
+  assert.equal(configured.headerSource, "preexisting")
+
+  for (const [sid, policy, provider] of [
+    ["ses_direct", POLICY_MIMO26, "xiaomi"],
+    ["ses_glm_direct", POLICY_GLM53, "zai"],
+    ["ses_unknown", POLICY_MIMO26, "unknown-provider"],
+  ]) {
+    const event = eventFor(sid, policy)
+    assert.equal(event.reason, "openrouter_affinity_bypassed_non_openrouter")
+    assert.equal(event.eligible, false)
+    assert.equal(event.provider, provider)
+    assert.equal(event.headerAttached, false)
+  }
+
+  const missing = eventFor("ses_missing_provider", POLICY_MIMO26)
+  assert.equal(missing.reason, "openrouter_affinity_bypassed_provider_missing_or_unknown")
+  assert.equal(missing.providerIdentityKnown, false)
+  assert.equal(missing.provider, null)
+  assert.equal(missing.headerAttached, false)
+
+  // New affinity-observation records contain classifications, never the
+  // generated or pre-existing x-session-id value.
+  for (const event of events) {
+    assert.equal(Object.hasOwn(event, "x-session-id"), false)
+    assert.equal(Object.hasOwn(event, "headerValue"), false)
+  }
+  const serializedAffinityEvents = JSON.stringify(events)
+  assert.equal(serializedAffinityEvents.includes(result.expectedSame), false)
+  assert.equal(serializedAffinityEvents.includes(result.expectedGlm), false)
+})
+
+test("affinity telemetry preserves non-OpenRouter families and reports provider changes", async () => {
+  const result = await miMoHeaderResults()
+  const events = result.telemetry
+  const affinityEvents = events.filter((event) => event.reason?.startsWith("openrouter_affinity_"))
+  assert.equal(affinityEvents.some((event) => event.policy === POLICY_DEEPSEEK), false)
+  assert.equal(affinityEvents.some((event) => event.policy === POLICY_GPT56), false)
+
+  const mimoChange = events.find((event) => event.reason === "mimo_provider_changed" && event.sid === "ses_mimo_switch")
+  assert.equal(mimoChange.from.providerID, "openrouter")
+  assert.equal(mimoChange.to.providerID, "xiaomi")
+
+  const glmChange = events.find((event) => event.reason === "glm_provider_changed" && event.sid === "ses_glm_switch")
+  assert.equal(glmChange.kind, "boundary")
+  assert.equal(glmChange.from.providerID, "openrouter")
+  assert.equal(glmChange.to.providerID, "zai")
+  assert.equal(glmChange.policy, POLICY_GLM53)
+})