lynkr 9.14.1 → 9.14.3

package/src/orchestrator/sse-transformer.js

@@ -28,6 +28,14 @@ const logger = require("../logger");
 // stream:false predated this transformer). Caveat: reasoning_content deltas
 // (kimi thinking) are not reshaped — thinking text is dropped from streamed
 // responses; the buffered path still lifts it into thinking blocks.
+// baidu (Qianfan's /v2/chat/completions) already returns the raw stream the
+// same way moonshot does (invokeBaidu's `if (response?.stream) return
+// response;`) and its endpoint is documented as OpenAI-compatible — but
+// unlike moonshot this hasn't been E2E-verified against a live key as of
+// this addition. If Qianfan's SSE deltas turn out not to match
+// choices[0].delta exactly, remove it from this list (or set
+// LYNKR_STREAM_TRANSFORM_PROVIDERS to exclude it) rather than patching the
+// shared transformer for one provider's quirk.
 const DEFAULT_OPENAI_SSE_PROVIDERS = [
   "openai",
   "atlas",
@@ -37,12 +45,36 @@ const DEFAULT_OPENAI_SSE_PROVIDERS = [
   "lmstudio",
   "llamacpp",
   "moonshot",
+  "baidu",
+  // fireworks (api.fireworks.ai/inference/v1/chat/completions) is documented
+  // as OpenAI-compatible SSE — same baidu caveat applies: E2E-unverified
+  // against a live key as of this addition. If its deltas turn out not to
+  // match choices[0].delta exactly, remove it from this list rather than
+  // patching the shared transformer for one provider's quirk.
+  "fireworks",
 ];
 
+// llama.cpp specific: reasoning-capable local builds (live-confirmed on this
+// deployment's GPT-OSS model) emit `delta.reasoning_content` before any
+// `delta.content`. This transformer only reads delta.content (see the
+// per-chunk loop below) — reasoning deltas are silently dropped, so a client
+// streaming through this path sees nothing at all during the thinking phase
+// and, if reasoning consumes the whole max_tokens budget, nothing ever.
+// Default OFF (buffered instead) for exactly the same reason Ollama already
+// defaults to buffering (LYNKR_OLLAMA_BUFFER_RESPONSES) — the buffered path's
+// convertOpenRouterResponseToAnthropic already lifts reasoning_content into a
+// proper `thinking` block, so no data is lost there. Opt into live streaming
+// (and accept dropped thinking text) via LYNKR_LLAMACPP_BUFFER_RESPONSES=false.
 function _transformProviders() {
   const env = process.env.LYNKR_STREAM_TRANSFORM_PROVIDERS;
+  if (env) {
+    return new Set(env.split(",").map((s) => s.trim()).filter(Boolean));
+  }
+  const bufferLlamacpp = process.env.LYNKR_LLAMACPP_BUFFER_RESPONSES !== "false";
   return new Set(
-    env ? env.split(",").map((s) => s.trim()).filter(Boolean) : DEFAULT_OPENAI_SSE_PROVIDERS,
+    bufferLlamacpp
+      ? DEFAULT_OPENAI_SSE_PROVIDERS.filter((p) => p !== "llamacpp")
+      : DEFAULT_OPENAI_SSE_PROVIDERS,
   );
 }
 
@@ -158,7 +190,62 @@ async function* _openaiToAnthropicEvents(upstream, opts = {}) {
     }
   };
 
