lynkr 9.7.3 → 9.9.1

package/README.md

@@ -2,25 +2,27 @@
 
 ### An LLM Gateway which optimises your token usage.
 
-**87.6% fewer tokens on JSON tool results. 53% fewer tokens on tool-heavy requests. 171ms semantic cache hits. Zero code changes.**
+**84% fewer tokens on JSON tool results. 53% fewer tokens on tool-heavy requests. Sub-300ms semantic cache hits. Zero code changes.**
 
 [![npm version](https://img.shields.io/npm/v/lynkr.svg)](https://www.npmjs.com/package/lynkr)
-[![Tests](https://img.shields.io/badge/tests-699%20passing-brightgreen)](https://github.com/Fast-Editor/Lynkr)
+[![Tests](https://img.shields.io/badge/tests-1041%20passing-brightgreen)](https://github.com/Fast-Editor/Lynkr)
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-20%2B-green)](https://nodejs.org)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Fast-Editor/Lynkr)
 
 <table>
 <tr>
-<td align="center"><strong>87.6%</strong><br/>JSON Compression</td>
+<td align="center"><strong>84%</strong><br/>JSON Compression</td>
 <td align="center"><strong>53%</strong><br/>Tool Token Reduction</td>
-<td align="center"><strong>171ms</strong><br/>Semantic Cache Hits</td>
+<td align="center"><strong>&lt;300ms</strong><br/>Semantic Cache Hits</td>
 <td align="center"><strong>13+</strong><br/>LLM Providers</td>
 <td align="center"><strong>0</strong><br/>Code Changes Required</td>
 </tr>
 </table>
 
-> Numbers from a live benchmark against LiteLLM on identical workloads. [See full report →](BENCHMARK_REPORT.md)
+> Numbers from the bundled benchmark against LiteLLM on identical free local backends — run it yourself: `node benchmark-tier-routing.js`. It doubles as a 19-scenario routing regression harness (currently 12/12 correctness checks), and `MODE=routing` runs a routing-only head-to-head that judges **both** proxies on the same acceptable-tier sets — including LiteLLM's Auto Router v2. [How it works →](docs/benchmarking.md)
+
+> **Third-party benchmark:** on [RouterArena](https://github.com/RouteWorks/RouterArena) (ICLR 2026, 8,400 queries) Lynkr's routing scores **67.65 arena / 68.41% accuracy at $0.29 per 1K queries with 92.38 robustness** — above GPT-5's built-in router and NotDiamond at a fraction of their cost. [Methodology & caveats →](docs/routerarena-benchmark.md)
 
 ---
 
@@ -40,8 +42,9 @@ lynkr wrap claude
 
 **Wrapping gives you:**
 - ✅ Tier routing (send simple tasks to free Ollama, complex to your subscription/API)
-- ✅ TOON/RTK compression (87% token reduction on tool outputs)
-- ✅ Semantic caching (171ms cache hits)
+- ✅ Sticky sessions: one routing decision per conversation via content fingerprinting, with automatic escalation when the task outgrows the model
+- ✅ TOON/RTK compression (84% token reduction on large JSON tool outputs)
+- ✅ Semantic caching (sub-300ms cache hits, 0 tokens billed)
 - ✅ **3-5x more usage from the same subscription limits**
 - ✅ Works with OAuth (Claude, Copilot, Cursor) or API keys (Aider, Codex)
 
@@ -180,9 +183,10 @@ Claude Code / Cursor / Codex / Cline / Continue
                   Lynkr
           ┌─────────────────────┐
           │  Strip unused tools  │  ← 53% fewer tokens on tool calls
-          │  Compress JSON blobs │  ← 87.6% on large tool results
-          │  Semantic cache      │  ← 171ms hits, 0 tokens billed
+          │  Compress JSON blobs │  ← 84% on large tool results
+          │  Semantic cache      │  ← <300ms hits, 0 tokens billed
           │  Route by complexity │  ← cheap model for simple, cloud for hard
+          │  Learn from outcomes │  ← kNN + bandit + auto-calibration
           └─────────────────────┘
                     ↓
     Ollama | Bedrock | Azure | Moonshot | OpenRouter | OpenAI
@@ -190,9 +194,10 @@ Claude Code / Cursor / Codex / Cline / Continue
 
 **What you get:**
 - ✅ **53% fewer tokens** on tool-heavy requests (Claude Code, Cursor sessions)
-- ✅ **87.6% compression** on large JSON tool results (grep, file reads, test output)
-- ✅ **Semantic cache** serves repeated queries in 171ms with 0 tokens billed
-- ✅ **Automatic tier routing** — simple questions go to cheap models, complex ones escalate
+- ✅ **84% compression** on large JSON tool results (grep, file reads, test output)
+- ✅ **Semantic cache** serves repeated queries in under 300ms with 0 tokens billed
+- ✅ **Automatic tier routing** — simple questions go to cheap models, complex ones escalate; sessions stick to one model until the task genuinely outgrows it
+- ✅ **A closed learning loop** — every outcome trains a kNN router and bandit, and tier thresholds re-calibrate nightly from your own traffic
 - ✅ Route through **your company's infrastructure** (Databricks, Azure, Bedrock)
 - ✅ **Zero code changes** — just change one environment variable
 
@@ -241,11 +246,11 @@ POLICY_MAX_STEPS=50
 POLICY_MAX_TOOL_CALLS=100
 ```
 
-Lynkr analyzes each request and routes it to the appropriate tier. Simple questions use fast models. Complex refactoring uses powerful models.
+Lynkr analyzes each request and routes it to the appropriate tier. Simple questions use fast models. Complex refactoring uses powerful models. The scorer combines anchor-embedding classification (WS7, payload-invariant) with an LLM difficulty classifier (Phase 6, added 2026-07-19) that catches topic-vs-difficulty confounding — `list the exports from this file` correctly routes to MEDIUM instead of getting boosted to REASONING by "technical vocabulary" alone.
 
-**Result:** 70-90% of requests use cheaper/faster models. Only hard problems hit expensive models.
+**Result:** 70-90% of requests use cheaper/faster models. Only hard problems hit expensive models. **15× reduction in expensive-tier over-routing** vs the anchor-only baseline on the 381-prompt eval set (0.6% vs ~15%).
 
-Tier configuration is strictly authoritative — bandit exploration is constrained to the models you've listed in `TIER_*`, and multi-turn conversations score with a recency-weighted sliding window so context isn't lost on short follow-ups. See [`docs/intent-window-routing.md`](docs/intent-window-routing.md).
+Tier configuration is strictly authoritative — bandit exploration is constrained to the models you've listed in `TIER_*`, and multi-turn conversations score with a recency-weighted sliding window so context isn't lost on short follow-ups. Conversations get a content-fingerprint session id (clients like Claude Code send none), the decision pins for the session, and a guarded escape ladder (risk keywords, force phrases, score drift, context overflow) re-escalates the moment a task outgrows its model. Full pipeline: [`docs/routing-intelligence.md`](docs/routing-intelligence.md) · intent scorer: [`docs/intent-window-routing.md`](docs/intent-window-routing.md) · verify any change: [`docs/benchmarking.md`](docs/benchmarking.md).
 
 ---
 
@@ -408,7 +413,7 @@ npm start
 
 Head-to-head against **LiteLLM** on the **same backends** (Ollama `minimax-m2.5`, Moonshot, Azure OpenAI), 9 scenarios across 4 feature categories. Apples-to-apples comparison is Lynkr vs LiteLLM **billed tokens on the same scenario**. Run with `node benchmark-tier-routing.js`.
 
-> _Run: June 5, 2026 · Lynkr v9.3.2 · LiteLLM v1.87.1 · macOS, Apple Silicon._
+> _Runs: token benchmarks — June 5, 2026 (Lynkr v9.3.2 · LiteLLM v1.87.1). Tier routing head-to-head — **re-run July 19, 2026** (Lynkr working tree w/ Phase-6 classifier + config B · LiteLLM v1.94.0.dev1 Auto Router v2). macOS, Apple Silicon._
 
 ### Token reduction (vs LiteLLM, same model & prompt)
 
@@ -428,23 +433,56 @@ Lynkr strips irrelevant tool schemas (smart tool selection) and binary-compresse
 
 Near-identical prompts return cached responses in 171ms. Zero model tokens billed on a cache hit.
 
-### Tier routing
+### Tier routing — vs LiteLLM Auto Router v2 (re-run July 19, 2026)
+
+LiteLLM v1.94 shipped a native complexity router (`auto_router/complexity_router`) with the same four tier names Lynkr uses. Head-to-head on the **same backends** with identical prompts, both proxies live, both judged against the same acceptable-tier sets (11 routing scenarios, `MODE=routing node benchmark-tier-routing.js`, LiteLLM config in `litellm-autorouter-v2.yaml`):
+
+| Router | Routing-correct | Notes |
+|---|---|---|
+| **Lynkr (Phase-6 classifier + config B)** | **11/11 ✅** | anchor embedding + local LLM classifier reconcile + FORCE_REASONING patterns + risk-remap; ~500ms warm classifier call, cached |
+| LiteLLM v2 — heuristic (default) | **4/11** | every miss *under-routed* — banking security analysis, whole-pipeline refactor, prod auth-file fix, autonomous agentic loop all sent to a 7B local model |
+| LiteLLM v2 — LLM classifier | 6–8/11 (non-deterministic) | paid GPT-5.2 call + ~2–3s on **every** request; fails outright with local classifier models |
+
+**The 7 requests LiteLLM v2 misroutes to a 7B ollama model (should be COMPLEX or REASONING):**
 
-| Request | Lynkr routes to | LiteLLM routes to |
+| What you typed | Lynkr sends to | LiteLLM sends to |
 |---|---|---|
-| "What does git stash do?" | `minimax-m2.5` (local, free) | Ollama (local) |
-| JWT vs cookies security analysis | `moonshot` (cloud — correct) | **Ollama (local — wrong call)** |
+| "Analyse security trade-offs of JWT vs httpOnly cookies for a banking app" | Claude Opus (top) | **ollama 7B** ❌ |
+| "Refactor the entire ingestion pipeline and give me the plan" | z.ai GLM-5.2 (mid) | **ollama 7B** ❌ |
+| "Fix the null-check bug in `src/auth/middleware.ts`" | Claude Opus (risk-remap) | **ollama 7B** ❌ |
+| "Figure out why this test is flaky. You have full autonomy — iterate until 10 runs pass" | Claude Opus (autonomous) | **ollama 7B** ❌ |
+| "please summarize the exports of this file quickly" | ollama minimax (correct — MEDIUM) | ollama minimax — but for the wrong reason (LiteLLM under-routed to SIMPLE) |
+
+Lynkr layers the following, in decreasing priority, to catch every miss LiteLLM leaks:
 
-Lynkr scores each request on 15 dimensions (token count, code complexity, reasoning markers, risk signals, agentic patterns) and escalates automatically. LiteLLM's `cost-based-routing` sends everything to the cheapest model regardless of complexity.
+- FORCE_REASONING regex (`ultrathink`, `prove`, `security audit`, `from first principles`) → deterministic top-tier
+- Risk classifier (auth/middleware/credentials paths) → REASONING under config B
+- Agentic detector (`AUTONOMOUS` workflows) → REASONING minimum
+- Anchor-embedding classifier over 4 difficulty classes + FRONTIER_MIN_SIM floor
+- Local LLM classifier (qwen2.5:3b) reconciles borderline anchor calls
+- Envelope invariance — scores cleaned user text only, ignoring tool schemas / history / system-reminders
+
+LiteLLM's router reads the raw last message with no envelope-stripping, no verify-then-escalate cascade, no risk classifier, no agentic detection — its fallbacks trigger only on HTTP errors, never on a bad answer.
+
+_Fairness notes: the 11 scenarios derive from Lynkr's own regression suite, so Lynkr has home-field advantage — the transferable finding is the **direction** of LiteLLM's failures (systematic under-routing to cheap on hard prompts), not the exact scores. Lynkr's top tiers used Claude Opus 4.8 / z.ai GLM-5.2; LiteLLM was given the identical tier targets._
 
 ### Cost projection (100,000 requests/month, same backend)
 
+**Direct cost (raw meter):**
+
 | | Monthly cost | vs LiteLLM |
 |---|---|---|
-| LiteLLM | ~$818 | baseline |
-| **Lynkr** | **~$409** | **~50% cheaper** |
+| LiteLLM (TOON tool-heavy scenario) | ~$818 | baseline |
+| **Lynkr (TOON tool-heavy)** | **~$409** | **~50% cheaper** via token optimization |
+
+**Effective cost per correct-tier answer** (July 19 head-to-head, all 11 routing scenarios):
+
+| | Direct $/mo | Effective $/mo if you re-issue misroutes at correct tier |
+|---|---|---|
+| **Lynkr** | ~$5.50 (spends where it should, doesn't where it shouldn't) | ~$5.50 |
+| LiteLLM v2 heuristic | $0 (under-routes everything to ollama) | ~$89 (7 misroutes need re-issue on Moonshot/COMPLEX) |
 
-_Based on a tool-heavy agentic session (TOON scenario). On equal footing — same provider, same model — Lynkr is cheaper due to token optimization._
+The story isn't "Lynkr always spends less." It's **Lynkr spends where it should and doesn't where it shouldn't**. LiteLLM's zero-dollar cost on complex prompts is bought with wrong-tier answers to hard work — a 7B model answering "prove this rate limiter is fair under concurrent refill" is silent quality collapse, not a savings.
 
 → [Full benchmark report with methodology](BENCHMARK_REPORT.md)
 
@@ -469,7 +507,7 @@ With tier routing + token optimization: **additional 50-87% savings** on cloud p
 | **Claude Code native** | ✅ Drop-in | ⚠️ Requires config | ❌ | ⚠️ Partial |
 | **Cursor native** | ✅ Drop-in | ⚠️ Partial | ❌ | ⚠️ Partial |
 | **Local models** | Ollama, llama.cpp, LM Studio | Ollama only | ❌ | ❌ |
-| **Automatic tier routing** | ✅ 15-dimension scorer | ⚠️ Cost-only | ❌ | ❌ Manual metadata |
+| **Automatic tier routing** | ✅ embedding intent + 13-dimension scorer, verified cascade | ⚠️ Auto Router v2 (v1.94): heuristic under-routes, LLM classifier billed per request | ❌ | ❌ Manual metadata |
 | **TOON JSON compression** | ✅ up to 87.6% | ❌ | ❌ | ❌ |
 | **Smart tool selection** | ✅ up to 60% token reduction | ❌ | ❌ | ❌ |
 | **Semantic cache** | ✅ 171ms hits, 0 tokens | ❌ | ❌ | ✅ Prompt cache only |

package/bin/cli.js

@@ -7,19 +7,31 @@ const pkg = require('../package.json');
 // don't start the proxy. Add new subcommands here, not in scattered binaries.
 const SUBCOMMANDS = {
   usage:      path.join(__dirname, "lynkr-usage.js"),
+  stats:      path.join(__dirname, "lynkr-usage.js"),
   trajectory: path.join(__dirname, "lynkr-trajectory.js"),
   wrap:       path.join(__dirname, "wrap.js"),
   init:       path.join(__dirname, "lynkr-init.js"),
 };
 
 const sub = process.argv[2];
-if (sub && Object.prototype.hasOwnProperty.call(SUBCOMMANDS, sub)) {
+// `lynkr start` is an alias for `lynkr` (start the proxy). Drop the token
+// and fall through so users can use whichever spelling they prefer.
+if (sub === 'start') {
+  process.argv.splice(2, 1);
+} else if (sub && Object.prototype.hasOwnProperty.call(SUBCOMMANDS, sub)) {
   process.argv.splice(2, 1); // drop the subcommand token so the script's own arg parser is happy
   // Subcommand scripts check this to decide whether to invoke their main()
   // when they're require()'d (vs being loaded by a test for unit-checking).
   process.env._LYNKR_SUBCMD = sub;
   require(SUBCOMMANDS[sub]);
   return;
+} else if (sub && !sub.startsWith('-')) {
+  // Unknown positional commands must error loudly, not silently boot the
+  // server (`lynkr codex` used to start a bare gateway and never say why).
+  console.error(`Error: unknown command '${sub}'.`);
+  console.error(`Did you mean: lynkr wrap ${sub}`);
+  console.error(`Known commands: ${Object.keys(SUBCOMMANDS).join(', ')}, start (or no command to start the server)`);
+  process.exit(1);
 }
 
 if (process.argv.includes('--version') || process.argv.includes('-v')) {
@@ -35,8 +47,11 @@ ${pkg.description}
 
 Usage:
   lynkr [options]                  Start the proxy server (default)
+  lynkr start [options]            Alias for the above
+  lynkr init [options]             Interactive setup wizard (writes .env, pulls classifier model)
   lynkr wrap <target> [options]    Wrap CLI tools through Lynkr proxy
   lynkr usage [options]            Show AI spend report and tier-routing savings
+  lynkr stats [options]            Shareable savings-receipt card (also: lynkr usage --card)
   lynkr trajectory [options]       Export agent trajectories as JSONL training data
 
 Options:

package/bin/lynkr-init.js

@@ -98,6 +98,15 @@ const PROVIDERS = {
     extras: [],
     defaultModel: 'anthropic/claude-sonnet-4',
   },
+  edenai: {
+    label: 'Eden AI (600+ models, one key, EU/GDPR)',
+    local: false,
+    creds: [
+      { key: 'EDENAI_API_KEY', label: 'Eden AI API key', secret: true },
+    ],
+    extras: [],
+    defaultModel: 'anthropic/claude-sonnet-4-5',
+  },
   databricks: {
     label: 'Databricks Foundation Models',
     local: false,
@@ -154,7 +163,7 @@ const PROVIDERS = {
 
 const PROVIDER_ORDER = [
   'ollama', 'llamacpp', 'lmstudio',
-  'azure-anthropic', 'azure-openai', 'openai', 'openrouter',
+  'azure-anthropic', 'azure-openai', 'openai', 'openrouter', 'edenai',
   'databricks', 'bedrock', 'vertex', 'zai', 'moonshot',
 ];
 const TIERS = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
@@ -304,6 +313,10 @@ const BASELINE_ENV = {
   OPENROUTER_EMBEDDINGS_MODEL: 'openai/text-embedding-ada-002',
   OPENROUTER_ENDPOINT: 'https://openrouter.ai/api/v1/chat/completions',
   OPENROUTER_MAX_TOOLS_FOR_ROUTING: '15',
+  EDENAI_API_KEY: '',
+  EDENAI_MODEL: 'openai/gpt-4o-mini',
+  EDENAI_EMBEDDINGS_MODEL: 'openai/text-embedding-ada-002',
+  EDENAI_ENDPOINT: 'https://api.edenai.run/v3/chat/completions',
   MOONSHOT_API_KEY: '',
   MOONSHOT_ENDPOINT: 'https://api.moonshot.ai/v1/chat/completions',
   MOONSHOT_MODEL: 'kimi-k2.6',
@@ -537,6 +550,36 @@ async function runInteractive(opts) {
     close();
     console.log('');
     writeEnvFile(buildEnvContent(env, isWrap, tierConfig), opts);
+
+    // ── Classifier bootstrap: detect ollama, pull model, warm-up ──
+    // Runs AFTER .env is written so the classifier can read tier config
+    // (currently uses hardcoded qwen2.5:3b, but leaves room for the future
+    // fine-tuned model to plug in via SIMPLE tier or an env override).
+    if (!opts.dryRun) {
+      console.log('');
+      console.log('Setting up the difficulty classifier…');
+      try {
+        const { ensureClassifierReady } = require('../src/routing/classifier-setup');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const prompt = (q) => new Promise((res) => rl.question(q, (a) => res(a)));
+        const result = await ensureClassifierReady({
+          mode: 'interactive',
+          log: (m) => console.log(m),
+          warn: (m) => console.warn(m),
+          prompt,
+        });
+        rl.close();
+        if (result.ready) {
+          console.log('✓ Classifier ready.');
+        } else if (result.reason === 'ollama_missing') {
+          console.log('(Install Ollama and re-run `lynkr init` to enable the classifier — Lynkr will still start without it, using anchor-only scoring.)');
+        } else {
+          console.log(`(Classifier disabled: ${result.reason}. Lynkr will fall back to anchor-only scoring.)`);
+        }
+      } catch (err) {
+        console.warn(`⚠ Classifier setup skipped: ${err.message}`);
+      }
+    }
   } catch (err) {
     close();
     throw err;

package/bin/lynkr-usage.js

@@ -18,6 +18,10 @@ const path = require("path");
 // Make sure config/logger pick up the workspace root
 process.env.WORKSPACE_ROOT = process.env.WORKSPACE_ROOT || path.resolve(__dirname, "..");
 
+// Reports and receipts go to stdout for humans (and screenshots) — telemetry
+// init logs would pollute them. Respect an explicit LOG_LEVEL override.
+if (!process.env.LOG_LEVEL) process.env.LOG_LEVEL = "silent";
+
 const aggregator = require("../src/usage/aggregator");
 
 function parseArgs(argv) {
@@ -26,6 +30,7 @@ function parseArgs(argv) {
     const a = argv[i];
     const next = argv[i + 1];
     if (a === "--json") opts.json = true;
+    else if (a === "--card") opts.card = true;
     else if (a === "--days" && next) {
       opts.window = `${parseInt(next, 10)}d`;
       i++;
@@ -204,6 +209,74 @@ function printReport(usage) {
   console.log("");
 }
 
+// ---------------------------------------------------------------------------
+// Shareable receipt card (`lynkr stats` / `lynkr usage --card`)
+// ---------------------------------------------------------------------------
+
+const LOCAL_PROVIDERS = new Set(["ollama", "llamacpp", "llama-cpp", "llama_cpp", "lmstudio", "lm-studio"]);
+
+function printCard(usage, opts) {
+  const { totals, byProvider, flagship, window } = usage;
+
+  let localReqs = 0;
+  let cloudReqs = 0;
+  for (const [provider, bucket] of Object.entries(byProvider)) {
+    if (LOCAL_PROVIDERS.has(String(provider).toLowerCase())) localReqs += bucket.requests;
+    else cloudReqs += bucket.requests;
+  }
+  const totalReqs = localReqs + cloudReqs;
+  const pct = (n) => (totalReqs > 0 ? `${Math.round((n / totalReqs) * 100)}%` : "0%");
+
+  let savings = { total: 0, byCategory: {} };
+  try {
+    const telemetry = require("../src/routing/telemetry");
+    const since = aggregator.resolveSince(opts.window) ?? 0;
+    savings = telemetry.getSavingsSummary(since);
+  } catch { /* savings table optional */ }
+
+  const WIDTH = 46;
+  const line = (label, value) => {
+    const l = ` ${label}`;
+    const v = `${value} `;
+    const gap = Math.max(1, WIDTH - l.length - v.length);
+    return `│${l}${" ".repeat(gap)}${v}│`;
+  };
+  const blank = `│${" ".repeat(WIDTH)}│`;
+
+  const rows = [
+    `╭${"─".repeat(WIDTH)}╮`,
+    line("Lynkr — savings receipt", `last ${window}`),
+    blank,
+    line("Requests routed", fmtInt(totalReqs)),
+    line("  local (free)", `${fmtInt(localReqs)} · ${pct(localReqs)}`),
+    line("  cloud", `${fmtInt(cloudReqs)} · ${pct(cloudReqs)}`),
+    blank,
+  ];
+
+  if (savings.total > 0) {
+    rows.push(line("Tokens saved", fmtTokens(savings.total)));
+    const labels = {
+      tool_stripping: "  tool-schema stripping",
+      compression: "  JSON compression",
+      cache_hit: "  semantic cache hits",
+    };
+    for (const [cat, label] of Object.entries(labels)) {
+      if (savings.byCategory[cat]) rows.push(line(label, fmtTokens(savings.byCategory[cat])));
+    }
+    rows.push(blank);
+  }
+
+  rows.push(line("Est. cost avoided*", fmtUSD(totals.saved)));
+  rows.push(blank);
+  rows.push(line("github.com/Fast-Editor/Lynkr", `v${require("../package.json").version}`));
+  rows.push(`╰${"─".repeat(WIDTH)}╯`);
+  rows.push(colour(`  *estimate vs routing everything to ${flagship}`, C.dim));
+
+  console.log("");
+  for (const row of rows) console.log(row);
+  console.log("");
+}
+
 function main() {
   const opts = parseArgs(process.argv);
   const usage = aggregator.getUsage(opts);
@@ -213,6 +286,11 @@ function main() {
     return;
   }
 
+  if (opts.card || process.env._LYNKR_SUBCMD === "stats") {
+    printCard(usage, opts);
+    return;
+  }
+
   printReport(usage);
 }
 

package/bin/wrap.js

@@ -224,7 +224,7 @@ async function wrapClaude() {
     // Show stats if enabled and clean exit
     if (process.env.LYNKR_WRAP_SHOW_STATS !== 'false' && code === 0) {
       try {
-        await showSessionStats();
+        await showSessionStats(port);
       } catch (err) {
         // Stats are nice-to-have, don't fail on error
       }
@@ -323,9 +323,21 @@ async function wrapCodex() {
     binaryName: 'codex',
     findBinary: findCodexBinary,
     envVar: 'OPENAI_API_BASE',
+    // Modern Codex (Rust CLI) ignores OPENAI_API_BASE — with ChatGPT-plan
+    // auth it talks straight to its own backend. A custom model_provider
+    // passed via -c overrides is the only supported redirect, and it beats
+    // every config file. env_key must name an env var that is set.
+    extraArgs: (port) => [
+      '-c', 'model_providers.lynkr.name="Lynkr"',
+      '-c', `model_providers.lynkr.base_url="http://localhost:${port}/v1"`,
+      '-c', 'model_providers.lynkr.wire_api="responses"',
+      '-c', 'model_providers.lynkr.env_key="LYNKR_API_KEY"',
+      '-c', 'model_provider="lynkr"',
+    ],
+    extraEnv: { LYNKR_API_KEY: 'lynkr-local' },
     installInstructions: [
-      '  • Install OpenAI CLI: pip install openai',
-      '  • Or: npm install -g openai',
+      '  • brew install --cask codex',
+      '  • Or: npm install -g @openai/codex',
     ],
   });
 }
@@ -409,10 +421,12 @@ async function wrapGeneric(opts) {
   console.log('');
 
   // 4. Launch binary with Lynkr as base URL
-  const child = spawn(binaryPath, targetArgs, {
+  const extraArgs = typeof opts.extraArgs === 'function' ? opts.extraArgs(port) : [];
+  const child = spawn(binaryPath, [...extraArgs, ...targetArgs], {
     env: {
       ...process.env,
       [opts.envVar]: `http://localhost:${port}`,
+      ...(opts.extraEnv || {}),
     },
     stdio: 'inherit',
   });
@@ -451,7 +465,7 @@ async function wrapGeneric(opts) {
     // Show stats if enabled and clean exit
     if (process.env.LYNKR_WRAP_SHOW_STATS !== 'false' && code === 0) {
       try {
-        await showSessionStats();
+        await showSessionStats(port);
       } catch (err) {
         // Stats are nice-to-have, don't fail on error
       }
@@ -628,19 +642,39 @@ function formatDuration(ms) {
   return `${seconds}s`;
 }
 
-async function showSessionStats() {
-  try {
-    const { getMetricsCollector } = require('../src/observability/metrics');
-    const metricsCollector = getMetricsCollector();
-    const metrics = metricsCollector.getMetrics();
-
-    // Check if we have any data
-    const hasRequests = metrics && (
-      (typeof metrics.totalRequests === 'number' && metrics.totalRequests > 0) ||
-      (typeof metrics.requestCount === 'number' && metrics.requestCount > 0)
+async function showSessionStats(port) {
+  // Read metrics from the RUNNING gateway over HTTP first — correct under
+  // cluster mode (workers hold the counters, not this process) — and fall
+  // back to the in-process collector. Field names follow getMetrics()'s
+  // snake_case output (requests_total, tokens_total, cost_usd_total):
+  // this function historically read camelCase fields that never existed,
+  // so every session ended with "No requests tracked" regardless of
+  // traffic.
+  const fetchMetrics = () => new Promise((resolve) => {
+    if (!port) return resolve(null);
+    const req = require('http').get(
+      `http://localhost:${port}/metrics/observability`,
+      (res) => {
+        let buf = '';
+        res.on('data', (c) => { buf += c; });
+        res.on('end', () => {
+          try { resolve(JSON.parse(buf)); } catch { resolve(null); }
+        });
+      }
     );
+    req.on('error', () => resolve(null));
+    req.setTimeout(1500, () => { req.destroy(); resolve(null); });
+  });
 
-    if (!hasRequests) {
+  try {
+    let metrics = await fetchMetrics();
+    if (!metrics) {
+      const { getMetricsCollector } = require('../src/observability/metrics');
+      metrics = getMetricsCollector().getMetrics();
+    }
+
+    const requestCount = Number(metrics?.requests_total) || 0;
+    if (!requestCount) {
       console.log('');
       console.log('╭─ Lynkr Session Stats ────────────────────────────────');
       console.log('│  No requests tracked (check dashboard for details)');
@@ -650,29 +684,20 @@ async function showSessionStats() {
 
     console.log('');
     console.log('╭─ Lynkr Session Stats ────────────────────────────────');
+    console.log(`│  Requests      ${requestCount} (${Number(metrics.requests_errors_total) || 0} errors)`);
 
-    const requestCount = metrics.totalRequests || metrics.requestCount || 0;
-    console.log(`│  Requests      ${requestCount}`);
-
-    if (metrics.tokensUsed || metrics.tokensSaved) {
-      const tokensUsed = metrics.tokensUsed || 0;
-      const tokensSaved = metrics.tokensSaved || 0;
-      const originalTokens = tokensUsed + tokensSaved;
-      if (originalTokens > 0) {
-        const savingsPercent = Math.round((tokensSaved / originalTokens) * 100);
-        console.log(`│  Tokens        Original: ${originalTokens.toLocaleString()}  →  Routed: ${tokensUsed.toLocaleString()}  (${savingsPercent}% saved)`);
-      }
+    const tokensIn = Number(metrics.tokens_input_total) || 0;
+    const tokensOut = Number(metrics.tokens_output_total) || 0;
+    if (tokensIn || tokensOut) {
+      console.log(`│  Tokens        in ${tokensIn.toLocaleString()} · out ${tokensOut.toLocaleString()}`);
     }
 
-    if (metrics.tierBreakdown && Object.keys(metrics.tierBreakdown).length > 0) {
-      const tiers = Object.entries(metrics.tierBreakdown)
-        .map(([tier, count]) => `${tier}: ${count}`)
-        .join('  ');
-      console.log(`│  Tier Mix      ${tiers}`);
-    }
+    const cost = Number(metrics.cost_usd_total) || 0;
+    console.log(`│  Est. cost     $${cost.toFixed(4)}`);
 
-    if (metrics.cacheHits && metrics.cacheHits > 0) {
-      console.log(`│  Cache Hits    ${metrics.cacheHits}`);
+    const p95 = metrics.latency_ms && Number(metrics.latency_ms.p95);
+    if (p95) {
+      console.log(`│  Latency p95   ${p95.toLocaleString()} ms`);
     }
 
     console.log('╰──────────────────────────────────────────────────────');

package/config/difficulty-anchors.json

@@ -0,0 +1,22 @@
+{
+  "_comment": "WS7.1b — difficulty anchor exemplars. All texts are REAL user asks from live telemetry / the engineering ledger (do not invent synthetic anchors; mine new ones with the §7 telemetry query). Embedded at boot via the kNN router's embed(); centroid vectors cached in difficulty-anchors.vectors.json (safe to delete — regenerates).",
+  "trivial": [
+    "hi",
+    "How are you",
+    "ok thanks",
+    "345+32",
+    "how do I install golang on mac?",
+    "what is meaning of purging?",
+    "Explain the difference between TCP and UDP in two sentences."
+  ],
+  "substantive": [
+    "Review this retry helper for bugs and race conditions",
+    "give me a plan to refactor this code",
+    "Read the current repo and explain it to me"
+  ],
+  "heavyweight": [
+    "Do an architecture review of the orchestrator",
+    "analyze every module in src/ for circular dependencies and give me a dependency-order refactor plan",
+    "design a horizontally scalable architecture for this service with failure-mode analysis"
+  ]
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "lynkr",
-  "version": "9.7.3",
+  "version": "9.9.1",
+  "files": [
+    "index.js",
+    "install.sh",
+    "bin",
+    "config",
+    "public",
+    "skills",
+    "lynkr-skill.tar.gz",
+    "src",
+    "!src/db/database.sqlite",
+    "!src/**/*.db",
+    "!src/**/*.backup",
+    "native/index.js",
+    "native/lynkr-native.node",
+    "native/src/lib.rs",
+    "native/Cargo.toml",
+    "models/router/README.md",
+    "scripts",
+    "!scripts/export-routellm-bert.py"
+  ],
   "description": "Self-hosted LLM gateway and tier-routing proxy for Claude Code, Cursor, and Codex. Routes across Ollama, AWS Bedrock, OpenRouter, Databricks, Azure OpenAI, llama.cpp, and LM Studio with prompt caching, MCP tools, and 60-80% cost savings.",
   "main": "index.js",
   "bin": {
@@ -16,7 +36,7 @@
     "dev": "nodemon index.js",
     "lint": "eslint src index.js",
     "test": "npm run test:unit && npm run test:performance",
-    "test:unit": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node --test test/routing.test.js test/hybrid-routing-integration.test.js test/web-tools.test.js test/passthrough-mode.test.js test/openrouter-error-resilience.test.js test/format-conversion.test.js test/azure-openai-config.test.js test/azure-openai-format-conversion.test.js test/azure-openai-routing.test.js test/azure-openai-streaming.test.js test/azure-openai-error-resilience.test.js test/azure-openai-integration.test.js test/openai-integration.test.js test/toon-compression.test.js test/llamacpp-integration.test.js test/resilience.test.js test/telemetry-routing.test.js test/memory/store.test.js test/memory/surprise.test.js test/memory/extractor.test.js test/memory/search.test.js test/memory/retriever.test.js test/distill.test.js test/large-payload.test.js test/code-mode.test.js test/prompt-cache-injection.test.js test/risk-analyzer.test.js test/interaction-block.test.js test/preflight.test.js test/token-reduction.test.js test/session-affinity.test.js test/model-registry-cost.test.js test/task-decomposition.test.js test/output-format-guard.test.js test/tier-fallback.test.js test/wrap.test.js test/init.test.js test/agent-learning.test.js test/tool-call-response-metadata.test.js",
+    "test:unit": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com LOG_FILE_ENABLED=false node --test test/routing.test.js test/hybrid-routing-integration.test.js test/web-tools.test.js test/passthrough-mode.test.js test/openrouter-error-resilience.test.js test/format-conversion.test.js test/azure-openai-config.test.js test/azure-openai-format-conversion.test.js test/azure-openai-routing.test.js test/azure-openai-streaming.test.js test/azure-openai-error-resilience.test.js test/azure-openai-integration.test.js test/openai-integration.test.js test/toon-compression.test.js test/gcf-compression.test.js test/llamacpp-integration.test.js test/resilience.test.js test/telemetry-routing.test.js test/memory/store.test.js test/memory/surprise.test.js test/memory/extractor.test.js test/memory/search.test.js test/memory/retriever.test.js test/distill.test.js test/large-payload.test.js test/code-mode.test.js test/prompt-cache-injection.test.js test/risk-analyzer.test.js test/interaction-block.test.js test/preflight.test.js test/token-reduction.test.js test/session-affinity.test.js test/model-registry-cost.test.js test/task-decomposition.test.js test/output-format-guard.test.js test/tier-fallback.test.js test/wrap.test.js test/init.test.js test/agent-learning.test.js test/tool-call-response-metadata.test.js test/degradation.test.js test/routing-telemetry-columns.test.js test/sticky-routing.test.js test/knn-ambiguous-escalate.test.js test/deescalator.test.js test/client-profiles.test.js test/strip-internal-fields.test.js test/complexity-tool-subtraction.test.js test/bandit.test.js test/routing-propensity.test.js test/reward-pipeline.test.js test/knn-cold-start.test.js test/calibration.test.js test/feedback-loop.test.js test/session-fingerprint.test.js test/side-request-guards.test.js test/verifier.test.js test/intent-score.test.js test/difficulty-classifier.test.js test/classifier-setup.test.js test/usage-stats.test.js test/loop-guard.test.js",
     "test:memory": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node --test test/memory/store.test.js test/memory/surprise.test.js test/memory/extractor.test.js test/memory/search.test.js test/memory/retriever.test.js",
     "test:new-features": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node --test test/passthrough-mode.test.js test/openrouter-error-resilience.test.js test/format-conversion.test.js",
     "test:performance": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node test/hybrid-routing-performance.test.js && DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com node test/performance-tests.js",
@@ -71,6 +91,7 @@
     "@azure/openai": "^2.0.0",
     "@babel/parser": "^7.29.0",
     "@babel/traverse": "^7.29.0",
+    "@blackwell-systems/gcf": "2.4.0",
     "@toon-format/toon": "^2.1.0",
     "cockatiel": "^3.2.1",
     "compression": "^1.7.4",