lynkr 9.0.2 → 9.1.3

package/src/routing/output-ratios.js

@@ -0,0 +1,57 @@
+/**
+ * Output-token ratio lookup (Phase 2.3).
+ *
+ * Reads data/output-ratios.json (built by scripts/learn-output-ratios.js).
+ * Falls back to hardcoded defaults when the file is absent.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+
+const FILE_PATH = path.join(__dirname, '../../data/output-ratios.json');
+
+const DEFAULT_RATIOS = {
+  simple_qa: 0.30,
+  code_gen: 2.10,
+  code_edit: 1.40,
+  summarization: 0.15,
+  reasoning: 1.50,
+  tool_use: 0.80,
+  default: 0.50,
+};
+
+let _cached = null;
+let _cacheLoadedAt = 0;
+const RELOAD_INTERVAL_MS = 60_000;
+
+function _load() {
+  if (_cached && Date.now() - _cacheLoadedAt < RELOAD_INTERVAL_MS) return _cached;
+  try {
+    if (fs.existsSync(FILE_PATH)) {
+      const data = JSON.parse(fs.readFileSync(FILE_PATH, 'utf8'));
+      if (data?.ratios && typeof data.ratios === 'object') {
+        _cached = { ...DEFAULT_RATIOS, ...data.ratios };
+        _cacheLoadedAt = Date.now();
+        return _cached;
+      }
+    }
+  } catch (err) {
+    logger.debug({ err: err.message }, '[OutputRatios] Load failed, using defaults');
+  }
+  _cached = DEFAULT_RATIOS;
+  _cacheLoadedAt = Date.now();
+  return _cached;
+}
+
+function ratioFor(taskType) {
+  const ratios = _load();
+  const key = (taskType || 'default').toLowerCase();
+  return ratios[key] ?? ratios.default ?? 0.5;
+}
+
+function reload() {
+  _cached = null;
+}
+
+module.exports = { ratioFor, reload, DEFAULT_RATIOS };

package/src/routing/regret-estimator.js

@@ -0,0 +1,91 @@
+/**
+ * Regret estimator (Phase 4.2).
+ *
+ * Periodically samples a fraction of yesterday's requests, re-runs them
+ * through a strictly-better model (Opus), and compares quality. If the
+ * routed model consistently underperforms vs Opus by >10%, this writes an
+ * alert to data/regret-alerts.json.
+ *
+ * Off by default (costs real money). Enable with LYNKR_REGRET_ESTIMATOR=true
+ * and run via cron: `node scripts/sample-regret.js`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+
+const ALERTS_PATH = path.join(__dirname, '../../data/regret-alerts.json');
+
+/**
+ * @param {object} args
+ * @param {Array<{request: object, response: object, model: string, quality: number}>} args.samples
+ * @param {function} args.runOpus — async (request) → { response, quality }
+ * @param {number} args.threshold — fractional underperformance threshold (default 0.10)
+ * @returns {Promise<{ regret, sampledCount, alerts }>}
+ */
+async function estimate(args) {
+  const threshold = args.threshold ?? 0.10;
+  const results = [];
+  for (const s of args.samples) {
+    try {
+      const opus = await args.runOpus(s.request);
+      const delta = (opus.quality - s.quality) / Math.max(1, opus.quality);
+      results.push({
+        model: s.model,
+        routedQuality: s.quality,
+        opusQuality: opus.quality,
+        regret: Math.max(0, delta),
+        underperforming: delta > threshold,
+      });
+    } catch (err) {
+      logger.debug({ err: err.message }, '[RegretEstimator] Opus re-run failed');
+    }
+  }
+
+  const byModel = new Map();
+  for (const r of results) {
+    if (!byModel.has(r.model)) byModel.set(r.model, []);
+    byModel.get(r.model).push(r);
+  }
+
+  const alerts = [];
+  for (const [model, runs] of byModel) {
+    const underperforming = runs.filter(r => r.underperforming).length;
+    const rate = underperforming / runs.length;
+    if (rate > 0.5 && runs.length >= 5) {
+      alerts.push({
+        model,
+        underperformingRate: rate,
+        sampleSize: runs.length,
+        avgRegret: runs.reduce((s, r) => s + r.regret, 0) / runs.length,
+        timestamp: Date.now(),
+      });
+    }
+  }
+
+  if (alerts.length > 0) {
+    try {
+      fs.mkdirSync(path.dirname(ALERTS_PATH), { recursive: true });
+      let existing = [];
+      if (fs.existsSync(ALERTS_PATH)) {
+        try { existing = JSON.parse(fs.readFileSync(ALERTS_PATH, 'utf8')); } catch {}
+      }
+      const out = Array.isArray(existing) ? existing : [];
+      out.push(...alerts);
+      // Keep last 100 alerts
+      const trimmed = out.slice(-100);
+      fs.writeFileSync(ALERTS_PATH, JSON.stringify(trimmed, null, 2));
+    } catch (err) {
+      logger.warn({ err: err.message }, '[RegretEstimator] Alert write failed');
+    }
+  }
+
+  const totalRegret = results.reduce((s, r) => s + r.regret, 0) / Math.max(1, results.length);
+  return { regret: totalRegret, sampledCount: results.length, alerts };
+}
+
+function isEnabled() {
+  return process.env.LYNKR_REGRET_ESTIMATOR === 'true';
+}
+
+module.exports = { estimate, isEnabled };

