freegate 0.6.0

package/lib/cache.js

@@ -0,0 +1,139 @@
+// lib/cache.js
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const MAX_SIZE = 500;
+const DEFAULT_TTL = 3600000; // 1 hour in ms
+const MAX_ENTRY_BYTES = 256 * 1024; // don't persist responses larger than 256KB
+const CACHE_PATH = path.join(__dirname, '..', 'cache.json');
+
+class LRUCache {
+  constructor(maxSize = MAX_SIZE, ttl = DEFAULT_TTL, skipLoad = false) {
+    this.maxSize = maxSize;
+    this.ttl = ttl;
+    this.cache = new Map();
+    this.hits = 0;
+    this.misses = 0;
+    if (!skipLoad) this.load();
+  }
+
+  _key(model, messages, temperature) {
+    const raw = `${model}|${JSON.stringify(messages)}|${temperature || 0}`;
+    return crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16);
+  }
+
+  load() {
+    // Restore persisted cache from disk (survives restarts)
+    try {
+      const data = JSON.parse(fs.readFileSync(CACHE_PATH, 'utf8'));
+      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 });
+        }
+        // Restore hit/miss counters so hitRate survives restarts
+        if (typeof data.hits === 'number') this.hits = data.hits;
+        if (typeof data.misses === 'number') this.misses = data.misses;
+      }
+    } catch {}
+  }
+
+  persist() {
+    try {
+      const now = Date.now();
+      const entries = [];
+      for (const [key, entry] of this.cache) {
+        if (now - entry.created > this.ttl) continue;
+        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 });
+        } catch {}
+      }
+      // Keep only the most recent 300 on disk to bound file size
+      const trimmed = entries.slice(-300);
+      fs.writeFileSync(CACHE_PATH, JSON.stringify({
+        saved: Date.now(),
+        hits: this.hits,
+        misses: this.misses,
+        entries: trimmed,
+      }));
+    } catch {}
+  }
+
+  get(model, messages, temperature) {
+    const key = this._key(model, messages, temperature);
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      this.misses++;
+      return null;
+    }
+
+    if (Date.now() - entry.created > this.ttl) {
+      this.cache.delete(key);
+      this.misses++;
+      return null;
+    }
+
+    // Hot entries: bump TTL + usage count so frequently-used responses
+    // stay cached longer (mirrors DeepSeek-style high cache-hit rates).
+    entry.created = Date.now();
+    entry.uses = (entry.uses || 0) + 1;
+
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    this.hits++;
+    return entry.value;
+  }
+
+  set(model, messages, temperature, value) {
+    const key = this._key(model, messages, temperature);
+
+    // Delete if exists (to update order)
+    if (this.cache.has(key)) this.cache.delete(key);
+
+    // Evict least-used entry if at capacity (not just oldest)
+    if (this.cache.size >= this.maxSize) {
+      let victim = null;
+      let minUses = Infinity;
+      for (const [k, e] of this.cache) {
+        const u = e.uses || 0;
+        if (u < minUses) { minUses = u; victim = k; }
+      }
+      if (victim) this.cache.delete(victim);
+    }
+
+    this.cache.set(key, { value, created: Date.now(), uses: 0 });
+  }
+
+  stats() {
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      size: this.cache.size,
+      maxSize: this.maxSize,
+      hitRate: this.hits + this.misses > 0
+        ? Math.round((this.hits / (this.hits + this.misses)) * 100)
+        : 0,
+    };
+  }
+
+  clear() {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+    try { fs.unlinkSync(CACHE_PATH); } catch {}
+  }
+}
+
+// Auto-persist every 60 seconds
+const _persistTimer = setInterval(() => {
+  const c = module.exports._activeCache;
+  if (c) c.persist();
+}, 60000);
+
+module.exports = { LRUCache, _stopTimers: () => clearInterval(_persistTimer) };

package/lib/clean.js

