opencode-cache-engine 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-cache-engine",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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,14 +1070,29 @@ 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",
         model,
-        provider: { id: model.providerID },
+        provider: { source: "config", info: { id: model.providerID }, options: {} },
         message: { id: "msg", sessionID, role: "user", content: "probe" },
       }, output)
-      return { headers: output.headers, sameObject: output.headers === headersRef, modelHeaders: model.headers }
+      return {
+        headers: output.headers,
+        sameObject: output.headers === headersRef,
+        outputKeys: Object.keys(output),
+        modelHeaders: model.headers,
+      }
     }
     const mimoOpenRouter = {
       providerID: "openrouter",
@@ -1057,6 +1111,33 @@ 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" }],
+      ["deepseek-direct", { providerID: "deepseek", id: "deepseek-v4.1-flash", api: { id: "deepseek-v4.1-flash" }, headers: {} }],
+      ["gpt-openai", { providerID: "openai", id: "gpt-5.6", api: { id: "gpt-5.6", npm: "@ai-sdk/openai" }, headers: {} }],
+      ["unknown-provider", { ...mimoOpenRouter, providerID: "unknown-provider" }],
+      ["missing-provider", { ...mimoOpenRouter, providerID: undefined }],
+      ["opencode-go-mimo", { ...mimoOpenRouter, providerID: "opencode" }],
+      ["opencode-go-glm", { ...glmOpenRouter, providerID: "opencode" }],
+    ]
+    const compatibility = []
+    for (const [name, model] of nonOpenRouterMatrix) {
+      const existing = { "User-Agent": "preserve-" + name, "x-compat-test": name }
+      compatibility.push({ name, ...(await invoke(model, "ses_" + name, existing)), expected: existing })
+    }
+    const gptOutput = { options: {} }
+    await hooks["chat.params"]({
+      sessionID: "ses_gpt_native_cache",
+      agent: "build",
+      model: { providerID: "openai", id: "gpt-5.6", api: { id: "gpt-5.6", npm: "@ai-sdk/openai" } },
+      provider: { source: "config", info: { id: "openai" }, options: {} },
+      message: { id: "msg-gpt", sessionID: "ses_gpt_native_cache", role: "user", content: "probe" },
+    }, gptOutput)
     const configured = await invoke({
       ...mimoOpenRouter,
       headers: { "X-Session-Id": "user-configured-value" },
@@ -1073,6 +1154,12 @@ async function runMiMoHeaderHookProbe() {
       glm2,
       glmDifferent,
       glmDirect,
+      mimoSwitchOpen,
+      mimoSwitchDirect,
+      glmSwitchOpen,
+      glmSwitchDirect,
+      compatibility,
+      gptOptions: gptOutput.options,
       configured,
       configuredModelHeaders: configured.modelHeaders,
       earlierPlugin,
@@ -1080,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")
@@ -1139,3 +1228,91 @@ test("GLM direct Z.AI does not receive x-session-id", async () => {
   assert.equal(result.glmDirect.headers["x-session-id"], undefined)
   assert.deepEqual(result.glmDirect.headers, { "User-Agent": "preserve-glm" })
 })
+
+test("non-OpenRouter endpoint matrix is x-session-id non-mutating and preserves unrelated headers", async () => {
+  const result = await miMoHeaderResults()
+  assert.equal(result.compatibility.length, 8)
+  for (const item of result.compatibility) {
+    assert.equal(item.headers["x-session-id"], undefined, `${item.name} must not receive OpenRouter affinity`)
+    assert.deepEqual(item.headers, item.expected, `${item.name} unrelated headers must remain unchanged`)
+    assert.equal(item.sameObject, true, `${item.name} headers object must be preserved`)
+    assert.deepEqual(item.outputKeys, ["headers"], `${item.name} hook output remains headers-only`)
+  }
+})
+
+test("OpenAI GPT retains its existing chat.params cache options without affinity headers", async () => {
+  const result = await miMoHeaderResults()
+  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)
+})