lynkr 9.14.2 → 9.14.7

package/src/routing/index.js

@@ -29,6 +29,7 @@ const { scoreIntent, intentScoreMode } = require('./intent-score');
 // Phase 3-6 routing modules
 const { getKnnRouter } = require('./knn-router');
 const { getBandit } = require('./bandit');
+const { buildCandidates, buildContextVector, decide, stampPropensity } = require('./decide');
 const { getShadowPolicy, compareAndLog: shadowCompareAndLog } = require('./shadow-mode');
 const { chooseFastest } = require('./deadline');
 const { applyTenantOverrides } = require('./tenant-policy');
@@ -391,6 +392,11 @@ function _pinToDecision(pin, { reason, risk }) {
 async function determineProviderSmart(payload, options = {}) {
   const pinCheck = checkSessionPin(payload, options);
 
+  // Thread the session identity into fresh routing without mutating the
+  // caller's options object. Used by the de-escalation holdout so a session
+  // deterministically lands on one side of the holdout on every turn.
+  options = pinCheck.sessionId ? { ...options, _sessionId: pinCheck.sessionId } : options;
+
   // Bypass (no session / forceProvider / feature-off) or no pin yet →
   // straight to fresh routing, then persist the outcome for the next turn.
   if (pinCheck.reason === 'bypass' || pinCheck.reason === 'no_pin') {
@@ -680,6 +686,27 @@ function checkSessionPin(payload, options = {}) {
   const refreshOk = Array.isArray(payload?.tools) && payload.tools.length > 0;
 
   if (sessionAffinity.payloadHasToolHistory(payload)) {
+    // Stuck-loop detection: the pinned model re-issuing the same tool call
+    // (or the same text) over and over. Switching mid-exchange is forbidden
+    // (tool-call IDs aren't provider-portable), so the intervention is the
+    // same safe pattern as the embedded-text triggers below — serve the pin
+    // this turn but DROP it, so the next turn boundary re-routes fresh.
+    try {
+      const { detectStuckLoop } = require('./stuck-detector');
+      const stuck = detectStuckLoop(payload);
+      if (stuck.stuck) {
+        sessionAffinity.removePin(sessionId);
+        logger.warn({
+          sessionId,
+          trigger: stuck.reason,
+          repeats: stuck.repeats,
+          signature: stuck.signature,
+          pinnedTier: pin.tier,
+          pinnedModel: pin.model,
+        }, '[Routing] Stuck loop detected — pin dropped, next boundary re-routes fresh');
+        return { serve: true, pin, reason: 'tool_history_pin_dropped', sessionId };
+      }
+    } catch { /* never block the pin-serve path */ }
     // Text typed during a tool loop arrives merged with the pending
     // tool_result, where the pin serves unconditionally (id linkage forbids
     // switching mid-exchange). If that embedded text trips a trigger, drop
@@ -705,6 +732,32 @@ function checkSessionPin(payload, options = {}) {
         }
       }
     } catch { /* never block the pin-serve path */ }
+    // Context-overflow escape hatch. Every frame of a tool loop is an
+    // unconditional pin serve, so a long agentic session could NEVER escape
+    // to a larger-context model — the guards that check context fit only run
+    // on non-tool turns, which a busy agent may not produce for hours (live
+    // incident: an 884k-token session stayed pinned to a 128k model for 43
+    // straight requests, with 93.7% of history amputated on every one).
+    // Same safe pattern as the triggers above: serve the pin THIS turn
+    // (tool-call IDs aren't provider-portable), drop it so the next boundary
+    // re-routes — and fresh routing's context guard picks a model that fits.
+    try {
+      if (pin.model) {
+        const promptTokensEst = countPayloadTokens(payload, pin.model);
+        const ctxResult = contextValidator.validate(pin.model, promptTokensEst);
+        if (!ctxResult.ok) {
+          sessionAffinity.removePin(sessionId);
+          logger.warn({
+            sessionId,
+            trigger: 'context_overflow',
+            pinnedModel: pin.model,
+            pinnedTier: pin.tier,
+            promptTokensEst,
+          }, '[Routing] Session outgrew pinned model\'s context window — pin dropped, next boundary re-routes to a context-capable model');
+          return { serve: true, pin, reason: 'tool_history_pin_dropped', sessionId };
+        }
+      }
+    } catch { /* never block the pin-serve path */ }
     if (refreshOk) {
       sessionAffinity.setPin(sessionId, pin, {
         // Monotonic within a pin's lifetime: refreshes must never SHRINK the
@@ -1177,6 +1230,91 @@ async function _determineProviderSmartInner(payload, options = {}) {
   selectedModel = modelSelection.model;
   logger.debug({ tier, provider, model: selectedModel }, '[Routing] Using tier config');
 
+  // Item 1 — capability-decoupled shortfall matching (HyDRA port).
+  // Shadow-computes whenever possible (weighted mode only); serves only when
+  // config/model-capabilities.json has enabled:true. Never overrides risk-high (returned earlier
+  // upstream), static mode (tier null), or legacy scorer mode. Downstream
+  // guards (de-escalation, context, vision, kNN, bandit, deadline, tenant)
+  // still run after and dominate — shortfall only replaces the tier_config pick.
+  let shortfallInfo = null;
+  try {
+    if (tier && config.modelTiers?.enabled && risk?.level !== 'high'
+      && analysis?.mode === 'weighted' && analysis?.breakdown) {
+      const { buildRequirementVector } = require('./capabilities');
+      const sf = require('./shortfall');
+      const req = buildRequirementVector({ dimensions: analysis.breakdown, agenticResult });
+      // Candidates constrained to the user's TIER_* (same eligibility rule
+      // as the bandit in decide.js) with tier labels attached for capability
+      // resolution. Dedupe identical provider:model keeping the highest tier.
+      const seen = new Map();
+      for (const t of ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING']) {
+        for (const m of selector.getModelsForTier(t)) {
+          const key = `${m.provider}:${m.model}`;
+          const prev = seen.get(key);
+          if (!prev || (TIER_DEFINITIONS[t]?.priority || 0) > (TIER_DEFINITIONS[prev.tier]?.priority || 0)) {
+            seen.set(key, { provider: m.provider, model: m.model, tier: t });
+          }
+        }
+      }
+      let registry = null;
+      try { registry = require('./model-registry').getModelRegistrySync(); } catch { registry = null; }
+      let optimizer = null;
+      try { optimizer = require('./cost-optimizer').getCostOptimizer(); } catch { optimizer = null; }
+      const candidates = [...seen.values()].map((c) => {
+        let cost = Number.POSITIVE_INFINITY; // unknown price never wins on cheapness
+        try {
+          const info = registry?.getCost?.(c.model);
+          if (info && !info.unknown) {
+            const est = optimizer?.estimateCost?.(c.model, 1000);
+            cost = Number.isFinite(est?.totalEstimate)
+              ? est.totalEstimate
+              : (Number(info.input) || 0) + (Number(info.output) || 0);
+          }
+        } catch { /* keep Infinity */ }
+        return { ...c, cost };
+      });
+      const result = sf.selectByShortfall(req, candidates);
+      if (result) {
+        const agreed = result.selected.provider === provider && result.selected.model === selectedModel;
+        shortfallInfo = {
+          req,
+          tau: result.tau,
+          selected: result.selected,
+          agreed,
+          legacy: { provider, model: selectedModel, tier },
+        };
+        logger.debug({
+          req,
+          tau: result.tau,
+          legacy: `${tier}:${provider}:${selectedModel}`,
+          shortfall: `${result.selected.tier}:${result.selected.provider}:${result.selected.model}`,
+          agreed,
+        }, '[Routing] Shortfall shadow compare');
+        if (sf.isEnabled() && !agreed) {
+          const fromTier = tier;
+          const fromModel = selectedModel;
+          provider = result.selected.provider;
+          selectedModel = result.selected.model;
+          tier = result.selected.tier;
+          analysis.tier = tier;
+          method = method + '+shortfall';
+          if ((TIER_DEFINITIONS[tier]?.priority || 0) > (TIER_DEFINITIONS[fromTier]?.priority || 0)) {
+            escalations.push({
+              source: 'shortfall',
+              fromTier,
+              toTier: tier,
+              fromModel,
+              toModel: selectedModel,
+            });
+          }
+          logger.info({ from: `${fromTier}:${fromModel}`, to: `${tier}:${selectedModel}` }, '[Routing] Shortfall override');
+        }
+      }
+    }
+  } catch (err) {
+    degradation.record('shortfall', err);
+  }
+
   // WS2.3 — evidence-based de-escalation.
   //
   // The check is intentionally gated by evidence, not a feature flag: the
@@ -1200,17 +1338,31 @@ async function _determineProviderSmartInner(payload, options = {}) {
         analysis,
       });
       if (demoted && demoted !== tier) {
-        const demotedSelection = selector.selectModel(demoted, null);
-        logger.debug({
-          from: `${tier}:${provider}:${selectedModel}`,
-          to: `${demoted}:${demotedSelection.provider}:${demotedSelection.model}`,
-          requestType,
-        }, '[Routing] De-escalation — demoting tier on evidence');
-        demotedFrom = tier;
-        provider = demotedSelection.provider;
-        selectedModel = demotedSelection.model;
-        tier = demoted;
-        method = method + '+deescalated';
+        // Percentage holdout (LYNKR_DEESCALATION_HOLDOUT_PCT, default 10):
+        // a deterministic slice of sessions is served at the original tier
+        // even though the evidence supports demotion. Their telemetry rows
+        // (method '+deescalation_holdout') are the running baseline that
+        // proves demoted sessions aren't quietly doing worse.
+        if (deescalator.isHeldOut(options._sessionId)) {
+          method = method + '+deescalation_holdout';
+          logger.debug({
+            tier,
+            wouldDemoteTo: demoted,
+            requestType,
+          }, '[Routing] De-escalation — evidence supports demotion, session held out as baseline');
+        } else {
+          const demotedSelection = selector.selectModel(demoted, null);
+          logger.debug({
+            from: `${tier}:${provider}:${selectedModel}`,
+            to: `${demoted}:${demotedSelection.provider}:${demotedSelection.model}`,
+            requestType,
+          }, '[Routing] De-escalation — demoting tier on evidence');
+          demotedFrom = tier;
+          provider = demotedSelection.provider;
+          selectedModel = demotedSelection.model;
+          tier = demoted;
+          method = method + '+deescalated';
+        }
       }
     } catch (err) {
       degradation.record('tier_select', err);
@@ -1441,65 +1593,29 @@ async function _determineProviderSmartInner(payload, options = {}) {
   // WS4.2 — capture propensity + candidates + context so the outcome row can
   // support off-policy evaluation. banditContext is stashed on the decision
   // (underscored → won't leak through headers, see WS4.2 verification).
-  let banditPropensity = null;
-  let banditCandidates = null;
-  let banditContext = null;
+  //
+  // The candidate-building / context-vector / pick logic lives in decide.js
+  // so the off-policy evaluator can replay it against logged rows.
+  let banditResult = null;
   if (config.routing?.banditEnabled !== false && knnResult && knnResult.model) {
     try {
-      // Build candidates: current selection and kNN alternative if different.
-      //
-      // Tier-aware filter: only treat the kNN suggestion as a real candidate
-      // if it matches a (provider, model) combo configured in ANY TIER_*
-      // entry. The bandit is allowed to explore freely across the user's
-      // configured tiers (e.g. swap a SIMPLE request to the COMPLEX-tier
-      // model), but is forbidden from picking a credentialed-but-untiered
-      // model (e.g. an Azure OpenAI deployment whose endpoint is set in .env
-      // for some other use, but not referenced by any TIER_*). This keeps
-      // tier routing as the source of truth for what's eligible while
-      // preserving cross-tier bandit exploration.
-      const allCandidates = [{ provider, model: selectedModel }];
-      if (knnResult.model !== selectedModel) {
-        const configured = require('./model-tiers').getModelTierSelector().getAllConfiguredModels();
-        const inConfig = configured.some(
-          m => m.provider === knnResult.provider && m.model === knnResult.model
-        );
-        if (inConfig) {
-          allCandidates.push({ provider: knnResult.provider, model: knnResult.model });
-        }
-      }
-
-      if (allCandidates.length > 1) {
-        const bandit = getBandit();
-        const TASK_TYPES = ['code_gen', 'summarization', 'reasoning', 'factoid', 'chat', 'other'];
-        const inferredTask = (analysis.breakdown?.taskType?.reason || 'other').toLowerCase();
-        const taskIdx = Math.max(0, TASK_TYPES.findIndex(t => inferredTask.includes(t)));
-        const ctx = [
-          (analysis.score || 0) / 100,
-          Math.log(Math.max(1, analysis.breakdown?.tokenCount || 0) + 1) / 15,
-          ((payload?.tools?.length ?? 0) > 0) ? 1 : 0,
-          options.streaming ? 1 : 0,
-          risk?.level === 'high' ? 1 : risk?.level === 'medium' ? 0.5 : 0,
-          agenticResult?.isAgentic ? 1 : 0,
-          ...TASK_TYPES.map((_, i) => i === taskIdx ? 1 : 0),
-        ];
-        const picked = bandit.pick(tier, allCandidates, ctx);
-        if (picked) {
-          banditCandidates = allCandidates;
-          banditPropensity = picked.propensity ?? null;
-          banditContext = ctx;
-          if (picked.model !== selectedModel) {
-            logger.debug({
-              from: `${provider}:${selectedModel}`,
-              to: `${picked.provider}:${picked.model}`,
-              ucb: picked.ucb?.toFixed(4),
-              explored: picked.explored,
-              propensity: picked.propensity,
-            }, '[Routing] Bandit override');
-            provider = picked.provider;
-            selectedModel = picked.model;
-            method = method + (picked.explored ? '+bandit_explore' : '+bandit');
-          }
-        }
+      const allCandidates = buildCandidates(
+        { provider, model: selectedModel },
+        { provider: knnResult.provider, model: knnResult.model },
+      );
+      const ctx = buildContextVector({ analysis, payload, options, risk, agenticResult });
+      banditResult = decide(tier, allCandidates, ctx);
+      if (banditResult && banditResult.model !== selectedModel) {
+        logger.debug({
+          from: `${provider}:${selectedModel}`,
+          to: `${banditResult.provider}:${banditResult.model}`,
+          ucb: banditResult.ucb?.toFixed(4),
+          explored: banditResult.explored,
+          propensity: banditResult.propensity,
+        }, '[Routing] Bandit override');
+        provider = banditResult.provider;
+        selectedModel = banditResult.model;
+        method = method + (banditResult.explored ? '+bandit_explore' : '+bandit');
       }
     } catch (err) {
       degradation.record('bandit', err);
@@ -1568,6 +1684,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
     knnResult,
     base_tier: baseTier,
     escalations,
+    shortfall: shortfallInfo,
     // Upward escalations take precedence in the source label; a demotion is
     // only surfaced when nothing else escalated (guarded by the wire above,
     // but re-checked here for clarity).
@@ -1577,24 +1694,13 @@ async function _determineProviderSmartInner(payload, options = {}) {
   });
 
   // WS4.2 — propensity/candidates for off-policy evaluation from telemetry.
-  // Bandit picks populate both. If a deterministic downstream override
-  // (deadline / tenant) then swapped the served model out of the bandit's
-  // candidate set, the bandit's propensity no longer describes the served
-  // choice — collapse to propensity=1.0 with a single candidate. Otherwise
-  // deterministic branches (bandit didn't run at all) always collapse.
-  // _banditContext is underscored so it never leaks to response headers;
-  // WS5 will consume it in the feedback path to call bandit.update().
-  const banditPickedServed = banditCandidates
-    && banditCandidates.some(c => c.provider === provider && c.model === selectedModel);
-  if (banditPickedServed) {
-    decision.propensity = banditPropensity ?? 1.0;
-    decision.candidates = banditCandidates;
-    decision._banditContext = banditContext;
-  } else {
-    decision.propensity = 1.0;
-    decision.candidates = [{ provider, model: selectedModel }];
-    decision._banditContext = null;
-  }
+  // Collapse rule lives in decide.js (stampPropensity): if a deterministic
+  // downstream override (deadline / tenant) swapped the served model out of
+  // the bandit's candidate set — or the bandit never ran — the row collapses
+  // to propensity=1.0 with a single candidate. _banditContext is underscored
+  // so it never leaks to response headers; the feedback path consumes it to
+  // call bandit.update().
+  stampPropensity(decision, { provider, model: selectedModel }, banditResult);
 
   // WS5.5 — attach the query embedding + raw query text so the feedback
   // path can turn conclusive outcomes into new kNN exemplars without
@@ -1658,6 +1764,16 @@ function getRoutingHeaders(decision) {
 
   if (decision.model) {
     headers['X-Lynkr-Model'] = decision.model;
+    // Served-model context window (workweave pattern): the client can't know
+    // the real window behind a virtual model name when tier routing serves
+    // different models per request — this header is the authoritative per-
+    // turn answer, intended as the client's compaction budget. Omitted (never
+    // guessed) when the registry doesn't know the model.
+    const { contextWindowFor } = require('./model-registry');
+    const contextWindow = contextWindowFor(decision.model);
+    if (contextWindow) {
+      headers['X-Lynkr-Context-Window'] = String(contextWindow);
+    }
   }
 
   if (decision.agenticResult?.isAgentic) {

package/src/routing/model-registry.js

@@ -537,10 +537,35 @@ function getModelRegistrySync() {
   return instance;
 }
 
+/**
+ * Real context window (tokens) for a model, or null when unknown.
+ *
+ * Null on unknown is deliberate: consumers surface this to CLIENTS (the
+ * X-Lynkr-Context-Window response header that harnesses may use as their
+ * compaction budget), and advertising a guessed window is worse than
+ * advertising none — a client that compacts against a fabricated number
+ * either wastes context or overruns the real window.
+ *
+ * @param {string} modelName
+ * @returns {number|null}
+ */
+function contextWindowFor(modelName) {
+  if (!modelName) return null;
+  try {
+    const registry = getModelRegistrySync();
+    const info = registry?.getCost?.(modelName);
+    if (!info || info.unknown) return null;
+    return Number.isFinite(info.context) && info.context > 0 ? info.context : null;
+  } catch {
+    return null;
+  }
+}
+
 module.exports = {
   ModelRegistry,
   getModelRegistry,
   getModelRegistrySync,
   DATABRICKS_FALLBACK,
   DEFAULT_COST,
+  contextWindowFor,
 };

package/src/routing/model-slots.js

@@ -0,0 +1,65 @@
+/**
+ * Model id → tier mapping for Claude Desktop's model picker.
+ *
+ * Claude Desktop VALIDATES model ids against a fixed set — arbitrary ids
+ * (e.g. "lynkr-simple") make it show "model list hasn't loaded". These five
+ * slots mirror ollama's internal/proxy/claude_desktop_models.go, the ids
+ * Desktop currently accepts.
+ *
+ * Shared by:
+ *   - src/api/claude-desktop-gateway.js — advertises these as the Anthropic-
+ *     format model list Desktop's picker renders.
+ *   - src/api/router.js — resolves an incoming request's `model` field back
+ *     to a tier, so an explicit pick in Desktop's dropdown pins routing
+ *     instead of only being advisory.
+ *
+ * @module routing/model-slots
+ */
+
+const MODEL_SLOTS = [
+  { id: "claude-fable-5", family: "fable", createdAt: "2026-06-09T00:00:00Z", isDefault: true, tier: null, label: "Lynkr Auto (tier routing)" },
+  { id: "claude-opus-5", family: "opus", createdAt: "2026-07-24T00:00:00Z", isDefault: true, tier: "REASONING" },
+  { id: "claude-sonnet-5", family: "sonnet", createdAt: "2026-06-30T00:00:00Z", isDefault: true, tier: "COMPLEX" },
+  { id: "claude-sonnet-4-6", family: "sonnet", createdAt: "2025-11-18T00:00:00Z", isDefault: false, tier: "MEDIUM" },
+  { id: "claude-haiku-4-5-20251001", family: "haiku", createdAt: "2025-10-01T00:00:00Z", isDefault: true, tier: "SIMPLE" },
+];
+
+/**
+ * Protocol-agnostic virtual tier ids. Unlike MODEL_SLOTS (whose ids must be
+ * real Claude names because Claude Desktop validates its picker against a
+ * fixed set), these are for clients whose model list Lynkr fully controls —
+ * e.g. the opencode provider entry written by `lynkr opencode`. Each id pins
+ * its tier explicitly, which also lets the client carry an HONEST per-tier
+ * context window in its own config (the tier's configured model is knowable
+ * at setup time), so client-side compaction budgets match the real serving
+ * model instead of one blended guess.
+ *
+ * "lynkr-auto" = no pin (full content-based tier routing).
+ */
+const VIRTUAL_TIER_IDS = {
+  'lynkr-auto': null,
+  'lynkr-simple': 'SIMPLE',
+  'lynkr-medium': 'MEDIUM',
+  'lynkr-complex': 'COMPLEX',
+  'lynkr-reasoning': 'REASONING',
+};
+
+/**
+ * Resolve a client-supplied model id to the tier it pins.
+ *
+ * @param {string} modelId
+ * @returns {string|null} one of SIMPLE/MEDIUM/COMPLEX/REASONING, or null if
+ *   the id is unrecognized or maps to "Auto" (no pin — caller should fall
+ *   through to content-based scoring).
+ */
+function resolveTierForModelId(modelId) {
+  if (!modelId) return null;
+  const normalized = String(modelId).toLowerCase();
+  if (Object.prototype.hasOwnProperty.call(VIRTUAL_TIER_IDS, normalized)) {
+    return VIRTUAL_TIER_IDS[normalized];
+  }
+  const slot = MODEL_SLOTS.find((s) => s.id === modelId);
+  return slot?.tier || null;
+}
+
+module.exports = { MODEL_SLOTS, VIRTUAL_TIER_IDS, resolveTierForModelId };

package/src/routing/model-tiers.js

@@ -353,6 +353,8 @@ class ModelTierSelector {
         return config.moonshot?.model || null;
       case 'baidu':
         return config.baidu?.model || null;
+      case 'fireworks':
+        return config.fireworks?.model || null;
       case 'codex':
         return config.codex?.model || null;
       case 'vertex':