freegate 0.6.14 → 0.6.16

package/README.md

@@ -5,13 +5,16 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm](https://img.shields.io/npm/v/freegate.svg)](https://www.npmjs.com/package/freegate)
 [![GitHub stars](https://img.shields.io/github/stars/Artur21101965/freegate?style=social)](https://github.com/Artur21101965/freegate)
+[![One endpoint](https://img.shields.io/badge/one%20endpoint-all%20agents-00d4ff)](/#features)
+[![Free](https://img.shields.io/badge/price-%240-00ff88)](/#why-free)
+[![Local](https://img.shields.io/badge/runs%20locally-private-00ff88)](/#private)
 
 **[Русская версия](README.ru.md) · Russian version**
 
 ## Why pay for LLMs when free ones exist?
 
-Your AI agent, bot, or script talks to a single OpenAI-compatible endpoint.
-Behind it, Freegate automatically routes requests across **25 free models**
+Your AI agent, bot, or script talks to a **single OpenAI-compatible endpoint**.
+Behind it, Freegate automatically routes requests across **34 free models**
 from Groq, Mistral, Gemini, NVIDIA NIM, OpenRouter, ZAI, Cerebras, DeepSeek
 and local models. If one provider goes down, gets overloaded, or burns its
 daily limit — the request **instantly falls through to the next one**. You
@@ -19,31 +22,48 @@ never see "rate limit", and you never pay.
 
 **Result:** full LLM access for everyday work at the price of **$0**.
 
+### 🔒 Runs locally — your conversations never leave your machine
+
+Freegate runs **on your machine** (`http://localhost:4000`). Your `localhost`
+is only yours — nobody else can connect to it, and you can't to theirs. Provider
+keys live in your local `.env`, history in local files. **No third-party server
+sees your keys or conversations.**
+
 ![Freegate Dashboard](assets/dashboard.png)
 
 ## Features
 
 | | |
 |---|---|
-| 🔀 **Auto-failover** | 25 providers in one chain. Provider down? The next one answers. |
-| 🤖 **Self-managing models** | Auto-discovers new free models, tests them, adds working ones, disables dead ones — every 6h. |
+| 🔀 **Auto-failover** | 34 providers in one chain. Provider down? The next one answers. |
+| 🤖 **Self-managing models** | Auto-discovers new free models, tests them, adds working ones, disables dead ones — built-in scheduler, always-fresh model base. |
+| 🗂️ **Model database** | Structured passport per model (score, latency, context window, history) + sorting: best models get routing priority. |
 | 🏷️ **Model categories** | reasoning / coding / general / vision / local — the right model for the right job. |
 | 🖼️ **Two-stage vision** | Screenshot → vision model reads it → coding model answers the fix. |
 | 💰 **Free** | Free models only. The dashboard shows each provider's remaining limit. |
 | ⚡ **Smart routing** | Picks the fastest, most stable provider for every request. |
 | 🛡️ **Reliability** | Circuit breaker, request queue, auto-disable of dead providers, watchdog. |
-| 📊 **Dashboard** | Status, speed, limits, history, tokens, RPM chart. |
+| 📊 **Dashboard** | Status, speed, limits, history, tokens, RPM chart, savings ($). RU/EN. |
 | 💾 **Disk cache** | Repeat prompts don't consume limits at all. |
+| 🎓 **Methodologist** | Agent answers like an engineer: plan→test→code (coding), stepwise (reasoning). Prompts customizable in `config.json`. |
 | 🔌 **Compatible** | Any OpenAI client: opencode, Cursor, your scripts. |
 
+![Freegate Models base](assets/dashboard-models.png)
+
 ## Quick start — 30 seconds
 
 ```bash
-npx freegate init -i     # wizard: password + each provider's key
+npx freegate init -i     # wizard: quick (1 OpenRouter key) or full (all keys)
 npx freegate start       # proxy on http://localhost:4000
 npx freegate test        # verify everything works
 ```
 
+**init modes:**
+- **quick** — one OpenRouter key → 15+ free models instantly. Add more keys later in Dashboard → Settings.
+- **full** — all provider keys → 8 sources, max speed and reliability (auto-failover).
+
+**Connect to Cursor in 2 clicks:** Cursor → Settings → Models → "OpenAI-compatible" → Base URL `http://localhost:4000/v1`, API Key = your password.
+
 Dashboard: `http://localhost:4000/?key=your_password`
 
 Or via Docker:
@@ -112,10 +132,55 @@ to watch for new releases. The model manager runs every 6 hours.
 3. If it fails — instantly tries the next one in the chain.
 4. The response returns in the same format — the client never notices.
 
+### Methodologist (Productive Agent Layer)
+
+Freegate classifies the task (coding / reasoning / search / chat) and injects a
+short system-prompt methodologist **without any client-side changes**. Any
+OpenAI-compatible client (opencode, Cursor, chat) gets engineer-grade answers:
+
+- **coding** — brief plan before code, a suggested test, where to verify.
+- **reasoning** — reason stepwise, show assumptions.
+- **search** — short factual answer, don't invent sources.
+- **chat** — to the point, concise.
+
+The task category also nudges routing toward matching provider categories
+(`coding`→coding models, `reasoning`→reasoning models) without dropping fallback.
+Category distribution is visible on the dashboard and via
+`node tools/context-diag.js`.
+
+> Methodologist prompts are a condensed derived text inspired by
+> [superpowers](https://github.com/obra/superpowers) (MIT). Full agentic cycle
+> (tools, subagents) runs on the client side.
+
+### Self-updating model database
+
+The scheduler lives inside the server — always on, no cron/launchd needed,
+works for every npm/Docker user. Every 6 hours (configurable) Freegate:
+
+1. **Checks existing** models: dead ones (404/402) get disabled.
+2. **Re-checks dead** models after 7 days — if the provider restores a model, it's re-enabled automatically.
+3. **Scans 8 sources**: OpenRouter, HuggingFace + native model lists of Groq, Mistral, Gemini, Cerebras, DeepSeek, NVIDIA NIM.
+4. **Tests new candidates** in parallel and adds the working ones.
+5. **Computes a score** (success rate + latency + context window + freshness) and sorts: best models get routing priority.
+
+Manual catalog entries (your hand-set priorities in `providers.json`) are never
+overwritten — sorting applies only to auto-added models.
+
+```bash
+node tools/models-db.js          # model base report
+node scripts/auto-manage-models.js   # manual cycle run
+```
+
+Configuration (`config.json`):
+
+```json
+{ "modelManager": { "enabled": true, "intervalHours": 6, "autoAdd": true, "recheckDisabledDays": 7 } }
+```
+
 ## Development
 
 ```bash
-npm test          # unit tests (17)
+npm test          # unit tests (187)
 node server.js    # run from source
 ```
 

package/README.ru.md

@@ -4,13 +4,16 @@
 [![Docker Hub](https://img.shields.io/docker/pulls/nik951751/freegate.svg)](https://hub.docker.com/r/nik951751/freegate)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm](https://img.shields.io/npm/v/freegate.svg)](https://www.npmjs.com/package/freegate)
+[![One endpoint](https://img.shields.io/badge/one%20endpoint-all%20agents-00d4ff)](/#features)
+[![Free](https://img.shields.io/badge/price-%240-00ff88)](/#why-free)
+[![Local](https://img.shields.io/badge/runs%20locally-private-00ff88)](/#private)
 
 **English version: [README.md](README.md)**
 
 ## Зачем платить за LLM, когда есть бесплатные?
 
-Твой AI-агент, бот или скрипт использует один OpenAI-совместимый endpoint.
-За ним Freegate автоматически распределяет запросы между **25 бесплатными
+Твой AI-агент, бот или скрипт использует **один OpenAI-совместимый endpoint**.
+За ним Freegate автоматически распределяет запросы между **34 бесплатными
 моделями** — Groq, Mistral, Gemini, NVIDIA NIM, OpenRouter, ZAI, Cerebras,
 DeepSeek и локальные модели. Если один провайдер упал, перегружен или сжёг
 дневной лимит — запрос **мгновенно уходит на следующий**. Ты никогда не
@@ -18,31 +21,48 @@ DeepSeek и локальные модели. Если один провайде
 
 **Результат:** полноценный LLM-доступ для повседневной работы по цене $0.
 
+### 🔒 Работает локально — переписки никуда не уходят
+
+Freegate крутится **на твоей машине** (`http://localhost:4000`). Твой `localhost` —
+только твой: никто другой не может к нему подключиться, и наоборот. Ключи
+провайдеров лежат в твоём локальном `.env`, история — в локальных файлах. **Ни
+один чужой сервер не видит твои ключи и переписки.**
+
 ![Дашборд Freegate](assets/dashboard.png)
 
 ## Возможности
 
 | | |
 |---|---|
-| 🔀 **Автопереключение** | 25 провайдеров в одной цепочке. Провайдер упал? Следующий уже отвечает. |
-| 🤖 **Автоуправление моделями** | Сам находит новые бесплатные модели, тестирует, добавляет рабочие, отключает мёртвые — каждые 6 часов. |
+| 🔀 **Автопереключение** | 34 провайдера в одной цепочке. Провайдер упал? Следующий уже отвечает. |
+| 🤖 **Автоуправление моделями** | Сам находит новые бесплатные модели, тестирует, добавляет рабочие, отключает мёртвые — встроенный планировщик, всегда актуальная база. |
+| 🗂️ **База моделей** | Структурированный паспорт каждой модели (скор, латентность, окно, история) + сортировка: лучшие модели получают приоритет в роутинге. |
 | 🏷️ **Категории моделей** | reasoning / coding / general / vision / local — правильная модель для каждой задачи. |
 | 🖼️ **Vision-конвейер** | Скриншот → vision-модель читает → кодинг-модель отвечает на вопрос. |
 | 💰 **Бесплатно** | Только free-модели. Дашборд показывает остаток лимита каждого провайдера. |
 | ⚡ **Умный выбор** | Прокси сам находит самый быстрый и стабильный провайдер для каждого запроса. |
 | 🛡️ **Надёжность** | Circuit breaker, очередь запросов, автоотключение мёртвых провайдеров, watchdog. |
-| 📊 **Дашборд** | Статус, скорость, лимиты, история, токены, RPM-график. |
+| 📊 **Дашборд** | Статус, скорость, лимиты, история, токены, RPM-график, экономия ($). RU/EN. |
 | 💾 **Кэш на диске** | Повторные промпты не тратят лимиты вообще. |
+| 🎓 **Методолог** | Агент отвечает как инженер: план→тест→код (coding), пошагово (reasoning). Промпты настраиваются в `config.json`. |
 | 🔌 **Совместимость** | Любой OpenAI-клиент: opencode, Cursor, ChatGPT-аналоги, твои скрипты. |
 
+![База моделей Freegate](assets/dashboard-models.png)
+
 ## Быстрый старт — 30 секунд
 
 ```bash
-npx freegate init -i     # мастер спросит: пароль + ключи каждого провайдера
+npx freegate init -i     # мастер: режим quick (1 ключ OpenRouter) или full (все ключи)
 npx freegate start       # прокси на http://localhost:4000
 npx freegate test        # проверить, что всё работает
 ```
 
+**Режимы init:**
+- **quick** — вставь один ключ OpenRouter → сразу 15+ бесплатных моделей. Остальные ключи добавишь позже в дашборде → «Настройки».
+- **full** — все ключи провайдеров → 8 источников, максимум скорости и надёжности (авто-failover).
+
+**Подключить к Cursor в 2 клика:** Cursor → Settings → Models → «OpenAI-compatible» → Base URL `http://localhost:4000/v1`, API Key = твой пароль.
+
 Дашборд: `http://localhost:4000/?key=твой_пароль`
 
 Или через Docker:
@@ -111,10 +131,58 @@ docker run -d --name freegate -p 4000:4000 \
 3. Если запрос не прошёл — мгновенно пробует следующий из цепочки.
 4. Ответ возвращается клиенту в том же формате — клиент ничего не замечает.
 
+### Методолог (Productive Agent Layer)
+
+Freegate определяет тип задачи (кодинг / рассуждение / поиск / болтовня) и
+подмешивает короткий системный промпт-методолог **без изменений на стороне
+клиента**. Любой OpenAI-совместимый клиент (opencode, Cursor, чат) получает
+ответы как от опытного инженера:
+
+- **coding** — краткий план перед кодом, предложенный тест, где проверять.
+- **reasoning** — рассуждать пошагово, показывать допущения.
+- **search** — короткий фактологичный ответ, не выдумывать источник.
+- **chat** — по существу и кратко.
+
+Дополнительно: категория задачи даёт буст моделям подходящей категории
+(`coding`→coding-модели, `reasoning`→reasoning-модели), не исключая fallback.
+Распределение категорий видно в дашборде и через
+`node tools/context-diag.js`.
+
+> Методолог-промпты — производный сжатый текст по мотивам
+> [superpowers](https://github.com/obra/superpowers) (MIT). Полный агентный цикл
+> (инструменты, субагенты) выполняется на стороне клиента.
+
+### Самообновляющаяся база моделей
+
+Планировщик встроен в сервер — работает всегда, без cron/launchd, у всех
+пользователей пакета. Каждые 6 часов (настраивается) Freegate:
+
+1. **Проверяет существующие** модели: мёртвые (404/402) отключаются.
+2. **Перепроверяет мёртвых** через 7 дней — если провайдер вернул модель, она автоматически реактивируется.
+3. **Сканирует 8 источников**: OpenRouter, HuggingFace + нативные списки Groq, Mistral, Gemini, Cerebras, DeepSeek, NVIDIA NIM.
+4. **Тестирует новых кандидатов** параллельно и добавляет рабочие.
+5. **Считает скор** (success-rate + латентность + контекст-окно + свежесть) и сортирует: лучшие модели получают приоритет в роутинге.
+
+Ручные записи каталога (твои приоритеты в `providers.json`) не перезаписываются
+— сортировка применяется только к автодобавленным моделям.
+
+```bash
+node tools/models-db.js          # отчёт по базе
+curl -s "localhost:4000/v1/models-db?key=пароль" | python3 -m json.tool | head -30
+node scripts/auto-manage-models.js   # ручной прогон цикла
+AUTO_ADD=false node scripts/auto-manage-models.js  # только отчёт, без записи
+```
+
+Конфигурация (`config.json`):
+
+```json
+{ "modelManager": { "enabled": true, "intervalHours": 6, "autoAdd": true, "recheckDisabledDays": 7 } }
+```
+
 ## Разработка
 
 ```bash
-npm test          # unit-тесты (17 шт.)
+npm test          # unit-тесты (187 шт.)
 node server.js    # запуск из исходников
 ```
 
@@ -142,6 +210,24 @@ PROVIDER_ZAI_APIKEY=...        # ZAI
 **Провайдеры** — каталог в `providers.json` (18 моделей). Добавить свой:
 впиши его в `config.json` → `providers` (формат как в `providers.json`).
 
+**Методолог** — в `config.json`:
+
+```json
+{
+  "methodology": {
+    "enabled": true,
+    "prompts": {
+      "coding": "Перед кодом — краткий план. Следи, чтобы тест описывал поведение.",
+      "reasoning": "Рассуждай пошагово, показывай допущения, затем вывод."
+    }
+  }
+}
+```
+
+- `enabled: false` — полностью выключает методолог и роутинг-буст.
+- `prompts` — переопределяет текст для конкретной категории; остальные
+  остаются в дефолтах.
+
 ## Команды CLI
 
 ```bash

package/bin/freegate.js

@@ -31,14 +31,26 @@ function makeReader() {
   };
 }
 
+// Виртуальный провайдер категорий моделей. Вся полезная инфа для онбординга.
+const EASY_START_PROVIDER = 'PROVIDER_OPENROUTER_APIKEY';
+const EASY_START_NAME = 'OpenRouter';
+
 async function initWizard() {
   const ask = makeReader();
 
+  // 0. Объяснение + выбор режима (quick / full).
+  console.log('\n=== Freegate — настройка ===');
+  console.log('Почему Freegate бесплатный? Он маршрутизирует запросы между бесплатными моделями.');
+  console.log('  • Минимум: 1 ключ OpenRouter → сразу 15+ бесплатных моделей (быстрый старт).');
+  console.log('  • Максимум: ключи всех провайдеров → 8 источников, максимум скорости и надёжности.\n');
+  const mode = (await ask('Режим [q]uick (1 ключ OpenRouter) или [f]ull (все ключи)? (q/f): ')).trim().toLowerCase();
+  const full = mode === 'f' || mode === 'full';
+
   // 1. Auth key for the proxy
   const auth = await ask('Пароль для доступа к прокси (Enter = сгенерировать): ');
   const authKey = auth.trim() || 'dc_' + Math.random().toString(36).slice(2, 14);
 
-  // 2. Collect provider keys from the catalog (unique env vars)
+  // 2. Collect provider keys from the catalog (unique env vars).
   const envVars = new Map(); // envVar -> [providerNames]
   for (const [name, p] of Object.entries(CATALOG)) {
     if (!p.envVar) continue;
@@ -50,7 +62,15 @@ async function initWizard() {
   for (const [envVar, providers] of envVars) {
     const sample = providers[0];
     const hint = CATALOG[sample].keyHint || '';
-    const answer = await ask(`\n${providers.join(', ')}\n  Ключ (${hint}) — пусто = пропустить: `);
+    // В quick-режиме OpenRouter просим обязательно-первым, остальные пропускаем.
+    if (!full && envVar !== EASY_START_PROVIDER) continue;
+    if (!full && envVar === EASY_START_PROVIDER) {
+      console.log(`\n👉 ${EASY_START_NAME} — самый большой источник бесплатных моделей.`);
+      console.log(`   Не хватает мощности? Позже добавь остальные ключи в дашборде (Настройки).`);
+    } else {
+      console.log(`\n${providers.join(', ')}`);
+    }
+    const answer = await ask(`  Ключ (${hint}) — пусто = пропустить: `);
     if (answer.trim()) keys[envVar] = answer.trim();
   }
 
@@ -73,8 +93,15 @@ async function initWizard() {
   console.log('✓ config.json создан');
 
   const filled = Object.values(keys).filter(Boolean).length;
-  console.log(`\nГотово! Провайдеров с ключами: ${filled} из ${envVars.size}`);
+  if (full) {
+    console.log(`\nГотово! Провайдеров с ключами: ${filled} из ${envVars.size} (полный режим)`);
+  } else {
+    const hasEasy = !!keys[EASY_START_PROVIDER];
+    console.log(`\nГотово! Режим quick: ${hasEasy ? 'OpenRouter добавлен' : 'ключей не введено'}.`);
+    console.log('  Провайдеров с ключами: ' + filled + '. Добавить больше ключей можно в дашборде → Настройки.');
+  }
   console.log(`Запуск: npx freegate start  (пароль: ${authKey})`);
+  console.log('Подключить к Cursor: Настройки Cursor → Models → OpenAI-compatible → http://localhost:4000/v1');
 }
 
 function copyExample(name, example) {
@@ -108,7 +135,7 @@ if (cmd === 'init') {
   const { execSync } = require('child_process');
   const isMac = process.platform === 'darwin';
   const launchDir = process.cwd();
-  const label = 'com.davilcod.proxy';
+  const label = 'com.freegate.proxy';
 
   if (isMac) {
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
@@ -220,7 +247,7 @@ WantedBy=default.target
 } else {
   console.log('Freegate — бесплатный LLM-прокси с failover');
   console.log('Команды:');
-  console.log('  npx freegate init       интерактивная настройка (ключи, пароль)');
+  console.log('  npx freegate init       интерактивная настройка (quick/full режим, пароль)');
   console.log('  npx freegate start      запустить прокси');
   console.log('  npx freegate status     диагностика: провайдеры, лимиты, ошибки');
   console.log('  npx freegate test       проверить, что прокси работает');

package/config.example.json

@@ -3,6 +3,19 @@
   "port": 4000,
   "auth": "your-secret-key-here",
   "rateLimit": { "maxRequests": 100, "windowMs": 60000 },
+  "modelManager": {
+    "enabled": true,
+    "intervalHours": 6,
+    "autoAdd": true,
+    "recheckDisabledDays": 7
+  },
+  "methodology": {
+    "enabled": true,
+    "prompts": {
+      "coding": "Перед кодом — краткий план. Следи, чтобы тест описывал поведение.",
+      "reasoning": "Рассуждай пошагово, показывай допущения, затем вывод."
+    }
+  },
   "providers": {
     "or-nemotron-550b": {
       "endpoint": "https://openrouter.ai/api/v1/chat/completions",

package/lib/bandit.js

@@ -69,4 +69,11 @@ function recordOutcome(bucketPriors, key, success) {
   else bucketPriors[key].b += 1;
 }
 
-module.exports = { bucket, sampleBeta, pick, recordOutcome, BUCKET_THRESHOLDS };
+// Временные лимиты (429/403/402/401) — это НЕ качество провайдера, а временное
+// состояние (лимит запросов, квота, баланс). Bandit не должен наказывать за них.
+const TRANSIENT_LIMITS = new Set([401, 402, 403, 408, 429]);
+function isTransientLimit(status) {
+  return typeof status === 'number' && TRANSIENT_LIMITS.has(status);
+}
+
+module.exports = { bucket, sampleBeta, pick, recordOutcome, BUCKET_THRESHOLDS, isTransientLimit };

package/lib/cache.js

@@ -2,7 +2,8 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
-const { normalizeMessages } = require('./normalize');
+const { normalizeMessages, looksLikeCode } = require('./normalize');
+const { trigrams, dice } = require('./semcache');
 
 const MAX_SIZE = 500;
 const DEFAULT_TTL = 3600000; // 1 hour in ms
@@ -16,6 +17,7 @@ class LRUCache {
     this.cache = new Map();
     this.hits = 0;
     this.misses = 0;
+    this.semHits = 0;
     this.useNormalize = useNormalize;
     if (!skipLoad) this.load();
   }
@@ -42,8 +44,8 @@ class LRUCache {
       if (data && Array.isArray(data.entries)) {
         const now = Date.now();
         for (const e of data.entries) {
-          if (now - e.created > this.ttl) continue;
-          this.cache.set(e.key, { value: e.value, created: e.created, uses: e.uses || 0 });
+if (now - e.created > this.ttl) continue;
+      this.cache.set(e.key, { value: e.value, created: e.created, uses: e.uses || 0, model: e.model, temperature: e.temperature, grams: e.grams || null });
         }
         // Restore hit/miss counters so hitRate survives restarts
         if (typeof data.hits === 'number') this.hits = data.hits;
@@ -61,7 +63,7 @@ class LRUCache {
         try {
           const size = Buffer.byteLength(JSON.stringify(entry.value));
           if (size > MAX_ENTRY_BYTES) continue;
-          entries.push({ key, value: entry.value, created: entry.created, uses: entry.uses || 0 });
+          entries.push({ key, value: entry.value, created: entry.created, uses: entry.uses || 0, model: entry.model, temperature: entry.temperature, grams: entry.grams || null });
         } catch {}
       }
       // Keep only the most recent 300 on disk to bound file size
@@ -102,6 +104,43 @@ class LRUCache {
     return entry.value;
   }
 
+  // Семантический кэш: на промахе точного ключа ищем закэшированный диалог с
+  // похожим нормализованным текстом (Dice по символьным триграммам). Отдаём
+  // только при совпадении model+temperature и similarity >= minSimilarity.
+  // Безопасность: код, сообщения с нестроковым content и role:'tool' никогда
+  // не матчатся семантически (разный интент/состояние инструментов).
+  getSemantic(model, messages, temperature, minSimilarity = 0.85) {
+    // Guards mirror set()'s grams computation — anything that gets grams:null
+    // in set() must not match here either.
+    if (!Array.isArray(messages)) { this.misses++; return null; }
+    const norm = normalizeMessages(messages);
+    if (!norm || looksLikeCode(messages)) { this.misses++; return null; }
+    if (messages.some(m => m && (typeof m.content !== 'string' || m.role === 'tool'))) { this.misses++; return null; }
+
+    const qgrams = new Set(trigrams(norm));
+    if (qgrams.size === 0) { this.misses++; return null; }
+
+    let bestKey = null;
+    let bestSim = 0;
+    for (const [key, entry] of this.cache) {
+      if (entry.model !== model || entry.temperature !== temperature) continue;
+      if (!entry.grams || entry.grams.length === 0) continue;
+      const sim = dice(qgrams, new Set(entry.grams));
+      if (sim > bestSim) { bestSim = sim; bestKey = key; }
+    }
+
+    if (!bestKey || bestSim < minSimilarity) { this.misses++; return null; }
+
+    const entry = this.cache.get(bestKey);
+    // Bump TTL + usage like a regular hit so hot semantic entries stay cached.
+    entry.created = Date.now();
+    entry.uses = (entry.uses || 0) + 1;
+    this.cache.delete(bestKey);
+    this.cache.set(bestKey, entry);
+    this.semHits++;
+    return { value: entry.value, similarity: Math.round(bestSim * 1000) / 1000 };
+  }
+
   set(model, messages, temperature, value) {
     const key = this._key(model, messages, temperature);
 
@@ -119,13 +158,23 @@ class LRUCache {
       if (victim) this.cache.delete(victim);
     }
 
-    this.cache.set(key, { value, created: Date.now(), uses: 0 });
+    // Семантический индекс: триграммы нормализованного диалога + параметры
+    // запроса. Для кода/content-массивов grams не строим (их и так не ищем).
+    let grams = null;
+    const norm = normalizeMessages(messages);
+    if (norm && !looksLikeCode(messages) &&
+        !(Array.isArray(messages) && messages.some(m => m && (typeof m.content !== 'string' || m.role === 'tool')))) {
+      grams = new Set(trigrams(norm));
+    }
+
+    this.cache.set(key, { value, created: Date.now(), uses: 0, model, temperature, grams: grams ? [...grams] : null });
   }
 
   stats() {
     return {
       hits: this.hits,
       misses: this.misses,
+      semHits: this.semHits,
       size: this.cache.size,
       maxSize: this.maxSize,
       hitRate: this.hits + this.misses > 0

package/lib/clean.js

@@ -67,12 +67,17 @@ function hasContent(data) {
 
 // Ответ короче MIN_ANSWER_LEN символов считается мусором (обрыв/один токен).
 const MIN_ANSWER_LEN = 5;
-function isTooShort(data) {
+// Короткий вопрос допускает короткий ответ: «ok» на «reply ok» — валидный
+// ответ, а не обрыв. Порог масштабируется: чем короче вопрос, тем короче
+// допустимый ответ, но никогда не ниже 1 символа.
+function isTooShort(data, askedText) {
   if (!data || !Array.isArray(data.choices)) return true;
   const msg = data.choices[0]?.message;
   const content = typeof msg?.content === 'string' ? msg.content.trim() : '';
   const reasoning = typeof msg?.reasoning === 'string' ? msg.reasoning.trim() : '';
-  return (content + reasoning).length < MIN_ANSWER_LEN;
+  const ask = typeof askedText === 'string' ? askedText.trim().length : 0;
+  const threshold = ask > 0 && ask < 40 ? Math.max(1, Math.min(MIN_ANSWER_LEN, Math.ceil(ask / 8))) : MIN_ANSWER_LEN;
+  return (content + reasoning).length < threshold;
 }
 
 module.exports = { stripThink, cleanMessage, cleanDelta, fixReasoningMessage, hasContent, isTooShort, MIN_ANSWER_LEN };