lynkr 9.1.2 → 9.1.3

package/README.md

@@ -225,14 +225,15 @@ Routes requests to the right model based on 5-phase complexity analysis. Simple
 - **Graphify integration** — AST-based knowledge graph detects god nodes, community cohesion, blast radius across 19 languages
 - **Routing telemetry** — every decision recorded with quality scoring (0-100) and latency tracking (P50/P95/P99)
 
-### Token Optimization (7 Phases)
-- **Smart tool selection** — only sends tools relevant to the current task
-- **Code Mode** — replaces 100+ MCP tools with 4 meta-tools (~96% token reduction)
-- **Distill compression** — structural similarity, delta rendering, smart dedup of repetitive tool outputs
-- **Prompt caching** — SHA-256 keyed LRU cache
-- **Memory deduplication** — eliminates repeated information across turns
-- **History compression** — sliding window with Distill-powered structural dedup
-- **Headroom sidecar** — optional 47-92% ML-based compression (Smart Crusher, CCR, LLMLingua)
+### Token Optimization (8 Phases)
+- **MCP Code Mode** — replaces 100+ MCP tool schemas with 4 meta-tools (~96% reduction, lazy tool discovery)
+- **Smart tool selection** — only sends tools relevant to the current task (50-70% reduction)
+- **Prompt caching** — SHA-256 keyed LRU cache (30-45% reduction on repeated prompts)
+- **Memory deduplication** — eliminates repeated information across turns (20-30% reduction)
+- **Tool response truncation** — intelligent truncation of long outputs (15-25% reduction)
+- **Dynamic system prompts** — adapt complexity to request type (10-20% reduction)
+- **Distill compression** — structural similarity, delta rendering, smart dedup of repetitive tool outputs (20-40% reduction)
+- **Headroom sidecar** — optional ML-based compression: Smart Crusher, CCR, LLMLingua (47-92% reduction)
 
 ### Enterprise Resilience
 - **Circuit breakers** — automatic failover with half-open probe recovery
@@ -254,12 +255,22 @@ SEMANTIC_CACHE_THRESHOLD=0.95
 ```
 
 ### MCP Integration + Code Mode
-Automatic Model Context Protocol server discovery and orchestration. Your MCP tools work through Lynkr without configuration. Enable Code Mode to replace 100+ MCP tool definitions with 4 lightweight meta-tools:
+Automatic Model Context Protocol server discovery and orchestration. Your MCP tools work through Lynkr without configuration.
+
+**MCP Code Mode** — Token optimization for heavy MCP setups:
+- Replaces 100+ individual MCP tool schemas with 4 meta-tools
+- Reduces tool catalog from ~17,500 tokens to ~700 tokens (**96% reduction**)
+- Enables lazy tool discovery: model queries `mcp_list_tools`, then `mcp_tool_info`, then `mcp_execute`
+- Best for: 50+ MCP tools, long conversations, context-constrained setups
+- Trade-off: 3 sequential calls instead of 1 (adds ~2-3s latency)
 
 ```bash
