lynkr 9.10.0 → 9.12.0

package/src/routing/telemetry.js

@@ -165,6 +165,16 @@ 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"],
+      // Lens dashboard — per-request cache counters from the provider's
+      // usage payload. NULL on rows recorded before capture began (or by
+      // providers that report none) — "not measured" is distinct from 0.
+      ["cache_read_tokens", "INTEGER"],
+      ["cache_creation_tokens", "INTEGER"],
     ];
     for (const [col, type] of additiveCols) {
       if (!existingCols.has(col)) {
@@ -226,7 +236,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, cache_read_tokens, cache_creation_tokens
         ) VALUES (
           @request_id, @session_id, @timestamp, @complexity_score, @tier,
           @agentic_type, @tool_count, @input_tokens, @message_count, @request_type,
@@ -234,7 +245,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, @cache_read_tokens, @cache_creation_tokens
         )`
       );
       if (!insert) return;
@@ -280,6 +292,13 @@ 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)),
+        cache_read_tokens: data.cache_read_tokens ?? null,
+        cache_creation_tokens: data.cache_creation_tokens ?? null,
       });
     } catch (err) {
       logger.debug({ err: err.message }, "Telemetry record failed");
@@ -791,6 +810,323 @@ 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;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Lens dashboard queries
+// ---------------------------------------------------------------------------
+
+/**
+ * MEASURED cache savings — backward-looking, auditable against the bill:
+ * for rows that carried cache counters, what did cache reads actually save
+ * vs. paying full input price? Distinct from the projected figures in
+ * getCacheEconomics. Also reports the hit ratio per (provider, model).
+ *
+ * @param {Object} [opts] {since}
+ * @returns {{measuredSavedUsd:number, rowsMeasured:number, perModel:Array}|null}
+ */
+function getMeasuredCacheSavings(opts = {}) {
+  if (!init()) return null;
+  const since = opts.since ?? Date.now() - 7 * 24 * 60 * 60 * 1000;
+  try {
+    const rows = db
+      .prepare(
+        `SELECT provider, model, COUNT(*) n,
+                SUM(COALESCE(cache_read_tokens,0)) rd,
+                SUM(COALESCE(cache_creation_tokens,0)) cr,
+                SUM(COALESCE(input_tokens,0)) inp
+         FROM routing_telemetry
+         WHERE timestamp > ? AND cache_read_tokens IS NOT NULL
+         GROUP BY provider, model`
+      )
+      .all(since);
+    const { resolveCacheEconomics } = require("./cache-economics");
+    let saved = 0;
+    let measured = 0;
+    const perModel = [];
+    for (const r of rows) {
+      measured += r.n;
+      const econ = resolveCacheEconomics(r.provider, r.model);
+      const savedUsd = econ.unknownPricing
+        ? null
+        : (r.rd * Math.max(0, econ.inputPerM - econ.cacheReadPerM)) / 1_000_000;
+      if (savedUsd != null) saved += savedUsd;
+      const total = r.rd + r.cr + r.inp;
+      perModel.push({
+        provider: r.provider,
+        model: r.model,
+        requests: r.n,
+        cacheReadTokens: r.rd,
+        hitRatio: total > 0 ? r.rd / total : null,
+        savedUsd,
+      });
+    }
+    perModel.sort((a, b) => (a.hitRatio ?? 1) - (b.hitRatio ?? 1));
+    return { measuredSavedUsd: saved, rowsMeasured: measured, perModel };
+  } catch (err) {
+    logger.debug({ err: err.message }, "Telemetry getMeasuredCacheSavings failed");
+    return null;
+  }
+}
+
+/**
+ * Session drill-down: per-model mix, context-growth series, tool totals.
+ * @param {string} sessionId
+ */
+function getSessionDetail(sessionId) {
+  if (!sessionId || !init()) return null;
+  try {
+    const rows = db
+      .prepare(
+        `SELECT timestamp, provider, model, tier, routing_method, input_tokens,
+                output_tokens, cost_usd, latency_ms, tool_count, tool_calls_made,
+                cache_read_tokens, cache_creation_tokens, status_code, error_type,
+                pinned, switch_reason, message_count
+         FROM routing_telemetry WHERE session_id = ? ORDER BY timestamp ASC LIMIT 2000`
+      )
+      .all(sessionId);
+    if (!rows.length) return null;
+
+    const perModel = new Map();
+    let toolCalls = 0;
+    let cost = 0;
+    for (const r of rows) {
+      const key = `${r.provider}:${r.model}`;
+      const m = perModel.get(key) ?? {
+        provider: r.provider, model: r.model, requests: 0,
+        inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, costUsd: 0,
+      };
+      m.requests++;
+      m.inputTokens += r.input_tokens ?? 0;
+      m.outputTokens += r.output_tokens ?? 0;
+      m.cacheReadTokens += r.cache_read_tokens ?? 0;
+      m.costUsd += r.cost_usd ?? 0;
+      perModel.set(key, m);
+      toolCalls += r.tool_calls_made ?? 0;
+      cost += r.cost_usd ?? 0;
+    }
+
+    return {
+      sessionId,
+      requests: rows.length,
+      totalCostUsd: cost,
+      toolCalls,
+      firstSeen: rows[0].timestamp,
+      lastSeen: rows[rows.length - 1].timestamp,
+      models: [...perModel.values()].sort((a, b) => b.costUsd - a.costUsd),
+      // Input (context) tokens per call over the session — the distiller
+      // cliff and frozen-block plateau are visible here.
+      contextSeries: rows.map((r) => ({
+        t: r.timestamp,
+        inputTokens: r.input_tokens ?? 0,
+        cacheReadTokens: r.cache_read_tokens ?? null,
+        tier: r.tier,
+        model: r.model,
+      })),
+      rows,
+    };
+  } catch (err) {
+    logger.debug({ err: err.message }, "Telemetry getSessionDetail failed");
+    return null;
+  }
+}
+
+// Pivot explorer — every metric/dimension is whitelisted; params never reach
+// SQL as strings.
+const ANALYTICS_METRICS = {
+  spend: "SUM(COALESCE(cost_usd,0))",
+  tokens: "SUM(COALESCE(input_tokens,0)+COALESCE(output_tokens,0))",
+  requests: "COUNT(*)",
+  sessions: "COUNT(DISTINCT session_id)",
+};
+const ANALYTICS_DIMS = {
+  provider: "provider",
+  model: "model",
+  tier: "tier",
+  request_type: "request_type",
+  routing_method: "routing_method",
+  switch_reason: "switch_reason",
+  day: "date(timestamp/1000, 'unixepoch')",
+};
+
+/**
+ * Generic Metric × Dimension (× Stack) pivot with KPI row and
+ * period-over-period deltas (suppressed when the prior window is thin).
+ *
+ * @param {Object} [opts] {metric, by, stack, since, until}
+ */
+function getAnalytics(opts = {}) {
+  if (!init()) return null;
+  const metricExpr = ANALYTICS_METRICS[opts.metric] ?? ANALYTICS_METRICS.spend;
+  const metric = ANALYTICS_METRICS[opts.metric] ? opts.metric : "spend";
+  const byExpr = ANALYTICS_DIMS[opts.by] ?? ANALYTICS_DIMS.provider;
+  const by = ANALYTICS_DIMS[opts.by] ? opts.by : "provider";
+  const stackExpr = opts.stack && ANALYTICS_DIMS[opts.stack] ? ANALYTICS_DIMS[opts.stack] : null;
+  const until = opts.until ?? Date.now();
+  const since = opts.since ?? until - 7 * 24 * 60 * 60 * 1000;
+
+  try {
+    const groupCols = stackExpr ? `${byExpr} AS dim, ${stackExpr} AS stack` : `${byExpr} AS dim`;
+    const groupBy = stackExpr ? "GROUP BY dim, stack" : "GROUP BY dim";
+    const rows = db
+      .prepare(
+        `SELECT ${groupCols}, ${metricExpr} AS value
+         FROM routing_telemetry
+         WHERE timestamp BETWEEN ? AND ?
+         ${groupBy} ORDER BY value DESC LIMIT 500`
+      )
+      .all(since, until);
+
+    const kpiRow = (lo, hi) =>
+      db
+        .prepare(
+          `SELECT SUM(COALESCE(cost_usd,0)) spend,
+                  SUM(COALESCE(input_tokens,0)+COALESCE(output_tokens,0)) tokens,
+                  COUNT(*) requests,
+                  COUNT(DISTINCT session_id) sessions
+           FROM routing_telemetry WHERE timestamp BETWEEN ? AND ?`
+        )
+        .get(lo, hi);
+    const kpis = kpiRow(since, until);
+    const prev = kpiRow(since - (until - since), since);
+    // Thin prior window → deltas are noise, suppress rather than mislead.
+    const kpiDeltas = (prev?.requests ?? 0) >= 10
+      ? {
+        spend: kpis.spend - (prev.spend ?? 0),
+        tokens: kpis.tokens - (prev.tokens ?? 0),
+        requests: kpis.requests - prev.requests,
+        sessions: kpis.sessions - (prev.sessions ?? 0),
+      }
+      : null;
+
+    return { metric, by, stack: stackExpr ? opts.stack : null, since, until, rows, kpis, kpiDeltas };
+  } catch (err) {
+    logger.debug({ err: err.message }, "Telemetry getAnalytics failed");
+    return null;
+  }
+}
+
 module.exports = {
   record,
   query,
@@ -799,6 +1135,11 @@ module.exports = {
   getRoutingAccuracy,
   getEscalationStats,
   getQualityByTierAndType,
+  getExpectedRemainingTurns,
+  getCacheEconomics,
+  getMeasuredCacheSavings,
+  getSessionDetail,
+  getAnalytics,
   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),
   ]);