opencode-cache-engine 0.1.1 → 0.3.0

package/README.md

@@ -1,20 +1,28 @@
 # OpenCode Cache Engine
 
-Provider-aware prompt-cache optimization and observability for [OpenCode](https://opencode.ai).
+Provider-aware prompt-cache optimization and observability for
+[OpenCode](https://opencode.ai).
+
+`opencode-cache-engine` is an OpenCode npm plugin with two targets:
+
+- **Server target** — the actual cache-engine runtime and provider policies.
+- **TUI target** — registration with OpenCode's TUI plugin manager.
+
+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.
 
 `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 three cache-policy families:
+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
 
 The central design principle is:
 
 > Optimize the request structure only when there is a clear provider-specific reason to do so. Otherwise, preserve OpenCode's native request behavior and measure what the provider actually reports.
 
----
 
 ## What this plugin does
 
@@ -28,12 +36,12 @@ It:
 4. Records provider-reported cache token usage.
 5. Adds a deterministic compaction continuation block.
 6. Applies GPT-5.6 cache-control metadata.
-7. Applies the GLM-5.3 volatile-environment relocation.
+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.
 
 The plugin deliberately avoids pretending that a local hash is proof of a provider cache hit. Provider-reported token usage remains the authoritative signal.
 
----
 
 # Provider behavior
 
@@ -88,7 +96,6 @@ DeepSeek:
     force cache behavior
 ```
 
----
 
 ## GPT-5.6 Luna
 
@@ -153,7 +160,6 @@ compaction:
 
 This prevents a compaction-specific prompt from sharing the same GPT cache namespace as the normal live-session prompt. The behavior is deterministic and tested explicitly.
 
----
 
 ## GLM-5.3 Flash
 
@@ -219,17 +225,168 @@ It only occurs when:
 
 The plugin does not arbitrarily rearrange unrelated prompt content.
 
----
 
-# Prompt-cache strategy
+## MiMo-V2.6 (Flash / Pro)
+
+### Policy: prefix stability + OpenRouter session affinity
+
+MiMo-V2.6 is Xiaomi's current model family. The plugin targets exactly two
+identifiers:
+
+* `xiaomi/mimo-v2.6-flash` / `mimo-v2.6-flash`
+* `xiaomi/mimo-v2.6-pro` / `mimo-v2.6-pro`
+
+Detection also tolerates `provider/model` shapes where `api.id` contains those
+slugs. It deliberately does **not** match `mimo-v2.5`, `mimo-v2.5-pro`,
+`mimo-v2.6-pro-ultraspeed`, or unrelated MiMo models.
+
+### Implicit context caching
+
+Xiaomi documents context caching for both V2.6 Flash and Pro, and exposes
+`usage.prompt_tokens_details.cached_tokens` as the number of prompt tokens
+served from cache. The V2.6 API documents implicit context caching, not a
+user-supplied cache key or explicit breakpoint.
+
+Accordingly the plugin **injects no cache-control parameter** for MiMo. It does
+not send `promptCacheKey`, `cacheControl`, `cacheBreakpoint`, or `ttl`.
+Implicit caching is the default assumption.
+
+### Environment-block stabilization
+
+MiMo uses the same narrow, content-preserving transformation as GLM-5.3: the
+identifiable volatile `<env>` block is relocated to the **tail** of the single
+system string. Contents are preserved byte-for-byte; only position changes. This
+keeps the large reusable prefix stable when only the environment/date changes.
 
-The plugin uses three different strategies because cache mechanisms differ by provider.
+The transformation is applied only when:
 
-| Provider          | Prompt text changed? | Cache metadata changed? | Main strategy                     |
-| ----------------- | -------------------: | ----------------------: | --------------------------------- |
-| DeepSeek V4.1 Flash |                   No |                      No | Preserve stable harness + observe |
-| GPT-5.6 Luna      |                   No |                     Yes | Stable cache key + cache options  |
-| GLM-5.3 Flash     |        Yes, narrowly |   No provider cache key | Isolate volatile system content   |
+* the selected model is MiMo-V2.6 Flash/Pro
+* `mimo26.stabilizeSystem` is `true`
+* there is exactly one system string
+* the expected `<env>` markers exist and the block is identified unambiguously
+* the block is not already at the tail
+
+### No generic system-prompt freezing
+
+MiMo-Code's own harness freezes its per-session system prefix. This plugin does
+**not** copy that mechanism. System instructions can legitimately change because
+of permissions, tools, agent mode, skills, MCP state, or project configuration;
+a plugin-level snapshot must never override a legitimate change.
+
+Instead the plugin:
+
+* records a first-seen system baseline per session;
+* computes the full system hash, stable prefix hash, and volatile suffix hash;
+* records changes for MiMo sessions;
+* allows the `<env>` relocation when that is the only identified volatility;
+* reports other system changes diagnostically and never overwrites the new
+  content.
+
+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.
+
+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**.
+
+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.
+
+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`.
+
+### MiMo cache metrics
+
+MiMo caches are provider-managed, so the authoritative metric is provider
+reported. For MiMo the plugin emits the preferred ratio:
+
+```text
+cacheHitRate = cachedTokens / promptTokens
+```
+
+This is intentionally **not** the `read / (read + write)` form used by other
+families. It is not GLM's `read / (read + write + input)` either.
+
+Derivation: the runtime exposes assistant tokens as `{ input, output,
+cache:{ read, write } }`, where `input` is the non-cached prompt input and
+`cache.read` is the cached prompt input. Total prompt tokens are therefore
+derived as `read + input`, and `cachedTokens = read`. `cache.write` is a
+separate accounting bucket and is not folded in; no cache-write value is
+fabricated, and the ratio is `null` when `promptTokens` is zero.
+
+A MiMo usage record looks conceptually like:
+
+```json
+{
+  "kind": "usage",
+  "policy": "mimo26",
+  "provider": "openrouter",
+  "model": "xiaomi/mimo-v2.6-flash",
+  "promptTokens": 50000,
+  "cachedTokens": 47000,
+  "cacheHitRate": 94
+}
+```
+
+### Provider-switch diagnostics
+
+Because MiMo caches live at the provider side, a provider change within one
+session can silently invalidate them. The plugin records provider identity on
+every MiMo request and emits a `mimo_provider_changed` boundary event when the
+OpenCode `providerID` changes within a session. It never forces or overrides the
+user's provider selection.
+
+Limitation: OpenRouter's *upstream* provider selection (for example
+`xiaomi/fp8` vs `atlas-cloud/fp8`) is not exposed to plugins, so only the
+OpenCode `providerID`/`modelID` are observable.
+
+### Reasoning / thinking
+
+MiMo-V2.6 supports deep thinking and reports reasoning tokens. The plugin does
+not treat reasoning replay as a cache requirement: reasoning diagnostics are
+instrumentation only, and the plugin never rewrites, duplicates, reorders, or
+re-injects reasoning content, nor changes reasoning effort for caching.
+
+### Skill-catalog / history limitation
+
+MiMo-Code moved skill catalogs out of repeatedly rewritten user messages and
+toward the system tail. In this OpenCode runtime the skill guidance
+(`<available_skills>`) and MCP instructions already live in the **system
+prefix**, not in user-message history. The plugin therefore performs no
+message-history rewrite. Skill/MCP changes simply appear as system-prefix changes
+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`         |
+
+
+# Prompt-cache strategy
+
+The plugin uses different strategies because cache mechanisms differ by provider.
+The table above summarises them; the essential point is the distinction between
+*changing prompt text* and *changing cache metadata*.
 
 This distinction is fundamental.
 
@@ -237,7 +394,6 @@ The plugin is **not** a generic "rewrite every prompt for caching" engine.
 
 It is a provider-aware cache policy engine.
 
----
 
 # System-prompt diagnostics
 
@@ -261,7 +417,6 @@ It does **not** mean:
 
 This distinction is intentional. Provider-reported cache token counts are the authoritative cache signal.
 
----
 
 # Tool-definition diagnostics
 
@@ -294,7 +449,6 @@ This distinction matters because semantic equality and byte-level request equali
 
 The plugin uses these fingerprints for **diagnostics only**. It does not reorder the tools to force a particular fingerprint.
 
----
 
 # Compaction handling
 
@@ -313,7 +467,6 @@ The plugin adds a deterministic continuation template:
 The digest is inserted once per compaction operation using a guard that prevents duplicate insertion if the compaction hook fires multiple times.
 The objective is to provide a deterministic continuation structure rather than generating a different arbitrary cache-affecting block on every compaction.
 
----
 
 # Cache metrics
 
@@ -350,6 +503,15 @@ read / (read + write + input)
 
 as implemented by `glmHitRatio()`.
 
+For MiMo, the implementation uses the provider-documented prompt-cache ratio:
+
+```text
+cacheHitRate = cachedTokens / promptTokens
+```
+
+implemented by `mimoHitRate()`. `hitRatePct()` itself is left untouched so other
+providers are unaffected.
+
 ### Important metric distinction
 
 These ratios answer different questions.
@@ -362,7 +524,12 @@ These ratios answer different questions.
 
 > How much of the total prompt-token accounting was represented by cached reads?
 
-Do not treat the two percentages as interchangeable.
+`cachedTokens / promptTokens` (MiMo) answers:
+
+> Of the prompt tokens the provider processed, what fraction was served from
+> cache?
+
+Do not treat these percentages as interchangeable.
 
 ---
 
@@ -388,7 +555,6 @@ Telemetry is best-effort.
 
 A failed metrics write must never break an OpenCode request. The recorder catches write failures rather than allowing telemetry failures to affect execution.
 
----
 
 # Metrics examples
 
@@ -446,8 +612,30 @@ Telemetry is intended to answer questions such as:
 * Did a compaction occur?
 * Which provider/model/policy was active?
 * 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`)?
+* What was MiMo's provider-reported cache hit rate (`cacheHitRate`)?
+
+A MiMo usage record adds the provider-reported cache fields:
+
+```json
+{
+  "kind": "usage",
+  "sid": "session-id",
+  "ts": 1750000000000,
+  "policy": "mimo26",
+  "provider": "openrouter",
+  "model": "xiaomi/mimo-v2.6-flash",
+  "read": 47000,
+  "input": 3000,
+  "promptTokens": 50000,
+  "cachedTokens": 47000,
+  "cacheHitRate": 94,
+  "stickySessionId": "mimo-ses-0123456789abcdef"
+}
+```
 
----
 
 # Configuration
 
@@ -476,6 +664,12 @@ The default configuration is:
       "enabled": true,
       "stabilizeSystem": true,
       "preserveThinkingIntegrity": true
+    },
+    "mimo26": {
+      "enabled": true,
+      "stabilizeSystem": true,
+      "stickySession": true,
+      "preserveThinkingIntegrity": true
     }
   }
 }
@@ -483,7 +677,6 @@ The default configuration is:
 
 The configuration parser starts from these defaults and applies valid file/environment overrides without mutating the caller's configuration object.
 
----
 
 # Configuration options
 
@@ -535,7 +728,6 @@ Controls whether the deterministic compaction continuation block is inserted.
 
 Controls warning logs for observed prefix-shape changes.
 
----
 
 # DeepSeek configuration
 
@@ -549,7 +741,6 @@ There are intentionally very few settings here.
 
 DeepSeek is treated as the conservative/passive policy.
 
----
 
 # GPT-5.6 configuration
 
@@ -601,7 +792,6 @@ Defaults to:
 
 Existing request options are not overwritten by the plugin.
 
----
 
 # GLM-5.3 configuration
 
@@ -629,7 +819,45 @@ The reasoning instrumentation is intended to identify anomalies such as:
 
 It is diagnostic rather than a reason to rewrite or fabricate reasoning content. The implementation maps these conditions to explicit diagnostic reasons.
 
----
+
+# MiMo-V2.6 configuration
+
+```json
+{
+  "mimo26": {
+    "enabled": true,
+    "stabilizeSystem": true,
+    "stickySession": true,
+    "preserveThinkingIntegrity": true
+  }
+}
+```
+
+### `enabled`
+
+Enables the MiMo-V2.6 policy.
+
+### `stabilizeSystem`
+
+Enables relocation of the volatile `<env>` section to the system-prompt tail
+(same narrow, content-preserving transformation as GLM-5.3).
+
+### `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".
+
+### `preserveThinkingIntegrity`
+
+Enables reasoning diagnostics as instrumentation. It never rewrites, duplicates,
+reorders, or re-injects reasoning content, and it is not a cache requirement.
+
+No `cacheBlockSize`, `cacheTTL`, `cacheBreakpoint`, or `minimumCacheTokens`
+knobs are exposed: those values are not established by authoritative V2.6
+documentation.
+
 
 # Model detection
 
@@ -639,6 +867,7 @@ The plugin classifies requests into:
 deepseek
 gpt56
 glm53
+mimo26
 neutral
 ```
 
@@ -647,9 +876,13 @@ The model detector recognizes:
 * DeepSeek model/provider identifiers
 * GPT-5.6 variants
 * GLM-5.3 variants
+* MiMo-V2.6 Flash and Pro (`xiaomi/mimo-v2.6-flash`, `mimo-v2.6-pro`, ...)
 
 GPT-5.6 has an additional OpenAI/Azure-context check so a string containing `gpt-5.6` does not automatically cause GPT-specific fields to be sent to an unrelated endpoint.
 
+MiMo detection targets exactly Flash and Pro: it excludes `mimo-v2.5`,
+`mimo-v2.5-pro`, and `mimo-v2.6-pro-ultraspeed`.
+
 Unknown models use the neutral policy.
 
 Neutral means:
@@ -658,7 +891,6 @@ Neutral means:
 no provider-specific request mutation
 ```
 
----
 
 # OpenRouter usage
 
@@ -666,11 +898,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.
+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.
 
 For that reason, a stable provider route is preferable when your goal is to measure and maximize prefix reuse.
 
----
 
 # Architecture
 
@@ -893,14 +1124,15 @@ A typical standalone repository can use:
 opencode-cache-engine/
 ├── src/
 │   ├── cache-engine.ts
-│   └── cache-engine-core.mjs
+│   ├── cache-engine-core.mjs
+│   └── tui.mjs
 ├── test/
 │   └── cache-engine.test.mjs
 ├── examples/
 │   └── cache-engine.json
+├── package.json
 ├── README.md
-├── LICENSE
-└── package.json
+└── LICENSE
 ```
 
 The OpenCode plugin export remains:
@@ -925,6 +1157,20 @@ without changing the `CacheEngine` export identifier.
 
 Install the plugin into the OpenCode plugins directory according to your OpenCode plugin-loading setup.
 
+`opencode-cache-engine` is distributed as an npm package.
+
+## Server/runtime plugin
+
+Add the package to the OpenCode runtime plugin configuration:
+
+```json
+{
+  "plugin": [
+    "opencode-cache-engine"
+  ]
+}
+```
+
 The runtime entry should expose:
 
 ```ts
@@ -959,6 +1205,12 @@ GPT-5.6:
 
 GLM-5.3:
     volatile env block relocated when eligible
+
+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)
+    telemetry carries provider/model/promptTokens/cachedTokens/cacheHitRate
 ```
 
 ---
@@ -1001,6 +1253,42 @@ The relevant block must contain the expected beginning and closing marker, and t
 
 ---
 
+## MiMo-V2.6 prompt is not being changed
+
+MiMo uses the same eligibility rules as GLM-5.3: exactly one system string, both
+`<env>` markers present, block identified unambiguously, and
+`mimo26.stabilizeSystem` enabled. If the block is already at the tail, the
+operation is a no-op.
+
+---
+
+## MiMo provider is not classified as `mimo26`
+
+Verify the model identifier is exactly Flash or Pro:
+
+```text
+mimo-v2.6-flash
+mimo-v2.6-pro
+xiaomi/mimo-v2.6-flash
+xiaomi/mimo-v2.6-pro
+```
+
+`mimo-v2.5`, `mimo-v2.5-pro`, and `mimo-v2.6-pro-ultraspeed` are intentionally
+not matched.
+
+---
+
+## No OpenRouter `session_id` is sent for MiMo
+
+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.
+
+---
+
 ## Metrics file is missing
 
 Telemetry is best-effort.
@@ -1025,6 +1313,7 @@ The current implementation is intentionally conservative:
 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
 ```
 
 That separation is the core design of the project.

package/examples/cache-engine.json

@@ -20,6 +20,12 @@
       "enabled": true,
       "stabilizeSystem": true,
       "preserveThinkingIntegrity": true
+    },
+    "mimo26": {
+      "enabled": true,
+      "stabilizeSystem": true,
+      "stickySession": true,
+      "preserveThinkingIntegrity": true
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-cache-engine",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "private": false,
   "description": "Provider-aware prompt-cache optimization and telemetry for OpenCode",
   "keywords": [
@@ -9,7 +9,8 @@
     "prompt-cache",
     "deepseek",
     "glm",
-    "gpt"
+    "gpt",
+    "mimo"
   ],
   "homepage": "https://github.com/AlexJoaquimPereira/opencode-cache-engine#readme",
   "bugs": {
@@ -27,6 +28,10 @@
     "example": "examples",
     "test": "test"
   },
+  "exports": {
+    "./server": "./src/cache-engine.ts",
+    "./tui": "./src/tui.mjs"
+  },
   "scripts": {
     "test": "node --test test/cache-engine.test.mjs",
     "postpublish": "VERSION=$(node -p \"require('./package').version\") && TAG=v$VERSION && echo \"Creating git tag $TAG for npm $VERSION\" && git tag $TAG && git push origin $TAG || echo \"Tag $TAG may already exist or push failed; continuing.\"",

package/src/cache-engine-core.mjs

@@ -5,9 +5,10 @@
 // TypeScript compiler. The plugin entry (cache-engine.ts) imports this module.
 //
 // This module is PROVIDER-AWARE: it classifies a model into a cache-policy
-// family (deepseek | gpt56 | glm53 | neutral) and exposes small pure helpers for
-// each family's strategy. The plugin entry (cache-engine.ts) remains the only
-// place that touches OpenCode hooks; every decision here is testable in Node.
+// family (deepseek | gpt56 | glm53 | mimo26 | neutral) and exposes small pure
+// helpers for each family's strategy. The plugin entry (cache-engine.ts) remains
+// the only place that touches OpenCode hooks; every decision here is testable in
+// Node.
 //
 // Terminology note: these functions deal with the *observed* system/tool
 // prefix shape. An observed change means the request's prefix bytes changed; it
@@ -35,6 +36,7 @@ export const DIGEST_TEMPLATE = `## Session digest (cache-stable continuation blo
 export const POLICY_DEEPSEEK = "deepseek"
 export const POLICY_GPT56 = "gpt56"
 export const POLICY_GLM53 = "glm53"
+export const POLICY_MIMO26 = "mimo26"
 export const POLICY_NEUTRAL = "neutral"
 
 export const GPT56_DEFAULT_TTL = "30m"
@@ -65,6 +67,15 @@ function defaultPolicies() {
       stabilizeSystem: true,
       preserveThinkingIntegrity: true,
     },
+    mimo26: {
+      enabled: true,
+      stabilizeSystem: true,
+      stickySession: true,
+      // MiMo reasoning diagnostics are instrumentation only. Unlike GLM
+      // preserved thinking, there is no evidence that MiMo prompt-cache reuse
+      // depends on reasoning replay, so this never rewrites reasoning content.
+      preserveThinkingIntegrity: true,
+    },
   }
 }
 
@@ -118,7 +129,7 @@ export function parseConfig(raw, env) {
     if (typeof raw.logPrefixChanges === "boolean") cfg.logPrefixChanges = raw.logPrefixChanges
     if (raw.policies && typeof raw.policies === "object") {
       const d = defaultPolicies()
-      for (const fam of ["deepseek", "gpt56", "glm53"]) {
+      for (const fam of ["deepseek", "gpt56", "glm53", "mimo26"]) {
         if (raw.policies[fam]) cfg.policies[fam] = parsePolicy(raw.policies[fam], d[fam])
       }
     }
@@ -232,6 +243,10 @@ function isOpenAIish(s) {
 const GPT56_RE = /gpt-5\.6(?![\d.])/i
 // GLM 5.3 family only (not glm-4.x / glm-4.6 etc).
 const GLM53_RE = /glm-5\.3(?![\d.])/i
+// Xiaomi MiMo V2.6 explicitly targets Flash + Pro only. The trailing
+// (?![\w-]) guard prevents matching a hypothetical "mimo-v2.6-pro-ultraspeed"
+// or "mimo-v2.6-flashx", and the v2\.6 literal excludes V2.5 / V2.
+const MIMO26_RE = /mimo-v2\.6-(flash|pro)(?![\w-])/i
 const DEEPSEEK_RE = /deepseek/i
 
 // Pure classifier. Returns one of the POLICY_* keys. `model` may be a full
@@ -242,6 +257,7 @@ export function detectPolicy(model) {
   if (!s.slug) return POLICY_NEUTRAL
   if (GPT56_RE.test(s.slug) && isOpenAIish(s)) return POLICY_GPT56
   if (GLM53_RE.test(s.slug)) return POLICY_GLM53
+  if (MIMO26_RE.test(s.slug)) return POLICY_MIMO26
   if (DEEPSEEK_RE.test(s.slug) || DEEPSEEK_RE.test(s.providerID)) return POLICY_DEEPSEEK
   return POLICY_NEUTRAL
 }
@@ -284,16 +300,17 @@ export function gptCacheOptionsDelta(existingOptions, { key, mode = GPT56_DEFAUL
 
 // The OpenCode system string begins with the agent prompt, then an env block
 // ("You are powered by the model named ... Today's date: ... </env>") whose
-// only per-day volatile byte is the date line. For GLM-5.3 we relocate that
-// whole identifiable env block to the END of the system string so a daily date
-// change only invalidates the tail of the prompt, leaving the long stable
-// prefix intact. Content is preserved byte-for-byte (only position changes).
+// only per-day volatile byte is the date line. For GLM-5.3 and MiMo-V2.6 we
+// relocate that whole identifiable env block to the END of the system string so
+// a daily date change only invalidates the tail of the prompt, leaving the long
+// stable prefix intact. Content is preserved byte-for-byte (only position
+// changes).
 //
 // Returns { text, changed }. When the block cannot be identified unambiguously,
 // returns the input unchanged (changed:false). This is a content-preserving
 // reorder of clearly volatile metadata only -- it never reorders arbitrary
 // instructions. This function is ONLY applied when the caller has already
-// classified the model as GLM-5.3.
+// classified the model into a family that opts into system stabilization.
 export function relocateVolatileEnvBlock(text) {
   if (typeof text !== "string") return { text, changed: false }
   const START = "You are powered by the model named "
@@ -438,6 +455,56 @@ export function glmHitRatio(read, write, input) {
   return Math.round((100 * read) / denom)
 }
 
+// ---------------------------------------------------------------------------
+// MiMo-V2.6 cache metrics + sticky-session identity
+//
+// MiMo caching is provider-managed (implicit context caching). Xiaomi documents
+// usage.prompt_tokens_details.cached_tokens as the number of PROMPT tokens
+// served from cache and prompt_tokens as the total prompt-token count, so the
+// authoritative cache metric is cachedTokens / promptTokens -- NOT the
+// read/(read+write) form used by other families. `hitRatePct` is intentionally
+// left untouched so existing providers are unaffected.
+//
+// The runtime exposes `Message.info.tokens` as { input, output, cache:{read,
+// write} } where `input` is the NON-cached prompt input and `cache.read` is the
+// cached prompt input. Total prompt tokens are therefore derived as
+// read + input (cache.write is a separate accounting bucket and is NOT folded
+// in). We never fabricate cache-write values.
+// ---------------------------------------------------------------------------
+
+// cachedTokens / promptTokens, rounded to a percentage. Returns null when the
+// denominator is unknown/zero or the inputs are not finite numbers, so no
+// fabricated hit rate is ever emitted.
+export function mimoHitRate(cachedTokens, promptTokens) {
+  if (!Number.isFinite(cachedTokens) || !Number.isFinite(promptTokens)) return null
+  if (promptTokens <= 0 || cachedTokens < 0) return null
+  return Math.round((100 * cachedTokens) / promptTokens)
+}
+
+// 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.
+export function mimoSessionIdFor(sessionID) {
+  if (typeof sessionID !== "string" || sessionID.length === 0) return null
+  return `mimo-ses-${shorthash(sessionID)}`
+}
+
+// Detect a provider switch within the same session. `previous` and `current`
+// are {providerID, modelID} observations. Returns {changed:false} until two
+// real observations exist; a change is only reported when both are known and
+// the providerID differs. Never forces or overrides provider selection.
+export function providerChangeEvent(previous, current) {
+  const prev = previous && typeof previous.providerID === "string" ? previous.providerID : null
+  const cur = current && typeof current.providerID === "string" ? current.providerID : null
+  if (prev == null || cur == null || prev === cur) return { changed: false, from: null, to: null }
+  return { changed: true, from: previous, to: current }
+}
+
 // Decide whether a `usage` record should be emitted for an aggregation sample.
 // We must not fabricate a zero-valued cache event merely because the session
 // became idle: a sample only counts when at least one assistant message with

package/src/cache-engine.ts

@@ -5,6 +5,7 @@ import {
   DIGEST_TEMPLATE,
   POLICY_GLM53,
   POLICY_GPT56,
+  POLICY_MIMO26,
   POLICY_NEUTRAL,
   createRecorder,
   detectPolicy,
@@ -16,10 +17,13 @@ import {
   gptCacheOptionsDelta,
   hitRatePct,
   loadConfig,
+  mimoHitRate,
+  mimoSessionIdFor,
   nextProcessedCursor,
   observeReasoningEffort,
   policyEnabled,
   prefixChangeReasons,
+  providerChangeEvent,
   reasoningEffortFromOptions,
   reasoningIssueReasons,
   relocateVolatileEnvBlock,
@@ -37,7 +41,7 @@ import {
 // cache-engine
 //
 // Provider-aware prompt-cache observability + conservative cache-shape
-// preservation for ONE OpenCode TUI across three model families:
+// preservation for ONE OpenCode TUI across four model families:
 //
 //   DeepSeek V4.1 Flash  -> pure passive. >99.66% hit rate is preserved by never
 //                         mutating system/options/requests. Observability only.
@@ -52,16 +56,28 @@ import {
 //                         history stable, and INSTRUMENT preserved-thinking
 //                         integrity (duplicate/reorder/modified reasoning). No
 //                         invented cache key (Z.ai exposes none).
+//   MiMo-V2.6          -> prefix stability + OpenRouter session affinity. The
+//                         safe env-block relocation is applied (stabilizeSystem)
+//                         and provider switches within a session are diagnosed.
+//                         MiMo caching is provider-managed implicit context
+//                         caching; no cache key/breakpoint/TTL is invented. The
+//                         OpenRouter sticky-session id is derived but currently
+//                         NOT injected: this runtime's OpenRouter request
+//                         adapter forwards only usage/reasoning/prompt_cache_key
+//                         and exposes no top-level `session_id` path (verified
+//                         against the installed runtime; see README).
 //
 // The engine remains conservative: it observes, hashes, compares, records,
 // appends a compaction continuation template, and (for GPT-5.6 only) injects
 // documented cache options. It never rewrites message history, reorders tools,
 // or alters user content. DeepSeek and neutral models are byte-untouched.
+// MiMo/GLM only relocate the identifiable volatile env block, content-preserving.
 //
 // IMPORTANT (terminology): local hashes describe the *observed* prefix shape.
 // A changed hash means request bytes changed; it is NOT proof the provider's
 // cache key changed or that a cache miss occurred. Provider-reported cache
-// token counts are authoritative; hashes are diagnostics only.
+// token counts are authoritative; hashes are diagnostics only. For MiMo, the
+// authoritative cache signal is provider-reported cached_tokens.
 // ---------------------------------------------------------------------------
 
 const TOOL_FETCH_TTL_MS = 1500
@@ -113,6 +129,7 @@ type SessionState = {
   cacheRootAt: number | null
   reasoningSeen: Map<string, number>
   reasoningLastSeq: string[] | null
+  mimoProvider: { providerID: string; modelID: string } | null
 }
 
 const emptyShape = (): Shape => ({
@@ -154,6 +171,7 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
         cacheRootAt: null,
         reasoningSeen: new Map(),
         reasoningLastSeq: null,
+        mimoProvider: null,
       }
       sessions.set(sid, s)
     }
@@ -397,6 +415,25 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
           recFields.promptTokens = read + write + input
           recFields.glmHitRate = glmHitRatio(read, write, input)
         }
+        if (family === POLICY_MIMO26) {
+          // Provider-reported cached tokens / total prompt tokens. The runtime's
+          // `input` is the non-cached prompt input and `cache.read` is the
+          // cached prompt input, so total prompt tokens are derived as read +
+          // input (cache.write is a separate accounting bucket). No cache-write
+          // value is fabricated; the ratio is null when prompt tokens are 0.
+          const promptTokens = read + input
+          recFields.promptTokens = promptTokens
+          recFields.cachedTokens = read
+          recFields.cacheHitRate = mimoHitRate(read, promptTokens)
+          if (cfg.policies?.[POLICY_MIMO26]?.stickySession === true) {
+            recFields.stickySessionId = mimoSessionIdFor(sid)
+          }
+          // Prefer the latest live provider identity over the latched one.
+          if (s.mimoProvider) {
+            recFields.provider = s.mimoProvider.providerID
+            recFields.model = s.mimoProvider.modelID
+          }
+        }
         if (family === POLICY_GPT56 && s.gptInjected) {
           recFields.keyStrategy = "session"
           recFields.mode = cfg.policies?.[POLICY_GPT56]?.mode
@@ -445,6 +482,48 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
       try {
         const info = rememberModel(input.sessionID, input.model as unknown as ChatParamsModel)
         const family = info?.family
+
+        // ---- MiMo-V2.6: provider-switch diagnostics (telemetry only) ---------
+        // MiMo cache lives at the provider side, so a provider change within one
+        // OpenCode session can silently invalidate it. We record identity on every
+        // MiMo request and emit a diagnostic when the OpenCode providerID changes.
+        // This never forces or overrides provider routing.
+        // NOTE: OpenRouter's *upstream* provider selection (e.g. xiaomi/fp8) is
+        // not exposed to plugins; only the OpenCode providerID/modelID are
+        // observable here.
+        if (family === POLICY_MIMO26 && policyEnabled(cfg, POLICY_MIMO26) && info) {
+          // Use the LIVE model identity (not the latched one) so a provider
+          // switch within the session is actually observable.
+          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.mimoProvider, cur)
+            if (ev.changed) {
+              const sticky =
+                cfg.policies?.[POLICY_MIMO26]?.stickySession === true
+                  ? { stickySessionId: mimoSessionIdFor(input.sessionID) }
+                  : {}
+              rec.record({
+                kind: "boundary",
+                sid: input.sessionID,
+                ts: Date.now(),
+                reason: "mimo_provider_changed",
+                policy: POLICY_MIMO26,
+                from: ev.from,
+                to: ev.to,
+                ...sticky,
+                note: "OpenCode providerID changed; upstream routing is not plugin-visible",
+              })
+            }
+            s.mimoProvider = 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.
@@ -626,28 +705,47 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
         const s = get(sid)
         const family = s.modelInfo?.family
 
-        // ---- GLM-5.3 input-shape stabilization -----------------------------
+        // ---- GLM-5.3 / MiMo-V2.6 input-shape stabilization ------------------
         // Relocate the identifiable volatile env block (per-day date) to the
         // tail of the single system string, content-preserving, ONLY when the
-        // model is GLM-5.3 and the block markers are present exactly. Never
-        // touches other content/order; never applied to other families.
+        // family opts into system stabilization and the block markers are
+        // present exactly. Never touches other content/order; never applied to
+        // other families. The runtime passes a single-element system array
+        // (verified against the installed runtime), so no generic reordering is
+        // involved.
         //
         // In-place mutation note: request.ts keeps using its own local `system`
         // array after the hook (the trigger's returned output is ignored), so
         // reassigning `output.system = [...]` would be lost. We rewrite the
         // single element in place instead.
         let systemText = output.system.join("\n")
-        if (
+        const glmStabilize =
           family === POLICY_GLM53 &&
           policyEnabled(cfg, POLICY_GLM53) &&
-          cfg.policies?.[POLICY_GLM53]?.stabilizeSystem === true &&
-          output.system.length === 1
-        ) {
+          cfg.policies?.[POLICY_GLM53]?.stabilizeSystem === true
+        const mimoStabilize =
+          family === POLICY_MIMO26 &&
+          policyEnabled(cfg, POLICY_MIMO26) &&
+          cfg.policies?.[POLICY_MIMO26]?.stabilizeSystem === true
+        if ((glmStabilize || mimoStabilize) && output.system.length === 1) {
           const rel = relocateVolatileEnvBlock(output.system[0])
           if (rel.changed) {
             output.system[0] = rel.text
             systemText = rel.text
-            log("debug", "glm system env block relocated to suffix", { sid })
+            if (family === POLICY_MIMO26) {
+              log("debug", "mimo system env block relocated to suffix", { sid })
+              rec.record({
+                kind: "boundary",
+                sid,
+                ts: Date.now(),
+                reason: "mimo_system_env_relocated",
+                policy: POLICY_MIMO26,
+                provider: s.modelInfo?.providerID,
+                model: s.modelInfo?.modelID,
+              })
+            } else {
+              log("debug", "glm system env block relocated to suffix", { sid })
+            }
           }
         }
 
@@ -724,6 +822,22 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
               ? { toolCount, prevToolCount: prevCount, semanticToolsChanged: semanticChanged, wireToolsChanged: wireChanged }
               : {}),
           })
+          // MiMo-specific explicit diagnostic: the STABLE prefix changed (not
+          // just the relocated volatile env suffix). Reported only; the new
+          // content is never overwritten with a stale snapshot.
+          if (family === POLICY_MIMO26 && reasons.includes("system_stable_prefix_changed")) {
+            rec.record({
+              kind: "boundary",
+              sid,
+              ts: Date.now(),
+              reason: "mimo_system_prefix_changed",
+              policy: POLICY_MIMO26,
+              provider: s.modelInfo?.providerID,
+              model: s.modelInfo?.modelID,
+              changedFields: granular,
+              reasons,
+            })
+          }
           if (cfg.logPrefixChanges) {
             log("warn", "observed prefix shape change", {
               sid,

package/src/tui.mjs

@@ -0,0 +1,11 @@
+const plugin = {
+  id: "opencode-cache-engine",
+
+  async tui() {
+    // CacheEngine has no TUI UI of its own.
+    // This target exists so the npm package can be registered,
+    // displayed, and enabled/disabled by the OpenCode plugin manager.
+  },
+}
+
+export default plugin

package/test/cache-engine.test.mjs

@@ -16,6 +16,7 @@ import {
   POLICY_DEEPSEEK,
   POLICY_GLM53,
   POLICY_GPT56,
+  POLICY_MIMO26,
   POLICY_NEUTRAL,
   canonicalStringify,
   commonPrefixLength,
@@ -28,8 +29,11 @@ import {
   gptCacheOptionsDelta,
   hitRatePct,
   loadConfig,
+  mimoHitRate,
+  mimoSessionIdFor,
   nextProcessedCursor,
   parseConfig,
+  providerChangeEvent,
   relocateVolatileEnvBlock,
   scanPage,
   shapeDiff,
@@ -221,6 +225,30 @@ test("recorder writes valid JSONL to a real file", () => {
   assert.deepEqual(JSON.parse(lines[0]), { kind: "prefix-change", sid: "s", dimensions: ["system"] })
 })
 
+// --- 14. TUI target test -----------------------------------------------------
+
+test("TUI target exports the expected plugin module", async () => {
+  const mod = await import("../src/tui.mjs")
+  assert.equal(mod.default.id, "opencode-cache-engine")
+  assert.equal(typeof mod.default.tui, "function")
+  assert.equal("server" in mod.default, false)
+})
+
+// --- 15. Package manifest test with TUI --------------------------------------
+
+test("package exposes separate server and TUI targets", async () => {
+  const { readFileSync } = await import("node:fs")
+  const { join } = await import("node:path")
+
+  const pkg = JSON.parse(
+    readFileSync(join(process.cwd(), "package.json"), "utf8")
+  )
+
+  assert.equal(pkg.exports["./server"], "./src/cache-engine.ts")
+  assert.equal(pkg.exports["./tui"], "./src/tui.mjs")
+})
+
+
 // ===========================================================================
 // Provider-aware model detection
 // ===========================================================================
@@ -269,6 +297,32 @@ test("unrelated GLM models do NOT match GLM-5.3 policy", () => {
   assert.equal(detectPolicy(M("zai", "glm-4.5")), POLICY_NEUTRAL)
 })
 
+test("MiMo V2.6 Flash/Pro match MiMo policy (openrouter + direct)", () => {
+  assert.equal(detectPolicy(M("openrouter", "xiaomi/mimo-v2.6-flash")), POLICY_MIMO26)
+  assert.equal(detectPolicy(M("openrouter", "xiaomi/mimo-v2.6-pro")), POLICY_MIMO26)
+  assert.equal(detectPolicy(M("xiaomi", "mimo-v2.6-flash")), POLICY_MIMO26)
+  assert.equal(detectPolicy(M("xiaomi", "mimo-v2.6-pro")), POLICY_MIMO26)
+  // full Model shape via api.id
+  assert.equal(
+    detectPolicy({ providerID: "openrouter", api: { id: "xiaomi/mimo-v2.6-flash", npm: "@openrouter/ai-sdk-provider" } }),
+    POLICY_MIMO26,
+  )
+})
+
+test("MiMo V2.5 and Pro-UltraSpeed do NOT match MiMo policy", () => {
+  assert.equal(detectPolicy(M("openrouter", "xiaomi/mimo-v2.5")), POLICY_NEUTRAL)
+  assert.equal(detectPolicy(M("openrouter", "xiaomi/mimo-v2.5-pro")), POLICY_NEUTRAL)
+  assert.equal(detectPolicy(M("xiaomi", "mimo-v2.5")), POLICY_NEUTRAL)
+  assert.equal(detectPolicy(M("xiaomi", "mimo-v2.6-pro-ultraspeed")), POLICY_NEUTRAL)
+  assert.equal(detectPolicy(M("xiaomi", "mimo-v2.6-flashx")), POLICY_NEUTRAL)
+})
+
+test("unrelated MiMo/other models do NOT match MiMo policy", () => {
+  assert.equal(detectPolicy(M("openrouter", "xiaomi/mimo-v2")), POLICY_NEUTRAL)
+  assert.equal(detectPolicy(M("openrouter", "xiaomi/mimo-v2-flash")), POLICY_NEUTRAL)
+  assert.equal(detectPolicy(M("anthropic", "claude-sonnet-4-5")), POLICY_NEUTRAL)
+})
+
 test("unrelated models match neutral policy", () => {
   assert.equal(detectPolicy(M("anthropic", "claude-sonnet-4-5")), POLICY_NEUTRAL)
   assert.equal(detectPolicy(M("openrouter", "x-ai/grok-4")), POLICY_NEUTRAL)
@@ -535,10 +589,16 @@ test("empty current sequence -> no anomalies", () => {
 // Config: provider policies
 // ===========================================================================
 
-test("config defaults enable all three policies", () => {
+test("config defaults enable all four policies", () => {
   const cfg = parseConfig({}, {})
   assert.deepEqual(cfg.policies.deepseek, { enabled: true })
   assert.deepEqual(cfg.policies.glm53, { enabled: true, stabilizeSystem: true, preserveThinkingIntegrity: true })
+  assert.deepEqual(cfg.policies.mimo26, {
+    enabled: true,
+    stabilizeSystem: true,
+    stickySession: true,
+    preserveThinkingIntegrity: true,
+  })
   assert.deepEqual(cfg.policies.gpt56, {
     enabled: true,
     promptCacheKey: true,
@@ -565,6 +625,7 @@ test("config policy overrides are honored", () => {
         },
         glm53: { stabilizeSystem: false },
         deepseek: { enabled: true },
+        mimo26: { enabled: false, stabilizeSystem: false, stickySession: false },
       },
     },
     {},
@@ -578,6 +639,10 @@ test("config policy overrides are honored", () => {
   assert.equal(cfg.policies.gpt56.ttl, "1h")
   assert.equal(cfg.policies.glm53.stabilizeSystem, false)
   assert.equal(cfg.policies.glm53.preserveThinkingIntegrity, true)
+  assert.equal(cfg.policies.mimo26.enabled, false)
+  assert.equal(cfg.policies.mimo26.stabilizeSystem, false)
+  assert.equal(cfg.policies.mimo26.stickySession, false)
+  assert.equal(cfg.policies.mimo26.preserveThinkingIntegrity, true)
 })
 
 test("config invalid policy values fall back to defaults", () => {
@@ -763,3 +828,143 @@ test("boundary: reasoning-integrity reason tokens", () => {
   ])
   assert.deepEqual(reasoningIssueReasons(null), [])
 })
+
+// ===========================================================================
+// MiMo-V2.6: system env relocation (shared content-preserving helper)
+// ===========================================================================
+
+const MIMO_SYSTEM = [
+  "You are a senior software engineer.",
+  "You are powered by the model named mimo-v2.6-flash. The exact model ID is xiaomi/mimo-v2.6-flash",
+  "Here is some useful information about the environment you are running in:",
+  "<env>",
+  "Working directory: /home/dev/project",
+  "Today's date: 2026-08-17",
+  "</env>",
+  "You MUST follow AGENTS.md instructions and keep your responses concise.",
+].join("\n")
+
+test("MiMo env block is relocated to the tail, contents preserved exactly", () => {
+  const { text, changed } = relocateVolatileEnvBlock(MIMO_SYSTEM)
+  assert.equal(changed, true)
+  assert.ok(text.endsWith("</env>"))
+  const norm = (t) => t.split("\n").filter((l) => l).sort().join("\n")
+  assert.equal(norm(text), norm(MIMO_SYSTEM))
+  assert.ok(text.indexOf("You MUST follow") < text.indexOf("You are powered"))
+})
+
+test("MiMo relocation is a no-op when the block is already at the tail", () => {
+  const already = relocateVolatileEnvBlock(MIMO_SYSTEM).text
+  const again = relocateVolatileEnvBlock(already)
+  assert.equal(again.changed, false)
+  assert.equal(again.text, already)
+})
+
+test("MiMo relocation is a no-op when start/end markers are missing", () => {
+  const missingStart = "Just a system prompt.\n<env>\nToday's date: x\n</env>"
+  assert.equal(relocateVolatileEnvBlock(missingStart).changed, false)
+  const missingEnd = "You are powered by the model named mimo-v2.6-flash\nbut never closed"
+  assert.equal(relocateVolatileEnvBlock(missingEnd).changed, false)
+})
+
+// ===========================================================================
+// MiMo-V2.6: sticky-session identity (pure, derived but not injected)
+// ===========================================================================
+
+test("mimoSessionIdFor: deterministic + stable for the same session", () => {
+  assert.equal(mimoSessionIdFor("ses_abc123"), mimoSessionIdFor("ses_abc123"))
+})
+
+test("mimoSessionIdFor: distinct sessions produce distinct ids", () => {
+  assert.notEqual(mimoSessionIdFor("ses_abc"), mimoSessionIdFor("ses_xyz"))
+})
+
+test("mimoSessionIdFor: printable, no whitespace, within 256 chars", () => {
+  const id = mimoSessionIdFor("ses_" + "a".repeat(500))
+  assert.ok(id.length <= 256)
+  assert.ok(!/\s/.test(id))
+  assert.ok(/^[\x20-\x7E]+$/.test(id))
+})
+
+test("mimoSessionIdFor: invalid input -> null (no fabrication)", () => {
+  assert.equal(mimoSessionIdFor(undefined), null)
+  assert.equal(mimoSessionIdFor(null), null)
+  assert.equal(mimoSessionIdFor(""), null)
+  assert.equal(mimoSessionIdFor(123), null)
+})
+
+test("mimoSessionIdFor: transient request fields cannot alter the id", () => {
+  // the helper is a pure function of the session id; extra args are ignored
+  assert.equal(mimoSessionIdFor("ses_stable"), mimoSessionIdFor("ses_stable", { turn: 7, temperature: 0.9 }))
+})
+
+// ===========================================================================
+// MiMo-V2.6: cached/prompt token metrics
+// ===========================================================================
+
+test("mimoHitRate = cachedTokens / promptTokens", () => {
+  assert.equal(mimoHitRate(47000, 50000), 94)
+  assert.equal(mimoHitRate(0, 100), 0)
+  assert.equal(mimoHitRate(100, 100), 100)
+})
+
+test("mimoHitRate returns null for zero/unknown denominators (no fabrication)", () => {
+  assert.equal(mimoHitRate(0, 0), null)
+  assert.equal(mimoHitRate(10, 0), null)
+  assert.equal(mimoHitRate(NaN, 100), null)
+  assert.equal(mimoHitRate(10, NaN), null)
+  assert.equal(mimoHitRate(undefined, 100), null)
+  assert.equal(mimoHitRate(10, undefined), null)
+})
+
+test("mimoHitRate is NOT the read/(read+write) form", () => {
+  // read=80, input=20 -> promptTokens derived 100 -> 80%. The read/(read+write)
+  // form would give 100% for (80, 0); they must not be conflated.
+  assert.equal(mimoHitRate(80, 80 + 20), 80)
+  assert.equal(hitRatePct(80, 0), 100)
+})
+
+// ===========================================================================
+// MiMo-V2.6: provider-switch diagnostics
+// ===========================================================================
+
+test("providerChangeEvent: no event until two real observations exist", () => {
+  assert.deepEqual(providerChangeEvent(null, { providerID: "openrouter", modelID: "xiaomi/mimo-v2.6-flash" }), {
+    changed: false,
+    from: null,
+    to: null,
+  })
+  assert.equal(providerChangeEvent({ providerID: "openrouter" }, null).changed, false)
+})
+
+test("providerChangeEvent: same provider -> no change", () => {
+  const a = { providerID: "openrouter", modelID: "xiaomi/mimo-v2.6-flash" }
+  const b = { providerID: "openrouter", modelID: "xiaomi/mimo-v2.6-pro" }
+  assert.equal(providerChangeEvent(a, b).changed, false)
+})
+
+test("providerChangeEvent: different provider -> change with from/to", () => {
+  const a = { providerID: "openrouter", modelID: "xiaomi/mimo-v2.6-flash" }
+  const b = { providerID: "xiaomi", modelID: "mimo-v2.6-flash" }
+  const ev = providerChangeEvent(a, b)
+  assert.equal(ev.changed, true)
+  assert.deepEqual(ev.from, a)
+  assert.deepEqual(ev.to, b)
+})
+
+// ===========================================================================
+// MiMo-V2.6: no tool-definition mutation
+// ===========================================================================
+
+test("MiMo policy performs no tool mutation (fingerprints are pure inputs)", () => {
+  // The plugin never adds a MiMo tool-ordering pass: this runtime already sorts
+  // tools alphabetically before the wire. Classifying a model as MiMo must not
+  // affect tool fingerprints, which are a pure function of the tool definitions.
+  const model = { providerID: "openrouter", modelID: "xiaomi/mimo-v2.6-flash" }
+  assert.equal(detectPolicy(model), POLICY_MIMO26)
+  const before = { sem: toolFingerprint(TOOLS), wire: toolWireFingerprint(TOOLS) }
+  const after = { sem: toolFingerprint(TOOLS), wire: toolWireFingerprint(TOOLS) }
+  assert.deepEqual(after, before)
+  // semantic fingerprint stays order-insensitive regardless of the policy
+  assert.equal(toolFingerprint([...TOOLS].reverse()), before.sem)
+})