@@ -0,0 +1,56 @@
+// lib/clean.js — response cleaning helpers.
+// Strips <think>...</think> reasoning blocks that some free models
+// (qwen, nemotron) inject into answers — they pollute short content.
+
+// Remove think blocks from a text string (case-insensitive, greedy-safe).
+// trim=true also trims whitespace (safe for full messages, NOT streaming deltas
+// — trimming each streamed chunk eats the spaces between words).
+function stripThink(text, trim = true) {
+  if (!text) return text;
+  let out = text;
+  // Handle <think> and <thinking> tags in any case, spanning newlines
+  out = out.replace(/<think\b[^>]*>[\s\S]*?<\/think>/gi, '');
+  out = out.replace(/<thinking\b[^>]*>[\s\S]*?<\/thinking>/gi, '');
+  if (trim) {
+    out = out.replace(/\n{3,}/g, '\n\n').trim();
+  } else {
+    // Collapse 3+ newlines into 2, but keep leading/trailing spaces intact
+    out = out.replace(/\n{3,}/g, '\n\n');
+  }
+  return out;
+}
+
+// Strip think content from a non-streaming completion message (in place).
+function cleanMessage(message) {
+  if (!message) return;
+  if (typeof message.content === 'string') {
+    message.content = stripThink(message.content, true);
+  }
+  return message;
+}
+
+// Fix reasoning-model responses: some free models (gpt-oss-120b, nemotron)
+// put the answer in `reasoning` and leave `content` empty. If content is
+// empty but reasoning has text, surface reasoning as the answer.
+function fixReasoningMessage(message) {
+  if (!message) return;
+  const content = typeof message.content === 'string' ? message.content.trim() : '';
+  const reasoning = typeof message.reasoning === 'string' ? message.reasoning.trim() : '';
+  if (!content && reasoning) {
+    message.content = stripThink(reasoning, true);
+  }
+  return message;
+}
+
+// Strip think content from a streaming delta (in place).
+// Do NOT trim — streaming chunks must keep their boundary spaces so words
+// don't merge when the client reassembles the stream.
+function cleanDelta(delta) {
+  if (!delta) return;
+  if (typeof delta.content === 'string') {
+    delta.content = stripThink(delta.content, false);
+  }
+  return delta;
+}
+
+module.exports = { stripThink, cleanMessage, cleanDelta, fixReasoningMessage };

package/lib/dashboard.js

