lynkr 9.7.3 → 9.9.0

package/scripts/ws7-anchor-replay.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * WS7.2 — replay real telemetry request texts through the anchor classifier
+ * and measure whether {trivial, substantive, heavyweight} separate cleanly
+ * in cosine space. This is the evidence gate for keeping the three-way
+ * blend (vs collapsing to a single cheap-vs-capable threshold).
+ *
+ * Usage: node scripts/ws7-anchor-replay.js [--db .lynkr/telemetry.db] [--limit N]
+ * Requires: local Ollama with the configured embeddings model.
+ *
+ * Reports:
+ *  - per-class counts + score distribution
+ *  - top-2 sim margin per class (median/p25) — the separation metric.
+ *    Margin >= ~0.05 median = classes separate; < 0.02 = collapse to binary.
+ *  - tier movement vs the recorded (lexical-era) tier.
+ */
+const path = require('path');
+const Database = require('better-sqlite3');
+
+const args = process.argv.slice(2);
+const dbPath = args.includes('--db')
+  ? args[args.indexOf('--db') + 1]
+  : path.join(__dirname, '../.lynkr/telemetry.db');
+const limit = args.includes('--limit') ? Number(args[args.indexOf('--limit') + 1]) : 100000;
+
+const MINING_SQL = `
+  SELECT DISTINCT request_text, tier, quality_score FROM routing_telemetry
+  WHERE request_text IS NOT NULL AND length(request_text)>3
+    AND request_text NOT LIKE '%system-reminder%'
+    AND request_text NOT LIKE '%SUGGESTION MODE%'
+    AND request_text NOT LIKE '%[Lynkr]%'
+    AND request_text NOT LIKE 'quota%'
+    AND request_text NOT LIKE '<session>%' AND request_text NOT LIKE '<conversation>%'
+  LIMIT ?`;
+
+function pct(arr, p) {
+  if (!arr.length) return null;
+  const s = [...arr].sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))];
+}
+
+async function main() {
+  const { scoreIntent, getDefaultCentroids } = require('../src/routing/intent-score');
+  const { getModelTierSelector } = require('../src/routing/model-tiers');
+
+  const centroids = await getDefaultCentroids();
+  if (!centroids) {
+    console.error('FATAL: could not build anchor centroids — is Ollama running with the embeddings model?');
+    process.exit(1);
+  }
+
+  const db = new Database(dbPath, { readonly: true });
+  const rows = db.prepare(MINING_SQL).all(limit);
+  console.log(`Mined ${rows.length} distinct request texts from ${dbPath}\n`);
+
+  const selector = getModelTierSelector();
+  const byClass = {};
+  const margins = { trivial: [], substantive: [], heavyweight: [] };
+  const moves = {};
+  let anchorMode = 0;
+  let lexicalFallback = 0;
+
+  for (const row of rows) {
+    const r = await scoreIntent({ messages: [{ role: 'user', content: row.request_text }] });
+    if (!r) continue;
+    if (r.mode !== 'anchor') { lexicalFallback++; continue; }
+    anchorMode++;
+    const cls = r.class;
+    byClass[cls] = byClass[cls] || { n: 0, scores: [], examples: [] };
+    byClass[cls].n++;
+    byClass[cls].scores.push(r.score);
+    if (byClass[cls].examples.length < 4) {
+      byClass[cls].examples.push(`${r.score.toString().padStart(2)}  ${row.request_text.slice(0, 90).replace(/\n/g, ' ')}`);
+    }
+    const sims = Object.entries(r.sims).sort((a, b) => b[1] - a[1]);
+    margins[cls].push(sims[0][1] - sims[1][1]);
+
+    const newTier = selector.getTier(r.score);
+    const oldTier = row.tier || '??';
+    const key = `${oldTier} -> ${newTier}`;
+    moves[key] = (moves[key] || 0) + 1;
+  }
+
+  console.log(`Scored: ${anchorMode} anchor-mode, ${lexicalFallback} lexical-fallback\n`);
+  console.log('=== Class distribution + score stats ===');
+  for (const [cls, d] of Object.entries(byClass)) {
+    console.log(`\n${cls}: n=${d.n}  score median=${pct(d.scores, 50)}  p10=${pct(d.scores, 10)}  p90=${pct(d.scores, 90)}`);
+    console.log(`  top-2 sim margin: median=${pct(margins[cls], 50)?.toFixed(4)}  p25=${pct(margins[cls], 25)?.toFixed(4)}  min=${Math.min(...margins[cls]).toFixed(4)}`);
+    for (const e of d.examples) console.log(`    ${e}`);
+  }
+
+  console.log('\n=== Tier movement (recorded lexical-era tier -> anchor tier) ===');
+  for (const [k, v] of Object.entries(moves).sort((a, b) => b[1] - a[1])) {
+    console.log(`  ${k}: ${v}`);
+  }
+
+  const allMargins = Object.values(margins).flat();
+  const med = pct(allMargins, 50);
+  console.log(`\n=== VERDICT ===`);
+  console.log(`Overall top-2 sim margin: median=${med?.toFixed(4)}  p25=${pct(allMargins, 25)?.toFixed(4)}`);
+  console.log(med >= 0.05
+    ? 'Classes separate cleanly (median margin >= 0.05) — three-way blend is supported by the data.'
+    : med >= 0.02
+      ? 'Borderline separation — keep three-way but watch misroutes; consider more anchors.'
+      : 'Classes do NOT separate — collapse to binary (trivial vs rest).');
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });

