@nitra/cursor 12.15.1 → 12.16.1

package/lib/docs/omlx-trace.md

@@ -1,49 +0,0 @@
----
-type: JS Module
-title: omlx-trace.mjs
-resource: npm/lib/omlx-trace.mjs
-docgen:
-  crc: 3ff568d5
-  score: 100
----
-
-Модуль збирає трасу викликів LLM, фіксуючи думки моделі та спостережуваний слід. Траса записується у локальний файл для ротації та готується для подальшої батч-агрегації. Дизайн-специфікація: docs/specs/2026-06-10-omlx-wire-trace-capture-design.md.
-
-## Поведінка
-
-MAX_MSG_CHARS
-Ліміт символів на одне message.content у записі
-
-ROTATE_BYTES
-Поріг недеструктивної ротації активного файлу в байтах
-
-tracePath
-Повертає шлях до trace-файлу або null
-
-capMessages
-Обрізає message.content та рахує sha256 повного масиву
-
-buildTraceRecord
-Будує нормалізований trace-запис
-
-rotateIfNeeded
-Недеструктивно ротує файл при перевищенні ROTATE_BYTES
-
-writeTrace
-Записує trace-запис у файл з ротацією та fail-safe
-
-## Публічний API
-
-MAX_MSG_CHARS — встановлює максимальну кількість символів для вмісту повідомлення.
-ROTATE_BYTES — визначає поріг для ініціювання ротації файлу.
-tracePath — зберігає шлях до файлу трасування або порожній рядок, якщо трасування вимкнено.
-N_CURSOR_LLM_TRACE — визначає пріоритет для вибору шляху трасування: спочатку перевіряється вимкнений перемикач, потім використовується явний шлях.
-buildTraceRecord — створює запис трасування, залишаючи порожні значення для полів, які недоступні.
-rotateIfNeeded — перейменовує файл при перевищенні ліміту, створюючи новий файл з послідовним індексом.
-writeTrace — записує один запис трасування, обробляючи шляхи, ротуючи дані за необхідності та обробляючи помилки вводу/виводу.
-
-## Гарантії поведінки
-
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.

package/lib/docs/omlx.md

@@ -1,41 +0,0 @@
----
-type: JS Module
-title: omlx.mjs
-resource: npm/lib/omlx.mjs
-docgen:
-  crc: 23163fe9
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
----
-
-Модуль реалізує логіку маршрутизації запитів до локального omlx-сервера, який надає OpenAI-сумісні відповіді за адресою `http://localhost:8000/v1/chat/completions`. Константа DEFAULT_OMLX_URL визначає цю базову адресу. Модуль визначає, чи є модель локальною, аналізуючи префікс у `model-id` (`omlx/<model>`). Якщо модель локальна, виконується прямий HTTP-запит до omlx. Якщо ж модель не локальна, запит спрямовується до pi CLI. При необхідності, API-ключ для omlx резолвиться з конфігураційного файлу settings.json або змінної N_CURSOR_OMLX_KEY і передається у заголовку `Authorization: Bearer …`. Обробка обмежується лише текстовим контентом, оскільки сервер не підтримує виклики інструментів.
-
-## Поведінка
-
-DEFAULT_OMLX_URL надає стандартний URL для доступу до omlx-сервера, який є `http://127.0.0.1:8000/v1/chat/completions`.
-resolveOmlxApiKey визначає API-ключ для omlx-сервера, шукаючи його в опціях виклику, змінній середовища `N_CURSOR_OMLX_KEY` або в файлі `~/.omlx/settings.json`.
-isOmlxModel перевіряє, чи відповідає наданий model-id локальному omlx-бекенду, тобто чи починається він з префікса `omlx/`.
-omlxModelId видаляє префікс `omlx/` з model-id, якщо він присутній, для отримання чистого ідентифікатора для omlx API.
-extractReasoning витягує текст думок (reasoning) з відповіді omlx-сервера, надаючи його разом із джерелом вилучення (поле, тег ``або зрізаний контент).
-callOmlxRaw виконує блокуючий HTTP-виклик до omlx-сервера через`curl`, повторюючи спроби при транзієнтних помилках, і повертає багатий об'єкт з контентом, думками, використанням та статусом завершення.
-callOmlx викликає `callOmlxRaw` і повертає лише текстовий контент відповіді від omlx-сервера.
-
-## Публічний API
-
-DEFAULT_OMLX_URL — Дефолтний URL для звернення до omlx-сервера, який може бути перевизначений.
-
-resolveOmlxApiKey — Визначає ключ доступу до omlx-сервера, використовуючи пріоритет: явний ключ, змінна середовища, конфігурація з `settings.json` або відсутність ключа.
-
-isOmlxModel — Визначає, чи ідентифікатор моделі вказує на локальний omlx-бекенд (за наявністю префікса `omlx/`).
-
-omlxModelId — Видаляє префікс `omlx/` з ідентифікатора моделі, залишаючи чистий ідентифікатор для API.
-
-extractReasoning — Витягує внутрішні роздуми моделі з відповіді omlx, шукаючи їх у спеціальному полі, тегу `` або в тексті, якщо відповідь була обрізана.
-
-callOmlxRaw — Здійснює прямий HTTP-запит до omlx, повертаючи повний об'єкт відповіді (включаючи контент, роздуми, використання та причину завершення). Автоматично повторює запит при тимчасових збоях.
-
-callOmlx — Спрощує виклик до omlx, повертаючи лише текстовий вміст відповіді, ігноруючи інші деталі.
-
-## Гарантії поведінки
-
-- Read-only: не виконує операцій запису (ФС/БД).

