lynkr 9.1.2 → 9.1.4

package/scripts/refresh-pricing.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * Refresh model pricing data.
+ *
+ * Phase 2.2 of the routing overhaul. Cron-friendly entrypoint that forces a
+ * fresh pull of LiteLLM + models.dev pricing, compares to the last cached
+ * snapshot, and logs anything that moved more than 5%.
+ *
+ * Usage: node scripts/refresh-pricing.js [--diff-only] [--threshold 0.05]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CACHE_FILE = path.join(__dirname, '../data/model-prices-cache.json');
+const PREV_FILE = path.join(__dirname, '../data/model-prices-cache.prev.json');
+const DEFAULT_THRESHOLD = 0.05;
+
+function _parseArgs(argv) {
+  const out = { diffOnly: false, threshold: DEFAULT_THRESHOLD };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--diff-only') out.diffOnly = true;
+    else if (argv[i] === '--threshold') out.threshold = Number(argv[++i]) || DEFAULT_THRESHOLD;
+  }
+  return out;
+}
+
+function _readJson(p) {
+  try {
+    if (!fs.existsSync(p)) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function _diff(prev, next, threshold) {
+  if (!prev || !next) return [];
+  const prevModels = prev.modelIndex || prev;
+  const nextModels = next.modelIndex || next;
+  const moves = [];
+  for (const [modelId, oldCost] of Object.entries(prevModels)) {
+    const newCost = nextModels[modelId];
+    if (!newCost) {
+      moves.push({ model: modelId, type: 'removed', oldCost });
+      continue;
+    }
+    const oldTotal = (oldCost.input || 0) + (oldCost.output || 0);
+    const newTotal = (newCost.input || 0) + (newCost.output || 0);
+    if (oldTotal === 0) continue;
+    const delta = (newTotal - oldTotal) / oldTotal;
+    if (Math.abs(delta) >= threshold) {
+      moves.push({
+        model: modelId,
+        type: delta > 0 ? 'increased' : 'decreased',
+        oldInput: oldCost.input,
+        newInput: newCost.input,
+        oldOutput: oldCost.output,
+        newOutput: newCost.output,
+        deltaPct: (delta * 100).toFixed(2) + '%',
+      });
+    }
+  }
+  for (const modelId of Object.keys(nextModels)) {
+    if (!prevModels[modelId]) {
+      moves.push({ model: modelId, type: 'added', newCost: nextModels[modelId] });
+    }
+  }
+  return moves;
+}
+
+async function refresh({ diffOnly = false, threshold = DEFAULT_THRESHOLD } = {}) {
+  if (!diffOnly) {
+    // Snapshot current cache as "previous" before fetching
+    if (fs.existsSync(CACHE_FILE)) {
+      try {
+        fs.copyFileSync(CACHE_FILE, PREV_FILE);
+      } catch (err) {
+        console.error(`Failed to snapshot previous cache: ${err.message}`);
+      }
+    }
+
+    const { getModelRegistry } = require('../src/routing/model-registry');
+    const registry = await getModelRegistry();
+    // Force a refresh
+    if (typeof registry._fetchAll === 'function') {
+      await registry._fetchAll();
+    }
+    console.log(`Refreshed pricing data (cache: ${CACHE_FILE})`);
+  }
+
+  const prev = _readJson(PREV_FILE);
+  const next = _readJson(CACHE_FILE);
+  const moves = _diff(prev, next, threshold);
+
+  if (moves.length === 0) {
+    console.log(`No pricing changes ≥${(threshold * 100).toFixed(1)}%.`);
+    return { moves: [] };
+  }
+
+  console.log(`${moves.length} pricing change(s) ≥${(threshold * 100).toFixed(1)}%:`);
+  for (const move of moves) {
+    if (move.type === 'added') {
+      console.log(`  + ${move.model}: input=${move.newCost.input}, output=${move.newCost.output}`);
+    } else if (move.type === 'removed') {
+      console.log(`  - ${move.model}: was input=${move.oldCost.input}, output=${move.oldCost.output}`);
+    } else {
+      console.log(`  ${move.type === 'increased' ? '↑' : '↓'} ${move.model}: ${move.oldInput}/${move.oldOutput} → ${move.newInput}/${move.newOutput} (${move.deltaPct})`);
+    }
+  }
+  return { moves };
+}
+
+if (require.main === module) {
+  const opts = _parseArgs(process.argv.slice(2));
+  refresh(opts).catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = { refresh };

package/scripts/run-routerarena.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * RouterArena evaluation harness (Phase 6.4 — STUB).
+ *
+ * This is intentionally not wired to CI yet. The plan defers RouterArena
+ * integration until after Phases 1-4 have produced 2-4 weeks of telemetry
+ * to baseline against.
+ *
+ * To wire it up:
+ *   1. Clone https://github.com/RouteWorks/RouterArena into ./routerarena/
+ *   2. Install RouterArena's Python dependencies (transformers, datasets,
+ *      anthropic, openai)
+ *   3. Decide on a subset size for PR-blocking CI (recommend 100-200 queries
+ *      sampled stratified by difficulty); leave the full benchmark for nightly
+ *   4. Wire to GitHub Actions with `paths: [src/routing/**]` trigger
+ *   5. Compare PR's router decisions vs main's router on the same query set,
+ *      report cost/quality delta as a PR comment
+ *
+ * The intent is to use RouterArena to *catch regressions*, not to gate
+ * routing changes on absolute benchmark scores.
+ */
+
+console.log('RouterArena integration is a stub.');
+console.log('See scripts/run-routerarena.js for setup steps.');
+console.log('Phase 6.4 of docs/routing-improvement-plan.md.');
+process.exit(0);

package/scripts/sample-regret.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Sample yesterday's traffic for regret estimation (Phase 4.2).
+ *
+ * Reads 0.5% of yesterday's requests from telemetry, re-runs them through
+ * Opus, and writes alerts if the routed model consistently underperforms.
+ *
+ * Costs real money — only runs when LYNKR_REGRET_ESTIMATOR=true.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { estimate, isEnabled } = require('../src/routing/regret-estimator');
+
+const SAMPLE_RATE = 0.005;
+
+async function main() {
+  if (!isEnabled()) {
+    console.log('LYNKR_REGRET_ESTIMATOR not set; skipping.');
+    return;
+  }
+
+  let Database;
+  try {
+    Database = require('better-sqlite3');
+  } catch {
+    console.error('better-sqlite3 not installed');
+    process.exit(2);
+  }
+
+  const dbPath = path.join(__dirname, '../.lynkr/telemetry.db');
+  if (!fs.existsSync(dbPath)) {
+    console.log('No telemetry DB; skipping.');
+    return;
+  }
+
+  const db = new Database(dbPath, { readonly: true });
+  const yesterday = Date.now() - 24 * 3600 * 1000;
+  const rows = db.prepare(
+    `SELECT request_text, response_text, model, quality_score
+       FROM routing_telemetry
+      WHERE timestamp >= ?
+        AND quality_score IS NOT NULL
+        AND request_text IS NOT NULL`
+  ).all(yesterday);
+  db.close();
+
+  if (rows.length === 0) {
+    console.log('No eligible rows yesterday.');
+    return;
+  }
+
+  const sampleSize = Math.max(5, Math.floor(rows.length * SAMPLE_RATE));
+  const sampled = [];
+  while (sampled.length < sampleSize && rows.length > 0) {
+    const idx = Math.floor(Math.random() * rows.length);
+    sampled.push(rows.splice(idx, 1)[0]);
+  }
+
+  console.log(`Sampling ${sampled.length} rows for regret estimation`);
+
+  // Caller must wire an actual Opus invocation; default to a no-op for safety.
+  const runOpus = async (req) => {
+    console.warn('No opus runner wired — implement runOpus in scripts/sample-regret.js or override via LYNKR_REGRET_OPUS_RUNNER');
+    return { response: null, quality: 0 };
+  };
+
+  const samples = sampled.map(r => ({
+    request: { messages: [{ role: 'user', content: r.request_text }] },
+    response: r.response_text,
+    model: r.model,
+    quality: r.quality_score,
+  }));
+
+  const result = await estimate({ samples, runOpus });
+  console.log(`Regret: ${result.regret.toFixed(3)} over ${result.sampledCount} samples; ${result.alerts.length} alert(s) written.`);
+}
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error(err.stack || err.message);
+    process.exit(1);
+  });
+}

