opencode-cache-engine 0.2.0 → 0.3.0

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/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)
+})