package/lib/llm.mjs

@@ -1,215 +0,0 @@
-/**
- * Єдина точка LLM-викликів для JS-оркестраторів (див. ADR 260610-2228).
- *
- * Маршрутизація — виключно за префіксом model-id (конвенція `npm/lib/models.mjs`):
- *   `omlx/<model>` → прямий HTTP до локального omlx-сервера (`callOmlx`)
- *   будь-що інше   → `pi` CLI (хмарні провайдери або pi-дефолт)
- *
- * Жодних env-перемикачів бекенда: рядок моделі сам визначає транспорт.
- *
- * Wire-trace (спека 2026-06-10-omlx-wire-trace-capture-design): **always-on**
- * багатий JSONL-запис на кожен виклик — обидва канали (reasoning + слід). Для
- * omlx захоплює content/reasoning/usage/finish_reason/attempts; для pi — лише
- * те, що CLI дає (rich-поля null). Деталі запису/шляху/ротації — `omlx-trace.mjs`.
- */
-import { spawnSync } from 'node:child_process'
-import { env } from 'node:process'
-
-import { callOmlxRaw, isOmlxModel } from './omlx.mjs'
-import { buildTraceRecord, writeTrace } from './omlx-trace.mjs'
-
-/** Дефолтний timeout одного виклику (узгоджено з LOCAL_TIMEOUT доки-конвеєра). */
-const DEFAULT_TIMEOUT_MS = 120_000
-
-/**
- * Бекенд для model-id: `omlx` — прямий HTTP, `pi` — CLI.
- * @param {string} model model-id (можливо порожній — pi-дефолт)
- * @returns {'omlx'|'pi'} назва бекенда
- */
-export function pickBackend(model) {
-  return isOmlxModel(model) ? 'omlx' : 'pi'
-}
-
-/**
- * Виклик через `pi` CLI: messages конкатенуються у plain prompt
- * (pi не приймає messages-масив), tools вимкнено.
- * @param {Array<{role:string, content:string}>} messages OpenAI-style messages
- * @param {string} model model-id для `--model` (порожній — pi-дефолт)
- * @param {number} timeoutMs ліміт очікування процесу
- * @returns {string} stdout відповіді
- */
-function callPi(messages, model, timeoutMs) {
-  const prompt = messages.map(m => m.content).join('\n\n')
-  const modelArgs = model ? ['--model', model] : []
-  const r = spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session', '--mode', 'text', '--no-tools'], {
-    encoding: 'utf8',
-    timeout: timeoutMs
-  })
-  if (r.error) throw new Error(`pi error: ${r.error.message}`)
-  if (r.status !== 0) throw new Error(`pi exit ${r.status}: ${r.stderr?.slice(0, 300) ?? ''}`)
-  return r.stdout?.trim() ?? ''
-}
-
-/**
- * Універсальний LLM-виклик з маршрутизацією за префіксом model-id і always-on
- * wire-trace (обидва канали). Повертає **багатий** обʼєкт із вмістом і reasoning.
- * @param {Array<{role:string, content:string}>} messages OpenAI-style messages (system зберігається на omlx)
- * @param {string} model model-id; `omlx/<m>` → прямий HTTP, інакше → pi CLI
- * @param {{ timeoutMs?: number, temperature?: number, maxTokens?: number, url?: string, caller?: string, thinkingBudget?: number }} [opts] timeout, температура, ліміт виходу, override URL, мітка викликача для trace, бюджет thinking-токенів (лише omlx)
- * @returns {{ content: string, reasoning: string|null, reasoningSource: string|null }} вміст відповіді і thinking-монолог
- */
-export function callLlmRich(messages, model, opts = {}) {
-  const { timeoutMs = DEFAULT_TIMEOUT_MS, temperature = 0.2, maxTokens, url, caller, thinkingBudget } = opts
-  const backend = pickBackend(model)
-  const resolvedCaller = caller ?? env.N_CURSOR_TRACE_CALLER ?? 'unknown'
-  const t0 = Date.now()
-  try {
-    let content
-    let reasoning = null
-    let reasoningSource = null
-    let finishReason = null
-    let usage = null
-    let attempts = 1
-    if (backend === 'omlx') {
-      const raw = callOmlxRaw(messages, model, {
-        url,
-        timeoutMs,
-        temperature,
-        ...(maxTokens ? { maxTokens } : {}),
-        ...(thinkingBudget ? { thinkingBudget } : {})
-      })
-      ;({ content, reasoning, reasoningSource, finishReason, usage, attempts } = raw)
-    } else {
-      content = callPi(messages, model, timeoutMs)
-    }
-    writeTrace(
-      buildTraceRecord({
-        ts: new Date().toISOString(),
-        caller: resolvedCaller,
-        backend,
-        model,
-        temperature,
-        maxTokens,
-        messages,
-        content,
-        reasoning,
-        reasoningSource,
-        finishReason,
-        usage,
-        ms: Date.now() - t0,
-        attempts,
-        ok: true,
-        error: null
-      })
-    )
-    return { content, reasoning, reasoningSource }
-  } catch (error) {
-    writeTrace(
-      buildTraceRecord({
-        ts: new Date().toISOString(),
-        caller: resolvedCaller,
-        backend,
-        model,
-        temperature,
-        maxTokens,
-        messages,
-        ms: Date.now() - t0,
-        attempts: null,
-        ok: false,
-        error: String(error.message).slice(0, 200)
-      })
-    )
-    throw error
-  }
-}
-
-/**
- * Тонка обгортка над `callLlmRich` — повертає лише рядок контенту. Зберігає
- * backward-compatible контракт для споживачів, яким reasoning не потрібен.
- * @param {Array<{role:string, content:string}>} messages OpenAI-style messages
- * @param {string} model model-id
- * @param {{ timeoutMs?: number, temperature?: number, maxTokens?: number, url?: string, caller?: string }} [opts]
- * @returns {string} текст відповіді
- */
-export function callLlm(messages, model, opts = {}) {
-  return callLlmRich(messages, model, opts).content
-}
-
-/** Фрагмент повідомлення omlx про memory-guard (динамічна стеля пам'яті). */
-const MEMORY_GUARD_MARKER = 'memory ceiling'
-/** Тип помилки omlx про відсутній/хибний API-ключ. */
-const AUTH_ERROR_MARKER = 'authentication_error'
-/** Детерміновані помилки: контекст/модель — ретрай чи чекання не допоможе. */
-const PERMANENT_RE = /too long|exceeds[^.]*context|not found/i
-
-/**
- * Класифікує omlx-помилку **після** того, як `callOmlxRaw` вичерпав внутрішні
- * ретраї — для реакції оркестратора (skip vs circuit-breaker vs звичайна помилка):
- *   - `permanent` — детерміновано (контекст завеликий, модель відсутня): skip, не ретраїти;
- *   - `systemic`  — середовище/сервер (memory-guard, auth, down/таймаут): каскадить → circuit-breaker;
- *   - `transient` — решта (empty content, bad json): рідкісне, не каскадить.
- * @param {string} message текст `error.message`
- * @returns {'transient'|'systemic'|'permanent'} клас помилки
- */
-export function classifyOmlxError(message) {
-  const m = String(message)
-  if (PERMANENT_RE.test(m)) return 'permanent'
-  if (m.includes(MEMORY_GUARD_MARKER) || m.includes(AUTH_ERROR_MARKER) || m.startsWith('omlx curl')) {
-    return 'systemic'
-  }
-  return 'transient'
-}
-
-/**
- * Preflight-перевірка omlx перед масовим прогоном: мінімальний chat-виклик
- * (`max_tokens: 1`). Розрізняє стани, які вимагають різних дій:
- *   - `down`         — сервер не відповідає (не запущений / не той порт);
- *   - `memory-guard` — модель не влазить у динамічну стелю пам'яті зайнятої
- *                      машини → «відклади прогін», а не «модель погана»;
- *   - `auth`         — сервер вимагає API-ключ → вистав `N_CURSOR_OMLX_KEY`;
- *   - `error`        — інша помилка API.
- * Порожній контент відповіді — це ok: сервер живий і модель завантажена.
- * @param {{ url?: string, model?: string, timeoutMs?: number }} [opts] override URL/моделі/timeout перевірки
- * @returns {{ ok: boolean, reason: 'down'|'memory-guard'|'auth'|'error'|null, detail: string }} стан сервера і класифікована причина збою
- */
-export function omlxHealthCheck(opts = {}) {
-  const { url, model = '', timeoutMs = DEFAULT_TIMEOUT_MS } = opts
-  try {
-    callOmlxRaw([{ role: 'user', content: 'ok' }], model, { url, timeoutMs, maxTokens: 1, temperature: 0 })
-    return { ok: true, reason: null, detail: '' }
-  } catch (error) {
-    const detail = String(error.message)
-    if (detail.includes(MEMORY_GUARD_MARKER)) return { ok: false, reason: 'memory-guard', detail }
-    if (detail.includes(AUTH_ERROR_MARKER)) return { ok: false, reason: 'auth', detail }
-    if (detail.startsWith('omlx empty content')) return { ok: true, reason: null, detail }
-    if (detail.startsWith('omlx curl')) return { ok: false, reason: 'down', detail }
-    return { ok: false, reason: 'error', detail }
-  }
-}
-
-/**
- * Спільний preflight локальної fix/gen-моделі (opportunistic LLM-fix tier, спека
- * docs/specs/2026-06-15-opportunistic-llm-fix-tier.md): чи можна звати модель зараз.
- * Health-check лише для omlx-бекенду (pi/cloud — завжди дозволено). Використовують
- * doc-files (генерація) і text/cspell (класифікація) — fast-skip замість приречених викликів.
- * @param {string} model model-id (зазвичай `N_LOCAL_MIN_MODEL`)
- * @returns {string|null} людинозрозумілий текст проблеми, або null якщо можна викликати
- */
-export function preflightLocalModel(model) {
-  if (!model) {
-    return 'модель не задано. Вистав N_LOCAL_MIN_MODEL (напр. omlx/mlx-community--gemma-4-e4b-it-OptiQ-4bit) і повтори.'
-  }
-  if (pickBackend(model) !== 'omlx') return null
-  const hc = omlxHealthCheck({ model })
-  if (hc.ok) return null
-  if (hc.reason === 'memory-guard') {
-    return `omlx memory-guard: модель не влазить у динамічну стелю пам'яті (машина зайнята).\n  Звільни пам'ять або повтори прогін пізніше.\n  ${hc.detail}`
-  }
-  if (hc.reason === 'down') {
-    return `omlx-сервер не відповідає. Запусти \`omlx serve\` і повтори.\n  ${hc.detail}`
-  }
-  if (hc.reason === 'auth') {
-    return `omlx вимагає API-ключ. Вистав N_CURSOR_OMLX_KEY (auth.api_key з ~/.omlx/settings.json).\n  ${hc.detail}`
-  }
-  return `omlx помилка: ${hc.detail}`
-}