-CODE_MODE_ENABLED=true  # ~96% reduction in tool-catalog tokens
+CODE_MODE_ENABLED=true          # Enable Code Mode
+CODE_MODE_CACHE_TTL=60000       # Tool list cache TTL (ms)
 ```
 
+See [Token Optimization Guide](documentation/token-optimization.md#phase-0-mcp-code-mode-96-reduction-for-mcp-tools) and [Tools Documentation](documentation/tools.md#mcp-code-mode-token-optimization) for details.
+
 ---
 
 ## Deployment Options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkr",
-  "version": "9.1.2",
+  "version": "9.1.3",
   "description": "Self-hosted Claude Code & Cursor proxy with Databricks,AWS BedRock,Azure  adapters, openrouter, Ollama,llamacpp,LM Studio, workspace tooling, and MCP integration.",
   "main": "index.js",
   "bin": {
@@ -55,6 +55,8 @@
     "express": "^5.1.0",
     "express-rate-limit": "^8.2.1",
     "fast-glob": "^3.3.2",
+    "hnswlib-node": "^3.0.0",
+    "js-tiktoken": "^1.0.20",
     "js-yaml": "^4.1.1",
     "openai": "^6.14.0",
     "pino": "^8.17.2",

package/scripts/build-knn-index.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Build the kNN router index from telemetry (and optional RouterBench bootstrap).
+ *
+ * Phase 3.1 of the routing overhaul. Should be run nightly:
+ *   node scripts/build-knn-index.js [--days 30] [--bootstrap path/to/routerbench.jsonl]
+ *
+ * RouterBench bootstrap format (one JSON per line):
+ *   { "query": "...", "provider": "anthropic", "model": "claude-...",
+ *     "quality": 87, "cost": 0.0034, "latency": 1200, "tier": "COMPLEX" }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { generateEmbedding } = require('../src/cache/embeddings');
+const { getKnnRouter } = require('../src/routing/knn-router');
+
+const DEFAULT_DAYS = 30;
+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 _parseArgs(argv) {
+  const out = { days: DEFAULT_DAYS, bootstrap: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--days') out.days = Number(argv[++i]) || DEFAULT_DAYS;
+    else if (argv[i] === '--bootstrap') out.bootstrap = argv[++i];
+  }
+  return out;
+}
+
+async function _readTelemetry(days) {
+  const dbPath = _findDb();
+  if (!dbPath) return [];
+  let Database;
+  try {
+    Database = require('better-sqlite3');
+  } catch {
+    console.error('better-sqlite3 not installed');
+    return [];
+  }
+  const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+  try {
+    const since = Date.now() - days * 24 * 3600 * 1000;
+    return db
+      .prepare(
+        `SELECT request_text AS query, provider, model, quality_score AS quality,
+                cost, total_latency_ms AS latency, tier
+           FROM routing_telemetry
+          WHERE timestamp >= ?
+            AND quality_score IS NOT NULL
+            AND request_text IS NOT NULL
+            AND request_text != ''`
+      )
+      .all(since);
+  } catch (err) {
+    console.error(`Telemetry query failed: ${err.message}`);
+    return [];
+  } finally {
+    try { db.close(); } catch {}
+  }
+}
+
+async function _readBootstrap(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return [];
+  const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+  const out = [];
+  for (const line of lines) {
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // skip malformed
+    }
+  }
+  return out;
+}
+
+async function build({ days = DEFAULT_DAYS, bootstrap = null } = {}) {
+  const router = getKnnRouter();
+  if (!router.ready) {
+    console.error('Router index not ready (hnswlib-node may be missing). Aborting.');
+    process.exit(2);
+  }
+
+  const teleRows = await _readTelemetry(days);
+  const bootRows = await _readBootstrap(bootstrap);
+  const all = [...bootRows, ...teleRows];
+  console.log(`Building index from ${bootRows.length} bootstrap + ${teleRows.length} telemetry rows`);
+
+  let added = 0;
+  let failed = 0;
+  for (const row of all) {
+    const text = row.query || row.request_text;
+    if (!text) continue;
+    try {
+      const emb = await generateEmbedding(text);
+      router.add(emb, {
+        provider: row.provider,
+        model: row.model,
+        quality: row.quality,
+        cost: row.cost,
+        latency: row.latency,
+        tier: row.tier,
+      });
+      added++;
+      if (added % 100 === 0) console.log(`  ${added} indexed...`);
+    } catch (err) {
+      failed++;
+    }
+  }
+
+  router.save();
+  console.log(`Indexed ${added}, failed ${failed}. Index size: ${router.size}`);
+}
+
+if (require.main === module) {
+  const opts = _parseArgs(process.argv.slice(2));
+  build(opts).catch((err) => {
+    console.error(err.stack || err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = { build };

package/scripts/calibrate-thresholds.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * Calibrate tier thresholds from telemetry.
+ *
+ * Phase 1.4 of the routing overhaul. Reads quality_score history from the
+ * routing_telemetry table, finds where each tier's median quality drops below
+ * acceptable, and writes adjusted [lo, hi] ranges to
+ * data/calibrated-thresholds.json. ModelTierSelector picks the file up on
+ * next start.
+ *
+ * Usage: node scripts/calibrate-thresholds.js [--days N] [--dry-run]
+ *        npx lynkr calibrate
+ *
+ * Behavior when telemetry is sparse (<100 rows with quality_score):
+ *   - No file is written and existing calibration is left alone.
+ *   - Exits 0 with a "skipped" message.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_DAYS = 7;
+const MIN_SAMPLES = 100;
+/** Quality score below which a complexity bucket is "underperforming" for its tier. */
+const QUALITY_FLOOR = {
+  SIMPLE: 55,
+  MEDIUM: 60,
+  COMPLEX: 65,
+  REASONING: 70,
+};
+
+const OUTPUT_PATH = path.join(__dirname, '../data/calibrated-thresholds.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 _parseArgs(argv) {
+  const out = { days: DEFAULT_DAYS, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--days') out.days = Number(argv[++i]) || DEFAULT_DAYS;
+    else if (a === '--dry-run') out.dryRun = true;
+  }
+  return out;
+}
+
+const DEFAULT_RANGES = {
+  SIMPLE: [0, 25],
+  MEDIUM: [26, 50],
+  COMPLEX: [51, 75],
+  REASONING: [76, 100],
+};
+
+function _openDb(dbPath) {
+  let Database;
+  try {
+    Database = require('better-sqlite3');
+  } catch (err) {
+    console.error('better-sqlite3 not installed. Install with: npm install --save-optional better-sqlite3');
+    process.exit(2);
+  }
+  return new Database(dbPath, { readonly: true, fileMustExist: true });
+}
+
+function calibrate({ days = DEFAULT_DAYS, dryRun = false } = {}) {
+  const dbPath = _findDb();
+  if (!dbPath) {
+    console.log('No telemetry DB found — skipping calibration.');
+    return { skipped: true, reason: 'no_db' };
+  }
+
+  let db;
+  try {
+    db = _openDb(dbPath);
+  } catch (err) {
+    console.error(`Failed to open telemetry DB: ${err.message}`);
+    return { skipped: true, reason: 'db_open_failed', error: err.message };
+  }
+
+  const since = Date.now() - days * 24 * 3600 * 1000;
+  let rows;
+  try {
+    rows = db
+      .prepare(
+        `SELECT tier, complexity_score AS score, quality_score AS q
+           FROM routing_telemetry
+          WHERE timestamp >= ?
+            AND quality_score IS NOT NULL
+            AND complexity_score IS NOT NULL
+            AND tier IS NOT NULL`
+      )
+      .all(since);
+  } catch (err) {
+    console.error(`Telemetry query failed (DB may be corrupt or schema missing): ${err.message}`);
+    return { skipped: true, reason: 'query_failed', error: err.message };
+  } finally {
+    try { db.close(); } catch {}
+  }
+
+  if (!rows || rows.length < MIN_SAMPLES) {
+    console.log(`Only ${rows ? rows.length : 0} rows with quality_score in last ${days}d (need ≥${MIN_SAMPLES}). Skipping.`);
+    return { skipped: true, reason: 'insufficient_samples', count: rows ? rows.length : 0 };
+  }
+
+  // Bucket by score (0-100 in width-5 buckets) per tier, compute median quality.
+  const buckets = new Map(); // tier -> Map<bucketLowerBound, q-values[]>
+  for (const row of rows) {
+    const s = Math.max(0, Math.min(100, Math.floor(row.score)));
+    const bucket = Math.floor(s / 5) * 5;
+    if (!buckets.has(row.tier)) buckets.set(row.tier, new Map());
+    const b = buckets.get(row.tier);
+    if (!b.has(bucket)) b.set(bucket, []);
+    b.get(bucket).push(row.q);
+  }
+
+  const _median = (arr) => {
+    const s = arr.slice().sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+  };
+
+  // Default ranges; will adjust per-tier upper bound if late buckets show poor quality.
+  const ranges = { ...DEFAULT_RANGES };
+  const tierOrder = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
+  const stats = {};
+
+  for (const tier of tierOrder) {
+    const floor = QUALITY_FLOOR[tier];
+    const tierBuckets = buckets.get(tier);
+    if (!tierBuckets) {
+      stats[tier] = { samples: 0, adjusted: false };
+      continue;
+    }
+    const ordered = Array.from(tierBuckets.entries()).sort((a, b) => a[0] - b[0]);
+    let suggestedUpper = DEFAULT_RANGES[tier][1];
+    const buckets_summary = [];
+    for (const [lo, vals] of ordered) {
+      if (vals.length < 5) {
+        buckets_summary.push({ bucket: lo, samples: vals.length, median: null });
+        continue;
+      }
+      const med = _median(vals);
+      buckets_summary.push({ bucket: lo, samples: vals.length, median: med });
+      if (med < floor && lo + 4 < suggestedUpper) {
+        suggestedUpper = lo + 4; // shrink tier upper bound just below the failing bucket
+      }
+    }
+    if (suggestedUpper !== DEFAULT_RANGES[tier][1]) {
+      ranges[tier] = [DEFAULT_RANGES[tier][0], suggestedUpper];
+      stats[tier] = { samples: ordered.reduce((s, [, v]) => s + v.length, 0), adjusted: true, buckets: buckets_summary };
+    } else {
+      stats[tier] = { samples: ordered.reduce((s, [, v]) => s + v.length, 0), adjusted: false, buckets: buckets_summary };
+    }
+  }
+
+  // Re-stitch ranges so they don't overlap or leave gaps.
+  for (let i = 1; i < tierOrder.length; i++) {
+    const prev = ranges[tierOrder[i - 1]];
+    const cur = ranges[tierOrder[i]];
+    if (cur[0] !== prev[1] + 1) cur[0] = prev[1] + 1;
+    if (cur[0] > cur[1]) cur[1] = cur[0]; // collapsed; tier disabled in practice
+  }
+
+  const out = {
+    calibratedAt: new Date().toISOString(),
+    days,
+    sampleCount: rows.length,
+    ranges,
+    stats,
+  };
+
+  if (dryRun) {
+    console.log(JSON.stringify(out, null, 2));
+    return { ...out, dryRun: true };
+  }
+
+  fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });
+  fs.writeFileSync(OUTPUT_PATH, JSON.stringify(out, null, 2));
+  console.log(`Wrote ${OUTPUT_PATH}`);
+  console.log(`Ranges: ${tierOrder.map((t) => `${t}=${ranges[t].join('-')}`).join(', ')}`);
+  return out;
+}
+
+if (require.main === module) {
+  const opts = _parseArgs(process.argv.slice(2));
+  calibrate(opts);
+}
+
+module.exports = { calibrate };

package/scripts/compare-policies.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Compare active vs shadow routing policies (Phase 4.4).
+ *
+ * Reads data/shadow-decisions.jsonl and reports agreement rate and the
+ * disagreement breakdown by (active model → shadow model).
+ *
+ * Run weekly: node scripts/compare-policies.js [--days 7]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { LOG_PATH } = require('../src/routing/shadow-mode');
+
+function _parseArgs(argv) {
+  let days = 7;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--days') days = Number(argv[++i]) || 7;
+  }
+  return { days };
+}
+
+function main() {
+  const { days } = _parseArgs(process.argv.slice(2));
+  if (!fs.existsSync(LOG_PATH)) {
+    console.log('No shadow decisions logged yet.');
+    return;
+  }
+  const since = Date.now() - days * 24 * 3600 * 1000;
+  const lines = fs.readFileSync(LOG_PATH, 'utf8').split('\n').filter(Boolean);
+
+  let total = 0;
+  let agree = 0;
+  const disagreement = new Map(); // "active → shadow" -> count
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry.timestamp < since) continue;
+    total++;
+    if (entry.agree) {
+      agree++;
+    } else if (entry.shadow) {
+      const key = `${entry.active.provider}:${entry.active.model} → ${entry.shadow.provider}:${entry.shadow.model}`;
+      disagreement.set(key, (disagreement.get(key) || 0) + 1);
+    }
+  }
+
+  if (total === 0) {
+    console.log(`No decisions in last ${days} days.`);
+    return;
+  }
+
+  console.log(`Last ${days}d: ${total} decisions, ${(agree / total * 100).toFixed(1)}% agreement`);
+  if (disagreement.size > 0) {
+    console.log('\nTop disagreements:');
+    const sorted = Array.from(disagreement.entries()).sort((a, b) => b[1] - a[1]).slice(0, 10);
+    for (const [k, c] of sorted) {
+      console.log(`  ${c}× ${k}`);
+    }
+  }
+}
+
+main();

package/scripts/learn-output-ratios.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * Learn per-task-type output-token ratios from telemetry.
+ *
+ * Phase 2.3 of the routing overhaul. The cost-optimizer's default assumption
+ * of `output = 0.5 × input` is wrong for code generation (typically 1.5-3×)
+ * and summarization (typically 0.1-0.2×). This script builds an empirical
+ * ratio table from past completions, written to data/output-ratios.json.
+ *
+ * The cost-optimizer reads this file when estimating cost during routing.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_DAYS = 30;
+const MIN_SAMPLES_PER_TASK = 30;
+const OUTPUT_PATH = path.join(__dirname, '../data/output-ratios.json');
+const TELEMETRY_DB_CANDIDATES = [
+  path.join(__dirname, '../.lynkr/telemetry.db'),
+  path.join(__dirname, '../data/lynkr.db'),
+];
+
+// Fallback ratios when no telemetry exists.
+// Derived from public benchmark data (RouterBench task distribution).
+const FALLBACK_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,
+};
+
+function _findDb() {
+  for (const p of TELEMETRY_DB_CANDIDATES) if (fs.existsSync(p)) return p;
+  return null;
+}
+
+function _openDb(dbPath) {
+  let Database;
+  try {
+    Database = require('better-sqlite3');
+  } catch {
+    console.error('better-sqlite3 not installed. Install with: npm install --save-optional better-sqlite3');
+    process.exit(2);
+  }
+  return new Database(dbPath, { readonly: true, fileMustExist: true });
+}
+
+function _median(arr) {
+  const s = arr.slice().sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+}
+
+function _parseArgs(argv) {
+  const out = { days: DEFAULT_DAYS, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--days') out.days = Number(argv[++i]) || DEFAULT_DAYS;
+    else if (argv[i] === '--dry-run') out.dryRun = true;
+  }
+  return out;
+}
+
+function learn({ days = DEFAULT_DAYS, dryRun = false } = {}) {
+  const dbPath = _findDb();
+  if (!dbPath) {
+    console.log('No telemetry DB — writing fallback ratios.');
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });
+      fs.writeFileSync(OUTPUT_PATH, JSON.stringify({
+        learnedAt: new Date().toISOString(),
+        source: 'fallback',
+        ratios: FALLBACK_RATIOS,
+      }, null, 2));
+    }
+    return { source: 'fallback', ratios: FALLBACK_RATIOS };
+  }
+
+  let db;
+  try {
+    db = _openDb(dbPath);
+  } catch (err) {
+    console.error(`Failed to open telemetry DB: ${err.message}. Writing fallback ratios.`);
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });
+      fs.writeFileSync(OUTPUT_PATH, JSON.stringify({
+        learnedAt: new Date().toISOString(),
+        source: 'fallback',
+        ratios: FALLBACK_RATIOS,
+      }, null, 2));
+    }
+    return { source: 'fallback', ratios: FALLBACK_RATIOS };
+  }
+
+  const since = Date.now() - days * 24 * 3600 * 1000;
+  let rows;
+  try {
+    rows = db
+      .prepare(
+        `SELECT task_type, input_tokens AS i, output_tokens AS o
+           FROM routing_telemetry
+          WHERE timestamp >= ?
+            AND input_tokens > 0
+            AND output_tokens > 0
+            AND task_type IS NOT NULL`
+      )
+      .all(since);
+  } catch (err) {
+    console.error(`Query failed: ${err.message}. Writing fallback.`);
+    rows = [];
+  } finally {
+    try { db.close(); } catch {}
+  }
+
+  // Bucket by task type
+  const buckets = new Map();
+  for (const row of rows) {
+    const key = String(row.task_type || 'default').toLowerCase();
+    if (!buckets.has(key)) buckets.set(key, []);
+    buckets.get(key).push(row.o / row.i);
+  }
+
+  const ratios = { ...FALLBACK_RATIOS };
+  const stats = {};
+  for (const [task, vals] of buckets) {
+    if (vals.length >= MIN_SAMPLES_PER_TASK) {
+      ratios[task] = +_median(vals).toFixed(3);
+      stats[task] = { samples: vals.length, median: ratios[task] };
+    } else {
+      stats[task] = { samples: vals.length, median: null, used_fallback: true };
+    }
+  }
+
+  const out = {
+    learnedAt: new Date().toISOString(),
+    days,
+    source: rows.length > 0 ? 'telemetry' : 'fallback',
+    sampleCount: rows.length,
+    ratios,
+    stats,
+  };
+
+  if (dryRun) {
+    console.log(JSON.stringify(out, null, 2));
+    return out;
+  }
+
+  fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });
+  fs.writeFileSync(OUTPUT_PATH, JSON.stringify(out, null, 2));
+  console.log(`Wrote ${OUTPUT_PATH} (source=${out.source}, samples=${out.sampleCount})`);
+  return out;
+}
+
+if (require.main === module) {
+  const opts = _parseArgs(process.argv.slice(2));
+  learn(opts);
+}
+
+module.exports = { learn, FALLBACK_RATIOS };