lynkr 9.7.2 → 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/agents/context-manager.js

@@ -62,6 +62,14 @@ class ContextManager {
       allowedTools: agentDef.allowedTools,
       startTime: Date.now(),
 
+      // Original task prompt — consumed by the Reflector to infer task type.
+      taskPrompt,
+
+      // In-memory transcript mirror of the JSONL file — consumed by the
+      // Reflector for tool-usage / error-recovery analysis. The JSONL file
+      // remains the durable record; this array is the hot-path copy.
+      transcript: [],
+
       // Token tracking
       inputTokens: 0,
       outputTokens: 0,
@@ -102,7 +110,7 @@ class ContextManager {
    * Record tool execution in transcript
    */
   recordToolCall(context, toolName, input, output, error = null) {
-    this.writeTranscriptEntry(context.transcriptPath, {
+    const entry = {
       type: "tool_call",
       agentId: context.agentId,
       step: context.steps,
@@ -111,7 +119,15 @@ class ContextManager {
       output: error ? null : output,
       error: error ? error.message : null,
       timestamp: Date.now()
-    });
+    };
+
+    // Keep the in-memory transcript in sync so the Reflector (which reads
+    // context.transcript) sees tool calls without re-parsing the JSONL file.
+    if (Array.isArray(context.transcript)) {
+      context.transcript.push(entry);
+    }
+
+    this.writeTranscriptEntry(context.transcriptPath, entry);
   }
 
   /**

package/src/agents/definitions/loader.js

@@ -4,11 +4,17 @@ const yaml = require("js-yaml");
 const logger = require("../../logger");
 const Skillbook = require("../skillbook");
 
+// How often to prune low-quality learned skills. 6 hours is frequent enough to
+// keep skillbooks tidy on a long-running process but rare enough to be
+// negligible overhead. Hardcoded on purpose — not worth a config knob.
+const SKILL_PRUNE_INTERVAL_MS = 6 * 60 * 60 * 1000;
+
 class AgentDefinitionLoader {
   constructor() {
     this.agents = new Map();
     this.skillbooks = new Map(); // agentType → Skillbook
     this.initialized = false;
+    this.pruneTimer = null;
 
     // Initialize synchronously for compatibility
     this.loadBuiltInAgentsSync();
@@ -82,6 +88,27 @@ class AgentDefinitionLoader {
     return this.skillbooks.get(agentType);
   }
 
+  /**
+   * Replace an agent's skillbook with a freshly-learned instance and re-inject
+   * its skills into the (in-memory) system prompt. Called by the executor after
+   * a run persists new skills, so learning takes effect within the running
+   * process instead of only after a restart. Injection rebuilds from
+   * originalSystemPrompt, so repeated calls do not duplicate the skills block.
+   */
+  setSkillbook(agentType, skillbook) {
+    if (!agentType || !skillbook) return;
+    // Match the case-insensitive key an agent is actually stored under.
+    const key = this.agents.has(agentType)
+      ? agentType
+      : Array.from(this.agents.keys()).find(
+          k => k.toLowerCase() === String(agentType).toLowerCase()
+        );
+    if (!key) return;
+
+    this.skillbooks.set(key, skillbook);
+    this._injectSkillsIntoPrompt(key);
+  }
+
   /**
    * Reload skillbooks and update prompts (call after learning)
    */
@@ -89,6 +116,69 @@ class AgentDefinitionLoader {
     await this._loadSkillbooksAsync();
   }
 
+  /**
+   * Prune low-quality skills from every loaded skillbook. Skillbook.prune()
+   * only drops skills that have been tried enough times to prove they don't
+   * help (default: useCount >= 3 && confidence < 0.2), so fresh skills are
+   * never removed. Persists and re-injects only the skillbooks that changed.
+   * @returns {Promise<number>} total skills pruned across all agents
+   */
+  async pruneSkillbooks() {
+    let totalPruned = 0;
+
+    for (const [agentType, skillbook] of this.skillbooks.entries()) {
+      try {
+        const pruned = skillbook.prune();
+        if (pruned > 0) {
+          await skillbook.save();
+          this._injectSkillsIntoPrompt(agentType);
+          totalPruned += pruned;
+        }
+      } catch (error) {
+        logger.warn(
+          { agentType, error: error.message },
+          "Failed to prune skillbook"
+        );
+      }
+    }
+
+    if (totalPruned > 0) {
+      logger.info({ totalPruned }, "Pruned low-quality agent skills");
+    }
+    return totalPruned;
+  }
+
+  /**
+   * Start periodic skillbook pruning. Idempotent; a non-positive interval
+   * disables pruning. The timer is unref'd so it never keeps the process alive.
+   */
+  startSkillPruning(intervalMs = SKILL_PRUNE_INTERVAL_MS) {
+    if (this.pruneTimer) return; // already running
+    if (!Number.isInteger(intervalMs) || intervalMs <= 0) {
+      logger.debug({ intervalMs }, "Skillbook pruning disabled");
+      return;
+    }
+
+    this.pruneTimer = setInterval(() => {
+      this.pruneSkillbooks().catch((error) => {
+        logger.warn({ error: error.message }, "Skillbook pruning failed");
+      });
+    }, intervalMs);
+    this.pruneTimer.unref();
+
+    logger.info({ intervalMs }, "Skillbook pruning started");
+  }
+
+  /**
+   * Stop periodic skillbook pruning (for shutdown / tests).
+   */
+  stopSkillPruning() {
+    if (this.pruneTimer) {
+      clearInterval(this.pruneTimer);
+      this.pruneTimer = null;
+    }
+  }
+
   /**
    * Load built-in agents (Explore, Plan, General)
    */

package/src/agents/executor.js

@@ -9,6 +9,18 @@ const Reflector = require("./reflector");
 const contextManager = new ContextManager();
 
 class SubagentExecutor {
+  /**
+   * @param {Object} [options]
+   * @param {Object} [options.definitionLoader] - Agent definition loader. When
+   *   provided, newly-learned skills are re-injected into agent prompts live
+   *   (within the running process). Optional so the executor still works
+   *   standalone (e.g. in tests); without it, learning still persists to disk
+   *   and is picked up on the next process start.
+   */
+  constructor({ definitionLoader = null } = {}) {
+    this.definitionLoader = definitionLoader;
+  }
+
   /**
    * Execute a single subagent
    * @param {Object} agentDef - Agent definition
@@ -403,8 +415,12 @@ class SubagentExecutor {
         return; // Nothing to learn
       }
 
-      // Load skillbook for this agent type
-      const skillbook = await Skillbook.load(context.agentName);
+      // Prefer the loader's live skillbook instance (so use-counts/confidence
+      // accumulate in one place); fall back to loading from disk when running
+      // standalone.
+      const skillbook =
+        this.definitionLoader?.getSkillbook(context.agentName) ||
+        (await Skillbook.load(context.agentName));
 
       // Add each learned pattern
       for (const pattern of patterns) {
@@ -414,6 +430,12 @@ class SubagentExecutor {
       // Save skillbook (persists learning)
       await skillbook.save();
 
+      // Re-inject into the agent's prompt so the next run benefits without a
+      // restart. No-op when no loader was provided.
+      if (this.definitionLoader) {
+        this.definitionLoader.setSkillbook(context.agentName, skillbook);
+      }
+
       logger.info({
         agentType: context.agentName,
         patternsLearned: patterns.length,

package/src/agents/index.js

@@ -5,7 +5,15 @@ const ParallelCoordinator = require("./parallel-coordinator");
 const agentStore = require("./store");
 
 const definitionLoader = new AgentDefinitionLoader();
-const coordinator = new ParallelCoordinator(config.agents?.maxConcurrent || 10);
+const coordinator = new ParallelCoordinator(config.agents?.maxConcurrent || 10, {
+  definitionLoader,
+});
+
+// Periodically drop learned skills that have proven unhelpful. Only when the
+// agents subsystem is active; the timer is unref'd so it never blocks exit.
+if (config.agents?.enabled) {
+  definitionLoader.startSkillPruning();
+}
 
 /**
  * Spawn and execute subagent(s)

package/src/agents/parallel-coordinator.js

@@ -2,9 +2,9 @@ const logger = require("../logger");
 const SubagentExecutor = require("./executor");
 
 class ParallelCoordinator {
-  constructor(maxConcurrent = 10) {
+  constructor(maxConcurrent = 10, { definitionLoader = null } = {}) {
     this.maxConcurrent = maxConcurrent;
-    this.executor = new SubagentExecutor();
+    this.executor = new SubagentExecutor({ definitionLoader });
   }
 
   /**

package/src/agents/reflector.js

@@ -184,8 +184,13 @@ class Reflector {
     // Pattern 1: Recovered from errors
     if (successful) {
       const failedTools = errorEntries.map(e => e.toolName);
+      // Tools invoked *after* the last error entry are the recovery path.
+      // Use the entry's position in the transcript, not its timestamp
+      // (slicing by a ~1.7e12 timestamp always yielded []).
+      const lastErrorEntry = errorEntries[errorEntries.length - 1];
+      const lastErrorIndex = transcript.indexOf(lastErrorEntry);
       const recoveryTools = transcript
-        .slice(errorEntries[errorEntries.length - 1].timestamp)
+        .slice(lastErrorIndex + 1)
         .filter(e => e.type === "tool_call" && !e.error)
         .map(e => e.toolName);
 
@@ -248,6 +253,11 @@ class Reflector {
    * Infer task type from prompt
    */
   static _inferTaskType(prompt) {
+    // Guard against a missing/non-string prompt so reflection never throws
+    // (a throw here previously aborted all learning silently).
+    if (typeof prompt !== "string" || prompt.length === 0) {
+      return null;
+    }
     const lower = prompt.toLowerCase();
 
     const taskTypes = [

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 };