package/skills/lynkr/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: lynkr
+display_name: Lynkr AI Routing Proxy
+version: 8.0.1
+description: Universal LLM gateway with intelligent routing, Graphify code intelligence, Distill compression, routing telemetry, Code Mode, and 12+ provider support. 60-80% cost reduction for Claude Code, Cursor, and Codex.
+author: lynkr-ai
+license: MIT
+tags:
+  - routing
+  - proxy
+  - llm
+  - multi-provider
+  - ollama
+  - openai
+  - anthropic
+  - bedrock
+  - cost-optimization
+  - graphify
+  - distill
+  - telemetry
+  - code-mode
+  - compression
+  - memory
+category: infrastructure
+homepage: https://github.com/Fast-Editor/Lynkr
+npm: lynkr
+requires:
+  node: ">=20"
+providers:
+  - ollama
+  - databricks
+  - azure-anthropic
+  - azure-openai
+  - openrouter
+  - openai
+  - bedrock
+  - vertex
+  - moonshot
+  - zai
+  - llamacpp
+  - lmstudio
+  - codex
+  - deepseek
+---
+
+# Lynkr - Universal LLM Gateway
+
+Lynkr routes AI coding requests to the optimal model based on task complexity, cost, and provider health. Supports 12+ providers with 60-80% cost reduction through intelligent token optimization.
+
+## Quick Start
+
+```bash
+npm install -g lynkr
+lynkr-setup   # Auto-installs Ollama + pulls a model
+lynkr          # Start the proxy
+```
+
+Then point your AI coding tool at `http://localhost:8081/v1`.
+
+## How It Works
+
+1. **5-Phase Complexity Analysis** - Scores each request 0-100 using token count, tool usage, code patterns, domain keywords, and Graphify structural analysis (god nodes, community cohesion, blast radius)
+2. **4-Tier Routing** - Maps score to SIMPLE/MEDIUM/COMPLEX/REASONING, each with a configured provider:model
+3. **Agentic Detection** - Detects multi-step workflows (tool loops, autonomous agents) and upgrades to higher tiers
+4. **Cost Optimization** - Picks the cheapest provider that can handle the tier
+5. **Circuit Breaker + Failover** - Automatic failover with half-open probe recovery
+
+## Key Features (v8.0)
+
+### Intelligent Routing
+- 5-phase complexity scoring with 15-dimension weighted mode
+- Agentic workflow detection (SINGLE_SHOT / TOOL_CHAIN / ITERATIVE / AUTONOMOUS)
+- Graphify knowledge graph integration — god node detection, community cohesion, blast radius
+- Routing telemetry with SQLite store, quality scoring (0-100), latency tracking (P50/P95/P99)
+
+### Token Optimization (60-80% savings)
+- **Smart tool selection** — filters tools by request type
+- **Distill compression** — structural similarity (Jaccard), delta rendering, block dedup
+- **Code Mode** — replaces 100+ MCP tools with 4 meta-tools (~96% token reduction)
+- **History compression** — sliding window with Distill-powered dedup
+- **Prompt caching** — SHA-256 keyed LRU cache
+- **Headroom sidecar** — optional 47-92% compression via Smart Crusher, CCR, LLMLingua
+
+### Production Hardening
+- Circuit breakers with half-open probe recovery
+- Admin hot-reload endpoint (POST /v1/admin/reload) — no restart needed
+- Per-request performance timing (PERF_TIMER=true)
+- Prometheus metrics, structured logging, health checks
+- Rate limiting, load shedding, input validation
+
+### Long-Term Memory (Titans-Inspired)
+- Surprise-based memory storage with decay
+- Semantic search via FTS5
+- Automatic extraction and injection
+
+## Configuration for OpenClaw
+
+Set tier routing in your environment:
+
+```env
+MODEL_PROVIDER=ollama
+TIER_SIMPLE=ollama:llama3.2
+TIER_MEDIUM=openrouter:anthropic/claude-sonnet-4
+TIER_COMPLEX=bedrock:anthropic.claude-sonnet-4-20250514-v1:0
+TIER_REASONING=bedrock:anthropic.claude-opus-4-20250514-v1:0
+```
+
+### OpenClaw Mode
+
+When running under OpenClaw, enable model name rewriting:
+
+```env
+OPENCLAW_MODE=true
+```
+
+This replaces the generic `model: "auto"` in responses with the actual `provider/model` that handled the request.
+
+## Provider Registration
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "models": {
+    "providers": [
+      {
+        "name": "lynkr",
+        "type": "openai-compatible",
+        "base_url": "http://localhost:8081/v1",
+        "api_key": "any-value",
+        "models": ["auto"]
+      }
+    ]
+  },
+  "agents": {
+    "defaults": {
+      "models": {
+        "primary": "lynkr/auto",
+        "fallback": "lynkr/auto"
+      }
+    }
+  }
+}
+```
+
+## Providers
+
+| Provider | Type | Models |
+|----------|------|--------|
+| Ollama | Local (free) | llama3.2, qwen2.5-coder, deepseek-coder, mistral |
+| llama.cpp | Local (free) | Any GGUF model |
+| LM Studio | Local (free) | Any downloaded model |
+| OpenAI | Cloud | gpt-4o, o3, o4-mini |
+| Anthropic | Cloud | claude-opus-4, claude-sonnet-4, claude-haiku-4.5 |
+| Databricks | Cloud | Claude, GPT, Llama via Foundation Model APIs |
+| AWS Bedrock | Cloud | Claude, Titan, Llama, Mistral |
+| Azure OpenAI | Cloud | GPT-4o, o1, o3 |
+| OpenRouter | Cloud | 100+ models |
+| 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 |
+
+## New in v8.0
+
+- **Graphify Integration** — AST-based knowledge graph with 19-language support for blast radius analysis
+- **Distill Compression** — Structural similarity, delta rendering, and smart dedup
+- **Routing Telemetry** — SQLite-backed decision recording with quality scoring
+- **Code Mode** — 4 MCP meta-tools replace 100+ individual definitions
+- **Admin Reload** — Hot-reload config + reset circuit breakers without restart
+- **Performance Timer** — Per-request timing breakdown (PERF_TIMER=true)
+- **Large Payload Passthrough** — Smart cloning skips base64 media that will be discarded
+
+## Response Headers
+
+| Header | Description |
+|--------|-------------|
+| `X-Lynkr-Provider` | Provider that handled the request |
+| `X-Lynkr-Model` | Model used |
+| `X-Lynkr-Tier` | Complexity tier (SIMPLE/MEDIUM/COMPLEX/REASONING) |
+| `X-Lynkr-Complexity-Score` | Numeric score 0-100 |
+| `X-Lynkr-Routing-Method` | How the route was decided |
+| `X-Lynkr-Agentic` | Agentic workflow type (if detected) |
+| `X-Lynkr-Cost-Optimized` | Whether cost optimization changed the provider |
+
+## Telemetry Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /v1/routing/stats` | Aggregated routing stats with latency percentiles |
+| `GET /v1/routing/stats/:provider` | Per-provider statistics |
+| `GET /v1/routing/telemetry` | Raw telemetry records |
+| `GET /v1/routing/accuracy` | Over/under-provisioned routing detection |
+| `POST /v1/admin/reload` | Hot-reload config + reset circuit breakers |
+| `POST /v1/admin/circuit-breakers/reset` | Reset circuit breakers |

