lynkr 9.7.3 → 9.9.0

package/src/routing/affinity-store.js

@@ -0,0 +1,194 @@
+/**
+ * Session-Pin Persistence
+ *
+ * Persists sticky-session routing pins to SQLite so they survive process
+ * restarts. Shares the telemetry DB handle (see telemetry.getDb) to avoid
+ * opening a second WAL connection to the same file.
+ *
+ * A "pin" records the provider/model/tier a session was routed to plus enough
+ * state (message_count, prompt_tokens_est, ts) for the wrapper in
+ * `session-affinity.js` to decide when to re-route:
+ *
+ *   - compaction detected (messages shrank ⇒ cache reset ⇒ free to re-route)
+ *   - guard escalation (context/vision needs pin can't satisfy)
+ *   - economic downgrade (fresh decision is cheaper AND prompt is small
+ *     enough that the cold-cache re-read is affordable)
+ *
+ * All I/O is best-effort: any failure is recorded via degradation.record and
+ * falls back to the in-memory Map in session-affinity.js.
+ *
+ * @module routing/affinity-store
+ */
+
+const telemetry = require("./telemetry");
+const degradation = require("./degradation");
+const logger = require("../logger");
+
+let schemaEnsured = false;
+
+function _db() {
+  const db = telemetry.getDb();
+  if (!db) return null;
+  if (!schemaEnsured) {
+    try {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS session_pins (
+          session_id        TEXT PRIMARY KEY,
+          provider          TEXT NOT NULL,
+          model             TEXT,
+          tier              TEXT,
+          score             REAL,
+          message_count     INTEGER,
+          prompt_tokens_est INTEGER,
+          ts                INTEGER NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_session_pins_ts ON session_pins(ts);
+      `);
+      // Additive migration for DBs created before `score` was added.
+      const cols = new Set(db.prepare("PRAGMA table_info(session_pins)").all().map((c) => c.name));
+      if (!cols.has("score")) {
+        db.exec("ALTER TABLE session_pins ADD COLUMN score REAL");
+      }
+      schemaEnsured = true;
+    } catch (err) {
+      degradation.record("feedback", err);
+      return null;
+    }
+  }
+  return db;
+}
+
+const stmts = new Map();
+function _stmt(db, key, sql) {
+  const cacheKey = `${key}`;
+  if (!stmts.has(cacheKey)) stmts.set(cacheKey, db.prepare(sql));
+  return stmts.get(cacheKey);
+}
+
+/**
+ * Load a pin by session id. Returns null if missing, expired against `ttlMs`,
+ * or the DB is unavailable.
+ *
+ * @param {string} sessionId
+ * @param {number} [ttlMs]
+ * @returns {{provider:string, model:string|null, tier:string|null, messageCount:number|null, promptTokensEst:number|null, ts:number}|null}
+ */
+function load(sessionId, ttlMs) {
+  if (!sessionId) return null;
+  const db = _db();
+  if (!db) return null;
+  try {
+    const row = _stmt(
+      db,
+      "load",
+      "SELECT provider, model, tier, score, message_count, prompt_tokens_est, ts FROM session_pins WHERE session_id = ?"
+    ).get(sessionId);
+    if (!row) return null;
+    if (ttlMs && Date.now() - row.ts > ttlMs) {
+      // Expired: delete lazily so a subsequent save doesn't pick up a stale ts.
+      try {
+        _stmt(db, "delete", "DELETE FROM session_pins WHERE session_id = ?").run(sessionId);
+      } catch { /* best-effort */ }
+      return null;
+    }
+    return {
+      provider: row.provider,
+      model: row.model,
+      tier: row.tier,
+      score: row.score,
+      messageCount: row.message_count,
+      promptTokensEst: row.prompt_tokens_est,
+      ts: row.ts,
+    };
+  } catch (err) {
+    degradation.record("feedback", err);
+    return null;
+  }
+}
+
+/**
+ * Upsert a pin. Silently no-ops if the DB is unavailable — the in-memory Map
+ * in session-affinity remains authoritative in that case.
+ *
+ * @param {string} sessionId
+ * @param {{provider:string, model?:string|null, tier?:string|null, messageCount?:number|null, promptTokensEst?:number|null, ts?:number}} pin
+ */
+function save(sessionId, pin) {
+  if (!sessionId || !pin?.provider) return;
+  const db = _db();
+  if (!db) return;
+  try {
+    _stmt(
+      db,
+      "upsert",
+      `INSERT INTO session_pins (session_id, provider, model, tier, score, message_count, prompt_tokens_est, ts)
+       VALUES (@session_id, @provider, @model, @tier, @score, @message_count, @prompt_tokens_est, @ts)
+       ON CONFLICT(session_id) DO UPDATE SET
+         provider = excluded.provider,
+         model = excluded.model,
+         tier = excluded.tier,
+         score = excluded.score,
+         message_count = excluded.message_count,
+         prompt_tokens_est = excluded.prompt_tokens_est,
+         ts = excluded.ts`
+    ).run({
+      session_id: sessionId,
+      provider: pin.provider,
+      model: pin.model ?? null,
+      tier: pin.tier ?? null,
+      score: typeof pin.score === 'number' ? pin.score : null,
+      message_count: pin.messageCount ?? null,
+      prompt_tokens_est: pin.promptTokensEst ?? null,
+      ts: pin.ts ?? Date.now(),
+    });
+  } catch (err) {
+    degradation.record("feedback", err);
+  }
+}
+
+/**
+ * Remove a pin.
+ * @param {string} sessionId
+ */
+function remove(sessionId) {
+  if (!sessionId) return;
+  const db = _db();
+  if (!db) return;
+  try {
+    _stmt(db, "delete", "DELETE FROM session_pins WHERE session_id = ?").run(sessionId);
+  } catch (err) {
+    degradation.record("feedback", err);
+  }
+}
+
+/**
+ * Delete pins older than ttlMs. Called from the same scheduler that runs
+ * telemetry.cleanup.
+ *
+ * @param {number} ttlMs
+ * @returns {number} rows deleted
+ */
+function cleanup(ttlMs) {
+  const db = _db();
+  if (!db) return 0;
+  try {
+    const threshold = Date.now() - ttlMs;
+    const result = _stmt(db, "cleanup", "DELETE FROM session_pins WHERE ts < ?").run(threshold);
+    logger.debug({ deleted: result.changes }, "[AffinityStore] pin cleanup");
+    return result.changes;
+  } catch (err) {
+    degradation.record("feedback", err);
+    return 0;
+  }
+}
+
+/** Test helper — wipe all pins. */
+function _clear() {
+  const db = _db();
+  if (!db) return;
+  try {
+    db.prepare("DELETE FROM session_pins").run();
+  } catch { /* best-effort */ }
+}
+
+module.exports = { load, save, remove, cleanup, _clear };

package/src/routing/agentic-detector.js

@@ -5,6 +5,7 @@
  */
 
 const logger = require('../logger');
+const clientProfiles = require('./client-profiles');
 
 // Agent type classification with tier requirements
 const AGENT_TYPES = {
@@ -41,8 +42,10 @@ const PATTERNS = {
   // Iterative work indicators
   iterative: /\b(keep\s+trying|until|repeat|loop|retry|iterate|fix.*again|try.*different|debug)\b/i,
 
-  // Autonomous work indicators
-  autonomous: /\b(figure\s+out|solve|complete\s+the\s+task|do\s+whatever|make\s+it\s+work|find\s+a\s+way|whatever\s+it\s+takes)\b/i,
+  // Autonomous work indicators. Must include the literal "autonomous(ly)":
+  // under client profiles the tool-count score sits below the 60 gate, so
+  // the phrase gate is the only path to AUTONOMOUS.
+  autonomous: /\b(figure\s+out|solve|complete\s+the\s+task|do\s+whatever|make\s+it\s+work|find\s+a\s+way|whatever\s+it\s+takes|autonomous(ly)?|on\s+your\s+own|without\s+(asking|supervision)|keep\s+(going|iterating|working)\s+until)\b/i,
 
   // Multi-file work
   multiFile: /\b(multiple\s+files?|across\s+(the\s+)?codebase|all\s+files?|refactor\s+entire|whole\s+project|everywhere)\b/i,
@@ -91,18 +94,41 @@ class AgenticDetector {
   /**
    * Detect agentic workflow patterns
    * @param {Object} payload - Request payload with messages and tools
+   * @param {Object} [opts]
+   * @param {Object} [opts.clientProfile] - Client harness profile (WS3.1).
+   *   When present, Signals 1 & 2 score only tools BEYOND the harness's
+   *   baseline loadout — Claude Code's 11 always-attached tools shouldn't
+   *   count as "agentic intent" on their own.
    * @returns {Object} Detection result
    */
-  detect(payload) {
+  detect(payload, opts = {}) {
     const messages = payload?.messages || [];
-    const tools = payload?.tools || [];
+    const rawTools = payload?.tools || [];
     const content = this._extractContent(messages);
+    const profile = opts.clientProfile || null;
+
+    // WS3.2 — subtract known-harness baseline tools before scoring tool-based
+    // signals. Signals 3-6 (tool_result depth, patterns, message depth,
+    // length) are genuine agentic evidence and always use the full payload.
+    let toolsForScoring;
+    let scoringNote = null;
+    if (profile) {
+      toolsForScoring = clientProfiles.effectiveTools(payload, profile);
+      scoringNote = `profile:${profile.name}`;
+    } else if (clientProfiles.allToolsAreBaseline(payload) && rawTools.length >= 10) {
+      // Unknown harness that looks like Claude Code / Cursor / Codex —
+      // zero out the tool-count signals to avoid the same trap.
+      toolsForScoring = [];
+      scoringNote = 'unknown_harness_guard';
+    } else {
+      toolsForScoring = rawTools;
+    }
 
     let score = 0;
     const signals = [];
 
     // Signal 1: Tool count (many tools = likely multi-step)
-    const toolCount = tools.length;
+    const toolCount = toolsForScoring.length;
     if (toolCount > 10) {
       score += 25;
       signals.push({ signal: 'very_high_tool_count', value: toolCount, weight: 25 });
@@ -115,7 +141,7 @@ class AgenticDetector {
     }
 
     // Signal 2: Agentic tools present (Bash, Write, Edit, Task)
-    const agenticToolCount = tools.filter(t => {
+    const agenticToolCount = toolsForScoring.filter(t => {
       const name = t.name || t.function?.name || '';
       return AGENTIC_TOOLS.has(name);
     }).length;
@@ -207,6 +233,8 @@ class AgenticDetector {
       minTier: AGENT_TYPES[agentType].minTier,
       scoreBoost: AGENT_TYPES[agentType].scoreBoost,
       description: AGENT_TYPES[agentType].description,
+      clientProfile: profile?.name ?? null,
+      scoringNote,
     };
 
     if (isAgentic) {
@@ -215,7 +243,9 @@ class AgenticDetector {
         score,
         signalCount: signals.length,
         toolCount,
+        rawToolCount: rawTools.length,
         toolResultCount,
+        scoringNote,
       }, '[AgenticDetector] Agentic workflow detected');
     }
 

package/src/routing/bandit.js

@@ -102,11 +102,18 @@ function _inv(M) {
 }
 
 class LinUCBBandit {
-  constructor({ alpha = DEFAULT_ALPHA, lambda = DEFAULT_LAMBDA, mu = DEFAULT_MU, dim = FEATURE_DIM } = {}) {
+  constructor({
+    alpha = DEFAULT_ALPHA,
+    lambda = DEFAULT_LAMBDA,
+    mu = DEFAULT_MU,
+    dim = FEATURE_DIM,
+    explorationRate = EXPLORATION_RATE,
+  } = {}) {
     this.alpha = alpha;
     this.lambda = lambda;
     this.mu = mu;
     this.dim = dim;
+    this.explorationRate = explorationRate;
     /** arms: Map<armKey, { A: number[][], b: number[], count: number }> */
     this.arms = new Map();
     this.steps = 0;
@@ -126,10 +133,18 @@ class LinUCBBandit {
 
   /**
    * Pick an arm for a given tier and context.
+   *
+   * Returns `propensity` — the probability, under the current policy, that
+   * this specific arm was chosen. WS4 uses this for off-policy evaluation
+   * from telemetry alone: an explored pick has probability `ε/K`; an
+   * exploited pick has `1 − ε + ε/K` (the ε-branch could still have
+   * landed on it uniformly). With K=1 the ε-branch trivially chooses the
+   * only arm, so both cases collapse to 1.0.
+   *
    * @param {string} tier
    * @param {Array<{ provider: string, model: string }>} candidates — qualifying arms
    * @param {number[]} context — feature vector
-   * @returns {{ provider, model, ucb, explored }} chosen arm
+   * @returns {{ provider, model, ucb, explored, propensity }} chosen arm
    */
   pick(tier, candidates, context) {
     if (!candidates || candidates.length === 0) return null;
@@ -139,10 +154,13 @@ class LinUCBBandit {
       while (context.length < this.dim) context.push(0);
     }
 
-    // ε-greedy: 5% pure exploration
-    if (Math.random() < EXPLORATION_RATE) {
+    const K = candidates.length;
+    const eps = this.explorationRate;
+
+    // ε-greedy: EXPLORATION_RATE pure exploration
+    if (Math.random() < eps) {
       const random = candidates[Math.floor(Math.random() * candidates.length)];
-      return { ...random, ucb: null, explored: true };
+      return { ...random, ucb: null, explored: true, propensity: eps / K };
     }
 
     let best = null;
@@ -165,6 +183,7 @@ class LinUCBBandit {
         best = { ...c, ucb, explored: false };
       }
     }
+    if (best) best.propensity = (1 - eps) + eps / K;
     return best;
   }
 
@@ -243,4 +262,4 @@ function getBandit() {
   return _instance;
 }
 
-module.exports = { LinUCBBandit, getBandit, FEATURE_DIM };
+module.exports = { LinUCBBandit, getBandit, FEATURE_DIM, EXPLORATION_RATE };

package/src/routing/calibration.js

@@ -0,0 +1,212 @@
+/**
+ * WS5.6 — auto-calibration.
+ *
+ * The core logic of `scripts/calibrate-thresholds.js` extracted so it can
+ * run inside the server process on a schedule, not just from the CLI.
+ *
+ * Read quality_score history from the routing_telemetry table, bucket by
+ * (tier, complexity_score) with width-5 buckets, and shrink each tier's
+ * upper bound to just below the first bucket whose median quality falls
+ * under a per-tier floor. Ranges are then re-stitched to leave no gaps
+ * before writing to `data/calibrated-thresholds.json`.
+ *
+ * The CLI script (`scripts/calibrate-thresholds.js`) is now a thin wrapper
+ * around `runCalibration()` — same defaults, same output format.
+ */
+
+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 DEFAULT_RANGES = {
+  // SIMPLE/MEDIUM boundary at 20 — mirrors model-tiers.js TIER_DEFINITIONS
+  // (see the rationale comment there; RouterArena-diagnosed 2026-07-16).
+  SIMPLE: [0, 19],
+  MEDIUM: [20, 50],
+  COMPLEX: [51, 75],
+  REASONING: [76, 100],
+};
+
+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(dbPath) {
+  if (dbPath) return fs.existsSync(dbPath) ? dbPath : null;
+  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 (err) {
+    throw new Error(
+      'better-sqlite3 not installed. Install with: npm install --save-optional better-sqlite3'
+    );
+  }
+  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;
+}
+
+/**
+ * Run calibration against a telemetry DB and (unless dryRun) write the
+ * result to `data/calibrated-thresholds.json`.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.days=7]
+ * @param {boolean} [opts.dryRun=false]
+ * @param {string} [opts.dbPath] — explicit DB path (else auto-discover).
+ * @param {string} [opts.outputPath] — override output path (tests set this).
+ * @returns {object} — either `{skipped:true, reason}` or a full result
+ *   `{calibratedAt, days, sampleCount, ranges, stats}` (with `dryRun:true`
+ *   when appropriate).
+ */
+function runCalibration({ days = DEFAULT_DAYS, dryRun = false, dbPath, outputPath = OUTPUT_PATH } = {}) {
+  const resolvedDb = _findDb(dbPath);
+  if (!resolvedDb) {
+    return { skipped: true, reason: 'no_db' };
+  }
+
+  let db;
+  try {
+    db = _openDb(resolvedDb);
+  } catch (err) {
+    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) {
+    return { skipped: true, reason: 'query_failed', error: err.message };
+  } finally {
+    try { db.close(); } catch { /* ignore */ }
+  }
+
+  if (!rows || rows.length < MIN_SAMPLES) {
+    return {
+      skipped: true,
+      reason: 'insufficient_samples',
+      count: rows ? rows.length : 0,
+      minSamples: MIN_SAMPLES,
+    };
+  }
+
+  // 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 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 bucketsSummary = [];
+    for (const [lo, vals] of ordered) {
+      if (vals.length < 5) {
+        bucketsSummary.push({ bucket: lo, samples: vals.length, median: null });
+        continue;
+      }
+      const med = _median(vals);
+      bucketsSummary.push({ bucket: lo, samples: vals.length, median: med });
+      if (med < floor && lo + 4 < suggestedUpper) {
+        // shrink tier upper bound just below the failing bucket
+        suggestedUpper = lo + 4;
+      }
+    }
+    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: bucketsSummary,
+      };
+    } else {
+      stats[tier] = {
+        samples: ordered.reduce((s, [, v]) => s + v.length, 0),
+        adjusted: false,
+        buckets: bucketsSummary,
+      };
+    }
+  }
+
+  // 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) return { ...out, dryRun: true };
+
+  try {
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, JSON.stringify(out, null, 2));
+    return { ...out, writtenTo: outputPath };
+  } catch (err) {
+    return { skipped: true, reason: 'write_failed', error: err.message };
+  }
+}
+
+module.exports = {
+  runCalibration,
+  MIN_SAMPLES,
+  DEFAULT_RANGES,
+  QUALITY_FLOOR,
+  OUTPUT_PATH,
+};