@@ -0,0 +1,178 @@
+// lib/dashboard.js
+const HTML = `<!DOCTYPE html>
+<html lang="ru">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Freegate — Панель управления</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', monospace; background: #1a1a2e; color: #e0e0e0; padding: 20px; }
+    h1 { color: #00d4ff; margin-bottom: 20px; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 20px; }
+    .card { background: #16213e; border-radius: 8px; padding: 20px; border: 1px solid #0f3460; }
+    .card h2 { color: #00d4ff; font-size: 14px; margin-bottom: 15px; text-transform: uppercase; }
+    .stat { display: flex; justify-content: space-between; margin-bottom: 8px; }
+    .stat-label { color: #888; }
+    .stat-value { color: #fff; font-weight: bold; }
+    .provider { display: flex; align-items: center; margin-bottom: 10px; }
+    .status-dot { width: 10px; height: 10px; border-radius: 50%; margin-right: 10px; }
+    .status-up { background: #00ff88; }
+    .status-error { background: #ff4444; }
+    .status-unknown { background: #888; }
+    .latency { color: #888; margin-left: auto; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { text-align: left; padding: 8px; border-bottom: 1px solid #0f3460; }
+    th { color: #00d4ff; font-size: 12px; }
+    td { font-size: 12px; }
+    .refresh { color: #888; font-size: 12px; margin-top: 10px; }
+    canvas { width: 100%; height: 120px; background: #0f3460; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <h1>Freegate — Панель управления</h1>
+  <div class="grid">
+    <div class="card"><h2>Провайдеры</h2><div id="providers">Загрузка...</div></div>
+    <div class="card"><h2>Статистика</h2><div id="stats">Загрузка...</div></div>
+    <div class="card"><h2>Кэш</h2><div id="cache">Загрузка...</div></div>
+    <div class="card"><h2>Токены</h2><div id="tokens">Загрузка...</div></div>
+    <div class="card"><h2>Очередь</h2><div id="pool">Загрузка...</div></div>
+    <div class="card" style="grid-column: span 2;"><h2>Лимиты (остаток за сегодня)</h2><div id="limits">Загрузка...</div></div>
+    <div class="card" style="grid-column: span 2;"><h2>График запросов (в минуту)</h2><canvas id="rpmChart"></canvas></div>
+    <div class="card" style="grid-column: span 2;">
+      <h2>Недавние запросы</h2>
+      <table id="recentTable"><tr><th>Время</th><th>Модель</th><th>Провайдер</th><th>Статус</th><th>Задержка</th></tr></table>
+    </div>
+  </div>
+  <div class="refresh">Автообновление: 5 сек</div>
+  <script>
+    // Carry the ?key= param from the dashboard URL to API calls
+    var _key = new URLSearchParams(location.search).get('key') || '';
+    function _api(path) {
+      return _key ? path + (path.includes('?') ? '&' : '?') + 'key=' + encodeURIComponent(_key) : path;
+    }
+    async function refresh() {
+      try {
+        const [statsRes, recentRes, rpmRes] = await Promise.all([
+          fetch(_api('/v1/stats')), fetch(_api('/v1/recent')), fetch(_api('/v1/rpm'))
+        ]);
+        const data = await statsRes.json();
+        const recent = (await recentRes.json()).data;
+        const rpmData = (await rpmRes.json()).data;
+        renderProviders(data.health);
+        renderStats(data);
+        renderCache(data.cache);
+        renderTokens(data.token_usage || {});
+        renderPool(data.pool || {});
+        renderLimits(data.limits || {});
+        renderRpm(rpmData);
+        renderRecent(recent);
+      } catch (e) { console.error('Ошибка обновления:', e); }
+    }
+
+    function renderProviders(health) {
+      let html = '';
+      for (const [key, h] of Object.entries(health)) {
+        const cls = h.status === 'up' ? 'status-up' : h.status === 'error' ? 'status-error' : 'status-unknown';
+        const rel = h.reliability !== null && h.reliability !== undefined ? ' | стаб. ' + h.reliability + '%' : '';
+        html += '<div class="provider"><div class="status-dot ' + cls + '"></div>';
+        html += '<span>' + key + '</span><span class="latency">' + h.latency_ms + 'ms · ' + (h.reason || '—') + rel + '</span></div>';
+      }
+      document.getElementById('providers').innerHTML = html || '<div>Нет провайдеров</div>';
+    }
+
+    function renderStats(data) {
+      document.getElementById('stats').innerHTML =
+        '<div class="stat"><span class="stat-label">Запросов</span><span class="stat-value">' + data.total_requests + '</span></div>' +
+        '<div class="stat"><span class="stat-label">Успешно</span><span class="stat-value">' + data.successful_requests + '</span></div>' +
+        '<div class="stat"><span class="stat-label">Ошибок</span><span class="stat-value">' + data.failed_requests + '</span></div>' +
+        '<div class="stat"><span class="stat-label">Время работы</span><span class="stat-value">' + Math.floor(data.uptime_seconds / 60) + ' мин</span></div>';
+    }
+
+    function renderCache(cache) {
+      if (!cache) return;
+      document.getElementById('cache').innerHTML =
+        '<div class="stat"><span class="stat-label">Хиты</span><span class="stat-value">' + cache.hits + '</span></div>' +
+        '<div class="stat"><span class="stat-label">Промахи</span><span class="stat-value">' + cache.misses + '</span></div>' +
+        '<div class="stat"><span class="stat-label">Размер</span><span class="stat-value">' + cache.size + '/' + cache.maxSize + '</span></div>' +
+        '<div class="stat"><span class="stat-label">Точность</span><span class="stat-value">' + cache.hitRate + '%</span></div>';
+    }
+
+    function renderTokens(tokens) {
+      let html = '';
+      for (const [key, t] of Object.entries(tokens)) {
+        html += '<div class="stat"><span class="stat-label">' + key + '</span><span class="stat-value">' + t.totalTokens + ' ток.</span></div>';
+      }
+      document.getElementById('tokens').innerHTML = html || '<div>Нет данных</div>';
+    }
+
+    function renderPool(pool) {
+      let html = '';
+      let totalQueued = 0;
+      for (const [key, s] of Object.entries(pool)) {
+        totalQueued += s.queued || 0;
+        if (s.queued > 0) {
+          html += '<div class="stat"><span class="stat-label">' + key + '</span><span class="stat-value">активных ' + s.active + ', ждут ' + s.queued + '</span></div>';
+        }
+      }
+      if (!html) html = '<div class="stat"><span class="stat-label">Все провайдеры</span><span class="stat-value">без очереди</span></div>';
+      document.getElementById('pool').innerHTML = html;
+    }
+
+    function renderLimits(limits) {
+      let html = '';
+      const keys = Object.keys(limits).sort((a, b) => (limits[a].percent || 0) - (limits[b].percent || 0));
+      for (const key of keys) {
+        const l = limits[key];
+        const color = l.percent > 90 ? '#ff4444' : l.percent > 60 ? '#ffaa00' : '#00ff88';
+        html += '<div class="stat"><span class="stat-label">' + key + '</span>' +
+          '<span class="stat-value" style="color:' + color + '">' + l.used + '/' + l.limit + ' (ост. ' + l.remaining + ', ' + l.percent + '%)</span></div>';
+      }
+      document.getElementById('limits').innerHTML = html || '<div>Нет данных</div>';
+    }
+
+    function renderRpm(rpmData) {
+      const canvas = document.getElementById('rpmChart');
+      const ctx = canvas.getContext('2d');
+      canvas.width = canvas.offsetWidth;
+      canvas.height = canvas.offsetHeight;
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+      if (!rpmData || rpmData.length === 0) return;
+      const max = Math.max.apply(null, rpmData.map(r => r.count), 1);
+      const w = canvas.width, h = canvas.height;
+      ctx.strokeStyle = '#00d4ff';
+      ctx.lineWidth = 2;
+      ctx.beginPath();
+      rpmData.forEach((r, i) => {
+        const x = w - (rpmData.length - 1 - i) * (w / 60);
+        const y = h - (r.count / max) * (h - 20) - 10;
+        if (i === 0) ctx.moveTo(x, y); else ctx.lineTo(x, y);
+      });
+      ctx.stroke();
+    }
+
+    function renderRecent(recent) {
+      const table = document.getElementById('recentTable');
+      table.innerHTML = '<tr><th>Время</th><th>Модель</th><th>Провайдер</th><th>Статус</th><th>Задержка</th></tr>';
+      recent.forEach(r => {
+        const row = table.insertRow();
+        row.insertCell().textContent = new Date(r.timestamp).toLocaleTimeString('ru-RU');
+        row.insertCell().textContent = r.model || '-';
+        row.insertCell().textContent = r.provider || '-';
+        row.insertCell().textContent = r.status || '-';
+        row.insertCell().textContent = (r.latency || 0) + 'ms';
+      });
+    }
+
+    refresh();
+    setInterval(refresh, 5000);
+  </script>
+</body>
+</html>`;
+
+function handleDashboard(req, res) {
+  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+  res.end(HTML);
+}
+
+module.exports = { handleDashboard };