package/src/routing/reward-pipeline.js

@@ -0,0 +1,62 @@
+/**
+ * Reward pipeline for the LinUCB bandit (Phase 4.1).
+ *
+ * Combines quality score, normalised cost, and normalised latency into a
+ * single scalar reward in [0, 100]. The bandit then rescales to [0, 1].
+ *
+ *   reward = quality - λ·norm_cost·100 - μ·norm_latency·100
+ *
+ * Normalisation uses running min/max so we don't need to pre-compute global
+ * scales.
+ */
+
+const logger = require('../logger');
+
+const DEFAULT_LAMBDA = 0.3;
+const DEFAULT_MU = 0.1;
+
+class RewardPipeline {
+  constructor({ lambda = DEFAULT_LAMBDA, mu = DEFAULT_MU } = {}) {
+    this.lambda = lambda;
+    this.mu = mu;
+    this.costRange = { min: Infinity, max: -Infinity };
+    this.latencyRange = { min: Infinity, max: -Infinity };
+  }
+
+  observe({ cost, latency }) {
+    if (typeof cost === 'number' && cost >= 0) {
+      this.costRange.min = Math.min(this.costRange.min, cost);
+      this.costRange.max = Math.max(this.costRange.max, cost);
+    }
+    if (typeof latency === 'number' && latency >= 0) {
+      this.latencyRange.min = Math.min(this.latencyRange.min, latency);
+      this.latencyRange.max = Math.max(this.latencyRange.max, latency);
+    }
+  }
+
+  _normalize(value, range) {
+    if (!isFinite(range.min) || !isFinite(range.max) || range.max <= range.min) return 0;
+    const v = Math.max(range.min, Math.min(range.max, value));
+    return (v - range.min) / (range.max - range.min);
+  }
+
+  /**
+   * @param {object} obs - { quality: 0-100, cost: dollars, latency: ms }
+   * @returns {number} reward in [0, 100]
+   */
+  reward(obs) {
+    this.observe(obs);
+    const q = typeof obs.quality === 'number' ? obs.quality : 50;
+    const cn = this._normalize(obs.cost ?? 0, this.costRange);
+    const ln = this._normalize(obs.latency ?? 0, this.latencyRange);
+    return Math.max(0, Math.min(100, q - this.lambda * cn * 100 - this.mu * ln * 100));
+  }
+}
+
+let _instance = null;
+function getRewardPipeline() {
+  if (!_instance) _instance = new RewardPipeline();
+  return _instance;
+}
+
+module.exports = { RewardPipeline, getRewardPipeline };

