lynkr 9.0.1 → 9.1.2

package/README.md

@@ -3,7 +3,7 @@
 ### Run Claude Code, Cursor, and Codex on any model. One proxy, every provider.
 
 [![npm version](https://img.shields.io/npm/v/lynkr.svg)](https://www.npmjs.com/package/lynkr)
-[![Tests](https://img.shields.io/badge/tests-652%20passing-brightgreen)](https://github.com/vishalveerareddy123/Lynkr)
+[![Tests](https://img.shields.io/badge/tests-699%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)
 [![Homebrew Tap](https://img.shields.io/badge/homebrew-lynkr-brightgreen.svg)](https://github.com/vishalveerareddy123/homebrew-lynkr)
@@ -11,9 +11,9 @@
 
 <table>
 <tr>
-<td align="center"><strong>10+</strong><br/>LLM Providers</td>
+<td align="center"><strong>12+</strong><br/>LLM Providers</td>
 <td align="center"><strong>60-80%</strong><br/>Cost Reduction</td>
-<td align="center"><strong>652</strong><br/>Tests Passing</td>
+<td align="center"><strong>699</strong><br/>Tests Passing</td>
 <td align="center"><strong>0</strong><br/>Code Changes Required</td>
 </tr>
 </table>
@@ -55,6 +55,12 @@ lynkr start
 
 ### Install
 
+**One-line install (recommended):**
+```bash
+curl -fsSL https://raw.githubusercontent.com/Fast-Editor/Lynkr/main/install.sh | bash
+```
+
+**Or via npm:**
 ```bash
 npm install -g pino-pretty && npm install -g lynkr
 ```
@@ -125,7 +131,24 @@ const { text } = await generateText({
 });
 ```
 
-> Works with any OpenAI-compatible client: Cline, Continue.dev, ClawdBot, KiloCode, and more.
+**OpenClaw**
+```json
+// openclaw.json
+{
+  "models": {
+    "providers": [{
+      "name": "lynkr",
+      "type": "openai-compatible",
+      "base_url": "http://localhost:8081/v1",
+      "api_key": "any-value",
+      "models": ["auto"]
+    }]
+  }
+}
+```
+Set `OPENCLAW_MODE=true` in Lynkr's `.env` to show actual provider/model in responses.
+
+> Works with any OpenAI-compatible client: Cline, Continue.dev, OpenClaw, KiloCode, and more.
 
 ---
 
@@ -139,12 +162,16 @@ const { text } = await generateText({
 | **MLX Server** | Local | Apple Silicon optimized | **Free** |
 | **AWS Bedrock** | Cloud | 100+ (Claude, Llama, Mistral, Titan) | $$ |
 | **OpenRouter** | Cloud | 100+ (GPT, Claude, Llama, Gemini) | $-$$ |
-| **Databricks** | Cloud | Claude Sonnet 4.5, Opus 4.5 | $$$ |
-| **Azure OpenAI** | Cloud | GPT-4o, GPT-5, o1, o3 | $$$ |
+| **Databricks** | Cloud | Claude Sonnet 4.5, Opus 4.6 | $$$ |
+| **Azure OpenAI** | Cloud | GPT-4o, o1, o3 | $$$ |
 | **Azure Anthropic** | Cloud | Claude models | $$$ |
-| **OpenAI** | Cloud | GPT-4o, o1, o3 | $$$ |
+| **OpenAI** | Cloud | GPT-4o, o3, o4-mini | $$$ |
+| **Google Vertex** | Cloud | Gemini 2.5 Pro/Flash | $$$ |
+| **Moonshot AI** | Cloud | Kimi K2 Thinking/Turbo | $$ |
+| **Z.AI** | Cloud | GLM-4.7 | $$ |
+| **DeepSeek** | Cloud | DeepSeek Reasoner, R1 | $ |
 
-4 local providers for **100% offline, free** usage. 6+ cloud providers for scale.
+4 local providers for **100% offline, free** usage. 10+ cloud providers for scale.
 
 ---
 
@@ -166,6 +193,9 @@ const { text } = await generateText({
 | **Transaction fees** | None | None (OSS) / Paid enterprise | 5.5% on credits | Free tier / Paid |
 | **Dependencies** | Node.js only | Python, Prisma, PostgreSQL | N/A | Docker, Python |
 | **Format conversion** | Anthropic <-> OpenAI (automatic) | Automatic | N/A | Automatic |
+| **Code intelligence** | Graphify (19-lang AST graph) | No | No | No |
+| **Routing telemetry** | Built-in (SQLite + REST API) | No | Dashboard | Dashboard |
+| **Admin hot-reload** | Yes (no restart) | Requires restart | N/A | Requires restart |
 | **License** | Apache 2.0 | MIT | Proprietary | MIT (gateway) |
 
 **Lynkr's edge:** Purpose-built for AI coding tools. Not a general LLM gateway — a proxy that understands Claude Code, Cursor, and Codex natively, with built-in token optimization, complexity-based routing, and a memory system designed for coding workflows. Installs in one command, runs on Node.js, zero infrastructure required.
@@ -188,20 +218,29 @@ const { text } = await generateText({
 
 Lynkr isn't just a passthrough proxy. It's an optimization layer.
 
-### Smart Routing
-Routes requests to the right model based on task complexity. Simple questions go to fast/cheap models. Complex architectural tasks go to powerful models. You configure the tiers.
+### Smart Routing (5-Phase)
+Routes requests to the right model based on 5-phase complexity analysis. Simple questions go to fast/cheap models. Complex architectural tasks go to powerful models. Includes Graphify structural analysis for code-aware routing.
+
+- **Complexity scoring** — 15-dimension weighted scoring with agentic workflow detection
+- **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
+### Token Optimization (7 Phases)
 - **Smart tool selection** — only sends tools relevant to the current task
-- **Prompt compression** — removes redundant context before sending
+- **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
-- **TOON format** — compact serialization that cuts token count
+- **History compression** — sliding window with Distill-powered structural dedup
+- **Headroom sidecar** — optional 47-92% ML-based compression (Smart Crusher, CCR, LLMLingua)
 
 ### Enterprise Resilience
-- **Circuit breakers** — automatic failover when a provider goes down
+- **Circuit breakers** — automatic failover with half-open probe recovery
+- **Admin hot-reload** — `POST /v1/admin/reload` reloads config + resets circuit breakers without restart
 - **Load shedding** — graceful degradation under high load
 - **Prometheus metrics** — full observability at `/metrics`
 - **Health checks** — K8s-ready endpoints at `/health`
+- **Performance timer** — per-request timing breakdown with `PERF_TIMER=true`
 
 ### Memory System
 Titans-inspired long-term memory with surprise-based filtering. The system remembers important context across sessions and forgets noise — reducing token waste from repeated context.
@@ -214,14 +253,23 @@ SEMANTIC_CACHE_ENABLED=true
 SEMANTIC_CACHE_THRESHOLD=0.95
 ```
 
-### MCP Integration
-Automatic Model Context Protocol server discovery and orchestration. Your MCP tools work through Lynkr without configuration.
+### 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:
+
+```bash
+CODE_MODE_ENABLED=true  # ~96% reduction in tool-catalog tokens
+```
 
 ---
 
 ## Deployment Options
 
-**NPM (recommended)**
+**One-line install (recommended)**
+```bash
+curl -fsSL https://raw.githubusercontent.com/Fast-Editor/Lynkr/main/install.sh | bash
+```
+
+**NPM**
 ```bash
 npm install -g lynkr && lynkr start
 ```
@@ -233,7 +281,7 @@ docker-compose up -d
 
 **Git Clone**
 ```bash
-git clone https://github.com/vishalveerareddy123/Lynkr.git
+git clone https://github.com/Fast-Editor/Lynkr.git
 cd Lynkr && npm install && cp .env.example .env
 npm start
 ```
@@ -251,9 +299,10 @@ brew install lynkr
 | Guide | Description |
 |-------|-------------|
 | [Installation](documentation/installation.md) | All installation methods |
-| [Provider Config](documentation/providers.md) | Setup for all 10+ providers |
+| [Provider Config](documentation/providers.md) | Setup for all 12+ providers |
 | [Claude Code CLI](documentation/claude-code-cli.md) | Detailed Claude Code integration |
 | [Codex CLI](documentation/codex-cli.md) | Codex config.toml setup |
+| [OpenClaw](documentation/openclaw-integration.md) | OpenClaw integration with tier routing |
 | [Cursor IDE](documentation/cursor-integration.md) | Cursor integration + troubleshooting |
 | [Embeddings](documentation/embeddings.md) | @Codebase semantic search (4 options) |
 | [Token Optimization](documentation/token-optimization.md) | 60-80% cost reduction strategies |
@@ -293,8 +342,8 @@ Apache 2.0 — See [LICENSE](LICENSE).
 
 ## Community
 
-- [GitHub Discussions](https://github.com/vishalveerareddy123/Lynkr/discussions) — Questions and tips
-- [Report Issues](https://github.com/vishalveerareddy123/Lynkr/issues) — Bug reports and feature requests
+- [GitHub Discussions](https://github.com/Fast-Editor/Lynkr/discussions) — Questions and tips
+- [Report Issues](https://github.com/Fast-Editor/Lynkr/issues) — Bug reports and feature requests
 - [NPM Package](https://www.npmjs.com/package/lynkr) — Official package
 - [DeepWiki](https://deepwiki.com/vishalveerareddy123/Lynkr) — AI-powered docs search
 

package/bin/cli.js

@@ -1,7 +1,22 @@
 #!/usr/bin/env node
 
+const path = require("path");
 const pkg = require('../package.json');
 
+// Subcommands. Dispatched before server boot so `lynkr usage` / `lynkr trajectory`
+// don't start the proxy. Add new subcommands here, not in scattered binaries.
+const SUBCOMMANDS = {
+  usage:      path.join(__dirname, "lynkr-usage.js"),
+  trajectory: path.join(__dirname, "lynkr-trajectory.js"),
+};
+
+const sub = process.argv[2];
+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
+  require(SUBCOMMANDS[sub]);
+  return;
+}
+
 if (process.argv.includes('--version') || process.argv.includes('-v')) {
   console.log(pkg.version);
   process.exit(0);
@@ -14,14 +29,20 @@ ${pkg.name} v${pkg.version}
 ${pkg.description}
 
 Usage:
-  lynkr [options]
+  lynkr [options]                  Start the proxy server (default)
+  lynkr usage [options]            Show AI spend report and tier-routing savings
+  lynkr trajectory [options]       Export agent trajectories as JSONL training data
 
 Options:
-  -h, --help     Show this help message
-  -v, --version  Show version number
+  -h, --help      Show this help message
+  -v, --version   Show version number
+  --cluster       Enable cluster mode (multi-core)
+  --workers N     Number of worker processes (default: auto)
 
 Environment Variables:
-  See .env.example for configuration options
+  CLUSTER_ENABLED=true    Enable multi-core cluster mode
+  CLUSTER_WORKERS=auto    Worker count (auto = CPU cores - 1)
+  See .env.example for all configuration options
 
 Documentation:
   ${pkg.homepage}
@@ -29,4 +50,13 @@ Documentation:
   process.exit(0);
 }
 
+// CLI flags for cluster mode
+if (process.argv.includes('--cluster')) {
+  process.env.CLUSTER_ENABLED = 'true';
+}
+const workersIdx = process.argv.indexOf('--workers');
+if (workersIdx !== -1 && process.argv[workersIdx + 1]) {
+  process.env.CLUSTER_WORKERS = process.argv[workersIdx + 1];
+}
+
 require("../index.js");

package/bin/lynkr-trajectory.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * lynkr trajectory — export agent trajectories from the session DB
+ * as JSONL training data.
+ *
+ * Usage:
+ *   lynkr trajectory                                     # stdout, last 30 days
+ *   lynkr trajectory --since 7d                          # last 7 days
+ *   lynkr trajectory --output trajectories.jsonl        # write to file
+ *   lynkr trajectory --tier COMPLEX                      # only complex sessions
+ *   lynkr trajectory --anonymize                         # strip PII / paths / secrets
+ *   lynkr trajectory --count                             # just print the row count
+ */
+
+const path = require("path");
+
+process.env.WORKSPACE_ROOT = process.env.WORKSPACE_ROOT || path.resolve(__dirname, "..");
+
+const compressor = require("../src/training/trajectory-compressor");
+
+function parseArgs(argv) {
+  const opts = { since: "30d", anonymize: false, output: "-", count: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    if (a === "--since" && next) {
+      opts.since = next;
+      i++;
+    } else if (a === "--days" && next) {
+      opts.since = `${parseInt(next, 10)}d`;
+      i++;
+    } else if (a === "--tier" && next) {
+      opts.tier = next.toUpperCase();
+      i++;
+    } else if (a === "--output" && next) {
+      opts.output = next;
+      i++;
+    } else if (a === "-o" && next) {
+      opts.output = next;
+      i++;
+    } else if (a === "--anonymize" || a === "--anonymise") {
+      opts.anonymize = true;
+    } else if (a === "--count") {
+      opts.count = true;
+    } else if (a === "--help" || a === "-h") {
+      printHelp();
+      process.exit(0);
+    } else if (a === "--format" && next) {
+      // Reserved for future formats. Only "jsonl" is supported today.
+      if (next !== "jsonl") {
+        console.error(`Unsupported --format: ${next}. Only 'jsonl' is supported.`);
+        process.exit(2);
+      }
+      i++;
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  console.log(`Lynkr trajectory exporter — emit JSONL training samples from session history.
+
+Usage:
+  lynkr trajectory [options]
+
+Options:
+  --since <window>     "7d", "30d", ISO date, or epoch ms (default: 30d)
+  --days N             Shorthand for --since Nd
+  --tier <tier>        Filter to one tier: SIMPLE, MEDIUM, COMPLEX, REASONING
+  --output, -o <path>  Output file (default: stdout, "-")
+  --anonymize          Strip PII, file paths, API keys, hostnames
+  --count              Print only the row count, no output
+  --format jsonl       Output format (only jsonl supported)
+  -h, --help           Show this help
+
+Examples:
+  lynkr trajectory --days 7 --output last-week.jsonl
+  lynkr trajectory --tier COMPLEX --anonymize -o complex-anon.jsonl
+  lynkr trajectory --count
+
+Output format (one JSON object per line):
+  {
+    "session_id": "...",
+    "messages": [{"role": "user", "content": "..."}, ...],
+    "tool_calls": [...],
+    "outcome": "success" | "error",
+    "tier": "MEDIUM",
+    "complexity_score": 38,
+    "model_used": "gpt-4o",
+    "provider_used": "azure-openai",
+    "tokens_in": 1234,
+    "tokens_out": 456,
+    "latency_ms": 2400,
+    "started_at": "...",
+    "ended_at": "..."
+  }
+`);
+}
+
+function fmtInt(n) {
+  return new Intl.NumberFormat("en-US").format(n || 0);
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+
+  if (opts.count) {
+    // Quick path — stream-walk the sessions and just count valid trajectories.
+    let count = 0;
+    compressor.exportJsonl({
+      ...opts,
+      output: { write: () => count++, end: () => {} },
+    });
+    console.log(`${fmtInt(count)} trajectories`);
+    return;
+  }
+
+  const isStdout = opts.output === "-";
+  const start = Date.now();
+  const result = compressor.exportJsonl({
+    since: opts.since,
+    tier: opts.tier,
+    anonymize: opts.anonymize,
+    output: opts.output,
+  });
+
+  if (!isStdout) {
+    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+    process.stderr.write(
+      `Exported ${fmtInt(result.count)} trajectories to ${result.output} in ${elapsed}s\n`
+    );
+  }
+}
+
+main();

package/bin/lynkr-usage.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * lynkr usage — print AI spend report from routing telemetry.
+ *
+ * Usage:
+ *   lynkr-usage                          # last 30 days
+ *   lynkr-usage --days 7
+ *   lynkr-usage --window 1d
+ *   lynkr-usage --window all
+ *   lynkr-usage --json                   # machine-readable
+ *   lynkr-usage --flagship gpt-5         # alternative comparison model
+ *   lynkr-usage --provider moonshot      # filter to one provider
+ */
+
+const path = require("path");
+
+// Make sure config/logger pick up the workspace root
+process.env.WORKSPACE_ROOT = process.env.WORKSPACE_ROOT || path.resolve(__dirname, "..");
+
+const aggregator = require("../src/usage/aggregator");
+
+function parseArgs(argv) {
+  const opts = { window: "30d", json: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    if (a === "--json") opts.json = true;
+    else if (a === "--days" && next) {
+      opts.window = `${parseInt(next, 10)}d`;
+      i++;
+    } else if (a === "--window" && next) {
+      opts.window = next;
+      i++;
+    } else if (a === "--since" && next) {
+      opts.window = next;
+      i++;
+    } else if (a === "--flagship" && next) {
+      opts.flagship = next;
+      i++;
+    } else if (a === "--provider" && next) {
+      opts.provider = next;
+      i++;
+    } else if (a === "--model" && next) {
+      opts.model = next;
+      i++;
+    } else if (a === "--help" || a === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  console.log(`Lynkr usage report — show AI spend and tier-routing savings.
+
+Usage:
+  lynkr usage [options]
+
+Options:
+  --days N            Window in days (e.g. --days 7)
+  --window <preset>   Window preset: 1d, 7d, 30d, all (default: 30d)
+  --since <iso>       Custom start time (ISO 8601 or epoch ms)
+  --flagship <model>  Comparison model for "savings" math (default: claude-sonnet-4-5-20250929)
+  --provider <name>   Filter to a single provider
+  --model <id>        Filter to a single model
+  --json              Print as JSON instead of a formatted table
+  -h, --help          Show this help
+
+Examples:
+  lynkr usage
+  lynkr usage --days 7
+  lynkr usage --window all --json
+`);
+}
+
+const C = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m",
+};
+
+function colour(text, code) {
+  if (!process.stdout.isTTY) return text;
+  return `${code}${text}${C.reset}`;
+}
+
+function fmtUSD(n) {
+  if (!n) return "$0.00";
+  if (n < 0.01) return `$${n.toFixed(4)}`;
+  return `$${n.toFixed(2)}`;
+}
+
+function fmtTokens(n) {
+  if (!n) return "0";
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(2)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+  return String(n);
+}
+
+function fmtInt(n) {
+  return new Intl.NumberFormat("en-US").format(n || 0);
+}
+
+function pad(s, width, align = "left") {
+  s = String(s);
+  if (s.length >= width) return s;
+  const filler = " ".repeat(width - visibleLength(s));
+  return align === "right" ? filler + s : s + filler;
+}
+
+function visibleLength(s) {
+  // strip ANSI for column-width math
+  return String(s).replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+function tableRow(cells, widths, aligns) {
+  return cells
+    .map((c, i) => pad(c, widths[i], aligns[i] || "left"))
+    .join("  ");
+}
+
+function printTable(rows, header, widths, aligns) {
+  console.log(colour(tableRow(header, widths, aligns), C.bold));
+  console.log(colour(widths.map((w) => "─".repeat(w)).join("  "), C.dim));
+  for (const row of rows) {
+    console.log(tableRow(row, widths, aligns));
+  }
+}
+
+function bucketRows(bucket, widths) {
+  return Object.entries(bucket)
+    .sort((a, b) => b[1].actualCost - a[1].actualCost)
+    .map(([key, b]) => [
+      key,
+      fmtInt(b.requests),
+      fmtTokens(b.totalTokens),
+      colour(fmtUSD(b.actualCost), C.cyan),
+      colour(fmtUSD(b.flagshipCost), C.gray),
+      colour(fmtUSD(b.saved), C.green),
+      colour(`${b.savedPercent.toFixed(1)}%`, C.green),
+    ]);
+}
+
+function printReport(usage) {
+  const { window, since, flagship, totals, byTier, byProvider, byModel } = usage;
+
+  const banner = `Lynkr — Usage Report`;
+  console.log("");
+  console.log(colour(banner, C.bold));
+  console.log(
+    colour(
+      `window: ${window}${since ? `  since: ${since}` : ""}  flagship-comparison: ${flagship}`,
+      C.dim
+    )
+  );
+  console.log("");
+
+  // Summary line
+  const headline =
+    `${fmtInt(totals.requests)} requests   ` +
+    `${fmtTokens(totals.totalTokens)} tokens   ` +
+    `actual ${colour(fmtUSD(totals.actualCost), C.cyan)}   ` +
+    `flagship-only ${colour(fmtUSD(totals.flagshipCost), C.gray)}   ` +
+    `saved ${colour(fmtUSD(totals.saved), C.green)} ` +
+    colour(`(${totals.savedPercent.toFixed(1)}%)`, C.green);
+  console.log(headline);
+  if (totals.fallbacks || totals.errors) {
+    console.log(
+      colour(
+        `   ${totals.fallbacks} fallback${totals.fallbacks !== 1 ? "s" : ""}, ` +
+          `${totals.errors} error${totals.errors !== 1 ? "s" : ""}`,
+        C.yellow
+      )
+    );
+  }
+  console.log("");
+
+  if (totals.requests === 0) {
+    console.log(colour("No telemetry yet for this window. Send some requests through Lynkr first.", C.yellow));
+    return;
+  }
+
+  const headers = ["", "REQUESTS", "TOKENS", "ACTUAL", "FLAGSHIP", "SAVED", "PCT"];
+  const widths = [22, 9, 9, 10, 10, 10, 7];
+  const aligns = ["left", "right", "right", "right", "right", "right", "right"];
+
+  console.log(colour("BY TIER", C.bold));
+  printTable(bucketRows(byTier, widths), ["TIER", ...headers.slice(1)], widths, aligns);
+  console.log("");
+
+  console.log(colour("BY PROVIDER", C.bold));
+  printTable(bucketRows(byProvider, widths), ["PROVIDER", ...headers.slice(1)], widths, aligns);
+  console.log("");
+
+  console.log(colour("BY MODEL", C.bold));
+  printTable(bucketRows(byModel, widths), ["MODEL", ...headers.slice(1)], widths, aligns);
+  console.log("");
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+  const usage = aggregator.getUsage(opts);
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(usage, null, 2) + "\n");
+    return;
+  }
+
+  printReport(usage);
+}
+
+main();