package/lib/health.js

@@ -0,0 +1,179 @@
+// lib/health.js
+const fs = require('fs');
+const path = require('path');
+const logger = require('./logger');
+
+const STATE_PATH = path.join(__dirname, '..', 'state.json');
+
+let health = {};
+let circuitBreakers = {};
+let stats = { totalRequests: 0, successfulRequests: 0, failedRequests: 0, providerUsage: {}, errors: {}, startTime: Date.now(), tokenUsage: {} };
+
+const MAX_RECENT = 50;
+let recent = [];
+let rpm = [];
+let currentRpmMinute = 0;
+
+function loadState() {
+  try {
+    const data = JSON.parse(fs.readFileSync(STATE_PATH, 'utf8'));
+    health = data.health || {};
+    circuitBreakers = data.circuitBreakers || {};
+    const saved = data.stats || {};
+    stats = {
+      totalRequests: saved.totalRequests || 0,
+      successfulRequests: saved.successfulRequests || 0,
+      failedRequests: saved.failedRequests || 0,
+      providerUsage: saved.providerUsage || {},
+      errors: saved.errors || {},
+      startTime: saved.startTime || Date.now(),
+      tokenUsage: saved.tokenUsage || {},
+      dailyUsage: saved.dailyUsage || {},
+      reliability: saved.reliability || {},
+    };
+    logger.info('State loaded', { healthKeys: Object.keys(health) });
+  } catch {
+    logger.info('No state file, starting fresh');
+  }
+}
+
+function saveState() {
+  try {
+    fs.writeFileSync(STATE_PATH, JSON.stringify({ health, circuitBreakers, stats }, null, 2));
+  } catch (err) {
+    logger.error('Failed to save state', { error: err.message });
+  }
+}
+
+function initHealth(key) {
+  if (!health[key]) {
+    health[key] = { score: 50, latency: 0, lastCheck: 0, status: 'unknown', quota: '--' };
+  }
+}
+
+function isCircuitOpen(key) {
+  const cb = circuitBreakers[key];
+  if (!cb || !cb.openUntil) return false;
+  if (Date.now() > cb.openUntil) {
+    cb.openUntil = null;
+    cb.failures = 0;
+    return false;
+  }
+  return true;
+}
+
+function recordSuccess(key) {
+  circuitBreakers[key] = { failures: 0, lastFailure: 0, openUntil: null };
+  initHealth(key);
+  health[key].status = 'up';
+  health[key].score = Math.min(100, health[key].score + 10);
+}
+
+function recordFailure(key, statusCode) {
+  if (!circuitBreakers[key]) circuitBreakers[key] = { failures: 0, lastFailure: 0, openUntil: null };
+  const cb = circuitBreakers[key];
+  cb.failures++;
+  cb.lastFailure = Date.now();
+  // Classify errors: hard errors open the breaker much longer than soft ones
+  const openMs = classifyErrorMs(statusCode);
+  if (cb.failures >= 3 || openMs > 60000) {
+    cb.openUntil = Date.now() + Math.max(openMs, 60000);
+    cb.failures = 0;
+    cb.reason = statusCode;
+    logger.warn('Circuit breaker opened', { key, statusCode, openMs });
+  }
+}
+
+// How long to hold the breaker open for a given HTTP status.
+// 401/403 = bad key (long), 429 = rate limit (medium), 5xx = overload (short, retry soon)
+function classifyErrorMs(statusCode) {
+  const s = statusCode || 0;
+  if (s === 401 || s === 403) return 300000;      // 5 min — key is dead
+  if (s === 429) return 120000;                    // 2 min — rate limited, wait for reset
+  if (s >= 500) return 30000;                      // 30s — transient overload
+  if (s === 404) return 300000;                    // 5 min — model/endpoint gone
+  return 60000;                                    // default
+}
+
+function recordRequest(providerKey, success, error = null) {
+  recordRpm();
+  stats.totalRequests++;
+  const today = new Date().toISOString().slice(0, 10);
+  if (success) {
+    stats.successfulRequests++;
+    stats.providerUsage[providerKey] = (stats.providerUsage[providerKey] || 0) + 1;
+    // Daily counter for limit tracking (resets each UTC day)
+    stats.dailyUsage = stats.dailyUsage || {};
+    stats.dailyUsage[providerKey] = stats.dailyUsage[providerKey] || {};
+    stats.dailyUsage[providerKey][today] = (stats.dailyUsage[providerKey][today] || 0) + 1;
+    // Reliability: count today's successes per provider
+    stats.reliability = stats.reliability || {};
+    stats.reliability[providerKey] = stats.reliability[providerKey] || { success: 0, fail: 0, day: '' };
+    const r = stats.reliability[providerKey];
+    if (r.day !== today) { r.day = today; r.success = 0; r.fail = 0; }
+    r.success++;
+  } else {
+    stats.failedRequests++;
+    if (error) stats.errors[providerKey] = (stats.errors[providerKey] || 0) + 1;
+    // Reliability: count today's failures
+    stats.reliability = stats.reliability || {};
+    stats.reliability[providerKey] = stats.reliability[providerKey] || { success: 0, fail: 0, day: '' };
+    const r = stats.reliability[providerKey];
+    if (r.day !== today) { r.day = today; r.success = 0; r.fail = 0; }
+    r.fail++;
+  }
+}
+
+// Reliability ratio (0..1) for today. Providers with 100% success get a boost at startup.
+function getReliability() {
+  return stats.reliability || {};
+}
+
+function recordTokens(providerKey, usage) {
+  if (!usage) return;
+  const tu = stats.tokenUsage[providerKey] || { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+  tu.promptTokens += usage.prompt_tokens || 0;
+  tu.completionTokens += usage.completion_tokens || 0;
+  tu.totalTokens += usage.total_tokens || (usage.prompt_tokens || 0) + (usage.completion_tokens || 0);
+  stats.tokenUsage[providerKey] = tu;
+}
+
+function getHealth() { return health; }
+function getStats() { return stats; }
+
+function recordRecent(entry) {
+  recent.unshift({ timestamp: Date.now(), ...entry });
+  if (recent.length > MAX_RECENT) recent.pop();
+}
+
+function recordRpm() {
+  const now = Date.now();
+  const minute = Math.floor(now / 60000);
+  if (minute !== currentRpmMinute) {
+    currentRpmMinute = minute;
+    rpm.unshift({ timestamp: now, count: 1 });
+    if (rpm.length > 60) rpm.pop();
+  } else if (rpm.length > 0) {
+    rpm[0].count++;
+  } else {
+    rpm.unshift({ timestamp: now, count: 1 });
+  }
+}
+
+function getRecent() { return recent; }
+function getRpm() { return rpm; }
+function getDailyUsage() { return stats.dailyUsage || {}; }
+
+// Auto-save every 30 seconds
+const _saveTimer = setInterval(saveState, 30000);
+
+function _stopTimers() { clearInterval(_saveTimer); }
+
+module.exports = {
+  loadState, saveState, initHealth, isCircuitOpen,
+  recordSuccess, recordFailure, recordRequest, recordTokens,
+  getHealth, getStats,
+  recordRecent, recordRpm, getRecent, getRpm,
+  getDailyUsage, getReliability,
+  _stopTimers,
+};

package/lib/logger.js

@@ -0,0 +1,48 @@
+// lib/logger.js
+const fs = require('fs');
+const path = require('path');
+
+const LOG_PATH = path.join(__dirname, '..', 'proxy.log');
+const MAX_LOG_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_ROTATIONS = 3;
+
+function rotateLog() {
+  try {
+    const stat = fs.statSync(LOG_PATH);
+    if (stat.size < MAX_LOG_SIZE) return;
+
+    // Rotate: delete .3, shift .2 -> .3, .1 -> .2, proxy.log -> .1
+    try { if (fs.existsSync(`${LOG_PATH}.${MAX_ROTATIONS}`)) fs.unlinkSync(`${LOG_PATH}.${MAX_ROTATIONS}`); } catch {}
+    if (fs.existsSync(`${LOG_PATH}.2`)) fs.renameSync(`${LOG_PATH}.2`, `${LOG_PATH}.3`);
+    if (fs.existsSync(`${LOG_PATH}.1`)) fs.renameSync(`${LOG_PATH}.1`, `${LOG_PATH}.2`);
+    if (fs.existsSync(LOG_PATH)) fs.renameSync(LOG_PATH, `${LOG_PATH}.1`);
+  } catch (err) {
+    console.error(`[logger] rotation failed: ${err.message}`);
+  }
+}
+
+function formatTime() {
+  return new Date().toISOString();
+}
+
+function writeLog(level, message, data) {
+  const line = `[${formatTime()}] [${level}] ${message} ${data ? JSON.stringify(data) : ''}\n`;
+  process.stdout.write(line);
+  try {
+    rotateLog();
+    fs.appendFileSync(LOG_PATH, line);
+  } catch (err) {
+    console.error(`[logger] write failed: ${err.message}`);
+  }
+}
+
+module.exports = {
+  info: (msg, data) => writeLog('INFO', msg, data),
+  error: (msg, data) => writeLog('ERROR', msg, data),
+  warn: (msg, data) => writeLog('WARN', msg, data),
+  request: (data) => writeLog('REQ', `${data.model || '?'} ${data.provider || '?'} ${data.status || '?'}`, {
+    latency: data.latency,
+    stream: data.stream,
+    cached: data.cached,
+  }),
+};

package/lib/pool.js

@@ -0,0 +1,41 @@
+// lib/pool.js — per-provider concurrency limiting.
+// Ensures at most N requests hit a provider simultaneously, so burst traffic
+// can't burn daily limits in seconds or trip provider rate limits (429).
+// Requests beyond the limit wait in a FIFO queue until a slot frees up.
+
+const DEFAULT_CONCURRENCY = 6;
+
+const slots = {};   // providerKey -> { active, queue: [] }
+
+function acquire(key, max = DEFAULT_CONCURRENCY) {
+  if (!slots[key]) slots[key] = { active: 0, queue: [] };
+  const s = slots[key];
+  if (s.active < max) {
+    s.active++;
+    return Promise.resolve(() => release(key));
+  }
+  return new Promise((resolve) => {
+    s.queue.push(resolve);
+  }).then(() => {
+    s.active++;
+    return () => release(key);
+  });
+}
+
+function release(key) {
+  const s = slots[key];
+  if (!s) return;
+  s.active = Math.max(0, s.active - 1);
+  const next = s.queue.shift();
+  if (next) next();
+}
+
+function stats() {
+  const out = {};
+  for (const [key, s] of Object.entries(slots)) {
+    out[key] = { active: s.active, queued: s.queue.length };
+  }
+  return out;
+}
+
+module.exports = { acquire, release, stats };