lynkr 9.11.0 → 9.12.0

package/README.md

@@ -5,7 +5,7 @@
 **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-1041%20passing-brightgreen)](https://github.com/Fast-Editor/Lynkr)
+[![Tests](https://img.shields.io/badge/tests-1249%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)
@@ -28,25 +28,26 @@
 
 ## 🚀 New: Wrap Mode for AI Coding Tools
 
-**Use Lynkr's routing with your AI coding assistant — maximize your subscription value:**
+**Use Lynkr's routing with your AI coding assistant — BYO API keys, route by task complexity:**
 
 ```bash
 npm install -g lynkr
 
 
-# Claude Code Pro/Max
+# Claude Code (with your own ANTHROPIC_API_KEY)
 lynkr wrap claude
 
 
 ```
 
 **Wrapping gives you:**
-- ✅ Tier routing (send simple tasks to free Ollama, complex to your subscription/API)
+- ✅ Tier routing (send simple tasks to free Ollama, complex to your configured API provider)
 - ✅ 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)
+- ✅ Works with API keys (Claude, Aider, Codex, Copilot, Cursor)
+
+> **Note on subscription (OAuth) logins:** Anthropic's Feb 2026 usage policy prohibits third-party tools from using OAuth tokens issued to Free/Pro/Max accounts. Wrap mode's tier routing, compression, and caching require an API key — they do not apply to and are not compatible with Claude Pro/Max subscription auth. See [ToS Compliance](docs/wrap-guide.md#tos-compliance) for details.
 
 [Full wrap guide →](docs/wrap-guide.md)
 
@@ -68,7 +69,7 @@ The fastest path is the interactive wizard:
 lynkr init
 ```
 
-It asks four questions — usage mode (Claude Pro/Max via wrap, or direct API keys), tier picks for SIMPLE/MEDIUM/COMPLEX/REASONING across the 12 supported providers, credentials for what you chose, and a few routing-intelligence knobs — then writes a fully-populated `.env` with sensible production defaults for everything else (caching, compression, policy budgets, MCP sandbox, rate limiting).
+It asks four questions — usage mode (BYO API keys, direct), tier picks for SIMPLE/MEDIUM/COMPLEX/REASONING across the 12 supported providers, credentials for what you chose, and a few routing-intelligence knobs — then writes a fully-populated `.env` with sensible production defaults for everything else (caching, compression, policy budgets, MCP sandbox, rate limiting).
 
 Useful flags:
 
@@ -326,12 +327,45 @@ the local telemetry store:
 - **Routing accuracy** — over-/under-provisioned request counts, a self-audit
   of the tier router's decisions
 - **Request logs** — filterable by provider, tier, and errors, with latency,
-  tokens, and cost per request
+  tokens, and cost per request; every session id links to a drill-down
 - **Provider health** — configured providers, credential warnings, circuit
   breaker states
+- **Insights** — analyzer findings ranked by *past overspend* (auditable
+  against spend already recorded, never projected savings): dead tool
+  schemas paying rent, harness side-traffic served on expensive tiers,
+  weak prompt-cache hit ratios, and Wilson-bounded tier-downsize verdicts.
+  Each finding ships its evidence rows, the fix, the caveat, and how the
+  figure was computed. "Not measured yet" is rendered distinctly from
+  zero — an un-run scan is not an all-clear.
+- **Explore** — a Metric × Dimension (× Stack) pivot over routing telemetry
+  (spend/tokens/requests/sessions by provider, model, tier, request type,
+  day…) with preset views, period-over-period deltas, and CSV export
+- **Session drill-down** — per-model cost mix and an input-context-per-call
+  chart where distillation and cache behavior are directly visible
+- **Cache receipts** — projected switch/hold economics from cache-aware
+  routing next to the *measured* companion (dollars saved by cache reads
+  actually served)
+
+JSON APIs behind it
+(`/dashboard/api/overview|usage|routing|logs|recommendations|analytics|sessions/:id|statusline`)
+if you want the raw numbers.
+
+### Status line for Claude Code
+
+One line after every turn — routed tier, served model, today's spend, and
+cache re-read share — with zero token cost (out-of-band, never enters model
+context). Add to `~/.claude/settings.json`:
+
+```json
+"statusLine": { "type": "command", "command": "lynkr-statusline" }
+```
+
+```
+◆ Opus 4.8 · MEDIUM → minimax-m3:cloud (ollama) · today $0.06 · cache 67%
+```
 
-JSON APIs behind it (`/dashboard/api/overview|usage|routing|logs`) if you want
-the raw numbers.
+Always prints exactly one line and always exits 0 — a down proxy can never
+break the harness. Set `LYNKR_PORT` if Lynkr isn't on 8081.
 
 ### Cost tracking & model pricing
 Per-request cost is computed from a model-pricing registry (LiteLLM → models.dev,
@@ -551,7 +585,8 @@ With tier routing + token optimization: **additional 50-87% savings** on cloud p
 | **TOON JSON compression** | ✅ up to 87.6% | ❌ | ❌ | ❌ |
 | **Upstream SSE streaming** | ✅ native passthrough + cross-format transform | ⚠️ passthrough only | ✅ | ⚠️ |
 | **Semantic cache** | ✅ 171ms hits, 0 tokens | ❌ | ❌ | ✅ Prompt cache only |
-| **Savings & routing dashboard** | ✅ spend, savings vs flagship, tier mix, routing accuracy, request logs | ⚠️ spend UI only | ⚠️ usage page | ✅ observability suite (no routing accuracy) |
+| **Savings & routing dashboard** | ✅ spend, savings vs flagship, tier mix, routing accuracy, request logs, pivot explorer, session drill-down | ⚠️ spend UI only | ⚠️ usage page | ✅ observability suite (no routing accuracy) |
+| **Cost recommendations** | ✅ evidence-backed findings (dead tool schemas, side-traffic, cache weak spots, Wilson-proven downsizes) ranked by past overspend | ❌ | ❌ | ⚠️ alerts, no findings |
 | **Long-term memory** | ✅ SQLite, per-session | ❌ | ❌ | ❌ |
 | **MCP integration** | ✅ | ❌ | ❌ | ❌ |
 | **Self-hosted** | ✅ Node.js only | ✅ Python stack | ❌ SaaS | ✅ Docker |

package/bin/statusline.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * lynkr statusline — zero-token Claude Code status line.
+ *
+ * Wire into ~/.claude/settings.json:
+ *   "statusLine": { "type": "command", "command": "lynkr-statusline" }
+ *
+ * Claude Code pipes session JSON on stdin after each turn. This command:
+ *  - never enters model context (out-of-band — an in-loop MCP integration
+ *    was measured at +36% model-weighted tokens by TokenJam; don't do that)
+ *  - makes ONE local HTTP call to the Lynkr dashboard API with a hard
+ *    250ms timeout
+ *  - always exits 0 and always prints exactly one line, no matter what
+ *    fails — a broken status line must never break the harness.
+ *
+ * Output: ◆ <model> · <tier> → <served model> (<provider>)[ · pin] · today $X · cache NN%
+ */
+
+'use strict';
+
+const PORT = Number(process.env.LYNKR_PORT) || Number(process.env.PORT) || 8081;
+const TIMEOUT_MS = 250;
+
+function readStdin(maxMs) {
+  return new Promise((resolve) => {
+    let data = '';
+    const timer = setTimeout(() => resolve(data), maxMs);
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(data); });
+  });
+}
+
+async function fetchStatus() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(`http://127.0.0.1:${PORT}/dashboard/api/statusline`, {
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main() {
+  const [stdinRaw, status] = await Promise.all([readStdin(150), fetchStatus()]);
+
+  let clientModel = null;
+  try {
+    const parsed = JSON.parse(stdinRaw);
+    clientModel = parsed?.model?.display_name || parsed?.model?.id || null;
+  } catch { /* stdin absent or non-JSON — fine */ }
+
+  const parts = [];
+  if (clientModel) parts.push(clientModel);
+
+  if (status?.last) {
+    const served = `${status.last.tier || '?'} → ${status.last.model || '?'} (${status.last.provider || '?'})`;
+    parts.push(served + (status.last.pinned ? ' · pin' : ''));
+  } else {
+    parts.push('lynkr: no traffic yet');
+  }
+  if (status && typeof status.todaySpendUsd === 'number') {
+    parts.push(`today $${status.todaySpendUsd.toFixed(2)}`);
+  }
+  if (status && typeof status.cacheReadPct === 'number') {
+    parts.push(`cache ${status.cacheReadPct}%`);
+  }
+
+  process.stdout.write('◆ ' + parts.join(' · ') + '\n');
+}
+
+main()
+  .catch(() => { process.stdout.write('◆ lynkr statusline unavailable\n'); })
+  .finally(() => process.exit(0));

package/bin/wrap.js

@@ -114,13 +114,16 @@ async function wrapClaude() {
 
   let server;
   try {
-    const { start } = require('../src/server');
-
-    // Override port if specified
+    // Override port BEFORE requiring the server: src/config reads
+    // process.env.PORT at module-load time, so setting it after the require
+    // is a no-op — the server binds the .env port and --port silently fails
+    // (printed 8082, bound 8081).
     if (port !== 8081) {
       process.env.PORT = String(port);
     }
 
+    const { start } = require('../src/server');
+
     server = await start();
 
     // Wait for server to be ready
@@ -381,13 +384,14 @@ async function wrapGeneric(opts) {
 
   let server;
   try {
-    const { start } = require('../src/server');
-
-    // Override port if specified
+    // Set PORT before requiring the server — src/config freezes
+    // process.env.PORT at module-load time (same fix as the claude path).
     if (port !== 8081) {
       process.env.PORT = String(port);
     }
 
+    const { start } = require('../src/server');
+
     server = await start();
 
     // Wait for server to be ready

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkr",
-  "version": "9.11.0",
+  "version": "9.12.0",
   "files": [
     "index.js",
     "install.sh",
@@ -25,7 +25,8 @@
   "main": "index.js",
   "bin": {
     "lynkr": "bin/cli.js",
-    "lynkr-setup": "scripts/setup.js"
+    "lynkr-setup": "scripts/setup.js",
+    "lynkr-statusline": "bin/statusline.js"
   },
   "scripts": {
     "postinstall": "node scripts/check-native.js",
@@ -36,7 +37,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 LOG_FILE_ENABLED=false node --test test/routing.test.js test/hybrid-routing-integration.test.js test/retry-logic.test.js test/sse-transformer.test.js test/passthrough-stream.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/memory/distiller.test.js test/memory/distiller-freeze.test.js test/memory/wiki.test.js test/memory/skills-cache.test.js test/memory/tencentdb-launcher.test.js test/distill.test.js test/large-payload.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/cache-state.test.js test/cache-switch-cost.test.js test/model-registry-cost.test.js test/output-format-guard.test.js test/tier-fallback.test.js test/wrap.test.js test/init.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/moonshot-model-mapping.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/retry-logic.test.js test/sse-transformer.test.js test/passthrough-stream.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/memory/distiller.test.js test/memory/distiller-freeze.test.js test/memory/wiki.test.js test/memory/skills-cache.test.js test/memory/tencentdb-launcher.test.js test/distill.test.js test/large-payload.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/cache-state.test.js test/cache-switch-cost.test.js test/lens-recommendations.test.js test/model-registry-cost.test.js test/output-format-guard.test.js test/tier-fallback.test.js test/wrap.test.js test/init.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/moonshot-model-mapping.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/memory/distiller.test.js test/memory/distiller-freeze.test.js test/memory/wiki.test.js test/memory/skills-cache.test.js test/memory/tencentdb-launcher.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",
@@ -92,6 +93,7 @@
     "@babel/parser": "^7.29.0",
     "@babel/traverse": "^7.29.0",
     "@blackwell-systems/gcf": "2.4.0",
+    "@tencentdb-agent-memory/memory-tencentdb": "^1.0.1",
     "@toon-format/toon": "^2.1.0",
     "cockatiel": "^3.2.1",
     "compression": "^1.7.4",
@@ -123,5 +125,8 @@
     "eslint": "^8.57.0",
     "nodemon": "^3.1.0",
     "pino-pretty": "^10.2.0"
+  },
+  "allowScripts": {
+    "@tencentdb-agent-memory/memory-tencentdb@1.0.1": true
   }
 }