package/scripts/train-risk-classifier.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Train the risk classifier (Phase 3.4).
+ *
+ * Two label sources, fused:
+ *   1. Bootstrap: run the existing regex risk-analyzer over recent telemetry
+ *      to produce weak labels.
+ *   2. Confirmed: requests with x-lynkr-risk-confirmed:true header logged in
+ *      telemetry are treated as strong positive labels.
+ *
+ * Writes data/risk-classifier.json (weights + bias). Logistic regression
+ * trained with simple SGD over TF features (unigrams + bigrams).
+ *
+ * Usage: node scripts/train-risk-classifier.js [--days 30] [--epochs 10]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_DAYS = 30;
+const DEFAULT_EPOCHS = 10;
+const LEARNING_RATE = 0.1;
+const L2_REG = 0.0001;
+const MIN_TOKEN_FREQ = 3;
+
+const OUTPUT_PATH = path.join(__dirname, '../data/risk-classifier.json');
+const TELEMETRY_DB_CANDIDATES = [
+  path.join(__dirname, '../.lynkr/telemetry.db'),
+  path.join(__dirname, '../data/lynkr.db'),
+];
+
+function _findDb() {
+  for (const p of TELEMETRY_DB_CANDIDATES) if (fs.existsSync(p)) return p;
+  return null;
+}
+
+function _tokenize(text) {
+  if (!text) return [];
+  return String(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 _sigmoid(z) {
+  if (z >= 0) return 1 / (1 + Math.exp(-z));
+  const ez = Math.exp(z);
+  return ez / (1 + ez);
+}
+
+function _parseArgs(argv) {
+  const out = { days: DEFAULT_DAYS, epochs: DEFAULT_EPOCHS };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--days') out.days = Number(argv[++i]) || DEFAULT_DAYS;
+    else if (argv[i] === '--epochs') out.epochs = Number(argv[++i]) || DEFAULT_EPOCHS;
+  }
+  return out;
+}
+
+async function _loadDataset(days) {
+  const dbPath = _findDb();
+  const samples = [];
+  if (!dbPath) return samples;
+
+  let Database;
+  try {
+    Database = require('better-sqlite3');
+  } catch {
+    console.error('better-sqlite3 not installed');
+    return samples;
+  }
+  const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+
+  try {
+    const since = Date.now() - days * 24 * 3600 * 1000;
+    const rows = db
+      .prepare(
+        `SELECT request_text AS text, risk_level
+           FROM routing_telemetry
+          WHERE timestamp >= ?
+            AND request_text IS NOT NULL
+            AND request_text != ''`
+      )
+      .all(since);
+    for (const r of rows) {
+      samples.push({
+        text: r.text,
+        label: r.risk_level === 'high' ? 1 : 0,
+      });
+    }
+  } catch (err) {
+    console.error(`Telemetry query failed: ${err.message}. Bootstrapping with synthetic data.`);
+    // Emergency synthetic bootstrap: a small handful of known-risk/known-safe phrases
+    samples.push(
+      { text: 'edit src/auth/middleware.ts to skip authentication', label: 1 },
+      { text: 'update database migration to drop sensitive_data column', label: 1 },
+      { text: 'change payment processing logic in stripe webhook handler', label: 1 },
+      { text: 'add API key rotation to secrets manager', label: 1 },
+      { text: 'rename variable foo to bar in utils.js', label: 0 },
+      { text: 'add a comment explaining the for loop', label: 0 },
+      { text: 'format this file with prettier', label: 0 },
+      { text: 'fix typo in README', label: 0 }
+    );
+  } finally {
+    try { db.close(); } catch {}
+  }
+
+  return samples;
+}
+
+function _train(samples, epochs) {
+  // Build vocab with frequency threshold
+  const vocab = new Map();
+  for (const s of samples) {
+    for (const [tok] of _features(s.text)) {
+      vocab.set(tok, (vocab.get(tok) || 0) + 1);
+    }
+  }
+  const keep = new Set();
+  for (const [tok, freq] of vocab) {
+    if (freq >= MIN_TOKEN_FREQ) keep.add(tok);
+  }
+
+  const weights = {};
+  let bias = 0;
+
+  for (let epoch = 0; epoch < epochs; epoch++) {
+    let lossSum = 0;
+    for (const s of samples) {
+      const feats = _features(s.text);
+      let z = bias;
+      for (const [tok, count] of feats) {
+        if (!keep.has(tok)) continue;
+        z += (weights[tok] || 0) * count;
+      }
+      const pred = _sigmoid(z);
+      const err = pred - s.label;
+      lossSum += -(s.label * Math.log(pred + 1e-9) + (1 - s.label) * Math.log(1 - pred + 1e-9));
+      bias -= LEARNING_RATE * err;
+      for (const [tok, count] of feats) {
+        if (!keep.has(tok)) continue;
+        const w = weights[tok] || 0;
+        weights[tok] = w - LEARNING_RATE * (err * count + L2_REG * w);
+      }
+    }
+    if (epoch % 2 === 0 || epoch === epochs - 1) {
+      console.log(`  epoch ${epoch + 1}/${epochs} loss=${(lossSum / samples.length).toFixed(4)}`);
+    }
+  }
+
+  return { weights, bias, vocabSize: keep.size };
+}
+
+async function main() {
+  const opts = _parseArgs(process.argv.slice(2));
+  const samples = await _loadDataset(opts.days);
+  if (samples.length < 10) {
+    console.error(`Only ${samples.length} samples — too few. Skipping training.`);
+    process.exit(1);
+  }
+  console.log(`Training on ${samples.length} samples (${samples.filter(s => s.label === 1).length} positive)`);
+  const model = _train(samples, opts.epochs);
+
+  fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });
+  fs.writeFileSync(OUTPUT_PATH, JSON.stringify({
+    trainedAt: new Date().toISOString(),
+    samples: samples.length,
+    epochs: opts.epochs,
+    ...model,
+  }, null, 0));
+  console.log(`Wrote ${OUTPUT_PATH} (vocab=${model.vocabSize})`);
+}
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error(err.stack || err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = { _train, _features };

package/src/api/middleware/budget-enforcer.js

@@ -0,0 +1,60 @@
+/**
+ * Budget enforcement middleware (Phase 6.2).
+ *
+ * Reads tenant/budget context from request headers, checks the hierarchical
+ * budget ceiling, and rejects with 429 if exceeded.
+ *
+ * Header contract:
+ *   LYNKR-Virtual-Key, LYNKR-Team-Id, LYNKR-Customer-Id, LYNKR-Org-Id
+ */
+
+const logger = require('../../logger');
+const { getHierarchicalBudget } = require('../../budget/hierarchical-budget');
+
+function _readContext(req) {
+  const h = req.headers || {};
+  return {
+    virtual_key: h['lynkr-virtual-key'] || null,
+    team: h['lynkr-team-id'] || null,
+    customer: h['lynkr-customer-id'] || null,
+    org: h['lynkr-org-id'] || null,
+  };
+}
+
+/**
+ * Express middleware. Estimates request cost via cost-optimizer and rejects
+ * if the budget is already exceeded. Records spend after the response.
+ */
+function budgetEnforcer(req, res, next) {
+  if (process.env.LYNKR_BUDGET_ENFORCER === 'false') return next();
+  const context = _readContext(req);
+  // Cheap pre-check at $0; we use the request to record actual spend.
+  // The actual ceiling check happens with an estimated $0.01 "minimum" so
+  // exhausted accounts get rejected before we even route.
+  const budget = getHierarchicalBudget();
+  const check = budget.check(context, 0.01);
+  if (!check.ok) {
+    logger.warn({ exceeded: check.exceeded }, '[BudgetEnforcer] Budget exceeded');
+    return res.status(429).json({
+      error: {
+        type: 'budget_exceeded',
+        message: `Budget exceeded for ${check.exceeded.level}=${check.exceeded.id}`,
+        ...check.exceeded,
+      },
+    });
+  }
+  res.locals = res.locals || {};
+  res.locals.budgetContext = context;
+  next();
+}
+
+/**
+ * Helper for handlers to record spend after a request completes.
+ * Call this from the orchestrator with the actual cost.
+ */
+function recordSpend(context, amount) {
+  if (!context) return;
+  getHierarchicalBudget().record(context, amount);
+}
+
+module.exports = { budgetEnforcer, recordSpend };

package/src/api/middleware/load-shedding.js

@@ -44,11 +44,18 @@ class LoadShedder {
     const memUsage = process.memoryUsage();
     const heapUsedPercent = memUsage.heapUsed / memUsage.heapTotal;
 
-    if (heapUsedPercent > this.heapThreshold) {
+    // FIX: Only trigger if BOTH percentage is high AND actual usage is significant
+    // This prevents false positives on startup when heapTotal is small but will grow
+    const heapUsedMB = memUsage.heapUsed / (1024 * 1024);
+    const minHeapThresholdMB = 500; // Only shed load if using more than 500MB
+
+    if (heapUsedPercent > this.heapThreshold && heapUsedMB > minHeapThresholdMB) {
       logger.warn(
         {
           heapUsedPercent: (heapUsedPercent * 100).toFixed(2),
+          heapUsedMB: heapUsedMB.toFixed(2),
           threshold: (this.heapThreshold * 100).toFixed(2),
+          minThresholdMB: minHeapThresholdMB,
         },
         "Load shedding: Heap usage exceeded threshold"
       );
@@ -96,6 +103,9 @@ class LoadShedder {
       activeRequests: this.activeRequests,
       totalShed: this.totalShed,
       heapUsedPercent: ((memUsage.heapUsed / memUsage.heapTotal) * 100).toFixed(2),
+      heapUsedMB: (memUsage.heapUsed / (1024 * 1024)).toFixed(2),
+      heapTotalMB: (memUsage.heapTotal / (1024 * 1024)).toFixed(2),
+      rssMB: (memUsage.rss / (1024 * 1024)).toFixed(2),
       rssPercent: ((memUsage.rss / os.totalmem()) * 100).toFixed(2),
       thresholds: {
         heapThreshold: (this.heapThreshold * 100).toFixed(2),

package/src/api/middleware/tenant.js

@@ -0,0 +1,21 @@
+/**
+ * Tenant context middleware (Phase 6.1).
+ *
+ * Reads LYNKR-Tenant-Id from request headers and attaches the loaded tenant
+ * policy to res.locals.tenantPolicy for downstream handlers.
+ */
+
+const { getTenantId, getPolicy } = require('../../routing/tenant-policy');
+
+function tenantMiddleware(req, res, next) {
+  const tenantId = getTenantId(req);
+  res.locals = res.locals || {};
+  if (tenantId) {
+    const policy = getPolicy(tenantId);
+    res.locals.tenantId = tenantId;
+    res.locals.tenantPolicy = policy;
+  }
+  next();
+}
+
+module.exports = { tenantMiddleware };

package/src/api/router.js

@@ -3,6 +3,7 @@ const { processMessage } = require("../orchestrator");
 const { getSession } = require("../sessions");
 const metrics = require("../metrics");
 const logger = require("../logger");
+const config = require("../config");
 const { createRateLimiter } = require("./middleware/rate-limiter");
 const openaiRouter = require("./openai-router");
 const providersRouter = require("./providers-handler");
@@ -17,50 +18,26 @@ const router = express.Router();
 const rateLimiter = createRateLimiter();
 
 /**
- * Estimate token count for messages
- * Uses rough approximation of ~4 characters per token
- * @param {Array} messages - Array of message objects with role and content
- * @param {string|Array} system - System prompt (string or array of content blocks)
- * @returns {number} Estimated input token count
+ * Estimate token count for messages.
+ *
+ * Phase 1.1: tiktoken-backed via routing/tokenizer (graceful fallback to chars/4
+ * if js-tiktoken is unavailable).
  */
-function estimateTokenCount(messages = [], system = null) {
-  let totalChars = 0;
-
-  // Count system prompt characters
-  if (system) {
-    if (typeof system === "string") {
-      totalChars += system.length;
-    } else if (Array.isArray(system)) {
-      system.forEach((block) => {
-        if (block.type === "text" && block.text) {
-          totalChars += block.text.length;
-        }
-      });
-    }
-  }
+const { countMessagesTokens } = require("../routing/tokenizer");
 
-  // Count message characters
-  messages.forEach((msg) => {
-    if (msg.content) {
-      if (typeof msg.content === "string") {
-        totalChars += msg.content.length;
-      } else if (Array.isArray(msg.content)) {
-        msg.content.forEach((block) => {
-          if (block.type === "text" && block.text) {
-            totalChars += block.text.length;
-          } else if (block.type === "image" && block.source?.data) {
-            // Images: rough estimate based on base64 length
-            totalChars += Math.floor(block.source.data.length / 6);
-          }
-        });
-      }
-    }
-  });
-
-  // Estimate tokens: ~4 characters per token
-  return Math.ceil(totalChars / 4);
+function estimateTokenCount(messages = [], system = null, model = null) {
+  return countMessagesTokens(messages, system, model);
 }
 
+// Root health check (for HEAD / and GET /)
+router.head("/", (req, res) => {
+  res.status(200).end();
+});
+
+router.get("/", (req, res) => {
+  res.json({ status: "ok", service: "lynkr" });
+});
+
 router.get("/health", (req, res) => {
   res.json({ status: "ok" });
 });
@@ -371,6 +348,7 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
         options: {
           maxSteps: req.body?.max_steps,
           maxDurationMs: req.body?.max_duration_ms,
+          tenantPolicy: res.locals?.tenantPolicy || null,
         },
       });
 
@@ -604,6 +582,7 @@ router.post("/v1/messages", rateLimiter, async (req, res, next) => {
       options: {
         maxSteps: req.body?.max_steps,
         maxDurationMs: req.body?.max_duration_ms,
+        tenantPolicy: res.locals?.tenantPolicy || null,
       },
     });
     timer.mark("processMessage");