package/src/api/middleware/loop-guard.js

@@ -0,0 +1,87 @@
+/**
+ * Loop guard — runaway-agent circuit breaker (WS: multi-agent cost controls).
+ *
+ * Agent frameworks (LangGraph, CrewAI, AutoGen) resend the full growing
+ * conversation every round-trip, so an uncapped tool loop compounds: each
+ * turn pays for every previous turn again. Real-world failure mode this
+ * guards: an AutoGen deployment ran 40% over budget in its first month from
+ * exactly this (uncapped reviewer<->coder loops).
+ *
+ * The guard is STATELESS — it reads loop depth from the incoming payload
+ * itself rather than tracking sessions:
+ *   - message count  ≈ total turns so far
+ *   - tool_result count ≈ tool-loop iterations so far
+ * Both survive proxy restarts and need no session affinity.
+ *
+ * Disabled by default (caps unset/0). Enable per deployment:
+ *   LYNKR_MAX_SESSION_TURNS=80    reject when messages[] exceeds 80 entries
+ *   LYNKR_MAX_TOOL_TURNS=25       reject when tool_result blocks exceed 25
+ *
+ * Rejections use 429 + a machine-readable error type so agent frameworks
+ * surface them as a hard stop instead of retrying blindly.
+ */
+
+const logger = require("../../logger");
+
+function _countToolResults(messages) {
+  let n = 0;
+  for (const m of messages) {
+    if (!Array.isArray(m?.content)) continue;
+    for (const block of m.content) {
+      if (block?.type === "tool_result") n++;
+    }
+  }
+  return n;
+}
+
+function _cap(name) {
+  const v = Number(process.env[name]);
+  return Number.isFinite(v) && v > 0 ? Math.floor(v) : null;
+}
+
+function loopGuard(req, res, next) {
+  const maxTurns = _cap("LYNKR_MAX_SESSION_TURNS");
+  const maxToolTurns = _cap("LYNKR_MAX_TOOL_TURNS");
+  if (!maxTurns && !maxToolTurns) return next();
+
+  const messages = Array.isArray(req.body?.messages) ? req.body.messages : [];
+
+  if (maxTurns && messages.length > maxTurns) {
+    logger.warn(
+      { messageCount: messages.length, cap: maxTurns, path: req.path },
+      "[LoopGuard] conversation exceeded turn cap"
+    );
+    return res.status(429).json({
+      error: {
+        type: "loop_cap_exceeded",
+        message:
+          `Conversation has ${messages.length} messages, over the configured ` +
+          `cap of ${maxTurns} (LYNKR_MAX_SESSION_TURNS). This usually means an ` +
+          `agent loop is not converging — inspect the conversation before raising the cap.`,
+      },
+    });
+  }
+
+  if (maxToolTurns) {
+    const toolResults = _countToolResults(messages);
+    if (toolResults > maxToolTurns) {
+      logger.warn(
+        { toolResults, cap: maxToolTurns, path: req.path },
+        "[LoopGuard] conversation exceeded tool-turn cap"
+      );
+      return res.status(429).json({
+        error: {
+          type: "loop_cap_exceeded",
+          message:
+            `Conversation carries ${toolResults} tool results, over the configured ` +
+            `cap of ${maxToolTurns} (LYNKR_MAX_TOOL_TURNS). This usually means a ` +
+            `tool loop is stuck — inspect the last few tool calls before raising the cap.`,
+        },
+      });
+    }
+  }
+
+  return next();
+}
+
+module.exports = { loopGuard, _countToolResults };

