lynkr 9.14.1 → 9.14.3

package/src/api/router.js

@@ -7,7 +7,9 @@ const logger = require("../logger");
 const { createRateLimiter } = require("./middleware/rate-limiter");
 const openaiRouter = require("./openai-router");
 const providersRouter = require("./providers-handler");
+const claudeDesktopGatewayRouter = require("./claude-desktop-gateway");
 const { getRoutingHeaders, getRoutingStats, analyzeComplexity, getModelTierSelector, analyzeRisk, checkSessionPin, writeSessionPin, checkPinScoreDrift } = require("../routing");
+const { resolveTierForModelId } = require("../routing/model-slots");
 
 // Upstream streams can die without a clean end (reader.read() never
 // resolves on a dropped socket), hanging the client forever. Every
@@ -36,7 +38,7 @@ const { detectClient } = require("../routing/client-profiles");
 const { buildInteractionBlock } = require("../routing/interaction");
 const { validateCwd } = require("../workspace");
 const { renderText } = require("../utils/markdown-ansi");
-const { classifyAuthMode } = require("../auth-mode");
+const { classifyAuthMode, isFirstPartyAnthropicClient } = require("../auth-mode");
 
 const router = express.Router();
 
@@ -306,21 +308,16 @@ async function handleOauthPassthrough(req, res, opts = {}) {
   const upstream = process.env.LYNKR_OAUTH_PASSTHROUGH_URL
     || "https://api.anthropic.com/v1/messages";
 
-  // === Optional: memory injection at last-user-message tail ===
-  // Headroom's P0-1 pattern: append memory context to the latest user
-  // message's first text block. NEVER touches system prompt or frozen-prefix
-  // messages, so the cache-hot zone Anthropic fingerprints stays intact.
-  // Opt-in via LYNKR_OAUTH_MEMORY_INJECTION=true since any body mutation on
-  // a subscription request has nonzero anti-abuse risk.
+  // NO body mutation on the passthrough — deliberate policy (2026-09). The
+  // memory-injection option that lived here (LYNKR_OAUTH_MEMORY_INJECTION)
+  // was removed: this function's whole contract is byte-for-byte fidelity
+  // to what the first-party client sent, and any mutation of subscription
+  // traffic both breaks that claim and carries anti-abuse risk. Memory
+  // injection remains available on the orchestrator paths, where Lynkr is
+  // openly transforming requests. The only change made below is stripping
+  // Lynkr-internal underscore-prefixed fields, which Anthropic would reject
+  // as unknown keys — protocol necessity, not content mutation.
   let bodyToSend = req.body;
-  if (process.env.LYNKR_OAUTH_MEMORY_INJECTION === 'true' && config.memory?.enabled !== false) {
-    try {
-      bodyToSend = maybeInjectMemoryIntoUserTail(req.body);
-    } catch (err) {
-      logger.debug({ err: err.message }, "Memory injection skipped (non-fatal)");
-      bodyToSend = req.body;
-    }
-  }
 
   // === Observability: start ===
   const startedAt = Date.now();
@@ -390,8 +387,13 @@ async function handleOauthPassthrough(req, res, opts = {}) {
   // Lynkr's own decision headers so callers can see which model answered.
   res.set("X-Lynkr-Provider", "azure-anthropic-passthrough");
   if (opts.tier?.tier) res.set("X-Lynkr-Tier", opts.tier.tier);
-  if (req.body?.model) res.set("X-Lynkr-Model", req.body.model);
-  res.set("X-Lynkr-Routing-Method", "oauth-subscription-stealth");
+  if (req.body?.model) {
+    res.set("X-Lynkr-Model", req.body.model);
+    const { contextWindowFor } = require("../routing/model-registry");
+    const contextWindow = contextWindowFor(req.body.model);
+    if (contextWindow) res.set("X-Lynkr-Context-Window", String(contextWindow));
+  }
+  res.set("X-Lynkr-Routing-Method", "oauth-subscription-passthrough");
 
   // Capture the response (buffered or streamed) so we can do observability hooks
   // on the way back without changing what the client sees.
@@ -450,7 +452,7 @@ async function handleOauthPassthrough(req, res, opts = {}) {
       try { reader.cancel(); } catch { /* already dead */ }
       try { res.write(SSE_STALL_EVENT); } catch { /* client gone */ }
     } finally {
-      try { reader.releaseLock(); } catch {}
+      try { reader.releaseLock(); } catch { /* lock already released */ }
     }
     res.end();
   } else {
@@ -495,7 +497,7 @@ async function handleOauthPassthrough(req, res, opts = {}) {
       const tier = opts.tier || {};
       let parsedResponse = null;
       if (contentType.includes("application/json")) {
-        try { parsedResponse = JSON.parse(responseTextForObservability); } catch {}
+        try { parsedResponse = JSON.parse(responseTextForObservability); } catch { /* not JSON — telemetry proceeds without a parsed body */ }
       } else if (contentType.includes("text/event-stream")) {
         // Extract a usable response object from the SSE stream by finding the
         // final message_delta / message_stop events.
@@ -730,86 +732,8 @@ function extractAnthropicMessageFromSSE(sseText) {
   return result;
 }
 
-/**
- * Append relevant memories to the FIRST TEXT BLOCK of the LATEST USER MESSAGE.
- *
- * Headroom's P0-1 pattern (`_append_context_to_latest_non_frozen_user_turn`).
- * The cache hot zone (system + frozen prefix) is NEVER touched. Mutating only
- * the latest user message — which is the request's "live zone" — keeps the
- * prompt-cache identity stable and avoids Anthropic anti-abuse fingerprint
- * divergence for subscription tokens.
- *
- * Returns the body unchanged if:
- *   - Memory is disabled
- *   - No memories retrieved
- *   - Latest message is not a user turn (could be tool_result, assistant)
- *
- * Returns a new body with appended context otherwise. Original body never
- * mutated (returns a shallow-cloned messages array).
- */
-function maybeInjectMemoryIntoUserTail(body) {
-  if (!body || !Array.isArray(body.messages) || body.messages.length === 0) return body;
-
-  const lastIdx = body.messages.length - 1;
-  const lastMsg = body.messages[lastIdx];
-  if (!lastMsg || lastMsg.role !== "user") return body;
-
-  const { retrieveRelevantMemories, formatMemoriesForContext, extractQueryFromMessage } =
-    require("../memory/retriever");
-  const query = extractQueryFromMessage(lastMsg);
-  if (!query || query.length < 10) return body; // too short to be a useful query
-
-  const memories = retrieveRelevantMemories(query, {
-    limit: Math.min(parseInt(process.env.MEMORY_RETRIEVAL_LIMIT, 10) || 5, 10),
-    sessionId: body._sessionId || null,
-    includeGlobal: process.env.MEMORY_INCLUDE_GLOBAL !== "false",
-  });
-  if (!memories || memories.length === 0) return body;
-
-  const formatted = formatMemoriesForContext(memories);
-  if (!formatted) return body;
-
-  const contextText = `\n\n## Relevant context from earlier sessions:\n${formatted}`;
-
-  // Bound the injection size (Headroom uses a MemoryInjectionBudget; we use
-  // a simpler char cap — ~1024 tokens * 4 chars/token = 4096 chars).
-  const MAX_INJECTION_CHARS = 4096;
-  const boundedContext = contextText.length > MAX_INJECTION_CHARS
-    ? contextText.slice(0, MAX_INJECTION_CHARS) + "\n…"
-    : contextText;
-
-  // Clone messages array (shallow) so we don't mutate the caller's body.
-  const newMessages = body.messages.slice();
-
-  if (typeof lastMsg.content === "string") {
-    newMessages[lastIdx] = { ...lastMsg, content: lastMsg.content + boundedContext };
-  } else if (Array.isArray(lastMsg.content) && lastMsg.content.length > 0) {
-    // Append to the FIRST text block, preserving every other block (images,
-    // tool_use, etc.) untouched.
-    const newContent = [];
-    let appended = false;
-    for (const block of lastMsg.content) {
-      if (!appended && block && typeof block === "object" && block.type === "text") {
-        newContent.push({ ...block, text: (block.text || "") + boundedContext });
-        appended = true;
-      } else {
-        newContent.push(block);
-      }
-    }
-    if (!appended) return body; // no text block to append to
-    newMessages[lastIdx] = { ...lastMsg, content: newContent };
-  } else {
-    return body;
-  }
-
-  logger.debug({
-    memoryCount: memories.length,
-    appendedChars: boundedContext.length,
-  }, "Memory injected into last-user-message tail");
-
-  return { ...body, messages: newMessages };
-}
-
+// (maybeInjectMemoryIntoUserTail was removed with the passthrough
+// memory-injection option — the passthrough is byte-for-byte by contract.)
 /**
  * Estimate token count for messages.
  *
@@ -1027,7 +951,10 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
     try {
       const { getMetricsCollector } = require("../observability/metrics");
       getMetricsCollector().recordRequest("POST", "/v1/messages", null, null);
-    } catch (_) {}
+    } catch (err) {
+      // If this fails silently, the wrap UI's "No requests tracked" bug returns.
+      logger.debug({ err: err?.message }, "observability collector recordRequest failed");
+    }
 
     messagesRequestCount += 1;
 
@@ -1089,7 +1016,7 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
     //
     // All three paths now share window-scored intent tier picking
     // (`pickTierByIntent`). Subscription still has the additional
-    // azure-anthropic passthrough fork for anti-abuse stealth; everything
+    // azure-anthropic passthrough fork (first-party clients only); everything
     // else just falls through to the orchestrator with the picked tier
     // pinned via _forceProvider/_tierModel. The reason all paths share the
     // scorer is that determineProviderSmart's full-body analysis inflates
@@ -1114,6 +1041,37 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
     // in a session skip the whole window-scored intent pipeline.
     let tier;
     const pinCheck = checkSessionPin(req.body);
+
+    // Explicit model-id pin: Claude Desktop's model picker (or any Anthropic-
+    // format caller) can name one of the fixed ids claude-desktop-gateway.js
+    // advertises (see ../routing/model-slots.js). Unlike every signal below,
+    // this one is EXPLICIT user intent, not an inference — it wins over
+    // session pins, side-request detection, and content scoring alike.
+    // "Lynkr Auto" (claude-fable-5) and any unrecognized id resolve to null
+    // and fall through to the existing cascade unchanged.
+    const modelPinTier = resolveTierForModelId(req.body?.model);
+    if (modelPinTier) {
+      const _sel = getModelTierSelector().selectModel(modelPinTier, null);
+      tier = {
+        tier: modelPinTier,
+        provider: _sel.provider,
+        model: _sel.model || null,
+        score: null,
+        method: 'model_id_pin',
+        reason: 'client_selected_model',
+        base_tier: null,
+        escalation_source: null,
+        pinned: false,
+        switch_reason: null,
+        propensity: 1.0,
+        candidates: [{ provider: _sel.provider, model: _sel.model || null }],
+      };
+      logger.debug({
+        model: req.body.model,
+        tier: modelPinTier,
+        provider: _sel.provider,
+      }, "[Routing] Explicit model-id pin — scoring bypassed");
+    } else {
     // Side-request detection. Claude Code fires internal background calls
     // (title generation, summarization, memory extraction, suggestion-mode
     // autocomplete) that REPLAY the conversation — so they share the
@@ -1340,11 +1298,13 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
         }, "OAuth intent — side request (no tools), pin write skipped");
       }
     }
+    } // end else — no explicit model-id pin, scored normally above
 
-    // Subscription-only fork: anti-abuse stealth passthrough when the picked
-    // tier resolves to azure-anthropic. Bypasses the orchestrator entirely
-    // so the inbound bytes hit api.anthropic.com unchanged (Anthropic
-    // fingerprints subscription clients; any mutation gets flagged).
+    // Subscription-only fork: byte-for-byte passthrough to api.anthropic.com
+    // when the picked tier resolves to azure-anthropic — FIRST-PARTY
+    // Anthropic clients only (Claude Code / Claude Desktop wrapping their
+    // own traffic; see auth-mode.js for the policy). Gated here at the
+    // dispatch point, not just in classification, so the two can't drift.
     // Passthrough forwards the CLIENT's credentials; GUI harnesses that
     // spawn claude headless inject placeholder keys ("dummy") that Anthropic
     // 401s. Placeholder auth ⇒ serve REASONING via the provider's own
@@ -1354,13 +1314,14 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
     const _placeholderAuth =
       !_clientAuthHdr &&
       (['dummy', 'test', 'placeholder', 'none', 'x', 'sk-dummy'].includes(_clientApiKey) || _clientApiKey.length < 8);
+    const _firstParty = isFirstPartyAnthropicClient(req.headers);
     if (_placeholderAuth && authMode === 'subscription' && tier.provider === 'azure-anthropic') {
       logger.info({
         reqNumber: messagesRequestCount,
         xApiKeyShape: _clientApiKey.slice(0, 12),
       }, 'Placeholder client auth — skipping passthrough, serving REASONING via provider credentials');
     }
-    if (authMode === 'subscription' && tier.provider === 'azure-anthropic' && !_placeholderAuth) {
+    if (authMode === 'subscription' && tier.provider === 'azure-anthropic' && !_placeholderAuth && _firstParty) {
       logger.debug({
         reqNumber: messagesRequestCount,
         authMode,
@@ -2087,6 +2048,12 @@ router.get("/api/tokens/stats", (req, res) => {
   }
 });
 
+// Claude Desktop third-party gateway: intercepts GET /v1/models for
+// Anthropic-API clients (anthropic-version header) and advertises Lynkr's
+// tiers as Claude model families. Mounted BEFORE openaiRouter so the
+// intercept wins; non-Anthropic callers fall through unchanged.
+router.use("/v1", claudeDesktopGatewayRouter);
+
 // Mount OpenAI-compatible endpoints for Cursor IDE support
 router.use("/v1", openaiRouter);
 

package/src/auth-mode.js

@@ -47,15 +47,34 @@
  * @module auth-mode
  */
 
+// FIRST-PARTY Anthropic clients only (deliberate policy, 2026-09): the
+// subscription classification — and with it the api.anthropic.com
+// passthrough — is for Claude Code and Claude Desktop wrapping their OWN
+// traffic. Third-party harness prefixes (codex-cli/, cursor/,
+// github-copilot/, antigravity/) were removed: classifying them as
+// 'subscription' handed the passthrough to exactly the harness category
+// Anthropic's ToS enforcement targets. Those clients still work through
+// Lynkr — they classify by token shape ('oauth'/'payg') and route through
+// the orchestrator with the operator's configured providers.
+//
+// BREAKING CHANGE for anyone who had Cursor/Codex/Copilot riding the
+// subscription path: that traffic now routes via configured tiers.
+//
+// If Claude Desktop's own requests carry a UA not listed here (capture one
+// via the desktop gateway before assuming), add THAT — never a third-party
+// harness. This is a UA check: it defines intended use, not cryptographic
+// attestation.
 const SUBSCRIPTION_UA_PREFIXES = [
   'claude-cli/',
   'claude-code/',
-  'codex-cli/',
-  'cursor/',
   'claude-vscode/',
-  'github-copilot/',
   'anthropic-cli/',
-  'antigravity/',
+  // Claude Desktop (Electron app). Captured from a real gateway request:
+  // "Mozilla/5.0 (...) Claude/1.46388.1 Chrome/148... Electron/42..." —
+  // the app identifies as "Claude/<version>" inside a browser-style UA.
+  // Deliberately 'claude/' (with slash): no third-party harness UA carries
+  // that token, and the first-party ids above don't collide with it.
+  'claude/',
 ];
 
 /**
@@ -110,7 +129,24 @@ function classifyAuthMode(headers) {
   return 'payg';
 }
 
+/**
+ * Is this request from a first-party Anthropic client (Claude Code / Claude
+ * Desktop family)? Used as the explicit gate at the api.anthropic.com
+ * passthrough dispatch fork — the security decision lives at the point of
+ * dispatch, not only in classification, so the two can't silently drift
+ * apart. Same UA semantics as classifyAuthMode's subscription check.
+ *
+ * @param {object} headers
+ * @returns {boolean}
+ */
+function isFirstPartyAnthropicClient(headers) {
+  const ua = getHeader(headers, 'user-agent').toLowerCase();
+  if (!ua) return false;
+  return SUBSCRIPTION_UA_PREFIXES.some((prefix) => ua.includes(prefix));
+}
+
 module.exports = {
   classifyAuthMode,
+  isFirstPartyAnthropicClient,
   SUBSCRIPTION_UA_PREFIXES,
 };

package/src/budget/index.js

@@ -75,6 +75,12 @@ class BudgetManager {
         minute_window_start INTEGER,
         hour_window_start INTEGER
       );
+
+      CREATE TABLE IF NOT EXISTS token_rate (
+        user_id TEXT PRIMARY KEY,
+        tokens_minute INTEGER NOT NULL DEFAULT 0,
+        minute_window_start INTEGER NOT NULL
+      );
     `);
 
     this.stmts = {
@@ -114,6 +120,86 @@ class BudgetManager {
     };
   }
 
+  /**
+   * Token-aware (TPM) rate limiting (ROUTING-NOTES §1 gap: request-count
+   * only). Off unless LYNKR_TPM_LIMIT is set — same "off unless configured"
+   * convention as the loop guard.
+   *
+   * Estimate → true-up pattern (the one every serious gateway converged on):
+   * the pre-flight check gates on the window's ACTUAL consumption plus the
+   * current request's cheap estimate; real usage lands in the window
+   * post-response via recordTokenUsage(). Soft admission control, not a hard
+   * ceiling — concurrent in-flight requests can overshoot by roughly one
+   * request's worth, by design.
+   *
+   * @param {string} userId
+   * @param {number} estimatedTokens — cheap pre-flight estimate for THIS request
+   * @returns {{allowed: boolean, reason?: string, limit?: number, current?: number, resetInMs?: number}}
+   */
+  checkTokenRate(userId, estimatedTokens = 0) {
+    if (!this.enabled) return { allowed: true };
+    const limit = Number.parseInt(process.env.LYNKR_TPM_LIMIT, 10);
+    if (!limit || limit <= 0 || Number.isNaN(limit)) return { allowed: true };
+
+    const now = Date.now();
+    const minuteWindow = 60 * 1000;
+    const row = this.db.prepare('SELECT * FROM token_rate WHERE user_id = ?').get(userId);
+    let tokensMinute = row?.tokens_minute ?? 0;
+    let windowStart = row?.minute_window_start ?? now;
+    if (now - windowStart >= minuteWindow) {
+      tokensMinute = 0;
+      windowStart = now;
+      this.db.prepare(`
+        INSERT INTO token_rate (user_id, tokens_minute, minute_window_start)
+        VALUES (?, 0, ?)
+        ON CONFLICT(user_id) DO UPDATE SET tokens_minute = 0, minute_window_start = excluded.minute_window_start
+      `).run(userId, windowStart);
+    }
+
+    if (tokensMinute + estimatedTokens > limit) {
+      return {
+        allowed: false,
+        reason: 'token_rate_limit_minute',
+        limit,
+        current: tokensMinute,
+        estimated: estimatedTokens,
+        resetInMs: minuteWindow - (now - windowStart),
+      };
+    }
+    return { allowed: true };
+  }
+
+  /**
+   * True-up: add ACTUAL token consumption to the user's TPM window after the
+   * response completes. No-op when TPM limiting is disabled.
+   * @param {string} userId
+   * @param {number} totalTokens — actual input+output tokens consumed
+   */
+  recordTokenUsage(userId, totalTokens) {
+    if (!this.enabled || !totalTokens || totalTokens <= 0) return;
+    const limit = Number.parseInt(process.env.LYNKR_TPM_LIMIT, 10);
+    if (!limit || limit <= 0 || Number.isNaN(limit)) return;
+    const now = Date.now();
+    const minuteWindow = 60 * 1000;
+    try {
+      const row = this.db.prepare('SELECT * FROM token_rate WHERE user_id = ?').get(userId);
+      const stale = !row || now - row.minute_window_start >= minuteWindow;
+      this.db.prepare(`
+        INSERT INTO token_rate (user_id, tokens_minute, minute_window_start)
+        VALUES (@user_id, @tokens, @window_start)
+        ON CONFLICT(user_id) DO UPDATE SET
+          tokens_minute = ${stale ? '@tokens' : 'tokens_minute + @tokens'},
+          minute_window_start = @window_start
+      `).run({
+        user_id: userId,
+        tokens: totalTokens,
+        window_start: stale ? now : row.minute_window_start,
+      });
+    } catch (err) {
+      logger.debug({ err: err.message }, '[Budget] token usage record failed');
+    }
+  }
+
   checkRateLimit(userId) {
     if (!this.enabled) return { allowed: true };
 

package/src/cache/embeddings.js

@@ -115,55 +115,136 @@ function simpleHash(str) {
   return hash;
 }
 
-// Track if embedding provider is available
+// Embedding provider availability state.
+//
+// The hash fallback is NOT a semantic embedding — when it's active, the
+// semantic cache and kNN router are effectively disabled (hash vectors are
+// 384-dim vs the providers' 768-dim, so they never match real entries; the
+// kNN index rejects them on dimension). Historically this degradation was a
+// permanent latch (one transient provider failure disabled semantic matching
+// until process restart) and logged only at debug level — i.e. invisible.
+// The same failure shape elsewhere in the industry silently misrouted ~20%
+// of a production cluster's spend before anyone noticed, so this state is
+// now: retried on a cooldown, logged loudly on every transition, counted,
+// and exposed via getEmbeddingStatus() for /metrics.
 let embeddingProviderAvailable = null;
+let degradedSince = null;
+let lastProviderAttempt = 0;
+let fallbackCount = 0;
+let lastProviderError = null;
+
+// After a provider failure, wait this long before trying it again (instead
+// of latching to the fallback forever). Env-tunable for tests/impatience.
+const RETRY_COOLDOWN_MS = Number.parseInt(process.env.LYNKR_EMBEDDINGS_RETRY_COOLDOWN_MS, 10) || 60_000;
+
+// Strict mode: throw instead of silently degrading to hash embeddings.
+// For deployments that prefer fail-loud (no semantic cache is better than a
+// silently fake one). Default stays fail-soft to match Lynkr's philosophy.
+const STRICT = process.env.LYNKR_EMBEDDINGS_STRICT === 'true';
+
+function _noteFallback(providerName, err) {
+  fallbackCount += 1;
+  lastProviderError = err?.message || String(err);
+  if (embeddingProviderAvailable !== false) {
+    embeddingProviderAvailable = false;
+    degradedSince = Date.now();
+    logger.warn({
+      provider: providerName,
+      error: lastProviderError,
+      retryCooldownMs: RETRY_COOLDOWN_MS,
+    }, '[Embeddings] Provider unreachable — DEGRADED to non-semantic hash embeddings. Semantic cache and kNN routing are effectively disabled until the provider recovers.');
+  }
+}
+
+function _noteRecovery(providerName) {
+  if (embeddingProviderAvailable === false) {
+    logger.info({
+      provider: providerName,
+      degradedForMs: degradedSince ? Date.now() - degradedSince : null,
+      fallbacksServed: fallbackCount,
+    }, '[Embeddings] Provider recovered — semantic embeddings restored');
+  }
+  embeddingProviderAvailable = true;
+  degradedSince = null;
+}
+
+function _wrapProvider(providerName, providerFn) {
+  return async (text) => {
+    // While degraded, only re-attempt the provider after the cooldown; serve
+    // the fallback in between so a dead provider doesn't add per-request
+    // connect timeouts to the hot path.
+    if (embeddingProviderAvailable === false
+        && Date.now() - lastProviderAttempt < RETRY_COOLDOWN_MS) {
+      if (STRICT) throw new Error(`Embedding provider ${providerName} degraded: ${lastProviderError}`);
+      fallbackCount += 1;
+      return generateHashEmbedding(text);
+    }
+    lastProviderAttempt = Date.now();
+    try {
+      const result = await providerFn(text);
+      _noteRecovery(providerName);
+      return result;
+    } catch (err) {
+      _noteFallback(providerName, err);
+      if (STRICT) throw err;
+      return generateHashEmbedding(text);
+    }
+  };
+}
 
 /**
  * Get the appropriate embedding function based on config
  * @returns {Function} - Embedding generation function
  */
 function getEmbeddingFunction() {
-  // If we already know embedding provider isn't available, use fallback
-  if (embeddingProviderAvailable === false) {
-    return (text) => Promise.resolve(generateHashEmbedding(text));
-  }
-
   const provider = config.modelProvider?.type || 'databricks';
 
+  // In-process ONNX embedder (opt-in): no external embedding server on the
+  // hot path at all. Same underlying model as the Ollama default
+  // (nomic-embed-text, 768-dim), so existing kNN/cache vectors stay valid.
+  // Wrapped in the same degradation machinery — a failed model load logs
+  // loudly, serves the hash fallback, and retries after the cooldown.
+  if (process.env.LYNKR_EMBEDDINGS_PROVIDER === 'onnx') {
+    const { generateOnnxEmbedding, isOnnxAvailable } = require('./onnx-embedder');
+    if (isOnnxAvailable()) {
+      return _wrapProvider('onnx', generateOnnxEmbedding);
+    }
+    logger.warn('[Embeddings] LYNKR_EMBEDDINGS_PROVIDER=onnx but @huggingface/transformers is not installed (optionalDependency) — falling through to the configured network provider');
+  }
+
   // Check if we have a local embedding provider configured
   if (config.ollama?.embeddingsEndpoint || provider === 'ollama') {
-    return async (text) => {
-      try {
-        const result = await generateOllamaEmbedding(text);
-        embeddingProviderAvailable = true;
-        return result;
-      } catch (err) {
-        logger.debug({ error: err.message }, 'Ollama embedding failed, using hash fallback');
-        embeddingProviderAvailable = false;
-        return generateHashEmbedding(text);
-      }
-    };
+    return _wrapProvider('ollama', generateOllamaEmbedding);
   }
 
   if (config.llamacpp?.embeddingsEndpoint || provider === 'llamacpp') {
-    return async (text) => {
-      try {
-        const result = await generateLlamaCppEmbedding(text);
-        embeddingProviderAvailable = true;
-        return result;
-      } catch (err) {
-        logger.debug({ error: err.message }, 'LlamaCpp embedding failed, using hash fallback');
-        embeddingProviderAvailable = false;
-        return generateHashEmbedding(text);
-      }
-    };
-  }
-
-  // Fallback to hash-based embeddings
-  logger.debug('No embedding provider configured, using hash-based fallback');
+    return _wrapProvider('llamacpp', generateLlamaCppEmbedding);
+  }
+
+  // No provider configured at all — hash fallback is the deliberate mode,
+  // not a degradation. Warn once so the operator knows semantic matching is
+  // approximate, then stay quiet.
+  if (embeddingProviderAvailable === null) {
+    embeddingProviderAvailable = false;
+    logger.warn('[Embeddings] No embedding provider configured — using non-semantic hash embeddings. Semantic cache matches will be approximate; configure an Ollama/llama.cpp embeddings endpoint for real semantic matching.');
+  }
   return (text) => Promise.resolve(generateHashEmbedding(text));
 }
 
+/**
+ * Current embedding subsystem status, for /metrics and health surfaces.
+ * @returns {{ providerAvailable: boolean|null, degradedSince: number|null,
+ *             fallbackCount: number, lastProviderError: string|null }}
+ */
+function getEmbeddingStatus() {
+  return {
+    providerAvailable: embeddingProviderAvailable,
+    degradedSince,
+    fallbackCount,
+    lastProviderError,
+  };
+}
+
 /**
  * Generate embedding for text
  * @param {string} text - Text to embed
@@ -178,12 +259,16 @@ async function generateEmbedding(text) {
   const maxLength = 8000;
   const truncated = text.length > maxLength ? text.substring(0, maxLength) : text;
 
+  const embedFn = getEmbeddingFunction();
+  if (STRICT) return embedFn(truncated);
   try {
-    const embedFn = getEmbeddingFunction();
     return await embedFn(truncated);
   } catch (err) {
-    // Final fallback to hash embeddings if everything else fails
-    logger.debug({ error: err.message }, 'Embedding generation failed, using hash fallback');
+    // Final fallback to hash embeddings if everything else fails. The
+    // provider wrapper already logged the degradation transition loudly;
+    // this catch only covers unexpected non-provider errors.
+    logger.warn({ error: err.message }, '[Embeddings] Embedding generation failed unexpectedly, serving hash fallback');
+    fallbackCount += 1;
     return generateHashEmbedding(truncated);
   }
 }
@@ -193,6 +278,10 @@ async function generateEmbedding(text) {
  */
 function resetEmbeddingProvider() {
   embeddingProviderAvailable = null;
+  degradedSince = null;
+  lastProviderAttempt = 0;
+  fallbackCount = 0;
+  lastProviderError = null;
 }
 
 /**
@@ -231,5 +320,6 @@ module.exports = {
   generateHashEmbedding,
   cosineSimilarity,
   getEmbeddingFunction,
+  getEmbeddingStatus,
   resetEmbeddingProvider,
 };