lynkr 9.9.1 → 9.11.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({
@@ -584,6 +710,8 @@ function checkSessionPin(payload, options = {}) {
         // the new_conversation guard for everyone after it.
         messageCount: Math.max(messageCount, pin.messageCount ?? 0),
         promptTokensEst: pin.promptTokensEst,
+        // We're inside payloadHasToolHistory(payload) — session has committed.
+        hasToolHistory: true,
       });
     }
     return { serve: true, pin, reason: 'tool_history', sessionId };
@@ -599,11 +727,30 @@ function checkSessionPin(payload, options = {}) {
     sessionAffinity.setPin(sessionId, pin, {
       messageCount: Math.max(messageCount, pin.messageCount ?? 0),
       promptTokensEst: guards.promptTokensEst ?? pin.promptTokensEst,
+      // setPin OR-merges with the existing pin's flag, so a plain-text turn
+      // between tool exchanges keeps the sticky-true property.
+      hasToolHistory: _payloadHasAnyToolBlocks(payload),
     });
   }
   return { serve: true, pin, reason: 'guards_passed', sessionId };
 }
 
+/** Whole-payload scan for tool_use/tool_result blocks. Unlike
+ * sessionAffinity.payloadHasToolHistory (last message only), this checks
+ * every message so we correctly flag sessions where the last frame is a
+ * plain text turn but earlier turns carried tools. */
+function _payloadHasAnyToolBlocks(payload) {
+  const msgs = payload?.messages;
+  if (!Array.isArray(msgs)) return false;
+  for (const m of msgs) {
+    if (!Array.isArray(m?.content)) continue;
+    for (const b of m.content) {
+      if (b?.type === 'tool_use' || b?.type === 'tool_result') return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Write-through helper: persist a fresh routing decision as the session's
  * new pin. No-op when sessionId is missing or the decision has no provider.
@@ -642,7 +789,11 @@ function writeSessionPin(sessionId, decision, payload) {
     return;
   }
   const promptTokensEst = _tryCountTokens(payload, decision.model);
-  sessionAffinity.setPin(sessionId, decision, { messageCount, promptTokensEst });
+  sessionAffinity.setPin(sessionId, decision, {
+    messageCount,
+    promptTokensEst,
+    hasToolHistory: _payloadHasAnyToolBlocks(payload),
+  });
 }
 
 async function _determineProviderSmartInner(payload, options = {}) {
@@ -688,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
@@ -711,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',
@@ -719,7 +867,6 @@ async function _determineProviderSmartInner(payload, options = {}) {
         reason: 'high_risk_forced_tier',
         score: 100,
         risk,
-        base_tier: null,
         escalations: [{
           source: 'risk',
           fromTier: null,
@@ -728,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',
@@ -753,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',
@@ -761,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) {
@@ -773,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;
   }
@@ -796,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',
@@ -804,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) {
@@ -829,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',
@@ -837,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) {
@@ -849,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;
   }
@@ -948,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',
@@ -961,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) {
@@ -973,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;
         }
@@ -1088,10 +1217,17 @@ async function _determineProviderSmartInner(payload, options = {}) {
 
   // Phase 1.2 — cost-optimizer override.
   // Only kick in when:
-  //  - feature flag enabled (default true, disable with LYNKR_COST_OPTIMIZE=false)
+  //  - feature flag EXPLICITLY enabled with LYNKR_COST_OPTIMIZE=true (default OFF)
   //  - risk level is not high (high-risk keeps the explicitly-configured model)
   //  - the optimizer finds a meaningfully cheaper qualifying model
-  const costOptimizeEnabled = process.env.LYNKR_COST_OPTIMIZE !== 'false'
+  //
+  // Default changed to OFF (2026-07-20): the optimizer silently overrides
+  // explicit TIER_* config with the cheapest model in the tier pool, which
+  // surprised operators who expected their tier settings to be authoritative
+  // (e.g. TIER_REASONING=azure-anthropic:claude-opus-4.7 was being swapped
+  // for openrouter:deepseek/deepseek-reasoner — which was also a typo that
+  // 400'd upstream). Opt-in only.
+  const costOptimizeEnabled = process.env.LYNKR_COST_OPTIMIZE === 'true'
     && config.routing?.costOptimize !== false;
   if (costOptimizeEnabled && risk?.level !== 'high') {
     try {
@@ -1413,7 +1549,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
     }
   }
 
-  const decision = {
+  const decision = buildDecision({
     provider,
     model: selectedModel,
     tier,
@@ -1436,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
@@ -1582,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/intent-score.js

@@ -347,9 +347,21 @@ function _reconcile(anchorScore, anchorClass, classifierResult) {
     // Classifier says LOWER tier — trust it. Fixes over-routing.
     return { score: TIER_MIDPOINT[classifierTier], reconciled: 'down' };
   }
-  // Classifier says HIGHER tier — gate on confidence.
+  // Classifier says HIGHER tier — gate on confidence, and cap the jump at
+  // ONE band above the anchor. The classifier is a tiebreaker, not an
+  // oracle: qwen2.5:3b's confidence is degenerate (92% of eval answers say
+  // 0.9-1.0, incl. every wrong one), so an unbounded jump let a 3B verdict
+  // catapult "Who kills him ?" from anchor 25 to 88 → REASONING →
+  // subscription passthrough (live incident 2026-07-21). Escalating past
+  // the adjacent band now takes consecutive turns that keep re-scoring
+  // higher, which is exactly the persistence a genuinely hard conversation
+  // exhibits.
   if (classifierResult.confidence >= 0.8) {
-    return { score: TIER_MIDPOINT[classifierTier], reconciled: 'up' };
+    const cappedIdx = Math.min(classifierIdx, anchorIdx + 1);
+    return {
+      score: TIER_MIDPOINT[TIER_ORDER[cappedIdx]],
+      reconciled: cappedIdx < classifierIdx ? 'up_capped' : 'up',
+    };
   }
   return { score: anchorScore, reconciled: 'up_gated' };
 }
@@ -385,6 +397,12 @@ async function scoreIntent(payload, opts = {}) {
             classifierResult = await classifyDifficulty(text, {
               forceMatched: opts.forceMatched,
               riskLevel: opts.riskLevel,
+              // Condensed prior turns, threaded by the router's window loop.
+              // Without it a short follow-up ("Who kills him ?") is
+              // unclassifiable in isolation.
+              context: typeof payload?._conversationContext === 'string'
+                ? payload._conversationContext
+                : null,
             });
           } catch (err) {
             logger.debug({ err: err.message }, '[IntentScore] classifier failed — anchor only');

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);
     }
   }