lynkr 9.9.1 → 9.11.0

package/src/routing/cache-economics.js

@@ -0,0 +1,123 @@
+/**
+ * Per-provider prompt-cache economics.
+ *
+ * Single resolution point for "what does the prompt cache cost on this
+ * provider/model": read price, write price, TTL, and mechanism. The
+ * switch-cost math in `cache-switch-cost.js` and the cache-state tracker in
+ * `session-affinity.js` read from here — decision code never hardcodes
+ * per-model numbers.
+ *
+ * Resolution order per field:
+ *   1. model-registry entry (models.dev carries absolute cacheRead/cacheWrite
+ *      $/1M for many models)
+ *   2. provider-type fallback table below (multipliers of the model's input
+ *      price), researched Aug 2026.
+ *
+ * Mechanisms:
+ *   - 'explicit'  — cache_control breakpoints, paid writes (Anthropic-style).
+ *     TTL refreshes on every read, so lastRequestAt + ttlMs is a live clock.
+ *   - 'automatic' — provider caches transparently, writes are free
+ *     (OpenAI/DeepSeek/Gemini-style). TTL is best-effort.
+ *   - 'local'     — no dollar cost at all; the "cost" of a cold prefix is
+ *     prefill latency, handled separately in cache-switch-cost.js.
+ *
+ * @module routing/cache-economics
+ */
+
+const logger = require('../logger');
+
+// Fallback economics keyed by Lynkr provider type. `readMult`/`writeMult`
+// are multipliers of the model's per-1M input price.
+const PROVIDER_CACHE_DEFAULTS = {
+  // Anthropic-hosted (explicit cache_control, 1.25x write for the 5-min TTL,
+  // TTL refreshed on every read).
+  'azure-anthropic': { readMult: 0.1, writeMult: 1.25, ttlMs: 5 * 60 * 1000, mechanism: 'explicit' },
+  bedrock:           { readMult: 0.1, writeMult: 1.25, ttlMs: 5 * 60 * 1000, mechanism: 'explicit' },
+  databricks:        { readMult: 0.1, writeMult: 1.25, ttlMs: 5 * 60 * 1000, mechanism: 'explicit' },
+
+  // OpenAI automatic prefix caching: writes free, ~5-10 min idle eviction.
+  openai:         { readMult: 0.1, writeMult: 0, ttlMs: 10 * 60 * 1000, mechanism: 'automatic' },
+  'azure-openai': { readMult: 0.1, writeMult: 0, ttlMs: 10 * 60 * 1000, mechanism: 'automatic' },
+
+  // Gemini implicit caching / GLM / Kimi / aggregators: free automatic
+  // caching, best-effort TTL. Aggregators (openrouter/edenai) depend on the
+  // underlying model; models.dev per-model data wins when present.
+  vertex:     { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  zai:        { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  moonshot:   { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  openrouter: { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  edenai:     { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  // DeepSeek direct (via aggregators today, kept for model-level matches):
+  deepseek:   { readMult: 0.02, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+
+  // Local runtimes: no dollars; KV cache lives as long as the model stays
+  // loaded (ollama keep_alive default ~5 min).
+  ollama:   { readMult: 0, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'local' },
+  llamacpp: { readMult: 0, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'local' },
+  lmstudio: { readMult: 0, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'local' },
+};
+
+const GENERIC_DEFAULT = { readMult: 0.1, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' };
+
+/**
+ * Fallback cache economics for a provider type (no model lookup).
+ * @param {string|null} providerType
+ * @returns {{readMult:number, writeMult:number, ttlMs:number, mechanism:string}}
+ */
+function getProviderCacheDefaults(providerType) {
+  return PROVIDER_CACHE_DEFAULTS[providerType] || GENERIC_DEFAULT;
+}
+
+/**
+ * Resolve full cache economics for a provider/model pair.
+ *
+ * @param {string|null} providerType - Lynkr provider type (e.g. 'databricks')
+ * @param {string|null} model - model name for registry lookup
+ * @returns {{
+ *   inputPerM:number, outputPerM:number,
+ *   cacheReadPerM:number, cacheWritePerM:number,
+ *   ttlMs:number, mechanism:string, unknownPricing:boolean
+ * }} All prices are USD per 1M tokens.
+ */
+function resolveCacheEconomics(providerType, model) {
+  const defaults = getProviderCacheDefaults(providerType);
+
+  let cost = null;
+  try {
+    const { getModelRegistrySync } = require('./model-registry');
+    cost = model ? getModelRegistrySync().getCost(model) : null;
+  } catch (err) {
+    logger.debug({ err: err.message }, '[CacheEconomics] registry lookup failed');
+  }
+
+  const inputPerM = typeof cost?.input === 'number' ? cost.input : 0;
+  const outputPerM = typeof cost?.output === 'number' ? cost.output : 0;
+
+  // Registry cacheTtlMs/cacheMechanism (Phase 4 entries) win over the
+  // provider fallback; models.dev absolute cache prices win over multipliers.
+  const mechanism = cost?.cacheMechanism || defaults.mechanism;
+  const ttlMs = typeof cost?.cacheTtlMs === 'number' ? cost.cacheTtlMs : defaults.ttlMs;
+
+  const cacheReadPerM = mechanism === 'local'
+    ? 0
+    : (typeof cost?.cacheRead === 'number' ? cost.cacheRead : inputPerM * defaults.readMult);
+  const cacheWritePerM = mechanism === 'local'
+    ? 0
+    : (typeof cost?.cacheWrite === 'number' ? cost.cacheWrite : inputPerM * defaults.writeMult);
+
+  return {
+    inputPerM,
+    outputPerM,
+    cacheReadPerM,
+    cacheWritePerM,
+    ttlMs,
+    mechanism,
+    unknownPricing: !!cost?.unknown,
+  };
+}
+
+module.exports = {
+  PROVIDER_CACHE_DEFAULTS,
+  getProviderCacheDefaults,
+  resolveCacheEconomics,
+};

package/src/routing/cache-switch-cost.js

@@ -0,0 +1,194 @@
+/**
+ * Switch-cost break-even model (Phase 3, cache-aware routing).
+ *
+ * Answers one question for a session that holds a warm prompt-cache prefix
+ * on its pinned model: does switching to a cheaper target model pay for the
+ * cache it breaks, within the turns this session is expected to have left?
+ *
+ *   stayPerTurn    = warm*cacheRead(cur) + new*input(cur) + out*output(cur)
+ *   switchOnce     = (warm + new) * cacheWrite(target)     // one-time
+ *   switchPerTurn  = warm*cacheRead(tgt) + new*input(tgt) + out*output(tgt)
+ *   breakEvenTurns = switchOnce / (stayPerTurn - switchPerTurn)
+ *
+ * Switch iff breakEvenTurns <= expectedRemainingTurns.
+ *
+ * The output-token term is deliberately included: for de-escalation the
+ * dominant per-turn saving is often the output-price spread (e.g. Opus $25/M
+ * vs Haiku $5/M out), and omitting it makes the router hold expensive pins
+ * long past the point the economics justify.
+ *
+ * Scope: this module prices COST-MOTIVATED switches (de-escalator, bandit
+ * exploration, economic downgrades). Hard triggers — risk keywords, force
+ * phrases, context overflow, vision, upward drift — are never gated here;
+ * correctness beats cost and the math can never favor a pricier model anyway
+ * (savings would be negative).
+ *
+ * Local models have no dollar cost; the price of a cold prefix is prefill
+ * latency, so a warm local prefix above a size threshold holds the pin.
+ *
+ * All pricing comes from cache-economics.js (registry-first, provider
+ * fallback) — no per-model numbers live in this file.
+ *
+ * @module routing/cache-switch-cost
+ */
+
+const config = require('../config');
+const logger = require('../logger');
+
+const PER_TOKEN = 1 / 1_000_000; // registry prices are USD per 1M tokens
+
+function _cfg() {
+  const c = config.routing?.cacheAware || {};
+  return {
+    enabled: c.enabled !== false,
+    defaultRemainingTurns: c.defaultRemainingTurns ?? 10,
+    newTokensPerTurn: c.newTokensPerTurn ?? 2000,
+    outputTokensPerTurn: c.outputTokensPerTurn ?? 800,
+    localMaxSwitchPrefixTokens: c.localMaxSwitchPrefixTokens ?? 16000,
+  };
+}
+
+/**
+ * Evaluate whether a cost-motivated switch away from the session's warm
+ * prefix should be allowed.
+ *
+ * @param {Object} args
+ * @param {Object|null} args.cacheState - from sessionAffinity.getCacheState:
+ *   {warmPrefixTokens, provider, model, lastRequestAt, ttlMs, cold} or null.
+ * @param {{provider:string, model:string|null}} args.current - pinned target.
+ * @param {{provider:string, model:string|null}} args.target - proposed target.
+ * @param {number} [args.newTokensPerTurn] - est. fresh input tokens per turn.
+ * @param {number} [args.outputTokensPerTurn] - est. output tokens per turn.
+ * @param {number|null} [args.expectedRemainingTurns] - median remaining
+ *   turns; falls back to the conservative config default when null.
+ * @param {Object} [args.deps] - test injection: {resolveCacheEconomics}.
+ * @returns {{
+ *   switchAllowed: boolean,
+ *   reason: string,
+ *   breakEvenTurns: number|null,
+ *   expectedRemainingTurns: number,
+ *   warmPrefixTokens: number,
+ *   switchOnceUsd: number|null,
+ *   stayPerTurnUsd: number|null,
+ *   switchPerTurnUsd: number|null,
+ *   projectedStaySavingsUsd: number|null,
+ * }}
+ */
+function evaluateSwitch({
+  cacheState,
+  current,
+  target,
+  newTokensPerTurn,
+  outputTokensPerTurn,
+  expectedRemainingTurns,
+  deps = {},
+} = {}) {
+  const cfg = _cfg();
+  const remaining = Number.isFinite(expectedRemainingTurns) && expectedRemainingTurns > 0
+    ? expectedRemainingTurns
+    : cfg.defaultRemainingTurns;
+
+  const base = {
+    switchAllowed: true,
+    reason: 'no_cache_state',
+    breakEvenTurns: null,
+    expectedRemainingTurns: remaining,
+    warmPrefixTokens: cacheState?.warmPrefixTokens ?? 0,
+    switchOnceUsd: null,
+    stayPerTurnUsd: null,
+    switchPerTurnUsd: null,
+    projectedStaySavingsUsd: null,
+  };
+
+  if (!cfg.enabled) return { ...base, reason: 'feature_disabled' };
+  if (!current?.provider || !target?.provider) return base;
+  if (current.provider === target.provider && current.model === target.model) {
+    return { ...base, reason: 'same_model' };
+  }
+
+  // No tracked state → nothing warm to protect (provider reports no cache
+  // usage, or no response seen yet). Switching is cache-free.
+  if (!cacheState || !(cacheState.warmPrefixTokens > 0)) return base;
+
+  // State recorded for a different model than the pin we're defending —
+  // stale after a prior switch; treat as no protection.
+  if (cacheState.model && current.model && cacheState.model !== current.model) {
+    return { ...base, reason: 'stale_cache_state' };
+  }
+
+  // Phase 2 — TTL clock. Anthropic-style caches refresh on every read, so
+  // lastRequestAt + ttlMs going stale means the prefix is already cold and
+  // the switch costs nothing extra.
+  if (cacheState.cold) return { ...base, reason: 'cache_cold' };
+
+  let resolve = deps.resolveCacheEconomics;
+  if (typeof resolve !== 'function') {
+    ({ resolveCacheEconomics: resolve } = require('./cache-economics'));
+  }
+
+  const econCur = resolve(current.provider, current.model);
+  const econTgt = resolve(target.provider, target.model);
+
+  const W = cacheState.warmPrefixTokens;
+  const N = Number.isFinite(newTokensPerTurn) && newTokensPerTurn >= 0
+    ? newTokensPerTurn : cfg.newTokensPerTurn;
+  const O = Number.isFinite(outputTokensPerTurn) && outputTokensPerTurn >= 0
+    ? outputTokensPerTurn : cfg.outputTokensPerTurn;
+
+  // Local pin: no dollars in either column — the cost of abandoning the
+  // warm prefix is prefill latency on whatever serves the next turn.
+  // Hold while the prefix is large; small prefixes re-fill fast enough.
+  if (econCur.mechanism === 'local' && econTgt.mechanism === 'local') {
+    const allowed = W <= cfg.localMaxSwitchPrefixTokens;
+    return {
+      ...base,
+      switchAllowed: allowed,
+      reason: allowed ? 'local_prefix_small' : 'local_prefill_hold',
+    };
+  }
+
+  const stayPerTurn = (W * econCur.cacheReadPerM + N * econCur.inputPerM + O * econCur.outputPerM) * PER_TOKEN;
+  const switchOnce = (W + N) * econTgt.cacheWritePerM * PER_TOKEN;
+  const switchPerTurn = (W * econTgt.cacheReadPerM + N * econTgt.inputPerM + O * econTgt.outputPerM) * PER_TOKEN;
+  const savingsPerTurn = stayPerTurn - switchPerTurn;
+
+  const priced = {
+    ...base,
+    switchOnceUsd: switchOnce,
+    stayPerTurnUsd: stayPerTurn,
+    switchPerTurnUsd: switchPerTurn,
+    projectedStaySavingsUsd: savingsPerTurn,
+  };
+
+  // Switching to a same-or-more-expensive target never pays on economics.
+  // (Escalations don't route through this gate, so blocking is safe.)
+  if (savingsPerTurn <= 0) {
+    return {
+      ...priced,
+      switchAllowed: false,
+      reason: 'never_profitable',
+      breakEvenTurns: Infinity,
+    };
+  }
+
+  const breakEvenTurns = switchOnce / savingsPerTurn;
+  const allowed = breakEvenTurns <= remaining;
+
+  logger.debug({
+    current: `${current.provider}:${current.model}`,
+    target: `${target.provider}:${target.model}`,
+    warmPrefixTokens: W,
+    breakEvenTurns: Number(breakEvenTurns.toFixed(2)),
+    expectedRemainingTurns: remaining,
+    allowed,
+  }, '[CacheSwitchCost] break-even evaluated');
+
+  return {
+    ...priced,
+    switchAllowed: allowed,
+    reason: allowed ? 'break_even_cleared' : 'break_even_blocked',
+    breakEvenTurns,
+  };
+}
+
+module.exports = { evaluateSwitch };

package/src/routing/calibration.js

@@ -146,7 +146,8 @@ function runCalibration({ days = DEFAULT_DAYS, dryRun = false, dbPath, outputPat
       continue;
     }
     const ordered = Array.from(tierBuckets.entries()).sort((a, b) => a[0] - b[0]);
-    let suggestedUpper = DEFAULT_RANGES[tier][1];
+    const [defaultLower, defaultUpper] = DEFAULT_RANGES[tier];
+    let suggestedUpper = defaultUpper;
     const bucketsSummary = [];
     for (const [lo, vals] of ordered) {
       if (vals.length < 5) {
@@ -155,6 +156,12 @@ function runCalibration({ days = DEFAULT_DAYS, dryRun = false, dbPath, outputPat
       }
       const med = _median(vals);
       bucketsSummary.push({ bucket: lo, samples: vals.length, median: med });
+      // Buckets outside the tier's own default range come from fallback-served
+      // requests (another tier's scores recorded under the serving tier). They
+      // say nothing about this tier's real range, and letting them shrink the
+      // upper bound below the lower bound collapses the tier to a single point
+      // in re-stitching (observed 2026-07-26: MEDIUM → [20,20]).
+      if (lo + 4 < defaultLower || lo > defaultUpper) continue;
       if (med < floor && lo + 4 < suggestedUpper) {
         // shrink tier upper bound just below the failing bucket
         suggestedUpper = lo + 4;

package/src/routing/complexity-analyzer.js

@@ -795,7 +795,13 @@ async function analyzeComplexity(payload, options = {}) {
       threshold,
       mode: 'weighted',
       recommendation,
-      breakdown: weighted.dimensions,
+      // taskType rides alongside the numeric dimensions. The legacy path
+      // has always carried breakdown.taskType, and both the deescalator
+      // (tier + request_type evidence key) and the telemetry request_type
+      // column derive from it — without it here, weighted-mode requests
+      // (the default) recorded request_type NULL and could never
+      // accumulate demotion evidence.
+      breakdown: { ...weighted.dimensions, taskType: taskTypeResult },
       weights: weighted.weights,
       meta: weighted.meta,
       forceReason: taskTypeResult.reason?.startsWith('force_') ? taskTypeResult.reason : null,

package/src/routing/context-compressor.js

@@ -0,0 +1,170 @@
+/**
+ * Context Compression Module
+ *
+ * Inspired by TencentDB Agent Memory's short-term memory compression.
+ * Reduces conversation context size before complexity scoring to enable
+ * more accurate tier routing.
+ *
+ * Key insight: Long conversations bloat context → force expensive routing
+ * even for simple follow-ups. By compressing tool outputs and previous
+ * turns, we keep more requests in SIMPLE/MEDIUM tiers.
+ *
+ * @module routing/context-compressor
+ */
+
+const logger = require('../logger');
+
+/**
+ * Compress conversation messages by:
+ * 1. Offloading verbose tool_result content
+ * 2. Summarizing repetitive patterns
+ * 3. Keeping only essential context for scoring
+ *
+ * Does NOT modify the actual request sent to LLM — only used for complexity scoring.
+ *
+ * @param {Array} messages - Conversation messages
+ * @returns {{ compressed: Array, stats: Object }} - Compressed messages + stats
+ */
+function compressMessages(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return { compressed: messages, stats: { original: 0, compressed: 0, ratio: 1.0 } };
+  }
+
+  const compressed = [];
+  let originalSize = 0;
+  let compressedSize = 0;
+  let toolResultsOffloaded = 0;
+  let messagesKept = 0;
+
+  // Keep system message always
+  const systemMsg = messages.find(m => m.role === 'system');
+  if (systemMsg) {
+    compressed.push(systemMsg);
+    const size = estimateMessageSize(systemMsg);
+    originalSize += size;
+    compressedSize += size;
+  }
+
+  // Keep last N user/assistant turns (sliding window)
+  const WINDOW_SIZE = 5;
+  const recentTurns = messages
+    .filter(m => m.role === 'user' || m.role === 'assistant')
+    .slice(-WINDOW_SIZE);
+
+  for (const msg of recentTurns) {
+    const original = estimateMessageSize(msg);
+    originalSize += original;
+
+    // Compress tool_result blocks (biggest token consumers)
+    if (Array.isArray(msg.content)) {
+      const compressedContent = msg.content.map(block => {
+        if (block?.type === 'tool_result') {
+          toolResultsOffloaded++;
+          // Keep only metadata, offload actual content
+          return {
+            type: 'tool_result',
+            tool_use_id: block.tool_use_id,
+            content: '[offloaded]', // Replaced with placeholder
+            _compressed: true,
+          };
+        }
+        return block;
+      });
+
+      const compressedMsg = { ...msg, content: compressedContent };
+      compressed.push(compressedMsg);
+      compressedSize += estimateMessageSize(compressedMsg);
+      messagesKept++;
+    } else {
+      // No compression needed for string content
+      compressed.push(msg);
+      compressedSize += original;
+      messagesKept++;
+    }
+  }
+
+  const ratio = originalSize > 0 ? compressedSize / originalSize : 1.0;
+
+  const stats = {
+    original: originalSize,
+    compressed: compressedSize,
+    ratio,
+    reduction: Math.round((1 - ratio) * 100),
+    toolResultsOffloaded,
+    messagesKept,
+    messagesDropped: messages.length - messagesKept - (systemMsg ? 1 : 0),
+  };
+
+  logger.debug({
+    ...stats,
+    originalMsgs: messages.length,
+    compressedMsgs: compressed.length,
+  }, '[context-compressor] Compression complete');
+
+  return { compressed, stats };
+}
+
+/**
+ * Estimate message size in tokens (rough heuristic: chars / 4)
+ */
+function estimateMessageSize(msg) {
+  if (!msg) return 0;
+
+  let size = 0;
+
+  // Role + metadata overhead
+  size += 10;
+
+  // Content
+  if (typeof msg.content === 'string') {
+    size += Math.ceil(msg.content.length / 4);
+  } else if (Array.isArray(msg.content)) {
+    for (const block of msg.content) {
+      if (block?.type === 'text' && block.text) {
+        size += Math.ceil(block.text.length / 4);
+      } else if (block?.type === 'tool_result') {
+        // Tool results are verbose (code, logs, errors)
+        const content = Array.isArray(block.content)
+          ? block.content.map(c => c?.text || '').join('')
+          : (block.content || '');
+        size += Math.ceil(content.length / 4);
+      } else if (block?.type === 'tool_use') {
+        // Tool use is compact (function name + args)
+        size += 50;
+      }
+    }
+  }
+
+  return size;
+}
+
+/**
+ * Check if compression is beneficial for this payload.
+ * Only compress if conversation is long enough to matter.
+ */
+function shouldCompress(payload) {
+  if (!payload?.messages || !Array.isArray(payload.messages)) {
+    return false;
+  }
+
+  const msgCount = payload.messages.length;
+
+  // Count total tool_result blocks (not just messages with tool results)
+  let toolResultCount = 0;
+  for (const msg of payload.messages) {
+    if (Array.isArray(msg.content)) {
+      toolResultCount += msg.content.filter(c => c?.type === 'tool_result').length;
+    }
+  }
+
+  // Compress if:
+  // 1. More than 10 messages (long conversation), OR
+  // 2. More than 3 tool_result blocks (verbose outputs)
+  return msgCount > 10 || toolResultCount > 3;
+}
+
+module.exports = {
+  compressMessages,
+  shouldCompress,
+  estimateMessageSize,
+};