package/lib/models.mjs

@@ -1,75 +0,0 @@
-/**
- * Глобальна класифікація моделей для pi.
- *
- * Формат значень: "provider/model-id" (pi --model формат).
- * Налаштовується один раз у середовищі; кожен скіл посилається на потрібний тир.
- *
- * Приклад ~/.bashrc або .env:
- *   N_LOCAL_MIN_MODEL=omlx/mlx-community--gemma-4-e2b-it-4bit
- *   N_CLOUD_MIN_MODEL=openai/gpt-5.4-mini
- *   N_CLOUD_AVG_MODEL=openai/gpt-5.4
- *   N_CLOUD_MAX_MODEL=openai/gpt-5.5
- *
- * Значення '' означає "pi дефолтний провайдер" (залежить від ~/.pi конфігу).
- *
- * ## Бекенд за префіксом model-id
- *
- * model-id з префіксом `omlx/...` іде прямим HTTP до локального
- * omlx-сервера (`npm/lib/omlx.mjs`), минаючи pi; решта (`openai/...`,
- * `ollama/...`, '') — через pi CLI. Тому локальні тири варто задавати у форматі
- * `omlx/<model>`, аби local-inference йшов напряму, а pi лишався шаром для хмари
- * (див. ADR 260610-1349).
- *
- * ## Каскад local → cloud (контракт)
- *
- * Використовуйте resolveModel(tier) замість прямих констант — система прозоро
- * відпрацює навіть без локальних моделей:
- *
- *   resolveModel('min') → LOCAL_MIN → LOCAL_AVG → LOCAL_MAX → CLOUD_MIN
- *   resolveModel('avg') → LOCAL_AVG → LOCAL_MAX → CLOUD_AVG
- *   resolveModel('max') → LOCAL_MAX → CLOUD_MAX
- *
- * Якщо жоден тир не задано — повертає '' (pi-дефолт провайдера).
- * Прямі константи (LOCAL_MIN тощо) залишені для випадків, де потрібен
- * явний контроль (напр., ollama HTTP, explicit retry до хмари).
- */
-
-import { env } from 'node:process'
-
-// ── Локальні (offline, без API-ключа) ────────────────────────────────────────
-
-/** Швидкий локальний inference. Напр.: ollama/gemma3:4b */
-export const LOCAL_MIN = env.N_LOCAL_MIN_MODEL ?? ''
-
-/** Середній локальний. Напр.: ollama/gemma4:26b-moe */
-export const LOCAL_AVG = env.N_LOCAL_AVG_MODEL ?? ''
-
-/** Максимальний локальний. Напр.: ollama/llama4-maverick */
-export const LOCAL_MAX = env.N_LOCAL_MAX_MODEL ?? ''
-
-// ── Хмарні (потрібен API-ключ у pi) ─────────────────────────────────────────
-
-/** Мінімальний хмарний. Напр.: openai/gpt-5.4-mini, google/gemini-2.5-flash, anthropic/claude-haiku-4-5 */
-export const CLOUD_MIN = env.N_CLOUD_MIN_MODEL ?? ''
-
-/** Середній хмарний. Напр.: openai/gpt-5.4, google/gemini-2.5-pro, anthropic/claude-sonnet-4-6 */
-export const CLOUD_AVG = env.N_CLOUD_AVG_MODEL ?? ''
-
-/** Максимальний хмарний. Напр.: openai/gpt-5.5, anthropic/claude-opus-4-8 */
-export const CLOUD_MAX = env.N_CLOUD_MAX_MODEL ?? ''
-
-// ── Каскадне розв'язання ─────────────────────────────────────────────────────
-
-/**
- * Повертає перший непорожній model-id для запитаного тиру,
- * каскадно перевіряючи локальні тири, а тоді хмарний еквівалент.
- * @param {'min'|'avg'|'max'} tier тир запитуваної моделі
- * @returns {string} provider/model-id або '' для pi-дефолту
- * @throws {TypeError} якщо tier невідомий
- */
-export function resolveModel(tier) {
-  if (tier === 'min') return LOCAL_MIN || LOCAL_AVG || LOCAL_MAX || CLOUD_MIN
-  if (tier === 'avg') return LOCAL_AVG || LOCAL_MAX || CLOUD_AVG
-  if (tier === 'max') return LOCAL_MAX || CLOUD_MAX
-  throw new TypeError(`resolveModel: unknown tier "${tier}". Use 'min', 'avg', or 'max'.`)
-}