package/src/api/middleware/request-logging.js

@@ -1,14 +1,12 @@
 const crypto = require("crypto");
-const logger = require("../../logger");
 
 /**
- * Structured request logging middleware
+ * Request ID middleware.
  *
- * Features:
- * - Request ID tracking (X-Request-ID header)
- * - Correlation across services
- * - Performance metrics
- * - Minimal overhead
+ * Assigns req.requestId (honouring an inbound X-Request-ID header) and
+ * echoes it on the response. Request/response logging itself is handled
+ * by pino-http in middleware/logging.js — don't log here or every
+ * request gets logged twice.
  */
 
 function generateRequestId() {
@@ -16,66 +14,9 @@ function generateRequestId() {
 }
 
 function requestLoggingMiddleware(req, res, next) {
-  const startTime = Date.now();
-
-  // Generate or use existing request ID
   const requestId = req.headers["x-request-id"] || generateRequestId();
   req.requestId = requestId;
-
-  // Add to response headers
   res.setHeader("X-Request-ID", requestId);
-
-  // Log request start
-  logger.info(
-    {
-      requestId,
-      method: req.method,
-      path: req.path || req.url,
-      query: req.query,
-      ip: req.ip || req.socket.remoteAddress,
-      userAgent: req.headers["user-agent"],
-    },
-    "Request started"
-  );
-
-  // Capture response finish
-  const originalSend = res.send;
-  res.send = function (body) {
-    const duration = Date.now() - startTime;
-
-    // Log request completion
-    logger.info(
-      {
-        requestId,
-        method: req.method,
-        path: req.path || req.url,
-        status: res.statusCode,
-        duration,
-        contentLength: res.getHeader("content-length"),
-      },
-      "Request completed"
-    );
-
-    return originalSend.call(this, body);
-  };
-
-  // Handle errors
-  res.on("finish", () => {
-    if (res.statusCode >= 400) {
-      const duration = Date.now() - startTime;
-      logger.warn(
-        {
-          requestId,
-          method: req.method,
-          path: req.path || req.url,
-          status: res.statusCode,
-          duration,
-        },
-        "Request failed"
-      );
-    }
-  });
-
   next();
 }