opencode-cache-engine 0.3.0 → 0.3.2

package/package.json

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

package/src/cache-engine-core.mjs

@@ -481,6 +481,25 @@ export function mimoHitRate(cachedTokens, promptTokens) {
   return Math.round((100 * cachedTokens) / promptTokens)
 }
 
+// Derive a provider-neutral stable ID from the logical OpenCode session ID.
+// The full SHA-256 digest avoids intentional truncation/collapse of distinct
+// sessions. This helper only generates an identifier; it does not select a
+// provider or inject the identifier into any request transport.
+export function stableSessionIdFor(sessionID) {
+  if (typeof sessionID !== "string" || sessionID.length === 0) return null
+  return `oc-ses-${createHash("sha256").update(sessionID).digest("hex")}`
+}
+
+// OpenRouter session affinity is currently eligible only for the two policy
+// families with documented affinity use: MiMo-V2.6 and GLM-5.3. This pure
+// policy decision is separate from ID generation and transport/header injection.
+export function isOpenRouterAffinityEligible(policyFamily, providerID) {
+  return (
+    providerID === "openrouter" &&
+    (policyFamily === POLICY_MIMO26 || policyFamily === POLICY_GLM53)
+  )
+}
+
 // 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

package/src/cache-engine.ts

@@ -56,16 +56,13 @@ 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).
+//   MiMo-V2.6          -> prefix stability + provider diagnostics. The safe
+//                         env-block relocation is applied (stabilizeSystem).
+//                         For actual OpenRouter requests only, chat.headers
+//                         adds the deterministic x-session-id unless an
+//                         explicit case-insensitive value already exists in
+//                         model/plugin headers. No MiMo cache key/breakpoint/
+//                         TTL is invented.
 //
 // The engine remains conservative: it observes, hashes, compares, records,
 // appends a compaction continuation template, and (for GPT-5.6 only) injects
@@ -141,7 +138,13 @@ const emptyShape = (): Shape => ({
   toolCount: null,
 })
 
