lynkr 9.10.0 → 9.12.0

package/src/routing/index.js

@@ -156,6 +156,7 @@ function getBestLocalProvider() {
  * @returns {Object} Routing decision with provider and metadata
  */
 const sessionAffinity = require('./session-affinity');
+const { evaluateSwitch: evaluateCacheSwitch } = require('./cache-switch-cost');
 
 // ---------------------------------------------------------------------------
 // WS1 — sticky sessions
@@ -258,30 +259,122 @@ function _economicDowngradeAllowed(promptTokensEst, pinModel, freshModel) {
   }
 }
 
-function _pinToDecision(pin, { reason, risk }) {
+/**
+ * Canonical routing-decision constructor. Every code path that returns a
+ * routing decision MUST build it here — the previous ten hand-assembled
+ * object literals had drifted (e.g. the non-tier agentic branch omitted
+ * `model`; only session_pin carried the full telemetry field set), and the
+ * reward pipeline requires `propensity` present on every decision it logs.
+ * Defaults first, caller's fields override; unknown extras (e.g.
+ * `_queryEmbedding`) pass through untouched.
+ */
+function buildDecision(fields = {}) {
+  if (!fields.provider || !fields.method) {
+    // Fail-open (routing must never throw on shape problems) but loud.
+    logger.error({ keys: Object.keys(fields) }, '[Routing] buildDecision called without provider/method');
+  }
+  // WS2.3 repair: the telemetry record sites read `analysis.requestType`,
+  // but nothing ever set that field — every routing_telemetry row recorded
+  // request_type NULL (verified live: 4052/4052 rows), so the evidence-based
+  // deescalator (keyed on tier + request_type) could never accumulate
+  // demotion evidence. Derive it here at the canonical constructor, using
+  // the SAME derivation the deescalator applies, so telemetry rows and
+  // demotion queries group by identical values.
+  let analysis = fields.analysis ?? null;
+  if (analysis && typeof analysis === 'object' && analysis.requestType == null) {
+    const requestType = analysis.breakdown?.taskType?.reason ?? analysis.taskType ?? null;
+    if (requestType != null) analysis = { ...analysis, requestType };
+  }
   return {
-    provider: pin.provider,
-    model: pin.model,
-    tier: pin.tier,
-    method: 'session_pin',
-    reason,
+    model: null,
+    tier: null,
+    reason: null,
     score: null,
-    analysis: null,
+    // `analysis` is appended after the ...fields spread (requestType
+    // derivation above); it defaults to null there.
     embeddingsResult: null,
     agenticResult: null,
-    costOptimized: false,
-    risk: risk ?? null,
     knnResult: null,
+    costOptimized: false,
+    risk: null,
     base_tier: null,
     escalations: [],
     escalation_source: null,
-    pinned: true,
+    pinned: false,
     switch_reason: null,
     propensity: 1.0,
-    candidates: [{ provider: pin.provider, model: pin.model }],
+    candidates: [{ provider: fields.provider, model: fields.model ?? null }],
+    ...fields,
+    analysis,
   };
 }
 
+/**
+ * Cache-aware switch gate (Phases 2+3).
+ *
+ * Prices a DOWNWARD (cost-motivated) model change against the session's warm
+ * prompt-cache prefix: inside the provider's cache TTL, the pin holds unless
+ * the break-even math clears within the session's expected remaining turns.
+ * A cold prefix (TTL elapsed — Phase 2) or absent cache state makes the
+ * switch cache-free and it passes.
+ *
+ * Upward/lateral moves (guard escalations, risk, drift to a higher tier)
+ * MUST NOT route through here — correctness beats cost, and the math can
+ * never favor a pricier model anyway.
+ *
+ * @returns {object|null} evaluation result, or null when gating doesn't
+ *   apply (same model, missing data, or evaluator failure — fail-open).
+ */
+function _cacheAwareSwitchGate(sessionId, pin, fresh, payload) {
+  if (!sessionId || !pin?.model || !fresh?.model) return null;
+  if (pin.provider === fresh.provider && pin.model === fresh.model) return null;
+  try {
+    const cacheState = sessionAffinity.getCacheState(sessionId);
+    const currentTurns = Array.isArray(payload?.messages) ? payload.messages.length : 0;
+    let expectedRemainingTurns = null;
+    try {
+      expectedRemainingTurns = telemetry.getExpectedRemainingTurns(currentTurns);
+    } catch { /* sparse-data default applies */ }
+    return evaluateCacheSwitch({
+      cacheState,
+      current: { provider: pin.provider, model: pin.model },
+      target: { provider: fresh.provider, model: fresh.model },
+      expectedRemainingTurns,
+    });
+  } catch (err) {
+    degradation.record('cache_switch_cost', err);
+    return null; // fail-open: gate must never block routing on an internal error
+  }
+}
+
+/** Shape the gate result into the telemetry receipt (Phase 6). */
+function _cacheDecisionReceipt(evaluation, decision) {
+  if (!evaluation) return null;
+  return {
+    decision,
+    reason: evaluation.reason,
+    warmPrefixTokens: evaluation.warmPrefixTokens,
+    breakEvenTurns: Number.isFinite(evaluation.breakEvenTurns)
+      ? Number(evaluation.breakEvenTurns.toFixed(2))
+      : evaluation.breakEvenTurns === Infinity ? -1 : null,
+    projectedSwitchCostUsd: evaluation.switchOnceUsd,
+    projectedStaySavingsUsd: evaluation.projectedStaySavingsUsd,
+    expectedRemainingTurns: evaluation.expectedRemainingTurns,
+  };
+}
+
+function _pinToDecision(pin, { reason, risk }) {
+  return buildDecision({
+    provider: pin.provider,
+    model: pin.model,
+    tier: pin.tier,
+    method: 'session_pin',
+    reason,
+    risk: risk ?? null,
+    pinned: true,
+  });
+}
+
 /**
  * Provider routing with cache-aware session pinning.
  *
@@ -325,7 +418,28 @@ async function determineProviderSmart(payload, options = {}) {
         fresh.switch_reason = 'score_drift';
         if (_tierPriority(fresh.tier) >= _tierPriority(pinCheck.pin.tier)) {
           writeSessionPin(pinCheck.sessionId, fresh, payload);
+          return fresh;
         }
+        // Fresh decision came back BELOW the pin on a drift re-decide —
+        // that's a cost-motivated downgrade (deescalator/bandit inside the
+        // fresh decision), so it must clear the cache break-even gate
+        // (Phases 2+3) before abandoning the warm prefix.
+        const gate = _cacheAwareSwitchGate(pinCheck.sessionId, pinCheck.pin, fresh, payload);
+        if (gate && !gate.switchAllowed) {
+          logger.info({
+            sessionId: pinCheck.sessionId,
+            pinModel: pinCheck.pin.model,
+            freshModel: fresh.model,
+            reason: gate.reason,
+            breakEvenTurns: gate.breakEvenTurns,
+            warmPrefixTokens: gate.warmPrefixTokens,
+          }, '[Routing] Cache break-even holds pin — downgrade suppressed');
+          const served = _pinToDecision(pinCheck.pin, { reason: 'cache_hold', risk: null });
+          served._cacheDecision = _cacheDecisionReceipt(gate, 'hold');
+          writeSessionPin(pinCheck.sessionId, pinCheck.pin, payload);
+          return served;
+        }
+        if (gate) fresh._cacheDecision = _cacheDecisionReceipt(gate, 'switch');
         return fresh;
       }
     }
@@ -352,6 +466,18 @@ async function determineProviderSmart(payload, options = {}) {
   // fires on the compaction path — guard escalations are mandatory.
   if (pinCheck.reason === 'compaction') {
     fresh.switch_reason = 'compaction';
+    // Compaction reset the provider-side prefix upstream (Phase 2: the
+    // cache is cold by construction), so the break-even gate doesn't apply;
+    // record the receipt so the dashboard can attribute the free switch.
+    fresh._cacheDecision = {
+      decision: 'switch',
+      reason: 'compaction_cache_reset',
+      warmPrefixTokens: 0,
+      breakEvenTurns: 0,
+      projectedSwitchCostUsd: null,
+      projectedStaySavingsUsd: null,
+      expectedRemainingTurns: null,
+    };
     const promptTokensEst = _tryCountTokens(payload, pin.model || fresh.model);
     if (!_economicDowngradeAllowed(promptTokensEst, pin.model, fresh.model)) {
       logger.debug({
@@ -713,17 +839,14 @@ async function _determineProviderSmartInner(payload, options = {}) {
 
   // If tier routing is disabled, use static configuration
   if (!config.modelTiers?.enabled) {
-    return {
+    return buildDecision({
       provider: primaryProvider,
-      model: null,
       method: 'static',
       reason: 'tier_routing_disabled',
       risk,
-      propensity: 1.0,
-      candidates: [{ provider: primaryProvider, model: null }],
       _queryEmbedding: queryEmbedding,
       _queryText: queryText,
-    };
+    });
   }
 
   // High-risk requests jump straight to COMPLEX and skip the rest of
@@ -736,7 +859,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
       // trusted provider (Claude) via REASONING, not the mid-tier GLM.
       // Security/auth/middleware changes belong on the governance path.
       const modelSelection = selector.selectModel('REASONING', null);
-      const decision = {
+      const decision = buildDecision({
         provider: modelSelection.provider,
         model: modelSelection.model,
         tier: 'REASONING',
@@ -744,7 +867,6 @@ async function _determineProviderSmartInner(payload, options = {}) {
         reason: 'high_risk_forced_tier',
         score: 100,
         risk,
-        base_tier: null,
         escalations: [{
           source: 'risk',
           fromTier: null,
@@ -753,11 +875,9 @@ async function _determineProviderSmartInner(payload, options = {}) {
           toModel: modelSelection.model,
         }],
         escalation_source: 'risk',
-        propensity: 1.0,
-        candidates: [{ provider: modelSelection.provider, model: modelSelection.model }],
         _queryEmbedding: queryEmbedding,
         _queryText: queryText,
-      };
+      });
       routingMetrics.record(decision);
       logger.debug({
         tier: 'REASONING',
@@ -778,7 +898,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
       try {
         const selector = getModelTierSelector();
         const modelSelection = selector.selectModel('SIMPLE', null);
-        const decision = {
+        const decision = buildDecision({
           provider: modelSelection.provider,
           model: modelSelection.model,
           tier: 'SIMPLE',
@@ -786,11 +906,9 @@ async function _determineProviderSmartInner(payload, options = {}) {
           reason: 'force_local_pattern',
           score: 0,
           risk,
-          propensity: 1.0,
-          candidates: [{ provider: modelSelection.provider, model: modelSelection.model }],
           _queryEmbedding: queryEmbedding,
           _queryText: queryText,
-        };
+        });
         routingMetrics.record(decision);
         return decision;
       } catch (err) {
@@ -798,18 +916,15 @@ async function _determineProviderSmartInner(payload, options = {}) {
       }
     }
     const provider = getBestLocalProvider();
-    const decision = {
+    const decision = buildDecision({
       provider,
-      model: null,
       method: 'force',
       reason: 'force_local_pattern',
       score: 0,
       risk,
-      propensity: 1.0,
-      candidates: [{ provider, model: null }],
       _queryEmbedding: queryEmbedding,
       _queryText: queryText,
-    };
+    });
     routingMetrics.record(decision);
     return decision;
   }
@@ -821,7 +936,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
     try {
       const selector = getModelTierSelector();
       const modelSelection = selector.selectModel('REASONING', null);
-      const decision = {
+      const decision = buildDecision({
         provider: modelSelection.provider,
         model: modelSelection.model,
         tier: 'REASONING',
@@ -829,11 +944,9 @@ async function _determineProviderSmartInner(payload, options = {}) {
         reason: 'force_reasoning_pattern',
         score: 100,
         risk,
-        propensity: 1.0,
-        candidates: [{ provider: modelSelection.provider, model: modelSelection.model }],
         _queryEmbedding: queryEmbedding,
         _queryText: queryText,
-      };
+      });
       routingMetrics.record(decision);
       return decision;
     } catch (err) {
@@ -854,7 +967,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
       try {
         const selector = getModelTierSelector();
         const modelSelection = selector.selectModel('COMPLEX', null);
-        const decision = {
+        const decision = buildDecision({
           provider: modelSelection.provider,
           model: modelSelection.model,
           tier: 'COMPLEX',
@@ -862,11 +975,9 @@ async function _determineProviderSmartInner(payload, options = {}) {
           reason: 'force_cloud_pattern',
           score: 100,
           risk,
-          propensity: 1.0,
-          candidates: [{ provider: modelSelection.provider, model: modelSelection.model }],
           _queryEmbedding: queryEmbedding,
           _queryText: queryText,
-        };
+        });
         routingMetrics.record(decision);
         return decision;
       } catch (err) {
@@ -874,18 +985,15 @@ async function _determineProviderSmartInner(payload, options = {}) {
       }
     }
     const provider = getBestCloudProvider();
-    const decision = {
+    const decision = buildDecision({
       provider,
-      model: null,
       method: 'force',
       reason: 'force_cloud_pattern',
       score: 100,
       risk,
-      propensity: 1.0,
-      candidates: [{ provider, model: null }],
       _queryEmbedding: queryEmbedding,
       _queryText: queryText,
-    };
+    });
     routingMetrics.record(decision);
     return decision;
   }
@@ -973,7 +1081,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
             try {
               const selector = getModelTierSelector();
               const modelSelection = selector.selectModel('REASONING', null);
-              const decision = {
+              const decision = buildDecision({
                 provider: modelSelection.provider,
                 model: modelSelection.model,
                 tier: 'REASONING',
@@ -986,11 +1094,9 @@ async function _determineProviderSmartInner(payload, options = {}) {
                 score: 100,
                 agenticResult,
                 risk,
-                propensity: 1.0,
-                candidates: [{ provider: modelSelection.provider, model: modelSelection.model }],
                 _queryEmbedding: queryEmbedding,
                 _queryText: queryText,
-              };
+              });
               routingMetrics.record(decision);
               return decision;
             } catch (err) {
@@ -998,18 +1104,16 @@ async function _determineProviderSmartInner(payload, options = {}) {
             }
           }
           const provider = getBestCloudProvider();
-          const decision = {
+          const decision = buildDecision({
             provider,
             method: 'agentic',
             reason: 'autonomous_workflow',
             score: 100, // trigger score matches forced tier — see comment above
             agenticResult,
             risk,
-            propensity: 1.0,
-            candidates: [{ provider, model: null }],
             _queryEmbedding: queryEmbedding,
             _queryText: queryText,
-          };
+          });
           routingMetrics.record(decision);
           return decision;
         }
@@ -1445,7 +1549,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
     }
   }
 
-  const decision = {
+  const decision = buildDecision({
     provider,
     model: selectedModel,
     tier,
@@ -1468,7 +1572,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
     escalation_source: escalations[0]?.source
       ?? (demotedFrom ? 'deescalation' : null),
     demoted_from: demotedFrom,
-  };
+  });
 
   // WS4.2 — propensity/candidates for off-policy evaluation from telemetry.
   // Bandit picks populate both. If a deterministic downstream override
@@ -1614,6 +1718,10 @@ module.exports = {
   // WS1.5: upward-drift detection for pinned sessions
   checkPinScoreDrift,
 
+  // Canonical decision constructor — every routing decision must be built
+  // through this (see the anti-drift shape test in test/routing.test.js).
+  buildDecision,
+
   // WS1: test-only internals (exercised by test/sticky-routing.test.js)
   _internals: {
     economicDowngradeAllowed: _economicDowngradeAllowed,

package/src/routing/model-registry.js

@@ -17,16 +17,19 @@ const CACHE_FILE = path.join(__dirname, '../../data/model-prices-cache.json');
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const REFRESH_RETRY_MS = 5 * 60 * 1000; // backoff between failed refresh attempts
 
-// Databricks fallback pricing (based on Anthropic direct API prices)
+// Databricks fallback pricing (based on Anthropic direct API prices).
+// cacheRead/cacheWrite are absolute USD/1M (0.1x / 1.25x input — Anthropic
+// explicit caching, 5-min TTL); non-Claude rows omit them and inherit the
+// provider-type multipliers in cache-economics.js.
 const DATABRICKS_FALLBACK = {
   // Claude models
-  'databricks-claude-opus-4-6': { input: 5.0, output: 25.0, context: 1000000 },
-  'databricks-claude-opus-4-5': { input: 5.0, output: 25.0, context: 200000 },
-  'databricks-claude-opus-4-1': { input: 15.0, output: 75.0, context: 200000 },
-  'databricks-claude-sonnet-4-5': { input: 3.0, output: 15.0, context: 200000 },
-  'databricks-claude-sonnet-4': { input: 3.0, output: 15.0, context: 200000 },
-  'databricks-claude-3-7-sonnet': { input: 3.0, output: 15.0, context: 200000 },
-  'databricks-claude-haiku-4-5': { input: 1.0, output: 5.0, context: 200000 },
+  'databricks-claude-opus-4-6': { input: 5.0, output: 25.0, cacheRead: 0.5, cacheWrite: 6.25, context: 1000000 },
+  'databricks-claude-opus-4-5': { input: 5.0, output: 25.0, cacheRead: 0.5, cacheWrite: 6.25, context: 200000 },
+  'databricks-claude-opus-4-1': { input: 15.0, output: 75.0, cacheRead: 1.5, cacheWrite: 18.75, context: 200000 },
+  'databricks-claude-sonnet-4-5': { input: 3.0, output: 15.0, cacheRead: 0.3, cacheWrite: 3.75, context: 200000 },
+  'databricks-claude-sonnet-4': { input: 3.0, output: 15.0, cacheRead: 0.3, cacheWrite: 3.75, context: 200000 },
+  'databricks-claude-3-7-sonnet': { input: 3.0, output: 15.0, cacheRead: 0.3, cacheWrite: 3.75, context: 200000 },
+  'databricks-claude-haiku-4-5': { input: 1.0, output: 5.0, cacheRead: 0.1, cacheWrite: 1.25, context: 200000 },
 
   // Llama models
   'databricks-llama-4-maverick': { input: 1.0, output: 1.0, context: 128000 },
@@ -208,6 +211,16 @@ class ModelRegistry {
       prices[modelId.toLowerCase()] = {
         input: inputCost,
         output: outputCost,
+        // Cache economics (Phase 4) — LiteLLM publishes per-token cache
+        // read/write costs for providers that price them. Absent fields
+        // stay undefined so cache-economics.js falls back to its
+        // provider-type multiplier table.
+        ...(info.cache_read_input_token_cost != null
+          ? { cacheRead: info.cache_read_input_token_cost * 1_000_000 }
+          : {}),
+        ...(info.cache_creation_input_token_cost != null
+          ? { cacheWrite: info.cache_creation_input_token_cost * 1_000_000 }
+          : {}),
         context: info.max_input_tokens || info.max_tokens || 128000,
         maxOutput: info.max_output_tokens || 4096,
         toolCall: info.supports_function_calling ?? true,
@@ -296,9 +309,21 @@ class ModelRegistry {
       this.modelIndex.set(modelId, info);
     }
 
-    // Add LiteLLM (highest priority)
+    // Add LiteLLM (highest priority) — but merge cache economics from the
+    // entry it shadows: LiteLLM wins on base prices, while cacheRead/
+    // cacheWrite survive from models.dev when LiteLLM doesn't carry them.
+    // Without this, a LiteLLM entry missing cache prices hides the
+    // models.dev cache data and the switch-cost math degrades to
+    // provider-multiplier approximations (observed live: 0 LiteLLM entries
+    // with cacheRead shadowing 4.9k models.dev entries that had it).
     for (const [modelId, info] of Object.entries(this.litellmPrices)) {
-      this.modelIndex.set(modelId, info);
+      const prev = this.modelIndex.get(modelId);
+      const merged = { ...info };
+      if (prev) {
+        if (merged.cacheRead == null && typeof prev.cacheRead === 'number') merged.cacheRead = prev.cacheRead;
+        if (merged.cacheWrite == null && typeof prev.cacheWrite === 'number') merged.cacheWrite = prev.cacheWrite;
+      }
+      this.modelIndex.set(modelId, merged);
     }
   }
 

package/src/routing/session-affinity.js

@@ -172,6 +172,64 @@ function shouldRepin(pin, payload) {
   return { repin: false, reason: null };
 }
 
+// ---------------------------------------------------------------------------
+// Cache-aware routing (Phase 1) — per-session prompt-cache state.
+//
+// After every upstream response we record how much of the session's prefix
+// is warm on the provider side: cache_read + cache_creation tokens together
+// describe the cached prefix as of that response. Anthropic-style explicit
+// caches refresh their TTL on every read, so `lastRequestAt + ttlMs` is a
+// live cache clock the switch-timing logic (Phase 2) can consult.
+// ---------------------------------------------------------------------------
+
+/**
+ * Record prompt-cache usage from an upstream response. No-ops when the
+ * response carried no cache signal (both counters zero/absent) so providers
+ * without cache reporting simply never accrue state.
+ *
+ * Overwrites unconditionally on signal: if the session switched models, the
+ * new response's numbers ARE the new model's cache state (caches are
+ * model-scoped — never carry a warm-prefix figure across a switch).
+ *
+ * @param {string} sessionId
+ * @param {{provider:string, model?:string|null, cacheReadTokens?:number, cacheCreationTokens?:number}} usage
+ */
+function recordCacheUsage(sessionId, usage) {
+  if (!sessionId || !usage?.provider) return;
+  const read = Number(usage.cacheReadTokens) || 0;
+  const created = Number(usage.cacheCreationTokens) || 0;
+  const warm = read + created;
+  if (warm <= 0) return; // no cache signal — state stays absent
+
+  let ttlMs = 5 * 60 * 1000;
+  try {
+    const { resolveCacheEconomics } = require("./cache-economics");
+    ttlMs = resolveCacheEconomics(usage.provider, usage.model ?? null).ttlMs;
+  } catch { /* keep default */ }
+
+  store.saveCacheState(sessionId, {
+    warmPrefixTokens: warm,
+    provider: usage.provider,
+    model: usage.model ?? null,
+    lastRequestAt: Date.now(),
+    ttlMs,
+  });
+}
+
+/**
+ * Load the session's cache state, annotated with liveness. Returns null when
+ * no state exists (provider reports no cache usage, or no response yet).
+ *
+ * @param {string} sessionId
+ * @returns {({warmPrefixTokens:number, provider:string, model:string|null, lastRequestAt:number, ttlMs:number, cold:boolean})|null}
+ */
+function getCacheState(sessionId) {
+  const state = store.loadCacheState(sessionId);
+  if (!state || typeof state.lastRequestAt !== "number") return null;
+  const ttl = typeof state.ttlMs === "number" ? state.ttlMs : 5 * 60 * 1000;
+  return { ...state, cold: Date.now() - state.lastRequestAt > ttl };
+}
+
 /** Test/maintenance helper — clear the in-memory Map only. */
 function _clear() {
   pins.clear();
@@ -223,6 +281,8 @@ module.exports = {
   setPin,
   removePin,
   shouldRepin,
+  recordCacheUsage,
+  getCacheState,
   // legacy
   getPinned,
   setPinned,