+  // GLM-family reasoning leak filter (streaming twin of the fix in
+  // convertOpenAIToAnthropic): suppresses matched <think>…</think> spans and
+  // strips a bare orphan closing tag from visible text deltas, holding back
+  // trailing partial-tag fragments so tags split across chunk boundaries
+  // still match. Orphan pre-text has already been emitted by the time the
+  // closer arrives — a stream can't retract — so only the tag is removed.
+  let _inThink = false;
+  let _tagTail = "";
+  const _partialTagLen = (s) => {
+    for (let k = Math.min(8, s.length); k > 0; k--) {
+      const suf = s.slice(-k);
+      if ("</think>".startsWith(suf) || "<think>".startsWith(suf)) return k;
+    }
+    return 0;
+  };
+  const filterThink = (text) => {
+    let s = _tagTail + text;
+    _tagTail = "";
+    let out = "";
+    for (;;) {
+      if (_inThink) {
+        const close = s.indexOf("</think>");
+        if (close === -1) break; // still inside thinking — discard s (tail kept below)
+        s = s.slice(close + 8);
+        _inThink = false;
+      } else {
+        const open = s.indexOf("<think>");
+        const close = s.indexOf("</think>");
+        if (close !== -1 && (open === -1 || close < open)) {
+          out += s.slice(0, close); // orphan closer: drop the tag only
+          s = s.slice(close + 8);
+        } else if (open !== -1) {
+          out += s.slice(0, open);
+          s = s.slice(open + 7);
+          _inThink = true;
+        } else {
+          break;
+        }
+      }
+    }
+    const keep = _partialTagLen(s);
+    if (keep > 0) _tagTail = s.slice(-keep);
+    if (!_inThink && s.length > keep) out += s.slice(0, s.length - keep);
+    return out;
+  };
+
   const closeTextBlock = function* () {
+    // Flush a held-back fragment that turned out not to be a tag.
+    if (_tagTail && !_inThink && textIndex !== null) {
+      yield _sse("content_block_delta", {
+        type: "content_block_delta",
+        index: textIndex,
+        delta: { type: "text_delta", text: _tagTail },
+      });
+      _tagTail = "";
+    }
     if (textIndex === null) return;
     yield _sse("content_block_stop", { type: "content_block_stop", index: textIndex });
     textIndex = null;
@@ -205,6 +292,8 @@ async function* _openaiToAnthropicEvents(upstream, opts = {}) {
       if (chunk.usage) {
         if (chunk.usage.prompt_tokens != null) stats.usage.input_tokens = chunk.usage.prompt_tokens;
         if (chunk.usage.completion_tokens != null) stats.usage.output_tokens = chunk.usage.completion_tokens;
+        const cached = chunk.usage.prompt_tokens_details?.cached_tokens;
+        if (cached != null) stats.usage.cache_read_input_tokens = cached;
       }
 
       const choice = chunk.choices?.[0];
@@ -217,19 +306,22 @@ async function* _openaiToAnthropicEvents(upstream, opts = {}) {
       // Text deltas are straightforward: open a block on first text, then
       // emit a text_delta per chunk.
       if (typeof delta.content === "string" && delta.content.length > 0) {
-        if (textIndex === null) {
-          textIndex = nextIndex++;
-          yield _sse("content_block_start", {
-            type: "content_block_start",
+        const visible = filterThink(delta.content);
+        if (visible.length > 0) {
+          if (textIndex === null) {
+            textIndex = nextIndex++;
+            yield _sse("content_block_start", {
+              type: "content_block_start",
+              index: textIndex,
+              content_block: { type: "text", text: "" },
+            });
+          }
+          yield _sse("content_block_delta", {
+            type: "content_block_delta",
             index: textIndex,
-            content_block: { type: "text", text: "" },
+            delta: { type: "text_delta", text: visible },
           });
         }
-        yield _sse("content_block_delta", {
-          type: "content_block_delta",
-          index: textIndex,
-          delta: { type: "text_delta", text: delta.content },
-        });
       }
 
       // Tool-call fragments: accumulate per OpenAI tool index. Fragments of
@@ -276,7 +368,11 @@ async function* _openaiToAnthropicEvents(upstream, opts = {}) {
   // argument JSON may be truncated mid-string.
   if (!finishReason) {
     logger.warn(
-      { droppedToolFragments: toolAcc.size, outputTokens: stats.usage.output_tokens },
+      {
+        droppedToolFragments: toolAcc.size,
+        inputTokens: stats.usage.input_tokens,
+        outputTokens: stats.usage.output_tokens,
+      },
       "[SSETransform] Upstream ended without finish_reason — signaling stream error"
     );
     yield _sse("error", {
@@ -294,10 +390,26 @@ async function* _openaiToAnthropicEvents(upstream, opts = {}) {
   const stopReason = _mapFinishReason(finishReason);
   stats.stopReason = stopReason;
   stats.finishReason = finishReason;
+  // Usage ordering problem, solved here: the Anthropic protocol reports
+  // input_tokens in message_start, but OpenAI-shaped upstreams (Azure
+  // Responses API especially) only deliver usage at END of stream — so our
+  // message_start necessarily went out with input_tokens: 0. Emit the real
+  // cumulative usage in the final message_delta instead: Anthropic's own
+  // newer streams carry input_tokens/cache fields here, and SDK clients
+  // (incl. opencode's @ai-sdk/anthropic) merge message_delta usage over
+  // message_start. Without this, clients see only output tokens (~tens) and
+  // render nonsense like "Context: 64 tokens, 0% used" for a 60k-token
+  // prompt — and misprice every turn.
   yield _sse("message_delta", {
     type: "message_delta",
     delta: { stop_reason: stopReason, stop_sequence: null },
-    usage: { output_tokens: stats.usage.output_tokens ?? 0 },
+    usage: {
+      output_tokens: stats.usage.output_tokens ?? 0,
+      ...(stats.usage.input_tokens != null ? { input_tokens: stats.usage.input_tokens } : {}),
+      ...(stats.usage.cache_read_input_tokens != null
+        ? { cache_read_input_tokens: stats.usage.cache_read_input_tokens }
+        : {}),
+    },
   });
   yield _sse("message_stop", { type: "message_stop" });
 
@@ -439,4 +551,9 @@ module.exports = {
   // Exported for unit tests.
   _openaiToAnthropicEvents,
   _anthropicToOpenaiEvents,
+  // Exported for reuse by other SSE adapters (e.g. azure-responses-sse.js) —
+  // generic, provider-agnostic SSE byte-stream parsing with no OpenAI-specific
+  // behavior, worth sharing rather than reimplementing per adapter.
+  _iterateStream,
+  _sseDataLines,
 };

package/src/policy/safe-commands.js

@@ -1,4 +1,3 @@
-const logger = require("../logger");
 const config = require("../config");
 
 /**

package/src/routing/bandit.js

@@ -187,6 +187,45 @@ class LinUCBBandit {
     return best;
   }
 
+  /**
+   * Mean reward estimate for one arm in one context — θ·x with NO
+   * uncertainty bonus. This is the regression model r̂(x, a) the
+   * doubly-robust off-policy estimator consumes (routing/ope.js): the same
+   * ridge-regression state the live policy learns from, reused as the
+   * DR baseline instead of training a second model.
+   *
+   * Returns null when the arm has never been observed (identity-prior-only
+   * arms predict 0 by construction, which would bias DR toward "never
+   * tried" — better to let the estimator fall back to the IPS-only term).
+   *
+   * @param {string} tier
+   * @param {string} provider
+   * @param {string} model
+   * @param {number[]} context
+   * @returns {number|null} estimated reward in [0, 1], or null if unknown arm
+   */
+  estimateReward(tier, provider, model, context) {
+    const key = this._armKey(tier, provider, model);
+    const arm = this.arms.get(key);
+    if (!arm || arm.count === 0) return null;
+    let ctx = context;
+    if (ctx.length !== this.dim) {
+      ctx = ctx.slice(0, this.dim);
+      while (ctx.length < this.dim) ctx.push(0);
+    }
+    let Ainv;
+    try {
+      Ainv = _inv(arm.A);
+    } catch {
+      return null;
+    }
+    const theta = _matVec(Ainv, arm.b);
+    const mean = _dot(theta, ctx);
+    // Rewards are trained in [0, 1]; clamp the linear extrapolation so a
+    // wild θ·x can't dominate the DR correction term.
+    return Math.max(0, Math.min(1, mean));
+  }
+
   /**
    * Update the chosen arm with the observed reward.
    * @param {string} tier

package/src/routing/calibration.js

@@ -19,6 +19,8 @@ const path = require('path');
 
 const DEFAULT_DAYS = 7;
 const MIN_SAMPLES = 100;
+/** Narrower than this and a calibrated band is treated as collapse, not signal. */
+const MIN_TIER_WIDTH = 10;
 
 /** Quality score below which a complexity bucket is "underperforming" for its tier. */
 const QUALITY_FLOOR = {
@@ -188,7 +190,24 @@ function runCalibration({ days = DEFAULT_DAYS, dryRun = false, dbPath, outputPat
     const prev = ranges[tierOrder[i - 1]];
     const cur = ranges[tierOrder[i]];
     if (cur[0] !== prev[1] + 1) cur[0] = prev[1] + 1;
-    if (cur[0] > cur[1]) cur[1] = cur[0]; // collapsed; tier disabled in practice
+    if (cur[0] > cur[1]) cur[1] = cur[0]; // collapsed; see guardrail below
+  }
+
+  // Guardrail: a tier squeezed under MIN_TIER_WIDTH means calibration had
+  // degenerate signal, not a real finding — e.g. 2026-07-26 (MEDIUM →
+  // [20,20]) and 2026-08-22 (COMPLEX → [51,54], which re-stitched
+  // REASONING's floor down to 55 and sent ~all agentic traffic to the most
+  // expensive tier; skewed telemetry then re-taught the same bands every
+  // 24h). Collapsed bands revert the whole set to DEFAULT_RANGES — bands
+  // are interdependent after stitching, so partial reverts would leave
+  // gaps.
+  const collapsed = tierOrder.filter(
+    (t) => ranges[t][1] - ranges[t][0] < MIN_TIER_WIDTH
+  );
+  let guardrail = null;
+  if (collapsed.length > 0) {
+    guardrail = { reverted: true, reason: 'band_collapse', collapsed };
+    for (const t of tierOrder) ranges[t] = [...DEFAULT_RANGES[t]];
   }
 
   const out = {
@@ -197,6 +216,7 @@ function runCalibration({ days = DEFAULT_DAYS, dryRun = false, dbPath, outputPat
     sampleCount: rows.length,
     ranges,
     stats,
+    ...(guardrail ? { guardrail } : {}),
   };
 
   if (dryRun) return { ...out, dryRun: true };

package/src/routing/capabilities.js

@@ -0,0 +1,88 @@
+/**
+ * Capability requirement vector (item 1: HyDRA port, phase 1).
+ *
+ * Maps the existing 15-dim weighted analysis (complexity-analyzer.js
+ * calculateWeightedScore dimensions, each 0-100) onto 4 independent
+ * capability heads in [0,1]:
+ *
+ *   - reasoning : multi-step / planning / tradeoff analysis load
+ *   - codegen   : code-writing demand (generation + technical + tool depth)
+ *   - debugging : diagnostic load (analysis + technical + domain breadth)
+ *   - tool_use  : tool-orchestration load (count, complexity, chaining, history)
+ *
+ * Deliberately decoupled from the model catalog: this module never names a
+ * provider/model/tier. Model capabilities live in
+ * config/model-capabilities.json and matching lives in shortfall.js, so a
+ * catalog change is a config edit with zero retraining.
+ *
+ * Deliberately excludes risk/agentic overrides: risk-high forces REASONING
+ * and AUTONOMOUS sets a REASONING floor upstream (routing/index.js). Those
+ * stay as deterministic post-passes (like HyDRA's health veto), not as
+ * learned heads — keeping this predictor language- and catalog-invariant.
+ * The agentic flag only floors tool_use (agentic work always needs tools),
+ * it never lowers a requirement.
+ *
+ * Pure function, no I/O. Never throws: bad input yields the neutral prior
+ * (all 0.2 ≈ trivial) so callers fail open to cheap routing.
+ */
+
+const HEADS = ['reasoning', 'codegen', 'debugging', 'tool_use'];
+
+function _clamp01(v) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return 0;
+  return Math.max(0, Math.min(1, n));
+}
+
+function _dim01(dimensions, name) {
+  const v = Number(dimensions?.[name]);
+  if (!Number.isFinite(v)) return 0;
+  return Math.max(0, Math.min(1, v / 100));
+}
+
+/**
+ * @param {object} args
+ * @param {object} [args.dimensions] — calculateWeightedScore dimensions (0-100 each)
+ * @param {object} [args.agenticResult] — { isAgentic } (floors tool_use only)
+ * @returns {{ reasoning:number, codegen:number, debugging:number, tool_use:number }}
+ */
+function buildRequirementVector({ dimensions = {}, agenticResult = null } = {}) {
+  try {
+    const d = (name) => _dim01(dimensions, name);
+
+    let reasoning = d('multiStepReasoning') * 0.4
+      + d('analysisDepth') * 0.4
+      + d('promptComplexity') * 0.2;
+
+    let codegen = d('codeGeneration') * 0.5
+      + d('technicalDepth') * 0.3
+      + d('toolComplexity') * 0.2;
+
+    let debugging = d('analysisDepth') * 0.3
+      + d('technicalDepth') * 0.2
+      + d('domainSpecificity') * 0.3
+      + d('promptComplexity') * 0.2;
+
+    let toolUse = d('toolCount') * 0.3
+      + d('toolComplexity') * 0.3
+      + d('toolChainPotential') * 0.2
+      + d('priorToolUsage') * 0.2;
+
+    // Agentic work always needs tool orchestration — floor only, never lower.
+    if (agenticResult?.isAgentic) {
+      toolUse = Math.max(toolUse, 0.6);
+    }
+
+    const round3 = (v) => Math.round(_clamp01(v) * 1000) / 1000;
+    return {
+      reasoning: round3(reasoning),
+      codegen: round3(codegen),
+      debugging: round3(debugging),
+      tool_use: round3(toolUse),
+    };
+  } catch {
+    return { reasoning: 0.2, codegen: 0.2, debugging: 0.2, tool_use: 0.2 };
+  }
+}
+
+module.exports = { HEADS, buildRequirementVector };

package/src/routing/capability-seeds/benchmarks-dir.js

@@ -0,0 +1,58 @@
+/**
+ * Drop-in benchmark directory loader: data/capability-benchmarks/*.json.
+ *
+ * For leaderboards with no stable raw endpoint (TerminalBench, LiveCodeBench
+ * snapshots, Artificial Analysis exports): download the export once, drop it
+ * here, and the seed script picks it up. Format per file:
+ *
+ *   { "source": "terminalbench-2.1", "scale": "percent",
+ *     "results": { "Kimi K2.5": 42.1, "GPT 5.2": 38.0 } }
+ *
+ * scale "percent" (0-100) or "fraction" (0-1). Model names are cleaned with
+ * the SWE-bench cleaner and family-mapped in normalize.js; unmapped names
+ * surface for review instead of being silently seeded. Directory absent or
+ * empty → { files: [] } (not an error).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { cleanName } = require('./swebench');
+
+const BENCHMARKS_DIR = path.join(__dirname, '../../../data/capability-benchmarks');
+
+function loadBenchmarksDir(dir = BENCHMARKS_DIR) {
+  try {
+    if (!fs.existsSync(dir)) return { files: [] };
+    const files = [];
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.json')) continue;
+      try {
+        const raw = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+        if (!raw || typeof raw !== 'object' || !raw.results || typeof raw.results !== 'object') {
+          files.push({ file: name, status: 'skipped', reason: 'missing results object' });
+          continue;
+        }
+        const entries = [];
+        for (const [modelName, score] of Object.entries(raw.results)) {
+          const cleaned = cleanName(modelName);
+          const s = Number(score);
+          if (cleaned && Number.isFinite(s)) entries.push({ name: cleaned, score: s });
+        }
+        files.push({
+          file: name,
+          status: 'ok',
+          source: String(raw.source || name.replace(/\.json$/, '')),
+          scale: raw.scale === 'fraction' ? 'fraction' : 'percent',
+          entries,
+        });
+      } catch (err) {
+        files.push({ file: name, status: 'skipped', reason: err.message });
+      }
+    }
+    return { files };
+  } catch (err) {
+    return { files: [], error: err.message };
+  }
+}
+
+module.exports = { loadBenchmarksDir, BENCHMARKS_DIR };

package/src/routing/capability-seeds/family-heuristics.js

@@ -0,0 +1,77 @@
+/**
+ * Family-ladder heuristics: zero-network capability estimates from model
+ * family names. Vendors ship in ladders (haiku<sonnet<opus, mini<full,
+ * flash<pro, air<max, 7b<32b<70b), so an unknown model usually reveals its
+ * rung by name. Deliberately pessimistic: heuristics never claim frontier
+ * (cap 0.85) — exact seeds do that. Returns null when nothing matches, so
+ * the resolver falls through to tier-slot caps (today's behavior).
+ *
+ * Tilts: coder-named models get +codegen, reasoner-named +reasoning.
+ * Everything rounded to 3 decimals. Pure, no I/O, never throws.
+ */
+
+const CAP = 0.85;
+const FLOOR = 0.15;
+
+// Ordered: first match wins. Frontier names before size rules (a bare
+// "deepseek-r1" carries no size suffix but is strong).
+const LADDER = [
+  // Frontier (0.80)
+  { re: /^(gpt-5(\.|$)|o1(-pro)?$|o3($|-)|claude-opus-4|gemini-2\.5-pro|deepseek-r1$|deepseek-reasoner|glm-5\.|kimi-k3($|-)|grok-4|llama-3\.1-405b|qwen3-max|qwen3-235b|doubao-seed-1\.6|minimax-m2($|-)|gpt-5\.2|gpt-5\.3|gpt-5\.4)/, base: 0.8 },
+  // Strong (0.65)
+  { re: /(sonnet|gpt-4o$|gpt-4-turbo|gpt-5-mini|gpt-5-nano$|gemini-2\.[05].*pro|qwen3-3[02]b|qwen2\.5-3[23]b|deepseek-v3|glm-4\.7|glm-4\.6|glm-4\.5($|-)|kimi-k2($|-)|mistral-large|codestral|gpt-oss-120b|llama-3\.3-70b|qwen3-30b-a3b|devstral-large|kimi-k2\.5|gemini-3-pro|claude-4\.5)/, base: 0.65 },
+  // Mid (0.50)
+  { re: /(gpt-4o-mini|haiku|o4-mini|qwen3-(4b|8b|14b)|qwen2\.5-(7b|14b)|gemma-3-27b|phi-4|mistral-small|ministral|glm-4-flash|glm-4\.5-air|-lite$|-air$|devstral-small|qwen3-4b|gpt-5\.1)/, base: 0.5 },
+  // Small (0.30)
+  { re: /(-7b|-8b|-9b|^.*[^0-9](7|8|9)b$|mini|nano|gemma-?2|phi-3|llama-3\.2|flash-lite)/, base: 0.3 },
+  // Tiny (0.20)
+  { re: /(-1b|-2b|-3b|-0\.5b|-1\.5b|tiny$|gpt-3\.5)/, base: 0.2 },
+];
+
+const CODER_RE = /(coder|codestral|starcoder|qwen3-coder|devstral)/;
+const REASONER_RE = /(reason|r1$|qwq|\bo1\b|\bo3\b|thinking)/;
+
+function _sizeBase(family) {
+  const m = String(family || '').match(/(\d+(?:\.\d+)?)\s*b(?:$|-)/);
+  if (!m) return null;
+  const gb = Number(m[1]);
+  if (!Number.isFinite(gb)) return null;
+  if (gb >= 100) return 0.8;
+  if (gb >= 30) return 0.65;
+  if (gb >= 10) return 0.5;
+  if (gb >= 4) return 0.35;
+  return 0.25;
+}
+
+/**
+ * @param {string} family — normalized family id (see family.js)
+ * @returns {null | { reasoning:number, codegen:number, debugging:number, tool_use:number }}
+ */
+function heuristicCaps(family) {
+  try {
+    const f = String(family || '').toLowerCase().trim();
+    if (!f || f === 'unknown') return null;
+    let base = null;
+    for (const { re, base: b } of LADDER) {
+      if (re.test(f)) {
+        base = b;
+        break;
+      }
+    }
+    if (base === null) base = _sizeBase(f);
+    if (base === null) return null;
+    const round3 = (v) => Math.max(FLOOR, Math.min(CAP, Math.round(v * 1000) / 1000));
+    const codegen = base + (CODER_RE.test(f) ? 0.05 : 0);
+    const reasoning = base + (REASONER_RE.test(f) ? 0.05 : 0);
+    return {
+      reasoning: round3(reasoning),
+      codegen: round3(codegen),
+      debugging: round3(base),
+      tool_use: round3(base),
+    };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { heuristicCaps };

package/src/routing/capability-seeds/family.js

@@ -0,0 +1,105 @@
+/**
+ * Model-family normalization for capability seeding.
+ *
+ * Capability is a property of the MODEL (weights), not the provider serving
+ * it: zai:glm-5.2, baidu:glm-5.2 and ollama:glm-5.2 must resolve to one
+ * family id ("glm-5.2") and therefore identical caps. Provider stays on the
+ * cost/invocation path only.
+ *
+ * Normalization (order matters):
+ *   1. lowercase + trim, drop @digest suffixes
+ *   2. last `/`-segment wins (strips org prefixes: zai-org/glm-5.2,
+ *      openai/gpt-4o-mini, anthropic/claude-...)
+ *   3. Ollama `:tag` becomes `-tag` (tags often carry SIZE: qwen2.5-coder:7b
+ *      → qwen2.5-coder-7b; :latest/:cloud are noise but harmless post-strip)
+ *   4. strip serving prefixes (databricks-, anthropic., bedrock/)
+ *   5. `_` → `-`, digit-dash-digit → digit.dot.digit
+ *      (gpt-3-5-turbo → gpt-3.5-turbo, llama-3-1-70b → llama-3.1-70b),
+ *      collapse repeats
+ *
+ * Quantization is detected, not normalized away: Q4_K_M / gguf / int4 / awq
+ * style markers set quant:true so the resolver can apply the small
+ * same-brain-smaller-body haircut. Full-precision self-hosted hits the same
+ * caps as the API.
+ *
+ * Pure functions, no I/O. Never throws.
+ */
+
+const SERVING_PREFIXES = ['databricks-', 'anthropic.', 'bedrock/'];
+
+// Quant markers: matched against the full "model:tag" string BEFORE tag
+// folding, and against the folded family after (tags like Q4_K_M survive as
+// -q4-k-m, so one pass after folding suffices — but pre-tag names like
+// "model-Q4" exist too, hence match post-fold only, on the whole string).
+const QUANT_RE = /(q[23468](_|-|$)|_k_[sm]|[-_]q8_0|gguf|int[48]|fp[148]|awq|gptq|bnb|mlx|quantized)/i;
+
+// Tags that carry no signal even as suffixes.
+const NOISE_TAGS = new Set(['latest', 'cloud', 'instruct']);
+
+function detectQuant(s) {
+  try {
+    return QUANT_RE.test(String(s || ''));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} provider
+ * @param {string} model
+ * @returns {{ family:string, quant:boolean }}
+ */
+function normalizeFamily(provider, model) {
+  try {
+    let s = `${String(model || '').trim()}`;
+    // @sha256:... digests
+    s = s.split('@')[0];
+    // org prefix: last segment wins
+    if (s.includes('/')) s = s.split('/').pop();
+    const quant = detectQuant(`${provider || ''}/${model || ''}`) || detectQuant(s);
+    // Ollama :tag → -tag (size tags preserved: :7b → -7b)
+    if (s.includes(':')) {
+      const [base, ...tags] = s.split(':');
+      const kept = tags
+        .map((t) => t.trim().toLowerCase())
+        .filter((t) => t && !NOISE_TAGS.has(t));
+      s = kept.length > 0 ? `${base}-${kept.join('-')}` : base;
+    }
+    s = s.toLowerCase().trim();
+    for (const p of SERVING_PREFIXES) {
+      if (s.startsWith(p)) {
+        s = s.slice(p.length);
+        break;
+      }
+    }
+    s = s.replace(/_/g, '-');
+    // digit-dash-digit → digit.dot.digit, but only for version runs: the
+    // second digit must be followed by another dash or end-of-string, so
+    // size suffixes survive (llama-3-1-70b → llama-3.1-70b, but
+    // qwen3-32b and gemma-3-27b keep their dash).
+    s = s.replace(/(\d)-(?=\d(?:-|$))/g, '$1.');
+    s = s.replace(/-+/g, '-').replace(/^-|-$/g, '');
+    return { family: s || 'unknown', quant };
+  } catch {
+    return { family: 'unknown', quant: false };
+  }
+}
+
+/**
+ * Quant haircut: same brain, smaller body. Applied by the resolver to
+ * seed/family/tier caps — never to explicit operator overrides (an exact
+ * provider:model override wins verbatim).
+ */
+const QUANT_HAIRCUT = 0.02;
+const QUANT_FLOOR = 0.1;
+
+function applyQuantHaircut(caps) {
+  const out = {};
+  for (const [k, v] of Object.entries(caps || {})) {
+    const n = Number(v);
+    out[k] = Number.isFinite(n) ? Math.max(QUANT_FLOOR, Math.round((n - QUANT_HAIRCUT) * 1000) / 1000) : v;
+  }
+  return out;
+}
+
+module.exports = { normalizeFamily, detectQuant, applyQuantHaircut, QUANT_HAIRCUT };