-type ChatParamsModel = { providerID: string; id?: string; api?: { id?: string; npm?: string }; name?: string }
+type ChatParamsModel = {
+  providerID: string
+  id?: string
+  api?: { id?: string; npm?: string }
+  headers?: Record<string, string>
+  name?: string
+}
 
 export const CacheEngine: Plugin = async ({ client, directory }) => {
   const cfg = loadConfig({ configPath: DEFAULT_CONFIG_PATH, env: process.env })
@@ -478,6 +481,30 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
     // GPT cache. Compaction requests (agent === "compaction") for the same root
     // use a deterministic separate namespace (<root>:compact) so a compaction
     // cache write never interferes with the useful live-session cache.
+    //
+    // MiMo-V2.6 + OpenRouter session affinity. Gate on the actual OpenCode
+    // provider identity as well as the detected family; a matching model slug
+    // on a direct endpoint is not sufficient. The runtime merges model.headers
+    // before this hook's output, so preserve a case-insensitive user/model or
+    // earlier-plugin x-session-id rather than silently overwriting it. Otherwise
+    // add the deterministic ID derived from the logical OpenCode session.
+    "chat.headers": async (input, output) => {
+      try {
+        const model = input.model as unknown as ChatParamsModel
+        const providerID = String(model?.providerID ?? "")
+        if (providerID !== "openrouter" || detectPolicy(model) !== POLICY_MIMO26) 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
+
+        const sessionID = mimoSessionIdFor(input.sessionID)
+        if (sessionID) output.headers["x-session-id"] = sessionID
+      } catch (e) {
+        rec.record({ kind: "telemetry-error", ts: Date.now(), error: String(e) })
+      }
+    },
+
     "chat.params": async (input, output) => {
       try {
         const info = rememberModel(input.sessionID, input.model as unknown as ChatParamsModel)

package/test/cache-engine.test.mjs

@@ -9,6 +9,7 @@
 
 import { test } from "node:test"
 import assert from "node:assert/strict"
+import { execFileSync } from "node:child_process"
 import { mkdtempSync, readFileSync, writeFileSync } from "node:fs"
 import { homedir, tmpdir } from "node:os"
 import { join } from "node:path"
@@ -28,6 +29,7 @@ import {
   glmHitRatio,
   gptCacheOptionsDelta,
   hitRatePct,
+  isOpenRouterAffinityEligible,
   loadConfig,
   mimoHitRate,
   mimoSessionIdFor,
@@ -40,6 +42,7 @@ import {
   shapeFieldDiffs,
   shorthash,
   shouldAggregate,
+  stableSessionIdFor,
   systemShapeHashes,
   toolFingerprint,
   toolWireFingerprint,
@@ -871,10 +874,22 @@ test("MiMo relocation is a no-op when start/end markers are missing", () => {
 // MiMo-V2.6: sticky-session identity (pure, derived but not injected)
 // ===========================================================================
 
+test("stableSessionIdFor: deterministic for the same logical session", () => {
+  assert.equal(stableSessionIdFor("ses_abc123"), stableSessionIdFor("ses_abc123"))
+})
+
+test("stableSessionIdFor: different logical sessions produce different ids", () => {
+  assert.notEqual(stableSessionIdFor("ses_abc"), stableSessionIdFor("ses_xyz"))
+})
+
 test("mimoSessionIdFor: deterministic + stable for the same session", () => {
   assert.equal(mimoSessionIdFor("ses_abc123"), mimoSessionIdFor("ses_abc123"))
 })
 
+test("mimoSessionIdFor preserves its existing id format", () => {
+  assert.equal(mimoSessionIdFor("ses_abc123"), `mimo-ses-${shorthash("ses_abc123")}`)
+})
+
 test("mimoSessionIdFor: distinct sessions produce distinct ids", () => {
   assert.notEqual(mimoSessionIdFor("ses_abc"), mimoSessionIdFor("ses_xyz"))
 })
@@ -898,6 +913,31 @@ test("mimoSessionIdFor: transient request fields cannot alter the id", () => {
   assert.equal(mimoSessionIdFor("ses_stable"), mimoSessionIdFor("ses_stable", { turn: 7, temperature: 0.9 }))
 })
 
+// ===========================================================================
+// OpenRouter session-affinity eligibility (pure policy decision only)
+// ===========================================================================
+
+test("OpenRouter affinity is eligible for MiMo and GLM only", () => {
+  assert.equal(isOpenRouterAffinityEligible(POLICY_MIMO26, "openrouter"), true)
+  assert.equal(isOpenRouterAffinityEligible(POLICY_GLM53, "openrouter"), true)
+})
+
+test("OpenRouter affinity is ineligible for non-OpenRouter providers", () => {
+  assert.equal(isOpenRouterAffinityEligible(POLICY_MIMO26, "xiaomi"), false)
+  assert.equal(isOpenRouterAffinityEligible(POLICY_GLM53, "zai"), false)
+  assert.equal(isOpenRouterAffinityEligible(POLICY_MIMO26, "unknown-provider"), false)
+})
+
+test("OpenRouter affinity is ineligible for DeepSeek and GPT", () => {
+  assert.equal(isOpenRouterAffinityEligible(POLICY_DEEPSEEK, "openrouter"), false)
+  assert.equal(isOpenRouterAffinityEligible(POLICY_GPT56, "openrouter"), false)
+})
+
+test("OpenRouter affinity is ineligible for unknown families and providers", () => {
+  assert.equal(isOpenRouterAffinityEligible("unknown-family", "openrouter"), false)
+  assert.equal(isOpenRouterAffinityEligible(POLICY_MIMO26, undefined), false)
+})
+
 // ===========================================================================
 // MiMo-V2.6: cached/prompt token metrics
 // ===========================================================================
@@ -968,3 +1008,116 @@ test("MiMo policy performs no tool mutation (fingerprints are pure inputs)", ()
   // semantic fingerprint stays order-insensitive regardless of the policy
   assert.equal(toolFingerprint([...TOOLS].reverse()), before.sem)
 })
+
+// ===========================================================================
+// MiMo/OpenRouter session affinity (real chat.headers hook, no model calls)
+// ===========================================================================
+
+async function runMiMoHeaderHookProbe() {
+  const home = mkdtempSync(join(tmpdir(), "ce-mimo-headers-"))
+  const pluginURL = new URL("../src/cache-engine.ts", import.meta.url).href
+  const coreURL = new URL("../src/cache-engine-core.mjs", import.meta.url).href
+  const script = `
+    import assert from "node:assert/strict"
+    const { CacheEngine } = await import(${JSON.stringify(pluginURL)})
+    const { mimoSessionIdFor } = await import(${JSON.stringify(coreURL)})
+    const client = {
+      app: { log: async () => ({}) },
+      session: { get: async () => ({ data: { parentID: null } }) },
+      tool: { list: async () => ({ data: [] }) },
+    }
+    const hooks = await CacheEngine({ client, directory: process.env.HOME })
+    assert.equal(typeof hooks["chat.headers"], "function")
+    const invoke = async (model, sessionID, existingHeaders = {}) => {
+      const output = { headers: { ...existingHeaders } }
+      const headersRef = output.headers
+      await hooks["chat.headers"]({
+        sessionID,
+        agent: "build",
+        model,
+        provider: { id: model.providerID },
+        message: { id: "msg", sessionID, role: "user", content: "probe" },
+      }, output)
+      return { headers: output.headers, sameObject: output.headers === headersRef, modelHeaders: model.headers }
+    }
+    const mimoOpenRouter = {
+      providerID: "openrouter",
+      id: "xiaomi/mimo-v2.6-flash",
+      api: { id: "xiaomi/mimo-v2.6-flash" },
+      headers: {},
+    }
+    const stable1 = await invoke(mimoOpenRouter, "ses_same", { "User-Agent": "preserve-me", "x-custom": "also-preserve" })
+    const stable2 = await invoke(mimoOpenRouter, "ses_same")
+    const different = await invoke(mimoOpenRouter, "ses_other")
+    const direct = await invoke({ ...mimoOpenRouter, providerID: "xiaomi" }, "ses_direct", { "User-Agent": "preserve-me" })
+    const unknown = await invoke({ ...mimoOpenRouter, providerID: "unknown-provider" }, "ses_unknown")
+    const missingProvider = await invoke({ ...mimoOpenRouter, providerID: undefined }, "ses_missing_provider")
+    const glm = await invoke({ providerID: "openrouter", id: "z-ai/glm-5.3", api: { id: "z-ai/glm-5.3" }, headers: {} }, "ses_glm")
+    const configured = await invoke({
+      ...mimoOpenRouter,
+      headers: { "X-Session-Id": "user-configured-value" },
+    }, "ses_configured")
+    const earlierPlugin = await invoke(mimoOpenRouter, "ses_plugin", { "X-SESSION-ID": "earlier-plugin-value" })
+    const result = {
+      stable1,
+      stable2,
+      different,
+      direct,
+      unknown,
+      missingProvider,
+      glm,
+      configured,
+      configuredModelHeaders: configured.modelHeaders,
+      earlierPlugin,
+      expectedSame: mimoSessionIdFor("ses_same"),
+      expectedOther: mimoSessionIdFor("ses_other"),
+    }
+    assert.equal(configured.headers["x-session-id"], undefined)
+    assert.equal(earlierPlugin.headers["X-SESSION-ID"], "earlier-plugin-value")
+    process.stdout.write(JSON.stringify(result))
+  `
+  const stdout = execFileSync(process.execPath, ["--experimental-strip-types", "--input-type=module", "-e", script], {
+    cwd: process.cwd(),
+    env: { ...process.env, HOME: home },
+    encoding: "utf8",
+  })
+  return JSON.parse(stdout.trim())
+}
+
+let miMoHeaderProbe
+const miMoHeaderResults = async () => (miMoHeaderProbe ??= runMiMoHeaderHookProbe())
+
+test("MiMo/OpenRouter attaches the existing deterministic MiMo session ID", async () => {
+  const result = await miMoHeaderResults()
+  assert.equal(result.stable1.headers["x-session-id"], result.expectedSame)
+  assert.equal(result.stable1.sameObject, true)
+  assert.deepEqual(result.stable1.headers["User-Agent"], "preserve-me")
+  assert.deepEqual(result.stable1.headers["x-custom"], "also-preserve")
+})
+
+test("MiMo/OpenRouter session ID is stable across turns and distinct across sessions", async () => {
+  const result = await miMoHeaderResults()
+  assert.equal(result.stable2.headers["x-session-id"], result.stable1.headers["x-session-id"])
+  assert.equal(result.different.headers["x-session-id"], result.expectedOther)
+  assert.notEqual(result.different.headers["x-session-id"], result.stable1.headers["x-session-id"])
+})
+
+test("MiMo direct and unknown providers do not receive x-session-id", async () => {
+  const result = await miMoHeaderResults()
+  assert.equal(result.direct.headers["x-session-id"], undefined)
+  assert.equal(result.unknown.headers["x-session-id"], undefined)
+  assert.equal(result.missingProvider.headers["x-session-id"], undefined)
+  assert.deepEqual(result.direct.headers, { "User-Agent": "preserve-me" })
+})
+
+test("MiMo affinity preserves existing x-session-id values case-insensitively", async () => {
+  const result = await miMoHeaderResults()
+  assert.equal(result.configured.headers["x-session-id"], undefined)
+  assert.deepEqual(result.configuredModelHeaders, { "X-Session-Id": "user-configured-value" })
+  assert.deepEqual(result.earlierPlugin.headers, { "X-SESSION-ID": "earlier-plugin-value" })
+})
+
+test("MiMo-only affinity does not add x-session-id to GLM/OpenRouter", async () => {
+  const result = await miMoHeaderResults()
+  assert.equal(result.glm.headers["x-session-id"], undefined)
+})