lynkr 9.10.0 → 9.11.0

package/src/routing/telemetry.js

@@ -165,6 +165,11 @@ function init() {
       ["candidates", "TEXT"],
       ["pinned", "INTEGER DEFAULT 0"],
       ["switch_reason", "TEXT"],
+      // Phase 6 (cache-aware routing) — per-decision cache economics
+      // receipt: {decision, reason, warmPrefixTokens, breakEvenTurns,
+      // projectedSwitchCostUsd, projectedStaySavingsUsd,
+      // expectedRemainingTurns} as JSON.
+      ["cache_decision", "TEXT"],
     ];
     for (const [col, type] of additiveCols) {
       if (!existingCols.has(col)) {
@@ -226,7 +231,8 @@ function record(data) {
           latency_ms, status_code, error_type, cost_usd, tool_calls_made,
           retry_count, circuit_breaker_state, quality_score, tokens_per_second,
           cost_efficiency, request_text, response_text,
-          base_tier, escalation_source, propensity, candidates, pinned, switch_reason
+          base_tier, escalation_source, propensity, candidates, pinned, switch_reason,
+          cache_decision
         ) VALUES (
           @request_id, @session_id, @timestamp, @complexity_score, @tier,
           @agentic_type, @tool_count, @input_tokens, @message_count, @request_type,
@@ -234,7 +240,8 @@ function record(data) {
           @latency_ms, @status_code, @error_type, @cost_usd, @tool_calls_made,
           @retry_count, @circuit_breaker_state, @quality_score, @tokens_per_second,
           @cost_efficiency, @request_text, @response_text,
-          @base_tier, @escalation_source, @propensity, @candidates, @pinned, @switch_reason
+          @base_tier, @escalation_source, @propensity, @candidates, @pinned, @switch_reason,
+          @cache_decision
         )`
       );
       if (!insert) return;
@@ -280,6 +287,11 @@ function record(data) {
         candidates: candidatesJson,
         pinned: data.pinned ? 1 : 0,
         switch_reason: data.switch_reason ?? null,
+        cache_decision: data.cache_decision == null
+          ? null
+          : (typeof data.cache_decision === "string"
+            ? data.cache_decision
+            : JSON.stringify(data.cache_decision)),
       });
     } catch (err) {
       logger.debug({ err: err.message }, "Telemetry record failed");
@@ -791,6 +803,129 @@ function _resetForTests() {
   _testDbDisabled = false;
 }
 
+// Cache-aware routing (Phase 6) — "cache dollars saved / burned by routing".
+//
+// Every gated switch/hold decision carries a receipt. Aggregating them
+// answers the public question "does model routing break prefix caching?"
+// with a dollar figure:
+//   - a HOLD avoided a switch whose one-time cache write exceeded its
+//     projected per-turn savings over the expected horizon
+//     (saved = switchOnce − savings × remainingTurns)
+//   - a SWITCH cleared break-even; its projected net gain is
+//     (savings × remainingTurns − switchOnce)
+/**
+ * @param {Object} [opts]
+ * @param {number} [opts.since] - default: last 7 days.
+ * @returns {{decisions:number, holds:number, switches:number,
+ *   dollarsSavedByHolds:number, dollarsSavedBySwitches:number,
+ *   totalDollarsSaved:number, byReason:Object}|null}
+ */
+function getCacheEconomics(opts = {}) {
+  if (!init()) return null;
+  const since = opts.since ?? Date.now() - 7 * 24 * 60 * 60 * 1000;
+  try {
+    const rows = db
+      .prepare(
+        `SELECT cache_decision FROM routing_telemetry
+         WHERE timestamp > ? AND cache_decision IS NOT NULL
+         LIMIT 20000`
+      )
+      .all(since);
+
+    const out = {
+      decisions: 0,
+      holds: 0,
+      switches: 0,
+      dollarsSavedByHolds: 0,
+      dollarsSavedBySwitches: 0,
+      totalDollarsSaved: 0,
+      byReason: {},
+    };
+
+    for (const row of rows) {
+      let d;
+      try {
+        d = JSON.parse(row.cache_decision);
+      } catch {
+        continue;
+      }
+      if (!d || typeof d !== "object") continue;
+      out.decisions++;
+      out.byReason[d.reason ?? "unknown"] = (out.byReason[d.reason ?? "unknown"] ?? 0) + 1;
+
+      const savings = typeof d.projectedStaySavingsUsd === "number" ? d.projectedStaySavingsUsd : null;
+      const once = typeof d.projectedSwitchCostUsd === "number" ? d.projectedSwitchCostUsd : null;
+      const horizon = typeof d.expectedRemainingTurns === "number" ? d.expectedRemainingTurns : null;
+
+      if (d.decision === "hold") {
+        out.holds++;
+        if (savings != null && once != null && horizon != null) {
+          out.dollarsSavedByHolds += Math.max(0, once - savings * horizon);
+        }
+      } else if (d.decision === "switch") {
+        out.switches++;
+        if (savings != null && once != null && horizon != null) {
+          out.dollarsSavedBySwitches += Math.max(0, savings * horizon - once);
+        }
+      }
+    }
+
+    out.totalDollarsSaved = out.dollarsSavedByHolds + out.dollarsSavedBySwitches;
+    return out;
+  } catch (err) {
+    logger.debug({ err: err.message }, "Telemetry getCacheEconomics failed");
+    return null;
+  }
+}
+
+// Cache-aware routing (Phase 3) — expected remaining turns.
+//
+// Conditional median: given a session has already reached `currentTurns`
+// messages, how many MORE messages do comparable sessions run? Uses the max
+// message_count each recent session reached. Conditional (len > current)
+// rather than a global median because long sessions systematically outlive
+// the average — exactly the sessions whose warm prefixes are worth pricing.
+const _remainingTurnsCache = new Map();
+const REMAINING_TURNS_CACHE_TTL_MS = 60 * 1000;
+const REMAINING_TURNS_MIN_SESSIONS = 20;
+
+/**
+ * @param {number} currentTurns - message_count the session has reached now.
+ * @returns {number|null} median remaining messages, or null when telemetry
+ *   is too sparse (< 20 comparable sessions in the last 7 days).
+ */
+function getExpectedRemainingTurns(currentTurns = 0) {
+  if (!init()) return null;
+  const bucket = Math.max(0, Math.floor((Number(currentTurns) || 0) / 5) * 5);
+  const cached = _remainingTurnsCache.get(bucket);
+  if (cached && Date.now() - cached.ts < REMAINING_TURNS_CACHE_TTL_MS) {
+    return cached.value;
+  }
+  try {
+    const since = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    const rows = db
+      .prepare(
+        `SELECT MAX(message_count) AS len
+         FROM routing_telemetry
+         WHERE timestamp > ? AND session_id IS NOT NULL AND message_count IS NOT NULL
+         GROUP BY session_id
+         HAVING len > ?
+         LIMIT 5000`
+      )
+      .all(since, bucket);
+    let value = null;
+    if (rows.length >= REMAINING_TURNS_MIN_SESSIONS) {
+      const remaining = rows.map((r) => r.len - bucket).sort((a, b) => a - b);
+      value = remaining[Math.floor(remaining.length / 2)];
+    }
+    _remainingTurnsCache.set(bucket, { value, ts: Date.now() });
+    return value;
+  } catch (err) {
+    logger.debug({ err: err.message }, "Telemetry getExpectedRemainingTurns failed");
+    return null;
+  }
+}
+
 module.exports = {
   record,
   query,
@@ -799,6 +934,8 @@ module.exports = {
   getRoutingAccuracy,
   getEscalationStats,
   getQualityByTierAndType,
+  getExpectedRemainingTurns,
+  getCacheEconomics,
   recordSavings,
   getSavingsSummary,
   cleanup,

package/src/routing/verifier.js

@@ -204,6 +204,28 @@ function contentScore(userText, answerText, responseBody) {
   return Math.max(0, Math.min(100, score));
 }
 
+// ---------------------------------------------------------------------------
+// Caveman detection
+// ---------------------------------------------------------------------------
+
+// context/caveman.js appends a brevity instruction tagged with this literal
+// marker whenever CAVEMAN is enabled. Presence in the outbound system prompt
+// is a reliable, config-independent signal that the model was told to be
+// terse — so the length-based effort penalty in contentScore() is a false
+// negative here (short answer = compliant, not lazy) and must not fire.
+const CAVEMAN_MARKER = "[brevity]";
+
+function _cavemanActive(payload) {
+  const s = payload?.system;
+  if (typeof s === "string") return s.includes(CAVEMAN_MARKER);
+  if (Array.isArray(s)) {
+    for (const b of s) {
+      if (typeof b?.text === "string" && b.text.includes(CAVEMAN_MARKER)) return true;
+    }
+  }
+  return false;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -240,11 +262,26 @@ function verify({ payload, responseBody } = {}) {
     ].filter(Boolean);
 
     const score = contentScore(userText, answerText, responseBody);
-    if (reasons.length === 0 && score < CONTENT_SCORE_FAIL_THRESHOLD) {
+    const cavemanActive = _cavemanActive(payload);
+    // When caveman brevity is active the model was explicitly told to be
+    // terse; a short answer is compliant, not lazy, so the length-driven
+    // low-score check would misfire and thrash the cascade. Structural
+    // checks above (language drift, degeneration, truncation, malformed
+    // tools, echo) still run — those catch real failures regardless.
+    if (
+      reasons.length === 0 &&
+      score < CONTENT_SCORE_FAIL_THRESHOLD &&
+      !cavemanActive
+    ) {
       reasons.push(`low-content-score (${score} < ${CONTENT_SCORE_FAIL_THRESHOLD})`);
     }
 
-    return { verdict: reasons.length ? 'fail' : 'pass', score, reasons };
+    return {
+      verdict: reasons.length ? 'fail' : 'pass',
+      score,
+      reasons,
+      cavemanActive,
+    };
   } catch (err) {
     // Fail-open: a broken verifier must never block serving.
     logger.debug({ err: err.message }, '[Verifier] error — failing open');
@@ -263,5 +300,7 @@ module.exports = {
     checkMalformedToolCalls,
     checkEmptyOrEcho,
     contentScore,
+    _cavemanActive,
+    CAVEMAN_MARKER,
   },
 };

package/src/server.js

@@ -1,5 +1,4 @@
 const express = require("express");
-const compression = require("compression");
 const config = require("./config");
 const loggingMiddleware = require("./api/middleware/logging");
 const router = require("./api/router");
@@ -19,7 +18,7 @@ const metrics = require("./metrics");
 const logger = require("./logger");
 const { initialiseMcp } = require("./mcp");
 const { initConfigWatcher, getConfigWatcher } = require("./config/watcher");
-const { initializeHeadroom, shutdownHeadroom, getHeadroomManager } = require("./headroom");
+const { initializeHeadroom, shutdownHeadroom } = require("./headroom");
 const { getWorkerPool, isWorkerPoolReady } = require("./workers/pool");
 const { waitForOllama } = require("./clients/ollama-startup");
 
@@ -196,10 +195,44 @@ async function start() {
     }
   }
 
-  const server = app.listen(config.port, () => {
+  const server = app.listen(config.port, (err) => {
+    // Express 5 invokes this callback on bind errors too (it wires the
+    // callback to the server 'error' event) — without the guard, a failed
+    // bind prints "listening" right before the EADDRINUSE failure.
+    if (err) return;
     console.log(`Claude→Databricks proxy listening on http://localhost:${config.port}`);
   });
 
+  // Surface bind failures to the caller. Without this, EADDRINUSE from a
+  // stale instance is swallowed, and `lynkr wrap`'s readiness probe then
+  // gets answered by the OLD server still holding the port — the new
+  // session silently runs against stale code.
+  await new Promise((resolve, reject) => {
+    server.once("listening", resolve);
+    server.once("error", reject);
+  });
+
+  // TencentDB-Agent-Memory sidecar — non-blocking (first start pulls two
+  // Docker images). Launched after listen so the proxy is usable immediately;
+  // the memory stack's LLM calls route back through Lynkr, which is why
+  // Lynkr must already be accepting requests when the containers come up.
+  if (config.tencentdbMemory?.enabled) {
+    (async () => {
+      try {
+        const tencentdbLauncher = require("./memory/tencentdb-launcher");
+        const result = await tencentdbLauncher.ensureRunning();
+        if (result.started) {
+          logger.info(result.endpoints, "[tdai] TencentDB Agent Memory stack ready");
+          console.log(`TencentDB Agent Memory ready — Panel UI: ${result.endpoints.panel}`);
+        } else {
+          logger.debug({ reason: result.reason }, "[tdai] Sidecar not started");
+        }
+      } catch (err) {
+        logger.warn({ err }, "[tdai] TencentDB memory sidecar failed to start — continuing without it");
+      }
+    })();
+  }
+
   // Classifier bootstrap check — non-blocking, log-only.
   // Detects ollama + confirms the classifier model is pulled. Never auto-
   // installs (that's `lynkr init`'s job); warns and lets scoring fall back

package/src/tools/code-graph.js

@@ -313,9 +313,10 @@ async function getBlastRadius(filePaths, options = {}) {
   if (cached) return cached;
 
   // Query neighbors for each file to estimate blast radius
+  const depth = String(config.codeGraph?.maxDepth ?? 2);
   const result = await execGraph(
     "query",
-    ["get_neighbors", "--files", ...filePaths, "--depth", "2", "--json"],
+    ["get_neighbors", "--files", ...filePaths, "--depth", depth, "--json"],
     ws
   );
   if (!result) return null;
@@ -364,11 +365,11 @@ async function getBlastRadius(filePaths, options = {}) {
  * Uses Graphify's BFS-based query to find related nodes.
  *
  * @param {string[]} filePaths — seed file paths
- * @param {number} [maxFiles=20] — maximum files to return
+ * @param {number} [maxFiles] — maximum files to return (default from config.codeGraph.maxFiles)
  * @param {CodeGraphOptions} [options]
  * @returns {Promise<string[]|null>}
  */
-async function getRelevantContext(filePaths, maxFiles = 20, options = {}) {
+async function getRelevantContext(filePaths, maxFiles = config.codeGraph?.maxFiles ?? 5, options = {}) {
   if (!Array.isArray(filePaths) || filePaths.length === 0) return null;
 
   const ws = resolveWorkspace({ ...options, filePaths });
@@ -419,8 +420,9 @@ async function getComplexitySignals(filePaths, options = {}) {
   if (cached) return cached;
 
   // Run parallel queries: neighbors (blast radius) + god_nodes + graph_stats
+  const signalDepth = String(config.codeGraph?.maxDepth ?? 2);
   const [neighborsResult, godNodesResult, statsResult] = await Promise.all([
-    execGraph("query", ["get_neighbors", "--files", ...filePaths, "--depth", "2", "--json"], ws),
+    execGraph("query", ["get_neighbors", "--files", ...filePaths, "--depth", signalDepth, "--json"], ws),
     execGraph("query", ["god_nodes", "--json"], ws),
     execGraph("query", ["graph_stats", "--json"], ws),
   ]);