package/src/routing/risk-analyzer.js

@@ -0,0 +1,194 @@
+/**
+ * Risk Analyzer
+ *
+ * Scores a request along a risk axis that is orthogonal to complexity.
+ * A trivially short edit to `auth/middleware.ts` is still high risk and
+ * should not be served by a cheap local model.
+ *
+ * @module routing/risk-analyzer
+ */
+
+const { extractContent } = require('./complexity-analyzer');
+
+// Substring keywords found in file paths or instruction text.
+// Matched case-insensitively as raw substrings, so "auth" hits
+// "src/auth/login.ts" and "authentication".
+const PROTECTED_PATH_KEYWORDS = [
+  'auth', 'oauth', 'jwt', 'session', 'security', 'permission', 'rbac',
+  'payment', 'payments', 'billing', 'invoice', 'subscription',
+  'migration', 'migrations', 'schema',
+  'infra', 'terraform', 'kustomize', 'helm', 'kubernetes',
+  '.github/workflows', '.env', 'secret', 'credential',
+  'api-key', 'api_key', 'apikey', 'token',
+  'webhook', 'admin',
+];
+
+// Whole-word instruction keywords that signal sensitive intent regardless
+// of which files are involved. Higher signal than path keywords because
+// they reflect what the user is *asking for*.
+const HIGH_RISK_INSTRUCTION_KEYWORDS = [
+  'authentication', 'authorization', 'permission', 'security',
+  'payment', 'billing', 'migration', 'database schema',
+  'encrypt', 'decrypt', 'secret', 'credential', 'api key',
+  'production', 'deploy', 'rollout', 'rollback',
+];
+
+// Path-extracting patterns. We look at:
+//   1. Anything that looks like a file path inside the instruction text.
+//   2. Explicit path-like fields in tool inputs (e.g. tool_use blocks).
+const PATH_LIKE_RE = /(?:^|[\s`'"([])([./a-zA-Z0-9_-]+\.[a-zA-Z0-9]{1,8})(?=[\s`'")\]:,;]|$)/g;
+const SLASHED_PATH_RE = /(?:^|[\s`'"([])((?:[a-zA-Z0-9_.-]+\/)+[a-zA-Z0-9_.-]+)(?=[\s`'")\]:,;]|$)/g;
+
+/**
+ * Pull every path-shaped substring out of free-form text.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractPathsFromText(text) {
+  if (!text) return [];
+  const out = new Set();
+  let m;
+  while ((m = PATH_LIKE_RE.exec(text)) !== null) {
+    out.add(m[1]);
+  }
+  while ((m = SLASHED_PATH_RE.exec(text)) !== null) {
+    out.add(m[1]);
+  }
+  return Array.from(out);
+}
+
+/**
+ * Walk every tool_use block in the conversation and collect any string
+ * inputs that look like paths. Catches cases where the model already
+ * called an Edit/Read tool on a sensitive file.
+ * @param {object} payload
+ * @returns {string[]}
+ */
+function extractPathsFromToolUses(payload) {
+  const out = new Set();
+  const messages = payload?.messages;
+  if (!Array.isArray(messages)) return [];
+
+  for (const msg of messages) {
+    if (!Array.isArray(msg?.content)) continue;
+    for (const block of msg.content) {
+      if (block?.type !== 'tool_use' || !block.input) continue;
+      const stack = [block.input];
+      while (stack.length) {
+        const node = stack.pop();
+        if (typeof node === 'string') {
+          if (node.includes('/') || node.includes('.')) {
+            // Treat short tool-input strings that look path-y as paths.
+            if (node.length <= 200) out.add(node);
+          }
+        } else if (Array.isArray(node)) {
+          for (const v of node) stack.push(v);
+        } else if (node && typeof node === 'object') {
+          for (const v of Object.values(node)) stack.push(v);
+        }
+      }
+    }
+  }
+  return Array.from(out);
+}
+
+/**
+ * Find which keywords from `keywords` appear (case-insensitively) inside
+ * any of `haystack`. Substring match — by design — so "auth" matches
+ * both "src/auth/login.ts" and the word "authorization".
+ * @param {string[]} keywords
+ * @param {string[]} haystack
+ * @returns {string[]} hit keywords, sorted
+ */
+function findHits(keywords, haystack) {
+  const hits = new Set();
+  const joined = haystack.join('\n').toLowerCase();
+  for (const kw of keywords) {
+    if (joined.includes(kw.toLowerCase())) hits.add(kw);
+  }
+  return Array.from(hits).sort();
+}
+
+/**
+ * Analyze the risk level of a request.
+ *
+ * Risk is orthogonal to complexity:
+ *   - low    → no protected paths or sensitive keywords detected
+ *   - medium → protected paths *or* a read-only task on a protected area
+ *   - high   → instruction explicitly names sensitive domain logic,
+ *              or protected paths combined with a write-intent task
+ *
+ * @param {object} payload - Anthropic-format request payload
+ * @returns {{ level: 'low'|'medium'|'high',
+ *             reason: string,
+ *             pathHits: string[],
+ *             instructionHits: string[],
+ *             paths: string[] }}
+ */
+function analyzeRisk(payload) {
+  const instructionText = extractContent(payload) || '';
+  const lowText = instructionText.toLowerCase();
+
+  const textPaths = extractPathsFromText(instructionText);
+  const toolPaths = extractPathsFromToolUses(payload);
+  const allPaths = Array.from(new Set([...textPaths, ...toolPaths]));
+
+  // Instruction-level hits scan the raw text. Path-level hits scan only
+  // the extracted path strings so phrases like "authentication is hard"
+  // don't double-fire as a path hit.
+  const instructionHits = findHits(HIGH_RISK_INSTRUCTION_KEYWORDS, [instructionText]);
+  const pathHits = findHits(PROTECTED_PATH_KEYWORDS, allPaths.length ? allPaths : []);
+  // Also let path keywords match against the instruction text — covers
+  // "update the auth flow" with no path mentioned.
+  const textPathHits = findHits(PROTECTED_PATH_KEYWORDS, [instructionText]);
+  const mergedPathHits = Array.from(new Set([...pathHits, ...textPathHits])).sort();
+
+  if (instructionHits.length > 0) {
+    return {
+      level: 'high',
+      reason: 'High-risk instruction keyword detected.',
+      pathHits: mergedPathHits,
+      instructionHits,
+      paths: allPaths,
+    };
+  }
+
+  if (mergedPathHits.length > 0) {
+    // Read-only intent on a protected area is medium, not high.
+    // Heuristic: presence of explain/summarize/read verbs.
+    const readOnly = /\b(explain|summarize|describe|what does|walk me through|read|show|list|search|find|grep|locate)\b/i.test(lowText);
+    if (readOnly) {
+      return {
+        level: 'medium',
+        reason: 'Protected paths involved but task appears read-only.',
+        pathHits: mergedPathHits,
+        instructionHits: [],
+        paths: allPaths,
+      };
+    }
+    return {
+      level: 'high',
+      reason: 'Protected path referenced with write-capable intent.',
+      pathHits: mergedPathHits,
+      instructionHits: [],
+      paths: allPaths,
+    };
+  }
+
+  return {
+    level: 'low',
+    reason: 'No risk signals detected.',
+    pathHits: [],
+    instructionHits: [],
+    paths: allPaths,
+  };
+}
+
+module.exports = {
+  analyzeRisk,
+  PROTECTED_PATH_KEYWORDS,
+  HIGH_RISK_INSTRUCTION_KEYWORDS,
+  // Exposed for tests
+  extractPathsFromText,
+  extractPathsFromToolUses,
+};

package/src/routing/risk-classifier.js

@@ -0,0 +1,130 @@
+/**
+ * Risk classifier (Phase 3.4).
+ *
+ * Replaces the regex-based risk-analyzer with a small logistic-regression
+ * model trained on TF-IDF of unigrams + bigrams. Bootstrap labels come from
+ * the existing regex matcher; subsequent training uses telemetry-flagged
+ * outcomes (set the request header `x-lynkr-risk-confirmed: true` to mark a
+ * request as truly risky for training).
+ *
+ * Falls back to the existing regex analyzer when no model artifact is present
+ * at data/risk-classifier.json. Model weights are JSON-serializable so they
+ * load fast and can be diffed in PRs.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+const { analyzeRisk: regexAnalyzeRisk } = require('./risk-analyzer');
+
+const MODEL_PATH = path.join(__dirname, '../../data/risk-classifier.json');
+const DECISION_THRESHOLD = 0.5;
+
+let _model = null;
+let _modelLoaded = false;
+
+function _tokenize(text) {
+  if (!text || typeof text !== 'string') return [];
+  return text.toLowerCase().split(/[^a-z0-9_\-/.]+/).filter(Boolean);
+}
+
+function _features(text) {
+  const tokens = _tokenize(text);
+  const out = new Map();
+  for (let i = 0; i < tokens.length; i++) {
+    out.set(tokens[i], (out.get(tokens[i]) || 0) + 1);
+    if (i + 1 < tokens.length) {
+      const bigram = `${tokens[i]} ${tokens[i + 1]}`;
+      out.set(bigram, (out.get(bigram) || 0) + 1);
+    }
+  }
+  return out;
+}
+
+function _loadModel() {
+  if (_modelLoaded) return _model;
+  _modelLoaded = true;
+  try {
+    if (!fs.existsSync(MODEL_PATH)) return null;
+    const raw = JSON.parse(fs.readFileSync(MODEL_PATH, 'utf8'));
+    if (!raw?.weights || !raw?.bias) return null;
+    _model = raw;
+    return _model;
+  } catch (err) {
+    logger.debug({ err: err.message }, '[RiskClassifier] Model load failed');
+    return null;
+  }
+}
+
+function _sigmoid(z) {
+  if (z >= 0) return 1 / (1 + Math.exp(-z));
+  const ez = Math.exp(z);
+  return ez / (1 + ez);
+}
+
+function _predict(text, model) {
+  const feats = _features(text);
+  let z = model.bias;
+  for (const [tok, count] of feats) {
+    const w = model.weights[tok];
+    if (typeof w === 'number') z += w * count;
+  }
+  return _sigmoid(z);
+}
+
+/**
+ * Drop-in replacement for analyzeRisk(payload).
+ * Returns { level: 'low'|'medium'|'high', score, ...regexHits } so it's
+ * compatible with the existing telemetry pipeline.
+ */
+function analyzeRisk(payload) {
+  // Always run the regex analyzer for hit details (kept for telemetry).
+  const regexResult = regexAnalyzeRisk(payload);
+
+  const model = _loadModel();
+  if (!model) return regexResult;
+
+  // Build the text we feed to the classifier: latest user message + tool defs + system fingerprint
+  let text = '';
+  if (Array.isArray(payload?.messages)) {
+    for (let i = payload.messages.length - 1; i >= 0; i--) {
+      const msg = payload.messages[i];
+      if (msg?.role === 'user') {
+        if (typeof msg.content === 'string') text = msg.content;
+        else if (Array.isArray(msg.content)) {
+          text = msg.content.filter(b => b?.type === 'text').map(b => b.text).join(' ');
+        }
+        break;
+      }
+    }
+  }
+  if (typeof payload?.system === 'string') text += ' ' + payload.system;
+
+  const prob = _predict(text, model);
+  let level;
+  if (prob >= 0.75) level = 'high';
+  else if (prob >= DECISION_THRESHOLD) level = 'medium';
+  else level = 'low';
+
+  // Reconcile with regex: if classifier disagrees with regex by a lot, prefer the stricter signal.
+  // (We never want to *downgrade* a regex-flagged high-risk request silently.)
+  if (regexResult?.level === 'high' && level !== 'high') level = 'high';
+
+  return {
+    ...regexResult,
+    level,
+    score: prob,
+    classifierUsed: true,
+  };
+}
+
+function reloadModel() {
+  _modelLoaded = false;
+  _model = null;
+}
+
+module.exports = {
+  analyzeRisk,
+  reloadModel,
+  _internal: { _features, _predict },
+};

package/src/routing/shadow-mode.js

@@ -0,0 +1,77 @@
+/**
+ * Shadow-mode policy A/B testing (Phase 4.4).
+ *
+ * Lets us test a new routing policy against production without serving its
+ * decisions. The shadow policy runs alongside the active policy, makes its
+ * decision, and that decision is logged. A weekly comparison job
+ * (scripts/compare-policies.js) summarises agreement, cost delta, and (via
+ * the regret estimator) projected quality delta on the disagreed-on subset.
+ *
+ * Activation:
+ *   - Set LYNKR_SHADOW_POLICY=<name> to enable
+ *   - Implement and register policies via registerPolicy()
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+
+const LOG_PATH = path.join(__dirname, '../../data/shadow-decisions.jsonl');
+
+const _registry = new Map();
+
+function registerPolicy(name, fn) {
+  if (typeof fn !== 'function') throw new Error('Policy must be a function');
+  _registry.set(name, fn);
+}
+
+function isEnabled() {
+  return !!process.env.LYNKR_SHADOW_POLICY && _registry.has(process.env.LYNKR_SHADOW_POLICY);
+}
+
+function getShadowPolicy() {
+  if (!isEnabled()) return null;
+  return _registry.get(process.env.LYNKR_SHADOW_POLICY);
+}
+
+function _appendLog(entry) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, JSON.stringify(entry) + '\n');
+  } catch (err) {
+    logger.debug({ err: err.message }, '[ShadowMode] Log append failed');
+  }
+}
+
+/**
+ * Compare active and shadow decisions on the same payload, log the result.
+ * Does NOT change which decision is served — the caller uses activeDecision.
+ */
+async function compareAndLog({ payload, activeDecision, shadowFn }) {
+  if (!shadowFn) return null;
+  let shadowDecision;
+  try {
+    shadowDecision = await shadowFn(payload);
+  } catch (err) {
+    logger.debug({ err: err.message }, '[ShadowMode] Shadow policy failed');
+    return null;
+  }
+  const agree = activeDecision.provider === shadowDecision?.provider
+    && activeDecision.model === shadowDecision?.model;
+  _appendLog({
+    timestamp: Date.now(),
+    policy: process.env.LYNKR_SHADOW_POLICY,
+    agree,
+    active: { provider: activeDecision.provider, model: activeDecision.model, tier: activeDecision.tier, score: activeDecision.score },
+    shadow: shadowDecision ? { provider: shadowDecision.provider, model: shadowDecision.model, tier: shadowDecision.tier, score: shadowDecision.score } : null,
+  });
+  return { agree, shadow: shadowDecision };
+}
+
+module.exports = {
+  registerPolicy,
+  isEnabled,
+  getShadowPolicy,
+  compareAndLog,
+  LOG_PATH,
+};

package/src/routing/telemetry.js

@@ -105,6 +105,9 @@ function init() {
 
       CREATE INDEX IF NOT EXISTS idx_telemetry_timestamp
         ON routing_telemetry(timestamp);
+
+      CREATE INDEX IF NOT EXISTS idx_telemetry_session_id
+        ON routing_telemetry(session_id, timestamp);
     `);
 
     logger.info({ dbPath }, "Routing telemetry database initialised");
@@ -233,6 +236,10 @@ function query(filters = {}) {
     clauses.push("timestamp >= @since");
     params.since = filters.since;
   }
+  if (filters.session_id) {
+    clauses.push("session_id = @session_id");
+    params.session_id = filters.session_id;
+  }
 
   const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
   const limit = filters.limit ?? 100;