package/lib/omlx-trace.mjs

@@ -1,158 +0,0 @@
-/**
- * Wire-trace LLM-викликів: будує й пише багатий JSONL-запис на кожен виклик
- * `callLlm` (див. `npm/lib/llm.mjs`). Захоплює **обидва канали** — reasoning
- * (думки моделі) і спостережуваний слід (request/response/usage/latency/retry).
- *
- * Дизайн-спека: `docs/specs/2026-06-10-omlx-wire-trace-capture-design.md`.
- *
- * Двошарова модель:
- *   - RAW (цей модуль) → `<cwd>/.n-cursor/llm-trace.jsonl` (gitignored, локальний,
- *     недеструктивна ротація) — сирий потік, доживає до батч-агрегації.
- *   - AGGREGATE (друга спека) → `docs/omlx-insights/` (коммітиться в git, назавжди).
- *
- * Always-on: пишеться завжди. `N_CURSOR_LLM_TRACE=0|false|off|no` — kill-switch;
- * будь-яке інше значення — override-шлях замість дефолтного.
- */
-import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from 'node:fs'
-import { createHash } from 'node:crypto'
-import { dirname, join } from 'node:path'
-import { cwd, env } from 'node:process'
-
-/** Ліміт символів на одне `message.content` у записі (захист обсягу/чутливості). */
-export const MAX_MSG_CHARS = 8000
-
-/** Поріг недеструктивної ротації активного файлу (байти). */
-export const ROTATE_BYTES = 50 * 1024 * 1024
-
-/** Значення `N_CURSOR_LLM_TRACE`, що вимикають трасування повністю. */
-const KILL_VALUES = new Set(['0', 'false', 'off', 'no'])
-
-/**
- * Шлях активного trace-файлу або `null`, якщо трасування вимкнено kill-switch-ем.
- * Пріоритет: `N_CURSOR_LLM_TRACE` (kill-switch → null; інакше явний шлях) →
- * дефолт `<cwd>/.n-cursor/llm-trace.jsonl` (корінь споживацького проєкту).
- * @returns {string|null} абсолютний/відносний шлях до .jsonl або null
- */
-export function tracePath() {
-  const override = env.N_CURSOR_LLM_TRACE
-  if (override !== undefined) {
-    if (KILL_VALUES.has(override.toLowerCase())) return null
-    if (override) return override
-  }
-  return join(cwd(), '.n-cursor', 'llm-trace.jsonl')
-}
-
-/**
- * Обрізає кожне `message.content` до `MAX_MSG_CHARS` і рахує sha256 повного
- * (необрізаного) масиву для дедуплікації.
- * @param {Array<{role:string, content:string}>} messages вихідні messages
- * @returns {{ messages: Array<{role:string, content:string}>, messages_sha256: string, messages_truncated: boolean }} обрізані messages, hash і прапор обрізки
- */
-export function capMessages(messages) {
-  const src = messages ?? []
-  let truncated = false
-  const capped = src.map(m => {
-    const content = m?.content ?? ''
-    if (content.length > MAX_MSG_CHARS) {
-      truncated = true
-      return { role: m.role, content: content.slice(0, MAX_MSG_CHARS) }
-    }
-    return { role: m?.role, content }
-  })
-  const messages_sha256 = createHash('sha256').update(JSON.stringify(src)).digest('hex')
-  return { messages: capped, messages_sha256, messages_truncated: truncated }
-}
-
-/**
- * Будує нормалізований trace-запис. Поля, яких backend не дає (pi: reasoning/
- * usage/finish_reason), лишаються `null` за побудовою.
- * @param {object} i вхід
- * @param {string} i.ts ISO-час завершення виклику
- * @param {string} i.caller хто викликав (doc-files|fix|coverage|unknown)
- * @param {'omlx'|'pi'} i.backend бекенд
- * @param {string} i.model model-id
- * @param {number} [i.temperature] температура
- * @param {number} [i.maxTokens] ліміт виходу
- * @param {Array<{role:string, content:string}>} i.messages messages запиту
- * @param {string|null} [i.content] відповідь
- * @param {string|null} [i.reasoning] думки моделі
- * @param {string|null} [i.reasoningSource] джерело reasoning
- * @param {string|null} [i.finishReason] finish_reason
- * @param {object|null} [i.usage] usage verbatim
- * @param {number} i.ms latency
- * @param {number|null} [i.attempts] кількість спроб
- * @param {boolean} i.ok успіх
- * @param {string|null} [i.error] текст помилки
- * @returns {object} JSONL-готовий запис
- */
-export function buildTraceRecord(i) {
-  const capped = capMessages(i.messages)
-  return {
-    ts: i.ts,
-    caller: i.caller,
-    backend: i.backend,
-    model: i.model,
-    temperature: i.temperature ?? null,
-    max_tokens: i.maxTokens ?? null,
-    messages: capped.messages,
-    messages_sha256: capped.messages_sha256,
-    messages_truncated: capped.messages_truncated,
-    content: i.content ?? null,
-    reasoning: i.reasoning ?? null,
-    reasoning_source: i.reasoningSource ?? null,
-    finish_reason: i.finishReason ?? null,
-    usage: i.usage ?? null,
-    ms: i.ms,
-    attempts: i.attempts ?? null,
-    ok: i.ok,
-    error: i.error ?? null
-  }
-}
-
-/**
- * Імʼя архіву для ротації: `llm-trace.jsonl` → `llm-trace.<seq>.jsonl`
- * (нестандартні імена без `.jsonl` → `<file>.<seq>`).
- * @param {string} file активний trace-файл
- * @param {number} seq порядковий номер архіву
- * @returns {string} шлях архіву
- */
-function archiveName(file, seq) {
-  return file.endsWith('.jsonl') ? `${file.slice(0, -'.jsonl'.length)}.${seq}.jsonl` : `${file}.${seq}`
-}
-
-/**
- * Недеструктивна ротація: якщо активний файл перевищує `ROTATE_BYTES`,
- * перейменовує його в перший вільний `llm-trace.<seq>.jsonl` (без перезапису
- * наявних архівів). Відсутній файл / помилка stat — no-op.
- * @param {string} file активний trace-файл
- */
-export function rotateIfNeeded(file) {
-  let size
-  try {
-    size = statSync(file).size
-  } catch {
-    return // файлу ще нема — нічого ротувати
-  }
-  if (size <= ROTATE_BYTES) return
-  let seq = 1
-  while (existsSync(archiveName(file, seq))) seq++
-  renameSync(file, archiveName(file, seq))
-}
-
-/**
- * Fail-safe запис одного trace-рядка. Резолвить шлях (kill-switch → no-op),
- * ротує за потреби, створює теку, append-ить JSONL. Будь-яка помилка IO
- * ковтається — трасування **ніколи** не ламає основний виклик.
- * @param {object} record запис від `buildTraceRecord`
- */
-export function writeTrace(record) {
-  const file = tracePath()
-  if (!file) return
-  try {
-    rotateIfNeeded(file)
-    mkdirSync(dirname(file), { recursive: true })
-    appendFileSync(file, JSON.stringify(record) + '\n')
-  } catch {
-    // трейс не має ламати основний виклик
-  }
-}